Registry / auth-security / pykcs11

pykcs11

JSON →
library1.5.18pypypi✓ verified 89d ago

PyKCS11 is a comprehensive Python wrapper for the PKCS#11 standard, enabling interaction with Hardware Security Modules (HSMs) and smart cards. It provides Python bindings for PKCS#11 functions, constants, and structures. The library is actively maintained with periodic releases, typically several times a year, with the current stable version being 1.5.18.

pip install pykcs11
INSTALL
IMPORT
SIG · PYKCS11
P
pykcs11
auth-securitypythonv1.5.18
Install
—
Import
—
Disk
—
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.920 runs
build_error
glibc
py 3.10–3.920 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PyKCS11
✓ import PyKCS11

This quickstart demonstrates how to load a PKCS#11 library, open a session, log in with a user PIN, and list objects (keys, certificates) present on the token. Replace `PKCS11_LIB_PATH` and `PKCS11_USER_PIN` with your actual PKCS#11 library path and PIN. For testing, SoftHSMv2 is a common choice.

import PyKCS11 import os # Path to your PKCS#11 shared library (e.g., softhsm2.so, libeToken.so) # For testing, consider installing SoftHSMv2. pkcs11_lib_path = os.environ.get('PKCS11_LIB_PATH', '/usr/local/lib/softhsm/libsofthsm2.so') user_pin = os.environ.get('PKCS11_USER_PIN', '1234') try: # Initialize the PyKCS11 library wrapper pkcs11 = PyKCS11.PyKCS11Lib() pkcs11.load(pkcs11_lib_path) # Get a list of available slots with a token present slots = pkcs11.getSlotList(tokenPresent=True) if not slots: print("No PKCS#11 slots with tokens found. Ensure your HSM/smart card is connected and configured.") exit() # Open a session with the first available slot session = pkcs11.openSession(slots[0]) # Log in to the token (required for most operations) session.login(user_pin) print(f"Successfully logged into slot {slots[0]} using PIN.") # Example: Find and list objects (e.g., keys, certificates) objects = session.findObjects() print(f"\nFound {len(objects)} objects in the token:") for obj in objects: # Attempt to get CKA_CLASS and CKA_LABEL attributes gracefully attributes = session.getAttributeValue(obj, [PyKCS11.CKA_CLASS, PyKCS11.CKA_LABEL]) obj_class = next((attr for attr in attributes if attr.type == PyKCS11.CKA_CLASS), None) obj_label = next((attr for attr in attributes if attr.type == PyKCS11.CKA_LABEL), None) class_name = pkcs11.constantToString(obj_class.value, PyKCS11.CKF_CLASS_DEFINED) if obj_class else 'N/A' label = obj_label.value if obj_label else 'N/A' print(f" - Class: {class_name}, Label: {label}") finally: # Ensure logout, close session, and unload library in a finally block if 'session' in locals() and session: try: session.logout() session.closeSession() print("\nLogged out and session closed.") except PyKCS11.PyKCS11Error as e: print(f"Error during cleanup: {e}") if 'pkcs11' in locals() and pkcs11: try: pkcs11.unload() print("PKCS#11 library unloaded.") except PyKCS11.PyKCS11Error as e: print(f"Error during library unload: {e}")
Debug
Known issues
deprecatedPython 2 support was officially removed in PyKCS11 v1.5.17. Users on older Python versions must upgrade to Python 3.
fix
Upgrade your Python environment to Python 3.x. Ensure your code is compatible with Python 3.
affects: <1.5.17
gotchaOlder versions of PyKCS11 (prior to 1.5.18) may have had thread-safety issues with `PyKCS11Lib.load()` and `PyKCS11Lib.unload()` methods in multi-threaded environments.
fix
Upgrade to PyKCS11 v1.5.18 or newer for improved thread-safety. If using an older version, ensure `load()` and `unload()` are called from a single thread or protected by explicit locks.
affects: <1.5.18
gotchaOn Python 3.12, a garbage collector issue could occur when calling `C_Finalize()` (implicitly called during `PyKCS11Lib.unload()`), potentially leading to crashes or unexpected behavior.
fix
Upgrade to PyKCS11 v1.5.13 or newer, which includes a specific fix for this Python 3.12 garbage collector interaction.
affects: 1.5.0 - 1.5.12 (on Python 3.12)
gotchaBuilding PyKCS11 from source requires `SWIG` (Simplified Wrapper and Interface Generator) to be installed on your system. This is often encountered when `pip install pykcs11` fails to find a pre-built wheel.
fix
Ensure `SWIG` is installed on your system (e.g., `sudo apt-get install swig` on Debian/Ubuntu, `brew install swig` on macOS). For a binary installation, ensure `pip` can find a compatible wheel.
affects: All versions (when building from source)
gotchaThe path to the PKCS#11 shared library (e.g., `.so` or `.dll` file) is highly system-dependent and must be provided correctly to `PyKCS11Lib.load()`. Incorrect paths are a very common source of errors.
fix
Verify the exact path to your PKCS#11 provider's shared library. Common locations include `/usr/local/lib/softhsm/libsofthsm2.so` (SoftHSMv2 on Linux), `/usr/lib/libeToken.so` (eToken on Linux), or specific vendor directories. Consult your HSM/smart card documentation.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'PyKCS11'
The PyKCS11 library is not installed in your current Python environment.
fix
Run `pip install pykcs11` to install the package.
PyKCS11.PyKCS11Error: CKR_GENERAL_ERROR: PKCS#11 function C_Initialize returned 0x5.
The PKCS#11 shared library could not be loaded or initialized, often due to an incorrect path, missing dependencies of the shared library, or permission issues.
fix
Double-check the `pkcs11_lib_path` provided to `pkcs11.load()`. Ensure the shared library exists, is readable, and its own dependencies (if any) are met. Also, ensure the library is compatible with your system's architecture (e.g., 64-bit Python with 64-bit PKCS#11 library).
PyKCS11.PyKCS11Error: CKR_PIN_INCORRECT: PKCS#11 function C_Login returned 0x100.
The provided PIN for logging into the token is incorrect.
fix
Verify the `user_pin` value. Ensure the token is not locked due to too many incorrect attempts. Some tokens have separate 'User PIN' and 'SO PIN' (Security Officer PIN).
PyKCS11.PyKCS11Error: CKR_SLOT_ID_INVALID: PKCS#11 function C_OpenSession returned 0x3.
No valid PKCS#11 slot with a token was found, or the specified slot ID is invalid.
fix
Ensure your HSM or smart card is correctly inserted and detected by the system. Use `pkcs11.getSlotList(tokenPresent=True)` to confirm active slots before attempting to open a session.
TypeError: 'NoneType' object has no attribute 'value'
Attempting to access `.value` or other attributes on a `PyKCS11` object attribute (e.g., `obj_label`) that was not found for a specific PKCS#11 object, resulting in `None`.
fix
Always check if the attribute object is `None` before attempting to access its properties. Use a conditional check or `next((attr for attr in attributes if attr.type == ...), None)` as shown in the quickstart to provide a default or handle missing attributes gracefully.
Upgrade
Version history
1.5.18latest on PyPI · released Aug 3, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
27 hits · last 30 days
node
26
OpenAI (training)
1
Resources
pykcs11 — pip install pykcs11 · libregistry