trust: Document the new command line trust tool

diff --git a/.gitignore b/.gitignore
index df18e5f71cd25c8d884d6f29d24ecc35f62dc749..d8c00479669334eae8e3e54a5c250d5ddc3027ca 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -84,6 +84,7 @@ x86_64-w64-mingw32
 /doc/manual/userdir.xml
 /doc/manual/version.xml
 /doc/manual/xml/
+/doc/manual/*.1
 /doc/manual/*.5
 /doc/manual/*.8
 

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index ab73373f7c211dd1f88045fbe63bc83c6c452a89..e839841924d564257c26841a2201c3dd31cad980 100644 (file)
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -114,6 +114,7 @@ version.xml:
 include $(top_srcdir)/gtk-doc.make
 
 if ENABLE_GTK_DOC
+man1_MANS = trust.1
 man8_MANS = p11-kit.8
 man5_MANS = pkcs11.conf.5
 
@@ -128,6 +129,8 @@ XSLTPROC_FLAGS = \
 XSLTPROC_MAN = \
        $(XSLTPROC) $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
 
+.xml.1:
+       $(AM_V_GEN) $(XSLTPROC_MAN) $<
 .xml.5:
        $(AM_V_GEN) $(XSLTPROC_MAN) $<
 .xml.8:
@@ -135,6 +138,7 @@ XSLTPROC_MAN = \
 
 else # ENABLE_GTK_DOC
 
+man1_MANS =
 man5_MANS =
 man8_MANS =
 

diff --git a/doc/manual/p11-kit-docs.xml b/doc/manual/p11-kit-docs.xml
index 5acfb97d0ccc9157f3d84b3a7a0c81746c346cdd..77ff3184fa4a4333a06fe452e0bc37c1f607a46b 100644 (file)
--- a/doc/manual/p11-kit-docs.xml
+++ b/doc/manual/p11-kit-docs.xml
@@ -20,6 +20,7 @@
                <title>Manual Pages</title>
                <xi:include href="p11-kit.xml"/>
                <xi:include href="pkcs11.conf.xml"/>
+               <xi:include href="trust.xml"/>
        </chapter>
 
        <chapter xml:id="reference">

diff --git a/doc/manual/p11-kit-trust.xml b/doc/manual/p11-kit-trust.xml
index 4b3521a89f5f8a51b80195531b703a9f4243d07c..dde614cee4e3da01bb5c4427e9d2d9dbb8ee925f 100644 (file)
--- a/doc/manual/p11-kit-trust.xml
+++ b/doc/manual/p11-kit-trust.xml
@@ -6,13 +6,16 @@
   <!ENTITY userdir SYSTEM "userdir.xml">
 ]>
 
-<chapter xml:id="trust">
+<chapter xml:id="trust-module">
 <title>Trust Policy Module</title>
 
        <para>The trust module provides system certificate anchors, blacklists
        and other trust policy to crypto libraries applications. This
        information is exposed as PKCS#11 objects.</para>
 
+       <para>You can use the <link linkend="trust">trust</link> command line
+       tool to examine and modify the trust policy store.</para>
+
 <section id="trust-files">
        <title>Paths loaded by the Module</title>
 

diff --git a/doc/manual/p11-kit.xml b/doc/manual/p11-kit.xml
index 325f5db756e15ce6ccbe46981b8a9533e8b1c38e..bc618f9d88d6b479f30a39ddc8c7233c223c566a 100644 (file)
--- a/doc/manual/p11-kit.xml
+++ b/doc/manual/p11-kit.xml
@@ -33,8 +33,7 @@
                <command>p11-kit list-modules</command>
        </cmdsynopsis>
        <cmdsynopsis>
-               <command>p11-kit extract</command> <arg choice="plain">--filter=&lt;what&gt;</arg>
-                       <arg choice="plain">--format=&lt;type&gt;</arg> /path/to/destination
+               <command>p11-kit extract</command> ...
        </cmdsynopsis>
 </refsynopsisdiv>
 
@@ -81,128 +80,8 @@ $ p11-kit list-modules
 
        <para>Extract certificates from configured PKCS#11 modules.</para>
 
-<programlisting>
-$ p11-kit extract --format=x509-directory --filter=ca-anchors /path/to/directory
-</programlisting>
-
-       <para>You can specify the following options to control what to extract.
-       The <option>--filter</option> and <option>--format</option> arguments
-       should be specified. By default this command will not overwrite the
-       destination file or directory.</para>
-
-       <variablelist>
-               <varlistentry>
-                       <term><option>--comment</option></term>
-                       <listitem><para>Add identifying comments to PEM bundle output files
-                       before each certificate.</para></listitem>
-               </varlistentry>
-               <varlistentry>
-                       <term><option>--filter=&lt;what&gt;</option></term>
-                       <listitem>
-                       <para>Specifies what certificates to extract. You can specify the following values:
-                       <variablelist>
-                               <varlistentry>
-                                       <term><option>ca-anchors</option></term>
-                                       <listitem><para>Certificate anchors (default)</para></listitem>
-                               </varlistentry>
-                               <varlistentry>
-                                       <term><option>trust-policy</option></term>
-                                       <listitem><para>Anchors and blacklist</para></listitem>
-                               </varlistentry>
-                               <varlistentry>
-                                       <term><option>blacklist</option></term>
-                                       <listitem><para>Blacklisted certificates</para></listitem>
-                               </varlistentry>
-                               <varlistentry>
-                                       <term><option>certificates</option></term>
-                                       <listitem><para>All certificates</para></listitem>
-                               </varlistentry>
-                               <varlistentry>
-                                       <term><option>pkcs11:object=xx</option></term>
-                                       <listitem><para>A PKCS#11 URI</para></listitem>
-                               </varlistentry>
-                       </variablelist>
-                       </para>
-
-                       <para>If an output format is chosen that cannot support type what has been
-                       specified by the filter, a message will be printed.</para>
-
-                       <para>None of the available formats support storage of blacklist entries
-                       that do not contain a full certificate. Thus any certificates blacklisted by
-                       their issuer and serial number alone, are not included in the extracted
-                       blacklist.</para>
-                       </listitem>
-               </varlistentry>
-               <varlistentry>
-                       <term><option>--format=&lt;type&gt;</option></term>
-                       <listitem><para>The format of the destination file or directory.
-                       You can specify one of the following values:
-                       <variablelist>
-                               <varlistentry>
-                                       <term><option>x509-file</option></term>
-                                       <listitem><para>DER X.509 certificate file</para></listitem>
-                               </varlistentry>
-                               <varlistentry>
-                                       <term><option>x509-directory</option></term>
-                                       <listitem><para>directory of X.509 certificates</para></listitem>
-                               </varlistentry>
-                               <varlistentry>
-                                       <term><option>pem-bundle</option></term>
-                                       <listitem><para>File containing one or more certificate PEM blocks</para></listitem>
-                               </varlistentry>
-                               <varlistentry>
-                                       <term><option>pem-directory</option></term>
-                                       <listitem><para>Directory PEM files each containing one certifiacte</para></listitem>
-                               </varlistentry>
-                               <varlistentry>
-                                       <term><option>openssl-bundle</option></term>
-                                       <listitem><para>OpenSSL specific PEM bundle of certificates</para></listitem>
-                               </varlistentry>
-                               <varlistentry>
-                                       <term><option>openssl-directory</option></term>
-                                       <listitem><para>Directory of OpenSSL specific PEM files</para></listitem>
-                               </varlistentry>
-                               <varlistentry>
-                                       <term><option>java-cacerts</option></term>
-                                       <listitem><para>Java keystore 'cacerts' certificate bundle</para></listitem>
-                               </varlistentry>
-                       </variablelist>
-                       </para></listitem>
-               </varlistentry>
-               <varlistentry>
-                       <term><option>--overwrite</option></term>
-                       <listitem><para>Overwrite output file or directory.</para></listitem>
-               </varlistentry>
-               <varlistentry>
-                       <term><option>--purpose=&lt;usage&gt;</option></term>
-                       <listitem><para>Limit to certificates usable for the given purpose
-                       You can specify one of the following values:
-                       <variablelist>
-                               <varlistentry>
-                                       <term><option>server-auth</option></term>
-                                       <listitem><para>For authenticating servers</para></listitem>
-                               </varlistentry>
-                               <varlistentry>
-                                       <term><option>client-auth</option></term>
-                                       <listitem><para>For authenticating clients</para></listitem>
-                               </varlistentry>
-                               <varlistentry>
-                                       <term><option>email</option></term>
-                                       <listitem><para>For email protection</para></listitem>
-                               </varlistentry>
-                               <varlistentry>
-                                       <term><option>code-signing</option></term>
-                                       <listitem><para>For authenticated signed code</para></listitem>
-                               </varlistentry>
-                               <varlistentry>
-                                       <term><option>1.2.3.4.5...</option></term>
-                                       <listitem><para>An arbitrary purpose OID</para></listitem>
-                               </varlistentry>
-                       </variablelist>
-                       </para></listitem>
-               </varlistentry>
-       </variablelist>
-
+       <para>See <member><citerefentry><refentrytitle>trust</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+       for more information</para>
 </refsect1>
 
 <refsect1 id="p11-kit-extract-trust">
@@ -210,21 +89,11 @@ $ p11-kit extract --format=x509-directory --filter=ca-anchors /path/to/directory
 
        <para>Extract standard trust information files.</para>
 
-<programlisting>
-$ p11-kit extract-trust
-</programlisting>
-
-       <para>OpenSSL, GnuTLS and Java cannot currently read trust information
-       directly from the trust policy module. This command extracts trust
-       information such as certificate anchors for use by these libraries.</para>
-
-       <para>What this command does, and where it extracts the files is
-       distribution or site specific. Packagers or administrators are expected
-       customize this command.</para>
-
+       <para>See <citerefentry><refentrytitle>trust</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+       for more information</para>
 </refsect1>
 
-<refsect1 id="p11-kit-extract-bugs">
+<refsect1 id="p11-kit-bugs">
   <title>Bugs</title>
   <para>
     Please send bug reports to either the distribution bug tracker
@@ -233,7 +102,7 @@ $ p11-kit extract-trust
   </para>
 </refsect1>
 
-<refsect1 id="p11-kit-extract-see-also">
+<refsect1 id="p11-kit-see-also">
   <title>See also</title>
     <simplelist type="inline">
         <member><citerefentry><refentrytitle>pkcs11.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>

diff --git a/doc/manual/trust.xml b/doc/manual/trust.xml
new file mode 100644 (file)
index 0000000..efb66c1
--- /dev/null
+++ b/doc/manual/trust.xml
@@ -0,0 +1,368 @@
+<?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">
+
+<refentry id="trust">
+
+<refentryinfo>
+       <title>trust</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>trust</refentrytitle>
+       <manvolnum>1</manvolnum>
+       <refmiscinfo class="manual">User Commands</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+       <refname>trust</refname>
+       <refpurpose>Tool for operating on the trust policy store</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+       <cmdsynopsis>
+               <command>trust list</command>
+       </cmdsynopsis>
+       <cmdsynopsis>
+               <command>trust extract</command> <arg choice="plain">--filter=&lt;what&gt;</arg>
+                       <arg choice="plain">--format=&lt;type&gt;</arg> /path/to/destination
+       </cmdsynopsis>
+       <cmdsynopsis>
+               <command>trust anchor</command> /path/to/certificate.crt
+       </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1 id="trust-description">
+       <title>Description</title>
+       <para><command>trust</command> is a command line tool to examine and
+       modify the shared trust policy store.</para>
+
+       <para>See the various sub commands below. The following global options
+       can be used:</para>
+
+       <variablelist>
+               <varlistentry>
+                       <term><option>-v, --verbose</option></term>
+                       <listitem><para>Run in verbose mode with debug
+                       output.</para></listitem>
+               </varlistentry>
+               <varlistentry>
+                       <term><option>-q, --quiet</option></term>
+                       <listitem><para>Run in quiet mode without warning or
+                       failure messages.</para></listitem>
+               </varlistentry>
+       </variablelist>
+
+</refsect1>
+
+<refsect1 id="trust-list">
+       <title>List</title>
+
+       <para>List trust policy store items.</para>
+
+<programlisting>
+$ trust list
+</programlisting>
+
+       <para>List information about the various items in the trust policy store.
+       Each item is listed with it's PKCS#11 URI and some descriptive information.</para>
+
+       <para>You can specify the following options to control what to list.</para>
+
+       <varlistentry>
+               <term><option>--filter=&lt;what&gt;</option></term>
+               <listitem>
+               <para>Specifies what certificates to extract. You can specify the following values:
+               <variablelist>
+                       <varlistentry>
+                               <term><option>ca-anchors</option></term>
+                               <listitem><para>Certificate anchors</para></listitem>
+                       </varlistentry>
+                       <varlistentry>
+                               <term><option>trust-policy</option></term>
+                               <listitem><para>Anchors and blacklist (default)</para></listitem>
+                       </varlistentry>
+                       <varlistentry>
+                               <term><option>blacklist</option></term>
+                               <listitem><para>Blacklisted certificates</para></listitem>
+                       </varlistentry>
+                       <varlistentry>
+                               <term><option>certificates</option></term>
+                               <listitem><para>All certificates</para></listitem>
+                       </varlistentry>
+                       <varlistentry>
+                               <term><option>pkcs11:object=xx</option></term>
+                               <listitem><para>A PKCS#11 URI to filter with</para></listitem>
+                       </varlistentry>
+               </variablelist>
+               </para>
+
+               <para>If an output format is chosen that cannot support type what has been
+               specified by the filter, a message will be printed.</para>
+
+               <para>None of the available formats support storage of blacklist entries
+               that do not contain a full certificate. Thus any certificates blacklisted by
+               their issuer and serial number alone, are not included in the extracted
+               blacklist.</para>
+               </listitem>
+       </varlistentry>
+       <varlistentry>
+               <term><option>--purpose=&lt;usage&gt;</option></term>
+               <listitem><para>Limit to certificates usable for the given purpose
+               You can specify one of the following values:
+               <variablelist>
+                       <varlistentry>
+                               <term><option>server-auth</option></term>
+                               <listitem><para>For authenticating servers</para></listitem>
+                       </varlistentry>
+                       <varlistentry>
+                               <term><option>client-auth</option></term>
+                               <listitem><para>For authenticating clients</para></listitem>
+                       </varlistentry>
+                       <varlistentry>
+                               <term><option>email</option></term>
+                               <listitem><para>For email protection</para></listitem>
+                       </varlistentry>
+                       <varlistentry>
+                               <term><option>code-signing</option></term>
+                               <listitem><para>For authenticated signed code</para></listitem>
+                       </varlistentry>
+                       <varlistentry>
+                               <term><option>1.2.3.4.5...</option></term>
+                               <listitem><para>An arbitrary purpose OID</para></listitem>
+                       </varlistentry>
+               </variablelist>
+               </para></listitem>
+       </varlistentry>
+
+</refsect1>
+
+<refsect1 id="trust-anchor">
+       <title>Anchor</title>
+
+       <para>Store or remove trust anchors.</para>
+
+<programlisting>
+$ trust anchor /path/to/certificate.crt
+$ trust anchor --remove /path/to/certificate.crt
+$ trust anchor --remove "pkcs11:id=%AA%BB%CC%DD%EE;object-type=cert"
+</programlisting>
+
+       <para>Store or remove trust anchors in the trust policy store. These are
+       usually root certificate authorities.</para>
+
+       <para>Specify either the <option>--store</option> or <option>--remove</option>
+       operations. If no operation is specified then <option>--store</option> is
+       assumed.</para>
+
+       <para>When storing, one or more certificate files are expected on the
+       command line. These are stored as anchors, unless they are already
+       present.</para>
+
+       <para>When removing an anchor, either specify certificate files or
+       PKCS#11 URI's on the command line. Matching anchors will be removed.</para>
+
+       <para>It may be that this command needs to be run as root in order to
+       modify the system trust policy store, if no user specific store is
+       available.</para>
+
+       <para>You can specify the following options.</para>
+
+       <variablelist>
+               <varlistentry>
+                       <term><option>--remove</option></term>
+                       <listitem><para>Remove one or more anchors from the trust
+                       policy store. Specify certificate files or PKCS#11 URI's
+                       on the command line.</para></listitem>
+               </varlistentry>
+               <varlistentry>
+                       <term><option>--store</option></term>
+                       <listitem><para>Store one or more anchors to the trust
+                       policy store. Specify certificate files on the command
+                       line.</para></listitem>
+               </varlistentry>
+       </variablelist>
+
+</refsect1>
+
+<refsect1 id="trust-extract">
+       <title>Extract</title>
+
+       <para>Extract trust policy from the shared trust policy store.</para>
+
+<programlisting>
+$ trust extract --format=x509-directory --filter=ca-anchors /path/to/directory
+</programlisting>
+
+       <para>You can specify the following options to control what to extract.
+       The <option>--filter</option> and <option>--format</option> arguments
+       should be specified. By default this command will not overwrite the
+       destination file or directory.</para>
+
+       <variablelist>
+               <varlistentry>
+                       <term><option>--comment</option></term>
+                       <listitem><para>Add identifying comments to PEM bundle output files
+                       before each certificate.</para></listitem>
+               </varlistentry>
+               <varlistentry>
+                       <term><option>--filter=&lt;what&gt;</option></term>
+                       <listitem>
+                       <para>Specifies what certificates to extract. You can specify the following values:
+                       <variablelist>
+                               <varlistentry>
+                                       <term><option>ca-anchors</option></term>
+                                       <listitem><para>Certificate anchors (default)</para></listitem>
+                               </varlistentry>
+                               <varlistentry>
+                                       <term><option>trust-policy</option></term>
+                                       <listitem><para>Anchors and blacklist</para></listitem>
+                               </varlistentry>
+                               <varlistentry>
+                                       <term><option>blacklist</option></term>
+                                       <listitem><para>Blacklisted certificates</para></listitem>
+                               </varlistentry>
+                               <varlistentry>
+                                       <term><option>certificates</option></term>
+                                       <listitem><para>All certificates</para></listitem>
+                               </varlistentry>
+                               <varlistentry>
+                                       <term><option>pkcs11:object=xx</option></term>
+                                       <listitem><para>A PKCS#11 URI</para></listitem>
+                               </varlistentry>
+                       </variablelist>
+                       </para>
+
+                       <para>If an output format is chosen that cannot support type what has been
+                       specified by the filter, a message will be printed.</para>
+
+                       <para>None of the available formats support storage of blacklist entries
+                       that do not contain a full certificate. Thus any certificates blacklisted by
+                       their issuer and serial number alone, are not included in the extracted
+                       blacklist.</para>
+                       </listitem>
+               </varlistentry>
+               <varlistentry>
+                       <term><option>--format=&lt;type&gt;</option></term>
+                       <listitem><para>The format of the destination file or directory.
+                       You can specify one of the following values:
+                       <variablelist>
+                               <varlistentry>
+                                       <term><option>x509-file</option></term>
+                                       <listitem><para>DER X.509 certificate file</para></listitem>
+                               </varlistentry>
+                               <varlistentry>
+                                       <term><option>x509-directory</option></term>
+                                       <listitem><para>directory of X.509 certificates</para></listitem>
+                               </varlistentry>
+                               <varlistentry>
+                                       <term><option>pem-bundle</option></term>
+                                       <listitem><para>File containing one or more certificate PEM blocks</para></listitem>
+                               </varlistentry>
+                               <varlistentry>
+                                       <term><option>pem-directory</option></term>
+                                       <listitem><para>Directory PEM files each containing one certifiacte</para></listitem>
+                               </varlistentry>
+                               <varlistentry>
+                                       <term><option>openssl-bundle</option></term>
+                                       <listitem><para>OpenSSL specific PEM bundle of certificates</para></listitem>
+                               </varlistentry>
+                               <varlistentry>
+                                       <term><option>openssl-directory</option></term>
+                                       <listitem><para>Directory of OpenSSL specific PEM files</para></listitem>
+                               </varlistentry>
+                               <varlistentry>
+                                       <term><option>java-cacerts</option></term>
+                                       <listitem><para>Java keystore 'cacerts' certificate bundle</para></listitem>
+                               </varlistentry>
+                       </variablelist>
+                       </para></listitem>
+               </varlistentry>
+               <varlistentry>
+                       <term><option>--overwrite</option></term>
+                       <listitem><para>Overwrite output file or directory.</para></listitem>
+               </varlistentry>
+               <varlistentry>
+                       <term><option>--purpose=&lt;usage&gt;</option></term>
+                       <listitem><para>Limit to certificates usable for the given purpose
+                       You can specify one of the following values:
+                       <variablelist>
+                               <varlistentry>
+                                       <term><option>server-auth</option></term>
+                                       <listitem><para>For authenticating servers</para></listitem>
+                               </varlistentry>
+                               <varlistentry>
+                                       <term><option>client-auth</option></term>
+                                       <listitem><para>For authenticating clients</para></listitem>
+                               </varlistentry>
+                               <varlistentry>
+                                       <term><option>email</option></term>
+                                       <listitem><para>For email protection</para></listitem>
+                               </varlistentry>
+                               <varlistentry>
+                                       <term><option>code-signing</option></term>
+                                       <listitem><para>For authenticated signed code</para></listitem>
+                               </varlistentry>
+                               <varlistentry>
+                                       <term><option>1.2.3.4.5...</option></term>
+                                       <listitem><para>An arbitrary purpose OID</para></listitem>
+                               </varlistentry>
+                       </variablelist>
+                       </para></listitem>
+               </varlistentry>
+       </variablelist>
+
+</refsect1>
+
+<refsect1 id="trust-extract-compat">
+       <title>Extract Compat</title>
+
+       <para>Extract compatibility trust certificate bundles.</para>
+
+<programlisting>
+$ trust extract-compat
+</programlisting>
+
+       <para>OpenSSL, Java and some versions of GnuTLS cannot currently read
+       trust information directly from the trust policy store. This command
+       extracts trust information such as certificate anchors for use by
+       these libraries.</para>
+
+       <para>What this command does, and where it extracts the files is
+       distribution or site specific. Packagers or administrators are expected
+       customize this command.</para>
+
+</refsect1>
+
+<refsect1 id="trust-bugs">
+  <title>Bugs</title>
+  <para>
+    Please send bug reports to either the distribution bug tracker
+    or the upstream bug tracker at
+    <ulink url="https://bugs.freedesktop.org/enter_bug.cgi?product=p11-glue&amp;component=p11-kit">https://bugs.freedesktop.org/enter_bug.cgi?product=p11-glue&amp;component=p11-kit</ulink>.
+  </para>
+</refsect1>
+
+<refsect1 id="trust-see-also">
+  <title>See also</title>
+    <simplelist type="inline">
+        <member><citerefentry><refentrytitle>p11-kit</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+    </simplelist>
+    <para>An explanatory document about storing trust policy:
+    <ulink url="http://p11-glue.freedesktop.org/doc/storing-trust-policy/">http://p11-glue.freedesktop.org/doc/storing-trust-policy/</ulink></para>
+    <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>