PyHSM Documentation

pip install vectorguard-pyhsm

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

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

pip install vectorguard-pyhsm

from hsm import PyHSM

with PyHSM("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
    plaintext = hsm.decrypt("my-key", ciphertext)
    print(f"Plaintext: {plaintext.decode()}")

# 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

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

with PyHSM("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

with PyHSM("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
    plaintext = hsm.decrypt("data-key", ciphertext)
    # plaintext = b"sk_live_abc123xyz"

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

# Export requires allow_export policy
hsm.generate_key("exportable-key", key_type="ed25519", policy={
    "allow_export": True,
})

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:
# Share 1: {"index": 1, "data": "d18a992fab..."}
# Share 2: {"index": 2, "data": "0985e4adb3..."}
# Share 3: {"index": 3, "data": "bc6a10ed35..."}
# Share 4: {"index": 4, "data": "ce2a97e318..."}
# Share 5: {"index": 5, "data": "7bc563a39e..."}

vectorguard-pyhsm reconstruct \
  --share '{"index": 1, "data": "d18a992fab..."}' \
  --share '{"index": 3, "data": "bc6a10ed35..."}' \
  --share '{"index": 5, "data": "7bc563a39e..."}'
# 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

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
)

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

# CLI verification
vectorguard-pyhsm audit --verify

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..."}, ...]

# 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"],
})

cd pyhsm-ts
npm install
npm run build

import { PyHSM } from "./core";

// Async factory (uses Argon2id)
const hsm = await PyHSM.create({
  keystorePath: "./keystore.enc",
  masterPassword: "strong-password",
  auditLogPath: "./audit.jsonl",
});

// Generate a key
await hsm.generateKey("my-key", { type: "aes-256" });

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

// Clean up
hsm.close();