{"id":4706,"library":"pyjks","title":"PyJKS","description":"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.","status":"active","version":"20.0.0","language":"python","source_language":"en","source_url":"https://github.com/kurtbrose/pyjks","tags":["security","java","keystore","jks","cryptography"],"install":[{"cmd":"pip install pyjks","lang":"bash","label":"Install PyJKS"}],"dependencies":[{"reason":"Provides cryptographic primitives for handling keys and certificates, including AES, RSA, and SHA operations.","package":"cryptography","optional":false}],"imports":[{"note":"The package is named 'pyjks', but the main module containing the KeyStore class is 'jks'.","wrong":"from pyjks import KeyStore","symbol":"KeyStore","correct":"from jks import KeyStore"},{"note":"The base exception for JKS-related errors is found in `jks.util`.","symbol":"KeystoreException","correct":"from jks.util import KeystoreException"}],"quickstart":{"code":"import jks\nimport os\n\n# --- Configuration ---\n# Replace 'path/to/your/keystore.jks' with the actual path to your JKS file.\n# For a runnable example, ensure this file exists or temporarily create an empty one.\nkeystore_path = os.environ.get('PYJKS_KEYSTORE_PATH', 'my_keystore.jks')\n\n# Replace 'your_keystore_password' with the actual password for your JKS file.\n# For security, avoid hardcoding passwords in production; use environment variables or a secret management system.\nkeystore_password = os.environ.get('PYJKS_KEYSTORE_PASSWORD', 'changeit')\n\n# --- Quickstart Code ---\ntry:\n    # Attempt to load the keystore from the specified path and password\n    with open(keystore_path, \"rb\") as f:\n        ks = jks.KeyStore.load(f, keystore_password)\n\n    print(f\"Successfully loaded keystore from: {keystore_path}\")\n    print(f\"Keystore type: {ks.ks_type}\")\n    print(f\"Number of entries: {len(ks.entries)}\")\n\n    if not ks.entries:\n        print(\"No entries found in the keystore.\")\n    else:\n        print(\"\\nKeystore Entries:\")\n        for alias, entry in ks.entries.items():\n            print(f\"  Alias: {alias}\")\n            print(f\"    Type: {entry.entry_type}\")\n            if entry.entry_type == 'key':\n                print(f\"    Key Algorithm: {entry.algorithm}\")\n                # Further details like certificate chain can be accessed via entry.cert_chain\n            elif entry.entry_type == 'cert':\n                print(f\"    Certificate Subject: {entry.cert.subject.human_friendly}\")\n                # Further details like issuer, validity, etc., are available on entry.cert\n\nexcept FileNotFoundError:\n    print(f\"Error: Keystore file not found at '{keystore_path}'.\")\n    print(\"Please replace 'my_keystore.jks' with an actual path or create a dummy JKS file for testing.\")\nexcept jks.util.KeystoreException as e:\n    print(f\"Error loading keystore: {e}\")\n    print(\"This often indicates an incorrect password or a corrupted/unsupported JKS format.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=20.0.0"},{"fix":"Always import classes like `KeyStore` from the `jks` module: `from jks import KeyStore`.","message":"The 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.","severity":"gotcha","affected_versions":"All"},{"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`.","message":"PyJKS 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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"While 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`.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"search_vec":"'20.0.0':38 'access':20 'activ':42 'certif':24,28 'cryptographi':56 'current':35 'entri':23,25,29 'file':16,33 'improv':51 'java':13,53 'jks':15,32,55 'key':22 'keystor':14,54 'librari':8 'maintain':43 'programmat':19 'provid':18 'pure':6 'pure-python':5 'pyjk':1,2 'python':7 'read':10 'releas':45 'secur':52 'signific':48 'tie':46 'trust':27 'updat':49 'version':36 'within':30 'write':12","created_at":"2026-04-12T14:04:08.096351+00:00","updated_at":"2026-04-16T18:30:30.023870+00:00","problems":[{"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.","cause":"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.","error":"error: Microsoft Visual C++ 14.0 is required. Get it with \"Microsoft Visual C++ Build Tools\""},{"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.","cause":"This error typically indicates that the provided password for loading the keystore is incorrect, or the JKS/JCEKS file itself is corrupted or malformed.","error":"ValueError: Hash mismatch; incorrect password or data corrupted"},{"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.","cause":"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.","error":"jks.util.BadKeystoreFormatException: Not a JKS or JCEKS keystore (magic number wrong; expected FEEDFEED or CECECECE)"},{"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.","cause":"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.","error":"jks.util.NotYetDecryptedException"},{"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.","cause":"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.","error":"ModuleNotFoundError: No module named 'pyjks'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"20.0.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"http://github.com/kurtbrose/pyjks","docs":null,"changelog":null,"pypi":"https://pypi.org/project/pyjks/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["auth-security","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"failing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}