5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2001 - 2002 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
35 * This interface defines also the SILC_MESSAGE_FLAG_SIGNED Payload,
36 * which defines how channel messages and private messages can be digitally
37 * signed. This interface provides the payload parsing, encoding,
38 * signature computing and signature verification routines.
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 /* Authentication protocol status message (used by all authentication
66 protocols in the SILC). */
67 #define SILC_AUTH_OK 0
68 #define SILC_AUTH_FAILED 1
71 /****s* silccore/SilcAuthAPI/SilcAuthPayload
75 * typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
80 * This context is the actual Authentication Payload and is allocated
81 * by silc_auth_payload_parse and given as argument usually to all
82 * silc_auth_payload_* functions. It is freed by silc_auth_payload_free
86 typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
88 /****f* silccore/SilcAuthAPI/silc_auth_payload_parse
92 * SilcAuthPayload silc_auth_payload_parse(const unsigned char *data,
93 * SilcUInt32 data_len);
97 * Parses and returns Authentication Payload. The `data' and the
98 * `data_len' are the raw payload buffer.
101 SilcAuthPayload silc_auth_payload_parse(const unsigned char *data,
102 SilcUInt32 data_len);
104 /****f* silccore/SilcAuthAPI/silc_auth_payload_encode
108 * SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
109 * const unsigned char *random_data,
110 * SilcUInt16 random_len,
111 * const unsigned char *auth_data,
112 * SilcUInt16 auth_len);
116 * Encodes authentication payload into buffer and returns it.
117 * The `random_data' is provided only if doing public key authentication.
118 * The `auth_data' is the actual authentication data. If the
119 * `method' is SILC_AUTH_PASSWORD the passphase in `auth_data' sent as
120 * argument SHOULD be UTF-8 encoded, if not library will attempt to
124 SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
125 const unsigned char *random_data,
126 SilcUInt16 random_len,
127 const unsigned char *auth_data,
128 SilcUInt16 auth_len);
130 /****f* silccore/SilcAuthAPI/silc_auth_payload_free
134 * void silc_auth_payload_free(SilcAuthPayload payload);
138 * Frees authentication payload and all data in it.
141 void silc_auth_payload_free(SilcAuthPayload payload);
143 /****f* silccore/SilcAuthAPI/silc_auth_get_method
147 * SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
151 * Get authentication method.
154 SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
156 /****f* silccore/SilcAuthAPI/silc_auth_get_data
160 * unsigned char *silc_auth_get_data(SilcAuthPayload payload,
161 * SilcUInt32 *auth_len);
165 * Get the authentication data. The caller must not free the data. If
166 * the authentication method is passphrase, then the returned string
167 * is UTF-8 encoded passphrase.
170 unsigned char *silc_auth_get_data(SilcAuthPayload payload,
171 SilcUInt32 *auth_len);
173 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate
177 * SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
178 * SilcPrivateKey private_key,
186 * Generates Authentication Payload with authentication data. This is used
187 * to do public key based authentication. This generates the random data
188 * and the actual authentication data. Returns NULL on error and the
189 * encoded Authentication Payload on success.
191 * The `private_key' is used to sign the payload. The `public_key', the
192 * and the `id' is encoded in the payload and signed. If the `rng' is
193 * NULL then global RNG is used, if non-NULL then `rng' is used as
194 * random number generator. Also random number is encoded in the
195 * payload before signing it with `private_key'.
198 SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
199 SilcPrivateKey private_key,
200 SilcRng rng, SilcHash hash,
201 const void *id, SilcIdType type);
203 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify
207 * bool silc_auth_public_key_auth_verify(SilcAuthPayload payload,
208 * SilcPublicKey public_key,
210 * const void *id, SilcIdType type);
214 * Verifies the authentication data. Returns TRUE if authentication was
218 bool silc_auth_public_key_auth_verify(SilcAuthPayload payload,
219 SilcPublicKey public_key, SilcHash hash,
220 const void *id, SilcIdType type);
222 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data
226 * bool silc_auth_public_key_auth_verify_data(const unsigned char *payload,
227 * SilcUInt32 payload_len,
228 * SilcPublicKey public_key,
235 * Same as silc_auth_public_key_auth_verify but the payload has not
236 * been parsed yet. This will parse it. Returns TRUE if authentication
240 bool silc_auth_public_key_auth_verify_data(const unsigned char *payload,
241 SilcUInt32 payload_len,
242 SilcPublicKey public_key,
244 const void *id, SilcIdType type);
246 /****f* silccore/SilcAuthAPI/silc_auth_verify
250 * bool silc_auth_verify(SilcAuthPayload payload,
251 * SilcAuthMethod auth_method,
252 * const void *auth_data, SilcUInt32 auth_data_len,
253 * SilcHash hash, const void *id, SilcIdType type);
257 * Verifies the authentication data directly from the Authentication
258 * Payload. Supports all authentication methods. If the authentication
259 * method is passphrase based then the `auth_data' and `auth_data_len'
260 * are the passphrase and its length. The passphrase MUST be UTF-8
261 * encoded. If the method is public key authentication then the
262 * `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
265 bool silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
266 const void *auth_data, SilcUInt32 auth_data_len,
267 SilcHash hash, const void *id, SilcIdType type);
269 /****f* silccore/SilcAuthAPI/silc_auth_verify_data
273 * bool silc_auth_verify_data(const unsigned char *payload,
274 * SilcUInt32 payload_len,
275 * SilcAuthMethod auth_method,
276 * const void *auth_data,
277 * SilcUInt32 auth_data_len, SilcHash hash,
278 * const void *id, SilcIdType type);
282 * Same as silc_auth_verify but the payload has not been parsed yet.
283 * Verifies the authentication data directly from the Authentication
284 * Payload. Supports all authentication methods. If the authentication
285 * method is passphrase based then the `auth_data' and `auth_data_len'
286 * are the passphrase and its length. The passphrase MUST be UTF-8
287 * encoded. If the method is public key authentication then the
288 * `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
291 bool silc_auth_verify_data(const unsigned char *payload,
292 SilcUInt32 payload_len,
293 SilcAuthMethod auth_method, const void *auth_data,
294 SilcUInt32 auth_data_len, SilcHash hash,
295 const void *id, SilcIdType type);
297 /****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload
301 * typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
305 * This context is the actual Key Agreement Payload and is allocated
306 * by silc_key_agreement_payload_parse and given as argument usually to all
307 * silc_key_agreement_* functions. It is freed by the function
308 * silc_key_agreement_payload_free.
311 typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
313 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse
317 * SilcKeyAgreementPayload
318 * silc_key_agreement_payload_parse(const unsigned char *payload,
319 * SilcUInt32 payload_len);
323 * Parses and returns an allocated Key Agreement payload.
326 SilcKeyAgreementPayload
327 silc_key_agreement_payload_parse(const unsigned char *payload,
328 SilcUInt32 payload_len);
330 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode
334 * SilcBuffer silc_key_agreement_payload_encode(char *hostname,
339 * Encodes the Key Agreement protocol and returns the encoded buffer
342 SilcBuffer silc_key_agreement_payload_encode(const char *hostname,
345 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free
349 * void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
353 * Frees the Key Agreement protocol and all data in it.
356 void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
358 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_hostname
362 * char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
366 * Returns the hostname in the payload. Caller must not free it.
367 * The hostname is the host that is able to accept key negotiation
368 * using the SILC Key Exchange protocol.
371 char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
373 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_port
377 * SilcUInt32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
381 * Returns the port in the payload. The port is the port on the
382 * host returned by silc_key_agreement_get_hostname that is running
383 * the SILC Key Exchange protocol.
386 SilcUInt32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
388 /****s* silccore/SilcAuthAPI/SilcSignedPayload
392 * typedef struct SilcSignedPayloadStruct *SilcSignedPayload;
397 * This context represents the SILC_MESSAGE_FLAG_SIGNED Payload which
398 * is used with channel messages and private messages to indicate that
399 * the message is digitally signed. This payload may include the
400 * message sender's public key and it includes the digital signature.
401 * This payload MUST NOT be used in any other context except with
402 * channel and private message sending and reception.
405 typedef struct SilcSignedPayloadStruct *SilcSignedPayload;
407 /****f* silccore/SilcAuthAPI/silc_signed_payload_parse
411 * SilcSignedPayload silc_signed_payload_parse(const unsigned char *data,
412 * SilcUInt32 data_len);
416 * Parses the SILC_MESSAGE_FLAG_SIGNED Payload from the `data' of
417 * length of `data_len' bytes. The `data' must be payload without
418 * the actual message payload. Returns the parsed payload or NULL
419 * on error. Caller must free the returned payload.
422 SilcSignedPayload silc_signed_payload_parse(const unsigned char *data,
423 SilcUInt32 data_len);
425 /****f* silccore/SilcAuthAPI/silc_signed_payload_encode
430 * silc_signed_payload_encode(const unsigned char *message_payload,
431 * SilcUInt32 message_payload_len,
432 * SilcPublicKey public_key,
433 * SilcPrivateKey private_key,
434 * bool include_public_key);
438 * Encodes the SILC_MESSAGE_FLAG_SIGNED Payload and computes the
439 * digital signature. The `message_payload' is the message data that
440 * is used in the signature computation. The encoding of the buffer
441 * is specified in the SILC protocol. If `include_public_key' is
442 * TRUE then the public key included in the payload. The `private_key'
443 * is used to produce the signature. This function returns the encoded
444 * payload with the signature or NULL on error. Caller must free the
448 SilcBuffer silc_signed_payload_encode(const unsigned char *message_payload,
449 SilcUInt32 message_payload_len,
450 SilcPublicKey public_key,
451 SilcPrivateKey private_key,
453 bool include_public_key);
455 /****f* silccore/SilcAuthAPI/silc_signed_payload_free
459 * void silc_signed_payload_free(SilcSignedPayload sig);
463 * Frees the SILC_MESSAGE_FLAG_SIGNED Payload.
466 void silc_signed_payload_free(SilcSignedPayload sig);
468 /****f* silccore/SilcAuthAPI/silc_signed_payload_verify
472 * int silc_signed_payload_verify(SilcSignedPayload sig,
473 * bool channel_message,
474 * void *message_payload,
475 * SilcPublicKey remote_public_key,
480 * This routine can be used to verify the signature found in
481 * SILC_MESSAGE_FLAG_SIGNED Payload. The `remote_public_key' is the
482 * sender's public key and is used in the verification. If the
483 * `channel_message' is TRUE then `message_payload' must include the
484 * SilcChannelMessagePayload. If it is FALSE then it must include
485 * SilcPrivateMessagePayload. This returns SILC_AUTH_OK if the
486 * signature verification was successful.
489 int silc_signed_payload_verify(SilcSignedPayload sig,
490 bool channel_message,
491 void *message_payload,
492 SilcPublicKey remote_public_key,
495 /****f* silccore/SilcAuthAPI/silc_signed_payload_get_public_key
499 * SilcPublicKey silc_signed_payload_get_public_key(SilcSignedPayload sig);
503 * Returns the public key from the SILC_MESSAGE_FLAG_SIGNED Payload
504 * or NULL if it does not include public key. The caller must free
505 * the returned public key.
508 SilcPublicKey silc_signed_payload_get_public_key(SilcSignedPayload sig);