same-secret used for:
- HMAC webhook verification,
- encrypting database fields,
- signing internal tokens,
- deriving user reset tokens.

key: hmac-webhook-partner-x-v2026-06
purpose: verify partner X webhook signatures
operations: MAC verify, MAC generate if sending callbacks
owner: integration-platform
cryptoperiod: 180 days
rotation: dual acceptance for 14 days

{
  "ciphertext": "base64..."
}

{
  "scheme": "field-encryption-v2",
  "algorithm": "AES-256-GCM",
  "keyId": "tenant-123-dek-2026-06",
  "keyVersion": 7,
  "wrappedKeyId": "reg-platform-kek-prod-2026",
  "iv": "base64...",
  "aad": "case:caseId:version",
  "ciphertext": "base64...",
  "tag": "included-by-provider-or-separated-by-format"
}

{
  "signatureScheme": "audit-event-signature-v1",
  "algorithm": "Ed25519",
  "keyId": "audit-signing-prod-2026-q2",
  "publicKeySetVersion": "2026-06-30",
  "canonicalization": "audit-event-c14n-v1",
  "signedAt": "2026-06-30T08:00:00Z",
  "signature": "base64..."
}

[ ] Store key ID/version with every protected object.
[ ] Store algorithm/scheme version with every protected object.
[ ] Store canonicalization version for signatures.
[ ] Store key lifecycle state outside the object in key registry.
[ ] Do not infer key from current config for old data.

import javax.crypto.KeyGenerator;
import javax.crypto.SecretKey;
import java.security.SecureRandom;

public final class LocalKeyGeneration {
    private LocalKeyGeneration() {}

    public static SecretKey aes256Key() throws Exception {
        KeyGenerator generator = KeyGenerator.getInstance("AES");
        generator.init(256, SecureRandom.getInstanceStrong());
        return generator.generateKey();
    }
}

import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.SecureRandom;

public final class SigningKeyGeneration {
    private SigningKeyGeneration() {}

    public static KeyPair ed25519() throws Exception {
        KeyPairGenerator generator = KeyPairGenerator.getInstance("Ed25519");
        generator.initialize(255, SecureRandom.getInstanceStrong());
        return generator.generateKeyPair();
    }
}

[ ] Keystore encrypted at rest.
[ ] Password delivered securely.
[ ] File permissions least privilege.
[ ] Not baked into container image.
[ ] Rotation path tested.
[ ] Startup logs only metadata.

[ ] Workload identity, not static long-lived credential.
[ ] Access by service/environment/tenant scope.
[ ] Audit reads.
[ ] Versioned secrets.
[ ] Rotation and rollback.

[ ] Key policy least privilege.
[ ] Separate encrypt/decrypt/admin rights.
[ ] Key usage audit monitored.
[ ] Key ID stored with ciphertext.
[ ] Rate/latency/failure fallback designed.

[ ] Key generated inside HSM.
[ ] Private key non-exportable.
[ ] Dual control for admin operations.
[ ] Backup/restore ceremony documented.
[ ] Mechanism support tested.
[ ] Performance capacity tested.

[ ] Provider configuration is explicit.
[ ] Mechanism/algorithm availability tested.
[ ] Token login lifecycle safe.
[ ] Key alias/label governance.
[ ] Failover behavior tested.

import javax.crypto.Cipher;
import javax.crypto.KeyGenerator;
import javax.crypto.SecretKey;
import javax.crypto.spec.GCMParameterSpec;
import java.security.SecureRandom;

public final class EnvelopeEncryptionSketch {
    private static final int GCM_TAG_BITS = 128;
    private static final int GCM_IV_BYTES = 12;

    private EnvelopeEncryptionSketch() {}

    public static EncryptedData encrypt(byte[] plaintext, byte[] aad, SecretKey dek) throws Exception {
        byte[] iv = new byte[GCM_IV_BYTES];
        SecureRandom.getInstanceStrong().nextBytes(iv);

        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
        cipher.init(Cipher.ENCRYPT_MODE, dek, new GCMParameterSpec(GCM_TAG_BITS, iv));
        cipher.updateAAD(aad);
        byte[] ciphertext = cipher.doFinal(plaintext);

        return new EncryptedData("AES-256-GCM", iv, ciphertext);
    }

    public static SecretKey generateDek() throws Exception {
        KeyGenerator generator = KeyGenerator.getInstance("AES");
        generator.init(256, SecureRandom.getInstanceStrong());
        return generator.generateKey();
    }

    public record EncryptedData(String algorithm, byte[] iv, byte[] ciphertext) {}
}

write path:
  use current active key version

read path:
  read keyId from envelope
  fetch key if state allows decrypt
  decrypt
  optionally re-encrypt with current key

public byte[] decryptAndMaybeRotate(EncryptedRecord record) {
    KeyRef oldKey = keyRegistry.resolve(record.keyId());

    byte[] plaintext = crypto.decrypt(record, oldKey);

    if (keyRegistry.shouldRotate(record.keyId())) {
        EncryptedRecord rotated = crypto.encrypt(
                plaintext,
                keyRegistry.currentEncryptionKey(record.tenantId())
        );
        repository.updateEncryptedPayload(record.id(), rotated);
    }

    return plaintext;
}

T0: Provider and consumer know old key.
T1: Add new key as secondary verification key.
T2: Start signer using new key ID.
T3: Verifier accepts old+new for replay window + grace period.
T4: Disable old key for signing.
T5: Disable old key for verification.

X-Signature-Key-Id: partner-x-hmac-2026-06
X-Signature-Timestamp: 2026-06-30T08:00:00Z
X-Signature: base64(hmac_sha256(canonical_request))

[ ] Application can encrypt/decrypt only keys it owns.
[ ] Operator can deploy service but not read plaintext key.
[ ] Security admin can create/rotate keys but not decrypt business data alone.
[ ] Auditor can read key metadata and logs but not key material.
[ ] Break-glass access is time-bound, approved, and heavily logged.

keys:
  - keyId: case-field-dek-tenant-42-2026-06
    type: data-encryption-key
    algorithm: AES-256-GCM
    owner: case-platform
    environment: prod
    tenant: tenant-42
    state: active
    createdAt: 2026-06-01T00:00:00Z
    activatedAt: 2026-06-01T01:00:00Z
    cryptoperiodEndsAt: 2026-09-01T00:00:00Z
    wrappingKeyId: reg-platform-kek-prod-2026
    storage: kms-wrapped
    allowedOperations:
      - encrypt
      - decrypt
    rotation:
      model: lazy-reencrypt
      gracePeriodDays: 30
    approval: SEC-KEY-2026-061

[ ] Is the KMS key a KEK, signing key, or direct encryption key?
[ ] Is plaintext DEK returned to application memory?
[ ] How long is DEK cached?
[ ] Are encrypt and decrypt permissions separated?
[ ] Is key usage logged with request context?
[ ] What happens if KMS is unavailable?
[ ] Can old data be decrypted after key rotation?
[ ] How is tenant separation enforced?

name = HsmSlot1
library = /opt/vendor/pkcs11/libpkcs11.so
slotListIndex = 0

import java.security.Provider;
import java.security.Security;

public final class Pkcs11ProviderLoader {
    private Pkcs11ProviderLoader() {}

    public static Provider load(String configPath) throws Exception {
        Provider base = Security.getProvider("SunPKCS11");
        if (base == null) {
            throw new IllegalStateException("SunPKCS11 provider not available");
        }
        Provider configured = base.configure(configPath);
        Security.addProvider(configured);
        return configured;
    }
}

import java.security.KeyStore;
import java.security.Provider;

public final class Pkcs11KeyStoreAccess {
    private Pkcs11KeyStoreAccess() {}

    public static KeyStore loadTokenKeyStore(Provider provider, char[] pin) throws Exception {
        KeyStore keyStore = KeyStore.getInstance("PKCS11", provider);
        // For PKCS#11, InputStream is usually null because store is token-backed.
        keyStore.load(null, pin);
        return keyStore;
    }
}

import java.security.KeyStore;
import java.security.PrivateKey;
import java.security.Provider;
import java.security.Signature;

public final class HsmSigning {
    private HsmSigning() {}

    public static byte[] sign(
            Provider provider,
            KeyStore tokenStore,
            String keyAlias,
            char[] keyPin,
            byte[] canonicalBytes
    ) throws Exception {
        PrivateKey privateKey = (PrivateKey) tokenStore.getKey(keyAlias, keyPin);
        Signature signature = Signature.getInstance("SHA256withRSA", provider);
        signature.initSign(privateKey);
        signature.update(canonicalBytes);
        return signature.sign();
    }
}

import javax.crypto.Cipher;
import javax.crypto.SecretKey;

public final class KeyWrappingSketch {
    private KeyWrappingSketch() {}

    public static byte[] wrapAesKey(SecretKey kek, SecretKey dek) throws Exception {
        Cipher cipher = Cipher.getInstance("AESWrap");
        cipher.init(Cipher.WRAP_MODE, kek);
        return cipher.wrap(dek);
    }

    public static SecretKey unwrapAesKey(SecretKey kek, byte[] wrappedDek) throws Exception {
        Cipher cipher = Cipher.getInstance("AESWrap");
        cipher.init(Cipher.UNWRAP_MODE, kek);
        return (SecretKey) cipher.unwrap(wrappedDek, "AES", Cipher.SECRET_KEY);
    }
}

{
  "wrappedDek": "base64...",
  "wrappingKeyId": "kek-prod-2026",
  "wrappingAlgorithm": "AES-KW-or-KMS-specific",
  "dekAlgorithm": "AES-256-GCM",
  "createdAt": "2026-06-30T08:00:00Z"
}

currentKeys:
  fieldEncryption:
    caseSensitiveData:
      tenant-42: case-field-dek-tenant-42-2026-06
  webhookHmac:
    partner-x: partner-x-hmac-2026-06
  auditSigning:
    prod: audit-signing-prod-2026-q2

# Key Rotation Runbook — <key-id>

## Scope
Data/service/signature affected by this key.

## Preconditions
- New key generated and approved.
- Key metadata registered.
- Consumers can resolve new key ID.
- Monitoring dashboard ready.
- Rollback plan validated.

## Steps
1. Put new key in PreActivation.
2. Deploy trust/public key/material where needed.
3. Activate new key for writes/signing.
4. Keep old key verify/decrypt-only for grace period.
5. Monitor failures and usage of old key.
6. Migrate/re-encrypt if required.
7. Disable old key for new operations.
8. Retire/destroy/archive old key according to retention policy.

## Rollback
Restore current-key pointer to previous key if no compromise exists.
Do not rollback to compromised key.

## Verification
- New writes use new key ID.
- Old data remains readable if policy allows.
- Unauthorized operations are denied.
- Audit events contain old/new key IDs.

[ ] What key was compromised?
[ ] Was it extractable or only misused through API?
[ ] What operations were possible: decrypt, sign, unwrap, issue certs?
[ ] What data/time window is affected?
[ ] Which services had access?
[ ] Are audit logs trustworthy?
[ ] Can old signatures/certificates still be trusted?
[ ] Which keys/data must be rotated, rewrapped, or re-encrypted?
[ ] Which external parties must be notified?

[ ] Prefer provider/KMS/HSM boundaries for high-value keys.
[ ] Avoid storing raw keys in immutable `String`.
[ ] Use `char[]`/`byte[]` where practical and clear after use.
[ ] Disable or protect heap dumps in production.
[ ] Avoid logging key material.
[ ] Limit key lifetime in memory.
[ ] Avoid broad caches of plaintext DEKs.

import java.util.Arrays;

byte[] keyBytes = loadKeyBytes();
try {
    // Use key bytes to construct provider object.
} finally {
    Arrays.fill(keyBytes, (byte) 0);
}

keyDestruction:
  keyId: webhook-hmac-partner-x-2025-12
  destroyedAt: 2026-06-30T08:00:00Z
  method: secret-version-destroyed
  reason: cryptoperiod-ended
  approvedBy:
    - platform-security
    - integration-owner
  evidence:
    - audit-log-event-id: sec-audit-982734

[ ] Are keys backed up?
[ ] Are backups encrypted with a separate key hierarchy?
[ ] Who can restore keys?
[ ] Can destroyed keys reappear from backup?
[ ] Are old backups within legal retention?
[ ] Does disaster recovery preserve key policy and audit logs?
[ ] Can HSM/KMS restore require quorum?

KEK: per environment + data domain
DEK: per tenant + data class + cryptoperiod
AAD: tenantId + caseId + schemaVersion + fieldName

String aad = String.join("|",
        "case-field-encryption-v2",
        "tenant=" + tenantId,
        "case=" + caseId,
        "field=" + fieldName,
        "schema=" + schemaVersion
);

{
  "eventType": "crypto.key.use",
  "timestamp": "2026-06-30T08:00:00Z",
  "keyId": "case-field-dek-tenant-42-2026-06",
  "operation": "decrypt",
  "principal": "service:case-api",
  "environment": "prod",
  "tenantId": "tenant-42",
  "resourceType": "case-field",
  "resourceIdHash": "sha256:...",
  "decision": "allowed",
  "correlationId": "req-abc123"
}

[ ] Decrypt volume spike.
[ ] Key used by unexpected service.
[ ] Old key still used for writes.
[ ] Key used outside expected environment.
[ ] Failed unwrap/decrypt increase.
[ ] Admin disables/deletes key outside change window.
[ ] Signing key used at abnormal rate.

public interface KeyResolver {
    CryptoKey resolveForEncryption(String purpose, String tenantId);
    CryptoKey resolveForDecryption(String keyId, String tenantId);
    CryptoKey resolveForSigning(String purpose);
    CryptoKey resolveForVerification(String keyId);
}

public record CryptoKey(
        String keyId,
        String algorithm,
        KeyState state,
        Object providerHandle
) {}

public enum KeyState {
    PRE_ACTIVATION,
    ACTIVE,
    DECRYPT_ONLY,
    VERIFY_ONLY,
    SUSPENDED,
    COMPROMISED,
    RETIRED,
    DESTROYED
}

CryptoKey key = keyResolver.resolveForEncryption("case-field", tenantId);
if (key.state() != KeyState.ACTIVE) {
    throw new IllegalStateException("Key is not active for encryption: " + key.keyId());
}

import java.util.Map;

public record CryptoEnvelope(
        String scheme,
        String algorithm,
        String keyId,
        int keyVersion,
        String ivBase64,
        String ciphertextBase64,
        String wrappedDekBase64,
        String wrappingKeyId,
        Map<String, String> context
) {}

[ ] Envelope is versioned.
[ ] Algorithm is explicit.
[ ] Key ID is explicit.
[ ] AAD/context is explicit or reproducible.
[ ] Wrapping key metadata is explicit.
[ ] Future migrations can parse old envelope versions.

// Bad: decryptor depends on current global key.
String plaintext = decrypt(ciphertext, config.getCurrentKey());

CryptoEnvelope envelope = parse(record.encryptedPayload());
CryptoKey key = keyResolver.resolveForDecryption(envelope.keyId(), tenantId);
byte[] plaintext = crypto.decrypt(envelope, key);

Invariant 1: No new encryption uses non-active key.
Invariant 2: No decryption uses destroyed/compromised key unless incident-approved.
Invariant 3: Every ciphertext resolves key by stored key ID, not current config.
Invariant 4: Every signing operation has business context and audit event.
Invariant 5: Every key has owner, purpose, state, cryptoperiod, and rotation path.

[ ] Every key has a documented purpose.
[ ] Key reuse across purposes is justified or eliminated.
[ ] Sensitivity tier is assigned.
[ ] Owner and system of record are known.

[ ] Key generated with approved provider/boundary.
[ ] High-value keys are non-exportable where feasible.
[ ] Raw key material is not committed or logged.
[ ] Keystore/KMS/HSM access is least privilege.
[ ] Bootstrap secret is understood.

[ ] Allowed operations are explicit.
[ ] Decrypt/sign operations are more restricted than encrypt/verify.
[ ] Key use emits audit events.
[ ] Key use includes tenant/resource context where relevant.

[ ] Key ID/version stored with protected data.
[ ] Rotation protocol supports overlap.
[ ] Old key state transitions are enforced.
[ ] Rollback does not reactivate compromised key.
[ ] Migration is idempotent.

[ ] Compromise playbook exists by key type.
[ ] Blast radius can be computed from key registry.
[ ] Emergency disable is tested.
[ ] Re-encryption/re-sign/reissue strategy is clear.

[ ] Retired keys are not used for new operations.
[ ] Destroyed keys cannot be restored silently from backup.
[ ] Public verification material is retained as long as evidence requires.
[ ] Destruction evidence is recorded.

[ ] Key registry has at least two AES keys.
[ ] Write path uses current active key.
[ ] Encrypted record stores key ID, algorithm, IV, and ciphertext.
[ ] Read path resolves key by key ID.
[ ] Old key can be marked decrypt-only.
[ ] New writes stop using old key.
[ ] Lazy re-encryption updates old records after read.
[ ] Destroyed key cannot decrypt.
[ ] Tests cover missing key, wrong key, wrong AAD, and old key state.

1. encrypt_with_active_key_stores_key_id
2. decrypt_uses_stored_key_id_not_current_key
3. rotate_new_writes_use_new_key
4. old_records_still_decrypt_when_old_key_decrypt_only
5. destroyed_key_rejects_decryption
6. wrong_aad_fails_authentication
7. lazy_rotation_is_idempotent
8. key_registry_audit_event_emitted

[ ] Evidence content encrypted with unique DEK or scoped DEK.
[ ] DEK wrapped by current KEK.
[ ] Metadata records wrapping key ID and DEK version.
[ ] Audit event signs evidence hash + metadata hash + actor + timestamp.
[ ] Audit signing key is non-exportable if risk tier requires.
[ ] Old audit public keys remain available for verification.
[ ] Key usage logs correlate with case ID without exposing sensitive content.

Key = secret or private material + purpose + owner + policy + state + boundary + audit + rotation + compromise plan.