5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2005 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* silcskr/SILC Key Repository
26 * SILC Key Repository is thread safe. Same key repository context can be
27 * safely used in multi threaded environment.
34 /****s* silcskr/SilcSKRAPI/SilcSKR
38 * typedef struct SilcSKRObject *SilcSKR, SilcSKRStruct;
42 * This context is the actual SILC Key Repository and is allocated
43 * by silc_skr_alloc (or initialized by silc_skr_init) and given as
44 * attribute to all silc_skr_* functions. It is freed by the
45 * silc_skr_free (or uninitialized with silc_skr_uninit) function.
48 typedef struct SilcSKRObject *SilcSKR, SilcSKRStruct;
50 /****s* silcskr/SilcSKRAPI/SilcSKRFind
54 * typedef struct SilcSKRFindStruct *SilcSKRFind
58 * This context contains the search constraints used find keys from the
59 * key repository. It is allocated by silc_skr_find_alloc and freed
60 * by silc_skr_find_free. The context is given as argument to all
61 * silc_skr_find* functions.
64 typedef struct SilcSKRFindStruct *SilcSKRFind;
66 /****d* silcskr/SilcSKRAPI/SilcSKRKeyUsage
70 * typedef enum { ... } SilcSKRKeyUsage;
74 * Indicates the usage of the key. Keys can be added for different
75 * reasons and for different purpose to the repository. SilcSKRKeyUsage
76 * indicates what for the key exists in the repository. The default
77 * usage is SILC_SKR_USAGE_ANY and allows any kind of usage for the key.
78 * If the usage should be limited then specific usage bitmask can be
79 * specified when adding the key. When searching keys from the
80 * repository at least one of the key usage bits must be found in order
86 SILC_SKR_USAGE_ANY = 0x0000, /* Any usage */
87 SILC_SKR_USAGE_AUTH = 0x0001, /* Signatures/verification */
88 SILC_SKR_USAGE_ENC = 0x0002, /* Encryption/decryption */
89 SILC_SKR_USAGE_KEY_AGREEMENT = 0x0004, /* Key agreement protocol */
90 SILC_SKR_USAGE_IDENTIFICATION = 0x0008, /* Identifying key owner */
94 /****s* silcskr/SilcSKRAPI/SilcSKRKey
98 * typedef struct SilcSKRKeyStruct { ... } *SilcSKRKey
102 * This context holds the public key cryptosystem key type and the key
103 * context that has been saved in the key repository. This context is
104 * returned in the SilcSKRFindCallback list. Each entry in the list is
107 * The key context saved in SilcSKRKey is based on the PKCS type and
108 * caller can explicitly type cast the key to correct type based on the
114 typedef struct SilcSKRKeyStruct {
115 SilcSKRKeyUsage usage; /* Key usage */
116 SilcPKCSType pk_type; /* PKCS type */
117 void *key; /* SILC_PKCS_SILC: SilcPublicKey */
118 void *key_context; /* Optional key specific context */
122 /****d* silcskr/SilcSKRAPI/SilcSKRStatus
126 * typedef enum { ... } SilcSKRStatus;
130 * Indicates the status of the key repository procedures. This is
131 * returned to SilcSKRFindCallback function to indicate the status
132 * of the finding. This is a bitmask, and more than one status may
133 * be set at one time.
135 * If there are no errors only SILC_SKR_OK is set. If error occurred
136 * then at least SILC_SKR_ERROR is set, and possibly other error
142 SILC_SKR_OK = 0x00000001, /* All is Ok */
143 SILC_SKR_ERROR = 0x00000002, /* Generic error status */
144 SILC_SKR_ALREADY_EXIST = 0x00000004, /* Key already exist */
145 SILC_SKR_NOT_FOUND = 0x00000008, /* No keys were found */
146 SILC_SKR_NO_MEMORY = 0x00000010, /* System out of memory */
147 SILC_SKR_UNSUPPORTED_TYPE = 0x00000020, /* Unsupported PKCS type */
151 /****f* silcskr/SilcSKRAPI/SilcSKRFindCallback
155 * typedef void (*SilcSKRFindCallback)(SilcSKR skr, SilcSKRFind find,
156 * SilcSKRStatus status,
157 * SilcDList keys, void *context);
161 * Callback that is given as argument to silc_skr_find and other find
162 * functions. Returns the results of the finding. If keys were found
163 * the `keys' is non-NULL and receiver must free it with silc_dlist_uninit.
164 * Each entry in the `keys' is SilcSKRKey context. The list `keys' is
165 * already at start so calling silc_dlist_start is not necessary when
166 * traversing the list from the start. If the `find' is non-NULL it must
167 * be freed with silc_skr_find_free.
170 typedef void (*SilcSKRFindCallback)(SilcSKR skr, SilcSKRFind find,
171 SilcSKRStatus status,
172 SilcDList keys, void *context);
174 /****f* silcskr/SilcSKRAPI/silc_skr_alloc
178 * SilcSKR silc_skr_alloc(SilcSchedule scheduler);
182 * Allocates key repository context.
185 SilcSKR silc_skr_alloc(SilcSchedule scheduler);
187 /****f* silcskr/SilcSKRAPI/silc_skr_free
191 * void silc_skr_free(SilcSKR skr);
195 * Free's the key repository context `skr' and all resources in it.
198 void silc_skr_free(SilcSKR skr);
200 /****f* silcskr/SilcSKRAPI/silc_skr_init
204 * SilcBool silc_skr_init(SilcSKR skr, SilcSchedule scheduler);
208 * Initializes a pre-allocated SilcSKR context. This function is
209 * equivalent to silc_skr_alloc but takes pre-allocated context as
210 * argument. Returns FALSE if initialization failed.
213 SilcBool silc_skr_init(SilcSKR skr, SilcSchedule scheduler);
215 /****f* silcskr/SilcSKRAPI/silc_skr_uninit
219 * void silc_skr_uninit(SilcSKR skr);
223 * Uninitializes a pre-allocated SilcSKR context. Use this function if
224 * you called silc_skr_init.
227 void silc_skr_uninit(SilcSKR skr);
229 /****f* silcskr/SilcSKRAPI/silc_skr_add_public_key
233 * SilcSKRStatus silc_skr_add_public_key(SilcSKR skr,
234 * SilcPublicKey public_key,
235 * SilcSKRKeyUsage usage,
236 * void *key_context);
240 * Add a public key to repository. The repository will steal `public_key'
241 * and caller must not free it. The `key_context' is optional key specific
242 * context that will be saved in the repository with the key, and can be
243 * retrieved with the key. Public key can be added only once to the
244 * repository. To add same key more than once to repository different
245 * `key_context' must be used each time.
247 * Returns SILC_SKR_OK if the key was added successfully, and error
248 * status if key could not be added, or has been added already.
252 * // Add a key to repository
253 * if (silc_skr_add_public_key(repository, public_key,
254 * SILC_SKR_USAGW_ANY, NULL) != SILC_SKR_OK)
258 SilcSKRStatus silc_skr_add_public_key(SilcSKR skr,
259 SilcPublicKey public_key,
260 SilcSKRKeyUsage usage,
263 /****f* silcskr/SilcSKRAPI/silc_skr_add_public_key_simple
267 * SilcSKRStatus silc_skr_add_public_key_simple(SilcSKR skr,
268 * SilcPublicKey public_key,
269 * SilcSKRKeyUsage usage,
270 * void *key_context);
274 * Same as silc_skr_add_public_key but adds only the public key, usage
275 * bits and key context. The key cannot be found with any other search
276 * constraint except setting the public key, usage bits and/or key
277 * context as search constraint. This function can be used to add the
278 * key with as little memory as possible to the repository, and makes
279 * it a good way to cheaply store large amounts of public keys.
281 * Returns SILC_SKR_OK if the key was added successfully, and error
282 * status if key could not be added, or has been added already.
285 SilcSKRStatus silc_skr_add_public_key_simple(SilcSKR skr,
286 SilcPublicKey public_key,
287 SilcSKRKeyUsage usage,
290 /****f* silcskr/SilcSKRAPI/silc_skr_find_alloc
294 * SilcSKRFind silc_skr_find_alloc(void);
298 * Allocates SilcSKRFind context that will hold search constraints used
299 * to find specific keys from the repository. Caller must free the
300 * context by calling silc_skr_find_free.
303 SilcSKRFind silc_skr_find_alloc(void);
305 /****f* silcskr/SilcSKRAPI/silc_skr_find_free
309 * void silc_skr_find_free(SilcSKRFind find);
313 * Free's the search constraints context `find' and all resources in it.
316 void silc_skr_find_free(SilcSKRFind find);
318 /****f* silcskr/SilcSKRAPI/silc_skr_find_add_pkcs_type
322 * SilcBool silc_skr_find_add_pkcs_type(SilcSKRFind find,
323 * SilcPKCSType type);
327 * Sets public key cryptosystem type as search constraint. Will search
328 * only for the specific type of key(s).
331 SilcBool silc_skr_find_set_pkcs_type(SilcSKRFind find, SilcPKCSType type);
333 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_username
337 * SilcBool silc_skr_find_set_username(SilcSKRFind find,
338 * const char *username);
342 * Sets username as search constraint. This specific username must be
343 * present in the key.
345 * This may be used with SILC_PKCS_SILC PKCS type only.
348 SilcBool silc_skr_find_set_username(SilcSKRFind find, const char *username);
350 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_host
354 * SilcBool silc_skr_find_set_host(SilcSKRFind find,
359 * Sets host as search constraint. This specific host must be
360 * present in the key. The `host' may be a hostname or IP address.
362 * This may be used with SILC_PKCS_SILC PKCS type only.
365 SilcBool silc_skr_find_set_host(SilcSKRFind find, const char *host);
367 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_realname
371 * SilcBool silc_skr_find_set_realname(SilcSKRFind find,
372 * const char *realname);
376 * Sets real name as search constraint. This specific name must be
377 * present in the key.
379 * This may be used with SILC_PKCS_SILC PKCS type only.
382 SilcBool silc_skr_find_set_realname(SilcSKRFind find, const char *realname);
384 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_email
388 * SilcBool silc_skr_find_set_email(SilcSKRFind find,
389 * const char *email);
393 * Sets email address as search constraint. This specific address must be
394 * present in the key.
396 * This may be used with SILC_PKCS_SILC PKCS type only.
399 SilcBool silc_skr_find_set_email(SilcSKRFind find, const char *email);
401 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_org
405 * SilcBool silc_skr_find_set_org(SilcSKRFind find,
406 * const char *email);
410 * Sets organization as search constraint. This specific organization
411 * must be present in the key.
413 * This may be used with SILC_PKCS_SILC PKCS type only.
416 SilcBool silc_skr_find_set_org(SilcSKRFind find, const char *org);
418 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_country
422 * SilcBool silc_skr_find_set_country(SilcSKRFind find,
423 * const char *email);
427 * Sets country as search constraint. This specific country must be
428 * present in the key.
430 * This may be used with SILC_PKCS_SILC PKCS type only.
433 SilcBool silc_skr_find_set_country(SilcSKRFind find, const char *country);
435 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_public_key
439 * SilcBool silc_skr_find_set_public_key(SilcSKRFind find,
440 * SilcPublicKey public_key);
444 * Sets public key as search constraint. This specific key must be
445 * present in the key.
448 SilcBool silc_skr_find_set_public_key(SilcSKRFind find,
449 SilcPublicKey public_key);
451 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_public_key
455 * SilcBool silc_skr_find_set_context(SilcSKRFind find, void *context);
459 * Sets public key specific context as search constraint. This specific
460 * context must be associated with the key. This is the context that
461 * was given as argument when adding the key to repository.
464 SilcBool silc_skr_find_set_context(SilcSKRFind find, void *context);
466 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_usage
470 * SilcBool silc_skr_find_set_usage(SilcSKRFind find,
471 * SilcSKRKeyUsage usage);
475 * Sets key usage as search constraint. At least one of the key usage
476 * bits must be present in the key. This search constraint cannot be
477 * used alone to search keys. At least one other search constraint
481 SilcBool silc_skr_find_set_usage(SilcSKRFind find, SilcSKRKeyUsage usage);
483 /****f* silcskr/SilcSKRAPI/silc_skr_find
487 * SilcAsyncOperation silc_skr_find(SilcSKR skr, SilcSKRFind find,
488 * SilcSKRFindCallback callback,
489 * void *callback_context);
493 * Finds key(s) from key repository `skr' by the search constraints
494 * `find'. As the finding procedure may be asynchronous this returns
495 * SilcAsyncOperation that may be used to control (like abort) the
496 * operation. The `callback' with `callback_context' will be called
497 * to return found keys. If this returns NULL, operation cannot be
498 * controlled, however it is not an error.
501 SilcAsyncOperation silc_skr_find(SilcSKR skr, SilcSKRFind find,
502 SilcSKRFindCallback callback,
503 void *callback_context);
505 /****f* silcskr/SilcSKRAPI/silc_skr_find_silc
509 * SilcAsyncOperation silc_skr_find_silc(SilcSKR skr,
510 * SilcPublicKey public_key,
511 * SilcSKRFindCallback callback,
512 * void *callback_context);
516 * A helper function that can be used to find specificly SILC style
517 * public keys from the repository. This returns found key(s) by
518 * the `public_key'. As the finding procedure may be asynchronous
519 * this returns SilcAsyncOperation that may be used to control (like
520 * abort) the operation. The `callback' with `callback_context' will
521 * be called to return found keys. If this returns NULL, operation
522 * cannot be controlled, however it is not an error.
525 SilcAsyncOperation silc_skr_find_silc(SilcSKR skr,
526 SilcPublicKey public_key,
527 SilcSKRFindCallback callback,
528 void *callback_context);
530 #include "silcskr_i.h"
532 #endif /* SILCSKR_H */