5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2005 - 2007 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
24 * SILC Key repository is a generic public key and certificate repository
25 * which allows fast and versatile ways to retrieve public keys from the
28 * SILC Key Repository is thread safe. Same key repository context can be
29 * safely used in multi threaded environment.
36 /****s* silcskr/SilcSKRAPI/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/SilcSKRAPI/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/SilcSKRAPI/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 /* From 0x0100 reserved for private/application use. */
99 /****s* silcskr/SilcSKRAPI/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 /****d* silcskr/SilcSKRAPI/SilcSKRStatus
125 * typedef enum { ... } SilcSKRStatus;
129 * Indicates the status of the key repository procedures. This is
130 * returned to SilcSKRFindCallback function to indicate the status
131 * of the finding. This is a bitmask, and more than one status may
132 * be set at one time.
134 * If there are no errors only SILC_SKR_OK is set. If error occurred
135 * then at least SILC_SKR_ERROR is set, and possibly other error
138 * If the SILC_SKR_UNSUPPORTED_TYPE is returned the repository does not
139 * support the public key type and it cannot be added to the repository.
144 SILC_SKR_OK = 0x00000001, /* All is Ok */
145 SILC_SKR_ERROR = 0x00000002, /* Generic error status */
146 SILC_SKR_ALREADY_EXIST = 0x00000004, /* Key already exist */
147 SILC_SKR_NOT_FOUND = 0x00000008, /* No keys were found */
148 SILC_SKR_NO_MEMORY = 0x00000010, /* System out of memory */
149 SILC_SKR_UNSUPPORTED_TYPE = 0x00000020, /* Unsupported PKCS type */
153 /****f* silcskr/SilcSKRAPI/SilcSKRFindCallback
157 * typedef void (*SilcSKRFindCallback)(SilcSKR skr, SilcSKRFind find,
158 * SilcSKRStatus status,
159 * SilcDList keys, void *context);
163 * Callback that is given as argument to silc_skr_find and other find
164 * functions. Returns the results of the finding. If keys were found
165 * the `keys' is non-NULL and receiver must free it with silc_dlist_uninit.
166 * Each entry in the `keys' is SilcSKRKey context. The list `keys' is
167 * already at start so calling silc_dlist_start is not necessary when
168 * traversing the list from the start. If the `find' is non-NULL it must
169 * be freed with silc_skr_find_free.
172 typedef void (*SilcSKRFindCallback)(SilcSKR skr, SilcSKRFind find,
173 SilcSKRStatus status,
174 SilcDList keys, void *context);
176 /****f* silcskr/SilcSKRAPI/silc_skr_alloc
180 * SilcSKR silc_skr_alloc(void);
184 * Allocates key repository context.
187 SilcSKR silc_skr_alloc(void);
189 /****f* silcskr/SilcSKRAPI/silc_skr_free
193 * void silc_skr_free(SilcSKR skr);
197 * Free's the key repository context `skr' and all resources in it.
200 void silc_skr_free(SilcSKR skr);
202 /****f* silcskr/SilcSKRAPI/silc_skr_init
206 * SilcBool silc_skr_init(SilcSKR skr);
210 * Initializes a pre-allocated SilcSKR context. This function is
211 * equivalent to silc_skr_alloc but takes pre-allocated context as
212 * argument. Returns FALSE if initialization failed.
215 SilcBool silc_skr_init(SilcSKR skr);
217 /****f* silcskr/SilcSKRAPI/silc_skr_uninit
221 * void silc_skr_uninit(SilcSKR skr);
225 * Uninitializes a pre-allocated SilcSKR context. Use this function if
226 * you called silc_skr_init.
229 void silc_skr_uninit(SilcSKR skr);
231 /****f* silcskr/SilcSKRAPI/silc_skr_add_public_key
235 * SilcSKRStatus silc_skr_add_public_key(SilcSKR skr,
236 * SilcPublicKey public_key,
237 * SilcSKRKeyUsage usage,
239 * SilcSKRKey *return_key);
243 * Add a public key to repository. The repository will steal `public_key'
244 * and caller must not free it. The `key_context' is optional key specific
245 * context that will be saved in the repository with the key, and can be
246 * retrieved with the key. Public key can be added only once to the
247 * repository. To add same key more than once to repository different
248 * `key_context' must be used each time.
250 * Returns an entry of the added public key in the repository to the
251 * `return_key' pointer, if it is non-NULL. The returned entry remains
252 * valid as long as the public key is in the repository, however a
253 * reference may be taken with silc_skr_ref_public_key to assure the
254 * entry remains valid.
256 * Returns SILC_SKR_OK if the key was added successfully, and error
257 * status if key could not be added, or has been added already.
261 * // Add a key to repository
262 * if (silc_skr_add_public_key(repository, pubkey, SILC_SKR_USAGE_ANY,
263 * NULL, NULL) != SILC_SKR_OK)
267 SilcSKRStatus silc_skr_add_public_key(SilcSKR skr,
268 SilcPublicKey public_key,
269 SilcSKRKeyUsage usage,
271 SilcSKRKey *return_key);
273 /****f* silcskr/SilcSKRAPI/silc_skr_add_public_key_simple
277 * SilcSKRStatus silc_skr_add_public_key_simple(SilcSKR skr,
278 * SilcPublicKey public_key,
279 * SilcSKRKeyUsage usage,
281 * SilcSKRKey *return_key);
285 * Same as silc_skr_add_public_key but adds only the public key, usage
286 * bits and key context. The key cannot be found with any other search
287 * constraint except setting the public key, usage bits and/or key
288 * context as search constraint. This function can be used to add the
289 * key with as little memory as possible to the repository, and makes
290 * it a good way to cheaply store large amounts of public keys.
292 * Returns an entry of the added public key in the repository to the
293 * `return_key' pointer, if it is non-NULL. The returned entry remains
294 * valid as long as the public key is in the repository, however a
295 * reference may be taken with silc_skr_ref_public_key to assure the
296 * entry remains valid.
298 * Returns SILC_SKR_OK if the key was added successfully, and error
299 * status if key could not be added, or has been added already.
302 SilcSKRStatus silc_skr_add_public_key_simple(SilcSKR skr,
303 SilcPublicKey public_key,
304 SilcSKRKeyUsage usage,
306 SilcSKRKey *return_key);
308 /****f* silcskr/SilcSKRAPI/silc_skr_del_public_key
312 * SilcSKRStatus silc_skr_del_public_key(SilcSKR skr,
313 * SilcPublicKey public_key,
314 * void *key_context);
318 * Removes and destroyes the public key from the repository. The
319 * public_key will become invalid after this call returns.
321 * Returns SILC_SKR_OK if the key was added successfully, and error
322 * status if key could not be added, or has been added already.
325 SilcSKRStatus silc_skr_del_public_key(SilcSKR skr,
326 SilcPublicKey public_key,
329 /****f* silcskr/SilcSKRAPI/silc_skr_ref_public_key
333 * void silc_skr_ref_public_key(SilcSKR skr, SilcSKRKey key);
337 * Takes a reference of the public key added to repository indicated
338 * by `key'. The reference must be released by calling the function
339 * silc_skr_unref_public_key when it is not needed anymore.
342 void silc_skr_ref_public_key(SilcSKR skr, SilcSKRKey key);
344 /****f* silcskr/SilcSKRAPI/silc_skr_unref_public_key
348 * void silc_skr_unref_public_key(SilcSKR skr, SilcSKRKey key);
352 * Releases the reference of the public key added to the repository
353 * indicated by `key'. If the released reference is the last reference
354 * to the key it will become invalid after this function returns.
357 void silc_skr_unref_public_key(SilcSKR skr, SilcSKRKey key);
359 /****f* silcskr/SilcSKRAPI/silc_skr_find_alloc
363 * SilcSKRFind silc_skr_find_alloc(void);
367 * Allocates SilcSKRFind context that will hold search constraints used
368 * to find specific keys from the repository. Caller must free the
369 * context by calling silc_skr_find_free.
372 SilcSKRFind silc_skr_find_alloc(void);
374 /****f* silcskr/SilcSKRAPI/silc_skr_find_free
378 * void silc_skr_find_free(SilcSKRFind find);
382 * Free's the search constraints context `find' and all resources in it.
385 void silc_skr_find_free(SilcSKRFind find);
387 /****f* silcskr/SilcSKRAPI/silc_skr_find_add_pkcs_type
391 * SilcBool silc_skr_find_add_pkcs_type(SilcSKRFind find,
392 * SilcPKCSType type);
396 * Sets public key cryptosystem type as search constraint. Will search
397 * only for the specific type of key(s).
400 SilcBool silc_skr_find_set_pkcs_type(SilcSKRFind find, SilcPKCSType type);
402 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_username
406 * SilcBool silc_skr_find_set_username(SilcSKRFind find,
407 * const char *username);
411 * Sets username as search constraint. This specific username must be
412 * present in the key.
414 * This may be used with SILC_PKCS_SILC PKCS type only.
417 SilcBool silc_skr_find_set_username(SilcSKRFind find, const char *username);
419 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_host
423 * SilcBool silc_skr_find_set_host(SilcSKRFind find,
428 * Sets host as search constraint. This specific host must be
429 * present in the key. The `host' may be a hostname or IP address.
431 * This may be used with SILC_PKCS_SILC PKCS type only.
434 SilcBool silc_skr_find_set_host(SilcSKRFind find, const char *host);
436 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_realname
440 * SilcBool silc_skr_find_set_realname(SilcSKRFind find,
441 * const char *realname);
445 * Sets real name as search constraint. This specific name must be
446 * present in the key.
448 * This may be used with SILC_PKCS_SILC PKCS type only.
451 SilcBool silc_skr_find_set_realname(SilcSKRFind find, const char *realname);
453 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_email
457 * SilcBool silc_skr_find_set_email(SilcSKRFind find,
458 * const char *email);
462 * Sets email address as search constraint. This specific address must be
463 * present in the key.
465 * This may be used with SILC_PKCS_SILC PKCS type only.
468 SilcBool silc_skr_find_set_email(SilcSKRFind find, const char *email);
470 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_org
474 * SilcBool silc_skr_find_set_org(SilcSKRFind find,
475 * const char *email);
479 * Sets organization as search constraint. This specific organization
480 * must be present in the key.
482 * This may be used with SILC_PKCS_SILC PKCS type only.
485 SilcBool silc_skr_find_set_org(SilcSKRFind find, const char *org);
487 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_country
491 * SilcBool silc_skr_find_set_country(SilcSKRFind find,
492 * const char *email);
496 * Sets country as search constraint. This specific country must be
497 * present in the key.
499 * This may be used with SILC_PKCS_SILC PKCS type only.
502 SilcBool silc_skr_find_set_country(SilcSKRFind find, const char *country);
504 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_public_key
508 * SilcBool silc_skr_find_set_public_key(SilcSKRFind find,
509 * SilcPublicKey public_key);
513 * Sets public key as search constraint. This specific key must be
514 * present in the key.
517 SilcBool silc_skr_find_set_public_key(SilcSKRFind find,
518 SilcPublicKey public_key);
520 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_context
524 * SilcBool silc_skr_find_set_context(SilcSKRFind find, void *context);
528 * Sets public key specific context as search constraint. This specific
529 * context must be associated with the key. This is the context that
530 * was given as argument when adding the key to repository.
533 SilcBool silc_skr_find_set_context(SilcSKRFind find, void *context);
535 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_usage
539 * SilcBool silc_skr_find_set_usage(SilcSKRFind find,
540 * SilcSKRKeyUsage usage);
544 * Sets key usage as search constraint. At least one of the key usage
545 * bits must be present in the key. This search constraint cannot be
546 * used alone to search keys. At least one other search constraint
550 SilcBool silc_skr_find_set_usage(SilcSKRFind find, SilcSKRKeyUsage usage);
552 /****f* silcskr/SilcSKRAPI/silc_skr_find
556 * SilcAsyncOperation silc_skr_find(SilcSKR skr, SilcSchedule schedule,
558 * SilcSKRFindCallback callback,
559 * void *callback_context);
563 * Finds key(s) from key repository `skr' by the search constraints
564 * `find'. As the finding procedure may be asynchronous this returns
565 * SilcAsyncOperation that may be used to control (like abort) the
566 * operation. The `callback' with `callback_context' will be called
567 * to return found keys. If this returns NULL the finding was not
568 * asynchronous, and the `callback' has been called already.
574 * // Find all SILC public keys originating from Finland
575 * find = silc_skr_find_alloc();
576 * silc_skr_find_set_pkcs_type(find, SILC_PKCS_SILC);
577 * silc_skr_find_set_country(find, "FI");
580 * silc_skr_find(skr, schedule, find, find_callback, cb_context);
583 SilcAsyncOperation silc_skr_find(SilcSKR skr, SilcSchedule schedule,
585 SilcSKRFindCallback callback,
586 void *callback_context);
588 #include "silcskr_i.h"
590 #endif /* SILCSKR_H */