'\" t .\" Title: trust .\" Author: Stef Walter .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 11/30/2023 .\" 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= \-\-format= /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 .HP \w'\fBtrust\ check\-format\fR\ 'u \fBtrust check\-format\fR /path/to/file\&.p11\-kit\&.\&.\&. .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=\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 blocklist (default) .RE .PP \fBblocklist\fR .RS 4 Distrusted 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 blocklist entries that do not contain a full certificate\&. Thus any certificates distrusted by their issuer and serial number alone, are not included in the extracted blocklist\&. .RE .PP \fB\-\-purpose=\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=\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 blocklist .RE .PP \fBblocklist\fR .RS 4 Distrusted 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 blocklist entries that do not contain a full certificate\&. Thus any certificates distrusted by their issuer and serial number alone, are not included in the extracted blocklist\&. .RE .PP \fB\-\-format=\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=\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=\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 "CHECK FORMAT" .PP Check the format of \&.p11\-kit files\&. .sp .if n \{\ .RS 4 .\} .nf $ trust check\-format /path/to/file\&.p11\-kit\&.\&.\&. .fi .if n \{\ .RE .\} .PP Administrators sometimes need to write a custom \&.p11\-kit file to amend the trust information\&. This is an error prone process as the file format is mainly for machine processing\&. Administrators can use this command to check whether a file has a correct \&.p11\-kit format\&. .PP This command takes an arbitrary number of files as an input\&. Each file is then analysed and any mismatch with the \&.p11\-kit format is reported on the standard error output\&. After the file is processed a check result is printed on the standard output\&. .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[]\&.