'\" t
.\"     Title: pkcs11-tool
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 09/30/2018
.\"    Manual: OpenSC Tools
.\"    Source: opensc
.\"  Language: English
.\"
.TH "PKCS11\-TOOL" "1" "09/30/2018" "opensc" "OpenSC Tools"
.\" -----------------------------------------------------------------
.\" * 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"
pkcs11-tool \- utility for managing and using PKCS #11 security tokens
.SH "SYNOPSIS"
.HP \w'\fBpkcs11\-tool\fR\ 'u
\fBpkcs11\-tool\fR [\fIOPTIONS\fR]
.SH "DESCRIPTION"
.PP
The
\fBpkcs11\-tool\fR
utility is used to manage the data objects on smart cards and similar PKCS #11 security tokens\&. Users can list and read PINs, keys and certificates stored on the token\&. User PIN authentication is performed for those operations that require it\&.
.SH "OPTIONS"
.PP
.PP
\fB\-\-attr\-from\fR \fIpath\fR
.RS 4
Extract information from
\fIpath\fR
(DER\-encoded certificate file) and create the corresponding attributes when writing an object to the token\&. Example: the certificate subject name is used to create the CKA_SUBJECT attribute\&.
.RE
.PP
\fB\-\-change\-pin\fR, \fB\-c\fR
.RS 4
Change the user PIN on the token
.RE
.PP
\fB\-\-unlock\-pin\fR
.RS 4
Unlock User PIN (without
\fB\-\-login\fR
unlock in logged in session; otherwise
\fB\-\-login\-type\fR
has to be \*(Aqcontext\-specific\*(Aq)\&.
.RE
.PP
\fB\-\-hash\fR, \fB\-h\fR
.RS 4
Hash some data\&.
.RE
.PP
\fB\-\-id\fR \fIid\fR, \fB\-d\fR \fIid\fR
.RS 4
Specify the id of the object to operate on\&.
.RE
.PP
\fB\-\-init\-pin\fR
.RS 4
Initializes the user PIN\&. This option differs from
\fB\-\-change\-pin\fR
in that it sets the user PIN for the first time\&. Once set, the user PIN can be changed using
\fB\-\-change\-pin\fR\&.
.RE
.PP
\fB\-\-init\-token\fR
.RS 4
Initialize a token: set the token label as well as a Security Officer PIN (the label must be specified using
\fB\-\-label\fR)\&.
.RE
.PP
\fB\-\-input\-file\fR \fIpath\fR, \fB\-i\fR \fIpath\fR
.RS 4
Specify the path to a file for input\&.
.RE
.PP
\fB\-\-keypairgen\fR, \fB\-k\fR
.RS 4
Generate a new key pair (public and private pair\&.)
.RE
.PP
\fB\-\-key\-type\fR <replacement>specification</replacement>
.RS 4
Specify the type and length of the key to create, for example rsa:1024 or EC:prime256v1\&.
.RE
.PP
\fB\-\-usage\-sign\fR
.RS 4
Specify \*(Aqsign\*(Aq key usage flag (sets SIGN in privkey, sets VERIFY in pubkey)\&.
.RE
.PP
\fB\-\-usage\-decrypt\fR
.RS 4
Specify \*(Aqdecrypt\*(Aq key usage flag (RSA only, set DECRYPT privkey, ENCRYPT in pubkey)\&.
.RE
.PP
\fB\-\-usage\-derive\fR
.RS 4
Specify \*(Aqderive\*(Aq key usage flag (EC only)\&.
.RE
.PP
\fB\-\-label\fR \fIname\fR, \fB\-a\fR \fIname\fR
.RS 4
Specify the name of the object to operate on (or the token label when
\fB\-\-init\-token\fR
is used)\&.
.RE
.PP
\fB\-\-list\-mechanisms\fR, \fB\-M\fR
.RS 4
Display a list of mechanisms supported by the token\&.
.RE
.PP
\fB\-\-list\-objects\fR, \fB\-O\fR
.RS 4
Display a list of objects\&.
.RE
.PP
\fB\-\-list\-slots\fR, \fB\-L\fR
.RS 4
Display a list of available slots on the token\&.
.RE
.PP
\fB\-\-list\-token\-slots\fR, \fB\-T\fR
.RS 4
List slots with tokens\&.
.RE
.PP
\fB\-\-login\fR, \fB\-l\fR
.RS 4
Authenticate to the token before performing other operations\&. This option is not needed if a PIN is provided on the command line\&.
.RE
.PP
\fB\-\-login\-type\fR
.RS 4
Specify login type (\*(Aqso\*(Aq, \*(Aquser\*(Aq, \*(Aqcontext\-specific\*(Aq; default:\*(Aquser\*(Aq)\&.
.RE
.PP
\fB\-\-mechanism\fR \fImechanism\fR, \fB\-m\fR \fImechanism\fR
.RS 4
Use the specified
\fImechanism\fR
for token operations\&. See
\fB\-M\fR
for a list of mechanisms supported by your token\&.
.RE
.PP
\fB\-\-module\fR \fImod\fR
.RS 4
Specify a PKCS#11 module (or library) to load\&.
.RE
.PP
\fB\-\-moz\-cert\fR \fIpath\fR, \fB\-z\fR \fIpath\fR
.RS 4
Test a Mozilla\-like keypair generation and certificate request\&. Specify the
\fIpath\fR
to the certificate file\&.
.RE
.PP
\fB\-\-output\-file\fR \fIpath\fR, \fB\-o\fR \fIpath\fR
.RS 4
Specify the path to a file for output\&.
.RE
.PP
\fB\-\-pin\fR \fIpin\fR, \fB\-p\fR \fIpin\fR
.RS 4
Use the given
\fIpin\fR
for token operations\&. If set to env:\fIVARIABLE\fR, the value of the environment variable
\fIVARIABLE\fR
is used\&. WARNING: Be careful using this option as other users may be able to read the command line from the system or if it is embedded in a script\&. If set to env:\fIVARIABLE\fR, the value of the environment variable
\fIVARIABLE\fR
is used\&.
.sp
This option will also set the
\fB\-\-login\fR
option\&.
.RE
.PP
\fB\-\-puk\fR \fIpuk\fR
.RS 4
Supply User PUK on the command line\&.
.RE
.PP
\fB\-\-new\-pin\fR \fIpin\fR
.RS 4
Supply new User PIN on the command line\&.
.RE
.PP
\fB\-\-set\-id\fR \fIid\fR, \fB\-e\fR \fIid\fR
.RS 4
Set the CKA_ID of the object\&.
.RE
.PP
\fB\-\-show\-info\fR, \fB\-I\fR
.RS 4
Display general token information\&.
.RE
.PP
\fB\-\-sign\fR, \fB\-s\fR
.RS 4
Sign some data\&.
.RE
.PP
\fB\-\-decrypt\fR,
.RS 4
Decrypt some data\&.
.RE
.PP
\fB\-\-derive\fR,
.RS 4
Derive a secret key using another key and some data\&.
.RE
.PP
\fB\-\-slot\fR \fIid\fR
.RS 4
Specify the id of the slot to use\&.
.RE
.PP
\fB\-\-slot\-description\fR \fIdescription\fR
.RS 4
Specify the description of the slot to use\&.
.RE
.PP
\fB\-\-slot\-index\fR \fIindex\fR
.RS 4
Specify the index of the slot to use\&.
.RE
.PP
\fB\-\-token\-label\fR \fIlabel\fR
.RS 4
Specify the label of token\&. Will be used the first slot, that has the inserted token with this label\&.
.RE
.PP
\fB\-\-so\-pin\fR \fIpin\fR
.RS 4
Use the given
\fIpin\fR
as the Security Officer PIN for some token operations (token initialization, user PIN initialization, etc)\&. If set to env:\fIVARIABLE\fR, the value of the environment variable
\fIVARIABLE\fR
is used\&. The same warning as
\fB\-\-pin\fR
also applies here\&.
.RE
.PP
\fB\-\-test\fR, \fB\-t\fR
.RS 4
Perform some tests on the token\&. This option is most useful when used with either
\fB\-\-login\fR
or
\fB\-\-pin\fR\&.
.RE
.PP
\fB\-\-test\-hotplug\fR
.RS 4
Test hotplug capabilities (C_GetSlotList + C_WaitForSlotEvent)\&.
.RE
.PP
\fB\-\-private\fR
.RS 4
Set the CKA_PRIVATE attribute (object is only viewable after a login)\&.
.RE
.PP
\fB\-\-test\-ec\fR
.RS 4
Test EC (best used with the
\fB\-\-login\fR
or
\fB\-\-pin\fR
option)\&.
.RE
.PP
\fB\-\-test\-fork\fR
.RS 4
Test forking and calling C_Initialize() in the child\&.
.RE
.PP
\fB\-\-type\fR \fItype\fR, \fB\-y\fR \fItype\fR
.RS 4
Specify the type of object to operate on\&. Examples are
cert,
privkey
and
pubkey\&.
.RE
.PP
\fB\-\-verbose\fR, \fB\-v\fR
.RS 4
Cause
\fBpkcs11\-tool\fR
to be more verbose\&.
.sp
NB! This does not affect OpenSC debugging level! To set OpenSC PKCS#11 module into debug mode, set the
\fIOPENSC_DEBUG\fR
environment variable to a non\-zero number\&.
.RE
.PP
\fB\-\-read\-object\fR, \fB\-r\fR
.RS 4
Get object\*(Aqs CKA_VALUE attribute (use with
\fB\-\-type\fR)\&.
.RE
.PP
\fB\-\-delete\-object\fR, \fB\-b\fR
.RS 4
Delete an object\&.
.RE
.PP
\fB\-\-application\-label\fR \fIlabel\fR
.RS 4
Specify the application label of the data object (use with
\fB\-\-type\fR
data)\&.
.RE
.PP
\fB\-\-application\-id\fR \fIid\fR
.RS 4
Specify the application ID of the data object (use with
\fB\-\-type\fR
data)\&.
.RE
.PP
\fB\-\-issuer\fR \fIdata\fR
.RS 4
Specify the issuer in hexadecimal format (use with
\fB\-\-type\fR
cert)\&.
.RE
.PP
\fB\-\-subject\fR \fIdata\fR
.RS 4
Specify the subject in hexadecimal format (use with
\fB\-\-type\fR
cert/privkey/pubkey)\&.
.RE
.PP
\fB\-\-signature\-format\fR \fIformat\fR
.RS 4
Format for ECDSA signature: \*(Aqrs\*(Aq (default), \*(Aqsequence\*(Aq, \*(Aqopenssl\*(Aq\&.
.RE
.PP
\fB\-\-write\-object\fR \fIid\fR, \fB\-w\fR \fIpath\fR
.RS 4
Write a key or certificate object to the token\&.
\fIpath\fR
points to the DER\-encoded certificate or key file\&.
.RE