![]() |
![]() |
![]() |
p11-kit | ![]() |
---|---|---|---|---|
Top | Description |
CK_RV p11_kit_initialize_registered (void
); CK_RV p11_kit_finalize_registered (void
); CK_FUNCTION_LIST_PTR * p11_kit_registered_modules (void
); char * p11_kit_registered_module_to_name (CK_FUNCTION_LIST_PTR module
); CK_FUNCTION_LIST_PTR p11_kit_registered_name_to_module (const char *name
); char * p11_kit_registered_option (CK_FUNCTION_LIST_PTR module
,const char *field
); CK_RV p11_kit_initialize_module (CK_FUNCTION_LIST_PTR module
); CK_RV p11_kit_load_initialize_module (const char *module_path
,CK_FUNCTION_LIST_PTR *module
); CK_RV p11_kit_finalize_module (CK_FUNCTION_LIST_PTR module
);
PKCS#11 modules are used by crypto libraries and applications to access crypto objects (like keys and certificates) and to perform crypto operations.
In order for applications to behave consistently with regard to the user's installed PKCS#11 modules, each module must be registered so that applications or libraries know that they should load it.
The functions here provide support for initializing registered modules. The
p11_kit_initialize_registered()
function should be used to load and initialize
the registered modules. When done, the p11_kit_finalize_registered()
function
should be used to release those modules and associated resources.
In addition p11_kit_registered_option()
can be used to access other parts
of the module configuration.
When multiple consumers of a module (such as libraries or applications) are in the same process, coordination of the initialization and finalization of PKCS#11 modules is required. The functions here automatically provide initialization reference counting to make this work.
If a consumer wishes to load an arbitrary PKCS#11 module that's not
registered, that module should be initialized with p11_kit_initialize_module()
and finalized with p11_kit_finalize_module()
. The module's own
C_Initialize
and C_Finalize
methods should not
be called directly.
Modules are represented by a pointer to their CK_FUNCTION_LIST
entry points. This means that callers can load modules elsewhere, using
dlopen()
for example, and then still use these methods on them.
CK_RV p11_kit_initialize_registered (void
);
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.
If this function fails, then an error message will be available via the
p11_kit_message()
function.
Returns : |
CKR_OK if the initialization succeeded, or an error code. |
CK_RV p11_kit_finalize_registered (void
);
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.
If this function fails, then an error message will be available via the
p11_kit_message()
function.
Returns : |
CKR_OK if the finalization succeeded, or an error code. |
CK_FUNCTION_LIST_PTR * p11_kit_registered_modules (void
);
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. |
char * p11_kit_registered_module_to_name (CK_FUNCTION_LIST_PTR 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.
|
pointer to a registered module |
Returns : |
A newly allocated string containing the module name, or
NULL if no such registered module exists. Use free() to
free this string. |
CK_FUNCTION_LIST_PTR p11_kit_registered_name_to_module (const char *name
);
Lookup a registered PKCS#11 module by its name. This name is specified by the registered module configuration.
|
name of a registered module |
Returns : |
a pointer to a PKCS#11 module, or NULL if this name was
not found. |
char * p11_kit_registered_option (CK_FUNCTION_LIST_PTR module
,const char *field
);
Lookup a configured option for a registered PKCS#11 module. If a
NULL
module argument is specified, then this will lookup
the configuration option in the global config file.
|
a pointer to a registered module |
|
the name of the option to lookup. |
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. |
CK_RV p11_kit_initialize_module (CK_FUNCTION_LIST_PTR module
);
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.
If this function fails, then an error message will be available via the
p11_kit_message()
function.
|
loaded module to initialize. |
Returns : |
CKR_OK if the initialization was successful. |
CK_RV p11_kit_load_initialize_module (const char *module_path
,CK_FUNCTION_LIST_PTR *module
);
Load an arbitrary PKCS#11 module from a dynamic library file, and
initialize it. Normally using the p11_kit_initialize_registered()
function
is preferred.
Using this function to load and initialize modules allows coordination between
multiple users of the same module in a single process. The caller should not
call the module's C_Initialize
method. This function will call
C_Initialize
as necessary.
If a module has already been loaded, then use of this function is unnecesasry.
Instead use the p11_kit_initialize_module()
function to initialize it.
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.
If this function fails, then an error message will be available via the
p11_kit_message()
function.
|
full file path of module library |
|
location to place loaded module pointer |
Returns : |
CKR_OK if the initialization was successful. |
CK_RV p11_kit_finalize_module (CK_FUNCTION_LIST_PTR module
);
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.
If this function fails, then an error message will be available via the
p11_kit_message()
function.
|
loaded module to finalize. |
Returns : |
CKR_OK if the finalization was successful. |