1 /*
2
3 silcauth.h
4
5 Author: Pekka Riikonen <priikone@silcnet.org>
6
7 Copyright (C) 2001 - 2007 Pekka Riikonen
8
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.
12
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.
17
18 */
19
20 /****h* silccore/SILC Authentication Interface
21 *
22 * DESCRIPTION
23 *
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
29 * authentication.
30 *
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
33 * in the network.
34 *
35 ***/
36
37 #ifndef SILCAUTH_H
38 #define SILCAUTH_H
39
40 /****d* silccore/SilcAuthAPI/SilcAuthMethod
41 *
42 * NAME
43 *
44 * typedef SilcUInt16 SilcAuthMethod;
45 *
46 * DESCRIPTION
47 *
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.
51 *
52 * SOURCE
53 */
54 typedef SilcUInt16 SilcAuthMethod;
55
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 */
59
60 /****d* silccore/SilcAuthAPI/SilcAuthResult
61 *
62 * NAME
63 *
64 * typedef SilcUInt32 SilcAuthResult;
65 *
66 * DESCRIPTION
67 *
68 * Authentication protocol status. Used by all authentication protocols
69 * in SILC.
70 *
71 * SOURCE
72 */
73 typedef SilcUInt32 SilcAuthResult;
74
75 #define SILC_AUTH_OK 0 /* Authentication successful */
76 #define SILC_AUTH_FAILED 1 /* Authentication failed */
77 /***/
78
79 /****s* silccore/SilcAuthAPI/SilcAuthPayload
80 *
81 * NAME
82 *
83 * typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
84 *
85 *
86 * DESCRIPTION
87 *
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
91 * function.
92 *
93 ***/
94 typedef struct SilcAuthPayloadStruct *SilcAuthPayload;
95
96 /****f* silccore/SilcAuthAPI/silc_auth_payload_parse
97 *
98 * SYNOPSIS
99 *
100 * SilcAuthPayload silc_auth_payload_parse(SilcStack stack,
101 * const unsigned char *data,
102 * SilcUInt32 data_len);
103 *
104 * DESCRIPTION
105 *
106 * Parses and returns Authentication Payload. The `data' and the
107 * `data_len' are the raw payload buffer. If `stack' is non-NULL the
108 * memory is allcoated from `stack'.
109 *
110 ***/
111 SilcAuthPayload silc_auth_payload_parse(SilcStack stack,
112 const unsigned char *data,
113 SilcUInt32 data_len);
114
115 /****f* silccore/SilcAuthAPI/silc_auth_payload_encode
116 *
117 * SYNOPSIS
118 *
119 * SilcBuffer silc_auth_payload_encode(SilcStack stack,
120 * SilcAuthMethod method,
121 * const unsigned char *random_data,
122 * SilcUInt16 random_len,
123 * const unsigned char *auth_data,
124 * SilcUInt16 auth_len);
125 *
126 * DESCRIPTION
127 *
128 * Encodes authentication payload into buffer and returns it.
129 * The `random_data' is provided only if doing public key authentication.
130 * The `auth_data' is the actual authentication data. If the
131 * `method' is SILC_AUTH_PASSWORD the passphase in `auth_data' sent as
132 * argument SHOULD be UTF-8 encoded, if not library will attempt to
133 * encode it.
134 *
135 * If `stack' is non-NULL the returned buffer is allocated from `stack'.
136 * This call consumes the `stack' so caller should push the stack before
137 * calling this function and then later pop it.
138 *
139 ***/
140 SilcBuffer silc_auth_payload_encode(SilcStack stack,
141 SilcAuthMethod method,
142 const unsigned char *random_data,
143 SilcUInt16 random_len,
144 const unsigned char *auth_data,
145 SilcUInt16 auth_len);
146
147 /****f* silccore/SilcAuthAPI/silc_auth_payload_free
148 *
149 * SYNOPSIS
150 *
151 * void silc_auth_payload_free(SilcAuthPayload payload);
152 *
153 * DESCRIPTION
154 *
155 * Frees authentication payload and all data in it.
156 *
157 ***/
158 void silc_auth_payload_free(SilcAuthPayload payload);
159
160 /****f* silccore/SilcAuthAPI/silc_auth_get_method
161 *
162 * SYNOPSIS
163 *
164 * SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
165 *
166 * DESCRIPTION
167 *
168 * Get authentication method.
169 *
170 ***/
171 SilcAuthMethod silc_auth_get_method(SilcAuthPayload payload);
172
173 /****f* silccore/SilcAuthAPI/silc_auth_get_public_data
174 *
175 * SYNOPSIS
176 *
177 * unsigned char *silc_auth_get_public_data(SilcAuthPayload payload,
178 * SilcUInt32 *pubdata_len);
179 *
180 * DESCRIPTION
181 *
182 * Returns the public data (usually random data) from the payload.
183 * Caller must not free the returned data.
184 *
185 ***/
186 unsigned char *silc_auth_get_public_data(SilcAuthPayload payload,
187 SilcUInt32 *pubdata_len);
188
189 /****f* silccore/SilcAuthAPI/silc_auth_get_data
190 *
191 * SYNOPSIS
192 *
193 * unsigned char *silc_auth_get_data(SilcAuthPayload payload,
194 * SilcUInt32 *auth_len);
195 *
196 * DESCRIPTION
197 *
198 * Get the authentication data. The caller must not free the data. If
199 * the authentication method is passphrase, then the returned string
200 * is UTF-8 encoded passphrase.
201 *
202 ***/
203 unsigned char *silc_auth_get_data(SilcAuthPayload payload,
204 SilcUInt32 *auth_len);
205
206 /****f* silccore/SilcAuthAPI/SilcAuthGenerated
207 *
208 * SYNOPSIS
209 *
210 * typedef void (*SilcAuthGenerated)(const SilcBuffer data, void *context);
211 *
212 * DESCRIPTION
213 *
214 * Callback of this type is given as argument to
215 * silc_auth_public_key_auth_generate and
216 * silc_auth_public_key_auth_generate_wpub to deliver the generated
217 * Authentication Payload. If `data' is NULL the generating failed.
218 *
219 ***/
220 typedef void (*SilcAuthGenerated)(const SilcBuffer data, void *context);
221
222 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate
223 *
224 * SYNOPSIS
225 *
226 * SilcAsyncOperation
227 * silc_auth_public_key_auth_generate(SilcPublicKey public_key,
228 * SilcPrivateKey private_key,
229 * SilcRng rng,
230 * SilcHash hash,
231 * const void *id,
232 * SilcIdType type,
233 * SilcAuthGenerated generated,
234 * void *context);
235 *
236 * DESCRIPTION
237 *
238 * Generates Authentication Payload with authentication data. This is used
239 * to do public key based authentication. This generates the random data
240 * and the actual authentication data.
241 *
242 * The `private_key' is used to sign the payload. The `public_key', the
243 * and the `id' is encoded in the payload and signed. If the `rng' is
244 * NULL then global RNG is used, if non-NULL then `rng' is used as
245 * random number generator. Also random number is encoded in the
246 * payload before signing it with `private_key'.
247 *
248 * The `generated' is called to deliver the generated Authentication
249 * Payload.
250 *
251 ***/
252 SilcAsyncOperation
253 silc_auth_public_key_auth_generate(SilcPublicKey public_key,
254 SilcPrivateKey private_key,
255 SilcRng rng, SilcHash hash,
256 const void *id, SilcIdType type,
257 SilcAuthGenerated generated,
258 void *context);
259
260 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_generate_wpub
261 *
262 * SYNOPSIS
263 *
264 * SilcAsyncOperation
265 * silc_auth_public_key_auth_generate_wpub(SilcPublicKey public_key,
266 * SilcPrivateKey private_key,
267 * const unsigned char *pubdata,
268 * SilcUInt32 pubdata_len,
269 * SilcHash hash,
270 * SilcRng rng,
271 * const void *id,
272 * SilcIdType type,
273 * SilcAuthGenerated generated,
274 * void *context);
275 *
276 * DESCRIPTION
277 *
278 * Same as silc_auth_public_key_auth_generate but takes the public data
279 * (usually random data) as argument. This function can be used when
280 * the public data must be something else than purely random or its
281 * structure mut be set before signing.
282 *
283 * The `generated' is called to deliver the generated Authentication
284 * Payload.
285 *
286 ***/
287 SilcAsyncOperation
288 silc_auth_public_key_auth_generate_wpub(SilcPublicKey public_key,
289 SilcPrivateKey private_key,
290 const unsigned char *pubdata,
291 SilcUInt32 pubdata_len,
292 SilcHash hash,
293 SilcRng rng,
294 const void *id, SilcIdType type,
295 SilcAuthGenerated generated,
296 void *context);
297
298 /****f* silccore/SilcAuthAPI/SilcAuthResult
299 *
300 * SYNOPSIS
301 *
302 * typedef void (*SilcAuthResult)(SilcBool success, void *context);
303 *
304 * DESCRIPTION
305 *
306 * Callback of this type is given as argument to silc_auth_verify,
307 * silc_auth_verify_data, silc_auth_public_key_auth_verify and
308 * silc_auth_public_key_auth_verify_data to deliver the result of
309 * the authentication verification. If `success' is FALSE the
310 * authentication failed.
311 *
312 ***/
313 typedef void (*SilcAuthResultCb)(SilcBool success, void *context);
314
315 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify
316 *
317 * SYNOPSIS
318 *
319 * SilcAsyncOperation
320 * silc_auth_public_key_auth_verify(SilcAuthPayload payload,
321 * SilcPublicKey public_key,
322 * SilcHash hash,
323 * const void *id,
324 * SilcIdType type,
325 * SilcAuthResult result,
326 * void *context);
327 *
328 * DESCRIPTION
329 *
330 * Verifies the authentication data. Calls the `result' to deliver
331 * the result of the verification.
332 *
333 ***/
334 SilcAsyncOperation
335 silc_auth_public_key_auth_verify(SilcAuthPayload payload,
336 SilcPublicKey public_key,
337 SilcHash hash,
338 const void *id,
339 SilcIdType type,
340 SilcAuthResultCb result,
341 void *context);
342
343 /****f* silccore/SilcAuthAPI/silc_auth_public_key_auth_verify_data
344 *
345 * SYNOPSIS
346 *
347 * SilcAsyncOperation
348 * silc_auth_public_key_auth_verify_data(const unsigned char *payload,
349 * SilcUInt32 payload_len,
350 * SilcPublicKey public_key,
351 * SilcHash hash,
352 * const void *id,
353 * SilcIdType type,
354 * SilcAuthResult result,
355 * void *context);
356 *
357 * DESCRIPTION
358 *
359 * Same as silc_auth_public_key_auth_verify but the payload has not
360 * been parsed yet. This will parse it. Calls the `result' to deliver
361 * the result of the verification.
362 *
363 ***/
364 SilcAsyncOperation
365 silc_auth_public_key_auth_verify_data(const unsigned char *payload,
366 SilcUInt32 payload_len,
367 SilcPublicKey public_key,
368 SilcHash hash,
369 const void *id,
370 SilcIdType type,
371 SilcAuthResultCb result,
372 void *context);
373
374 /****f* silccore/SilcAuthAPI/silc_auth_verify
375 *
376 * SYNOPSIS
377 *
378 * SilcAsyncOperation
379 * silc_auth_verify(SilcAuthPayload payload,
380 * SilcAuthMethod auth_method,
381 * const void *auth_data,
382 * SilcUInt32 auth_data_len,
383 * SilcHash hash,
384 * const void *id, SilcIdType type,
385 * SilcAuthResult result, void *context);
386 *
387 * DESCRIPTION
388 *
389 * Verifies the authentication data directly from the Authentication
390 * Payload. Supports all authentication methods. If the authentication
391 * method is passphrase based then the `auth_data' and `auth_data_len'
392 * are the passphrase and its length. The passphrase MUST be UTF-8
393 * encoded. If the method is public key authentication then the
394 * `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
395 * Calls the `result' to deliver the result of the verification.
396 *
397 ***/
398 SilcAsyncOperation
399 silc_auth_verify(SilcAuthPayload payload, SilcAuthMethod auth_method,
400 const void *auth_data, SilcUInt32 auth_data_len,
401 SilcHash hash, const void *id, SilcIdType type,
402 SilcAuthResultCb result, void *context);
403
404 /****f* silccore/SilcAuthAPI/silc_auth_verify_data
405 *
406 * SYNOPSIS
407 *
408 * SilcAsyncOperation
409 * silc_auth_verify_data(const unsigned char *payload,
410 * SilcUInt32 payload_len,
411 * SilcAuthMethod auth_method,
412 * const void *auth_data,
413 * SilcUInt32 auth_data_len, SilcHash hash,
414 * const void *id, SilcIdType type,
415 * SilcAuthResult result, void *context);
416 *
417 * DESCRIPTION
418 *
419 * Same as silc_auth_verify but the payload has not been parsed yet.
420 * Verifies the authentication data directly from the Authentication
421 * Payload. Supports all authentication methods. If the authentication
422 * method is passphrase based then the `auth_data' and `auth_data_len'
423 * are the passphrase and its length. The passphrase MUST be UTF-8
424 * encoded. If the method is public key authentication then the
425 * `auth_data' is the SilcPublicKey and the `auth_data_len' is ignored.
426 * Calls the `result' to deliver the result of the verification.
427 *
428 ***/
429 SilcAsyncOperation
430 silc_auth_verify_data(const unsigned char *payload,
431 SilcUInt32 payload_len,
432 SilcAuthMethod auth_method,
433 const void *auth_data,
434 SilcUInt32 auth_data_len, SilcHash hash,
435 const void *id, SilcIdType type,
436 SilcAuthResultCb result, void *context);
437
438 /****s* silccore/SilcAuthAPI/SilcKeyAgreementPayload
439 *
440 * NAME
441 *
442 * typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
443 *
444 * DESCRIPTION
445 *
446 * This context is the actual Key Agreement Payload and is allocated
447 * by silc_key_agreement_payload_parse and given as argument usually to all
448 * silc_key_agreement_* functions. It is freed by the function
449 * silc_key_agreement_payload_free.
450 *
451 ***/
452 typedef struct SilcKeyAgreementPayloadStruct *SilcKeyAgreementPayload;
453
454 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_parse
455 *
456 * SYNOPSIS
457 *
458 * SilcKeyAgreementPayload
459 * silc_key_agreement_payload_parse(const unsigned char *payload,
460 * SilcUInt32 payload_len);
461 *
462 * DESCRIPTION
463 *
464 * Parses and returns an allocated Key Agreement payload.
465 *
466 ***/
467 SilcKeyAgreementPayload
468 silc_key_agreement_payload_parse(const unsigned char *payload,
469 SilcUInt32 payload_len);
470
471 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_encode
472 *
473 * SYNOPSIS
474 *
475 * SilcBuffer silc_key_agreement_payload_encode(char *hostname,
476 * SilcUInt16 protocol,
477 * SilcUInt16 port);
478 *
479 * DESCRIPTION
480 *
481 * Encodes the Key Agreement payload and returns the encoded buffer.
482 * The `protocol' is 0 for TCP and 1 for UDP.
483 *
484 ***/
485 SilcBuffer silc_key_agreement_payload_encode(const char *hostname,
486 SilcUInt16 protocol,
487 SilcUInt16 port);
488
489 /****f* silccore/SilcAuthAPI/silc_key_agreement_payload_free
490 *
491 * SYNOPSIS
492 *
493 * void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
494 *
495 * DESCRIPTION
496 *
497 * Frees the Key Agreement payload and all data in it.
498 *
499 ***/
500 void silc_key_agreement_payload_free(SilcKeyAgreementPayload payload);
501
502 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_hostname
503 *
504 * SYNOPSIS
505 *
506 * char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
507 *
508 * DESCRIPTION
509 *
510 * Returns the hostname in the payload. Caller must not free it.
511 * The hostname is the host that is able to accept key negotiation
512 * using the SILC Key Exchange protocol.
513 *
514 ***/
515 char *silc_key_agreement_get_hostname(SilcKeyAgreementPayload payload);
516
517 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_protocol
518 *
519 * SYNOPSIS
520 *
521 * SilcUInt16
522 * silc_key_agreement_get_protocol(SilcKeyAgreementPayload payload);
523 *
524 * DESCRIPTION
525 *
526 * Returns the protocol in the payload. The protocol is either TCP (0)
527 * or UDP (1).
528 *
529 ***/
530 SilcUInt16 silc_key_agreement_get_protocol(SilcKeyAgreementPayload payload);
531
532 /****f* silccore/SilcAuthAPI/silc_key_agreement_get_port
533 *
534 * SYNOPSIS
535 *
536 * SilcUInt16 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
537 *
538 * DESCRIPTION
539 *
540 * Returns the port in the payload. The port is the port on the
541 * host returned by silc_key_agreement_get_hostname that is running
542 * the SILC Key Exchange protocol.
543 *
544 ***/
545 SilcUInt16 silc_key_agreement_get_port(SilcKeyAgreementPayload payload);
546
547 #endif
548
This page was automatically generated by the LXR engine.
Free-text search provided by Glimpse