doc: Move manual into doc/manual subdirectory

1 files changed, 207 insertions, 0 deletions

diff --git a/doc/manual/pkcs11.conf.xml b/doc/manual/pkcs11.conf.xml
new file mode 100644
index 0000000..3146f60
--- /dev/null
+++ b/doc/manual/pkcs11.conf.xml
@@ -0,0 +1,207 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<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>
+	<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>trust-policy:</option></term>
+		<listitem>
+			<para>If this setting is present then this module is used to load
+			trust policy information such as certificate anchors and black lists.
+			The value should be an integer. Modules with a lower number are loaded
+			first. Trust policy information in modules loaded later overrides
+			those loaded first.</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>
+	</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 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 usually 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 usually located in the
+	<literal>/etc/pkcs11/modules</literal> directory, with one configuration
+	file per module. In addition the <literal>~/.pkcs11/modules</literal> directory
+	can be used for modules installed by the user.</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>
+	<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>