PyHSM Documentation

pipx install vectorguard-pyhsm

git clone https://github.com/pavondunbar/PyHSM.git
cd PyHSM
pipx install .

pipx install ".[dev]"    # includes pytest + pytest-cov
pipx install -e .        # editable mode

pipx install vectorguard-pyhsm

from hsm import PyHSM

# v2: all constructor parameters must be passed as keyword arguments
with PyHSM(storage_path="my-keystore.enc", master_password="strong-password-here") as hsm:
    # Generate an AES-256 encryption key
    hsm.generate_key("my-key", key_type="aes-256")

    # Encrypt sensitive data
    ciphertext = hsm.encrypt("my-key", "secret data")
    print(f"Ciphertext: {ciphertext}")

    # Decrypt it back — decrypt() always returns bytes in v2
    plaintext = hsm.decrypt("my-key", ciphertext)
    print(f"Plaintext: {plaintext.decode('utf-8')}")

# Generate an AES-256 key
vectorguard-pyhsm --store my-keystore.enc generate my-key --type aes-256

# Encrypt data
vectorguard-pyhsm --store my-keystore.enc encrypt my-key -d "secret data"

# Decrypt data
vectorguard-pyhsm --store my-keystore.enc decrypt my-key -d "<ciphertext-hex>"

from hsm import PyHSM

# v2: all parameters MUST be keyword arguments (positional args removed)
hsm = PyHSM(
    storage_path="keystore.enc",        # Path to encrypted keystore file
    master_password="your-password",    # Required, minimum 12 characters
    audit_log_path="audit.jsonl",       # Optional audit log path
    session_timeout_s=300.0,            # Session idle timeout (seconds)
    rate_limit_max_ops=100,             # Max operations per key per window
    rate_limit_window_s=60.0,           # Rate limit window (seconds)
    license_file="/etc/pyhsm/license.jwt",  # Commercial license token file (v2.3.0+, optional)
    # license_token="",     # Or: inline JWT string
)

with PyHSM(storage_path="keystore.enc", master_password="...") as hsm:
    # operations here
    pass
# Session closed, memory zeroized

# Primary class
from hsm import PyHSM

# Storage and errors
from hsm import KeyStore, TamperError
from hsm.backends import StorageBackend, FileBackend, MemoryBackend

# Security utilities
from hsm import SecureBytes, zeroize_bytearray
from hsm import AuditLog, RateLimiter, MetricsCollector
from hsm import run_self_tests

# Shamir secret sharing
from hsm import split_secret, reconstruct_secret, zeroize

# JWK support
from hsm import export_symmetric_jwk, export_ec_jwk
from hsm import export_rsa_jwk, export_ed25519_jwk

hsm.generate_key(
    key_id: str,                    # Unique identifier for the key
    key_type: str = "aes-256",      # Key type (see Key Types table)
    metadata: dict = None,          # Optional metadata dict
    policy: dict = None,            # Optional policy dict
    caller_id: str = None,          # Caller identity for ACL/audit
) -> str                            # Returns key_id

# AES-256 for symmetric encryption
hsm.generate_key("encryption-key", key_type="aes-256")

# Ed25519 for fast signing (Solana, SSH)
hsm.generate_key("signing-key", key_type="ed25519")

# secp256k1 for Ethereum/Bitcoin transaction signing
hsm.generate_key("eth-wallet", key_type="ec-secp256k1")

# RSA-4096 for legacy systems
hsm.generate_key("legacy-rsa", key_type="rsa-4096")

# With policy constraints
hsm.generate_key("limited-key", key_type="aes-256", policy={
    "max_operations": 10000,
    "allowed_callers": ["payment-service", "auth-service"],
    "allow_encrypt": True,
    "allow_decrypt": True,
    "expires_at": "2027-01-01T00:00:00Z",
    "rotate_every_days": 90,
})

hsm.encrypt(
    key_id: str,                    # Key to encrypt with
    plaintext: str | bytes,         # Data to encrypt
    caller_id: str = None,          # Caller identity
) -> str                            # Hex-encoded ciphertext

hsm.decrypt(
    key_id: str,                    # Key to decrypt with
    ciphertext_hex: str,            # Hex ciphertext from encrypt()
    caller_id: str = None,          # Caller identity
) -> bytes                          # Decrypted plaintext (always bytes in v2)

with PyHSM(storage_path="keystore.enc", master_password="...") as hsm:
    hsm.generate_key("data-key", key_type="aes-256")

    # Encrypt a private key, API token, or any sensitive data
    ciphertext = hsm.encrypt("data-key", "sk_live_abc123xyz")

    # Later, decrypt it — returns bytes in v2
    plaintext = hsm.decrypt("data-key", ciphertext)
    # plaintext = b"sk_live_abc123xyz"
    secret_str = plaintext.decode("utf-8")  # explicit decode if you need str

hsm.sign(
    key_id: str,                    # Asymmetric key to sign with
    message: str | bytes,           # Data to sign
    caller_id: str = None,
) -> str                            # Hex-encoded signature

hsm.verify(
    key_id: str,                    # Key to verify with
    message: str | bytes,           # Original message
    signature_hex: str,             # Hex signature from sign()
    caller_id: str = None,
) -> bool                           # True if valid

hsm.get_public_key(key_id: str) -> str  # PEM-encoded public key

with PyHSM("keystore.enc", master_password="...") as hsm:
    # Generate or import a secp256k1 wallet key
    hsm.generate_key("eth-wallet", key_type="ec-secp256k1")

    # Sign a transaction hash (32 bytes)
    tx_hash = bytes.fromhex("a1b2c3...")  # Your tx hash
    signature_hex = hsm.sign("eth-wallet", tx_hash)

    # Parse DER signature into (r, s, v) for broadcasting
    # The private key was unwrapped, used, and zeroized internally

with PyHSM(storage_path="keystore.enc", master_password="...") as hsm:
    # Rotate to a new version
    new_version = hsm.rotate_key("data-key")
    # new_version = 2

    # New encryptions use version 2
    ct_new = hsm.encrypt("data-key", "new data")

    # Old ciphertexts still decrypt (version 1 auto-selected)
    plaintext = hsm.decrypt("data-key", old_ciphertext)

hsm.generate_key("auto-rotate-key", key_type="aes-256", policy={
    "rotate_every_days": 90,  # Auto-rotate every 90 days
})

# Import an existing EC key from JWK
jwk_data = {
    "kty": "EC",
    "crv": "secp256k1",
    "x": "...",
    "y": "...",
    "d": "..."  # private key component
}
hsm.import_key_jwk("imported-wallet", jwk_data)

# Import an RSA key from JWK (v2 addition)
# NOTE (v2.3.1+): RSA keys below 2048 bits are rejected per NIST SP 800-131A Rev. 2
hsm.import_key_jwk("rsa-key", {
    "kty": "RSA",
    "n": "...",   # base64url modulus — must be 2048 or 4096 bits
    "e": "AQAB", # public exponent
    "d": "...",  # private exponent
})

# v2: allow_export defaults to False — must be explicitly set to True
hsm.generate_key("exportable-key", key_type="ed25519", policy={
    "allow_export": True,   # required in v2; previously could be unset
})

jwk = hsm.export_jwk("exportable-key")
# Returns standard JWK dict

vectorguard-pyhsm --store <path> generate <key_id> [options]

# Generate an AES-256 key
vectorguard-pyhsm generate vault-key --type aes-256

# Generate an Ed25519 signing key with max 5000 operations
vectorguard-pyhsm generate signer --type ed25519 --max-operations 5000

# Generate a key that expires
vectorguard-pyhsm generate temp-key --type aes-256 --expires-at 2027-06-01T00:00:00Z

# Encrypt with -d flag
vectorguard-pyhsm encrypt my-key -d "sensitive data"

# Encrypt from stdin
echo "sensitive data" | vectorguard-pyhsm encrypt my-key

# Decrypt hex ciphertext
vectorguard-pyhsm decrypt my-key -d "0200000001f383ad67..."

# Decrypt from stdin
echo "0200000001f383ad67..." | vectorguard-pyhsm decrypt my-key

vectorguard-pyhsm sign my-signing-key -d "message to sign"
# Output: hex-encoded signature

vectorguard-pyhsm verify my-signing-key "message to sign" "3045022100..."
# Exit code: 0 = VALID, 1 = INVALID

vectorguard-pyhsm pubkey my-signing-key
# Output: PEM-encoded public key

vectorguard-pyhsm split -k 3 -n 5 -s "64656d6f2d6d61737465722d70617373776f7264"

# Output (v2.2.0+ format with per-share HMAC-SHA256):
# Share 1: {"index": 1, "data": "d18a992fab...", "share_hmac": "...", "hmac_salt": "...", "reconstruction_hmac": "..."}
# Share 2: {"index": 2, "data": "0985e4adb3...", "share_hmac": "...", "hmac_salt": "...", "reconstruction_hmac": "..."}
# Share 3: {"index": 3, "data": "bc6a10ed35...", "share_hmac": "...", "hmac_salt": "...", "reconstruction_hmac": "..."}
# Share 4: {"index": 4, "data": "ce2a97e318...", "share_hmac": "...", "hmac_salt": "...", "reconstruction_hmac": "..."}
# Share 5: {"index": 5, "data": "7bc563a39e...", "share_hmac": "...", "hmac_salt": "...", "reconstruction_hmac": "..."}

vectorguard-pyhsm reconstruct \
  --share '{"index": 1, "data": "d18a992fab...", "share_hmac": "...", "hmac_salt": "...", "reconstruction_hmac": "..."}' \
  --share '{"index": 3, "data": "bc6a10ed35...", "share_hmac": "...", "hmac_salt": "...", "reconstruction_hmac": "..."}' \
  --share '{"index": 5, "data": "7bc563a39e...", "share_hmac": "...", "hmac_salt": "...", "reconstruction_hmac": "..."}'
# Output: 64656d6f2d6d61737465722d70617373776f7264

# Show all audit entries
vectorguard-pyhsm audit

# Verify audit log integrity (HMAC chain)
vectorguard-pyhsm audit --verify

# Filter by operation type
vectorguard-pyhsm audit --operation encrypt --since 2026-01-01T00:00:00Z

# Raw JSON output
vectorguard-pyhsm audit --raw

# Human-readable metrics
vectorguard-pyhsm metrics

# Prometheus text format
vectorguard-pyhsm metrics --prometheus

vectorguard-pyhsm --license-file /etc/pyhsm/license.jwt license

vectorguard-pyhsm --store keystore.enc license

export PYHSM_LICENSE_TOKEN="$(cat /etc/pyhsm/license.jwt)"
vectorguard-pyhsm --store keystore.enc license

info = hsm.get_license_info()
print(info.tier.value)      # "startup" | "growth" | "scale" | "agpl"
print(info.licensee)        # e.g. "you@example.com" or "agpl-user"
print(info.expires_at)      # ISO 8601 timestamp
print(info.max_keys)        # 5 for Startup, None for Growth/Scale/AGPL
print(info.is_commercial)   # True for paid tiers

hsm.generate_key("payment-key", key_type="aes-256", policy={
    "allowed_callers": ["payment-service", "billing-service"],
})

# This succeeds:
hsm.encrypt("payment-key", data, caller_id="payment-service")

# This raises ValueError + logs accessDenied:
hsm.encrypt("payment-key", data, caller_id="unknown-service")

# Configured at HSM initialization
hsm = PyHSM(
    "keystore.enc",
    master_password="...",
    rate_limit_max_ops=100,     # 100 operations...
    rate_limit_window_s=60.0,   # ...per 60-second window
)

hsm.generate_key("limited-key", key_type="aes-256", policy={
    "max_operations": 10000,  # After 10,000 ops, key is unusable
})

from hsm import AuditLog

audit = AuditLog(
    log_path="pyhsm-audit.jsonl",
    hmac_key=derived_key,              # Derived from master via HKDF
    webhook_url="https://siem.example.com/ingest",  # Optional
    max_bytes=50 * 1024 * 1024,        # 50 MB rotation threshold
    max_rotated_files=10,              # Keep 10 rotated files
)

# get_audit_log() returns an AuditLog object in v2 (not a raw list)
audit = hsm.get_audit_log()

# Programmatic verification (active log file only)
result = audit.verify()
# Returns -1 if chain is clean
# Returns sequence number of first corrupted entry otherwise

# Cross-rotation chain verification (v2.2.0+)
# Verifies the full chain across all retained rotated files.
# Deletion of any rotated file is detectable.
from hsm.audit import AuditLog
log = AuditLog('/var/log/pyhsm/keystore.enc.audit.jsonl', hmac_key=key)
result = log.verify_across_rotations()
# {"ok": True, "files_checked": 5}  — or error on tamper

# Export entries as a list of dicts (SIEM-ready)
entries = audit.export_jsonl()                         # all entries
entries = audit.export_jsonl(operation="encrypt")      # filter by operation

# CLI verification (active log)
vectorguard-pyhsm audit --verify

# CLI export for SIEM (CEF format for Splunk/QRadar/ArcSight)
vectorguard-pyhsm audit --siem-format cef | logger -t pyhsm -p security.info

# CLI export as JSON for Elastic/OpenSearch
vectorguard-pyhsm audit --siem-format json

from hsm import split_secret, reconstruct_secret, zeroize

# Split a secret into 5 shares, threshold of 3
secret = b"my-master-password"
shares = split_secret(secret, k=3, n=5)
# shares = [{"index": 1, "data": "hex...", "share_hmac": "...", "hmac_salt": "...", "reconstruction_hmac": "..."}, ...]

# Reconstruct from any 3 shares
recovered = reconstruct_secret(shares[:3])
# recovered = bytearray(b"my-master-password")

# Always zeroize after use
zeroize(recovered)

┌─────────────────────┐         ┌─────────────────────┐
│  Your Application   │  IPC    │   PyHSM Process     │
│                     │ ──────► │                     │
│  PyHSMClient        │  Unix   │  Keys in memory     │
│  (sends requests)   │  Socket │  Crypto operations  │
│                     │ ◄────── │  Zeroization        │
└─────────────────────┘         └─────────────────────┘

import { PyHSMClient } from "pyhsm-ts/client";

const client = new PyHSMClient("/tmp/pyhsm.sock", "my-service");

// All operations go through IPC
const ciphertext = await client.encrypt("data-key", "secret");
const plaintext = await client.decrypt("data-key", ciphertext);
const health = await client.health();
// { status: "ok", uptime: 3600 }

hsm.generate_key("production-key", key_type="aes-256", policy={
    "allow_encrypt": True,
    "allow_decrypt": True,
    "allow_export": False,
    "max_operations": 1000000,
    "expires_at": "2028-01-01T00:00:00Z",
    "rotate_every_days": 90,
    "allowed_callers": ["api-gateway", "worker-service"],
})

useradd --system --no-create-home --shell /usr/sbin/nologin pyhsm
install -d -m 750 -o pyhsm -g pyhsm /var/lib/pyhsm /run/pyhsm /var/log/pyhsm

# Place on tmpfs so it never touches disk
mount -t tmpfs -o size=1m,mode=700 tmpfs /run/secrets
printf '%s' 'YourStr0ng!Passphrase' > /run/secrets/pyhsm-password
chmod 600 /run/secrets/pyhsm-password
chown pyhsm:pyhsm /run/secrets/pyhsm-password

openssl rand -hex 32 > /run/secrets/pyhsm-ipc-secret
chmod 600 /run/secrets/pyhsm-ipc-secret
chown pyhsm:pyhsm /run/secrets/pyhsm-ipc-secret

pipx install --require-hashes -r requirements.lock

python3 -c "
from hsm.audit import AuditLog
import sys
key = open('/run/secrets/pyhsm-audit-key', 'rb').read()
log = AuditLog('/var/log/pyhsm/keystore.enc.audit.jsonl', hmac_key=key)
result = log.verify_across_rotations()
if result['ok']:
    print('Audit chain OK — files checked:', result['files_checked'])
else:
    print('TAMPER DETECTED:', result['first_error'], file=sys.stderr)
    sys.exit(1)
"

[ ] PyHSM runs as a dedicated unprivileged user (not root)
[ ] Keystore file: chmod 600, owned by pyhsm user
[ ] Password file: chmod 600, on tmpfs
[ ] IPC secret file: chmod 600, on tmpfs (openssl rand -hex 32)
[ ] IPC server started with --ipc-secret (mandatory as of v2.2.0)
[ ] Audit log: chmod 640, shipped to SIEM
[ ] verify_across_rotations() returns ok=true
[ ] Swap encrypted or disabled
[ ] pipx install --require-hashes -r requirements.lock
[ ] systemd unit: NoNewPrivileges=true, MemoryDenyWriteExecute=true
[ ] Backup tested with verify-backup
[ ] NTP synchronized (key expiry depends on accurate time)
[ ] auditd watching keystore and audit log files

cd pyhsm-ts
npm install
npm run build

import { PyHSM } from "./core";

// v2: PyHSM.create() is the ONLY supported factory for production use
// It guarantees Argon2id KDF (64 MB / 3 passes / 4 threads)
const hsm = await PyHSM.create({
  storePath: "./keystore.enc",
  masterPassword: "strong-password",
});

// Generate a key
hsm.generateKey("my-key");

// Encrypt and decrypt
const ct = hsm.encrypt("my-key", "secret data");
const pt = hsm.decrypt("my-key", ct);  // returns string

// Clean up
hsm.closeSession();