Application Encryption and Key Management

Pathrule4 Rules • 2 Memories • 1 Skill

Application encryption fails when teams choose an algorithm without a threat model, reuse nonces, mix key and ciphertext storage, omit integrity, lose encryption context, or rotate keys without a way to read old records and resume interrupted migration. This pattern constrains approved primitives, key separation, context, and error behavior; it records envelope and rotation ownership and supplies a staged key-rotation workflow. It complements secrets management by focusing on data encryption and key hierarchy; secret storage governs access to credentials, while this pattern governs how keys protect persisted or transported application data.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

rotate-application-encryption-key

src/

crypto/

Use reviewed authenticated-encryption primitives

Guarantee nonce uniqueness for each key

Envelope encryption creates a rotatable key hierarchy

data/

Bind ciphertext to its immutable context

ops/

keys/

Keep master keys outside application data and general runtime access

Key deletion is a data-deletion and recovery decision

Rules

Use reviewed authenticated-encryption primitives/src/cryptohighstrictSelect an approved library and AEAD construction and prohibit custom cipher, padding, tag, and key-derivation designs.

1	Confidentiality without integrity allows attackers to modify ciphertext and influence decrypted data. Custom composition creates subtle nonce, padding, oracle, and verification failures.
2
3	- Use a maintained platform or cryptographic library and an approved authenticated-encryption mode through its high-level API.
4	- Generate keys with a cryptographically secure source at the required size and keep encryption, signing, wrapping, and derivation purposes separate.
5	- Verify authentication before releasing plaintext or distinguishing detailed failure causes to an untrusted caller.
6	- Version the ciphertext envelope with algorithm and key identity so future readers can select the correct reviewed implementation.
7
8	See /ops/keys for the adjacent decision or procedure that completes this constraint.

Guarantee nonce uniqueness for each key/src/cryptohighstrictGenerate or allocate nonces according to the selected construction and never reuse one with the same encryption key.

1	Nonce reuse can reveal relationships between plaintexts or destroy authentication guarantees even when the key remains secret. A timestamp or per-process counter can collide across restart or scale-out.
2
3	- Follow the chosen library's nonce generation or sequencing contract and use a secure random source where that contract expects random uniqueness.
4	- Store the nonce with ciphertext; it is normally not secret, but it must match the exact encryption operation.
5	- Do not derive nonce solely from time, record count, process ID, or an identifier that can repeat across tenants, retries, restore, or concurrent writers.
6	- Treat any suspected reuse under one key as a security incident requiring scope analysis and key replacement, not only regeneration of future nonces.
7
8	See /src/data for the adjacent decision or procedure that completes this constraint.

Bind ciphertext to its immutable context/src/datahighstrictAuthenticate tenant, record, field, schema, and purpose as associated data so encrypted values cannot be moved into another valid location.

1	Valid ciphertext copied from one row or tenant to another may decrypt successfully unless the encryption operation binds it to the location and purpose the application expects.
2
3	- Construct canonical associated data from stable tenant, entity, field, schema, and purpose identifiers that both encryption and decryption can reproduce.
4	- Do not include mutable display values or values unavailable during recovery in the binding.
5	- Fail closed when context, key identity, tag, or envelope version does not match and preserve only a non-sensitive diagnostic category.
6	- Include context migration in schema change plans because renaming or moving an encrypted field can require controlled re-encryption.
7
8	See /src/crypto for the adjacent decision or procedure that completes this constraint.

Keep master keys outside application data and general runtime access/ops/keyshighstrictUse a key-management boundary for wrapping or cryptographic operations and grant applications the narrowest key actions and context.

1	Storing the master key beside ciphertext defeats separation, while exporting broad key material into every process increases compromise and logging risk.
2
3	- Use a managed or protected key service to generate or wrap data keys and restrict access by application identity, environment, tenant or context where supported.
4	- Keep plaintext data keys in memory only for the bounded operation and clear references promptly; never log them or write them to temporary files.
5	- Separate production, test, backup, and tenant key scopes according to the threat and recovery model.
6	- Audit key use, denied operations, policy changes, disablement, deletion scheduling, and unusual decryption patterns without logging protected plaintext.
7
8	See /src/crypto for the adjacent decision or procedure that completes this constraint.

Memories

Envelope encryption creates a rotatable key hierarchy/src/cryptoEncrypt data with scoped data keys and protect those keys with a versioned wrapping key held by the key-management service.

1	Encrypting every record directly with one master key couples data operations to the key service and makes key scope and rotation coarse. Envelope encryption separates bulk data encryption from key protection.
2
3	- Generate a data key at the appropriate record, file, tenant, batch, or other bounded scope based on blast radius and operational cost.
4	- Store ciphertext, nonce, wrapped data key, wrapping-key identity, associated-data schema, and envelope version together.
5	- Decrypt by authorizing and unwrapping the data key through the key service, then authenticating ciphertext and context locally.
6	- Rotate wrapping keys by rewrapping data keys where policy permits, and rotate data keys by decrypting and re-encrypting the protected data.
7
8	See /ops/keys for the rule or workflow that puts this decision into practice.

Key deletion is a data-deletion and recovery decision/ops/keysAccount for replicas, backups, archives, disaster recovery, legal holds, and rollback before disabling or destroying key material.

1	Destroying a key can make every protected copy permanently unreadable, including backups needed for incident recovery. Retaining it forever can violate deletion policy.
2
3	- Map each key to active ciphertext, replicas, caches, queues, backups, exports, retention, and recovery environments.
4	- Use disablement and a review window before irreversible deletion where the key platform supports it.
5	- Test disaster recovery with restored ciphertext and the authorized key path before changing retention or rotation policy.
6	- Record approvals, owner, scope, date, recovery consequence, and evidence for key disablement and destruction.
7
8	See /src/data for the rule or workflow that puts this decision into practice.

Skills

rotate-application-encryption-key/rootStage new key identity, write new ciphertext, migrate or rewrap old data, verify, resume, and retire safely.

1	---
2	name: rotate-application-encryption-key
3	description: Rotate an application encryption, data, wrapping, or key-management key.
4	---
5
6	# Rotate Application Encryption Key
7
8	Run this procedure when the affected surface changes, before the result is promoted to production. Record evidence for every step instead of accepting a plausible-looking result.
9
10	1. Inventory algorithms, key hierarchy, ciphertext envelope versions, contexts, data locations, backups, readers, writers, permissions, and recovery dependencies.
11	2. Create the replacement key under approved policy and deploy readers that can decrypt both old and new envelopes before changing writers.
12	3. Switch new writes to the replacement identity and migrate old data through idempotent batches with a durable cursor, verification, and bounded load.
13	4. Measure remaining old-key ciphertext, decryption failures, context failures, throughput, and backup implications; rehearse interruption and resume.
14	5. Disable old use only after active and recoverable copies are accounted for, retain rollback through the approved window, and destroy material only through the irreversible-deletion review.
15
16	## Exit criteria
17
18	The change is complete only when the expected behavior, failure behavior, and rollback path have all been exercised with representative data. Preserve the evidence with the change so the next operator can repeat the same checks.

Why this pattern

AI agents often implement custom crypto, use encryption without authentication, reuse a nonce with the same key, or overwrite the only key before existing ciphertext is migrated.

Built for Security and backend teams protecting sensitive fields, files, tokens, backups, and tenant data.

Keeps your assistant from:

Accepting tampered ciphertext as valid plaintext
Reusing a nonce under the same encryption key
Giving application instances direct master-key material unnecessarily
Making old data unreadable during key rotation

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25