--- name: "pkcs11-tool" section: "1" platform: "linux" package: "opensc" version: "0.27.1-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/pkcs11-tool" --- # pkcs11-tool(1) utility for managing and using PKCS #11 security tokens ## NAME pkcs11-tool - utility for managing and using PKCS #11 security tokens ## SYNOPSIS **pkcs11-tool** \[*OPTIONS*\] ## 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, EC:ED25519, EC:X448, GOSTR3410-2012-256:B, DES:8, DES3:24, AES:16, AES:, CHACHA20, POLY1305 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. - **--usage-encapsulate** Specify 'encapsulate' key usage flag (sets DECAPSULATE in privkey, sets ENCAPSULATE in pubkey). - **--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. - **--public-key-info** Read public key from the module using "CKA\_PUBLIC\_KEY\_INFO" (use with **--read-object --type public**). The output is a "SubjectPublicKeyInfo" i.e. as used in certificates and openssl. - **--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) - **--uri** *value* Specify the PKCS#11 URI for module, slot, token or object - **--uri-with-slot-id** Include SlotId in PKCS#11 URI ## 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 \ --output-file cert.der 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 \ -algorithm EC -pkeyopt ec_paramgen_curve:P-521 pkcs11-tool --write-object EC_private.der --id "$ID" \ --type privkey --label "EC private key" -p "$PIN" openssl pkey -in EC_private.der -out EC_public.der \ -pubout -inform DER -outform DER pkcs11-tool --write-object EC_public.der --id "$ID" \ --type pubkey --label "EC public key" -p $PIN ``` 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 \ --input-file data --output-file data.sig ``` The same is also possible by piping the data from stdin rather than specifying a input file: ``` dd if=data bs=128 count=1 \ | pkcs11-tool --sign --id $ID --mechanism RSA-PKCS \ > data.sig ``` Verify the signed data: ``` pkcs11-tool --id ID --verify -m RSA-PKCS \ --input-file data --signature-file data.sig ``` 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 \ --iv "00000000000000000000000000000000" \ -i file.txt -o encrypted_file.data ``` Decipher the encrypted file: ``` pkcs11-tool --login --decrypt --id 85 -m AES-CBC-PAD \ --iv "00000000000000000000000000000000" \ --i encrypted_file.data -o decrypted.txt ``` 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 \ --iv "00000000000000000000000000000000" \ --application-id 76 \ --output-file exported_aes.key ``` 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 \ -i aes_wrapped.key --key-type AES: \ --application-id 90 --application-label unwrapped-key ``` 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 \.