diff --git a/docs/design/08-component-config.md b/docs/design/08-component-config.md index 8e7e59f15..bb0e1967f 100755 --- a/docs/design/08-component-config.md +++ b/docs/design/08-component-config.md @@ -52,7 +52,6 @@ Environment variables use double-underscore (`__`) as a nesting separator, prefi | `storage.postgres.read_replica_url` | `EXTENDDB__STORAGE__POSTGRES__READ_REPLICA_URL` | | `storage.sqlite.path` | `EXTENDDB__STORAGE__SQLITE__PATH` | | `auth.provider` | `EXTENDDB__AUTH__PROVIDER` | -| `auth.encryption_key` | `EXTENDDB__AUTH__ENCRYPTION_KEY` | | `auth.aws_iam.region` | `EXTENDDB__AUTH__AWS_IAM__REGION` | | `auth.aws_iam.identity_cache_ttl_seconds` | `EXTENDDB__AUTH__AWS_IAM__IDENTITY_CACHE_TTL_SECONDS` | | `auth.aws_iam.policy_cache_ttl_seconds` | `EXTENDDB__AUTH__AWS_IAM__POLICY_CACHE_TTL_SECONDS` | @@ -121,7 +120,8 @@ statement_timeout_secs = 30 [auth] provider = "builtin" # "none" | "builtin" | "aws_iam" | future: "azure_ad" region = "us-east-1" # Region for SigV4 validation -# encryption_key: Set via EXTENDDB__AUTH__ENCRYPTION_KEY env var (never in config files) +# The credential encryption key is not read from this file: `extenddb init` generates it +# and stores it in the catalog `settings` table (see docs/manuals/10-security-model.md). credential_cache_ttl_secs = 300 policy_cache_ttl_secs = 300 timestamp_skew_secs = 300 @@ -429,7 +429,6 @@ Type=simple ExecStart=/usr/local/bin/extenddb --config /etc/extenddb/config.toml Restart=always RestartSec=5 -Environment=EXTENDDB__AUTH__ENCRYPTION_KEY= [Install] WantedBy=multi-user.target @@ -459,11 +458,6 @@ spec: secretKeyRef: name: db-credentials key: connection-string - - name: EXTENDDB__AUTH__ENCRYPTION_KEY - valueFrom: - secretKeyRef: - name: auth-secrets - key: encryption-key livenessProbe: httpGet: path: /health diff --git a/docs/manuals/02-design-guide.md b/docs/manuals/02-design-guide.md index 601d93541..af924870f 100755 --- a/docs/manuals/02-design-guide.md +++ b/docs/manuals/02-design-guide.md @@ -23,7 +23,7 @@ On PostgreSQL, the data database connection string is stored in the catalog's `s | `tables` | DynamoDB table metadata. Composite PK: `(account_id, table_name)`. Stores key schema, attribute definitions, billing mode, stream spec, status, ARN, and TTL config. | | `indexes` | GSI/LSI metadata. FK on `table_id` (UUID) with CASCADE delete. | | `tags` | Resource tags. PK: `(resource_arn, tag_key)`. | -| `settings` | Key-value store for catalog version, data DB URL, and runtime settings. | +| `settings` | Key-value store for catalog version, data DB URL, the AES-256-GCM key that encrypts access key secrets (`encryption_key`), and runtime settings. | | `schema_history` | Migration tracking. Records which SQL files have been applied. | | `admin_users` | Admin credentials (bcrypt-hashed passwords). | | `iam_users` | IAM users scoped to accounts. Optional console password. | @@ -37,7 +37,6 @@ On PostgreSQL, the data database connection string is stored in the catalog's `s | `iam_user_tags` | Tags on IAM users. | | `iam_role_tags` | Tags on IAM roles. | | `permissions_boundaries` | Permissions boundaries for users and roles. | -| `encryption_keys` | AES-256-GCM key used to encrypt access key secrets. | | `stream_shards` | Stream shard metadata (parent shard, sequence range). | | `stream_records` | Stream change records with 24-hour retention. | | `stream_pending` | Stream records that wait for their sequence number. A write stores its record here, and the record moves to `stream_records` once the write has committed. | @@ -127,9 +126,9 @@ Policy conditions support all IAM condition operators: `StringEquals`, `StringNo ### Credential Storage -Access key secrets are encrypted at rest using AES-256-GCM. The encryption key is generated during `extenddb init` and stored in the `encryption_keys` table. Each access key record stores the encrypted secret and a unique nonce. +Access key secrets are encrypted at rest using AES-256-GCM. The encryption key is generated during `extenddb init` and stored in the `settings` table under the key `encryption_key`. Each access key record stores the encrypted secret and a unique nonce. -Credential lookups (access key ID → decrypted secret) go through each server's in-memory credential cache; a miss reads the database. See Credential and Policy Caching in the Security Model. The encryption key used to decrypt secrets is cached at startup because it is immutable after `extenddb init` (see Caching Design below). +Credential lookups (access key ID → decrypted secret) go through each server's in-memory credential cache; a miss reads the database. See Credential and Policy Caching in the Security Model. The server reads the encryption key that decrypts secrets once, at startup. extenddb never changes the key. A change made by hand in the `settings` table takes effect at the next restart. See Credential Storage in the Security Model, and Caching Design below. ## DynamoDB Streams Internals @@ -191,7 +190,7 @@ extenddb caches a small set of operational settings in memory to avoid per-reque | Setting | Mechanism | Refresh | Justification | |---------|-----------|---------|---------------| | `index_propagation_delay_ms` | `AtomicU64` | Background poller every 30s | Write-path hot path; briefly-stale value only affects GSI propagation timing | -| `encryption_key` | `Arc` loaded at startup | Never (immutable after `extenddb init`) | Decryption key for access key secrets; generated once, never changes | +| `encryption_key` | `Arc` loaded at startup | Never: read at startup, so a change made by hand takes a restart | Decryption key for access key secrets. extenddb generates it once and never changes it | | `log_level` / `log_destination` | Tracing filter reload | Background poller every 30s | Observability tuning; stale value only delays log level changes | | `throttling_enabled` | `AtomicBool` | Background poller every 30s | Capacity management toggle; briefly-stale is safe | diff --git a/docs/manuals/10-security-model.md b/docs/manuals/10-security-model.md index c9b6ab412..b69ea2b23 100755 --- a/docs/manuals/10-security-model.md +++ b/docs/manuals/10-security-model.md @@ -19,12 +19,14 @@ This document describes the security architecture of extenddb, including the thr 1. **Client ↔ extenddb**: Untrusted. All input is validated. SigV4 signatures are verified. IAM policies are evaluated. 2. **extenddb ↔ PostgreSQL**: Trusted network. The PostgreSQL connection string contains credentials. Use TLS for the PostgreSQL connection in production (`sslmode=require` in the connection string). 3. **Admin ↔ Management API/Console**: Authenticated via admin credentials or IAM user credentials. CSRF tokens protect the web console. +4. **Catalog database contents**: Credential-equivalent. The AES-256-GCM key that encrypts access key secrets lives in the catalog `settings` table alongside the ciphertext it protects, so read access to the catalog database yields every stored access key secret. On PostgreSQL the same table holds `data_database_connection_string`, the login for the data database; the console, the management API and the `settings` CLI mask it, but a reader of the catalog database gets it in full. Treat catalog read access, and any catalog backup, as equivalent to holding those credentials. See [Credential Storage](#credential-storage). +5. **Server host**: Credential-equivalent as well. `extenddb.toml` holds the catalog connection string, and a running server keeps the encryption key and recently used decrypted secrets in process memory, so read access to the config file, a core dump of the server, or a read of its memory yields the same credentials. ### Out of Scope - **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 an encrypted volume, a managed database with a customer-managed KMS key, or a PostgreSQL distribution that adds transparent data encryption. That protects the key at rest but not from a principal that can query the catalog. ## Authentication @@ -58,7 +60,14 @@ Request bodies are parsed before authentication (the service does the same), so #### Credential Storage - Secret keys encrypted with AES-256-GCM using a per-catalog encryption key -- Encryption key generated during `extenddb init` and stored in the catalog database +- Encryption key generated during `extenddb init` and stored unwrapped in the catalog `settings` table, under the key `encryption_key` +- The encryption key and the ciphertext it protects therefore share one trust domain: anyone who can read the catalog database can decrypt every stored access key secret. Restrict catalog database access to the extenddb service account, and protect catalog backups to the same standard as the credentials themselves. +- The management API and web console redact `encryption_key` from settings responses. The key is readable only with catalog database access: a database client, or `extenddb settings get encryption_key --show-secret` on a host that holds the catalog connection string. +- extenddb has no command to rotate the encryption key, and `extenddb settings set` refuses `encryption_key`. Replacing the key by hand in the catalog `settings` table makes every stored access key secret and session credential unreadable. The server reads the key at startup and keeps it in memory, so a rotation takes these steps in order: + 1. Replace the value of `encryption_key` in the catalog `settings` table with 32 random bytes in standard base64, for example the output of `openssl rand -base64 32`. On MongoDB the key is the `value` field of the `settings` document whose `_id` is `encryption_key`. The server checks only that the key is present. A value of any other form makes every signed request, CreateAccessKey call and AssumeRole call fail. + 2. Restart every server that serves the catalog. From the restart on, each request signed with an old access key or an unexpired session credential fails with `InternalServerError` (HTTP 500). Once step 3 deletes an old key, a request signed with it fails with `UnrecognizedClientException`. + 3. Delete every access key and create a new one. For each client that uses AssumeRole session credentials, call AssumeRole again with `extenddb manage assume-role`. The web console and `extenddb manage` sign in with a password, so they still work for this step. + 4. Give each client its new credentials: an access key ID and secret, or the new session's access key ID, secret and session token. Until then, each of its requests fails. - Console passwords hashed with bcrypt (cost factor 12) - Credentials and the inputs to authorization are cached in each server's memory; see Credential and Policy Caching below @@ -319,7 +328,7 @@ Import/export file paths are validated: - `extenddb init` prints admin credentials once; they are not stored in plaintext - `extenddb manage` reads the password from the `EXTENDDB_PASSWORD` environment variable when `--password` is not given, so the password does not appear in process listings - `extenddb manage` prints a warning on stderr when it gets `--password` -- Access key secrets are shown once on creation and cannot be retrieved afterward +- Access key secrets are shown once on creation, and no API or console page returns them again; a reader of the catalog database can still decrypt them (see [Credential Storage](#credential-storage)) ### Logging @@ -345,7 +354,7 @@ pg_dump extenddb_catalog > catalog_backup.sql pg_dump extenddb > data_backup.sql ``` -Encryption keys are stored in the catalog database. A catalog backup includes the encryption key needed to decrypt access key secrets. +The encryption key is stored in the catalog database, so a catalog dump contains both the key and the encrypted access key secrets. A catalog backup is credential-equivalent: store it encrypted, restrict who can read it, and do not copy it to less-protected environments (for example a developer machine or a shared bucket) to reproduce an issue. ---