5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2001 - 2008 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 #define SILC_DEFAULT_HMAC "hmac-sha1-96"
41 #define SILC_DEFAULT_HASH "sha1"
42 #define SILC_DEFAULT_PKCS "rsa"
43 #define SILC_DEFAULT_CIPHER "aes-256-cbc"
45 /****d* silccore/SilcAuthAPI/SilcAuthMethod
49 * typedef SilcUInt16 SilcAuthMethod;
53 * Authentication method type definition, the authentication methods
54 * and the authentication status'. The status defines are used by
55 * all authentication protocols in the SILC.
59 typedef SilcUInt16 SilcAuthMethod;
61 #define SILC_AUTH_NONE 0 /* No authentication */
62 #define SILC_AUTH_PASSWORD 1 /* Passphrase authentication */
63 #define SILC_AUTH_PUBLIC_KEY 2 /* Public key authentication */
65 /****d* silccore/SilcAuthAPI/SilcAuthResult
69 * typedef SilcUInt32 SilcAuthResult;
73 * Authentication protocol status. Used by all authentication protocols
78 typedef SilcUInt32 SilcAuthResult;
80 #define SILC_AUTH_OK 0 /* Authentication successful */
81 #define SILC_AUTH_FAILED 1 /* Authentication failed */
84 /****s* silccore/SilcAuthAPI/SilcAuthPayload
88 * typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
93 * This context is the actual Authentication Payload and is allocated
94 * by silc_auth_payload_parse and given as argument usually to all
95 * silc_auth_payload_* functions. It is freed by silc_auth_payload_free
99 typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
101 /****f* silccore/SilcAuthAPI/silc_auth_payload_parse
105 * SilcAuthPayload silc_auth_payload_parse(SilcStack stack,
106 * 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. If `stack' is non-NULL the
113 * memory is allcoated from `stack'.
116 SilcAuthPayload silc_auth_payload_parse(SilcStack stack,
117 const unsigned char *data,
118 SilcUInt32 data_len);
120 /****f* silccore/SilcAuthAPI/silc_auth_payload_encode
124 * SilcBuffer silc_auth_payload_encode(SilcStack stack,
125 * SilcAuthMethod method,
126 * const unsigned char *random_data,
127 * SilcUInt16 random_len,
128 * const unsigned char *auth_data,
129 * SilcUInt16 auth_len);
133 * Encodes authentication payload into buffer and returns it.
134 * The `random_data' is provided only if doing public key authentication.
135 * The `auth_data' is the actual authentication data. If the
136 * `method' is SILC_AUTH_PASSWORD the passphase in `auth_data' sent as
137 * argument SHOULD be UTF-8 encoded, if not library will attempt to
140 * If `stack' is non-NULL the returned buffer is allocated from `stack'.
141 * This call consumes the `stack' so caller should push the stack before
142 * calling this function and then later pop it.
145 SilcBuffer silc_auth_payload_encode(SilcStack stack,
146 SilcAuthMethod method,
147 const unsigned char *random_data,
148 SilcUInt16 random_len,
149 const unsigned char *auth_data,
150 SilcUInt16 auth_len);
152 /****f* silccore/SilcAuthAPI/silc_auth_payload_free
156 * void silc_auth_payload_free(SilcAuthPayload payload);
160 * Frees authentication payload and all data in it.
163 void silc_auth_payload_free(SilcAuthPayload payload);
165 /****f* silccore/SilcAuthAPI/silc_auth_get_method
169 * SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
173 * Get authentication method.
176 SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
178 /****f* silccore/SilcAuthAPI/silc_auth_get_public_data
182 * unsigned char *silc_auth_get_public_data(SilcAuthPayload payload,
183 * SilcUInt32 *pubdata_len);
187 * Returns the public data (usually random data) from the payload.
188 * Caller must not free the returned data.
191 unsigned char *silc_auth_get_public_data(SilcAuthPayload payload,
192 SilcUInt32 *pubdata_len);
194 /****f* silccore/SilcAuthAPI/silc_auth_get_data
198 * unsigned char *silc_auth_get_data(SilcAuthPayload payload,
199 * SilcUInt32 *auth_len);
203 * Get the authentication data. The caller must not free the data. If
204 * the authentication method is passphrase, then the returned string
205 * is UTF-8 encoded passphrase.
208 unsigned char *silc_auth_get_data(SilcAuthPayload payload,
209 SilcUInt32 *auth_len);
211 /****f* silccore/SilcAuthAPI/SilcAuthGenerated
215 * typedef void (*SilcAuthGenerated)(const SilcBuffer data, void *context);
219 * Callback of this type is given as argument to
220 * silc_auth_public_key_auth_generate and
221 * silc_auth_public_key_auth_generate_wpub to deliver the generated
222 * Authentication Payload. If `data' is NULL the generating failed.
225 typedef void (*SilcAuthGenerated)(const SilcBuffer data, void *context);
227 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate
232 * silc_auth_public_key_auth_generate(SilcPublicKey public_key,
233 * SilcPrivateKey private_key,
238 * SilcAuthGenerated generated,
243 * Generates Authentication Payload with authentication data. This is used
244 * to do public key based authentication. This generates the random data
245 * and the actual authentication data.
247 * The `private_key' is used to sign the payload. The `public_key', the
248 * and the `id' is encoded in the payload and signed. If the `rng' is
249 * NULL then global RNG is used, if non-NULL then `rng' is used as
250 * random number generator. Also random number is encoded in the
251 * payload before signing it with `private_key'.
253 * The `generated' is called to deliver the generated Authentication
258 silc_auth_public_key_auth_generate(SilcPublicKey public_key,
259 SilcPrivateKey private_key,
260 SilcRng rng, SilcHash hash,
261 const void *id, SilcIdType type,
262 SilcAuthGenerated generated,
265 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate_wpub
270 * silc_auth_public_key_auth_generate_wpub(SilcPublicKey public_key,
271 * SilcPrivateKey private_key,
272 * const unsigned char *pubdata,
273 * SilcUInt32 pubdata_len,
278 * SilcAuthGenerated generated,
283 * Same as silc_auth_public_key_auth_generate but takes the public data
284 * (usually random data) as argument. This function can be used when
285 * the public data must be something else than purely random or its
286 * structure mut be set before signing.
288 * The `generated' is called to deliver the generated Authentication
293 silc_auth_public_key_auth_generate_wpub(SilcPublicKey public_key,
294 SilcPrivateKey private_key,
295 const unsigned char *pubdata,
296 SilcUInt32 pubdata_len,
299 const void *id, SilcIdType type,
300 SilcAuthGenerated generated,
303 /****f* silccore/SilcAuthAPI/SilcAuthResult
307 * typedef void (*SilcAuthResult)(SilcBool success, void *context);
311 * Callback of this type is given as argument to silc_auth_verify,
312 * silc_auth_verify_data, silc_auth_public_key_auth_verify and
313 * silc_auth_public_key_auth_verify_data to deliver the result of
314 * the authentication verification. If `success' is FALSE the
315 * authentication failed.
318 typedef void (*SilcAuthResultCb)(SilcBool success, void *context);
320 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify
325 * silc_auth_public_key_auth_verify(SilcAuthPayload payload,
326 * SilcPublicKey public_key,
330 * SilcAuthResult result,
335 * Verifies the authentication data. Calls the `result' to deliver
336 * the result of the verification.
340 silc_auth_public_key_auth_verify(SilcAuthPayload payload,
341 SilcPublicKey public_key,
345 SilcAuthResultCb result,
348 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data
353 * silc_auth_public_key_auth_verify_data(const unsigned char *payload,
354 * SilcUInt32 payload_len,
355 * SilcPublicKey public_key,
359 * SilcAuthResult result,
364 * Same as silc_auth_public_key_auth_verify but the payload has not
365 * been parsed yet. This will parse it. Calls the `result' to deliver
366 * the result of the verification.
370 silc_auth_public_key_auth_verify_data(const unsigned char *payload,
371 SilcUInt32 payload_len,
372 SilcPublicKey public_key,
376 SilcAuthResultCb result,
379 /****f* silccore/SilcAuthAPI/silc_auth_verify
384 * silc_auth_verify(SilcAuthPayload payload,
385 * SilcAuthMethod auth_method,
386 * const void *auth_data,
387 * SilcUInt32 auth_data_len,
389 * const void *id, SilcIdType type,
390 * SilcAuthResult result, void *context);
394 * Verifies the authentication data directly from the Authentication
395 * Payload. Supports all authentication methods. If the authentication
396 * method is passphrase based then the `auth_data' and `auth_data_len'
397 * are the passphrase and its length. The passphrase MUST be UTF-8
398 * encoded. If the method is public key authentication then the
399 * `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
400 * Calls the `result' to deliver the result of the verification.
404 silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
405 const void *auth_data, SilcUInt32 auth_data_len,
406 SilcHash hash, const void *id, SilcIdType type,
407 SilcAuthResultCb result, void *context);
409 /****f* silccore/SilcAuthAPI/silc_auth_verify_data
414 * silc_auth_verify_data(const unsigned char *payload,
415 * SilcUInt32 payload_len,
416 * SilcAuthMethod auth_method,
417 * const void *auth_data,
418 * SilcUInt32 auth_data_len, SilcHash hash,
419 * const void *id, SilcIdType type,
420 * SilcAuthResult result, void *context);
424 * Same as silc_auth_verify but the payload has not been parsed yet.
425 * Verifies the authentication data directly from the Authentication
426 * Payload. Supports all authentication methods. If the authentication
427 * method is passphrase based then the `auth_data' and `auth_data_len'
428 * are the passphrase and its length. The passphrase MUST be UTF-8
429 * encoded. If the method is public key authentication then the
430 * `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
431 * Calls the `result' to deliver the result of the verification.
435 silc_auth_verify_data(const unsigned char *payload,
436 SilcUInt32 payload_len,
437 SilcAuthMethod auth_method,
438 const void *auth_data,
439 SilcUInt32 auth_data_len, SilcHash hash,
440 const void *id, SilcIdType type,
441 SilcAuthResultCb result, void *context);
443 /****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload
447 * typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
451 * This context is the actual Key Agreement Payload and is allocated
452 * by silc_key_agreement_payload_parse and given as argument usually to all
453 * silc_key_agreement_* functions. It is freed by the function
454 * silc_key_agreement_payload_free.
457 typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
459 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse
463 * SilcKeyAgreementPayload
464 * silc_key_agreement_payload_parse(const unsigned char *payload,
465 * SilcUInt32 payload_len);
469 * Parses and returns an allocated Key Agreement payload.
472 SilcKeyAgreementPayload
473 silc_key_agreement_payload_parse(const unsigned char *payload,
474 SilcUInt32 payload_len);
476 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode
480 * SilcBuffer silc_key_agreement_payload_encode(char *hostname,
481 * SilcUInt16 protocol,
486 * Encodes the Key Agreement payload and returns the encoded buffer.
487 * The `protocol' is 0 for TCP and 1 for UDP.
490 SilcBuffer silc_key_agreement_payload_encode(const char *hostname,
494 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free
498 * void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
502 * Frees the Key Agreement payload and all data in it.
505 void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
507 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_hostname
511 * char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
515 * Returns the hostname in the payload. Caller must not free it.
516 * The hostname is the host that is able to accept key negotiation
517 * using the SILC Key Exchange protocol.
520 char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
522 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_protocol
527 * silc_key_agreement_get_protocol(SilcKeyAgreementPayload payload);
531 * Returns the protocol in the payload. The protocol is either TCP (0)
535 SilcUInt16 silc_key_agreement_get_protocol(SilcKeyAgreementPayload payload);
537 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_port
541 * SilcUInt16 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
545 * Returns the port in the payload. The port is the port on the
546 * host returned by silc_key_agreement_get_hostname that is running
547 * the SILC Key Exchange protocol.
550 SilcUInt16 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);