5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2001 - 2007 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; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
20 /****h* silccore/SILC Authentication Interface
24 * Implementations of the SILC Authentication Payload and authentication
25 * routines. The SILC Authentication Payload is used to deliver
26 * authentication data usually from client to server in purpose of
27 * gaining access to some service. The Payload and the authentication
28 * routines supports both passphrase and public key (signature) based
31 * This interface defines also the SILC Key Agreement Payload that is
32 * used by client to agree on key material usually with another client
40 /****d* silccore/SilcAuthAPI/SilcAuthMethod
44 * typedef SilcUInt16 SilcAuthMethod;
48 * Authentication method type definition, the authentication methods
49 * and the authentication status'. The status defines are used by
50 * all authentication protocols in the SILC.
54 typedef SilcUInt16 SilcAuthMethod;
56 #define SILC_AUTH_NONE 0 /* No authentication */
57 #define SILC_AUTH_PASSWORD 1 /* Passphrase authentication */
58 #define SILC_AUTH_PUBLIC_KEY 2 /* Public key authentication */
60 /****d* silccore/SilcAuthAPI/SilcAuthResult
64 * typedef SilcUInt32 SilcAuthResult;
68 * Authentication protocol status. Used by all authentication protocols
73 typedef SilcUInt32 SilcAuthResult;
75 #define SILC_AUTH_OK 0 /* Authentication successful */
76 #define SILC_AUTH_FAILED 1 /* Authentication failed */
79 /****s* silccore/SilcAuthAPI/SilcAuthPayload
83 * typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
88 * This context is the actual Authentication Payload and is allocated
89 * by silc_auth_payload_parse and given as argument usually to all
90 * silc_auth_payload_* functions. It is freed by silc_auth_payload_free
94 typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
96 /****f* silccore/SilcAuthAPI/silc_auth_payload_parse
100 * SilcAuthPayload silc_auth_payload_parse(SilcStack stack,
101 * const unsigned char *data,
102 * SilcUInt32 data_len);
106 * Parses and returns Authentication Payload. The `data' and the
107 * `data_len' are the raw payload buffer. If `stack' is non-NULL the
108 * memory is allcoated from `stack'.
111 SilcAuthPayload silc_auth_payload_parse(SilcStack stack,
112 const unsigned char *data,
113 SilcUInt32 data_len);
115 /****f* silccore/SilcAuthAPI/silc_auth_payload_encode
119 * SilcBuffer silc_auth_payload_encode(SilcStack stack,
120 * SilcAuthMethod method,
121 * const unsigned char *random_data,
122 * SilcUInt16 random_len,
123 * const unsigned char *auth_data,
124 * SilcUInt16 auth_len);
128 * Encodes authentication payload into buffer and returns it.
129 * The `random_data' is provided only if doing public key authentication.
130 * The `auth_data' is the actual authentication data. If the
131 * `method' is SILC_AUTH_PASSWORD the passphase in `auth_data' sent as
132 * argument SHOULD be UTF-8 encoded, if not library will attempt to
135 * If `stack' is non-NULL the returned buffer is allocated from `stack'.
136 * This call consumes the `stack' so caller should push the stack before
137 * calling this function and then later pop it.
140 SilcBuffer silc_auth_payload_encode(SilcStack stack,
141 SilcAuthMethod method,
142 const unsigned char *random_data,
143 SilcUInt16 random_len,
144 const unsigned char *auth_data,
145 SilcUInt16 auth_len);
147 /****f* silccore/SilcAuthAPI/silc_auth_payload_free
151 * void silc_auth_payload_free(SilcAuthPayload payload);
155 * Frees authentication payload and all data in it.
158 void silc_auth_payload_free(SilcAuthPayload payload);
160 /****f* silccore/SilcAuthAPI/silc_auth_get_method
164 * SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
168 * Get authentication method.
171 SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
173 /****f* silccore/SilcAuthAPI/silc_auth_get_public_data
177 * unsigned char *silc_auth_get_public_data(SilcAuthPayload payload,
178 * SilcUInt32 *pubdata_len);
182 * Returns the public data (usually random data) from the payload.
183 * Caller must not free the returned data.
186 unsigned char *silc_auth_get_public_data(SilcAuthPayload payload,
187 SilcUInt32 *pubdata_len);
189 /****f* silccore/SilcAuthAPI/silc_auth_get_data
193 * unsigned char *silc_auth_get_data(SilcAuthPayload payload,
194 * SilcUInt32 *auth_len);
198 * Get the authentication data. The caller must not free the data. If
199 * the authentication method is passphrase, then the returned string
200 * is UTF-8 encoded passphrase.
203 unsigned char *silc_auth_get_data(SilcAuthPayload payload,
204 SilcUInt32 *auth_len);
206 /****f* silccore/SilcAuthAPI/SilcAuthGenerated
210 * typedef void (*SilcAuthGenerated)(const SilcBuffer data, void *context);
214 * Callback of this type is given as argument to
215 * silc_auth_public_key_auth_generate and
216 * silc_auth_public_key_auth_generate_wpub to deliver the generated
217 * Authentication Payload. If `data' is NULL the generating failed.
220 typedef void (*SilcAuthGenerated)(const SilcBuffer data, void *context);
222 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate
227 * silc_auth_public_key_auth_generate(SilcPublicKey public_key,
228 * SilcPrivateKey private_key,
233 * SilcAuthGenerated generated,
238 * Generates Authentication Payload with authentication data. This is used
239 * to do public key based authentication. This generates the random data
240 * and the actual authentication data.
242 * The `private_key' is used to sign the payload. The `public_key', the
243 * and the `id' is encoded in the payload and signed. If the `rng' is
244 * NULL then global RNG is used, if non-NULL then `rng' is used as
245 * random number generator. Also random number is encoded in the
246 * payload before signing it with `private_key'.
248 * The `generated' is called to deliver the generated Authentication
253 silc_auth_public_key_auth_generate(SilcPublicKey public_key,
254 SilcPrivateKey private_key,
255 SilcRng rng, SilcHash hash,
256 const void *id, SilcIdType type,
257 SilcAuthGenerated generated,
260 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate_wpub
265 * silc_auth_public_key_auth_generate_wpub(SilcPublicKey public_key,
266 * SilcPrivateKey private_key,
267 * const unsigned char *pubdata,
268 * SilcUInt32 pubdata_len,
273 * SilcAuthGenerated generated,
278 * Same as silc_auth_public_key_auth_generate but takes the public data
279 * (usually random data) as argument. This function can be used when
280 * the public data must be something else than purely random or its
281 * structure mut be set before signing.
283 * The `generated' is called to deliver the generated Authentication
288 silc_auth_public_key_auth_generate_wpub(SilcPublicKey public_key,
289 SilcPrivateKey private_key,
290 const unsigned char *pubdata,
291 SilcUInt32 pubdata_len,
294 const void *id, SilcIdType type,
295 SilcAuthGenerated generated,
298 /****f* silccore/SilcAuthAPI/SilcAuthResult
302 * typedef void (*SilcAuthResult)(SilcBool success, void *context);
306 * Callback of this type is given as argument to silc_auth_verify,
307 * silc_auth_verify_data, silc_auth_public_key_auth_verify and
308 * silc_auth_public_key_auth_verify_data to deliver the result of
309 * the authentication verification. If `success' is FALSE the
310 * authentication failed.
313 typedef void (*SilcAuthResultCb)(SilcBool success, void *context);
315 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify
320 * silc_auth_public_key_auth_verify(SilcAuthPayload payload,
321 * SilcPublicKey public_key,
325 * SilcAuthResult result,
330 * Verifies the authentication data. Calls the `result' to deliver
331 * the result of the verification.
335 silc_auth_public_key_auth_verify(SilcAuthPayload payload,
336 SilcPublicKey public_key,
340 SilcAuthResultCb result,
343 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data
348 * silc_auth_public_key_auth_verify_data(const unsigned char *payload,
349 * SilcUInt32 payload_len,
350 * SilcPublicKey public_key,
354 * SilcAuthResult result,
359 * Same as silc_auth_public_key_auth_verify but the payload has not
360 * been parsed yet. This will parse it. Calls the `result' to deliver
361 * the result of the verification.
365 silc_auth_public_key_auth_verify_data(const unsigned char *payload,
366 SilcUInt32 payload_len,
367 SilcPublicKey public_key,
371 SilcAuthResultCb result,
374 /****f* silccore/SilcAuthAPI/silc_auth_verify
379 * silc_auth_verify(SilcAuthPayload payload,
380 * SilcAuthMethod auth_method,
381 * const void *auth_data,
382 * SilcUInt32 auth_data_len,
384 * const void *id, SilcIdType type,
385 * SilcAuthResult result, void *context);
389 * Verifies the authentication data directly from the Authentication
390 * Payload. Supports all authentication methods. If the authentication
391 * method is passphrase based then the `auth_data' and `auth_data_len'
392 * are the passphrase and its length. The passphrase MUST be UTF-8
393 * encoded. If the method is public key authentication then the
394 * `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
395 * Calls the `result' to deliver the result of the verification.
399 silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
400 const void *auth_data, SilcUInt32 auth_data_len,
401 SilcHash hash, const void *id, SilcIdType type,
402 SilcAuthResultCb result, void *context);
404 /****f* silccore/SilcAuthAPI/silc_auth_verify_data
409 * silc_auth_verify_data(const unsigned char *payload,
410 * SilcUInt32 payload_len,
411 * SilcAuthMethod auth_method,
412 * const void *auth_data,
413 * SilcUInt32 auth_data_len, SilcHash hash,
414 * const void *id, SilcIdType type,
415 * SilcAuthResult result, void *context);
419 * Same as silc_auth_verify but the payload has not been parsed yet.
420 * Verifies the authentication data directly from the Authentication
421 * Payload. Supports all authentication methods. If the authentication
422 * method is passphrase based then the `auth_data' and `auth_data_len'
423 * are the passphrase and its length. The passphrase MUST be UTF-8
424 * encoded. If the method is public key authentication then the
425 * `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
426 * Calls the `result' to deliver the result of the verification.
430 silc_auth_verify_data(const unsigned char *payload,
431 SilcUInt32 payload_len,
432 SilcAuthMethod auth_method,
433 const void *auth_data,
434 SilcUInt32 auth_data_len, SilcHash hash,
435 const void *id, SilcIdType type,
436 SilcAuthResultCb result, void *context);
438 /****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload
442 * typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
446 * This context is the actual Key Agreement Payload and is allocated
447 * by silc_key_agreement_payload_parse and given as argument usually to all
448 * silc_key_agreement_* functions. It is freed by the function
449 * silc_key_agreement_payload_free.
452 typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
454 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse
458 * SilcKeyAgreementPayload
459 * silc_key_agreement_payload_parse(const unsigned char *payload,
460 * SilcUInt32 payload_len);
464 * Parses and returns an allocated Key Agreement payload.
467 SilcKeyAgreementPayload
468 silc_key_agreement_payload_parse(const unsigned char *payload,
469 SilcUInt32 payload_len);
471 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode
475 * SilcBuffer silc_key_agreement_payload_encode(char *hostname,
476 * SilcUInt16 protocol,
481 * Encodes the Key Agreement payload and returns the encoded buffer.
482 * The `protocol' is 0 for TCP and 1 for UDP.
485 SilcBuffer silc_key_agreement_payload_encode(const char *hostname,
489 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free
493 * void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
497 * Frees the Key Agreement payload and all data in it.
500 void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
502 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_hostname
506 * char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
510 * Returns the hostname in the payload. Caller must not free it.
511 * The hostname is the host that is able to accept key negotiation
512 * using the SILC Key Exchange protocol.
515 char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
517 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_protocol
522 * silc_key_agreement_get_protocol(SilcKeyAgreementPayload payload);
526 * Returns the protocol in the payload. The protocol is either TCP (0)
530 SilcUInt16 silc_key_agreement_get_protocol(SilcKeyAgreementPayload payload);
532 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_port
536 * SilcUInt16 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
540 * Returns the port in the payload. The port is the port on the
541 * host returned by silc_key_agreement_get_hostname that is running
542 * the SILC Key Exchange protocol.
545 SilcUInt16 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);