diff options
Diffstat (limited to 'doc/manual/p11-kit-sharing.xml')
| -rw-r--r-- | doc/manual/p11-kit-sharing.xml | 110 |
1 files changed, 0 insertions, 110 deletions
diff --git a/doc/manual/p11-kit-sharing.xml b/doc/manual/p11-kit-sharing.xml deleted file mode 100644 index 0edf36e..0000000 --- a/doc/manual/p11-kit-sharing.xml +++ /dev/null @@ -1,110 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" - "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> - -<chapter xml:id="sharing"> - <title>Sharing PKCS#11 modules</title> - - <section xml:id="sharing-problem"> - <title>Multiple consumers of PKCS#11 in a process</title> - - <para>As more and more applications and libraries use PKCS#11 we run - into a very basic problem. The PKCS#11 modules cannot be initialized and - finalized properly without coordination between the various consumers. - </para> - - <para>An example: An application might use GnuTLS for - TLS connections, and use libgcr for display of certificates. Both of - these want to load (and initialize) the same PKCS#11 modules. There are - many places where this situation occurs, including large applications - like Evolution which due to their dependencies end up using both NSS and - GnuTLS.</para> - - <para>Consumer A loads a PKCS#11 module and uses the module's - C_Initialize function to initialize it, which works as expected. - When consumer B initializes the module (also using C_Initialize), - the error code <literal>CKR_CRYPTOKI_ALREADY_INITIALIZED</literal> - is correctly returned. This is normal PKCS#11 specification - defined behavior for when a module is initialized twice in the - same process. If consumer B is aware of this situation they may - choose to ignore this error code.</para> - - <para>However when the consumer A is done with its use of the - PKCS#11 module it finalizes the module using the module's - C_Finalize function. This is expected of a well behaved PKCS#11 - consumer. This then causes errors and/or crashes for consumer B, - which cannot know that the module has now been finalized out - from underneath it.</para> - - <para>It is necessary for the two consumers to coordinate their - initialization and finalization in some fashion. In - <literal>p11-kit</literal> we provide this coordination in a - loosely coupled, backwards compatible, and flexible way.</para> - </section> - - <section xml:id="sharing-managed"> - <title>Managed modules</title> - - <para><literal>p11-kit</literal> 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.</para> - - <para>Each caller that uses the - <link linkend="p11-kit-modules-load"><function>p11_kit_modules_load()</function></link> - or <link linkend="p11-kit-module-load"><function>p11_kit_module_load()</function></link> - 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.</para> - - <para>When modules are managed, the following aspects are wrapped and - coordinated:</para> - - <itemizedlist> - <listitem> - <para>Calls to <literal>C_Initialize</literal> and - <literal>C_Finalize</literal> can be called by multiple - callers.</para> - - <para>The first time that the managed module - <literal>C_Initialize</literal> is called, the PKCS#11 module's actual - <literal>C_Initialize</literal> function is called. Subsequent calls by - other callers will cause <literal>p11-kit</literal> to increment an - internal initialization count, rather than calling - <literal>C_Initialize</literal> again.</para> - - <para>Multiple callers can call the managed - <literal>C_Initialize</literal> function concurrently from different - threads and <literal>p11-kit</literal> will guarantee that this managed - in a thread-safe manner.</para> - </listitem> - <listitem> - <para>When the managed module <literal>C_Finalize</literal> 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 <literal>C_Finalize</literal> - function is called.</para> - - <para>Multiple callers can call the managed <literal>C_Finalize</literal> - function concurrently from different threads and <literal>p11-kit</literal> - will guarantee that this managed in a thread-safe manner.</para> - </listitem> - <listitem> - <para>Call to <literal>C_CloseAllSessions</literal> only close the - sessions that the caller of the managed module has opened. This allows the - <literal>C_CloseAllSessions</literal> function to be used without closing - sessions for other callers of the same PKCS#11 module.</para> - </listitem> - <listitem> - <para>Managed modules have ability to log PKCS#11 method calls for debugging - purposes. See the <link linkend="option-log-calls"><literal>log-calls = yes</literal></link> - module configuration option.</para> - </listitem> - <listitem> - <para>Managed modules have the ability to be remoted to another machine or - isolated in their own process. - See the <link linkend="option-remote"><literal>remote = ...</literal></link> - module configuration option.</para> - </listitem> - </itemizedlist> - </section> -</chapter> |