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
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, optional public key specific
103 * context and public key usage bits. This context is returned in
104 * the SilcSKRFindCallback list. Each entry in the list is SIlcSKRKey.
109 typedef struct SilcSKRKeyStruct {
110 SilcSKRKeyUsage usage; /* Key usage */
111 SilcPublicKey key; /* Public key */
112 void *key_context; /* Optional key specific context */
116 /****d* silcskr/SilcSKRAPI/SilcSKRStatus
120 * typedef enum { ... } SilcSKRStatus;
124 * Indicates the status of the key repository procedures. This is
125 * returned to SilcSKRFindCallback function to indicate the status
126 * of the finding. This is a bitmask, and more than one status may
127 * be set at one time.
129 * If there are no errors only SILC_SKR_OK is set. If error occurred
130 * then at least SILC_SKR_ERROR is set, and possibly other error
136 SILC_SKR_OK = 0x00000001, /* All is Ok */
137 SILC_SKR_ERROR = 0x00000002, /* Generic error status */
138 SILC_SKR_ALREADY_EXIST = 0x00000004, /* Key already exist */
139 SILC_SKR_NOT_FOUND = 0x00000008, /* No keys were found */
140 SILC_SKR_NO_MEMORY = 0x00000010, /* System out of memory */
141 SILC_SKR_UNSUPPORTED_TYPE = 0x00000020, /* Unsupported PKCS type */
145 /****f* silcskr/SilcSKRAPI/SilcSKRFindCallback
149 * typedef void (*SilcSKRFindCallback)(SilcSKR skr, SilcSKRFind find,
150 * SilcSKRStatus status,
151 * SilcDList keys, void *context);
155 * Callback that is given as argument to silc_skr_find and other find
156 * functions. Returns the results of the finding. If keys were found
157 * the `keys' is non-NULL and receiver must free it with silc_dlist_uninit.
158 * Each entry in the `keys' is SilcSKRKey context. The list `keys' is
159 * already at start so calling silc_dlist_start is not necessary when
160 * traversing the list from the start. If the `find' is non-NULL it must
161 * be freed with silc_skr_find_free.
164 typedef void (*SilcSKRFindCallback)(SilcSKR skr, SilcSKRFind find,
165 SilcSKRStatus status,
166 SilcDList keys, void *context);
168 /****f* silcskr/SilcSKRAPI/silc_skr_alloc
172 * SilcSKR silc_skr_alloc(SilcSchedule scheduler);
176 * Allocates key repository context.
179 SilcSKR silc_skr_alloc(SilcSchedule scheduler);
181 /****f* silcskr/SilcSKRAPI/silc_skr_free
185 * void silc_skr_free(SilcSKR skr);
189 * Free's the key repository context `skr' and all resources in it.
192 void silc_skr_free(SilcSKR skr);
194 /****f* silcskr/SilcSKRAPI/silc_skr_init
198 * SilcBool silc_skr_init(SilcSKR skr, SilcSchedule scheduler);
202 * Initializes a pre-allocated SilcSKR context. This function is
203 * equivalent to silc_skr_alloc but takes pre-allocated context as
204 * argument. Returns FALSE if initialization failed.
207 SilcBool silc_skr_init(SilcSKR skr, SilcSchedule scheduler);
209 /****f* silcskr/SilcSKRAPI/silc_skr_uninit
213 * void silc_skr_uninit(SilcSKR skr);
217 * Uninitializes a pre-allocated SilcSKR context. Use this function if
218 * you called silc_skr_init.
221 void silc_skr_uninit(SilcSKR skr);
223 /****f* silcskr/SilcSKRAPI/silc_skr_add_public_key
227 * SilcSKRStatus silc_skr_add_public_key(SilcSKR skr,
228 * SilcPublicKey public_key,
229 * SilcSKRKeyUsage usage,
230 * void *key_context);
234 * Add a public key to repository. The repository will steal `public_key'
235 * and caller must not free it. The `key_context' is optional key specific
236 * context that will be saved in the repository with the key, and can be
237 * retrieved with the key. Public key can be added only once to the
238 * repository. To add same key more than once to repository different
239 * `key_context' must be used each time.
241 * Returns SILC_SKR_OK if the key was added successfully, and error
242 * status if key could not be added, or has been added already.
246 * // Add a key to repository
247 * if (silc_skr_add_public_key(repository, public_key,
248 * SILC_SKR_USAGE_ANY, NULL) != SILC_SKR_OK)
252 SilcSKRStatus silc_skr_add_public_key(SilcSKR skr,
253 SilcPublicKey public_key,
254 SilcSKRKeyUsage usage,
257 /****f* silcskr/SilcSKRAPI/silc_skr_add_public_key_simple
261 * SilcSKRStatus silc_skr_add_public_key_simple(SilcSKR skr,
262 * SilcPublicKey public_key,
263 * SilcSKRKeyUsage usage,
264 * void *key_context);
268 * Same as silc_skr_add_public_key but adds only the public key, usage
269 * bits and key context. The key cannot be found with any other search
270 * constraint except setting the public key, usage bits and/or key
271 * context as search constraint. This function can be used to add the
272 * key with as little memory as possible to the repository, and makes
273 * it a good way to cheaply store large amounts of public keys.
275 * Returns SILC_SKR_OK if the key was added successfully, and error
276 * status if key could not be added, or has been added already.
279 SilcSKRStatus silc_skr_add_public_key_simple(SilcSKR skr,
280 SilcPublicKey public_key,
281 SilcSKRKeyUsage usage,
284 /****f* silcskr/SilcSKRAPI/silc_skr_find_alloc
288 * SilcSKRFind silc_skr_find_alloc(void);
292 * Allocates SilcSKRFind context that will hold search constraints used
293 * to find specific keys from the repository. Caller must free the
294 * context by calling silc_skr_find_free.
297 SilcSKRFind silc_skr_find_alloc(void);
299 /****f* silcskr/SilcSKRAPI/silc_skr_find_free
303 * void silc_skr_find_free(SilcSKRFind find);
307 * Free's the search constraints context `find' and all resources in it.
310 void silc_skr_find_free(SilcSKRFind find);
312 /****f* silcskr/SilcSKRAPI/silc_skr_find_add_pkcs_type
316 * SilcBool silc_skr_find_add_pkcs_type(SilcSKRFind find,
317 * SilcPKCSType type);
321 * Sets public key cryptosystem type as search constraint. Will search
322 * only for the specific type of key(s).
325 SilcBool silc_skr_find_set_pkcs_type(SilcSKRFind find, SilcPKCSType type);
327 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_username
331 * SilcBool silc_skr_find_set_username(SilcSKRFind find,
332 * const char *username);
336 * Sets username as search constraint. This specific username must be
337 * present in the key.
339 * This may be used with SILC_PKCS_SILC PKCS type only.
342 SilcBool silc_skr_find_set_username(SilcSKRFind find, const char *username);
344 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_host
348 * SilcBool silc_skr_find_set_host(SilcSKRFind find,
353 * Sets host as search constraint. This specific host must be
354 * present in the key. The `host' may be a hostname or IP address.
356 * This may be used with SILC_PKCS_SILC PKCS type only.
359 SilcBool silc_skr_find_set_host(SilcSKRFind find, const char *host);
361 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_realname
365 * SilcBool silc_skr_find_set_realname(SilcSKRFind find,
366 * const char *realname);
370 * Sets real name as search constraint. This specific name must be
371 * present in the key.
373 * This may be used with SILC_PKCS_SILC PKCS type only.
376 SilcBool silc_skr_find_set_realname(SilcSKRFind find, const char *realname);
378 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_email
382 * SilcBool silc_skr_find_set_email(SilcSKRFind find,
383 * const char *email);
387 * Sets email address as search constraint. This specific address must be
388 * present in the key.
390 * This may be used with SILC_PKCS_SILC PKCS type only.
393 SilcBool silc_skr_find_set_email(SilcSKRFind find, const char *email);
395 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_org
399 * SilcBool silc_skr_find_set_org(SilcSKRFind find,
400 * const char *email);
404 * Sets organization as search constraint. This specific organization
405 * must be present in the key.
407 * This may be used with SILC_PKCS_SILC PKCS type only.
410 SilcBool silc_skr_find_set_org(SilcSKRFind find, const char *org);
412 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_country
416 * SilcBool silc_skr_find_set_country(SilcSKRFind find,
417 * const char *email);
421 * Sets country as search constraint. This specific country must be
422 * present in the key.
424 * This may be used with SILC_PKCS_SILC PKCS type only.
427 SilcBool silc_skr_find_set_country(SilcSKRFind find, const char *country);
429 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_public_key
433 * SilcBool silc_skr_find_set_public_key(SilcSKRFind find,
434 * SilcPublicKey public_key);
438 * Sets public key as search constraint. This specific key must be
439 * present in the key.
442 SilcBool silc_skr_find_set_public_key(SilcSKRFind find,
443 SilcPublicKey public_key);
445 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_context
449 * SilcBool silc_skr_find_set_context(SilcSKRFind find, void *context);
453 * Sets public key specific context as search constraint. This specific
454 * context must be associated with the key. This is the context that
455 * was given as argument when adding the key to repository.
458 SilcBool silc_skr_find_set_context(SilcSKRFind find, void *context);
460 /****f* silcskr/SilcSKRAPI/silc_skr_find_set_usage
464 * SilcBool silc_skr_find_set_usage(SilcSKRFind find,
465 * SilcSKRKeyUsage usage);
469 * Sets key usage as search constraint. At least one of the key usage
470 * bits must be present in the key. This search constraint cannot be
471 * used alone to search keys. At least one other search constraint
475 SilcBool silc_skr_find_set_usage(SilcSKRFind find, SilcSKRKeyUsage usage);
477 /****f* silcskr/SilcSKRAPI/silc_skr_find
481 * SilcAsyncOperation silc_skr_find(SilcSKR skr, SilcSKRFind find,
482 * SilcSKRFindCallback callback,
483 * void *callback_context);
487 * Finds key(s) from key repository `skr' by the search constraints
488 * `find'. As the finding procedure may be asynchronous this returns
489 * SilcAsyncOperation that may be used to control (like abort) the
490 * operation. The `callback' with `callback_context' will be called
491 * to return found keys. If this returns NULL the finding was not
492 * asynchronous, and the `callback' has been called already.
495 SilcAsyncOperation silc_skr_find(SilcSKR skr, SilcSKRFind find,
496 SilcSKRFindCallback callback,
497 void *callback_context);
499 #include "silcskr_i.h"
501 #endif /* SILCSKR_H */