FreeBSD Manual Pages
PKCS11-TOOL(1) OpenSC Tools PKCS11-TOOL(1) 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, 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 \ --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 AUTHORS pkcs11-tool was written by Olaf Kirch <okir@suse.de>. opensc 11/02/2025 PKCS11-TOOL(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=pkcs11-tool&sektion=1&manpath=FreeBSD+Ports+15.0>