'\" t
.\"     Title: trust
.\"    Author: Stef Walter <stef@thewalter.net>
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 01/04/2021
.\"    Manual: User Commands
.\"    Source: p11-kit
.\"  Language: English
.\"
.TH "TRUST" "1" "" "p11-kit" "User Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
trust \- Tool for operating on the trust policy store
.SH "SYNOPSIS"
.HP \w'\fBtrust\ list\fR\ 'u
\fBtrust list\fR
.HP \w'\fBtrust\ extract\fR\ 'u
\fBtrust extract\fR \-\-filter=<what> \-\-format=<type> /path/to/destination
	
.HP \w'\fBtrust\ anchor\fR\ 'u
\fBtrust anchor\fR /path/to/certificate\&.crt
	
.HP \w'\fBtrust\ dump\fR\ 'u
\fBtrust dump\fR
.SH "DESCRIPTION"
.PP
\fBtrust\fR
is a command line tool to examine and modify the shared trust policy store\&.
.PP
See the various sub commands below\&. The following global options can be used:
.PP
\fB\-v, \-\-verbose\fR
.RS 4
Run in verbose mode with debug output\&.
.RE
.PP
\fB\-q, \-\-quiet\fR
.RS 4
Run in quiet mode without warning or failure messages\&.
.RE
.SH "LIST"
.PP
List trust policy store items\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ trust list
.fi
.if n \{\
.RE
.\}
.PP
List information about the various items in the trust policy store\&. Each item is listed with it\*(Aqs PKCS#11 URI and some descriptive information\&.
.PP
You can specify the following options to control what to list\&.
.PP
\fB\-\-filter=<what>\fR
.RS 4
Specifies what certificates to extract\&. You can specify the following values:
.PP
\fBca\-anchors\fR
.RS 4
Certificate anchors
.RE
.PP
\fBtrust\-policy\fR
.RS 4
Anchors and blacklist (default)
.RE
.PP
\fBblacklist\fR
.RS 4
Blacklisted certificates
.RE
.PP
\fBcertificates\fR
.RS 4
All certificates
.RE
.PP
\fBpkcs11:object=xx\fR
.RS 4
A PKCS#11 URI to filter with
.RE
.sp
If an output format is chosen that cannot support type what has been specified by the filter, a message will be printed\&.
.sp
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\&.
.RE
.PP
\fB\-\-purpose=<usage>\fR
.RS 4
Limit to certificates usable for the given purpose You can specify one of the following values:
.PP
\fBserver\-auth\fR
.RS 4
For authenticating servers
.RE
.PP
\fBclient\-auth\fR
.RS 4
For authenticating clients
.RE
.PP
\fBemail\fR
.RS 4
For email protection
.RE
.PP
\fBcode\-signing\fR
.RS 4
For authenticated signed code
.RE
.PP
\fB1\&.2\&.3\&.4\&.5\&.\&.\&.\fR
.RS 4
An arbitrary purpose OID
.RE
.sp
.RE
.SH "ANCHOR"
.PP
Store or remove trust anchors\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ trust anchor /path/to/certificate\&.crt
$ trust anchor \-\-remove /path/to/certificate\&.crt
$ trust anchor \-\-remove "pkcs11:id=%AA%BB%CC%DD%EE;type=cert"
.fi
.if n \{\
.RE
.\}
.PP
Store or remove trust anchors in the trust policy store\&. These are usually root certificate authorities\&.
.PP
Specify either the
\fB\-\-store\fR
or
\fB\-\-remove\fR
operations\&. If no operation is specified then
\fB\-\-store\fR
is assumed\&.
.PP
When storing, one or more certificate files are expected on the command line\&. These are stored as anchors, unless they are already present\&.
.PP
When removing an anchor, either specify certificate files or PKCS#11 URI\*(Aqs on the command line\&. Matching anchors will be removed\&.
.PP
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\&.
.PP
You can specify the following options\&.
.PP
\fB\-\-remove\fR
.RS 4
Remove one or more anchors from the trust policy store\&. Specify certificate files or PKCS#11 URI\*(Aqs on the command line\&.
.RE
.PP
\fB\-\-store\fR
.RS 4
Store one or more anchors to the trust policy store\&. Specify certificate files on the command line\&.
.RE
.SH "EXTRACT"
.PP
Extract trust policy from the shared trust policy store\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ trust extract \-\-format=x509\-directory \-\-filter=ca\-anchors /path/to/directory
.fi
.if n \{\
.RE
.\}
.PP
You can specify the following options to control what to extract\&. The
\fB\-\-filter\fR
and
\fB\-\-format\fR
arguments should be specified\&. By default this command will not overwrite the destination file or directory\&.
.PP
\fB\-\-comment\fR
.RS 4
Add identifying comments to PEM bundle output files before each certificate\&.
.RE
.PP
\fB\-\-filter=<what>\fR
.RS 4
Specifies what certificates to extract\&. You can specify the following values:
.PP
\fBca\-anchors\fR
.RS 4
Certificate anchors (default)
.RE
.PP
\fBtrust\-policy\fR
.RS 4
Anchors and blacklist
.RE
.PP
\fBblacklist\fR
.RS 4
Blacklisted certificates
.RE
.PP
\fBcertificates\fR
.RS 4
All certificates
.RE
.PP
\fBpkcs11:object=xx\fR
.RS 4
A PKCS#11 URI
.RE
.sp
If an output format is chosen that cannot support type what has been specified by the filter, a message will be printed\&.
.sp
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\&.
.RE
.PP
\fB\-\-format=<type>\fR
.RS 4
The format of the destination file or directory\&. You can specify one of the following values:
.PP
\fBx509\-file\fR
.RS 4
DER X\&.509 certificate file
.RE
.PP
\fBx509\-directory\fR
.RS 4
directory of X\&.509 certificates
.RE
.PP
\fBpem\-bundle\fR
.RS 4
File containing one or more certificate PEM blocks
.RE
.PP
\fBpem\-directory\fR
.RS 4
Directory of PEM files each containing one certificate
.RE
.PP
\fBpem\-directory\-hash\fR
.RS 4
Directory of PEM files each containing one certificate, with hash symlinks
.RE
.PP
\fBopenssl\-bundle\fR
.RS 4
OpenSSL specific PEM bundle of certificates
.RE
.PP
\fBopenssl\-directory\fR
.RS 4
Directory of OpenSSL specific PEM files
.RE
.PP
\fBjava\-cacerts\fR
.RS 4
Java keystore \*(Aqcacerts\*(Aq certificate bundle
.RE
.sp
.RE
.PP
\fB\-\-overwrite\fR
.RS 4
Overwrite output file or directory\&.
.RE
.PP
\fB\-\-purpose=<usage>\fR
.RS 4
Limit to certificates usable for the given purpose You can specify one of the following values:
.PP
\fBserver\-auth\fR
.RS 4
For authenticating servers
.RE
.PP
\fBclient\-auth\fR
.RS 4
For authenticating clients
.RE
.PP
\fBemail\fR
.RS 4
For email protection
.RE
.PP
\fBcode\-signing\fR
.RS 4
For authenticated signed code
.RE
.PP
\fB1\&.2\&.3\&.4\&.5\&.\&.\&.\fR
.RS 4
An arbitrary purpose OID
.RE
.sp
.RE
.SH "EXTRACT COMPAT"
.PP
Extract compatibility trust certificate bundles\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ trust extract\-compat
.fi
.if n \{\
.RE
.\}
.PP
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\&.
.PP
What this command does, and where it extracts the files is distribution or site specific\&. Packagers or administrators are expected customize this command\&.
.SH "DUMP"
.PP
Dump PKCS#11 items in the various tokens\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ trust dump
.fi
.if n \{\
.RE
.\}
.PP
Dump information about the various PKCS#11 items in the tokens\&. Each item is dumped with it\*(Aqs PKCS#11 URI and information in the \&.p11\-kit persistence format\&.
.PP
You can specify the following options to control what to dump\&.
.PP
\fB\-\-filter=<what>\fR
.RS 4
Specifies what certificates to extract\&. You can specify the following values:
.PP
\fBall\fR
.RS 4
All objects\&. This is the default
.RE
.PP
\fBpkcs11:object=xx\fR
.RS 4
A PKCS#11 URI to filter with
.RE
.sp
.RE
.SH "BUGS"
.PP
Please send bug reports to either the distribution bug tracker or the upstream bug tracker at
\m[blue]\fBhttps://github\&.com/p11\-glue/p11\-kit/issues/\fR\m[]\&.
.SH "SEE ALSO"
\fBp11-kit\fR(8)
.PP
An explanatory document about storing trust policy:
\m[blue]\fBhttps://p11\-glue\&.github\&.io/p11\-glue/doc/storing\-trust\-policy/\fR\m[]
.PP
Further details available in the p11\-kit online documentation at
\m[blue]\fBhttps://p11\-glue\&.github\&.io/p11\-glue/p11\-kit/manual/\fR\m[]\&.
