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(const unsigned char *data,
101 * SilcUInt32 data_len);
105 * Parses and returns Authentication Payload. The `data' and the
106 * `data_len' are the raw payload buffer.
109 SilcAuthPayload silc_auth_payload_parse(const unsigned char *data,
110 SilcUInt32 data_len);
112 /****f* silccore/SilcAuthAPI/silc_auth_payload_encode
116 * SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
117 * const unsigned char *random_data,
118 * SilcUInt16 random_len,
119 * const unsigned char *auth_data,
120 * SilcUInt16 auth_len);
124 * Encodes authentication payload into buffer and returns it.
125 * The `random_data' is provided only if doing public key authentication.
126 * The `auth_data' is the actual authentication data. If the
127 * `method' is SILC_AUTH_PASSWORD the passphase in `auth_data' sent as
128 * argument SHOULD be UTF-8 encoded, if not library will attempt to
132 SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
133 const unsigned char *random_data,
134 SilcUInt16 random_len,
135 const unsigned char *auth_data,
136 SilcUInt16 auth_len);
138 /****f* silccore/SilcAuthAPI/silc_auth_payload_free
142 * void silc_auth_payload_free(SilcAuthPayload payload);
146 * Frees authentication payload and all data in it.
149 void silc_auth_payload_free(SilcAuthPayload payload);
151 /****f* silccore/SilcAuthAPI/silc_auth_get_method
155 * SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
159 * Get authentication method.
162 SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
164 /****f* silccore/SilcAuthAPI/silc_auth_get_public_data
168 * unsigned char *silc_auth_get_public_data(SilcAuthPayload payload,
169 * SilcUInt32 *pubdata_len);
173 * Returns the public data (usually random data) from the payload.
174 * Caller must not free the returned data.
177 unsigned char *silc_auth_get_public_data(SilcAuthPayload payload,
178 SilcUInt32 *pubdata_len);
180 /****f* silccore/SilcAuthAPI/silc_auth_get_data
184 * unsigned char *silc_auth_get_data(SilcAuthPayload payload,
185 * SilcUInt32 *auth_len);
189 * Get the authentication data. The caller must not free the data. If
190 * the authentication method is passphrase, then the returned string
191 * is UTF-8 encoded passphrase.
194 unsigned char *silc_auth_get_data(SilcAuthPayload payload,
195 SilcUInt32 *auth_len);
197 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate
201 * SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
202 * SilcPrivateKey private_key,
210 * Generates Authentication Payload with authentication data. This is used
211 * to do public key based authentication. This generates the random data
212 * and the actual authentication data. Returns NULL on error and the
213 * encoded Authentication Payload on success.
215 * The `private_key' is used to sign the payload. The `public_key', the
216 * and the `id' is encoded in the payload and signed. If the `rng' is
217 * NULL then global RNG is used, if non-NULL then `rng' is used as
218 * random number generator. Also random number is encoded in the
219 * payload before signing it with `private_key'.
222 SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
223 SilcPrivateKey private_key,
224 SilcRng rng, SilcHash hash,
225 const void *id, SilcIdType type);
227 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate_wpub
232 * silc_auth_public_key_auth_generate_wpub(SilcPublicKey public_key,
233 * SilcPrivateKey private_key,
234 * const unsigned char *pubdata,
235 * SilcUInt32 pubdata_len,
242 * Same as silc_auth_public_key_auth_generate but takes the public data
243 * (usually random data) as argument. This function can be used when
244 * the public data must be something else than purely random or its
245 * structure mut be set before signing.
249 silc_auth_public_key_auth_generate_wpub(SilcPublicKey public_key,
250 SilcPrivateKey private_key,
251 const unsigned char *pubdata,
252 SilcUInt32 pubdata_len,
254 const void *id, SilcIdType type);
256 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify
260 * SilcBool silc_auth_public_key_auth_verify(SilcAuthPayload payload,
261 * SilcPublicKey public_key,
263 * const void *id, SilcIdType type);
267 * Verifies the authentication data. Returns TRUE if authentication was
271 SilcBool silc_auth_public_key_auth_verify(SilcAuthPayload payload,
272 SilcPublicKey public_key,
277 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data
281 * SilcBool silc_auth_public_key_auth_verify_data(const unsigned char *payload,
282 * SilcUInt32 payload_len,
283 * SilcPublicKey public_key,
290 * Same as silc_auth_public_key_auth_verify but the payload has not
291 * been parsed yet. This will parse it. Returns TRUE if authentication
295 SilcBool silc_auth_public_key_auth_verify_data(const unsigned char *payload,
296 SilcUInt32 payload_len,
297 SilcPublicKey public_key,
302 /****f* silccore/SilcAuthAPI/silc_auth_verify
306 * SilcBool silc_auth_verify(SilcAuthPayload payload,
307 * SilcAuthMethod auth_method,
308 * const void *auth_data, SilcUInt32 auth_data_len,
309 * SilcHash hash, const void *id, SilcIdType type);
313 * Verifies the authentication data directly from the Authentication
314 * Payload. Supports all authentication methods. If the authentication
315 * method is passphrase based then the `auth_data' and `auth_data_len'
316 * are the passphrase and its length. The passphrase MUST be UTF-8
317 * encoded. If the method is public key authentication then the
318 * `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
321 SilcBool silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
322 const void *auth_data, SilcUInt32 auth_data_len,
323 SilcHash hash, const void *id, SilcIdType type);
325 /****f* silccore/SilcAuthAPI/silc_auth_verify_data
329 * SilcBool silc_auth_verify_data(const unsigned char *payload,
330 * SilcUInt32 payload_len,
331 * SilcAuthMethod auth_method,
332 * const void *auth_data,
333 * SilcUInt32 auth_data_len, SilcHash hash,
334 * const void *id, SilcIdType type);
338 * Same as silc_auth_verify but the payload has not been parsed yet.
339 * Verifies the authentication data directly from the Authentication
340 * Payload. Supports all authentication methods. If the authentication
341 * method is passphrase based then the `auth_data' and `auth_data_len'
342 * are the passphrase and its length. The passphrase MUST be UTF-8
343 * encoded. If the method is public key authentication then the
344 * `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
347 SilcBool silc_auth_verify_data(const unsigned char *payload,
348 SilcUInt32 payload_len,
349 SilcAuthMethod auth_method,
350 const void *auth_data,
351 SilcUInt32 auth_data_len, SilcHash hash,
352 const void *id, SilcIdType type);
354 /****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload
358 * typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
362 * This context is the actual Key Agreement Payload and is allocated
363 * by silc_key_agreement_payload_parse and given as argument usually to all
364 * silc_key_agreement_* functions. It is freed by the function
365 * silc_key_agreement_payload_free.
368 typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
370 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse
374 * SilcKeyAgreementPayload
375 * silc_key_agreement_payload_parse(const unsigned char *payload,
376 * SilcUInt32 payload_len);
380 * Parses and returns an allocated Key Agreement payload.
383 SilcKeyAgreementPayload
384 silc_key_agreement_payload_parse(const unsigned char *payload,
385 SilcUInt32 payload_len);
387 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode
391 * SilcBuffer silc_key_agreement_payload_encode(char *hostname,
392 * SilcUInt16 protocol,
397 * Encodes the Key Agreement payload and returns the encoded buffer.
398 * The `protocol' is 0 for TCP and 1 for UDP.
401 SilcBuffer silc_key_agreement_payload_encode(const char *hostname,
405 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free
409 * void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
413 * Frees the Key Agreement payload and all data in it.
416 void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
418 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_hostname
422 * char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
426 * Returns the hostname in the payload. Caller must not free it.
427 * The hostname is the host that is able to accept key negotiation
428 * using the SILC Key Exchange protocol.
431 char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
433 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_protocol
438 * silc_key_agreement_get_protocol(SilcKeyAgreementPayload payload);
442 * Returns the protocol in the payload. The protocol is either TCP (0)
446 SilcUInt16 silc_key_agreement_get_protocol(SilcKeyAgreementPayload payload);
448 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_port
452 * SilcUInt16 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
456 * Returns the port in the payload. The port is the port on the
457 * host returned by silc_key_agreement_get_hostname that is running
458 * the SILC Key Exchange protocol.
461 SilcUInt16 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);