5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2005 - 2008 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/Key Manager and Repository
24 * SILC Key manager and repository is a generic public key and certificate
25 * manager which allows fast and versatile ways to store, retrieve and
26 * validate public keys and certificates.
28 * SILC Key Repository is thread safe. Same key repository context can be
29 * safely used in multi threaded environment.
36 /****s* silcskr/SilcSKR
40 * typedef struct SilcSKRObject *SilcSKR, SilcSKRStruct;
44 * This context is the actual SILC Key Repository and is allocated
45 * by silc_skr_alloc (or initialized by silc_skr_init) and given as
46 * attribute to all silc_skr_* functions. It is freed by the
47 * silc_skr_free (or uninitialized with silc_skr_uninit) function.
50 typedef struct SilcSKRObject *SilcSKR, SilcSKRStruct;
52 /****s* silcskr/SilcSKRFind
56 * typedef struct SilcSKRFindStruct *SilcSKRFind
60 * This context contains the search constraints used find keys from the
61 * key repository. It is allocated by silc_skr_find_alloc and freed
62 * by silc_skr_find_free. The context is given as argument to all
63 * silc_skr_find* functions.
66 typedef struct SilcSKRFindStruct *SilcSKRFind;
68 /****d* silcskr/SilcSKRKeyUsage
72 * typedef enum { ... } SilcSKRKeyUsage;
76 * Indicates the usage of the key. Keys can be added for different
77 * reasons and for different purpose to the repository. SilcSKRKeyUsage
78 * indicates for what reason the key exists in the repository. The default
79 * usage is SILC_SKR_USAGE_ANY and allows any kind of usage for the key.
80 * If the usage should be limited then specific usage bitmask can be
81 * specified when adding the key. When searching keys from the
82 * repository at least one of the key usage bits must be found in order
88 SILC_SKR_USAGE_ANY = 0x0000, /* Any usage */
89 SILC_SKR_USAGE_AUTH = 0x0001, /* Signatures/verification */
90 SILC_SKR_USAGE_ENC = 0x0002, /* Encryption/decryption */
91 SILC_SKR_USAGE_KEY_AGREEMENT = 0x0004, /* Key agreement protocol */
92 SILC_SKR_USAGE_IDENTIFICATION = 0x0008, /* Identifying key owner */
93 SILC_SKR_USAGE_SERVICE_AUTHORIZATION = 0x0010, /* Service authorization */
95 /* 0x0200 - 0x8000 reserved for private/application use. */
99 /****s* silcskr/SilcSKRKey
103 * typedef struct SilcSKRKeyStruct { ... } *SilcSKRKey;
107 * This context holds the public key, optional public key specific
108 * context and public key usage bits. This context is returned in
109 * the SilcSKRFindCallback list. Each entry in the list is SIlcSKRKey.
114 typedef struct SilcSKRKeyStruct {
115 SilcSKRKeyUsage usage; /* Key usage */
116 SilcPublicKey key; /* Public key */
117 void *key_context; /* Optional key specific context */
121 /****f* silcskr/SilcSKRFindCallback
125 * typedef void (*SilcSKRFindCallback)(SilcSKR skr, SilcSKRFind find,
126 * SilcResult status, SilcDList keys,
131 * Callback that is given as argument to silc_skr_find and other find
132 * functions. Returns the results of the finding. If keys were found
133 * the `keys' is non-NULL and receiver must free it with silc_dlist_uninit.
134 * Each entry in the `keys' is SilcSKRKey context. The list `keys' is
135 * already at start so calling silc_dlist_start is not necessary when
136 * traversing the list from the start. If the `find' is non-NULL it must
137 * be freed with silc_skr_find_free.
140 typedef void (*SilcSKRFindCallback)(SilcSKR skr, SilcSKRFind find,
141 SilcResult status, SilcDList keys,
144 /****f* silcskr/silc_skr_alloc
148 * SilcSKR silc_skr_alloc(void);
152 * Allocates key repository context.
155 SilcSKR silc_skr_alloc(void);
157 /****f* silcskr/silc_skr_free
161 * void silc_skr_free(SilcSKR skr);
165 * Free's the key repository context `skr' and all resources in it.
168 void silc_skr_free(SilcSKR skr);
170 /****f* silcskr/silc_skr_init
174 * SilcBool silc_skr_init(SilcSKR skr);
178 * Initializes a pre-allocated SilcSKR context. This function is
179 * equivalent to silc_skr_alloc but takes pre-allocated context as
180 * argument. Returns FALSE if initialization failed.
183 SilcBool silc_skr_init(SilcSKR skr);
185 /****f* silcskr/silc_skr_uninit
189 * void silc_skr_uninit(SilcSKR skr);
193 * Uninitializes a pre-allocated SilcSKR context. Use this function if
194 * you called silc_skr_init.
197 void silc_skr_uninit(SilcSKR skr);
199 /****f* silcskr/silc_skr_add_public_key
203 * SilcResult silc_skr_add_public_key(SilcSKR skr,
204 * SilcPublicKey public_key,
205 * SilcSKRKeyUsage usage,
207 * SilcSKRKey *return_key);
211 * Add a public key to repository. The repository will steal `public_key'
212 * and caller must not free it. The `key_context' is optional key specific
213 * context that will be saved in the repository with the key, and can be
214 * retrieved with the key. Public key can be added only once to the
215 * repository. To add same key more than once to repository different
216 * `key_context' must be used each time.
218 * Returns an entry of the added public key in the repository to the
219 * `return_key' pointer, if it is non-NULL. The returned entry remains
220 * valid as long as the public key is in the repository, however a
221 * reference may be taken with silc_skr_ref_public_key to assure the
222 * entry remains valid.
224 * Returns SILC_OK if the key was added successfully, and error
225 * status if key could not be added, or has been added already.
229 * // Add a key to repository
230 * if (silc_skr_add_public_key(repository, pubkey, SILC_SKR_USAGE_ANY,
231 * NULL, NULL) != SILC_OK)
235 SilcResult silc_skr_add_public_key(SilcSKR skr,
236 SilcPublicKey public_key,
237 SilcSKRKeyUsage usage,
239 SilcSKRKey *return_key);
241 /****f* silcskr/silc_skr_add_public_key_simple
245 * SilcResult silc_skr_add_public_key_simple(SilcSKR skr,
246 * SilcPublicKey public_key,
247 * SilcSKRKeyUsage usage,
249 * SilcSKRKey *return_key);
253 * Same as silc_skr_add_public_key but adds only the public key, usage
254 * bits and key context. The key cannot be found with any other search
255 * constraint except setting the public key, usage bits and/or key
256 * context as search constraint. This function can be used to add the
257 * key with as little memory as possible to the repository, and makes
258 * it a good way to cheaply store large amounts of public keys.
260 * Returns an entry of the added public key in the repository to the
261 * `return_key' pointer, if it is non-NULL. The returned entry remains
262 * valid as long as the public key is in the repository, however a
263 * reference may be taken with silc_skr_ref_public_key to assure the
264 * entry remains valid.
266 * Returns SILC_OK if the key was added successfully, and error
267 * status if key could not be added, or has been added already.
270 SilcResult silc_skr_add_public_key_simple(SilcSKR skr,
271 SilcPublicKey public_key,
272 SilcSKRKeyUsage usage,
274 SilcSKRKey *return_key);
276 /****f* silcskr/silc_skr_del_public_key
280 * SilcResult silc_skr_del_public_key(SilcSKR skr,
281 * SilcPublicKey public_key,
282 * void *key_context);
286 * Removes and destroyes the public key from the repository. The
287 * public_key will become invalid after this call returns.
289 * Returns SILC_OK if the key was deleted successfully, and error
290 * status if key could not be deleted, or has been deleted already.
293 SilcResult silc_skr_del_public_key(SilcSKR skr,
294 SilcPublicKey public_key,
297 /****f* silcskr/silc_skr_ref_public_key
301 * void silc_skr_ref_public_key(SilcSKR skr, SilcSKRKey key);
305 * Takes a reference of the public key added to repository indicated
306 * by `key'. The reference must be released by calling the function
307 * silc_skr_unref_public_key when it is not needed anymore.
310 void silc_skr_ref_public_key(SilcSKR skr, SilcSKRKey key);
312 /****f* silcskr/silc_skr_unref_public_key
316 * void silc_skr_unref_public_key(SilcSKR skr, SilcSKRKey key);
320 * Releases the reference of the public key added to the repository
321 * indicated by `key'. If the released reference is the last reference
322 * to the key it will become invalid after this function returns.
325 void silc_skr_unref_public_key(SilcSKR skr, SilcSKRKey key);
327 /****f* silcskr/silc_skr_find_alloc
331 * SilcSKRFind silc_skr_find_alloc(void);
335 * Allocates SilcSKRFind context that will hold search constraints used
336 * to find specific keys from the repository. Caller must free the
337 * context by calling silc_skr_find_free.
340 SilcSKRFind silc_skr_find_alloc(void);
342 /****f* silcskr/silc_skr_find_free
346 * void silc_skr_find_free(SilcSKRFind find);
350 * Free's the search constraints context `find' and all resources in it.
353 void silc_skr_find_free(SilcSKRFind find);
355 /****f* silcskr/silc_skr_find_add_pkcs_type
359 * SilcBool silc_skr_find_add_pkcs_type(SilcSKRFind find,
360 * SilcPKCSType type);
364 * Sets public key cryptosystem type as search constraint. Will search
365 * only for the specific type of key(s).
368 SilcBool silc_skr_find_set_pkcs_type(SilcSKRFind find, SilcPKCSType type);
370 /****f* silcskr/silc_skr_find_set_username
374 * SilcBool silc_skr_find_set_username(SilcSKRFind find,
375 * const char *username);
379 * Sets username as search constraint. This specific username must be
380 * present in the key.
382 * This may be used with SILC_PKCS_SILC PKCS type only.
385 SilcBool silc_skr_find_set_username(SilcSKRFind find, const char *username);
387 /****f* silcskr/silc_skr_find_set_host
391 * SilcBool silc_skr_find_set_host(SilcSKRFind find,
396 * Sets host as search constraint. This specific host must be
397 * present in the key. The `host' may be a hostname or IP address.
399 * This may be used with SILC_PKCS_SILC PKCS type only.
402 SilcBool silc_skr_find_set_host(SilcSKRFind find, const char *host);
404 /****f* silcskr/silc_skr_find_set_realname
408 * SilcBool silc_skr_find_set_realname(SilcSKRFind find,
409 * const char *realname);
413 * Sets real name as search constraint. This specific name must be
414 * present in the key.
416 * This may be used with SILC_PKCS_SILC PKCS type only.
419 SilcBool silc_skr_find_set_realname(SilcSKRFind find, const char *realname);
421 /****f* silcskr/silc_skr_find_set_email
425 * SilcBool silc_skr_find_set_email(SilcSKRFind find,
426 * const char *email);
430 * Sets email address (user FQDN) as search constraint. This specific
431 * address must be present in the key.
433 * This may be used with SILC_PKCS_SILC PKCS type only.
436 SilcBool silc_skr_find_set_email(SilcSKRFind find, const char *email);
438 /****f* silcskr/silc_skr_find_set_org
442 * SilcBool silc_skr_find_set_org(SilcSKRFind find,
443 * const char *email);
447 * Sets organization as search constraint. This specific organization
448 * must be present in the key.
450 * This may be used with SILC_PKCS_SILC PKCS type only.
453 SilcBool silc_skr_find_set_org(SilcSKRFind find, const char *org);
455 /****f* silcskr/silc_skr_find_set_country
459 * SilcBool silc_skr_find_set_country(SilcSKRFind find,
460 * const char *email);
464 * Sets country as search constraint. This specific country must be
465 * present in the key.
467 * This may be used with SILC_PKCS_SILC PKCS type only.
470 SilcBool silc_skr_find_set_country(SilcSKRFind find, const char *country);
472 /****f* silcskr/silc_skr_find_set_public_key
476 * SilcBool silc_skr_find_set_public_key(SilcSKRFind find,
477 * SilcPublicKey public_key);
481 * Sets public key as search constraint. This specific key must be
482 * present in the key.
485 SilcBool silc_skr_find_set_public_key(SilcSKRFind find,
486 SilcPublicKey public_key);
488 /****f* silcskr/silc_skr_find_set_context
492 * SilcBool silc_skr_find_set_context(SilcSKRFind find, void *context);
496 * Sets public key specific context as search constraint. This specific
497 * context must be associated with the key. This is the context that
498 * was given as argument when adding the key to repository.
501 SilcBool silc_skr_find_set_context(SilcSKRFind find, void *context);
503 /****f* silcskr/silc_skr_find_set_usage
507 * SilcBool silc_skr_find_set_usage(SilcSKRFind find,
508 * SilcSKRKeyUsage usage);
512 * Sets key usage as search constraint. At least one of the key usage
513 * bits must be present in the key. This search constraint cannot be
514 * used alone to search keys. At least one other search constraint
518 SilcBool silc_skr_find_set_usage(SilcSKRFind find, SilcSKRKeyUsage usage);
520 /****f* silcskr/silc_skr_find
524 * SilcAsyncOperation silc_skr_find(SilcSKR skr, SilcSchedule schedule,
526 * SilcSKRFindCallback callback,
527 * void *callback_context);
531 * Finds key(s) from key repository `skr' by the search constraints
532 * `find'. As the finding procedure may be asynchronous this returns
533 * SilcAsyncOperation that may be used to control (like abort) the
534 * operation. The `callback' with `callback_context' will be called
535 * to return found keys. If this returns NULL the finding was not
536 * asynchronous, and the `callback' has been called already.
542 * // Find all SILC public keys originating from Finland
543 * find = silc_skr_find_alloc();
544 * silc_skr_find_set_pkcs_type(find, SILC_PKCS_SILC);
545 * silc_skr_find_set_country(find, "FI");
548 * silc_skr_find(skr, schedule, find, find_callback, cb_context);
551 SilcAsyncOperation silc_skr_find(SilcSKR skr, SilcSchedule schedule,
553 SilcSKRFindCallback callback,
554 void *callback_context);
556 #include "silcskr_i.h"
558 #endif /* SILCSKR_H */