PKCS11-TOOL(1)

📦
version 0.27.1 · 17 versions
, in fedora 43, fedora 44

okay bestie, welcome to pkcs11-tool(1) from OpenSC Tools. She's literally the utility for managing and using PKCS #11 security tokens, and she's about to spill every single flag. No cap, we're keeping all the details. 💅

✨ NAME ✨

pkcs11-tool — utility for managing and using PKCS #11 security tokens. That's the name, that's the whole vibe, periodt. 💖

🌸 SYNOPSIS 🌸

pkcs11-tool [OPTIONS]

She takes options. That's it. Simple. Elegant. Ate. ✨

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

So yes bestie, she's your token bestie: list stuff, read stuff, and do the PIN auth when the operation needs it. Slay. 👑

👑 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 — extra authenticated data for AEAD ciphers 💖 bestie, this one's a hexadecimal number, so no sneaking in anything else, okay?
  • --tag-bits-len num — sets the tag length for AEAD ciphers to num bits. that's it, that's the whole job ✨
  • --salt-file filename — points at the file holding the salt for HKDF. it's optional 🧂
  • --info-file filename — points at the file holding the info for HKDF. also optional 🫶
  • --uri value — drops the PKCS#11 URI for a module, slot, token or object. very main character of you 🌈
  • --uri-with-slot-id — throws the SlotId into the PKCS#11 URI too 💅

✨ EXAMPLES ✨

okay this is the part where it all clicks, i promise 🎀

Do a basic functionality test of the card:

pkcs11-tool --test --login

List every certificate sitting on the smart card:

pkcs11-tool --list-objects --type cert

Read the certificate with ID CERT_ID off the card in DER format, then hand it to OpenSSL so it becomes PEM:

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 onto the token:

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

Generate a brand new RSA key pair:

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

Generate a brand new extractable RSA key pair (yes, extractable, she said what she said 🔥):

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 the private keys:

pkcs11-tool --login --list-objects --type privkey

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

pkcs11-tool --sign --id $ID --mechanism RSA-PKCS \
     --input-file data --output-file data.sig

Same energy, but you pipe the data in from stdin instead of naming an 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

Encrypt a file using the AES key with ID 85 and the AES-CBC mechanism with padding:

pkcs11-tool --login --encrypt --id 85 -m AES-CBC-PAD \
     --iv "00000000000000000000000000000000" \
     -i file.txt -o encrypted_file.data

Decipher that 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, mechanism AES-CBC-PAD, and initialization vector "00000000000000000000000000000000" to wrap the key with ID 76 into the 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 a key from file aes_wrapped.key. After a successful unwrap operation, a new AES key is created on the token. Its ID is set to 90 and its label is set to unwrapped-key.

⚠️ note bestie: for the MyEID card, the AES key size must be present in the 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 <okir@suse.de>. absolute legend behaviour, we stan 🫶

aaaand that's the whole page, bestie!! 🌸 this one shipped as part of opensc and the page itself is dated 04/19/2026. go forth and handle your keys responsibly, ily, mwah 💖✨🎀🦋

📦 where this page comes from