pypkcs11-tool

A single-file Python port of OpenSC's pkcs11-tool command line utility. It talks to PKCS#11 modules through python-pkcs11 and reproduces the pkcs11-tool option surface, including its usage listing order and output format, so existing scripts and expectations keep working.

The tool runs against a real PKCS#11 library (for example SoftHSM2) as well as against a pure Python stub implementation, which is useful on platforms where a native module is not available.

Features

• Slot, token, mechanism and object listing (-L, -T, -M, -O).
• Global token information (-I), including token flags and hardware features.
• Object management: write (-w), read (-r), delete (-b), -e/--set-id, --attr-from, application label/ID, issuer and subject attributes.
• Key pair generation (-k/--keypairgen) for RSA, EC, ML-DSA, ML-KEM, GOST and more, plus symmetric key generation (--keygen) for AES, DES3, GENERIC, HKDF, CHACHA20 and POLY1305.
• Cryptographic operations: sign (-s), verify (--verify), encrypt (--encrypt), decrypt (--decrypt), hash (-h), derive (--derive, --derive-pass-der), wrap (--wrap) and unwrap (--unwrap).
• Mechanism parameters: --hash-algorithm, --mgf, --salt-len, --iv, --mac-general-param, --aad, --tag-bits-len, --salt-file, --info-file.
• Session and login control: -l/--login, --login-type, -p/--pin, --puk, --new-pin, --so-pin, --session-rw, --session-only, --use-locking.
• Token management: --init-token, --init-pin, -c/--change-pin, --unlock-pin.
• Diagnostics: -t/--test, --test-ec, --test-fork, --test-threads, --test-hotplug, --generate-random, --list-interfaces, --public-key-info, --allow-sw.
• PKCS#11 URI support: --uri and --uri-with-slot-id, including pin-value and pin-source handling.
• Slot selection by id, index, description or token label (--slot, --slot-index, --slot-description, --token-label), and object selection with --object-index.

Requirements

• Python 3.14 or newer.
• A PKCS#11 module to talk to (for example SoftHSM2), and python-pkcs11 0.10.0 for real hardware/library access.
• cryptography for the mechanisms implemented in pure Python (AEAD ciphers, HKDF, modern post-quantum algorithms).

python-pkcs11 is a declared dependency, so pip install . pulls it in. cryptography is optional and available through the crypto extra (pip install ".[crypto]"); without it those features are skipped, mirroring a pkcs11-tool built without OpenSSL.

Installation

From a source checkout:

python -m pip install .

With the optional cryptography extra:

python -m pip install ".[crypto]"

For development (editable install):

python -m pip install -e .

Either install exposes the pypkcs11-tool console script.

Usage

After installation:

pypkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so -L

You can also run the package as a module:

python -m pypkcs11_tool --module /usr/lib/softhsm/libsofthsm2.so -L

The --module option may be omitted when a PKCS#11 URI supplies module-path.

Examples

List slots, tokens and objects:

pypkcs11-tool --module /path/to/pkcs11.so -L
pypkcs11-tool --module /path/to/pkcs11.so -T
pypkcs11-tool --module /path/to/pkcs11.so -O --login --pin 1234

Show token information and supported mechanisms:

pypkcs11-tool --module /path/to/pkcs11.so -I
pypkcs11-tool --module /path/to/pkcs11.so -M

Generate a symmetric key and random data:

pypkcs11-tool --module /path/to/pkcs11.so --login --pin 1234 \
    --keygen --key-type AES:256 --usage-encrypt --usage-decrypt -d 30
pypkcs11-tool --module /path/to/pkcs11.so --generate-random 32

Sign and verify:

pypkcs11-tool --module /path/to/pkcs11.so --login --pin 1234 \
    --sign --mechanism SHA256-RSA-PKCS -d 01 -i data.bin -o sig.bin
pypkcs11-tool --module /path/to/pkcs11.so \
    --verify --mechanism SHA256-RSA-PKCS -d 01 -i data.bin --signature-file sig.bin

Use a PKCS#11 URI:

pypkcs11-tool --uri 'pkcs11:module-path=/path/to/pkcs11.so;token=my-token;type=private;id=%01;pin-value=1234' \
    --sign --mechanism SHA256-RSA-PKCS -i data.bin -o sig.bin

Run the built-in self tests:

pypkcs11-tool --module /path/to/pkcs11.so --login --pin 1234 --test
pypkcs11-tool --module /path/to/pkcs11.so --login --pin 1234 --test-ec

Options

pypkcs11-tool --help prints the complete option list in the same order as pkcs11-tool's Usage: section. The main groups are:

Group	Options
Informational	-I, -L, -T, -M, -O, --list-interfaces
Data operations	-s/--sign, --verify, --decrypt, --encrypt, --wrap, --unwrap, -h/--hash, --derive, --derive-pass-der
Mechanism parameters	-m/--mechanism, --hash-algorithm, --mgf, --salt-len, --iv, --mac-general-param, --aad, --tag-bits-len, --salt-file, --info-file
Session / login	--session-rw, --session-only, -l/--login, --login-type, -p/--pin, --puk, --new-pin, --so-pin, --use-locking
Token management	--init-token, --init-pin, -c/--change-pin, --unlock-pin
Key generation	-k/--keypairgen, --keygen, --key-type, --usage-sign, --usage-decrypt, --usage-derive, --usage-wrap, --usage-encapsulate
Object management	-w/--write-object, -r/--read-object, -b/--delete-object, --application-label, --application-id, --issuer, --subject, -y/--type, -d/--id, -a/--label, -e/--set-id, --attr-from
Selection	--slot, --slot-description, --slot-index, --object-index, --token-label
I/O	-i/--input-file, --signature-file, -o/--output-file, -f/--signature-format
Object attributes	--private, --sensitive, --extractable, --undestroyable, --always-auth, --allowed-mechanisms
Tests / misc	-t/--test, --test-hotplug, --test-ec, --test-fork, --test-threads, --generate-random, --allow-sw, --public-key-info, --uri, --uri-with-slot-id

Use -M to list the mechanisms supported by the selected token, and -m <name-or-hex> (for example -m SHA256-RSA-PKCS or -m 0x80001234) to select a mechanism.

Notes and compatibility

• pypkcs11-tool is a port, not a drop-in replacement: it aims for byte-compatible output and option ordering, but it is implemented on top of python-pkcs11 and Python, not the OpenSC C library.
• Token attribute names differ between the pure Python stub and python-pkcs11; the tool resolves both transparently.
• Some token-management operations are validated and reported but do not yet perform a real C_InitToken/C_InitPIN/C_SetPIN call against the library.
• When no native module is available, the pure Python stub can be used for development and testing.

Development

The command line implementation lives in src/pypkcs11_tool/cli.py, exposed as the pypkcs11-tool console script and the python -m pypkcs11_tool module.

python -m pip install -e .
pypkcs11-tool --help

License

This project is licensed under the GNU Lesser General Public License v2.1 or later (LGPL-2.1-or-later). See the LICENSE file for the full text.