X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcskr%2Fsilcskr.h;h=be1521bbc7529411523a81c354f0b13125205bd1;hb=e7b6c157b80152bf9fb9266e6bdd93f9fb0db776;hp=a2e9abfd65cfec19248e3dbdeac60400f5afe398;hpb=40f8443d8d3a6577336ee66d18e04d9ac4d956bb;p=silc.git diff --git a/lib/silcskr/silcskr.h b/lib/silcskr/silcskr.h index a2e9abfd..be1521bb 100644 --- a/lib/silcskr/silcskr.h +++ b/lib/silcskr/silcskr.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - Copyright (C) 2005 Pekka Riikonen + Copyright (C) 2005 - 2007 Pekka Riikonen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -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; /***/ @@ -95,26 +100,20 @@ typedef enum { * * NAME * - * typedef struct SilcSKRKeyStruct { ... } *SilcSKRKey + * typedef struct SilcSKRKeyStruct { ... } *SilcSKRKey; * * DESCRIPTION * - * This context holds the public key cryptosystem key type and the key - * context that has been saved in the key repository. This context is - * returned in the SilcSKRFindCallback list. Each entry in the list is - * SilcSKRKey. - * - * The key context saved in SilcSKRKey is based on the PKCS type and - * caller can explicitly type cast the key to correct type based on the - * PKCS type. + * This context holds the public key, optional public key specific + * context and public key usage bits. This context is returned in + * the SilcSKRFindCallback list. Each entry in the list is SIlcSKRKey. * * SOURCE * */ typedef struct SilcSKRKeyStruct { SilcSKRKeyUsage usage; /* Key usage */ - SilcPKCSType pk_type; /* PKCS type */ - void *key; /* SILC_PKCS_SILC: SilcPublicKey */ + SilcPublicKey key; /* Public key */ void *key_context; /* Optional key specific context */ } *SilcSKRKey; /***/ @@ -136,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 { @@ -175,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 * @@ -201,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 * @@ -210,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 * @@ -233,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 * @@ -244,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_USAGW_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 * @@ -267,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 * @@ -278,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. * @@ -285,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 * @@ -448,7 +517,7 @@ SilcBool silc_skr_find_set_country(SilcSKRFind find, const char *country); SilcBool silc_skr_find_set_public_key(SilcSKRFind find, SilcPublicKey public_key); -/****f* silcskr/SilcSKRAPI/silc_skr_find_set_public_key +/****f* silcskr/SilcSKRAPI/silc_skr_find_set_context * * SYNOPSIS * @@ -484,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); * @@ -494,38 +564,26 @@ SilcBool silc_skr_find_set_usage(SilcSKRFind find, SilcSKRKeyUsage usage); * `find'. As the finding procedure may be asynchronous this returns * SilcAsyncOperation that may be used to control (like abort) the * operation. The `callback' with `callback_context' will be called - * to return found keys. If this returns NULL, operation cannot be - * controlled, however it is not an error. + * to return found keys. If this returns NULL the finding was not + * asynchronous, and the `callback' has been called already. * - ***/ -SilcAsyncOperation silc_skr_find(SilcSKR skr, SilcSKRFind find, - SilcSKRFindCallback callback, - void *callback_context); - -/****f* silcskr/SilcSKRAPI/silc_skr_find_silc - * - * SYNOPSIS + * EXAMPLE * - * SilcAsyncOperation silc_skr_find_silc(SilcSKR skr, - * SilcPublicKey public_key, - * SilcSKRFindCallback callback, - * void *callback_context); + * SilcSKRFind find; * - * DESCRIPTION + * // Find all SILC public keys originating from Finland + * find = silc_skr_find_alloc(); + * silc_skr_find_set_pkcs_type(find, SILC_PKCS_SILC); + * silc_skr_find_set_country(find, "FI"); * - * A helper function that can be used to find specificly SILC style - * public keys from the repository. This returns found key(s) by - * the `public_key'. As the finding procedure may be asynchronous - * this returns SilcAsyncOperation that may be used to control (like - * abort) the operation. The `callback' with `callback_context' will - * be called to return found keys. If this returns NULL, operation - * cannot be controlled, however it is not an error. + * // Find + * silc_skr_find(skr, schedule, find, find_callback, cb_context); * ***/ -SilcAsyncOperation silc_skr_find_silc(SilcSKR skr, - SilcPublicKey public_key, - SilcSKRFindCallback callback, - void *callback_context); +SilcAsyncOperation silc_skr_find(SilcSKR skr, SilcSchedule schedule, + SilcSKRFind find, + SilcSKRFindCallback callback, + void *callback_context); #include "silcskr_i.h"