diff options
Diffstat (limited to 'doc/manual')
| -rw-r--r-- | doc/manual/Makefile.am | 4 | ||||
| -rw-r--r-- | doc/manual/p11-kit-docs.xml | 1 | ||||
| -rw-r--r-- | doc/manual/p11-kit-trust.xml | 5 | ||||
| -rw-r--r-- | doc/manual/p11-kit.xml | 145 | ||||
| -rw-r--r-- | doc/manual/trust.xml | 368 |
5 files changed, 384 insertions, 139 deletions
diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index ab73373..e839841 100644 --- 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 5acfb97..77ff318 100644 --- 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 4b3521a..dde614c 100644 --- 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 325f5db..bc618f9 100644 --- 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=<what></arg> - <arg choice="plain">--format=<type></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=<what></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=<type></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=<usage></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 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=<what></arg> + <arg choice="plain">--format=<type></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=<what></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=<usage></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=<what></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=<type></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=<usage></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&component=p11-kit">https://bugs.freedesktop.org/enter_bug.cgi?product=p11-glue&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> |