summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--.gitignore1
-rw-r--r--doc/Makefile.am19
-rw-r--r--doc/p11-kit-config.xml166
-rw-r--r--doc/p11-kit-docs.sgml3
-rw-r--r--doc/p11-kit.xml5
-rw-r--r--doc/pkcs11.conf.xml207
6 files changed, 239 insertions, 162 deletions
diff --git a/.gitignore b/.gitignore
index d0abc67..ee5c6b3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -73,6 +73,7 @@ temp.txt
/doc/tmpl/
/doc/version.xml
/doc/xml/
+/doc/*.5
/doc/*.8
/p11-kit/p11-kit.pc
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 4fd8d54..b27980e 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -89,8 +89,8 @@ GTKDOC_LIBS=
include $(top_srcdir)/gtk-doc.make
if ENABLE_GTK_DOC
-man8_MANS = \
- p11-kit.8
+man8_MANS = p11-kit.8
+man5_MANS = pkcs11.conf.5
XSLTPROC_FLAGS = \
--nonet \
@@ -100,22 +100,33 @@ XSLTPROC_FLAGS = \
--stringparam man.authors.section.enabled 0 \
--stringparam man.copyright.section.enabled 0
+XSLTPROC_MAN = \
+ $(XSLTPROC) $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
+
+.xml.5:
+ $(AM_V_GEN) $(XSLTPROC_MAN) $<
.xml.8:
- $(AM_V_GEN) $(XSLTPROC) $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
+ $(AM_V_GEN) $(XSLTPROC_MAN) $<
else # ENABLE_GTK_DOC
+man5_MANS =
man8_MANS =
endif # ENABLE_GTK_DOC
-MAN_IN_FILES = $(man8_MANS:.8=.xml)
+MAN_IN_FILES = \
+ $(man8_MANS:.8=.xml) \
+ $(man5_MANS:.5=.xml) \
+ $(NULL)
CLEANFILES += \
+ $(man5_MANS) \
$(man8_MANS) \
$(NULL)
EXTRA_DIST += \
+ $(MAN_IN_FILES) \
version.xml.in \
version.xml \
$(NULL)
diff --git a/doc/p11-kit-config.xml b/doc/p11-kit-config.xml
index da413e0..ca07769 100644
--- a/doc/p11-kit-config.xml
+++ b/doc/p11-kit-config.xml
@@ -75,162 +75,16 @@ critical: yes
</section>
- <section id="config-format">
- <title>File format</title>
+<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>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 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. 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>module:</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>critical:</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>enable-in:</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>disable-in:</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>trust-policy</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>
- </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>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>
- </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 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>
- </section>
+ <para><link linkend="pkcs11.conf">See the manual page</link> for more details
+ on the format and available options.</para>
+</section>
</chapter>
diff --git a/doc/p11-kit-docs.sgml b/doc/p11-kit-docs.sgml
index 7138690..0397169 100644
--- a/doc/p11-kit-docs.sgml
+++ b/doc/p11-kit-docs.sgml
@@ -16,8 +16,9 @@
<xi:include href="p11-kit-trust.xml"/>
<chapter xml:id="tools">
- <title>Command Line Tools</title>
+ <title>Manual Pages</title>
<xi:include href="p11-kit.xml"/>
+ <xi:include href="pkcs11.conf.xml"/>
</chapter>
<chapter xml:id="reference">
diff --git a/doc/p11-kit.xml b/doc/p11-kit.xml
index 98f5da5..95b1c3e 100644
--- a/doc/p11-kit.xml
+++ b/doc/p11-kit.xml
@@ -217,7 +217,10 @@ $ p11-kit extract-trust
<refsect1>
<title>See also</title>
- <para>
+ <simplelist type="inline">
+ <member><citerefentry><refentrytitle>pkcs11.conf</refentrytitle><manvolnum>5</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>
diff --git a/doc/pkcs11.conf.xml b/doc/pkcs11.conf.xml
new file mode 100644
index 0000000..974cdf6
--- /dev/null
+++ b/doc/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>module:</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>critical:</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>enable-in:</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>disable-in:</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>trust-policy</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>user-config:</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>