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/Makefile.am | 2 + doc/manual/p11-kit-docs.xml | 2 + doc/manual/p11-kit-proxy.xml | 29 +++++++++++++ doc/manual/p11-kit-sections.txt | 39 +++++++++++++---- doc/manual/p11-kit-sharing.xml | 94 ++++++++++++++++++++--------------------- doc/manual/pkcs11.conf.xml | 24 +++++++++++ 6 files changed, 134 insertions(+), 56 deletions(-) create mode 100644 doc/manual/p11-kit-proxy.xml (limited to 'doc/manual') diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index c10375a..b5b80f1 100644 --- a/doc/manual/Makefile.am +++ b/doc/manual/Makefile.am @@ -53,6 +53,7 @@ IGNORE_HFILES= \ debug.h \ dict.h \ mock.h \ + modules.h \ pkcs11.h \ pkcs11x.h \ private.h \ @@ -70,6 +71,7 @@ HTML_IMAGES= # e.g. content_files=running.sgml building.sgml changes-2.0.sgml content_files=p11-kit-config.xml p11-kit-sharing.xml \ p11-kit-devel.xml \ + p11-kit-proxy.xml \ p11-kit-trust.xml \ p11-kit.xml \ pkcs11.conf.xml \ diff --git a/doc/manual/p11-kit-docs.xml b/doc/manual/p11-kit-docs.xml index 0397169..5acfb97 100644 --- a/doc/manual/p11-kit-docs.xml +++ b/doc/manual/p11-kit-docs.xml @@ -13,6 +13,7 @@ + @@ -28,6 +29,7 @@ + API Index diff --git a/doc/manual/p11-kit-proxy.xml b/doc/manual/p11-kit-proxy.xml new file mode 100644 index 0000000..7cc3615 --- /dev/null +++ b/doc/manual/p11-kit-proxy.xml @@ -0,0 +1,29 @@ + + + + Proxy Module + + When an application is aware of the fact that coordination + is necessary between multiple consumers of a PKCS#11 module, and wants + to load standard configured PKCS#11 modules, it can link to + p11-kit and use the functions there to provide this + functionality. + + 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 + manages their features as described earlier. 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 C_GetFunctionList exported entry point of the + proxy module returns a new managed PKCS#11 module each time it is called. These + managed instances are released when the proxy module is unloaded. + diff --git a/doc/manual/p11-kit-sections.txt b/doc/manual/p11-kit-sections.txt index dc85f2d..84f084d 100644 --- a/doc/manual/p11-kit-sections.txt +++ b/doc/manual/p11-kit-sections.txt @@ -52,15 +52,22 @@ p11_kit_pin_file_callback
p11-kit -p11_kit_initialize_registered -p11_kit_finalize_registered -p11_kit_registered_modules -p11_kit_registered_module_to_name -p11_kit_registered_name_to_module -p11_kit_registered_option -p11_kit_initialize_module -p11_kit_load_initialize_module -p11_kit_finalize_module +P11_KIT_MODULE_CRITICAL +P11_KIT_MODULE_UNMANAGED +p11_kit_modules_load_and_initialize +p11_kit_modules_finalize_and_release +p11_kit_modules_load +p11_kit_modules_initialize +p11_kit_modules_finalize +p11_kit_modules_release +p11_kit_module_load +p11_kit_module_initialize +p11_kit_module_finalize +p11_kit_module_release +p11_kit_module_for_name +p11_kit_module_get_name +p11_kit_module_get_flags +p11_kit_config_option
@@ -104,3 +111,17 @@ p11_kit_iter_get_object p11_kit_iter_load_attributes p11_kit_iter_free
+ +
+p11-kit-deprecated +p11_kit_initialize_registered +p11_kit_finalize_registered +p11_kit_registered_modules +p11_kit_registered_module_to_name +p11_kit_registered_name_to_module +p11_kit_registered_option +p11_kit_initialize_module +p11_kit_load_initialize_module +p11_kit_finalize_module +P11_KIT_DEPRECATED_FOR +
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. + +
diff --git a/doc/manual/pkcs11.conf.xml b/doc/manual/pkcs11.conf.xml index 1814377..1051ee1 100644 --- a/doc/manual/pkcs11.conf.xml +++ b/doc/manual/pkcs11.conf.xml @@ -128,6 +128,16 @@ x-custom : text + + + Set to no if the module is not to be managed by + p11-kit. Making a module unmanaged is not recommended, and will cause + problems if multiple callers in a single process share a PKCS#11 module. + + This argument is optonal and defaults to yes. + + + The value should be an integer. When lists of modules are @@ -172,6 +182,20 @@ x-custom : text none, merge, only. + + + + Set to yes or no to + force all modules to be managed or unmanaged by p11-kit. Setting this + setting in a global configuration file will override the + managed setting in the individual module configuration + files. Making modules unmanaged is not recommended, and will cause + problems if multiple callers in a single process share a PKCS#11 + module. + + This argument is optonal. + + Other fields may be present, but it is recommended that field names -- cgit v1.1