PyJKS

Warnings

• breaking 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.
  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.
• gotcha 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.
  Fix: Always import classes like `KeyStore` from the `jks` module: `from jks import KeyStore`.
• gotcha 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.
  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`.
• gotcha 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`.
  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.

Install

• pip install pyjks Install PyJKS

Imports

• KeyStore

  from jks 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`.

Quickstart

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}")