updates.

[silc.git] / lib / silccore / silcauth.h

diff --git a/lib/silccore/silcauth.h b/lib/silccore/silcauth.h
index 84d6789c461ca6b3ab14a59ab41dd5bc61e1b1b4..f66621324107bbc403b2c85a45f4b05b270b920c 100644 (file)
--- a/lib/silccore/silcauth.h
+++ b/lib/silccore/silcauth.h
@@ -18,7 +18,7 @@
 
 */
 
-/****h* silccore/SilcAuthAPI
+/****h* silccore/SILC Authentication Interface
  *
  * DESCRIPTION
  *
@@ -129,7 +129,10 @@ SilcAuthPayload silc_auth_payload_parse(const unsigned char *data,
  *
  *    Encodes authentication payload into buffer and returns it.
  *    The `random_data' is provided only if doing public key authentication.
- *    The `auth_data' is the actual authentication data.
+ *    The `auth_data' is the actual authentication data.  If the
+ *    `method' is SILC_AUTH_PASSWORD the passphase in `auth_data' sent as
+ *    argument SHOULD be UTF-8 encoded, if not library will attempt to
+ *    encode it.
  *
  ***/
 SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
@@ -173,7 +176,9 @@ SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
  *
  * DESCRIPTION
  *
- *    Get the authentication data. The caller must not free the data.
+ *    Get the authentication data. The caller must not free the data.  If
+ *    the authentication method is passphrase, then the returned string
+ *    is UTF-8 encoded passphrase.
  *
  ***/
 unsigned char *silc_auth_get_data(SilcAuthPayload payload,
@@ -185,6 +190,7 @@ unsigned char *silc_auth_get_data(SilcAuthPayload payload,
  *
  *    SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
  *                                                  SilcPrivateKey private_key,
+ *                                                  SilcRng rng,
  *                                                  SilcHash hash,
  *                                                  const void *id, 
  *                                                  SilcIdType type);
@@ -196,10 +202,16 @@ unsigned char *silc_auth_get_data(SilcAuthPayload payload,
  *    and the actual authentication data. Returns NULL on error and the
  *    encoded Authentication Payload on success.
  *
+ *    The `private_key' is used to sign the payload.  The `public_key', the
+ *    and the `id' is encoded in the payload and signed.  If the `rng' is
+ *    NULL then global RNG is used, if non-NULL then `rng' is used as
+ *    random number generator.  Also random number is encoded in the
+ *    payload before signing it with `private_key'.
+ *
  ***/
 SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
                                              SilcPrivateKey private_key,
-                                             SilcHash hash,
+                                             SilcRng rng, SilcHash hash,
                                              const void *id, SilcIdType type);
 
 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify
@@ -259,9 +271,9 @@ bool silc_auth_public_key_auth_verify_data(const unsigned char *payload,
  *    Verifies the authentication data directly from the Authentication 
  *    Payload. Supports all authentication methods. If the authentication
  *    method is passphrase based then the `auth_data' and `auth_data_len'
- *    are the passphrase and its length. If the method is public key
- *    authentication then the `auth_data' is the SilcPublicKey and the
- *    `auth_data_len' is ignored.
+ *    are the passphrase and its length.  The passphrase MUST be UTF-8
+ *    encoded.  If the method is public key authentication then the
+ *    `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
  *
  ***/
 bool silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
@@ -285,12 +297,13 @@ bool silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
  *    Verifies the authentication data directly from the Authentication 
  *    Payload. Supports all authentication methods. If the authentication
  *    method is passphrase based then the `auth_data' and `auth_data_len'
- *    are the passphrase and its length. If the method is public key
- *    authentication then the `auth_data' is the SilcPublicKey and the
- *    `auth_data_len' is ignored.
+ *    are the passphrase and its length.  The passphrase MUST be UTF-8
+ *    encoded.  If the method is public key authentication then the
+ *    `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
  *
  ***/
-bool silc_auth_verify_data(const unsigned char *payload, SilcUInt32 payload_len,
+bool silc_auth_verify_data(const unsigned char *payload, 
+                          SilcUInt32 payload_len,
                           SilcAuthMethod auth_method, const void *auth_data,
                           SilcUInt32 auth_data_len, SilcHash hash, 
                           const void *id, SilcIdType type);