1 /****h* silccore/silcauth.h
9 * Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
11 * Copyright (C) 2001 Pekka Riikonen
13 * This program is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License as published by
15 * the Free Software Foundation; either version 2 of the License, or
16 * (at your option) any later version.
18 * This program is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU General Public License for more details.
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;
49 * This context is the actual Authentication Payload and is allocated
50 * by silc_auth_payload_parse and given as argument usually to all
51 * silc_auth_payload_* functions. It is freed by silc_auth_payload_free
55 typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
57 /****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload
61 * typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
65 * This context is the actual Key Agreement Payload and is allocated
66 * by silc_key_agreement_payload_parse and given as argument usually to all
67 * silc_key_agreement_* functions. It is freed by the function
68 * silc_key_agreement_payload_free.
71 typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
73 /****d* silccore/SilcAuthAPI/SilcAuthMethod
77 * typedef uint16 SilcAuthMethod;
81 * Authentication method type definition, the authentication methods
82 * and the authentication status'. The status defines are used by
83 * all authentication protocols in the SILC.
87 typedef uint16 SilcAuthMethod;
89 #define SILC_AUTH_NONE 0 /* No authentication */
90 #define SILC_AUTH_PASSWORD 1 /* Passphrase authentication */
91 #define SILC_AUTH_PUBLIC_KEY 2 /* Public key authentication */
93 /* Authentication protocol status message (used by all authentication
94 protocols in the SILC). */
95 #define SILC_AUTH_OK 0
96 #define SILC_AUTH_FAILED 1
101 /****f* silccore/SilcAuthAPI/silc_auth_payload_parse
105 * SilcAuthPayload silc_auth_payload_parse(unsigned char *data,
110 * Parses and returns Authentication Payload. The `data' and the
111 * `data_len' are the raw payload buffer.
114 SilcAuthPayload silc_auth_payload_parse(unsigned char *data,
117 /****f* silccore/SilcAuthAPI/silc_auth_payload_encode
121 * SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
122 * unsigned char *random_data,
124 * unsigned char *auth_data,
129 * Encodes authentication payload into buffer and returns it.
130 * The `random_data' is provided only if doing public key authentication.
131 * The `auth_data' is the actual authentication data.
134 SilcBuffer silc_auth_payload_encode(SilcAuthMethod method,
135 unsigned char *random_data,
137 unsigned char *auth_data,
140 /****f* silccore/SilcAuthAPI/silc_auth_payload_free
144 * void silc_auth_payload_free(SilcAuthPayload payload);
148 * Frees authentication payload and all data in it.
151 void silc_auth_payload_free(SilcAuthPayload payload);
153 /****f* silccore/SilcAuthAPI/silc_auth_get_method
157 * SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
161 * Get authentication method.
164 SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
166 /****f* silccore/SilcAuthAPI/silc_auth_get_data
170 * unsigned char *silc_auth_get_data(SilcAuthPayload payload,
175 * Get the authentication data. The caller must not free the data.
178 unsigned char *silc_auth_get_data(SilcAuthPayload payload,
181 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate
185 * SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
186 * SilcPrivateKey private_key,
188 * void *id, SilcIdType type);
192 * Generates Authentication Payload with authentication data. This is used
193 * to do public key based authentication. This generates the random data
194 * and the actual authentication data. Returns NULL on error and the
195 * encoded Authentication Payload on success.
198 SilcBuffer silc_auth_public_key_auth_generate(SilcPublicKey public_key,
199 SilcPrivateKey private_key,
201 void *id, SilcIdType type);
203 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify
207 * int silc_auth_public_key_auth_verify(SilcAuthPayload payload,
208 * SilcPublicKey public_key,
210 * void *id, SilcIdType type);
214 * Verifies the authentication data. Returns TRUE if authentication was
218 int silc_auth_public_key_auth_verify(SilcAuthPayload payload,
219 SilcPublicKey public_key, SilcHash hash,
220 void *id, SilcIdType type);
222 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data
226 * int silc_auth_public_key_auth_verify_data(SilcBuffer payload,
227 * SilcPublicKey public_key,
229 * void *id, SilcIdType type);
233 * Same as silc_auth_public_key_auth_verify but the payload has not
234 * been parsed yet. This will parse it. Returns TRUE if authentication
238 int silc_auth_public_key_auth_verify_data(SilcBuffer payload,
239 SilcPublicKey public_key,
241 void *id, SilcIdType type);
243 /****f* silccore/SilcAuthAPI/silc_auth_verify
247 * int silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
248 * void *auth_data, uint32 auth_data_len,
249 * SilcHash hash, void *id, SilcIdType type);
253 * Verifies the authentication data directly from the Authentication
254 * Payload. Supports all authentication methods. If the authentication
255 * method is passphrase based then the `auth_data' and `auth_data_len'
256 * are the passphrase and its length. If the method is public key
257 * authentication then the `auth_data' is the SilcPublicKey and the
258 * `auth_data_len' is ignored.
261 int silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
262 void *auth_data, uint32 auth_data_len,
263 SilcHash hash, void *id, SilcIdType type);
265 /****f* silccore/SilcAuthAPI/silc_auth_verify_data
269 * int silc_auth_verify_data(unsigned char *payload, uint32 payload_len,
270 * SilcAuthMethod auth_method, void *auth_data,
271 * uint32 auth_data_len, SilcHash hash,
272 * void *id, SilcIdType type);
276 * Same as silc_auth_verify but the payload has not been parsed yet.
277 * Verifies the authentication data directly from the Authentication
278 * Payload. Supports all authentication methods. If the authentication
279 * method is passphrase based then the `auth_data' and `auth_data_len'
280 * are the passphrase and its length. If the method is public key
281 * authentication then the `auth_data' is the SilcPublicKey and the
282 * `auth_data_len' is ignored.
285 int silc_auth_verify_data(unsigned char *payload, uint32 payload_len,
286 SilcAuthMethod auth_method, void *auth_data,
287 uint32 auth_data_len, SilcHash hash,
288 void *id, SilcIdType type);
290 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse
294 * SilcKeyAgreementPayload
295 * silc_key_agreement_payload_parse(SilcBuffer buffer);
299 * Parses and returns an allocated Key Agreement payload.
302 SilcKeyAgreementPayload silc_key_agreement_payload_parse(SilcBuffer buffer);
304 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode
308 * SilcBuffer silc_key_agreement_payload_encode(char *hostname,
313 * Encodes the Key Agreement protocol and returns the encoded buffer
316 SilcBuffer silc_key_agreement_payload_encode(char *hostname,
319 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free
323 * void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
327 * Frees the Key Agreement protocol and all data in it.
330 void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
332 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_hostname
336 * char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
340 * Returns the hostname in the payload. Caller must not free it.
341 * The hostname is the host that is able to accept key negotiation
342 * using the SILC Key Exchange protocol.
345 char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
347 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_port
351 * uint32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
355 * Returns the port in the payload. The port is the port on the
356 * host returned by silc_key_agreement_get_hostname that is running
357 * the SILC Key Exchange protocol.
360 uint32 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);