'\" t
.\"     Title: pkcs11-tool
.\"    Author: [see the "Authors" section]
.\" 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 \fIfilename\fR
.RS 4
Extract information from
\fIfilename\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\-\-hash\-algorithm\fR \fImechanism\fR
.RS 4
Specify hash algorithm used with RSA\-PKCS\-PSS signature or RSA\-OAEP decryption\&. Allowed values are "SHA\-1", "SHA256", "SHA384", "SHA512", and some tokens may also allow "SHA224"\&. Default is "SHA\-1"\&.
.sp
Note that the input to RSA\-PKCS\-PSS has to be of the size equal to the specified hash algorithm\&. E\&.g\&., for SHA256 the signature input must be exactly 32 bytes long (for mechanisms SHA256\-RSA\-PKCS\-PSS there is no such restriction)\&. For RSA\-OAEP, the plaintext input size mLen must be at most keyLen \- 2 \- 2*hashLen\&. For example, for RSA 3072\-bit key and SHA384, the longest plaintext to encrypt with RSA\-OAEP is (with all sizes in bytes): 384 \- 2 \- 2*48 = 286, aka 286 bytes\&.
.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 \fIfilename\fR, \fB\-i\fR \fIfilename\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\-\-keygen\fR
.RS 4
Generate a new key\&.
.RE
.PP
\fB\-\-key\-type\fR \fIspecification\fR
.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\&. The mechanism can also be specified in hexadecimal, e\&.g\&.,
\fI0x80001234\fR\&.
.RE
.PP
\fB\-\-mgf\fR \fIfunction\fR
.RS 4
Use the specified Message Generation Function (MGF)
\fIfunction\fR
for RSA\-PKCS\-PSS signatures or RSA\-OAEP decryptions\&. Supported arguments are MGF1\-SHA1 to MGF1\-SHA512 if supported by the driver\&. The default is based on the hash selection\&.
.RE
.PP
\fB\-\-module\fR \fImod\fR
.RS 4
Specify a PKCS#11 module (or library) to load\&.
.RE
.PP
\fB\-\-moz\-cert\fR \fIfilename\fR, \fB\-z\fR \fIfilename\fR
.RS 4
Test a Mozilla\-like keypair generation and certificate request\&. Specify the
\fIfilename\fR
to the certificate file\&.
.RE
.PP
\fB\-\-output\-file\fR \fIfilename\fR, \fB\-o\fR \fIfilename\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\-\-sensitive\fR
.RS 4
Set the CKA_SENSITIVE attribute (object cannot be revealed in plaintext)\&.
.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\-\-derive\-pass\-der\fR,
.RS 4
Derive ECDHpass DER encoded pubkey for compatibility with some PKCS#11 implementations
.RE
.PP
\fB\-\-salt\-len\fR \fIbytes\fR
.RS 4
Specify how many bytes of salt should be used in RSA\-PSS signatures\&. Accepts two special values: "\-1" means salt length equals to digest length, "\-2" means use maximum permissible length\&. Default is digest length (\-1)\&.
.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 \fIfilename\fR, \fB\-w\fR \fIfilename\fR
.RS 4
Write a key or certificate object to the token\&.
\fIfilename\fR
points to the DER\-encoded certificate or key file\&.
.RE
.PP
\fB\-\-generate\-random\fR \fInum\fR
.RS 4
Get
\fInum\fR
bytes of random data\&.
.RE
.SH "EXAMPLES"
.PP
To list all certificates on the smart card:
.sp
.if n \{\
.RS 4
.\}
.nf
pkcs11\-tool \-\-list\-objects \-\-type cert
.fi
.if n \{\
.RE
.\}
.sp
To read the certificate with ID
\fIKEY_ID\fR
in DER format from smart card:
.sp
.if n \{\
.RS 4
.\}
.nf
pkcs11\-tool \-\-read\-object  \-\-id KEY_ID \-\-type cert \-\-outfile cert\&.der
.fi
.if n \{\
.RE
.\}
.sp
To convert the certificate in DER format to PEM format, use OpenSSL tools:
.sp
.if n \{\
.RS 4
.\}
.nf
openssl x509 \-inform DER \-in cert\&.der \-outform PEM > cert\&.pem
.fi
.if n \{\
.RE
.\}
.sp
To sign some data stored in file
\fIdata\fR
using the private key with ID
\fIID\fR
and using the RSA\-PKCS mechanism:
.sp
.if n \{\
.RS 4
.\}
.nf
pkcs11\-tool \-\-sign \-\-id ID \-\-mechanism RSA\-PKCS \-\-input\-file data \-\-output\-file data\&.sig
.fi
.if n \{\
.RE
.\}
.sp
.SH "AUTHORS"
.PP
\fBpkcs11\-tool\fR
was written by Olaf Kirch
<okir@suse\&.de>\&.