5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2001 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; either version 2 of the License, or
12 (at your option) any later version.
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License for more details.
21 /****h* silccore/SILC Authentication Interface
25 * Implementations of the SILC Authentication Payload and authentication
26 * routines. The SILC Authentication Payload is used to deliver
27 * authentication data usually from client to server in purpose of
28 * gaining access to some service. The Payload and the authentication
29 * routines supports both passphrase and public key (signature) based
32 * This interface defines also the SILC Key Agreement Payload that is
33 * used by client to agree on key material usually with another client
41 /****s* silccore/SilcAuthAPI/SilcAuthPayload
45 * typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
50 * This context is the actual Authentication Payload and is allocated
51 * by silc_auth_payload_parse and given as argument usually to all
52 * silc_auth_payload_* functions. It is freed by silc_auth_payload_free
56 typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
58 /****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload
62 * typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
66 * This context is the actual Key Agreement Payload and is allocated
67 * by silc_key_agreement_payload_parse and given as argument usually to all
68 * silc_key_agreement_* functions. It is freed by the function
69 * silc_key_agreement_payload_free.
72 typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
74 /****d* silccore/SilcAuthAPI/SilcAuthMethod
78 * typedef SilcUInt16 SilcAuthMethod;
82 * Authentication method type definition, the authentication methods
83 * and the authentication status'. The status defines are used by
84 * all authentication protocols in the SILC.
88 typedef SilcUInt16 SilcAuthMethod;
90 #define SILC_AUTH_NONE 0 /* No authentication */
91 #define SILC_AUTH_PASSWORD 1 /* Passphrase authentication */
92 #define SILC_AUTH_PUBLIC_KEY 2 /* Public key authentication */
94 /* Authentication protocol status message (used by all authentication
95 protocols in the SILC). */
96 #define SILC_AUTH_OK 0
97 #define SILC_AUTH_FAILED 1
102 /****f* silccore/SilcAuthAPI/silc_auth_payload_parse
106 * SilcAuthPayload silc_auth_payload_parse(const unsigned char *data,
107 * SilcUInt32 data_len);
111 * Parses and returns Authentication Payload. The `data' and the
112 * `data_len' are the raw payload buffer.
115 SilcAuthPayload silc_auth_payload_parse(const unsigned char *data,
116 SilcUInt32 data_len);
118 /****f* silccore/SilcAuthAPI/silc_auth_payload_encode
122 * SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
123 * const unsigned char *random_data,
124 * SilcUInt16 random_len,
125 * const unsigned char *auth_data,
126 * SilcUInt16 auth_len);
130 * Encodes authentication payload into buffer and returns it.
131 * The `random_data' is provided only if doing public key authentication.
132 * The `auth_data' is the actual authentication data. If the
133 * `method' is SILC_AUTH_PASSWORD the passphase in `auth_data' sent as
134 * argument SHOULD be UTF-8 encoded, if not library will attempt to
138 SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
139 const unsigned char *random_data,
140 SilcUInt16 random_len,
141 const unsigned char *auth_data,
142 SilcUInt16 auth_len);
144 /****f* silccore/SilcAuthAPI/silc_auth_payload_free
148 * void silc_auth_payload_free(SilcAuthPayload payload);
152 * Frees authentication payload and all data in it.
155 void silc_auth_payload_free(SilcAuthPayload payload);
157 /****f* silccore/SilcAuthAPI/silc_auth_get_method
161 * SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
165 * Get authentication method.
168 SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
170 /****f* silccore/SilcAuthAPI/silc_auth_get_data
174 * unsigned char *silc_auth_get_data(SilcAuthPayload payload,
175 * SilcUInt32 *auth_len);
179 * Get the authentication data. The caller must not free the data. If
180 * the authentication method is passphrase, then the returned string
181 * is UTF-8 encoded passphrase.
184 unsigned char *silc_auth_get_data(SilcAuthPayload payload,
185 SilcUInt32 *auth_len);
187 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate
191 * SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
192 * SilcPrivateKey private_key,
200 * Generates Authentication Payload with authentication data. This is used
201 * to do public key based authentication. This generates the random data
202 * and the actual authentication data. Returns NULL on error and the
203 * encoded Authentication Payload on success.
205 * The `private_key' is used to sign the payload. The `public_key', the
206 * and the `id' is encoded in the payload and signed. If the `rng' is
207 * NULL then global RNG is used, if non-NULL then `rng' is used as
208 * random number generator. Also random number is encoded in the
209 * payload before signing it with `private_key'.
212 SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
213 SilcPrivateKey private_key,
214 SilcRng rng, SilcHash hash,
215 const void *id, SilcIdType type);
217 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify
221 * bool silc_auth_public_key_auth_verify(SilcAuthPayload payload,
222 * SilcPublicKey public_key,
224 * const void *id, SilcIdType type);
228 * Verifies the authentication data. Returns TRUE if authentication was
232 bool silc_auth_public_key_auth_verify(SilcAuthPayload payload,
233 SilcPublicKey public_key, SilcHash hash,
234 const void *id, SilcIdType type);
236 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data
240 * bool silc_auth_public_key_auth_verify_data(const unsigned char *payload,
241 * SilcUInt32 payload_len,
242 * SilcPublicKey public_key,
249 * Same as silc_auth_public_key_auth_verify but the payload has not
250 * been parsed yet. This will parse it. Returns TRUE if authentication
254 bool silc_auth_public_key_auth_verify_data(const unsigned char *payload,
255 SilcUInt32 payload_len,
256 SilcPublicKey public_key,
258 const void *id, SilcIdType type);
260 /****f* silccore/SilcAuthAPI/silc_auth_verify
264 * bool silc_auth_verify(SilcAuthPayload payload,
265 * SilcAuthMethod auth_method,
266 * const void *auth_data, SilcUInt32 auth_data_len,
267 * SilcHash hash, const void *id, SilcIdType type);
271 * Verifies the authentication data directly from the Authentication
272 * Payload. Supports all authentication methods. If the authentication
273 * method is passphrase based then the `auth_data' and `auth_data_len'
274 * are the passphrase and its length. The passphrase MUST be UTF-8
275 * encoded. If the method is public key authentication then the
276 * `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
279 bool silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
280 const void *auth_data, SilcUInt32 auth_data_len,
281 SilcHash hash, const void *id, SilcIdType type);
283 /****f* silccore/SilcAuthAPI/silc_auth_verify_data
287 * bool silc_auth_verify_data(const unsigned char *payload,
288 * SilcUInt32 payload_len,
289 * SilcAuthMethod auth_method,
290 * const void *auth_data,
291 * SilcUInt32 auth_data_len, SilcHash hash,
292 * const void *id, SilcIdType type);
296 * Same as silc_auth_verify but the payload has not been parsed yet.
297 * Verifies the authentication data directly from the Authentication
298 * Payload. Supports all authentication methods. If the authentication
299 * method is passphrase based then the `auth_data' and `auth_data_len'
300 * are the passphrase and its length. The passphrase MUST be UTF-8
301 * encoded. If the method is public key authentication then the
302 * `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
305 bool silc_auth_verify_data(const unsigned char *payload,
306 SilcUInt32 payload_len,
307 SilcAuthMethod auth_method, const void *auth_data,
308 SilcUInt32 auth_data_len, SilcHash hash,
309 const void *id, SilcIdType type);
311 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse
315 * SilcKeyAgreementPayload
316 * silc_key_agreement_payload_parse(const unsigned char *payload,
317 * SilcUInt32 payload_len);
321 * Parses and returns an allocated Key Agreement payload.
324 SilcKeyAgreementPayload
325 silc_key_agreement_payload_parse(const unsigned char *payload,
326 SilcUInt32 payload_len);
328 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode
332 * SilcBuffer silc_key_agreement_payload_encode(char *hostname,
337 * Encodes the Key Agreement protocol and returns the encoded buffer
340 SilcBuffer silc_key_agreement_payload_encode(const char *hostname,
343 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free
347 * void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
351 * Frees the Key Agreement protocol and all data in it.
354 void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
356 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_hostname
360 * char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
364 * Returns the hostname in the payload. Caller must not free it.
365 * The hostname is the host that is able to accept key negotiation
366 * using the SILC Key Exchange protocol.
369 char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
371 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_port
375 * SilcUInt32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
379 * Returns the port in the payload. The port is the port on the
380 * host returned by silc_key_agreement_get_hostname that is running
381 * the SILC Key Exchange protocol.
384 SilcUInt32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);