From 5c19f0cf66495f00ccf69eba1d0915f862a88c8d Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Wed, 6 Feb 2013 21:57:45 +0100 Subject: p11-kit: Managed PKCS#11 module loading Support a new managed style module loading for PKCS#11 modules. This allows us to better coordinate between multiple callers of the same PKCS#11 modules and provide hooks into their behavior. This meant redoing the public facing API. The old methods are now deprecated, marked and documented as such. --- doc/manual/p11-kit-sharing.xml | 94 +++++++++++++++++++++--------------------- 1 file changed, 47 insertions(+), 47 deletions(-) (limited to 'doc/manual/p11-kit-sharing.xml') diff --git a/doc/manual/p11-kit-sharing.xml b/doc/manual/p11-kit-sharing.xml index e692e3d..01b3c8b 100644 --- a/doc/manual/p11-kit-sharing.xml +++ b/doc/manual/p11-kit-sharing.xml @@ -42,52 +42,52 @@ loosely coupled, backwards compatible, and flexible way. -
- Solution: p11-kit - - p11-kit provides functions to - coordinate initialization and finalization of any PKCS#11 - module. A module may be initialized any number of times using - the p11_kit_initialize_module() function. The first time that - p11_kit_initialize_module() is called for a module, that module's - C_Initialize function is used. Later invocations for the same - module cause p11-kit to increment an internal initialization - count, rather than calling C_Initialize again. - - The p11_kit_finalize_module() is used to finalize a module. - Each time it is called it decrements the internal initialization - count for that module. When the internal initialization count - reaches zero, the module's C_Finalize function is called. - - This is done in a thread-safe manner. These functions can - be used on modules that the consumer loads themselves. -
- -
- Solution: proxy module - - When an application is aware of the fact that coordination - is necessary between multiple consumers of a PKCS#11 module, it - can link to p11-kit and use the functions there to provide - this coordination. - - However most current consumers of PKCS#11 are ignorant of - this problem, and do not link to p11-kit. In order to solve this - multiple initialization problem for all applications, - p11-kit provides a proxy compatibility - module. - - This proxy module acts like a normal PKCS#11 module, but - internally loads a preconfigured set of PKCS#11 modules and - coordinates their initialization and finalization. Each slot - in the configured modules is exposed as a slot of the - p11-kit proxy module. The proxy module is - then used as a normal PKCS#11 module would be. It can be loaded by - crypto libraries like NSS and behaves as expected. - - The proxy module bends the PKCS#11 rules slightly. It does - not return the CKR_CRYPTOKI_ALREADY_INITIALIZED - error code as specified in PKCS#11. However this is a small - price to pay for this compatibility. +
+ Managed modules + + p11-kit wraps PKCS#11 modules to manage + them and customize their functionality so that they are able + to be shared between multiple callers in the same process. + + Each caller that uses the + p11_kit_modules_load() + or p11_kit_module_load() + function gets independent wrapped PKCS#11 module(s). This is unless a caller + or module configuration specifies that a module should be used in an + unmanaged fashion. + + When modules are managed, the following aspects are wrapped and + coordinated: + + + + Calls to C_Initialize and + C_Finalize can be called by multiple + callers. + + The first time that the managed module + C_Initialize is called, the PKCS#11 module's actual + C_Initialize function is called. Subsequent calls by + other callers will cause p11-kit to increment an + internal initialization count, rather than calling + C_Initialize again. + + Multiple callers can call the managed + C_Initialize function concurrently from different + threads and p11-kit will guarantee that this managed + in a thread-safe manner. + + + When the managed module C_Finalize is used + to finalize a module, each time it is called it decrements the internal + initialization count for that module. When the internal initialization + count reaches zero, the module's actual C_Finalize + function is called. + + Multiple callers can call the managed C_Finalize + function concurrently from different threads and p11-kit + will guarantee that this managed in a thread-safe manner. + +
-- cgit v1.1