Protect the Digital Secrets
That Keep Your Business Running.

Vault solves a different problem at a different scale. It's a secrets management platform — it manages database credentials, API tokens, PKI certificates, and dynamic secrets across an organization. It requires Consul for HA, needs dedicated operators, and the Enterprise license for features like HSM auto-unseal costs six figures.

PyHSM is a focused key management library. You pip install it, import it in your code, and you have key generation, signing, encryption, and audit logging in five lines. There's no cluster to manage, no Consul dependency, no operator UI to secure, no HCL policy language to learn.

Use Vault if: You need org-wide secrets management with 50 services and dynamic credential rotation.

Use PyHSM if: You need to encrypt data or sign transactions from your application with proper key lifecycle management — without the operational overhead.

Additional distinction: Vault's Transit engine doesn't support secp256k1. If you're signing Ethereum or Bitcoin transactions, Vault can't do it natively. PyHSM can.

Short answer: PyHSM doesn't claim the key is impossible to extract. It makes extraction as difficult as possible within software constraints, and makes all access auditable.

The layers of defense:

1. Double-encrypted at rest. The keystore file is AES-256-GCM encrypted (master password → Argon2id → HKDF → encryption key). Each individual key inside is additionally wrapped with AES-KWP (RFC 5649).
2. Never in memory as immutable objects. Key material is stored as mutable bytearray (Python) or Buffer (Node.js) and deterministically zeroized byte-by-byte after each operation.
3. The API never returns raw key bytes. You call hsm.sign() and get a signature back. The private key is unwrapped internally, used, and zeroized.
4. Process isolation mode puts the keys in a separate OS process. Even a full RCE in your application can't read the HSM process's address space without a kernel exploit.
5. Export is explicit and audited. export_jwk() exists for interoperability, but it's a deliberate call that gets logged in the audit trail.

What PyHSM cannot prevent: A root-level attacker with memory debugging tools attached to the running HSM process during the microseconds of signing. That's what hardware HSMs solve with a physical trust boundary.

Key rotation generates a new key version and archives the old one. Old ciphertexts remain decryptable because the version number is embedded in the ciphertext format.

Mechanically:

1. New random key material is generated (os.urandom(32))
2. It's wrapped with AES-KWP before storage
3. The previous version is marked archived: true
4. New encrypt() calls use the new version
5. decrypt() reads the version prefix from the ciphertext header and selects the matching key version automatically

This means you can rotate keys without re-encrypting your entire database. Old data decrypts with the old version, new data uses the new version.

Rotation is currently supported for AES keys. Asymmetric keys (EC, RSA, Ed25519) don't rotate in-place — you generate a new key ID and transition callers.

Each audit entry contains an HMAC that chains to the previous entry — similar to a blockchain of log records.

To tamper with entry N, an attacker would need to recompute the HMAC for entries N, N+1, N+2, ... all the way to the end. And to compute any HMAC, they need the audit HMAC key — which is derived from the master password via HKDF.

Verification walks the chain and checks every HMAC against its predecessor. If any entry was modified, inserted, or deleted, the chain breaks and verification reports the exact sequence number where corruption occurred.

The log is append-only — entries are never modified or deleted during normal operation. Every operation (including denied ones) is recorded with timestamp, operation type, key ID, caller ID, and success/failure status.

PyHSM provides the following guarantees:

• Confidentiality at rest: AES-256-GCM / AES-256-GCM-SIV (NIST SP 800-38D / RFC 8452)
• Key wrapping: AES-KWP (RFC 5649)
• Key derivation: Argon2id (64MB/3 passes) → HKDF-Expand (RFC 9106 / RFC 5869)
• Authentication: Encrypt-then-MAC (HMAC-SHA256) — proven-secure composition
• Nonce safety: Hybrid nonce (random+counter+random) / GCM-SIV — birthday bound eliminated
• Signing (ECDSA): SHA-256 (P-256, secp256k1), SHA-384 (P-384), SHA-512 (P-521) — FIPS 186-5
• Signing (EdDSA): Ed25519 (RFC 8032)
• Constant-time comparison: Timing side-channel resistant
• Audit integrity: HMAC-chained append-only log — tamper-evident

What is explicitly NOT guaranteed: Protection against kernel-level access, CPU side-channel attacks, physical access to hardware, or compromised underlying crypto libraries.

PyHSM defends against five classes of threat actors:

• T1: Network attacker — Process isolation; app never holds keys
• T2: App-level code execution — Rate limiting, ACLs, operation caps, process isolation
• T3: Filesystem read access — Double-encryption (AES-GCM + AES-KWP), Argon2id
• T4: Malicious insider — Shamir M-of-N, tamper detection, audit log
• T5: Root/kernel access — LIMITED — deterministic zeroization reduces window only

In-scope: Filesystem theft, application compromise, unauthorized key usage, silent key abuse, insider threats with partial access, keystore tampering, audit log manipulation.

Out-of-scope (acknowledged): Root attacker with debugger during signing, CPU side-channels, physical hardware access, compromised OS kernel.

It depends on your constraints. Neither is universally better.

Use AWS KMS if: You're in a regulated environment requiring FIPS certification, you're already all-in on AWS, you don't need secp256k1/Ed25519, and you're fine with per-operation costs and network latency.

Use PyHSM if: You need secp256k1/Ed25519 signing (blockchain), you want to avoid per-operation costs at scale, you require data sovereignty, you want zero vendor lock-in, or your latency budget can't tolerate network round-trips for every operation.

Key differences: AWS KMS costs $1/key/month + $0.03/10K API calls and adds 5–50ms latency per operation. PyHSM is free (MIT), runs locally with sub-millisecond crypto latency, supports secp256k1 and Ed25519 (which KMS doesn't), and has no vendor lock-in — you can export keys in standard JWK format.

They're not mutually exclusive: Some teams use AWS KMS for general infrastructure encryption and PyHSM specifically for blockchain transaction signing where AWS has no native support.

Process isolation is the highest security configuration PyHSM offers within software constraints. It separates key material into a dedicated OS process that communicates with your application over a Unix domain socket (IPC).

Why it matters: Without isolation, an attacker who achieves Remote Code Execution (RCE) in your application can read anything in that process's memory — including any key material that happens to be unwrapped at that moment. With process isolation, the keys live in a separate address space. The attacker would need a kernel exploit to cross that boundary.

How it works:

1. The HSM process starts independently, loads the encrypted keystore, and listens on a Unix socket (e.g., /run/pyhsm/pyhsm.sock).
2. Your application connects as a client and sends operation requests (encrypt, sign, rotate, etc.) over the socket.
3. The HSM process unwraps the key, performs the cryptographic operation, zeroizes the key from memory, and returns only the result (ciphertext, signature, etc.).
4. Your application never sees raw key bytes — it only receives operation outputs.

Authentication: The client authenticates each request using an HMAC over the message payload with a shared caller secret (PYHSM_CALLER_SECRET). This prevents other processes on the same host from issuing unauthorized commands to the socket.

Trade-offs: Process isolation adds IPC latency (typically <1ms on localhost) and operational complexity (two processes to manage instead of one). For most deployments, this is negligible compared to the security gain.

In production, you don't want a single person (or a single .env file) holding the master password that unlocks all keys. PyHSM implements Shamir's Secret Sharing over GF(256) to split the master password into N shares where any K shares can reconstruct it — but K-1 or fewer reveal zero information about the secret.

Typical setup (3-of-5):

1. During initial deployment, the security team generates 5 shares from the master password.
2. Each share is distributed to a different key custodian (stored offline, in separate locations, or in separate password managers).
3. At startup, 3 custodians provide their shares to unlock the HSM. No single custodian can unlock it alone.

Security properties:

• K-1 shares reveal nothing. Even if an attacker steals 2 of 5 shares (in a 3-of-5 scheme), they gain zero knowledge about the master password. This is mathematically proven, not just computationally hard.
• Intermediate buffers are zeroized. After reconstruction, the share data and intermediate polynomial evaluation buffers are deterministically cleared from memory.
• Works with environment variables. In containerized deployments, shares can be injected via PYHSM_SHARES as a comma-separated list of JSON objects — each provided by a different secrets manager or operator.

When to use Shamir: Any deployment where the master password represents a single point of failure — production systems, multi-team environments, regulatory contexts requiring separation of duties, or anywhere you need to survive the "hit by a bus" scenario.

This is by design — it's a security property of Shamir Secret Sharing, not a bug.

Why the shares differ each time: Shamir Secret Sharing works by generating a random polynomial of degree K-1 (where K is your threshold). The secret is the constant term (the y-intercept), but the other coefficients are randomly chosen each time you run split.

For a 3-of-5 split, PyHSM generates a random degree-2 polynomial:

f(x) = secret + a1*x + a2*x² (over GF(256))

• secret is fixed (your master password bytes)
• a1 and a2 are randomly generated each time

The shares are points on this polynomial: Share 1 = f(1), Share 2 = f(2), etc. Different random coefficients produce a different polynomial, which produces different shares — but the same y-intercept (your secret).

Why reconstruction still works: Any 3 points on a degree-2 polynomial uniquely determine that polynomial, and therefore uniquely determine f(0) — the secret. Your shares and someone else's shares are from different polynomials that pass through the same point at x=0.

Visual intuition:

• Run 1: f(x) = secret + 7x + 3x² → shares A, B, C, D, E
• Run 2: g(x) = secret + 2x + 9x² → shares V, W, X, Y, Z

Both f(0) = g(0) = secret. But f(1) ≠ g(1), f(2) ≠ g(2), etc.

Why this matters for security: This randomness is critical. If the same secret always produced the same shares, an attacker who saw shares from two different split ceremonies could cross-reference them. The random coefficients ensure that every split is independent — even if you split the same secret 1,000 times, the shares are completely different each time and reveal nothing about each other.

Yes — blockchain signing is one of PyHSM's primary use cases and a key differentiator from cloud KMS solutions like AWS KMS or Google Cloud KMS, which don't support secp256k1 or Ed25519.

Supported blockchain ecosystems:

• Ethereum / EVM chains (secp256k1 + ECDSA): Sign raw transaction hashes for Ethereum, Polygon, Arbitrum, Optimism, BSC, and any EVM-compatible network.
• Bitcoin (secp256k1 + ECDSA): Sign Bitcoin transactions with the same curve and algorithm Bitcoin uses natively.
• Solana / Cosmos (Ed25519 + EdDSA): High-performance 64-byte signatures for Solana transactions, Cosmos SDK messages, and any Ed25519-based protocol.

How it works in practice:

1. Import your existing private key (e.g., from MetaMask export) via JWK, or generate a fresh wallet key directly in PyHSM.
2. The private key is AES-KWP double-encrypted at rest — it never sits in plaintext on disk.
3. Your application builds and hashes the transaction, then calls hsm.sign("eth-wallet", tx_hash).
4. PyHSM unwraps the key, signs, zeroizes the key from memory, and returns only the signature.
5. Your application parses the DER-encoded signature into (r, s, v) and broadcasts.

Security advantages over raw key files:

• The key is never in a .env file — it's double-encrypted and requires the master password (or M-of-N Shamir shares) to unlock.
• Every signing operation is recorded in the HMAC-chained audit log with caller ID, timestamp, and key version.
• Rate limiting and max_operations policies prevent unlimited signing even if the application is compromised.
• Process isolation mode ensures key material lives in a separate address space from your application.

Production considerations: Latency is ~103ms per sign operation (dominated by keystore persistence). For high-frequency use cases, consider the TypeScript layer's deferred persistence mode. For cold wallets or treasury keys, combine with Shamir 3-of-5 so no single operator can unlock the signing key.