diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | doc/Makefile.am | 19 | ||||
| -rw-r--r-- | doc/p11-kit-config.xml | 166 | ||||
| -rw-r--r-- | doc/p11-kit-docs.sgml | 3 | ||||
| -rw-r--r-- | doc/p11-kit.xml | 5 | ||||
| -rw-r--r-- | doc/pkcs11.conf.xml | 207 |
6 files changed, 239 insertions, 162 deletions
@@ -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> |