pkcs11-tool

List slots and their potential token, using a specific module (e.g. /usr/lib/softhsm/libsofthsm2.so)

$ pkcs11-tool --module [path/to/module.so] [[-L|--list-slots]] [[-T|--list-token-slots]]

$ pkcs11-tool [[-O|--list-objects]] [[-p|--pin]] [auth_pin] --slot [slot_id]

$ pkcs11-tool --slot [slot_id] [[-p|--pin]] [auth_pin] [[-y|--type]] [cert|privkey|pubkey|secrkey|data|...] [[-a|--label]] "[label]" [[-d|--id]] [01] [[-w|--write-object]] [path/to/cert.crt]

$ pkcs11-tool --slot [slot_id] [[-p|--pin]] [auth_pin] [[-y|--type]] [cert|privkey|pubkey|secrkey|data|...] [[-a|--label]] "[label]" [[-b|--delete-object]]

pkcs11-tool [OPTIONS]

-M, --module <path>
    Loads the specified PKCS#11 shared library file (e.g., /usr/lib/opensc-pkcs11.so).

-P, --pin <PIN>
    Provides the user PIN for authentication or cryptographic operations.

-s, --slot <num>
    Selects the PKCS#11 slot by its numerical ID.

--list-slots
    Displays all available PKCS#11 slots and their detailed information.

--list-tokens
    Lists all cryptographic tokens found within the available slots.

--list-objects
    Enumerates all cryptographic objects (keys, certificates, data) on the currently logged-in token.

--login
    Establishes a user session on the token, typically requiring the --pin option.

--logout
    Terminates the active user session on the token.

--init-token
    Initializes a new PKCS#11 token, setting its label and Security Officer (SO) PIN. Requires --label and --so-pin.

--init-pin
    Initializes the user PIN for an already initialized token. Requires --so-pin and --new-pin.

--change-pin
    Changes the user PIN of the logged-in token. Requires the current --pin and --new-pin.

--gen-keypair
    Generates a new cryptographic key pair (e.g., RSA, EC) on the token. Requires --key-type and --bits.

--key-type <type>
    Specifies the type of key to generate, such as RSA or EC.

--bits <num>
    Defines the key size in bits for generated keys (e.g., 2048 for RSA).

--label <label>
    Assigns a human-readable label to an object during creation or identifies an existing object.

--id <hex_id>
    Assigns a unique hexadecimal ID to an object or identifies an existing object by its ID.

--delete-object
    Deletes a specific object from the token, identified by --id or --label.

--read-object
    Reads the content of an object from the token. Requires --id or --label.

--write-object <file>
    Writes data from a specified file as a new object onto the token.

--test
    Executes a built-in self-test of the token's cryptographic capabilities.

pkcs11-tool is a powerful command-line utility for interacting with PKCS#11 compliant cryptographic tokens, such as smart cards and Hardware Security Modules (HSMs).

It provides comprehensive functionalities to manage cryptographic objects like keys and certificates, and to perform various security operations. Users can list available PKCS#11 slots and tokens, initialize tokens and PINs, generate key pairs (e.g., RSA, EC), import and export objects, and change user/SO PINs.

The tool also supports cryptographic operations such as signing, verification, encryption, and decryption, making it indispensable for testing PKCS#11 drivers, automating key management tasks, and diagnosing issues with secure hardware. It is part of the OpenSC project, widely used in environments requiring strong authentication and secure key storage.

Using pkcs11-tool requires careful handling of sensitive information like PINs and private keys.

Incorrect usage, especially with commands like --init-token or --delete-object, can lead to permanent data loss or render the token unusable.

The exact behavior and supported mechanisms can vary significantly between different PKCS#11 modules and hardware tokens.

PKCS#11 (Cryptoki) is a standard API for cryptographic tokens, defining how applications can interact with cryptographic devices like smart cards or HSMs. pkcs11-tool provides a direct command-line interface to this API, enabling low-level management and operations without custom programming.

To use pkcs11-tool, you must specify the path to the PKCS#11 shared library (.so file) of your token using the --module option. Common paths include /usr/lib/opensc-pkcs11.so, /usr/lib/softhsm/libsofthsm2.so, or vendor-specific library paths provided by your hardware vendor.

pkcs11-tool is a core component of the OpenSC project, an open-source initiative dedicated to providing secure smart card and PKCS#11 support on Linux and other Unix-like operating systems.

Its development began in the early 2000s, aligning with the growing demand for standardized interfaces to cryptographic hardware. Over the years, it has evolved to support various PKCS#11 versions and a wide range of hardware security modules and smart cards, establishing itself as a de-facto standard command-line utility for PKCS#11 interaction in the open-source ecosystem.

pkcs15-tool(1), opensc-tool(1), p11tool(1), certtool(1), ssh-keygen(1)