Metadata-Version: 2.4
Name: pypkcs11-tool
Version: 0.0.1
Summary: pypkcs11-tool CLI Python script
Author-email: Gil Weisbord <gil.weisbord@gmail.com>
License-Expression: LGPL-2.1-or-later
Project-URL: Homepage, https://github.com/gilweis/pypkcs11-tool
Project-URL: Issues, https://github.com/gilweis/pypkcs11-tool/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-pkcs11>=0.10.0
Provides-Extra: crypto
Requires-Dist: cryptography>=41.0; extra == "crypto"
Dynamic: license-file

# pypkcs11-tool

A single-file Python port of OpenSC's [`pkcs11-tool`](https://github.com/OpenSC/OpenSC/wiki/pkcs11-tool)
command line utility. It talks to PKCS#11 modules through
[`python-pkcs11`](https://pypi.org/project/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](https://www.opendnssec.org/softhsm/)) 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`](https://pypi.org/project/python-pkcs11/) **0.10.0** for real
  hardware/library access.
- [`cryptography`](https://pypi.org/project/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:

```console
python -m pip install .
```

With the optional `cryptography` extra:

```console
python -m pip install ".[crypto]"
```

For development (editable install):

```console
python -m pip install -e .
```

Either install exposes the `pypkcs11-tool` console script.

## Usage

After installation:

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

You can also run the package as a module:

```console
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:

```console
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:

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

Generate a symmetric key and random data:

```console
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:

```console
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:

```console
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:

```console
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.

```console
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](LICENSE) file for the full text.

