From f2beacb7c59b9c4b41b00da993c747fd814882a8 Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Thu, 29 Aug 2013 11:46:08 +0200 Subject: trust: Document the new command line trust tool --- .gitignore | 1 + doc/manual/Makefile.am | 4 + doc/manual/p11-kit-docs.xml | 1 + doc/manual/p11-kit-trust.xml | 5 +- doc/manual/p11-kit.xml | 145 +---------------- doc/manual/trust.xml | 368 +++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 385 insertions(+), 139 deletions(-) create mode 100644 doc/manual/trust.xml diff --git a/.gitignore b/.gitignore index df18e5f..d8c0047 100644 --- 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 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 @@ Manual Pages + 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 @@ ]> - + Trust Policy Module The trust module provides system certificate anchors, blacklists and other trust policy to crypto libraries applications. This information is exposed as PKCS#11 objects. + You can use the trust command line + tool to examine and modify the trust policy store. +
Paths loaded by the Module 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 @@ p11-kit list-modules - p11-kit extract --filter=<what> - --format=<type> /path/to/destination + p11-kit extract ... @@ -81,128 +80,8 @@ $ p11-kit list-modules Extract certificates from configured PKCS#11 modules. - -$ p11-kit extract --format=x509-directory --filter=ca-anchors /path/to/directory - - - You can specify the following options to control what to extract. - The and arguments - should be specified. By default this command will not overwrite the - destination file or directory. - - - - - Add identifying comments to PEM bundle output files - before each certificate. - - - - - Specifies what certificates to extract. You can specify the following values: - - - - Certificate anchors (default) - - - - Anchors and blacklist - - - - Blacklisted certificates - - - - All certificates - - - - A PKCS#11 URI - - - - - If an output format is chosen that cannot support type what has been - specified by the filter, a message will be printed. - - 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. - - - - - The format of the destination file or directory. - You can specify one of the following values: - - - - DER X.509 certificate file - - - - directory of X.509 certificates - - - - File containing one or more certificate PEM blocks - - - - Directory PEM files each containing one certifiacte - - - - OpenSSL specific PEM bundle of certificates - - - - Directory of OpenSSL specific PEM files - - - - Java keystore 'cacerts' certificate bundle - - - - - - - Overwrite output file or directory. - - - - Limit to certificates usable for the given purpose - You can specify one of the following values: - - - - For authenticating servers - - - - For authenticating clients - - - - For email protection - - - - For authenticated signed code - - - - An arbitrary purpose OID - - - - - - + See trust1 + for more information @@ -210,21 +89,11 @@ $ p11-kit extract --format=x509-directory --filter=ca-anchors /path/to/directory Extract standard trust information files. - -$ p11-kit extract-trust - - - 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. - - What this command does, and where it extracts the files is - distribution or site specific. Packagers or administrators are expected - customize this command. - + See trust1 + for more information - + Bugs Please send bug reports to either the distribution bug tracker @@ -233,7 +102,7 @@ $ p11-kit extract-trust - + See also pkcs11.conf5 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 @@ + + + + + + + trust + p11-kit + + + Maintainer + Stef + Walter + stef@thewalter.net + + + + + + trust + 1 + User Commands + + + + trust + Tool for operating on the trust policy store + + + + + trust list + + + trust extract --filter=<what> + --format=<type> /path/to/destination + + + trust anchor /path/to/certificate.crt + + + + + Description + trust is a command line tool to examine and + modify the shared trust policy store. + + See the various sub commands below. The following global options + can be used: + + + + + Run in verbose mode with debug + output. + + + + Run in quiet mode without warning or + failure messages. + + + + + + + List + + List trust policy store items. + + +$ trust list + + + 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. + + You can specify the following options to control what to list. + + + + + Specifies what certificates to extract. You can specify the following values: + + + + Certificate anchors + + + + Anchors and blacklist (default) + + + + Blacklisted certificates + + + + All certificates + + + + A PKCS#11 URI to filter with + + + + + If an output format is chosen that cannot support type what has been + specified by the filter, a message will be printed. + + 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. + + + + + Limit to certificates usable for the given purpose + You can specify one of the following values: + + + + For authenticating servers + + + + For authenticating clients + + + + For email protection + + + + For authenticated signed code + + + + An arbitrary purpose OID + + + + + + + + + Anchor + + Store or remove trust anchors. + + +$ 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" + + + Store or remove trust anchors in the trust policy store. These are + usually root certificate authorities. + + Specify either the or + operations. If no operation is specified then is + assumed. + + When storing, one or more certificate files are expected on the + command line. These are stored as anchors, unless they are already + present. + + When removing an anchor, either specify certificate files or + PKCS#11 URI's on the command line. Matching anchors will be removed. + + 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. + + You can specify the following options. + + + + + Remove one or more anchors from the trust + policy store. Specify certificate files or PKCS#11 URI's + on the command line. + + + + Store one or more anchors to the trust + policy store. Specify certificate files on the command + line. + + + + + + + Extract + + Extract trust policy from the shared trust policy store. + + +$ trust extract --format=x509-directory --filter=ca-anchors /path/to/directory + + + You can specify the following options to control what to extract. + The and arguments + should be specified. By default this command will not overwrite the + destination file or directory. + + + + + Add identifying comments to PEM bundle output files + before each certificate. + + + + + Specifies what certificates to extract. You can specify the following values: + + + + Certificate anchors (default) + + + + Anchors and blacklist + + + + Blacklisted certificates + + + + All certificates + + + + A PKCS#11 URI + + + + + If an output format is chosen that cannot support type what has been + specified by the filter, a message will be printed. + + 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. + + + + + The format of the destination file or directory. + You can specify one of the following values: + + + + DER X.509 certificate file + + + + directory of X.509 certificates + + + + File containing one or more certificate PEM blocks + + + + Directory PEM files each containing one certifiacte + + + + OpenSSL specific PEM bundle of certificates + + + + Directory of OpenSSL specific PEM files + + + + Java keystore 'cacerts' certificate bundle + + + + + + + Overwrite output file or directory. + + + + Limit to certificates usable for the given purpose + You can specify one of the following values: + + + + For authenticating servers + + + + For authenticating clients + + + + For email protection + + + + For authenticated signed code + + + + An arbitrary purpose OID + + + + + + + + + + Extract Compat + + Extract compatibility trust certificate bundles. + + +$ trust extract-compat + + + 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. + + What this command does, and where it extracts the files is + distribution or site specific. Packagers or administrators are expected + customize this command. + + + + + Bugs + + Please send bug reports to either the distribution bug tracker + or the upstream bug tracker at + https://bugs.freedesktop.org/enter_bug.cgi?product=p11-glue&component=p11-kit. + + + + + See also + + p11-kit8 + + An explanatory document about storing trust policy: + http://p11-glue.freedesktop.org/doc/storing-trust-policy/ + + Further details available in the p11-kit online documentation at + http://p11-glue.freedesktop.org/doc/p11-kit/. + + + + -- cgit v1.1