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/SilcAuthAPI
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 uint16 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 uint16 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(unsigned char *data,
111 * Parses and returns Authentication Payload. The `data' and the
112 * `data_len' are the raw payload buffer.
115 SilcAuthPayload silc_auth_payload_parse(unsigned char *data,
118 /****f* silccore/SilcAuthAPI/silc_auth_payload_encode
122 * SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
123 * unsigned char *random_data,
125 * unsigned char *auth_data,
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.
135 SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
136 unsigned char *random_data,
138 unsigned char *auth_data,
141 /****f* silccore/SilcAuthAPI/silc_auth_payload_free
145 * void silc_auth_payload_free(SilcAuthPayload payload);
149 * Frees authentication payload and all data in it.
152 void silc_auth_payload_free(SilcAuthPayload payload);
154 /****f* silccore/SilcAuthAPI/silc_auth_get_method
158 * SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
162 * Get authentication method.
165 SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
167 /****f* silccore/SilcAuthAPI/silc_auth_get_data
171 * unsigned char *silc_auth_get_data(SilcAuthPayload payload,
176 * Get the authentication data. The caller must not free the data.
179 unsigned char *silc_auth_get_data(SilcAuthPayload payload,
182 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate
186 * SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
187 * SilcPrivateKey private_key,
189 * void *id, SilcIdType type);
193 * Generates Authentication Payload with authentication data. This is used
194 * to do public key based authentication. This generates the random data
195 * and the actual authentication data. Returns NULL on error and the
196 * encoded Authentication Payload on success.
199 SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
200 SilcPrivateKey private_key,
202 void *id, SilcIdType type);
204 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify
208 * int silc_auth_public_key_auth_verify(SilcAuthPayload payload,
209 * SilcPublicKey public_key,
211 * void *id, SilcIdType type);
215 * Verifies the authentication data. Returns TRUE if authentication was
219 int silc_auth_public_key_auth_verify(SilcAuthPayload payload,
220 SilcPublicKey public_key, SilcHash hash,
221 void *id, SilcIdType type);
223 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data
227 * int silc_auth_public_key_auth_verify_data(SilcBuffer payload,
228 * SilcPublicKey public_key,
230 * void *id, SilcIdType type);
234 * Same as silc_auth_public_key_auth_verify but the payload has not
235 * been parsed yet. This will parse it. Returns TRUE if authentication
239 int silc_auth_public_key_auth_verify_data(SilcBuffer payload,
240 SilcPublicKey public_key,
242 void *id, SilcIdType type);
244 /****f* silccore/SilcAuthAPI/silc_auth_verify
248 * int silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
249 * void *auth_data, uint32 auth_data_len,
250 * SilcHash hash, void *id, SilcIdType type);
254 * Verifies the authentication data directly from the Authentication
255 * Payload. Supports all authentication methods. If the authentication
256 * method is passphrase based then the `auth_data' and `auth_data_len'
257 * are the passphrase and its length. If the method is public key
258 * authentication then the `auth_data' is the SilcPublicKey and the
259 * `auth_data_len' is ignored.
262 int silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
263 void *auth_data, uint32 auth_data_len,
264 SilcHash hash, void *id, SilcIdType type);
266 /****f* silccore/SilcAuthAPI/silc_auth_verify_data
270 * int silc_auth_verify_data(unsigned char *payload, uint32 payload_len,
271 * SilcAuthMethod auth_method, void *auth_data,
272 * uint32 auth_data_len, SilcHash hash,
273 * void *id, SilcIdType type);
277 * Same as silc_auth_verify but the payload has not been parsed yet.
278 * Verifies the authentication data directly from the Authentication
279 * Payload. Supports all authentication methods. If the authentication
280 * method is passphrase based then the `auth_data' and `auth_data_len'
281 * are the passphrase and its length. If the method is public key
282 * authentication then the `auth_data' is the SilcPublicKey and the
283 * `auth_data_len' is ignored.
286 int silc_auth_verify_data(unsigned char *payload, uint32 payload_len,
287 SilcAuthMethod auth_method, void *auth_data,
288 uint32 auth_data_len, SilcHash hash,
289 void *id, SilcIdType type);
291 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse
295 * SilcKeyAgreementPayload
296 * silc_key_agreement_payload_parse(SilcBuffer buffer);
300 * Parses and returns an allocated Key Agreement payload.
303 SilcKeyAgreementPayload silc_key_agreement_payload_parse(SilcBuffer buffer);
305 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode
309 * SilcBuffer silc_key_agreement_payload_encode(char *hostname,
314 * Encodes the Key Agreement protocol and returns the encoded buffer
317 SilcBuffer silc_key_agreement_payload_encode(char *hostname,
320 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free
324 * void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
328 * Frees the Key Agreement protocol and all data in it.
331 void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
333 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_hostname
337 * char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
341 * Returns the hostname in the payload. Caller must not free it.
342 * The hostname is the host that is able to accept key negotiation
343 * using the SILC Key Exchange protocol.
346 char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
348 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_port
352 * uint32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
356 * Returns the port in the payload. The port is the port on the
357 * host returned by silc_key_agreement_get_hostname that is running
358 * the SILC Key Exchange protocol.
361 uint32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);