'\" t
.\"     Title: p11-kit
.\"    Author: Stef Walter <stef@thewalter.net>
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 10/25/2024
.\"    Manual: System Commands
.\"    Source: p11-kit
.\"  Language: English
.\"
.TH "P11\-KIT" "8" "" "p11-kit" "System 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"
p11-kit \- Tool for operating on configured PKCS#11 modules
.SH "SYNOPSIS"
.HP \w'\fBp11\-kit\ list\-modules\fR\ 'u
\fBp11\-kit list\-modules\fR
.HP \w'\fBp11\-kit\ list\-tokens\fR\ 'u
\fBp11\-kit list\-tokens\fR \&.\&.\&.
	
.HP \w'\fBp11\-kit\ list\-objects\fR\ 'u
\fBp11\-kit list\-objects\fR \&.\&.\&.
	
.HP \w'\fBp11\-kit\ import\-object\fR\ 'u
\fBp11\-kit import\-object\fR \&.\&.\&.
	
.HP \w'\fBp11\-kit\ export\-object\fR\ 'u
\fBp11\-kit export\-object\fR \&.\&.\&.
	
.HP \w'\fBp11\-kit\ delete\-object\fR\ 'u
\fBp11\-kit delete\-object\fR \&.\&.\&.
	
.HP \w'\fBp11\-kit\ generate\-keypair\fR\ 'u
\fBp11\-kit generate\-keypair\fR \&.\&.\&.
	
.HP \w'\fBp11\-kit\ list\-profiles\fR\ 'u
\fBp11\-kit list\-profiles\fR \&.\&.\&.
	
.HP \w'\fBp11\-kit\ add\-profile\fR\ 'u
\fBp11\-kit add\-profile\fR \&.\&.\&.
	
.HP \w'\fBp11\-kit\ delete\-profile\fR\ 'u
\fBp11\-kit delete\-profile\fR \&.\&.\&.
	
.HP \w'\fBp11\-kit\ list\-mechanisms\fR\ 'u
\fBp11\-kit list\-mechanisms\fR \&.\&.\&.
	
.HP \w'\fBp11\-kit\ print\-config\fR\ 'u
\fBp11\-kit print\-config\fR
.HP \w'\fBp11\-kit\ extract\fR\ 'u
\fBp11\-kit extract\fR \&.\&.\&.
	
.HP \w'\fBp11\-kit\ server\fR\ 'u
\fBp11\-kit server\fR \&.\&.\&.
	
.SH "DESCRIPTION"
.PP
\fBp11\-kit\fR
is a command line tool that can be used to perform operations on PKCS#11 modules configured on the system\&.
.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 MODULES"
.PP
List system configured PKCS#11 modules\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ p11\-kit list\-modules
.fi
.if n \{\
.RE
.\}
.PP
The modules, information about them and the tokens present in the PKCS#11 modules will be displayed\&.
.SH "LIST TOKENS"
.PP
List all tokens available in system configured PKCS#11 modules\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ p11\-kit list\-tokens [\-\-only\-uris] pkcs11:token
.fi
.if n \{\
.RE
.\}
.PP
This retrieves all tokens and displays some of their common attributes\&. If
\fB\-\-only\-uris\fR
is given, only the matching token URIs are printed\&.
.SH "LIST OBJECTS"
.PP
List objects matching given PKCS#11 URI\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ p11\-kit list\-objects [\-\-login] pkcs11:object_on_token
.fi
.if n \{\
.RE
.\}
.PP
This retrieves all objects that match given PKCS#11 URI and displays some of their common attributes\&. Storage objects also have their PKCS#11 URI displayed\&.
.SH "IMPORT OBJECT"
.PP
Import object into PKCS#11 token\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ p11\-kit import\-object \-\-file=file\&.pem [\-\-label=label] [\-\-login] pkcs11:token
.fi
.if n \{\
.RE
.\}
.PP
Takes either an X\&.509 certificate or a public key in the form of a PEM file and imports it into the first token matched by given PKCS#11 URI\&.
.PP
\fB\-\-file=<file\&.pem>\fR
.RS 4
File containing either an X\&.509 certificate or a public key in PEM format\&. This option is required\&.
.RE
.PP
\fB\-\-label=<label>\fR
.RS 4
Assigns label to the imported object\&.
.RE
.SH "EXPORT OBJECT"
.PP
Export object matching PKCS#11 URI\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ p11\-kit export\-object [\-\-login] pkcs11:object_on_token
.fi
.if n \{\
.RE
.\}
.PP
Displays PEM formatted contents of the first object matched by given PKCS#11 URI\&. The matched object has to either be an X\&.509 certificate or a public key\&.
.SH "DELETE OBJECT"
.PP
Delete object matching PKCS#11 URI\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ p11\-kit delete\-object [\-\-login] pkcs11:object_on_token
.fi
.if n \{\
.RE
.\}
.PP
Destroys the first object matched by given PKCS#11 URI\&.
.SH "GENERATE KEY\-PAIR"
.PP
Generate key\-pair on a PKCS#11 token\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ p11\-kit generate\-keypair \-\-type=algorithm {\-\-bits=n|\-\-curve=name} [\-\-label=label] [\-\-login] pkcs11:token
.fi
.if n \{\
.RE
.\}
.PP
Generate private\-public key\-pair of given type on the first token matched by given PKCS#11 URI\&. This command should be used together with \-\-type option and one of \-\-bits or \-\-curve options\&.
.PP
\fB\-\-type=<algorithm>\fR
.RS 4
Specify the type of keys to generate\&. Supported values are rsa, ecdsa and ed25519\&. This option is required\&.
.RE
.PP
\fB\-\-bits=<n>\fR
.RS 4
Specify the number of bits for the key\-pair generation\&. Cannot be used together with \-\-curve option\&.
.RE
.PP
\fB\-\-curve=<name>\fR
.RS 4
Specify an elliptic curve for the key\-pair generation\&. Supported values are secp256r1, secp384r1, secp521r1, ed25519 and ed448\&. Cannot be used together with \-\-bits option\&.
.RE
.PP
\fB\-\-label=<label>\fR
.RS 4
Assigns label to the generated key\-pair objects\&.
.RE
.SH "LIST PROFILES"
.PP
List PKCS#11 profiles supported by the token\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ p11\-kit list\-profiles [\-\-login] pkcs11:token
.fi
.if n \{\
.RE
.\}
.PP
Displays profile IDs of the first token matched by given PKCS#11 URI in human\-readable form\&.
.SH "ADD PROFILE"
.PP
Add PKCS#11 profile to a token\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ p11\-kit add\-profile \-\-profile=profile [\-\-login] pkcs11:token
.fi
.if n \{\
.RE
.\}
.PP
Creates new profile object with given profile ID on the first token matched by given PKCS#11 URI\&. This command fails if the profile ID already exists on the token\&.
.PP
\fB\-\-profile=<profile>\fR
.RS 4
Profile ID to add\&. Value can either be numerical or textual\&. This option is required\&.
.RE
.SH "DELETE PROFILE"
.PP
Delete PKCS#11 profile from a token\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ p11\-kit delete\-profile \-\-profile=profile [\-\-login] pkcs11:token
.fi
.if n \{\
.RE
.\}
.PP
Destroys all profile objects with given profile ID from the first token matched by given PKCS#11 URI\&.
.PP
\fB\-\-profile=<profile>\fR
.RS 4
Profile ID to delete\&. Value can either be numerical or textual\&. This option is required\&.
.RE
.SH "LIST MECHANISMS"
.PP
List PKCS#11 mechanisms supported by the token\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ p11\-kit list\-mechanisms pkcs11:token
.fi
.if n \{\
.RE
.\}
.PP
This lists all available mechanimsms for a PKCS#11 token
.SH "PRINT CONFIG"
.PP
Print merged configuration\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ p11\-kit print\-config
.fi
.if n \{\
.RE
.\}
.PP
P11\-kit provides 3 levels of configuration: system wide, per\-module, and per\-user\&. At run\-time all 3 levels are merged into a single configuration\&. This command displays the merged configuration\&.
.SH "EXTRACT"
.PP
Extract certificates from configured PKCS#11 modules\&.
.PP
This operation has been moved to a separate command
\fBtrust extract\fR\&. See
\fBtrust\fR(1)
for more information
.SH "SERVER"
.PP
Run a server process that exposes PKCS#11 module remotely\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ p11\-kit server pkcs11:token1 pkcs11:token2 \&.\&.\&.
$ p11\-kit server \-\-provider /path/to/pkcs11\-module\&.so pkcs11:token1 pkcs11:token2 \&.\&.\&.
.fi
.if n \{\
.RE
.\}
.PP
This launches a server that exposes the given PKCS#11 tokens on a local socket\&. The tokens must belong to the same module\&. To access the socket, use
p11\-kit\-client\&.so
module\&. The server address and PID are printed as a shell\-script snippet which sets the appropriate environment variable:
P11_KIT_SERVER_ADDRESS
and
P11_KIT_SERVER_PID\&.
.SH "EXTRACT TRUST"
.PP
Extract standard trust information files\&.
.PP
This operation has been moved to a separate command
\fBtrust extract\-compat\fR\&. See
\fBtrust\fR(1)
for more information
.SH "REMOTE"
.PP
Run a PKCS#11 module remotely\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ p11\-kit remote /path/to/pkcs11\-module\&.so
$ p11\-kit remote pkcs11:token1 pkcs11:token2 \&.\&.\&.
.fi
.if n \{\
.RE
.\}
.PP
This is not meant to be run directly from a terminal\&. But rather in a
\fBremote\fR
option in a
\fBpkcs11.conf\fR(5)
file\&.
.PP
This exposes the given PKCS#11 module or tokens over standard input and output\&. Those two forms, whether to expose a module or tokens, are mutually exclusive and if the second form is used, the tokens must belong to the same module\&.
.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"
\fBpkcs11.conf\fR(5)
.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[]\&.
