softhsm2-util is the primary support tool for libsofthsm2. It initializes tokens, imports key material, and manages the lifecycle of PKCS#11 tokens. It can also be used with any other PKCS#11 library via --module.
Actions
Display all available slots and their current status, including whether a token is initialized and its label and serial number.
Show configuration info.
var may be one of:default-pkcs11-lib— print the path to the default PKCS#11 library.
Initialize the token at a given slot, token label, or serial number. If the token is already initialized, this command reinitializes it, erasing all objects in the token. The matching Security Officer (SO) PIN must be provided when reinitializing. After initialization, the token is reassigned to a slot based on its serial number.Use with
--slot, --token, --serial, or --free; and --label, --so-pin, and --pin.Import an object from the file at
path. Supports keypairs (PKCS#8 PEM), AES keys (raw binary), and X.509 certificates (PEM).Use with --import-type, --slot or --token or --serial, --file-pin, --pin, --no-public-key, --label, and --id.Delete the token at a given slot. Use with
--token or --serial.Show the help screen.
Show version info.
Options
Specify the type of object to import.
type may be one of:keypair(default) — the file must be in PKCS#8 PEM format.aes— the file must be in raw binary format.cert— the file must be in X.509 PEM format.
Tells
--import to treat the input file as-is and import it as an AES key.The PIN used to decrypt an encrypted PKCS#8 input file. If not provided, the file is assumed to be unencrypted.
Override warnings and force the given action. When importing a key pair, use this flag if the specified
--id already exists in the token.Use the first free (uninitialized) token slot. Use with
--init-token.The ID to assign to the imported object. Must be provided as a hexadecimal string of variable length (e.g.,
A1B2). Use --force if another object with the same ID already exists.The label to assign to the object (when importing) or to the token (when initializing).
Use an alternative PKCS#11 library instead of the default SoftHSM library. Provide the path to the
.so or .dylib file.Do not import the public key portion of a key pair. Only the private key object is stored in the token.
The PIN for the normal (user) role. Required for operations that access token objects.
Select the token whose serial number matches
number. An alternative to --slot and --token.The slot number where the target token is located.
The PIN for the Security Officer (SO) role. Required when initializing or reinitializing a token.
Select the token whose label matches
label. An alternative to --slot and --serial.Examples
Initialize a new token
Use--free to pick the first available slot automatically:
List all slots
Import a key pair
Import a PKCS#8 PEM key file into an existing token:Import an AES key
Import an X.509 certificate
Delete a token
Show the default PKCS#11 library path
Use with a non-SoftHSM PKCS#11 library
Key import workflow
Prepare the key file
Keys must be in PKCS#8 PEM format for keypairs, raw binary for AES, or X.509 PEM for certificates. To convert from BIND
.private-key format, use softhsm2-keyconv.See also
softhsm2-keyconv— convert BIND.private-keyfiles to PKCS#8softhsm2-migrate— migrate SoftHSM v1 token databasessofthsm2.conf(5)— SoftHSM configuration file reference