X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilccore%2Fsilcauth.h;h=29101966d7ce6208f7b79055477b6ca1a66cd64d;hb=413da0f8686910f5e627393157566ae729ca99c4;hp=a42c60fc902462dd8a391d6a4a2dbbe255b5a3b4;hpb=395df2c1aeed253ccaad7978a0cf866c3ef3a738;p=silc.git diff --git a/lib/silccore/silcauth.h b/lib/silccore/silcauth.h index a42c60fc..29101966 100644 --- a/lib/silccore/silcauth.h +++ b/lib/silccore/silcauth.h @@ -1,16 +1,15 @@ /* silcauth.h - + Author: Pekka Riikonen - - Copyright (C) 2001 Pekka Riikonen - + + Copyright (C) 2001 - 2003 Pekka Riikonen + This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - + the Free Software Foundation; version 2 of the License. + This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -18,13 +17,13 @@ */ -/****h* silccore/SilcAuthAPI +/****h* silccore/SILC Authentication Interface * * DESCRIPTION * - * Implementations of the Silc Authentication Payload and authentication - * routines. The SILC Authentication Payload is used to deliver - * authentication data usually from client to server in purpose of + * Implementations of the SILC Authentication Payload and authentication + * routines. The SILC Authentication Payload is used to deliver + * authentication data usually from client to server in purpose of * gaining access to some service. The Payload and the authentication * routines supports both passphrase and public key (signature) based * authentication. @@ -38,44 +37,11 @@ #ifndef SILCAUTH_H #define SILCAUTH_H -/****s* silccore/SilcAuthAPI/SilcAuthPayload - * - * NAME - * - * typedef struct SilcAuthPayloadStruct *SilcAuthPayload; - * - * - * DESCRIPTION - * - * This context is the actual Authentication Payload and is allocated - * by silc_auth_payload_parse and given as argument usually to all - * silc_auth_payload_* functions. It is freed by silc_auth_payload_free - * function. - * - ***/ -typedef struct SilcAuthPayloadStruct *SilcAuthPayload; - -/****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload - * - * NAME - * - * typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload; - * - * DESCRIPTION - * - * This context is the actual Key Agreement Payload and is allocated - * by silc_key_agreement_payload_parse and given as argument usually to all - * silc_key_agreement_* functions. It is freed by the function - * silc_key_agreement_payload_free. - * - ***/ -typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload; - /****d* silccore/SilcAuthAPI/SilcAuthMethod * * NAME - * - * typedef uint16 SilcAuthMethod; + * + * typedef SilcUInt16 SilcAuthMethod; * * DESCRIPTION * @@ -85,7 +51,7 @@ typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload; * * SOURCE */ -typedef uint16 SilcAuthMethod; +typedef SilcUInt16 SilcAuthMethod; #define SILC_AUTH_NONE 0 /* No authentication */ #define SILC_AUTH_PASSWORD 1 /* Passphrase authentication */ @@ -97,14 +63,29 @@ typedef uint16 SilcAuthMethod; #define SILC_AUTH_FAILED 1 /***/ -/* Prototypes */ +/****s* silccore/SilcAuthAPI/SilcAuthPayload + * + * NAME + * + * typedef struct SilcAuthPayloadStruct *SilcAuthPayload; + * + * + * DESCRIPTION + * + * This context is the actual Authentication Payload and is allocated + * by silc_auth_payload_parse and given as argument usually to all + * silc_auth_payload_* functions. It is freed by silc_auth_payload_free + * function. + * + ***/ +typedef struct SilcAuthPayloadStruct *SilcAuthPayload; /****f* silccore/SilcAuthAPI/silc_auth_payload_parse * * SYNOPSIS * - * SilcAuthPayload silc_auth_payload_parse(unsigned char *data, - * uint32 data_len); + * SilcAuthPayload silc_auth_payload_parse(const unsigned char *data, + * SilcUInt32 data_len); * * DESCRIPTION * @@ -112,31 +93,34 @@ typedef uint16 SilcAuthMethod; * `data_len' are the raw payload buffer. * ***/ -SilcAuthPayload silc_auth_payload_parse(unsigned char *data, - uint32 data_len); +SilcAuthPayload silc_auth_payload_parse(const unsigned char *data, + SilcUInt32 data_len); /****f* silccore/SilcAuthAPI/silc_auth_payload_encode * * SYNOPSIS * * SilcBuffer silc_auth_payload_encode(SilcAuthMethod method, - * unsigned char *random_data, - * uint16 random_len, - * unsigned char *auth_data, - * uint16 auth_len); + * const unsigned char *random_data, + * SilcUInt16 random_len, + * const unsigned char *auth_data, + * SilcUInt16 auth_len); * * DESCRIPTION * * 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, - unsigned char *random_data, - uint16 random_len, - unsigned char *auth_data, - uint16 auth_len); + const unsigned char *random_data, + SilcUInt16 random_len, + const unsigned char *auth_data, + SilcUInt16 auth_len); /****f* silccore/SilcAuthAPI/silc_auth_payload_free * @@ -164,20 +148,38 @@ void silc_auth_payload_free(SilcAuthPayload payload); ***/ SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload); +/****f* silccore/SilcAuthAPI/silc_auth_get_public_data + * + * SYNOPSIS + * + * unsigned char *silc_auth_get_public_data(SilcAuthPayload payload, + * SilcUInt32 *pubdata_len); + * + * DESCRIPTION + * + * Returns the public data (usually random data) from the payload. + * Caller must not free the returned data. + * + ***/ +unsigned char *silc_auth_get_public_data(SilcAuthPayload payload, + SilcUInt32 *pubdata_len); + /****f* silccore/SilcAuthAPI/silc_auth_get_data * * SYNOPSIS * * unsigned char *silc_auth_get_data(SilcAuthPayload payload, - * uint32 *auth_len); + * SilcUInt32 *auth_len); * * 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, - uint32 *auth_len); + SilcUInt32 *auth_len); /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate * @@ -185,8 +187,10 @@ 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, - * void *id, SilcIdType type); + * const void *id, + * SilcIdType type); * * DESCRIPTION * @@ -195,20 +199,55 @@ 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, - void *id, SilcIdType type); + SilcRng rng, SilcHash hash, + const void *id, SilcIdType type); + +/****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate_wpub + * + * SYNOPSIS + * + * SilcBuffer + * silc_auth_public_key_auth_generate_wpub(SilcPublicKey public_key, + * SilcPrivateKey private_key, + * const unsigned char *pubdata, + * SilcUInt32 pubdata_len, + * SilcHash hash, + * const void *id, + * SilcIdType type); + * + * DESCRIPTION + * + * Same as silc_auth_public_key_auth_generate but takes the public data + * (usually random data) as argument. This function can be used when + * the public data must be something else than purely random or its + * structure mut be set before signing. + * + ***/ +SilcBuffer +silc_auth_public_key_auth_generate_wpub(SilcPublicKey public_key, + SilcPrivateKey private_key, + const unsigned char *pubdata, + SilcUInt32 pubdata_len, + SilcHash hash, + const void *id, SilcIdType type); /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify * * SYNOPSIS * - * int silc_auth_public_key_auth_verify(SilcAuthPayload payload, - * SilcPublicKey public_key, - * SilcHash hash, - * void *id, SilcIdType type); + * bool silc_auth_public_key_auth_verify(SilcAuthPayload payload, + * SilcPublicKey public_key, + * SilcHash hash, + * const void *id, SilcIdType type); * * DESCRIPTION * @@ -216,18 +255,20 @@ SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key, * successful. * ***/ -int silc_auth_public_key_auth_verify(SilcAuthPayload payload, - SilcPublicKey public_key, SilcHash hash, - void *id, SilcIdType type); +bool silc_auth_public_key_auth_verify(SilcAuthPayload payload, + SilcPublicKey public_key, SilcHash hash, + const void *id, SilcIdType type); /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data * * SYNOPSIS * - * int silc_auth_public_key_auth_verify_data(SilcBuffer payload, - * SilcPublicKey public_key, - * SilcHash hash, - * void *id, SilcIdType type); + * bool silc_auth_public_key_auth_verify_data(const unsigned char *payload, + * SilcUInt32 payload_len, + * SilcPublicKey public_key, + * SilcHash hash, + * const void *id, + * SilcIdType type); * * DESCRIPTION * @@ -236,78 +277,102 @@ int silc_auth_public_key_auth_verify(SilcAuthPayload payload, * was successful. * ***/ -int silc_auth_public_key_auth_verify_data(SilcBuffer payload, - SilcPublicKey public_key, - SilcHash hash, - void *id, SilcIdType type); +bool silc_auth_public_key_auth_verify_data(const unsigned char *payload, + SilcUInt32 payload_len, + SilcPublicKey public_key, + SilcHash hash, + const void *id, SilcIdType type); /****f* silccore/SilcAuthAPI/silc_auth_verify * * SYNOPSIS * - * int silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method, - * void *auth_data, uint32 auth_data_len, - * SilcHash hash, void *id, SilcIdType type); + * bool silc_auth_verify(SilcAuthPayload payload, + * SilcAuthMethod auth_method, + * const void *auth_data, SilcUInt32 auth_data_len, + * SilcHash hash, const void *id, SilcIdType type); * * DESCRIPTION * - * Verifies the authentication data directly from the Authentication + * 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. * ***/ -int silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method, - void *auth_data, uint32 auth_data_len, - SilcHash hash, void *id, SilcIdType type); +bool silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method, + const void *auth_data, SilcUInt32 auth_data_len, + SilcHash hash, const void *id, SilcIdType type); /****f* silccore/SilcAuthAPI/silc_auth_verify_data * * SYNOPSIS * - * int silc_auth_verify_data(unsigned char *payload, uint32 payload_len, - * SilcAuthMethod auth_method, void *auth_data, - * uint32 auth_data_len, SilcHash hash, - * void *id, SilcIdType type); + * 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); * * DESCRIPTION * * Same as silc_auth_verify but the payload has not been parsed yet. - * Verifies the authentication data directly from the Authentication + * 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. * ***/ -int silc_auth_verify_data(unsigned char *payload, uint32 payload_len, - SilcAuthMethod auth_method, void *auth_data, - uint32 auth_data_len, SilcHash hash, - void *id, SilcIdType type); +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); + +/****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload + * + * NAME + * + * typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload; + * + * DESCRIPTION + * + * This context is the actual Key Agreement Payload and is allocated + * by silc_key_agreement_payload_parse and given as argument usually to all + * silc_key_agreement_* functions. It is freed by the function + * silc_key_agreement_payload_free. + * + ***/ +typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload; /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse * * SYNOPSIS * - * SilcKeyAgreementPayload - * silc_key_agreement_payload_parse(SilcBuffer buffer); + * SilcKeyAgreementPayload + * silc_key_agreement_payload_parse(const unsigned char *payload, + * SilcUInt32 payload_len); * * DESCRIPTION * * Parses and returns an allocated Key Agreement payload. * ***/ -SilcKeyAgreementPayload silc_key_agreement_payload_parse(SilcBuffer buffer); +SilcKeyAgreementPayload +silc_key_agreement_payload_parse(const unsigned char *payload, + SilcUInt32 payload_len); /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode * * SYNOPSIS * * SilcBuffer silc_key_agreement_payload_encode(char *hostname, - * uint32 port); + * SilcUInt32 port); * * DESCRIPTION * @@ -315,7 +380,7 @@ SilcKeyAgreementPayload silc_key_agreement_payload_parse(SilcBuffer buffer); * ***/ SilcBuffer silc_key_agreement_payload_encode(const char *hostname, - uint32 port); + SilcUInt32 port); /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free * @@ -349,7 +414,7 @@ char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload); * * SYNOPSIS * - * uint32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload); + * SilcUInt32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload); * * DESCRIPTION * @@ -358,6 +423,6 @@ char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload); * the SILC Key Exchange protocol. * ***/ -uint32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload); +SilcUInt32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload); #endif