doc: Move manual into doc/manual subdirectory

1 files changed, 90 insertions, 0 deletions

diff --git a/doc/manual/p11-kit-config.xml b/doc/manual/p11-kit-config.xml
new file mode 100644
index 0000000..ca07769
--- /dev/null
+++ b/doc/manual/p11-kit-config.xml
@@ -0,0 +1,90 @@
+<?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-example">
+		<title>Example</title>
+
+		<para>The following sections describe the config format in detail. But first
+		an example which shows the various features. The configuration below, loads
+		two modules called 'my-module' and 'nss'. The user settings override some
+		aspects of the system settings.</para>
+
+<para>Global configuration file: <literal>/etc/pkcs11/pkcs11.conf</literal></para>
+<programlisting>
+# This setting controls whether to load user configuration from the
+# ~/.pkcs11 directory. Possible values:
+#    none: No user configuration
+#    merge: Merge the user config over the system configuration (default)
+#    only: Only user configuration, ignore system configuration
+user-config: merge
+</programlisting>
+
+<para>One module configuration file per module: <literal>/etc/pkcs11/modules/my-module</literal></para>
+<programlisting>
+# This setting controls the actual module library to load. This config file
+# might be installed by the package that installs this module library. This
+# is not an absolute path name. Relative path names are loaded from the
+# $(libdir)/pkcs11 directory by default.
+module: my-pkcs11-module.so
+
+# This controls whether the module is required to successfully initialize. If 'yes', then
+# a failure to load or initialize this module will result in a p11-kit system failure.
+critical: no
+</programlisting>
+
+<para>User configuration file: <literal>~/.pkcs11/pkcs11.conf</literal></para>
+<programlisting>
+# This is an empty file. Files that do not exist are treated as empty.
+</programlisting>
+
+<para>User configuration file: <literal>~/.pkcs11/modules/my-module</literal></para>
+<programlisting>
+# Merge with the settings in the system my-module config file. In this case
+# a developer has overridden to load a different module for my-module instead.
+module: /home/user/src/custom-module/my-module.so
+</programlisting>
+
+<para>User configuration file: <literal>~/.pkcs11/modules/nss</literal></para>
+<programlisting>
+# Load the NSS libsoftokn.so.3 PKCS#11 library as a module. Note that we pass
+# some custom non-standard initialization arguments, as NSS expects.
+module: /usr/lib/libsoftokn3.so
+x-init-reserved: configdir='sql:/home/test/.pki/nssdb' certPrefix='' keyPrefix='' secmod='socmod.db'
+critical: yes
+</programlisting>
+
+
+</section>
+
+<section>
+	<title>Configuration Files</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><link linkend="pkcs11.conf">See the manual page</link> for more details
+	on the format and available options.</para>
+</section>
+</chapter>