diff options
Diffstat (limited to 'module')
| -rw-r--r-- | module/p11-kit-lib.c | 119 | ||||
| -rw-r--r-- | module/p11-kit-uri.c | 43 |
2 files changed, 162 insertions, 0 deletions
diff --git a/module/p11-kit-lib.c b/module/p11-kit-lib.c index 80fdc77..33b768f 100644 --- a/module/p11-kit-lib.c +++ b/module/p11-kit-lib.c @@ -732,6 +732,20 @@ _p11_kit_initialize_registered_unlocked_reentrant (void) return rv; } +/** + * p11_kit_initialize_registered: + * + * Initialize all the registered PKCS#11 modules. + * + * If this is the first time this function is called multiple times + * consecutively within a single process, then it merely increments an + * initialization reference count for each of these modules. + * + * Use p11_kit_finalize_registered() to finalize these registered modules once + * the caller is done with them. + * + * Returns: CKR_OK if the initialization succeeded, or an error code. + */ CK_RV p11_kit_initialize_registered (void) { @@ -788,6 +802,19 @@ _p11_kit_finalize_registered_unlocked_reentrant (void) return CKR_OK; } +/** + * p11_kit_finalize_registered: + * + * Finalize all the registered PKCS#11 modules. These should have been + * initialized with p11_kit_initialize_registered(). + * + * If p11_kit_initialize_registered() has been called more than once in this + * process, then this function must be called the same number of times before + * actual finalization will occur. + * + * Returns: CKR_OK if the finalization succeeded, or an error code. + */ + CK_RV p11_kit_finalize_registered (void) { @@ -825,6 +852,18 @@ _p11_kit_registered_modules_unlocked (void) return result; } +/** + * p11_kit_registered_modules: + * + * Get a list of all the registered PKCS#11 modules. This list will be valid + * once the p11_kit_initialize_registered() function has been called. + * + * The returned value is a %NULL terminated array of %CK_FUNCTION_LIST_PTR + * pointers. + * + * Returns: A list of all the registered modules. Use the free() function to + * free the list. + */ CK_FUNCTION_LIST_PTR_PTR p11_kit_registered_modules (void) { @@ -839,6 +878,18 @@ p11_kit_registered_modules (void) return result; } +/** + * p11_kit_registered_module_to_name: + * @funcs: pointer to a registered module + * + * Get the name of a registered PKCS#11 module. + * + * You can use p11_kit_registered_modules() to get a list of all the registered + * modules. This name is specified by the registered module configuration. + * + * Returns: A newly allocated string containing the module name, or %NULL + * if no such registered module exists. Use free() to free this string. + */ char* p11_kit_registered_module_to_name (CK_FUNCTION_LIST_PTR funcs) { @@ -859,6 +910,15 @@ p11_kit_registered_module_to_name (CK_FUNCTION_LIST_PTR funcs) return name; } +/** + * p11_kit_registered_name_to_module: + * @name: name of a registered module + * + * Lookup a registered PKCS#11 module by its name. This name is specified by + * the registered module configuration. + * + * Returns: a pointer to a PKCS#11 module, or %NULL if this name was not found. + */ CK_FUNCTION_LIST_PTR p11_kit_registered_name_to_module (const char *name) { @@ -878,6 +938,17 @@ p11_kit_registered_name_to_module (const char *name) return funcs; } +/** + * p11_kit_registered_option: + * @funcs: a pointer to a registered module + * @field: the name of the option to lookup. + * + * Lookup a configured option for a registered PKCS#11 module. + * + * Returns: A newly allocated string containing the option value, or %NULL + * if the registered module or the option were not found. Use free() to free + * the returned string. + */ char* p11_kit_registered_option (CK_FUNCTION_LIST_PTR funcs, const char *field) { @@ -901,9 +972,36 @@ p11_kit_registered_option (CK_FUNCTION_LIST_PTR funcs, const char *field) return option; } +/** + * p11_kit_initialize_module: + * @funcs: loaded module to initialize. + * + * Initialize an arbitrary PKCS#11 module. Normally using the + * p11_kit_initialize_registered() is preferred. + * + * Using this function to initialize modules allows coordination between + * multiple users of the same module in a single process. It should be called + * on modules that have been loaded (with dlopen() for example) but not yet + * initialized. The caller should not yet have called the module's + * %C_Initialize method. This function will call %C_Initialize as necessary. + * + * Subsequent calls to this function for the same module will result in an + * initialization count being incremented for the module. It is safe (although + * usually unnecessary) to use this function on registered modules. + * + * The module must be finalized with p11_kit_finalize_module() instead of + * calling its %C_Finalize method directly. + * + * This function does not accept a %CK_C_INITIALIZE_ARGS argument. Custom + * initialization arguments cannot be supported when multiple consumers load + * the same module. + * + * Returns: CKR_OK if the initialization was successful. + */ CK_RV p11_kit_initialize_module (CK_FUNCTION_LIST_PTR funcs) { + CK_C_INITIALIZE_ARGS args; Module *module; Module *allocated = NULL; CK_RV rv = CKR_OK; @@ -938,6 +1036,27 @@ p11_kit_initialize_module (CK_FUNCTION_LIST_PTR funcs) return rv; } +/** + * p11_kit_finalize_module: + * @funcs: loaded module to finalize. + * + * Finalize an arbitrary PKCS#11 module. The module must have been initialized + * using p11_kit_initialize_module(). In most cases callers will want to use + * p11_kit_finalize_registered() instead of this function. + * + * Using this function to finalize modules allows coordination between + * multiple users of the same module in a single process. The caller should + * call the module's %C_Finalize method. This function will call + * %C_Finalize as necessary. + * + * If the module was initialized more than once, then this function will + * decrement an initialization count for the module. When the count reaches zero + * the module will be truly finalized. It is safe (although usually unnecessary) + * to use this function on registered modules if (and only if) they were + * initialized using p11_kit_initialize_module() for some reason. + * + * Returns: CKR_OK if the finalization was successful. + */ CK_RV p11_kit_finalize_module (CK_FUNCTION_LIST_PTR funcs) { diff --git a/module/p11-kit-uri.c b/module/p11-kit-uri.c index 7fdb33d..6830896 100644 --- a/module/p11-kit-uri.c +++ b/module/p11-kit-uri.c @@ -200,6 +200,13 @@ match_struct_version (CK_VERSION_PTR inuri, CK_VERSION_PTR real) return memcmp (inuri, real, sizeof (CK_VERSION)); } +/** + * p11_kit_uri_get_module_info: + * + * Get the %CK_INFO structure associated with this URI. + * + * Returns: A pointer to the %CK_INFO structure. + */ CK_INFO_PTR p11_kit_uri_get_module_info (P11KitUri *uri) { @@ -207,6 +214,18 @@ p11_kit_uri_get_module_info (P11KitUri *uri) return &uri->module; } +/** + * p11_kit_uri_match_module_info: + * + * Match a %CK_INFO structure against the library parts of this URI. + * + * Only the fields of the %CK_INFO structure that are valid for use in a + * URI will be matched. A URI part that was not specified in the URI will + * match any value in the structure. If during the URI parsing any unrecognized + * parts were encountered then this match will fail. + * + * Returns: 1 if the URI matches, 0 if not. + */ int p11_kit_uri_match_module_info (P11KitUri *uri, CK_INFO_PTR info) { @@ -233,6 +252,18 @@ p11_kit_uri_get_token_info (P11KitUri *uri) return &uri->token; } +/** + * p11_kit_uri_match_token_info: + * + * Match a %CK_TOKEN_INFO structure against the token parts of this URI. + * + * Only the fields of the %CK_TOKEN_INFO structure that are valid for use in a + * URI will be matched. A URI part that was not specified in the URI will + * match any value in the structure. If during the URI parsing any unrecognized + * parts were encountered then this match will fail. + * + * Returns: 1 if the URI matches, 0 if not. + */ int p11_kit_uri_match_token_info (P11KitUri *uri, CK_TOKEN_INFO_PTR token_info) { @@ -362,6 +393,18 @@ match_attributes (CK_ATTRIBUTE_PTR one, CK_ATTRIBUTE_PTR two) return memcmp (one->pValue, two->pValue, one->ulValueLen) == 0; } +/** + * p11_kit_uri_match_attributes: + * + * Match a attributes against the object parts of this URI. + * + * Only the attributes that are valid for use in a URI will be matched. A URI + * part that was not specified in the URI will match any attribute value. If + * during the URI parsing any unrecognized parts were encountered then this + * match will fail. + * + * Returns: 1 if the URI matches, 0 if not. + */ int p11_kit_uri_match_attributes (P11KitUri *uri, CK_ATTRIBUTE_PTR attrs, CK_ULONG n_attrs) |