docs: state the catalog trust boundary for the credential encryption key - #228
Open
LeeroyHannigan wants to merge 1 commit into
Open
docs: state the catalog trust boundary for the credential encryption key#228LeeroyHannigan wants to merge 1 commit into
LeeroyHannigan wants to merge 1 commit into
Conversation
The security model noted that the encryption key lives in the catalog database and that a catalog backup includes it, but left the consequence for the reader to infer and did not mention that no rotation path exists. - Add the catalog database contents as an explicit trust boundary: the key and the ciphertext it protects share one trust domain, so catalog read access yields every stored access key secret. - Scope that boundary to direct database access — the management API and console redact `encryption_key` from settings responses. - Record that there is no key rotation path; re-keying means re-creating the affected access keys. - Replace the vague "use a KMS-backed encryption layer at the PostgreSQL level" guidance with what extenddb does and does not do, and what below-extenddb protection can and cannot achieve. - State that a catalog dump is credential-equivalent and should not be copied to less-protected environments.
LeeroyHannigan
requested review from
amrith,
c33howard,
jcshepherd,
pdf-amzn and
yesyayen
as code owners
July 27, 2026 19:17
jcshepherd
reviewed
Aug 5, 2026
| - **PostgreSQL security**: extenddb relies on PostgreSQL access controls and network security. Securing the PostgreSQL instance (firewall rules, TLS, authentication) is the operator's responsibility. | ||
| - **Operating system security**: File permissions on `extenddb.toml`, TLS keys, and the PID file are the operator's responsibility. | ||
| - **Key management**: Access key secrets are encrypted with a locally generated AES key stored in the catalog database. For HSM-grade key management, use a KMS-backed encryption layer at the PostgreSQL level. | ||
| - **Key management**: extenddb generates the credential encryption key locally and stores it unwrapped in the catalog database. It does not wrap the key with an external KMS or HSM, derive it from an operator passphrase, or rotate it. Deployments that require any of those must add protection below extenddb — for example PostgreSQL transparent data encryption, an encrypted volume, or a managed database with a customer-managed KMS key — which protects the key at rest but not from a principal that can query the catalog. |
Collaborator
There was a problem hiding this comment.
Maybe something for the backlog here: pluggable support for generating/managing credential encryption keys. Seems like this would be important for a lot of users.
jcshepherd
reviewed
Aug 5, 2026
jcshepherd
left a comment
jcshepherd
left a comment
Collaborator
There was a problem hiding this comment.
Thanks for documenting this. I think it'd be good to cut an issue to support other, more secure, mechanisms for handling the credential encryption key like the ones you mentioned: HSM, passcodes, etc. Status quo is probably not sufficient for many production uses.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
State the catalog trust boundary for the credential encryption key in the security model. The doc noted that the key lives in the catalog database and that a catalog backup includes it, but left the consequence to inference and did not mention that no rotation path exists.
encryption_keyfrom settings responses.Why
The security model understated a real trust boundary. Making it explicit lets operators
protect the catalog database and its backups to the standard the credentials require,
and sets up a follow-up RFC on key wrapping / rotation.
Closes #
Testing done
Documentation only, no code change:
bootstrapper.rs:261(INSERT INTO settings ... VALUES ('encryption_key', $1)).encryption_keyredacted from settings API/console responses:settings.rs:19-25(REDACTED_KEYS).crates/for rotation/re-key logic returns nothing.Checklist
cargo test --workspace)cargo fmt --check)cargo clippy -- -W clippy::pedantic)Storagetrait, auth model, on-diskformat, or public CLI surface, an RFC has been accepted or is linked
below. Otherwise, an ADR captures the decision (link below).
ADR / RFC: n/a — documentation only, no behavior change.
Breaking changes
None.
By submitting this pull request, I confirm that my contribution is made under
the terms of the Apache License 2.0 and I agree to the Developer Certificate of
Origin (DCO). See CONTRIBUTING.md for details.