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

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

opensc                                             03/22/2025                                     PKCS11-TOOL(1)

       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.

       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 --applicatin-label unwrapped-key

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

           pkcs11-tool --login --login-type so --init-pin

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

--attr-fromfilename
           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-algorithmmechanism
           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.

       --idid, -did
           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-filefilename, -ifilename
           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-typespecification
           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.

       --labelname, -aname
           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').

       --mechanismmechanism, -mmechanism
           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.

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

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

       --moz-certfilename, -zfilename
           Test a Mozilla-like key pair generation and certificate request. Specify the filename to the
           certificate file.

       --output-filefilename, -ofilename
           Specify the path to a file for output.

       --pinpin, -ppin
           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.

       --pukpuk
           Supply User PUK on the command line.

       --new-pinpin
           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-idid, -eid
           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-lenbytes
           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).

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

       --slot-descriptiondescription
           Specify the description of the slot to use.

       --slot-indexindex
           Specify the index of the slot to use.

       --object-indexindex
           Specify the index of the object to use.

       --use-locking
           Tell pkcs11 module it should use OS thread locking.

       --test-threadsoptions
           Test a pkcs11 module's thread implication. (See source code).

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

       --so-pinpin
           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-mechanismsmechanisms
           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.

       --typetype, -ytype
           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-labellabel
           Specify the application label of the data object (use with --type data).

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

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

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

       --signature-filefilename
           The path to the signature file for signature verification

       --signature-formatformat
           Format for ECDSA signature: 'rs' (default), 'sequence', 'openssl'.

       --write-objectfilename, -wfilename
           Write a key or certificate object to the token.  filename points to the DER-encoded certificate or
           key file.

       --generate-randomnum
           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.

       --ivdata
           Initialization vector for symmetric ciphers. The data is hexadecimal number, i.e. "000013aa7bffa0".

       --mac-general-paramnum
           Sets the length of the MAC for the general-length MACing mechanisms to num bytes.

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

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

       --salt-filefilename
           Specify the file containing the salt for HKDF (optional)

       --info-filefilename
           Specify the file containing the info for HKDF (optional)

pkcs11-tool [OPTIONS]