pkcs11-tool.1

PKCS11−TOOL

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
EXAMPLES
AUTHORS

---

NAME

pkcs11-tool − utility for managing and using PKCS #11 security tokens

SYNOPSIS

DESCRIPTION

The pkcs11−tool 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.

OPTIONS

−−attr−from filename

Extract information from filename (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.

−−change−pin, −c

Change the user PIN on the token

−−unlock−pin

Unlock User PIN (without −−login unlock in logged in session; otherwise −−login−type has to be ‘context−specific’).

−−hash, −h

Hash some data.

−−hash−algorithm mechanism

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”.

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.

−−id id, −d id

Specify the id of the object to operate on.

−−init−pin

Initializes the user PIN. This option differs from −−change−pin in that it sets the user PIN for the first time. Once set, the user PIN can be changed using −−change−pin.

−−init−token

Initialize a token: set the token label as well as a Security Officer PIN (the label must be specified using −−label).

−−input−file filename, −i filename

Specify the path to a file for input.

−−keypairgen, −k

Generate a new key pair (public and private pair.)

−−keygen

Generate a new key.

−−key−type specification

Specify the type and (not always compulsory) flavour (byte−wise symmetric key length, bit−wise asymmetric key length, elliptic curve identifier, etc.) of the key to create, for example RSA:2048, EC:prime256v1, GOSTR3410−2012−256:B, DES:8, DES3:24, AES:16, AES: or GENERIC:64. If the key type was incompletely specified, possible values are listed.

−−usage−sign

Specify ‘sign’ key usage flag (sets SIGN in privkey, sets VERIFY in pubkey).

−−usage−decrypt

Specify ‘decrypt’ key usage flag.

For RSA keys, sets DECRYPT in privkey and ENCRYPT in pubkey. For secret keys, sets both DECRYPT and ENCRYPT.

−−usage−derive

Specify ‘derive’ key usage flag (EC only).

−−usage−wrap

Specify ‘wrap’ key usage flag.

−−label name, −a name

Specify the name of the object to operate on (or the token label when −−init−token is used).

−−list−mechanisms, −M

Display a list of mechanisms supported by the token.

−−list−objects, −O

Display a list of objects.

The options −−keytype, −−label , −−id or −−application−id can be used to filter the listed objects.

−−list−slots, −L

Display a list of available slots on the token.

−−list−token−slots, −T

List slots with tokens.

−−list−interfaces

List interfaces of PKCS #11 3.0 library.

−−session−rw,

Forces to open the PKCS#11 session with CKF_RW_SESSION.

−−login, −l

Authenticate to the token before performing other operations. This option is not needed if a PIN is provided on the command line.

−−login−type

Specify login type (‘so’, ‘user’, ‘context−specific’; default:‘user’).

−−mechanism mechanism, −m mechanism

Use the specified mechanism for token operations. See −M for a list of mechanisms supported by your token. The mechanism can also be specified in hexadecimal, e.g., 0x80001234.

−−mgf function

Use the specified Message Generation Function (MGF) function 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.

−−module mod

Specify a PKCS#11 module (or library) to load.

−−moz−cert filename, −z filename

Test a Mozilla−like key pair generation and certificate request. Specify the filename to the certificate file.

−−output−file filename, −o filename

Specify the path to a file for output.

−−pin pin, −p pin

Use the given pin for token operations. If set to env:VARIABLE, the value of the environment variable VARIABLE 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:VARIABLE, the value of the environment variable VARIABLE is used.

This option will also set the −−login option.

−−puk puk

Supply User PUK on the command line.

−−new−pin pin

Supply new User PIN on the command line.

−−sensitive

Set the CKA_SENSITIVE attribute (object cannot be revealed in plaintext).

−−extractable

Set the CKA_EXTRACTABLE attribute (object can be extracted)

−−undestroyable

Set the CKA_DESTROYABLE attribute to false (object cannot be destroyed)

−−set−id id, −e id

Set the CKA_ID of the object.

−−show−info, −I

Display general token information.

−−sign, −s

Sign some data.

−−decrypt,

Decrypt some data.

−−encrypt,

Encrypt some data.

−−unwrap,

Unwrap key.

−−wrap,

Wrap key.

−−derive,

Derive a secret key using another key and some data.

−−derive−pass−der,

Derive ECDHpass DER encoded pubkey for compatibility with some PKCS#11 implementations

−−salt−len bytes

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).

−−slot id

Specify the id of the slot to use (accepts HEX format with 0x.. prefix or decimal number).

−−slot−description description

Specify the description of the slot to use.

−−slot−index index

Specify the index of the slot to use.

−−object−index index

Specify the index of the object to use.

−−use−locking

Tell pkcs11 module it should use OS thread locking.

−−test−threads options

Test a pkcs11 module’s thread implication. (See source code).

−−token−label label

Specify the label of token. Will be used the first slot, that has the inserted token with this label.

−−so−pin pin

Use the given pin as the Security Officer PIN for some token operations (token initialization, user PIN initialization, etc). If set to env:VARIABLE, the value of the environment variable VARIABLE is used. The same warning as −−pin also applies here.

−−test, −t

Perform some tests on the token. This option is most useful when used with either −−login or −−pin.

−−test−hotplug

Test hotplug capabilities (C_GetSlotList + C_WaitForSlotEvent).

−−private

Set the CKA_PRIVATE attribute (object is only viewable after a login).

−−always−auth

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.

−−allowed−mechanisms mechanisms

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.

−−test−ec

Test EC (best used with the −−login or −−pin option).

−−test−fork

Test forking and calling C_Initialize() in the child.

−−type type, −y type

Specify the type of object to operate on. Valid value are cert, privkey, pubkey, secrkey and data.

−−verbose, −v

Cause pkcs11−tool to be more verbose.

NB! This does not affect OpenSC debugging level! To set OpenSC PKCS#11 module into debug mode, set the OPENSC_DEBUG environment variable to a non−zero number.

−−verify,

Verify signature of some data.

−−read−object, −r

Get object’s CKA_VALUE attribute (use with −−type).

−−delete−object, −b

Delete an object.

−−application−label label

Specify the application label of the data object (use with −−type data).

−−application−id id

Specify the application ID of the data object (use with −−type data).

−−issuer data

Specify the issuer in hexadecimal format (use with −−type cert).

−−subject data

Specify the subject in hexadecimal format (use with −−type cert/privkey/pubkey).

−−signature−file filename

The path to the signature file for signature verification

−−signature−format format

Format for ECDSA signature: ‘rs’ (default), ‘sequence’, ‘openssl’.

−−write−object filename, −w filename

Write a key or certificate object to the token. filename points to the DER−encoded certificate or key file.

−−generate−random num

Get num bytes of random data.

−−allow−sw

Allow using software mechanisms that do not have the CKF_HW flag set. May be required when using software tokens and emulators.

−−iv data

Initialization vector for symmetric ciphers. The data is hexadecimal number, i.e. “000013aa7bffa0”.

−−mac−general−param num

Sets the length of the MAC for the general−length MACing mechanisms to num bytes.

−−aad data

Additional authenticated data for AEAD ciphers. The data is an hexadecimal number.

−−tag−bits−len num

Sets the length of the tag for AEAD ciphers to num bits.

−−salt−file filename

Specify the file containing the salt for HKDF (optional)

−−info−file filename

Specify the file containing the info for HKDF (optional)

EXAMPLES

Perform a basic functionality test of the card:

pkcs11−tool −−test −−login

List all certificates on the smart card:

pkcs11−tool −−list−objects −−type cert

Read the certificate with ID CERT_ID in DER format from smart card and convert it to PEM via OpenSSL:

pkcs11−tool −−read−object −−id $CERT_ID −−type cert \

openssl x509 −inform DER −in cert.der −outform PEM > cert.pem

Write a certificate to token:

pkcs11−tool −−login −−write−object certificate.der −−type cert

Generate new RSA Key pair:

pkcs11−tool −−login −−keypairgen −−key−type RSA:2048

Generate new extractable RSA Key pair:

pkcs11−tool −−login −−keypairgen −−key−type RSA:2048 −−extractable

Generate an elliptic curve key pair with OpenSSL and import it to the card as $ID:

openssl genpkey −out EC_private.der −outform DER \

pkcs11−tool −−write−object EC_private.der −−id “$ID” \

openssl pkey −in EC_private.der −out EC_public.der \

pkcs11−tool −−write−object EC_public.der −−id “$ID” \

List private keys:

pkcs11−tool −−login −−list−objects −−type privkey

Sign some data stored in file data using the private key with ID ID and using the RSA−PKCS mechanism:

pkcs11−tool −−sign −−id $ID −−mechanism RSA−PKCS \

The same is also possible by piping the data from stdin rather than specifying a input file:

dd if=data bs=128 count=1 \

Verify the signed data:

pkcs11−tool −−id ID −−verify −m RSA−PKCS \

To encrypt file using the AES key with ID 85 and using mechanism AES−CBC with padding:

pkcs11−tool −−login −−encrypt −−id 85 −m AES−CBC−PAD \

Decipher the encrypted file:

pkcs11−tool −−login −−decrypt −−id 85 −m AES−CBC−PAD \

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

pkcs11−tool −−login −−wrap −−id 75 −−mechanism AES−CBC−PAD \

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

pkcs11−tool −−login −−unwrap −−mechanism RSA−PKCS −−id 22 \

Use the SO−PIN to initialize or re−set the PIN:

pkcs11−tool −−login −−login−type so −−init−pin

AUTHORS

pkcs11−tool was written by Olaf Kirch <okir@suse.de>.

---