diff options
Diffstat (limited to 'doc/manual/pkcs11.conf.xml')
| -rw-r--r-- | doc/manual/pkcs11.conf.xml | 281 |
1 files changed, 0 insertions, 281 deletions
diff --git a/doc/manual/pkcs11.conf.xml b/doc/manual/pkcs11.conf.xml deleted file mode 100644 index ffd89a5..0000000 --- a/doc/manual/pkcs11.conf.xml +++ /dev/null @@ -1,281 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" - "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" -[ - <!ENTITY sysdir SYSTEM "sysdir.xml"> - <!ENTITY userdir SYSTEM "userdir.xml"> -]> - -<refentry id="pkcs11-conf"> - -<refentryinfo> - <title>pkcs11.conf</title> - <productname>p11-kit</productname> - <authorgroup> - <author> - <contrib>Maintainer</contrib> - <firstname>Stef</firstname> - <surname>Walter</surname> - <email>stef@thewalter.net</email> - </author> - </authorgroup> -</refentryinfo> - -<refmeta> - <refentrytitle>pkcs11.conf</refentrytitle> - <manvolnum>5</manvolnum> - <refmiscinfo class="manual">System Files</refmiscinfo> -</refmeta> - -<refnamediv> - <refname>pkcs11.conf</refname> - <refpurpose>Configuration files for PKCS#11 modules</refpurpose> -</refnamediv> - -<refsect1 id="pkcs11-conf-description"> - <title>Description</title> - <para>The <command>pkcs11.conf</command> configuration files are a standard - way to configure PKCS#11 modules.</para> -</refsect1> - -<refsect1 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 <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 module configuration file might look like:</para> -<programlisting> -module: module.so -# Here is a comment - -managed: true -setting.2: A long value with text. -x-custom : text -</programlisting> -</refsect1> - -<refsect1 id="config-module"> - <title>Module Configuration</title> - - <para>Each configured PKCS#11 module has its own config file. These files - can be <link linkend="config-locations">placed in various locations</link>.</para> - <para>The filename of the configuration file may consist of upper and lowercase letters - underscore, comma, dash and dots. The first characters needs to be an alphanumeric, - the filename should end with a <literal>.module</literal> extension.</para> - <para>Most importantly each config file specifies the path of the PKCS#11 module to - load. A module config file has the following fields:</para> - - <variablelist> - <varlistentry> - <term><option>module:</option></term> - <listitem> - <para>The filename of the PKCS#11 module to load. - This should include an extension like <literal>.so</literal></para> - <para>If this value is blank, then the module will be ignored. - This can be used in the user configs to override loading of a module - specified in the system configuration.</para> - - <para>If this is a relative path, then the module will be loaded - from the <link linkend="devel-paths-modules">default module directory</link>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>critical:</option></term> - <listitem> - <para>Set to <literal>yes</literal> if the module is critical and - required to load. If a critical module fails to load or initialize, - then the loading process for all registered modules will abort and - return an error code.</para> - - <para>This argument is optional and defaults to <literal>no</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>enable-in:</option></term> - <listitem> - <para>A comma and/or space separated list of names of programs that - this module should only be loaded in. The module will not be loaded - for other programs using p11-kit. The base name of the process executable - should be used here, for example - <literal>seahorse, ssh</literal>.</para> - <para>This is not a security feature. The argument is optional. If - not present, then any process will load the module.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>disable-in:</option></term> - <listitem> - <para>A comma and/or space separated list of names of programs that - this module should not be loaded in. The module will be loaded for any - other programs using p11-kit. The base name of the process - executable should be used here, for example - <literal>firefox, thunderbird-bin</literal>.</para> - <para>This is not a security feature. The argument is optional. If - not present, then any process will load the module.</para> - </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 optional 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 - returned to a caller of p11-kit, modules with a higher number are sorted - first. When applications search modules for certificates, keys and - trust policy information, this setting will affect what find - first.</para> - <para>This argument is optional, and defaults to zero. Modules - with the same <option>priority</option> option will be sorted - alphabetically.</para> - </listitem> - </varlistentry> - <varlistentry id="option-remote"> - <term><option>remote:</option></term> - <listitem> - <para>Instead of loading the PKCS#11 module locally, run the module - remotely.</para> - <para>Specify a command to run, prefixed with <literal>|</literal> a pipe. - The command must speak the p11-kit remoting protocol on its standard in - and standard out. For example:</para> -<programlisting> -remote: |ssh user@remote p11-kit remote /path/to/module.so -</programlisting> - <para>Other forms of remoting will appear in later p11-kit releases.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><option>trust-policy:</option></term> - <listitem> - <para>Set to <literal>yes</literal> to use use this module as a source - 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 optional and defaults to <literal>no</literal>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Do not specify both <literal>enable-in</literal> and <literal>disable-in</literal> - for the same module.</para> - - <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> -</refsect1> - -<refsect1 id="config-global"> - <title>Global Configuration</title> - - <para>A global configuration may also be 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><option>user-config:</option></term> - <listitem><para>This will be equal to one of the following values: - <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 optional.</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 - that are not specified in this document start with a <literal>x-</literal> - prefix.</para> -</refsect1> - -<refsect1 id="config-locations"> - <title>Configuration Files</title> - - <para>Each configured PKCS#11 module 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 usually in - <literal>&sysdir;/pkcs11.conf</literal> and the user global - configuration file is in <literal>&userdir;/pkcs11.conf</literal> in the - user's home directory.</para> - - <para>The module config files are usually located in the - <literal>&sysdir;/modules</literal> directory, with one configuration - file per module. In addition the <literal>&userdir;/modules</literal> directory - can be used for modules installed by the user.</para> - - <para>Note that user configuration files are not loaded from the home - directory if running inside a setuid or setgid program.</para> - - <para>The default system config file and module directory can be changed - when building p11-kit. Always - <link linkend="devel-paths">lookup these paths</link> using - <literal>pkg-config</literal>.</para> -</refsect1> - -<refsect1 id="pkcs11-conf-see-also"> - <title>See also</title> - <simplelist type="inline"> - <member><citerefentry><refentrytitle>p11-kit</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> - </simplelist> - <para>Further details available in the p11-kit online documentation at - <ulink url="http://p11-glue.freedesktop.org/doc/p11-kit/">http://p11-glue.freedesktop.org/doc/p11-kit/</ulink>. - </para> -</refsect1> - -</refentry> |