Registry / auth-security / pyjks
library20.0.0pypypiunverified

PyJKS is a pure-Python library for reading and writing Java KeyStore (JKS) files. It provides programmatic access to key entries, certificate entries, and trusted certificate entries within a JKS file. The current version is 20.0.0, and it is actively maintained with releases tied to significant updates and improvements.

pip install pyjks
INSTALL
IMPORT
SIG · PYJKS
P
pyjks
auth-securitypythonv20.0.0
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.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.103.95 runs
build_error
glibc
py 3.103.95 runs
build_error
Code
Verified usage

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

KeyStore
from jks import KeyStore
from pyjks import KeyStore
The package is named 'pyjks', but the main module containing the KeyStore class is 'jks'.
KeystoreException
from jks.util import KeystoreException
The base exception for JKS-related errors is found in `jks.util`.

This quickstart demonstrates how to load a Java KeyStore (JKS) file, authenticate with a password, and iterate through its entries. It uses `os.environ.get` for `KEYSTORE_PATH` and `KEYSTORE_PASSWORD` to allow easy configuration via environment variables or fall back to default placeholders. Error handling for `FileNotFoundError` and `jks.util.KeystoreException` is included for common issues like incorrect paths or passwords.

import jks import os # --- Configuration --- # Replace 'path/to/your/keystore.jks' with the actual path to your JKS file. # For a runnable example, ensure this file exists or temporarily create an empty one. keystore_path = os.environ.get('PYJKS_KEYSTORE_PATH', 'my_keystore.jks') # Replace 'your_keystore_password' with the actual password for your JKS file. # For security, avoid hardcoding passwords in production; use environment variables or a secret management system. keystore_password = os.environ.get('PYJKS_KEYSTORE_PASSWORD', 'changeit') # --- Quickstart Code --- try: # Attempt to load the keystore from the specified path and password with open(keystore_path, "rb") as f: ks = jks.KeyStore.load(f, keystore_password) print(f"Successfully loaded keystore from: {keystore_path}") print(f"Keystore type: {ks.ks_type}") print(f"Number of entries: {len(ks.entries)}") if not ks.entries: print("No entries found in the keystore.") else: print("\nKeystore Entries:") for alias, entry in ks.entries.items(): print(f" Alias: {alias}") print(f" Type: {entry.entry_type}") if entry.entry_type == 'key': print(f" Key Algorithm: {entry.algorithm}") # Further details like certificate chain can be accessed via entry.cert_chain elif entry.entry_type == 'cert': print(f" Certificate Subject: {entry.cert.subject.human_friendly}") # Further details like issuer, validity, etc., are available on entry.cert except FileNotFoundError: print(f"Error: Keystore file not found at '{keystore_path}'.") print("Please replace 'my_keystore.jks' with an actual path or create a dummy JKS file for testing.") except jks.util.KeystoreException as e: print(f"Error loading keystore: {e}") print("This often indicates an incorrect password or a corrupted/unsupported JKS format.") except Exception as e: print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingVersion 20.0.0 introduced major breaking API changes, particularly for `jks.util.KeyStore` and `jks.util.PrivateKey`. Code written for earlier versions (e.g., 19.x) will likely require updates.
fix
Refer to the `CHANGELOG.md` and the latest documentation/examples on the GitHub repository for updated API usage, especially around `KeyStore` loading and entry access.
affects: >=20.0.0
gotchaThe Python package name is `pyjks`, but the primary module to import is `jks`. Attempting to import `KeyStore` directly from `pyjks` (e.g., `from pyjks import KeyStore`) will fail.
fix
Always import classes like `KeyStore` from the `jks` module: `from jks import KeyStore`.
affects: All
gotchaPyJKS depends on the `cryptography` library, which often requires C/C++ compilers and development headers during installation, especially on Linux systems. Installation via `pip` might fail if these prerequisites are not met.
fix
Ensure you have the necessary build tools (e.g., `build-essential` on Debian/Ubuntu, `Xcode Command Line Tools` on macOS) and Python development headers installed before attempting `pip install pyjks`.
affects: All
gotchaWhile PyJKS supports JCEKS format as of version 17.0.0, there can be compatibility issues with older or very new Java KeyStore formats or specific providers. Attempting to load an unsupported or corrupted JKS file will raise a `jks.util.KeystoreException`.
fix
Always handle `jks.util.KeystoreException` when loading a keystore. If issues persist, verify the JKS file's integrity and version using Java's `keytool` utility or refer to `pyjks`'s GitHub issues for known compatibility notes.
affects: All
Errors
Common errors & fixes
error: Microsoft Visual C++ 14.0 is required. Get it with "Microsoft Visual C++ Build Tools"
This error occurs on Windows when installing pyjks (or its dependencies) because some of its underlying cryptographic libraries have C extensions that require a C++ compiler to be present on the system.
fix
Download and install the "Desktop development with C++" workload from Visual Studio Build Tools. Ensure that 'MSVC vxxx - VS 2019 C++ build tools', 'Windows 10 SDK (latest version)', and 'C++/CLI support for build tools' are selected during installation. After installation and a reboot, run `pip install pyjks` again.
ValueError: Hash mismatch; incorrect password or data corrupted
This error typically indicates that the provided password for loading the keystore is incorrect, or the JKS/JCEKS file itself is corrupted or malformed.
fix
Double-check the keystore password for accuracy, including any leading/trailing spaces or case sensitivity. If you are certain the password is correct, the keystore file might be damaged, or it could be an unsupported keystore type. Ensure the `pyjks` version supports the specific JCEKS features used if applicable, as older versions had limitations.
jks.util.BadKeystoreFormatException: Not a JKS or JCEKS keystore (magic number wrong; expected FEEDFEED or CECECECE)
This error means that the file being loaded does not have the expected 'magic number' at its beginning, which signifies a valid JKS or JCEKS keystore format. It often happens when trying to open a PKCS12 (.p12) file or a corrupted file.
fix
Verify that the file you are attempting to load is indeed a standard JKS or JCEKS file. PyJKS does not directly support PKCS12 files; for those, you would typically use `OpenSSL.crypto.load_pkcs12` (from the `pyOpenSSL` library) instead.
jks.util.NotYetDecryptedException
This exception occurs when you try to access attributes (like `private_key` or `cert`) of a key entry that has not yet been successfully decrypted. By default, `jks.KeyStore.load()` attempts to decrypt keys using the store password, but if a key has a different password, it remains encrypted.
fix
After loading the keystore, iterate through the entries and explicitly call the `decrypt()` method on any `PrivateKeyEntry` or `SecretKeyEntry` using its specific password. For example: `entry.decrypt(key_specific_password)`. Alternatively, ensure `try_decrypt_keys=True` is passed to `KeyStore.load()` if all key entries share the store password.
ModuleNotFoundError: No module named 'pyjks'
Despite a successful `pip install pyjks`, this error can occur if Python is being run from a different environment (e.g., a different virtual environment, or the system Python if installed in a virtual environment) where `pyjks` is not installed.
fix
Ensure you are activating and running Python from the same virtual environment (if used) where `pyjks` was installed. For example, after `source venv/bin/activate` (Linux/macOS) or `venv\Scripts\activate` (Windows), then run your Python script. Verify installation with `pip list | grep pyjks` in the active environment.
Upgrade
Version history
20.0.0latest on PyPI · released Apr 19, 2020
Audit
Dependencies
cryptographyrequiredProvides cryptographic primitives for handling keys and certificates, including AES, RSA, and SHA operations.
Agent activity
20 hits · last 30 days
node
18
OpenAI (training)
1
Resources