Cryptography and Key Management Architecture

The refund request from Chapter 13 crosses two cryptographic boundaries. The API verifies the operator’s token, and the payment provider verifies the webhook. Both checks can be mathematically sound on Monday and fail operationally on Tuesday: an old signing key remains trusted, a new verification key has not reached every consumer, a webhook secret leaks into a log, or a certificate expires before the person named in the alert can replace it.

The algorithm is only one part of the design. A cryptographic control also has a key, an owner, an allowed use, a lifetime, a distribution path, failure behavior, and evidence. Use approved primitives through maintained libraries or managed services, then make every key operable through normal change and compromise.

Remove invention from ordinary application code

A cryptography policy should make the safe path narrower than the set of choices exposed by a general-purpose library. Maintain approved patterns for transport protection, authenticated encryption, signing, password storage, key derivation, and random token generation. Each pattern should name a supported library or service, approved algorithms and parameters, key-storage boundary, output format, migration path, and owner. Applications select a pattern; they do not assemble one from primitive names.

Set these as engineering defaults:

• use approved, maintained libraries and platform cryptography;
• prefer managed key services, and use hardware-backed protection when the exposure or signing consequence warrants it;
• do not invent algorithms, modes, padding, protocols, random number generators, or key exchange;
• do not implement low-level cryptographic primitives unless the team has explicit cryptographic expertise and review;
• separate keys by environment and purpose, and by tenant or product boundary when that separation materially reduces blast radius;
• make keys non-exportable when consumers can ask the service to perform the operation without receiving raw key material;
• record the design and its exception owner when an approved pattern does not fit.

“Approved” is versioned policy, not a permanent adjective. The owner must be able to withdraw a library version, algorithm, key size, certificate profile, or parameter set and find every dependent system. A legacy exception needs a deadline and migration plan, not a quiet place on the allowlist.

Decide what protection the system needs

Begin with the security property and the attacker. “Encrypt this field” is not yet a design.

1. If data needs protection while crossing a network boundary, use maintained platform TLS with certificate validation. Do not add an application cipher merely because the network is untrusted.
2. If a stored value needs confidentiality against loss of disks, snapshots, or storage media, use managed storage encryption. If the threat includes a database reader or an operator with broad storage access, decide whether field-level or application-level encryption creates a genuinely separate key boundary.
3. If a message must reveal tampering, use authenticated encryption when it also needs confidentiality. Otherwise choose an approved MAC or signature according to who must be able to verify and who must be able to produce it.
4. If a service must prove who issued a token or artifact to parties that must not gain signing power, use an approved signature pattern with a protected private key and distributed public verification keys. If all parties may both produce and verify, an approved MAC pattern may fit, but compromise of any holder compromises attribution among them.
5. If the input is a human password, store a salted, costed, password-specific hash. Reversible encryption and fast general-purpose hashes solve the wrong problem.
6. If one key must protect another, use the managed service’s envelope or key wrapping pattern. Keep the key-encryption key in a separate protection boundary from wrapped data-encryption keys.

Claims of non-repudiation need more than a digital signature. Identity proof, private-key custody, authorization, trusted time, certificate status, audit retention, and the legal meaning of the act all contribute. Do not promise that property unless policy defines the whole evidence chain.

Encryption without integrity can permit undetected tampering. Encryption without access control can give every compromised application instance a decryption oracle. Start with the boundary and consequence, then select the approved mechanism.

Follow one signing key through its life

The refund API accepts tokens from the identity service. That service signs; the API verifies. The asymmetry is useful because the API can hold public verification material without gaining the power to mint operator tokens. It also exposes the lifecycle decisions that a diagram can make look deceptively smooth.

Generate. The identity team creates a signing key in the approved managed key service using the approved algorithm and parameters. The service produces the key with a cryptographic random generator; a human does not invent key material or move it through a workstation. Inventory records purpose, environment, owner, algorithm, service identifier, creation time, cryptoperiod, export policy, and intended token profile.

Store and authorize. The private key remains non-exportable when the service supports remote signing. Only the production identity workload may request signatures with it; administrators manage policy through a separate, strongly authenticated path. Verification keys are public, but their distribution still needs integrity: an attacker who can replace the published key can redirect trust to a key they control.

Use. Key policy limits the private key to signing for this purpose. The token profile fixes the algorithm rather than accepting whatever its header requests. The API selects a verification key by a bounded key identifier and then validates the signature, issuer, audience, token type, and time claims. A valid signature does not authorize a refund; it protects claims that the Chapter 12 policy decision consumes.

Rotate. Before the old key stops signing, publish the new verification key and prove that every verifier can obtain and cache it. Then begin signing with the new key while retaining the old public key long enough to verify tokens already issued. Observe issuance and verification by key identifier. Remove old trust only after the maximum token lifetime, clock tolerance, cache behavior, and rollback window have been accounted for. Rotation is a protocol between producers and consumers, not a date attached to one key.

Encrypted data requires a different migration. New writes can move to a new data-encryption key while old ciphertext remains labeled with the key version that can decrypt it. The team must either re-encrypt old data or retain the old decryption capability for its required lifetime, including backups. Deleting an old encryption key on the signing-key schedule can make legitimate data irrecoverable.

Revoke and recover. Suspected compromise ends normal rotation. Stop signing with the key, block its use, bound which tokens or artifacts may have been forged, and distribute the trust change. Short token lifetimes reduce the window but do not replace an emergency path. If verifiers cannot receive revocation quickly, the architecture has made compromise recovery depend on waiting. For encryption keys, recovery may require isolating affected workloads, replacing the key, re-encrypting reachable data, and deciding how to handle backups and replicas that retain old ciphertext.

Retire, archive, or destroy. A private signing key that no longer has a valid use should be destroyed with service evidence. An encryption key may need protected archival while retained data or backups still depend on it. Retention, legal holds, and recovery objectives determine that dependency; habit does not. Destruction includes replicas, exported copies, backups where applicable, and authorization paths—not just deletion of an inventory row.

Audit. Record key creation, policy changes, enabled and disabled versions, sign or decrypt operations at an appropriate granularity, rotation outcomes, failed operations, administrative access, recovery, and destruction. Logs must identify the key and caller without containing raw keys, plaintext, or whole sensitive tokens.

For each key, the lifecycle checklist is therefore concrete:

• purpose, security property, data or action, environment, and owner;
• approved algorithm, parameters, library or service, and key identifier;
• generation source, storage boundary, exportability, backup, and recovery;
• callers allowed to use or administer it, with separation of duties where consequence requires it;
• cryptoperiod and usage limits, normal rotation sequence, overlap, rollback, and proof of consumer readiness;
• compromise trigger, emergency disable path, blast-radius method, and communication path to every relying system;
• retirement, archive, destruction, and evidence requirements;
• logs, alerts, access review, inventory review, and policy owner.

Names should reveal purpose without revealing protected data: product, environment, operation or data class, tenant boundary where needed, and lifecycle owner. A key named prod-key-7 hides the exact dependency an operator needs during an incident.

Certificates bind key operations to names and trust

Certificates add an issuer, subject names, permitted uses, validity interval, chain, and relying-party trust store to a public key. They also add several clocks. A certificate can be within its validity period while the workload is serving the wrong chain, a client trusts the wrong root, the private key is unavailable, or renewal has produced a certificate that deployment never loaded.

For each public TLS or mTLS path:

• inventory the issuer, subject names, allowed key usage, private-key location, serving workloads, trust stores, environment, owner, and renewal method;
• automate issuance, deployment, and renewal, and monitor the certificate actually served rather than only the file or control-plane record;
• alert far enough ahead for the owner to repair issuance, validation, deployment, and rollback failures;
• restrict private-key export and access, and prove replacement after suspected compromise;
• validate hostname or service identity, chain, validity, and intended use; possession of any certificate from a trusted issuer is not sufficient;
• assign ownership for mTLS issuers, workload identity, trust-bundle rollout, overlap, removal, and emergency distrust;
• exercise renewal and issuer or root transition in a production-like path, including clients with stale caches or trust stores.

Revocation checking is not uniformly available or reliable in every protocol and client. The design must state whether it uses revocation information, short-lived certificates, rapid trust-store change, or another bounded replacement strategy. Manual renewal is operational debt for a critical path, but automation without end-to-end observation can still expire in production.

Password hashes are deliberately expensive verifiers

The password database must let the application verify a guess without storing the password or a reversible equivalent. Use the platform’s approved, password-specific scheme—preferably a memory-hard construction such as Argon2id where the platform and policy support it—with a unique random salt and a cost calibrated to the service’s hardware and latency budget. The cost should make offline guesses expensive without making login a cheap denial-of-service primitive.

Store the algorithm, version, salt, parameters, and resulting verifier. When policy changes, a successful login can verify with the old parameters and replace the record using the current ones. Accounts that do not return still need a deliberate migration or reset policy.

A pepper is a separate secret, not a better salt. It can deny an attacker who steals only the database the material needed to test guesses, but it creates a high-consequence shared dependency and a difficult rotation problem. Use it only when a managed or hardware-protected service can keep it outside the password database and the team has designed outage, compromise, rotation, and recovery behavior.

Never log raw passwords, password reset tokens, password hashes, or recovery secrets.

Randomness has separate secrecy and uniqueness jobs

Keys, unguessable session identifiers, reset tokens, salts, nonces, and initialization vectors do not all require the same property. Generate secret or unpredictable values with the platform cryptographic random generator. Generate a salt to prevent equal passwords from sharing the same verifier; it need not be secret. Follow the chosen construction’s exact nonce or IV rule: some require unpredictability, some uniqueness, and some fail catastrophically when a key and nonce pair repeats.

A counter can be an excellent uniqueness mechanism if its state cannot repeat after restart, rollback, cloning, or concurrent allocation. A random nonce can be unsafe at sufficient volume if its size makes collisions plausible. A timestamp, object identifier, ordinary simulation RNG, or improvised mixture of fields is not a substitute for the approved pattern.

Reviewers should ask:

• Where is randomness generated?
• What uniqueness property is required?
• What happens if a nonce repeats?
• Can restart, restore, cloning, concurrency, or multi-region operation repeat state?
• How is exhaustion, collision, or generator failure detected?
• Is the code using the approved API directly?

Make rotation and failure observable

The common failures are system failures with cryptographic consequences.

A hardcoded key turns every source clone, image, package, log, and developer machine into key storage. A static IV or repeated nonce can collapse the confidentiality or integrity guarantee of particular constructions. A fast password hash makes every stolen verifier cheaper to guess. A long-lived signing key and long-lived token preserve an attacker’s value. Encryption with broad decrypt permission leaves the database confidential only until the application boundary is crossed. Logging plaintext before encryption or after decryption bypasses the storage control entirely.

Monitor the signals that reveal these failures: use of old key versions, verification requests for unknown key identifiers, unexpected signing or decryption callers, policy changes, export attempts, certificate renewal and deployment failures, certificates approaching expiry, password records on old parameters, and bursts of cryptographic operation failures. Rate and cardinality matter; logging every operation without a way to find misuse is expensive obscurity.

When a managed key service is unavailable, each operation needs an explicit answer. Verification may continue safely from a bounded cache of authenticated public keys. Signing a new token, decrypting sensitive data, or minting a reset credential may need to stop. A fallback key in application configuration usually converts a visible outage into an invisible security downgrade.

Review the architecture, not the algorithm name

A cryptographic design review should record:

• the data, message, identity, or action being protected, and whether the required property is confidentiality, integrity, authentication, signing, password verification, wrapping, or transport protection;
• the attacker capability and the boundary the control is meant to survive;
• the approved pattern, library or managed service, algorithm and parameters, serialized format, and responsible policy owner;
• every key’s purpose, owner, identifier, generation, storage, exportability, permitted callers, environment and tenant separation, backup, and recovery;
• the rotation protocol for producers and consumers, overlap and rollback, emergency revocation, retained-data dependency, and destruction evidence;
• certificate issuance, identity validation, trust-store ownership, renewal, replacement, and observed serving state where certificates are involved;
• failure behavior for unavailable key services, stale caches, unknown key identifiers, invalid ciphertext or signatures, exhausted randomness, and partial rollout;
• tests, metrics, alerts, audit events, access review, and incident owner;
• migration for old ciphertext, tokens, certificates, hashes, formats, libraries, and algorithm policy.

Reject a design that depends on secrecy of custom algorithm behavior, gives application code raw key material without need, cannot identify every relying party, or calls normal rotation an emergency revocation plan.

Before the refund path is released, the reviewer should be able to trace one token key through the live system:

1. Generate a replacement key under the intended production policy.
2. Publish its verification material and prove every verifier accepts it.
3. Switch signing, observe the new key identifier, and preserve verification of still-valid old tokens.
4. Roll back without losing the ability to distinguish which key signed what.
5. Disable a test key as if compromised and measure how long every verifier takes to reject it.
6. Remove old trust after all valid dependencies have ended, then retain or destroy private material according to policy and capture evidence.

The exercise is complete only when the correlation chain connects token issuance, key-service use, API verification, the authorization decision, and the refund effect without recording the token or key itself. Chapter 15 will follow the webhook secret and other credentials through their storage and delivery paths. Here the narrower test is decisive: cryptography architecture is ready when approved mechanisms constrain application choice and every key can survive both routine change and an urgent loss of trust.