# Cryptography and Key Management

Trustpoint separates certificate metadata (stored in PostgreSQL) from private-key operations (delegated to PKCS#11 providers). This separation enables hardware HSM support, key-access auditing, and crypto-agile design.

## Cryptographic Architecture

```{mermaid}
flowchart TB
    PKI_SERVICE["PKI domain services / certificate issuance, signing"]
    CRYPTO_API["Crypto provider abstraction / trustpoint/crypto/"]
    
    PKI_SERVICE --> CRYPTO_API
    
    CRYPTO_API --> PROVIDER_PROFILE["Provider profile / PKCS#11 config / token selector"]
    
    PROVIDER_PROFILE --> ADAPTER{Crypto adapter}
    
    ADAPTER -->|Production| PKCS11_ADAPTER["PKCS#11 adapter / generic PKCS#11 module"]
    ADAPTER -->|Development| SOFTWARE_ADAPTER["Software adapter / in-memory keys"]
    ADAPTER -->|Future| FUTURE_ADAPTER[REST, KMS, other providers]
    
    PKCS11_ADAPTER --> MODULE["PKCS#11 module / libsofthsm2.so or hardware HSM"]
    MODULE --> TOKEN["PKCS#11 token / slot + PIN authentication"]
    
    TOKEN --> KEYS["Private keys / RSA, ECDSA"]
    
    CRYPTO_API --> BINDING_DB[("PostgreSQL / key metadata / binding to token")]
```

## Architectural Rules

1. **Private keys never leave the HSM in production:** Keys are generated in the PKCS#11 token and used for signing operations. The private-key bytes are never exported to Trustpoint's database or filesystem.

2. **Metadata separation:** Certificate objects, device records, and domain configuration are stored in PostgreSQL. Private-key metadata (key ID, token serial, public key) is stored in `CryptoManagedKeyModel` and `CryptoManagedKeyPkcs11BindingModel`.

3. **Provider abstraction:** The `crypto` module provides a uniform API for key generation, signing, and public-key retrieval. Different providers (PKCS#11, software, future REST/KMS) implement the same interface.

4. **Token selection:** PKCS#11 providers support multiple tokens. The provider profile specifies token-selection criteria (serial number, label, slot index).

5. **Protected imported credentials (optional):** Trustpoint supports importing externally generated private keys. These keys are encrypted using Trustpoint's application-secret protection and optionally wrapped by a PKCS#11 key. This feature is disabled by default and intended for migration scenarios only.

## Cryptographic Providers

### PKCS#11 Provider

**Purpose:** Generic PKCS#11 module support for hardware and software HSMs

**Module:** `trustpoint/crypto/adapters/pkcs11/`

**Supported HSMs:**
- SoftHSM (development and testing)
- Hardware HSMs: Thales, Utimaco, Gemalto, YubiHSM, etc.
- Cloud HSMs with PKCS#11 interface
- PKCS#11 proxies (e.g., for remote HSMs)

**Configuration fields:**
- `module_path`: Path to PKCS#11 library (e.g., `/usr/lib/libsofthsm2.so`)
- `token_serial`: Token serial number
- `token_label`: Token label
- `slot_index`: Token slot index
- `auth_source`: PIN authentication source (`file`, `environment`, `prompt`)
- `pin_file`: Path to PIN file (if `auth_source=file`)

**Token selection:**
- By serial number (preferred for production)
- By label (human-readable, but may not be unique)
- By slot index (may change on HSM restart)

### Software Provider

**Purpose:** In-memory keys for development and testing

**Module:** `trustpoint/crypto/adapters/software/`

**Characteristics:**
- Keys generated in memory
- Private keys stored in Python objects
- No hardware protection
- **Not secure for production**

**Use cases:**
- Unit testing
- Development without HSM
- CI/CD pipelines
- Quick prototyping

**Limitations:**
- Keys lost on process restart
- No multi-process key sharing
- No audit trail for key operations

## Key Generation

### Supported Key Algorithms

**RSA:**
- `RSA_2048`: 2048-bit RSA (minimum recommended)
- `RSA_3072`: 3072-bit RSA
- `RSA_4096`: 4096-bit RSA

**ECDSA:**
- `ECDSA_P256`: NIST P-256 (secp256r1)
- `ECDSA_P384`: NIST P-384 (secp384r1)
- `ECDSA_P521`: NIST P-521 (secp521r1)

## Security Best Practices

1. **Use hardware HSM in production:** SoftHSM is for development only

2. **Never export private keys:** Configure PKCS#11 with `CKA_EXTRACTABLE=False`

3. **Rotate keys regularly:** Establish key rotation procedures for CAs

4. **Backup HSM keys securely:** Use HSM-specific backup procedures

5. **Protect PIN files:** Restrict filesystem permissions (mode 600, owner www-data)

6. **Use strong PINs:** Minimum 8 characters, mixed case, numbers, symbols

7. **Monitor key operations:** Enable HSM audit logging

8. **Test key recovery:** Verify HSM backup and restore procedures

9. **Separate CA keys:** Use different keys for different CAs

10. **Document key inventory:** Maintain record of all managed keys and their purposes

## Future Enhancements

- **Cloud KMS integration:** AWS KMS, Azure Key Vault, Google Cloud KMS
- **Key rotation automation:** Automatic CA key rotation with overlap period
- **Post-quantum cryptography:** Prepare for PQC algorithms (ML-DSA, SLH-DSA)
- **Key ceremony support:** Structured key generation and backup procedures
- **Hardware security module clustering:** High-availability HSM configuration
- **Key usage auditing:** Detailed audit trail for all key operations
- **Threshold cryptography:** Multi-party signing for critical operations