pkcs11-tool

1 OpenSC OpenSC Tools opensc

pkcs11-tool

utility for managing and using PKCS #11 security tokens

    			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 okir@suse.de.