'\" t
.\"     Title: pkcs11-tool
.\"    Author: [see the "Authors" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 04/05/2024
.\"    Manual: OpenSC Tools
.\"    Source: opensc
.\"  Language: English
.\"
.TH "PKCS11\-TOOL" "1" "04/05/2024" "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 (bytes if symmetric) of the key to create, for example RSA:1024, EC:prime256v1, GOSTR3410\-2012\-256:B, DES:8, DES3:24, AES:16 or GENERIC:64\&. If the key type was incompletely specified, possible values are listed\&.
.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\&.
.sp
For RSA keys, sets DECRYPT in privkey and ENCRYPT in pubkey\&. For secret keys, sets both DECRYPT and ENCRYPT\&.
.RE
.PP
\fB\-\-usage\-derive\fR
.RS 4
Specify \*(Aqderive\*(Aq key usage flag (EC only)\&.
.RE
.PP
\fB\-\-usage\-wrap\fR
.RS 4
Specify \*(Aqwrap\*(Aq key usage flag\&.
.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\&.
.sp
The options
\fB\-\-keytype\fR,
\fB\-\-label\fR
,
\fB\-\-id\fR
or
\fB\-\-application\-id\fR
can be used to filter the listed 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\-\-list\-interfaces\fR
.RS 4
List interfaces of PKCS #11 3\&.0 library\&.
.RE
.PP
\fB\-\-session\-rw\fR,
.RS 4
Forces to open the PKCS#11 session with CKF_RW_SESSION\&.
.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 key pair 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\-\-extractable\fR
.RS 4
Set the CKA_EXTRACTABLE attribute (object can be extracted)
.RE
.PP
\fB\-\-undestroyable\fR
.RS 4
Set the CKA_DESTROYABLE attribute to false (object cannot be destroyed)
.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\-\-encrypt\fR,
.RS 4
Encrypt some data\&.
.RE
.PP
\fB\-\-unwrap\fR,
.RS 4
Unwrap key\&.
.RE
.PP
\fB\-\-wrap\fR,
.RS 4
Wrap key\&.
.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" or "\-3" means use maximum permissible length\&. For verify operation "\-2" means that the salt length is automatically recovered from signature\&. The value "\-2" for the verify operation is supported for opensc pkcs#11 module only\&. Default is digest length (\-1)\&.
.RE
.PP
\fB\-\-slot\fR \fIid\fR
.RS 4
Specify the id of the slot to use (accepts HEX format with 0x\&.\&. prefix or decimal number)\&.
.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\-\-object\-index\fR \fIindex\fR
.RS 4
Specify the index of the object to use\&.
.RE
.PP
\fB\-\-use\-locking\fR
.RS 4
Tell pkcs11 module it should use OS thread locking\&.
.RE
.PP
\fB\-\-test\-threads\fR \fIoptions\fR
.RS 4
Test a pkcs11 module\*(Aqs thread implication\&. (See source code)\&.
.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\-\-always\-auth\fR
.RS 4
Set the CKA_ALWAYS_AUTHENTICATE attribute to a private key object\&. If set, the user has to supply the PIN for each use (sign or decrypt) with the key\&.
.RE
.PP
\fB\-\-allowed\-mechanisms\fR \fImechanisms\fR
.RS 4
Sets the CKA_ALLOWED_MECHANISMS attribute to a key objects when importing an object or generating a keys\&. The argument accepts comma\-separated list of algorithmsm, that can be used with the given key\&.
.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\&. Valid value are
cert,
privkey,
pubkey,
secrkey
and
data\&.
.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\-\-verify\fR,
.RS 4
Verify signature of some data\&.
.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\-file\fR \fIfilename\fR
.RS 4
The path to the signature file for signature verification
.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
.PP
\fB\-\-allow\-sw\fR
.RS 4
Allow using software mechanisms that do not have the CKF_HW flag set\&. May be required when using software tokens and emulators\&.
.RE
.PP
\fB\-\-iv\fR \fIdata\fR
.RS 4
Initialization vector for symmetric ciphers\&. The
\fIdata\fR
is hexadecimal number, i\&.e\&. "000013aa7bffa0"\&.
.RE
.SH "EXAMPLES"
.PP
Perform a basic functionality test of the card:
.sp
.if n \{\
.RS 4
.\}
.nf
pkcs11\-tool \-\-test \-\-login
.fi
.if n \{\
.RE
.\}
.sp
List all certificates on the smart card:
.sp
.if n \{\
.RS 4
.\}
.nf
pkcs11\-tool \-\-list\-objects \-\-type cert
.fi
.if n \{\
.RE
.\}
.sp
Read the certificate with ID
\fICERT_ID\fR
in DER format from smart card and convert it to PEM via OpenSSL:
.sp
.if n \{\
.RS 4
.\}
.nf
pkcs11\-tool \-\-read\-object \-\-id $CERT_ID \-\-type cert \e
					\-\-output\-file cert\&.der
openssl x509 \-inform DER \-in cert\&.der \-outform PEM > cert\&.pem
			
.fi
.if n \{\
.RE
.\}
.sp
Write a certificate to token:
.sp
.if n \{\
.RS 4
.\}
.nf
pkcs11\-tool \-\-login \-\-write\-object certificate\&.der \-\-type cert
.fi
.if n \{\
.RE
.\}
.sp
Generate new RSA Key pair:
.sp
.if n \{\
.RS 4
.\}
.nf
pkcs11\-tool \-\-login \-\-keypairgen \-\-key\-type RSA:2048
.fi
.if n \{\
.RE
.\}
.sp
Generate new extractable RSA Key pair:
.sp
.if n \{\
.RS 4
.\}
.nf
pkcs11\-tool \-\-login \-\-keypairgen \-\-key\-type RSA:2048 \-\-extractable
.fi
.if n \{\
.RE
.\}
.sp
Generate an elliptic curve key pair with OpenSSL and import it to the card as
\fI$ID\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
openssl genpkey \-out EC_private\&.der \-outform DER \e
	\-algorithm EC \-pkeyopt ec_paramgen_curve:P\-521
pkcs11\-tool \-\-write\-object EC_private\&.der \-\-id "$ID" \e
	\-\-type privkey \-\-label "EC private key" \-p "$PIN"
openssl pkey \-in EC_private\&.der \-out EC_public\&.der \e
	\-pubout \-inform DER \-outform DER
pkcs11\-tool \-\-write\-object EC_public\&.der \-\-id "$ID" \e
	\-\-type pubkey  \-\-label "EC public key" \-p $PIN
.fi
.if n \{\
.RE
.\}
.sp
List private keys:
.sp
.if n \{\
.RS 4
.\}
.nf
pkcs11\-tool \-\-login \-\-list\-objects \-\-type privkey
.fi
.if n \{\
.RE
.\}
.sp
Sign some data stored in file
data
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 \e
	\-\-input\-file data \-\-output\-file data\&.sig
			
.fi
.if n \{\
.RE
.\}
.sp
The same is also possible by piping the data from stdin rather than specifying a input file:
.sp
.if n \{\
.RS 4
.\}
.nf
dd if=data bs=128 count=1 \e
	| pkcs11\-tool \-\-sign \-\-id $ID \-\-mechanism RSA\-PKCS \e
	> data\&.sig
			
.fi
.if n \{\
.RE
.\}
.sp
Verify the signed data:
.sp
.if n \{\
.RS 4
.\}
.nf
pkcs11\-tool \-\-id ID \-\-verify \-m RSA\-PKCS \e
	\-\-input\-file data \-\-signature\-file data\&.sig
			
.fi
.if n \{\
.RE
.\}
.sp
To encrypt file using the AES key with ID 85 and using mechanism AES\-CBC with padding:
.sp
.if n \{\
.RS 4
.\}
.nf
pkcs11\-tool \-\-login \-\-encrypt \-\-id 85 \-m AES\-CBC\-PAD \e
	\-\-iv "00000000000000000000000000000000" \e
	\-i file\&.txt \-o encrypted_file\&.data
				
.fi
.if n \{\
.RE
.\}
.sp
Decipher the encrypted file:
.sp
.if n \{\
.RS 4
.\}
.nf
pkcs11\-tool \-\-login \-\-decrypt \-\-id 85 \-m AES\-CBC\-PAD \e
	\-\-iv "00000000000000000000000000000000" \e
	\-\-i encrypted_file\&.data \-o decrypted\&.txt
				
.fi
.if n \{\
.RE
.\}
.sp
Use the key with ID 75 using mechanism AES\-CBC\-PAD, with initialization vector "00000000000000000000000000000000" to wrap the key with ID 76 into output file
exported_aes\&.key
.sp
.if n \{\
.RS 4
.\}
.nf
pkcs11\-tool \-\-login \-\-wrap \-\-id 75 \-\-mechanism AES\-CBC\-PAD \e
	\-\-iv "00000000000000000000000000000000" \e
	\-\-application\-id 76 \e
	\-\-output\-file exported_aes\&.key
				
.fi
.if n \{\
.RE
.\}
.sp
Use the key with ID 22 and mechanism RSA\-PKCS to unwrap key from file
aes_wrapped\&.key\&. After a successful unwrap operation, a new AES key is created on token\&. ID of this key is set to 90 and label of this key is set to
unwrapped\-key
Note: for the MyEID card, the AES key size must be present in key specification i\&.e\&. AES:16
.sp
.if n \{\
.RS 4
.\}
.nf
pkcs11\-tool \-\-login \-\-unwrap \-\-mechanism RSA\-PKCS \-\-id 22 \e
	\-i aes_wrapped\&.key \-\-key\-type AES: \e
	\-\-application\-id 90 \-\-applicatin\-label unwrapped\-key
				
.fi
.if n \{\
.RE
.\}
.sp
Use the SO\-PIN to initialize or re\-set the PIN:
.sp
.if n \{\
.RS 4
.\}
.nf
pkcs11\-tool \-\-login \-\-login\-type so \-\-init\-pin
				
.fi
.if n \{\
.RE
.\}
.sp
.SH "AUTHORS"
.PP
\fBpkcs11\-tool\fR
was written by Olaf Kirch
<okir@suse\&.de>\&.