X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcskr%2Fsilcskr.h;h=be1521bbc7529411523a81c354f0b13125205bd1;hb=e7b6c157b80152bf9fb9266e6bdd93f9fb0db776;hp=63293ea947dc43674237f4bf74c9ef0a12855d9b;hpb=8fd8212bcd16f2b53fbedff2a9b9a4e8c15b9695;p=silc.git diff --git a/lib/silcskr/silcskr.h b/lib/silcskr/silcskr.h index 63293ea9..be1521bb 100644 --- a/lib/silcskr/silcskr.h +++ b/lib/silcskr/silcskr.h @@ -21,7 +21,9 @@ * * DESCRIPTION * - * SILC Key Repository + * SILC Key repository is a generic public key and certificate repository + * which allows fast and versatile ways to retrieve public keys from the + * the repository. * * SILC Key Repository is thread safe. Same key repository context can be * safely used in multi threaded environment. @@ -73,7 +75,7 @@ typedef struct SilcSKRFindStruct *SilcSKRFind; * * Indicates the usage of the key. Keys can be added for different * reasons and for different purpose to the repository. SilcSKRKeyUsage - * indicates what for the key exists in the repository. The default + * indicates for what reason the key exists in the repository. The default * usage is SILC_SKR_USAGE_ANY and allows any kind of usage for the key. * If the usage should be limited then specific usage bitmask can be * specified when adding the key. When searching keys from the @@ -83,11 +85,14 @@ typedef struct SilcSKRFindStruct *SilcSKRFind; * SOURCE */ typedef enum { - SILC_SKR_USAGE_ANY = 0x0000, /* Any usage */ - SILC_SKR_USAGE_AUTH = 0x0001, /* Signatures/verification */ - SILC_SKR_USAGE_ENC = 0x0002, /* Encryption/decryption */ - SILC_SKR_USAGE_KEY_AGREEMENT = 0x0004, /* Key agreement protocol */ - SILC_SKR_USAGE_IDENTIFICATION = 0x0008, /* Identifying key owner */ + SILC_SKR_USAGE_ANY = 0x0000, /* Any usage */ + SILC_SKR_USAGE_AUTH = 0x0001, /* Signatures/verification */ + SILC_SKR_USAGE_ENC = 0x0002, /* Encryption/decryption */ + SILC_SKR_USAGE_KEY_AGREEMENT = 0x0004, /* Key agreement protocol */ + SILC_SKR_USAGE_IDENTIFICATION = 0x0008, /* Identifying key owner */ + SILC_SKR_USAGE_SERVICE_AUTHORIZATION = 0x0010, /* Service authorization */ + + /* From 0x0100 reserved for private/application use. */ } SilcSKRKeyUsage; /***/ @@ -130,6 +135,9 @@ typedef struct SilcSKRKeyStruct { * then at least SILC_SKR_ERROR is set, and possibly other error * status also. * + * If the SILC_SKR_UNSUPPORTED_TYPE is returned the repository does not + * support the public key type and it cannot be added to the repository. + * * SOURCE */ typedef enum { @@ -169,14 +177,14 @@ typedef void (*SilcSKRFindCallback)(SilcSKR skr, SilcSKRFind find, * * SYNOPSIS * - * SilcSKR silc_skr_alloc(SilcSchedule scheduler); + * SilcSKR silc_skr_alloc(void); * * DESCRIPTION * * Allocates key repository context. * ***/ -SilcSKR silc_skr_alloc(SilcSchedule scheduler); +SilcSKR silc_skr_alloc(void); /****f* silcskr/SilcSKRAPI/silc_skr_free * @@ -195,7 +203,7 @@ void silc_skr_free(SilcSKR skr); * * SYNOPSIS * - * SilcBool silc_skr_init(SilcSKR skr, SilcSchedule scheduler); + * SilcBool silc_skr_init(SilcSKR skr); * * DESCRIPTION * @@ -204,7 +212,7 @@ void silc_skr_free(SilcSKR skr); * argument. Returns FALSE if initialization failed. * ***/ -SilcBool silc_skr_init(SilcSKR skr, SilcSchedule scheduler); +SilcBool silc_skr_init(SilcSKR skr); /****f* silcskr/SilcSKRAPI/silc_skr_uninit * @@ -227,7 +235,8 @@ void silc_skr_uninit(SilcSKR skr); * SilcSKRStatus silc_skr_add_public_key(SilcSKR skr, * SilcPublicKey public_key, * SilcSKRKeyUsage usage, - * void *key_context); + * void *key_context, + * SilcSKRKey *return_key); * * DESCRIPTION * @@ -238,21 +247,28 @@ void silc_skr_uninit(SilcSKR skr); * repository. To add same key more than once to repository different * `key_context' must be used each time. * + * Returns an entry of the added public key in the repository to the + * `return_key' pointer, if it is non-NULL. The returned entry remains + * valid as long as the public key is in the repository, however a + * reference may be taken with silc_skr_ref_public_key to assure the + * entry remains valid. + * * Returns SILC_SKR_OK if the key was added successfully, and error * status if key could not be added, or has been added already. * * EXAMPLE * * // Add a key to repository - * if (silc_skr_add_public_key(repository, public_key, - * SILC_SKR_USAGE_ANY, NULL) != SILC_SKR_OK) + * if (silc_skr_add_public_key(repository, pubkey, SILC_SKR_USAGE_ANY, + * NULL, NULL) != SILC_SKR_OK) * goto error; * ***/ SilcSKRStatus silc_skr_add_public_key(SilcSKR skr, SilcPublicKey public_key, SilcSKRKeyUsage usage, - void *key_context); + void *key_context, + SilcSKRKey *return_key); /****f* silcskr/SilcSKRAPI/silc_skr_add_public_key_simple * @@ -261,7 +277,8 @@ SilcSKRStatus silc_skr_add_public_key(SilcSKR skr, * SilcSKRStatus silc_skr_add_public_key_simple(SilcSKR skr, * SilcPublicKey public_key, * SilcSKRKeyUsage usage, - * void *key_context); + * void *key_context, + * SilcSKRKey *return_key); * * DESCRIPTION * @@ -272,6 +289,12 @@ SilcSKRStatus silc_skr_add_public_key(SilcSKR skr, * key with as little memory as possible to the repository, and makes * it a good way to cheaply store large amounts of public keys. * + * Returns an entry of the added public key in the repository to the + * `return_key' pointer, if it is non-NULL. The returned entry remains + * valid as long as the public key is in the repository, however a + * reference may be taken with silc_skr_ref_public_key to assure the + * entry remains valid. + * * Returns SILC_SKR_OK if the key was added successfully, and error * status if key could not be added, or has been added already. * @@ -279,7 +302,59 @@ SilcSKRStatus silc_skr_add_public_key(SilcSKR skr, SilcSKRStatus silc_skr_add_public_key_simple(SilcSKR skr, SilcPublicKey public_key, SilcSKRKeyUsage usage, - void *key_context); + void *key_context, + SilcSKRKey *return_key); + +/****f* silcskr/SilcSKRAPI/silc_skr_del_public_key + * + * SYNOPSIS + * + * SilcSKRStatus silc_skr_del_public_key(SilcSKR skr, + * SilcPublicKey public_key, + * void *key_context); + * + * DESCRIPTION + * + * Removes and destroyes the public key from the repository. The + * public_key will become invalid after this call returns. + * + * Returns SILC_SKR_OK if the key was added successfully, and error + * status if key could not be added, or has been added already. + * + ***/ +SilcSKRStatus silc_skr_del_public_key(SilcSKR skr, + SilcPublicKey public_key, + void *key_context); + +/****f* silcskr/SilcSKRAPI/silc_skr_ref_public_key + * + * SYNOPSIS + * + * void silc_skr_ref_public_key(SilcSKR skr, SilcSKRKey key); + * + * DESCRIPTION + * + * Takes a reference of the public key added to repository indicated + * by `key'. The reference must be released by calling the function + * silc_skr_unref_public_key when it is not needed anymore. + * + ***/ +void silc_skr_ref_public_key(SilcSKR skr, SilcSKRKey key); + +/****f* silcskr/SilcSKRAPI/silc_skr_unref_public_key + * + * SYNOPSIS + * + * void silc_skr_unref_public_key(SilcSKR skr, SilcSKRKey key); + * + * DESCRIPTION + * + * Releases the reference of the public key added to the repository + * indicated by `key'. If the released reference is the last reference + * to the key it will become invalid after this function returns. + * + ***/ +void silc_skr_unref_public_key(SilcSKR skr, SilcSKRKey key); /****f* silcskr/SilcSKRAPI/silc_skr_find_alloc * @@ -478,7 +553,8 @@ SilcBool silc_skr_find_set_usage(SilcSKRFind find, SilcSKRKeyUsage usage); * * SYNOPSIS * - * SilcAsyncOperation silc_skr_find(SilcSKR skr, SilcSKRFind find, + * SilcAsyncOperation silc_skr_find(SilcSKR skr, SilcSchedule schedule, + * SilcSKRFind find, * SilcSKRFindCallback callback, * void *callback_context); * @@ -501,10 +577,11 @@ SilcBool silc_skr_find_set_usage(SilcSKRFind find, SilcSKRKeyUsage usage); * silc_skr_find_set_country(find, "FI"); * * // Find - * silc_skr_find(skr, find, find_callback, cb_context); + * silc_skr_find(skr, schedule, find, find_callback, cb_context); * ***/ -SilcAsyncOperation silc_skr_find(SilcSKR skr, SilcSKRFind find, +SilcAsyncOperation silc_skr_find(SilcSKR skr, SilcSchedule schedule, + SilcSKRFind find, SilcSKRFindCallback callback, void *callback_context);