diff options
Diffstat (limited to 'doc/p11-kit-config.xml')
| -rw-r--r-- | doc/p11-kit-config.xml | 119 |
1 files changed, 119 insertions, 0 deletions
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> |