diff options
| -rw-r--r-- | .gitignore | 2 | ||||
| -rw-r--r-- | Makefile.am | 2 | ||||
| -rw-r--r-- | configure.ac | 1 | ||||
| -rw-r--r-- | doc/Makefile.am | 22 | ||||
| -rw-r--r-- | doc/docbook-params.xsl | 39 | ||||
| -rw-r--r-- | doc/p11-kit-config.xml | 119 | ||||
| -rw-r--r-- | doc/p11-kit-multiple-problem.xml | 92 | ||||
| -rw-r--r-- | doc/p11-kit.xml | 11 |
8 files changed, 287 insertions, 1 deletions
@@ -6,6 +6,7 @@ *.gcda *.gcov *~ +*.html .deps .libs @@ -30,6 +31,7 @@ INSTALL libtool ltmain.sh m4 +makefile Makefile Makefile.in missing diff --git a/Makefile.am b/Makefile.am index 1d42904..e8f0c0c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,5 +1,5 @@ -SUBDIRS = po module tests po +SUBDIRS = module tests doc po ACLOCAL_AMFLAGS = -I m4 diff --git a/configure.ac b/configure.ac index 4cfc5d6..9f63f66 100644 --- a/configure.ac +++ b/configure.ac @@ -138,6 +138,7 @@ AC_CONFIG_FILES([Makefile module/p11-kit.pc po/Makefile.in tests/Makefile + doc/Makefile ]) AC_OUTPUT diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..52c269b --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,22 @@ + +# p11-kit-glue.xml + +PARTS = \ + p11-kit-config.xml \ + p11-kit-multiple-problem.xml + +BOOK = \ + p11-kit.xml + +DOCUMENTS = \ + html/p11-kit.html + +all-local: $(DOCUMENTS) + +html/p11-kit.html: $(BOOK) $(PARTS) + xmlto --skip-validation -vv html-nochunks -o html/ p11-kit.xml + +EXTRA_DIST = \ + $(BOOK) \ + $(PARTS) \ + docbook-params.xsl diff --git a/doc/docbook-params.xsl b/doc/docbook-params.xsl new file mode 100644 index 0000000..5d8591a --- /dev/null +++ b/doc/docbook-params.xsl @@ -0,0 +1,39 @@ +<?xml version="1.0"?> +<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> + +<!-- + Parameters for DocBook transformation. + + Copyright (C) 2009 Michael Leupold <lemma@confuego.org> + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA +--> + + <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"/> + + <xsl:param name="toc.max.depth">3</xsl:param> + <xsl:param name="generate.section.toc.level">0</xsl:param> + <xsl:param name="generate.toc"> + book toc + part nop + chapter toc + </xsl:param> + <xsl:param name="html.stylesheet">style.css</xsl:param> + <xsl:param name="funcsynopsis.style">ansi</xsl:param> + <xsl:param name="funcsynopsis.decoration">1</xsl:param> + <xsl:param name="refentry.generate.name">0</xsl:param> + <xsl:param name="refentry.generate.title">1</xsl:param> + +</xsl:stylesheet> diff --git a/doc/p11-kit-config.xml b/doc/p11-kit-config.xml new file mode 100644 index 0000000..851f5dc --- /dev/null +++ b/doc/p11-kit-config.xml @@ -0,0 +1,119 @@ +<?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="config"> + <title>PKCS#11 Configuration</title> + + <section id="config-introduction"> + <title>Consistent configuration</title> + + <para>In order for multiple applications on the user's desktop to use + PKCS#11 modules in a consistent manner, there must be a configuration + or registry to specify which modules to load and how to use them. The + PKCS#11 specification does not specify such a configuration standard. + </para> + + <para>Because of the multi-library module initialization problem, use of + PKCS#11 modules must be coordinated within an application. p11-kit + provides that coordination. Since coordination is required, it follows + that p11-kit can also implement a consistent module configuration. + </para> + </section> + + <section id="config-format"> + <title>File format</title> + + <para>A complete configuration consists of several files. These files are + text files. Since <literal>p11-kit</literal> is built to be used in all + sorts of environments and at very low levels of the software stack, we + cannot make use of high level configuration APIs that you may find on a + modern desktop.</para> + + <para>Each setting in the config file is specified consists of a name and + a value. The name is a simple string consisting of characters and dashes. + The name consists of alpha numeric characters, dot, hyphen and + underscore.</para> + + <para>The value is specified after the name on the same line, separated + from it by a a <literal>:</literal> colon. White space between the + name and value is ignored.</para> + + <para>Blank lines are ignored. White space at the beginning or end of + lines is stripped. Lines that begin with a <literal>#</literal> character + are ignored as comments. Comments are not recognized when they come after + a value on a line.</para> + + <para>A fictitious sample configuration file might look like:</para> + + <programlisting> + name:value + # Here is a comment + + setting.2: A long value with text. + x-custom : text + </programlisting> + + </section> + + <section id="config-module"> + <title>Module Configuration</title> + + <para>Each configured PKCS#11 module has its own config file. The + location(s) of these files are described below. Most importantly each + config file specifies the location of the PKCS#11 module to load. Each + module config file has the following fields:</para> + + <variablelist> + <varlistentry> + <term>module</term> + <listitem><para>The absolute path to the PKCS#11 module to load. + This should include an extension line <literal>.so</literal></para></listitem> + </varlistentry> + </variablelist> + + <para>Other fields may be present, but it is recommended that field names + that are not specified in this document start with a <literal>x-</literal> + prefix.</para> + </section> + + <section id="config-global"> + <title>Global Configuration</title> + + <para>A global configuration is also present. This file contains settings + that are not related to a single PKCS#11 module. The location(s) of the + global configuration are described below. The global configuration file + can contain the following fields:</para> + + <variablelist> + <varlistentry> + <term>user-config</term> + <listitem><para>This will be equal to one of the following values: + <literal>none</literal>, <literal>merge</literal>, + <literal>override</literal>.</para></listitem> + </varlistentry> + </variablelist> + + <para>Other fields may be present, but it is recommended that field names + that are not specified in this document start with a <literal>x-</literal> + prefix.</para> + </section> + + <section id="config-locations"> + <title>Configuration Files</title> + + <para>Each configured PKCS#11 module is has its own config file. These + files are placed in a directory. In addition a global config file exists. + There is a system configuration consisting of the various module config + files and a file for global configuration. Optionally each user can provide + additional configuration or override the system configuration.</para> + + <para>The system global configuration file is in + <literal>/etc/pkcs11/pkcs11.conf</literal> and the user global + configuration file is in <literal>~/.pkcs11/pkcs11.conf</literal> in the + user's home directory.</para> + + <para> + The module config files are located XXX> + </para> + </section> +</chapter> diff --git a/doc/p11-kit-multiple-problem.xml b/doc/p11-kit-multiple-problem.xml new file mode 100644 index 0000000..a1c19a7 --- /dev/null +++ b/doc/p11-kit-multiple-problem.xml @@ -0,0 +1,92 @@ +<?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>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 initialze) 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 initalized 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-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> +</chapter> diff --git a/doc/p11-kit.xml b/doc/p11-kit.xml new file mode 100644 index 0000000..6231800 --- /dev/null +++ b/doc/p11-kit.xml @@ -0,0 +1,11 @@ +<?xml version="1.0"?> +<book xml:id="index" xmlns="http://docbook.org/ns/docbook" version="5.0"> + + <xi:include href="p11-kit-multiple-problem.xml" xmlns:xi="http://www.w3.org/2001/XInclude"> + <xi:fallback/> + </xi:include> + <xi:include href="p11-kit-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude"> + <xi:fallback/> + </xi:include> + +</book>
\ No newline at end of file |