Envelope encryption with AES-256-GCM, a separate vault that holds credentials, and hash-chained audit logs that auditors can check.
What you will learn
Keep account credentials in a separate vault and let the rest of the system hold only references.
Encrypt with envelope encryption: a data key per record, wrapped by a root key in a key service.
Make an audit logtamper-evident with a hash chain, and know its limits.
What needs protecting
The primer's accounts table stores what the service needs to reach each financial institution, with the credential hashed. That works for checking a credential, but an aggregator has to use the credential, or an access grant, to fetch data. So it must store it in a form it can recover, which means encryption, not hashing. Account numbers and personal details deserve the same care.
The aim is that most of the system never sees these values. The budget, notification and analytics services work with a reference such as vault-ref-3f9a…. Only a small, separate vault service can turn a reference back into the secret.
Envelope encryption
AWS's KMS documentation defines it: "Envelope encryption is the practice of encryptingplaintext data with a data key, and then encrypting the data key under another key."
Generate a fresh data key for each record, a 256-bit AES key.
Encrypt the secret with it using AES-GCM. NISTSP 800-38D recommends 96-bit IVs, and requires that IVs be unique: the chance that the same IV and key ever encrypt two different inputs must be no greater than 2−32. GCM produces an authentication tag (128 bits is the maximum) that detects any change to the ciphertext.
Encrypt the data key under a long-lived root key (AWS calls it a KMS key) and store the encrypted data key next to the ciphertext. Discard the plaintext data key.
To decrypt, ask the key service to decrypt the data key, then decrypt the record.
What this buys, per AWS:
The data key needs no special storage. "You can safely store the encrypted data key alongside the encrypted data."
Re-keying is cheap. To move to a new root key, re-encrypt only the small data keys, not the records.
The root key stays put. KMS keys "never leave the AWS KMS FIPS 140-3 Security Level 3 validated hardware security modules unencrypted". AWS KMS itself uses AES-GCM with 256-bit keys.
Access is controlled at one point. Only identities allowed to call the key service's decrypt operation, for example through an IAM policy, can recover anything.
A data key per record also keeps each key's use far below GCM's limits. With random IVs, SP 800-38D caps a single key at 232 encryptions.
The visual uses your browser's real AES-256-GCM. A local key that cannot be exported stands in for the KMS key. Flip one bit of a ciphertext and decryption fails.
Tamper-evident audit logs
Record every decryption: who, when, which reference. To make silent edits detectable, chain the entries. Each entry stores
hn=SHA-256(hn−1∥timen∥whon∥actionn∥refn)what its symbols mean
where hnwhat its symbols mean is the hash stored with entry nwhat its symbols mean, hn−1what its symbols mean is the hash stored with the entry before it, and ∥ puts the fields of entry n together with that hash before they are hashed. So changing an old entry breaks every hash after it.
There is a catch. Whoever controls the log can rewrite an entry and recompute every later hash, and the result is internally consistent again. Crosby and Wallach make the point directly, in their 2009 paper on tamper-evident logging: "Tamper-evidence requires auditing. If the log is never examined, then tampering cannot be detected." The logger must regularly hand commitments, such as the latest head hash, to auditors who keep them. A rewritten log will no longer match a head an auditor already holds. Their paper also shows how a tree-based log makes those audits cheap.
Compliance names
Specific regimes bring specific duties. PCI DSS, for example, covers payment card data. Which ones apply depends on what you store and where you operate, so treat them as requirements to look up, not as features of the design.
Envelope encryption and a hash-chained audit log
Real AES-256-GCM in your browser: each record gets its own data key and 96-bit IV, and the data key is encrypted under a root key. Here the root key is a local key that cannot be exported, standing in for a KMS key.
A vault service holds envelope-encrypted credentials and records each decryption in a hash-chained audit log; other services keep only references.
Follow one credential. When a user links an account, the vault service gets a fresh data key, encrypts the credential with it, has the key service encrypt the data key under the root key, and stores the ciphertext with the encrypted data key in the vault database; the app database keeps only a reference. To use the credential, the extraction service sends the reference to the vault service, which asks the key service to decrypt the data key, decrypts the credential, and appends who, when and which reference to the audit log. The budget, notification and analytics services never call the vault. The lesson gives no rates for the vault, so each of its parts is drawn as one server plus a spare; the other services are counted as in figure 1.
Budget, notification and analytics services: 3 × App server
Budget, notification and analytics services sends requests to App database (references only)
Extraction service sends requests to App database (references only)
Extraction service sends requests to Vault service
Vault service sends requests to Key service (root key)
Vault service sends requests to Vault database (ciphertext)
Vault service sends requests to Audit log (hash chain)
Key takeaways
An aggregator must use credentials, not just check them, so they are encrypted rather than hashed, and only a small vault service can decrypt them.
AES-GCM with a fresh data key per record detects tampering; the encrypted data key is stored next to the data, and moving to a new root key re-encrypts only the small data keys.
The root key never leaves the key service's hardware unencrypted, and access is controlled at its decrypt call.
Chaining log entries with SHA-256 makes edits detectable, but whoever controls the log can rewrite the chain unless its head is published or checked elsewhere.