Skip to main content

uv-pkcs11

PyPI

An unofficial fork of uv — the extremely fast Python package and project manager — with PKCS#11 client-certificate (mTLS) support, so uv can authenticate to package indexes with keys held in PKCS#11 providers that never expose the private key.

The fork never logs in to a token, so it works with providers whose certificate and key are usable without a PIN: software HSMs, network HSMs unlocked out of band, and p11-kit-proxied providers configured for loginless use. Ordinary PIN-protected smart cards and tokens that require C_Login before private-key use are not supported. The PKCS#11 support itself is new (beta): tested end to end against SoftHSM, with limited real-world provider mileage so far.

This project is not affiliated with or endorsed by Astral. The fork lives at github.com/dtrodrigues/uv-pkcs11 and is published on PyPI as uv-pkcs11; for everything except the PKCS#11 additions, see the upstream documentation.

Usage

Client-certificate behavior is controlled entirely by SSL_CLIENT_CERT:

  • A pkcs11: URI (an RFC 7512 subset) selects a PKCS#11 identity:

    $ export SSL_CLIENT_CERT='pkcs11:?module-path=/path/to/pkcs11-module.so'
    $ uv pip install --index-url https://my-mtls-index.example.com/simple/ some-package
    

    The path attributes token, serial, id (percent-encoded CKA_ID), and object (certificate label) narrow the match when tokens hold more than one identity, for example pkcs11:id=%01 or pkcs11:token=MyToken; type=cert is accepted, other attributes are rejected. The module-path query attribute must be an absolute path, and the named module is native code loaded into the process — only point it at a module you trust. Without a module-path query attribute, the p11-kit proxy (p11-kit-proxy.so; p11-kit-proxy.dylib on macOS) is loaded, picking up any module registered with p11-kit. Exactly one identity must match, otherwise uv reports an error naming the candidates.

  • A file path is a PEM client certificate and key, exactly as in upstream uv.

  • Unset means no client certificate — stock uv behavior. PKCS#11 is never activated implicitly.

Notes:

  • No PIN is presented and no login is performed: the certificate/key pair must be visible in a public session (providers unlocked out of band work as-is; PIN-protected devices requiring login will not). pin-value/pin-source URI attributes are rejected.
  • RSA only (PKCS#1 v1.5 and PSS with SHA-256/384/512); the identity applies only to verified HTTPS connections, never to hosts marked --allow-insecure-host.
  • Hash-and-sign mechanisms (CKM_SHA*_RSA_PKCS, CKM_SHA*_RSA_PKCS_PSS) are preferred; providers that only expose the raw CKM_RSA_PKCS and CKM_RSA_PKCS_PSS mechanisms work too, with the handshake transcript hashed by uv and the token padding and signing the digest. A provider without CKM_RSA_PKCS_PSS can only authenticate over TLS 1.2, since TLS 1.3 requires RSA-PSS for client certificates. CKM_RSA_X_509 is not used.
  • A key's CKA_ALLOWED_MECHANISMS, where the provider reports it, narrows the mechanisms offered for that key, so a key restricted to part of the token's mechanism list advertises only the schemes it can actually produce.
  • Only the leaf certificate is sent; intermediates must be known to the server.
  • A certificate is only considered when it can sign as a TLS client: its keyUsage, if present, must include digitalSignature (a keyEncipherment-only RSA key-exchange certificate is passed over), and its extendedKeyUsage, if present, must include clientAuth. Selecting such a certificate explicitly reports the reason; uv-pkcs11-inspect lists it next to the certificate.

Known limitations (kept simple on purpose; both surface as TLS handshake failures rather than discovery-time errors):

  • Pairing trusts the provider's CKA_ID convention: the certificate's public key is not compared against the private key, so a stale or mispaired certificate sharing the key's CKA_ID is selected and fails when the server verifies the handshake signature. Re-provision the token so certificate and key match.
  • Signature schemes are offered based on C_GetMechanismList and the key's CKA_ALLOWED_MECHANISMS: per-mechanism CKF_SIGN flags and key-size ranges from C_GetMechanismInfo are not checked, so a token that lists an RSA mechanism it cannot use with the selected key (for example a key outside the mechanism's supported size range) fails in C_Sign during the handshake.

Diagnosing a token

The wheel installs uv-pkcs11-inspect next to uv and uvx. It lists the tokens, certificates, and private keys a module exposes without login and applies the same selection rules as uv, so its verdict is what uv will do with the same URI. Pass the pkcs11: URI you intend to put in SSL_CLIENT_CERT, or just a module path; with no argument, the p11-kit proxy is inspected. For every identity it finds it prints the URI that names that identity, ready to paste into SSL_CLIENT_CERT. The exit status is 0 when exactly one identity would be selected.

$ uv-pkcs11-inspect 'pkcs11:?module-path=/path/to/pkcs11-module.so'
Module: /path/to/pkcs11-module.so

Token `MyToken` (slot 1)
  Signing: RSA_PSS_SHA512, RSA_PSS_SHA384, RSA_PSS_SHA256, RSA_PKCS1_SHA512, ...
  Certificates: 1
    CKA_ID 3f9a…         label `My Certificate`
  Private keys: 1
    CKA_ID 3f9a…         label `My Key`  RSA_PSS_SHA512, RSA_PSS_SHA384, ...

OK: exactly one usable identity across all tokens: token `MyToken`, CKA_ID 3f9a….
URI: pkcs11:token=MyToken;id=%3f%9a…?module-path=/path/to/pkcs11-module.so

The printed URI names that identity and nothing else: it carries the token label (or the token's serial number, when labels repeat), the CKA_ID, and the certificate's object label when two certificates share the CKA_ID. With several identities it prints AMBIGUOUS and one URI per identity, so you can pass back the one you want; with none it prints NOT USABLE and a hint (for example that nothing is visible without login). uv-pkcs11-inspect --version reports the fork build it came from.

Installation

$ pip install uv-pkcs11

Releases are published to PyPI at pypi.org/project/uv-pkcs11. Wheels are built for Linux (x86_64 and aarch64) and macOS (Apple Silicon); other platforms build from the sdist. The distribution installs the uv and uvx commands and therefore must not be installed alongside the official uv distribution in the same environment — install one or the other.

Versioning

Wheel versions mirror the upstream uv release the fork is built from (e.g. 0.12.9); a fourth component (0.12.9.1, 0.12.9.2, ...) marks a fork-side re-release on the same upstream base. Note that PEP 440 treats 0.12.9.0 as equal to 0.12.9, so re-releases start at .1. uv self update support is intentionally not built in — it would replace this fork with official uv binaries.

The binary identifies itself as the fork: uv --version and uv self version end with a [uv-pkcs11 <fork version>] marker naming the exact fork release (the version itself stays the upstream version so required-version checks keep working), and uv self version --output-format json reports "package_name": "uv-pkcs11" and "fork_version", so you can confirm which build is installed.

$ uv --version
uv 0.12.9 (1a2b3c4d5 2026-09-01 aarch64-apple-darwin) [uv-pkcs11 0.12.9.1]

Metadata

Release files for uv-pkcs11 0.12.21

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for uv-pkcs11 0.12.21
File Size Uploaded Provenance Actions
uv_pkcs11-0.12.21.tar.gz 7.2 MB Without provenance Details for uv_pkcs11-0.12.21.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for uv-pkcs11 0.12.21
File Interpreter ABI Platform Actions
uv_pkcs11-0.12.21-py3-none-manylinux_2_28_aarch64.whl Python 3 none Linux glibc 2.28+ ARM64 Details for uv_pkcs11-0.12.21-py3-none-manylinux_2_28_aarch64.whl
uv_pkcs11-0.12.21-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for uv_pkcs11-0.12.21-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
uv_pkcs11-0.12.21-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for uv_pkcs11-0.12.21-py3-none-macosx_11_0_arm64.whl

Total release size: 77.6 MB

Release files / uv_pkcs11-0.12.21.tar.gz

Download URL uv_pkcs11-0.12.21.tar.gz
Size 7.2 MB
Tags Source
SHA-256 checksum
How to use checksums
a0ce84db4e7d4c2fb733dbe030a027eef9992f9beaf6e6968c9d693028da51f5
BLAKE2b-256 checksum
How to use checksums
cd052e7ccdf184c12b176717cfde7be71c60b22af766cf1984b11c295bd4ad0d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / uv_pkcs11-0.12.21-py3-none-manylinux_2_28_aarch64.whl

Download URL uv_pkcs11-0.12.21-py3-none-manylinux_2_28_aarch64.whl
Size 24.0 MB
Tags Linux glibc 2.28+ ARM64 Python 3
SHA-256 checksum
How to use checksums
c37e51a9142122357ea4d5c4ed2fcbff92a2442b1c0659607ae70c345f7ca38e
BLAKE2b-256 checksum
How to use checksums
f5accef9b5837545dc600b6b4dbd93fbf43e100630d0af2146503ea9dc79c1c7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / uv_pkcs11-0.12.21-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL uv_pkcs11-0.12.21-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 25.0 MB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
34e0e12ce9fc087f87360d95f30db1e069b1c24efd565fffa5d53ef7dec9f384
BLAKE2b-256 checksum
How to use checksums
7e202bada8620eba0fb50ab4beda3942569d0ac94421684474098ed0119e2a58
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / uv_pkcs11-0.12.21-py3-none-macosx_11_0_arm64.whl

Download URL uv_pkcs11-0.12.21-py3-none-macosx_11_0_arm64.whl
Size 21.3 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
d6fb7af836f77045e437147faea0e48f2b6bf7bb6fcbb4b5a5838f0441df871a
BLAKE2b-256 checksum
How to use checksums
5c2e8236f21a4304542471daa467e894622c82f4cac9811b0c52ee41da77abd8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for uv-pkcs11 0.12.21

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page