diff options
Diffstat (limited to 'doc/manual')
| -rw-r--r-- | doc/manual/Makefile.am | 9 | ||||
| -rw-r--r-- | doc/manual/p11-kit-devel.xml | 3 | ||||
| -rw-r--r-- | doc/manual/p11-kit-docs.xml | 2 | ||||
| -rw-r--r-- | doc/manual/p11-kit-proxy.xml | 29 | ||||
| -rw-r--r-- | doc/manual/p11-kit-sections.txt | 41 | ||||
| -rw-r--r-- | doc/manual/p11-kit-sharing.xml | 105 | ||||
| -rw-r--r-- | doc/manual/pkcs11.conf.xml | 43 |
7 files changed, 173 insertions, 59 deletions
diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index cf4e49d..e306fb1 100644 --- a/doc/manual/Makefile.am +++ b/doc/manual/Makefile.am @@ -52,14 +52,18 @@ IGNORE_HFILES= \ conf.h \ debug.h \ dict.h \ - mock-module.h \ + log.h \ + mock.h \ + modules.h \ pkcs11.h \ pkcs11x.h \ private.h \ + proxy.h \ util.h \ + virtual.h \ array.h \ compat.h \ - mock-module.h + $(NULL) # Images to copy into HTML directory. # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png @@ -69,6 +73,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-devel.xml b/doc/manual/p11-kit-devel.xml index 96db868..873aff1 100644 --- a/doc/manual/p11-kit-devel.xml +++ b/doc/manual/p11-kit-devel.xml @@ -149,6 +149,9 @@ $ make install during the build, then certain features will be disabled.</para> <itemizedlist> + <listitem><para><command>libffi1</command> for shoring of PKCS#11 modules + between multiple callers in the same process. It is highly recommended that + this dependency be treated as a required dependency.</para></listitem> <listitem><para><command>gtk-doc</command> is required to build the reference manual. Use <literal>--enable-doc</literal> to control this dependency.</para></listitem> 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 @@ <xi:include href="p11-kit-config.xml"/> <xi:include href="p11-kit-sharing.xml"/> + <xi:include href="p11-kit-proxy.xml"/> <xi:include href="p11-kit-trust.xml"/> <chapter xml:id="tools"> @@ -28,6 +29,7 @@ <xi:include href="xml/p11-kit-pin.xml"/> <xi:include href="xml/p11-kit-util.xml"/> <xi:include href="xml/p11-kit-future.xml"/> + <xi:include href="xml/p11-kit-deprecated.xml"/> <index id="api-index-full"> <title>API Index</title> 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 @@ +<?xml version="1.0"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ +]> +<chapter xml:id="sharing"> + <title>Proxy Module</title> + + <para>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 + <literal>p11-kit</literal> and use the functions there to provide this + functionality.</para> + + <para>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, + <literal>p11-kit</literal> provides a proxy compatibility + module.</para> + + <para>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 <literal>p11-kit</literal> 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.</para> + + <para>The <literal>C_GetFunctionList</literal> 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.</para> +</chapter> diff --git a/doc/manual/p11-kit-sections.txt b/doc/manual/p11-kit-sections.txt index dc85f2d..5ccba7c 100644 --- a/doc/manual/p11-kit-sections.txt +++ b/doc/manual/p11-kit-sections.txt @@ -52,20 +52,28 @@ p11_kit_pin_file_callback <SECTION> <FILE>p11-kit</FILE> -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 </SECTION> <SECTION> <FILE>p11-kit-util</FILE> p11_kit_strerror +p11_kit_message p11_kit_space_strdup p11_kit_space_strlen <SUBSECTION Private> @@ -85,7 +93,6 @@ p11_kit_uri_type_t p11_kit_set_progname p11_kit_be_quiet p11_kit_be_loud -p11_kit_message p11_kit_destroyer P11KitIter p11_kit_iter_new @@ -104,3 +111,17 @@ p11_kit_iter_get_object p11_kit_iter_load_attributes p11_kit_iter_free </SECTION> + +<SECTION> +<FILE>p11-kit-deprecated</FILE> +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 +</SECTION> diff --git a/doc/manual/p11-kit-sharing.xml b/doc/manual/p11-kit-sharing.xml index e692e3d..bf0ed01 100644 --- a/doc/manual/p11-kit-sharing.xml +++ b/doc/manual/p11-kit-sharing.xml @@ -42,52 +42,63 @@ loosely coupled, backwards compatible, and flexible way.</para> </section> - <section xml:id="sharing-initialize"> - <title>Solution: p11-kit</title> - - <para><literal>p11-kit</literal> 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.</para> - - <para>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.</para> - - <para>This is done in a thread-safe manner. These functions can - be used on modules that the consumer loads themselves.</para> - </section> - - <section xml:id="sharing-module"> - <title>Solution: proxy module</title> - - <para>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.</para> - - <para>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, - <literal>p11-kit</literal> provides a proxy compatibility - module.</para> - - <para>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 - <literal>p11-kit</literal> 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.</para> - - <para>The proxy module bends the PKCS#11 rules slightly. It does - not return the <literal>CKR_CRYPTOKI_ALREADY_INITIALIZED</literal> - error code as specified in PKCS#11. However this is a small - price to pay for this compatibility.</para> + <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> + </itemizedlist> </section> </chapter> diff --git a/doc/manual/pkcs11.conf.xml b/doc/manual/pkcs11.conf.xml index 1814377..1ff2562 100644 --- a/doc/manual/pkcs11.conf.xml +++ b/doc/manual/pkcs11.conf.xml @@ -128,6 +128,16 @@ x-custom : text </listitem> </varlistentry> <varlistentry> + <term><option>managed:</option></term> + <listitem> + <para>Set to <literal>no</literal> 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.</para> + + <para>This argument is optonal and defaults to <literal>yes</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> <term><option>priority:</option></term> <listitem> <para>The value should be an integer. When lists of modules are @@ -147,6 +157,15 @@ x-custom : text of trust policy information such as certificate anchors and black lists.</para> </listitem> </varlistentry> + <varlistentry id="option-log-calls"> + <term>log-calls:</term> + <listitem> + <para>Set to <literal>yes</literal> to write a log to stderr of all the + calls into the module. This is only supported for managed modules.</para> + + <para>This argument is optonal and defaults to <literal>no</literal>.</para> + </listitem> + </varlistentry> </variablelist> <para>Do not specify both <literal>enable-in</literal> and <literal>disable-in</literal> @@ -172,6 +191,30 @@ x-custom : text <literal>none</literal>, <literal>merge</literal>, <literal>only</literal>.</para></listitem> </varlistentry> + <varlistentry> + <term><option>managed:</option></term> + <listitem> + <para>Set to <literal>yes</literal> or <literal>no</literal> to + force all modules to be managed or unmanaged by p11-kit. Setting this + setting in a global configuration file will override the + <literal>managed</literal> 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.</para> + + <para>This argument is optonal.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>log-calls:</term> + <listitem> + <para>Set to <literal>yes</literal> to write a log to stderr of all the + calls into all configured modules. This is only supported for managed + modules.</para> + + <para>This argument is optional.</para> + </listitem> + </varlistentry> </variablelist> <para>Other fields may be present, but it is recommended that field names |