LEARN. PRACTICE. GROW.1. Separate the guarantees the service needs
In a fictional fund-position service, encrypting a file prevents someone without the key from directly reading its content. That alone does not answer who may request a read, whether the file belongs to the stated fund or whether an old version is being replayed. Frame those questions before choosing an algorithm. Identify data, consumers, keys, administrators, backups and recovery dependencies. A cryptographic change can affect batch processing, integration and retention without changing the visible interface. Define exception authority and evidence needed to accept the change. The lab uses synthetic data and ephemeral keys to demonstrate primitives; it does not implement user identity, enterprise key management or access approval. Keep those boundaries visible in the APS handover.
2. Bind context without treating it as secret
The exercise uses AES-256-GCM and binds ciphertext to a context containing fund and object. This context is additional authenticated data, AAD: it affects integrity verification but is not encrypted by that mechanism. Reading under a different fund or object fails. In a real application, expected context should come from trusted information and the authorization decision, rather than solely from a client-supplied field. An attacker presenting correct context does not thereby gain read permission. AWS KMS encryption context is likewise nonsecret and can appear in logs; it should not contain credentials or unnecessary personal data. The local example illustrates cryptographic binding but does not execute IAM policies, grants or KMS calls.
3. Do not consume plaintext before authentication
Some APIs return bytes during decryption before confirming the authentication tag. The lab demonstrates this with update and an incorrect tag: plausible bytes can appear before final fails. The exercise’s safe wrapper returns its result only after final verification. Do not write those bytes to a database, send them to a consumer or use them to select an action before authentication. If verification fails, treat content as untrusted and retain appropriate operational evidence without logging secrets. Failure alone does not identify its cause: corruption, wrong context, wrong key or tampering are possible. Diagnosis should confirm versions, identifiers and the data path while retaining the integrity control.
4. Plan rotation, migration and old dependencies
In the lab, new writes move from data-v1 to data-v2. Earlier ciphertext stays unchanged and still requires the old key. Only an explicit read and new encryption creates a record protected by the new data key. This local replacement exercise does not reproduce internal material rotation of an AWS KMS key. When rotating internal material of a symmetric KMS key generated by the service (AWS_KMS), logical identity stays stable and the service retains material needed for earlier reads; rotation does not re-encrypt data or resolve an already compromised data key. For a real migration, inventory active objects, versions, copies and recovery paths. Measure coverage against a defined population and verify representative reads and restores before removing old dependencies. A successful new write does not establish historical recovery.
5. Exercise failures and avoid unsupported erasure claims
The exercise independently changes ciphertext, tag, nonce and context to confirm rejection. It uses random 96-bit nonces and 128-bit tags in a small sample; that does not prove production-scale uniqueness management and usage limits. Nonce reuse under one key requires serious treatment, rather than merely repeating a positive test. Another experiment removes the old key from the map while retaining an independent copy: that copy still reads the record. Deleting an entry does not prove secure erasure from memory, backups or other systems. KMS key deletion has its own rules and can make data unrecoverable; do not use JavaScript-map behavior as proof of those rules. Record which operations were executed and which dependencies remain untested.
The old record keeps its ciphertext after changing the write key; an old-key copy still reads it after removing the map entry.
Common pitfalls
Context treated as authorization; update plaintext treated as authenticated; rotation treated as re-encryption; deleting a reference treated as deleting all copies.
Related topics: Signatures, origin and release policy
Confirm integrity before using data and separately establish authorization, migration and recoverability.
Reference: Node.js cryptographic API · CAS-005 / SecurityX V5; objectives 3.0; launched 2024-12-17