diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/PROTOCOL.md | 30 |
1 files changed, 27 insertions, 3 deletions
diff --git a/docs/PROTOCOL.md b/docs/PROTOCOL.md index e02d2f7..a4e61ec 100644 --- a/docs/PROTOCOL.md +++ b/docs/PROTOCOL.md @@ -370,8 +370,8 @@ resolved rows in a dry run. | Command | Args | Notes | |---|---|---| -| `settings.get` | — | effective org settings (defaults included) | -| `settings.set` | `key`, `value` | known keys: `default_series`, `attachment_dir`, `bank_account`, `invoice_receivable_account`, `invoice_revenue_account` | +| `settings.get` | — | effective org settings (defaults included); secret values replaced by `_set` flags | +| `settings.set` | `key`, `value?` | known keys: `default_series`, `attachment_dir`, `bank_account`, `invoice_receivable_account`, `invoice_revenue_account`, `smtp_host`, `smtp_port`, `smtp_user`, `smtp_from`, `smtp_reply_to`, `smtp_security`, `smtp_password` | `default_series` (1–8 characters, e.g. `A`, `V-`, `A `) is used when `voucher.post` carries no `series` and as the default series for new @@ -385,6 +385,25 @@ characters. Verification ids are the concatenation of series and number (`V-8`), and series are free-form: only an unbroken numbering per series is required. +`smtp_host` (up to 255 characters, no control characters), `smtp_user` (up to +255), `smtp_from` and `smtp_reply_to` (up to 254), `smtp_port` (digits, +1–65535) and `smtp_security` (`starttls`, `tls` or `plain`, default +`starttls` when unset) configure the outgoing mail used when invoices are +sent. + +`smtp_password` is a secret setting. `settings.set` encrypts the value with +AES-256-GCM under the key in the `BOKFD_SECRET_KEY` environment variable (32 +bytes as 64 hex characters or standard base64, padding optional) and stores +only the `enc:v1:<nonce>:<ciphertext>` form; a plaintext password is never +written. `settings.get` never returns the value. When the setting exists it +returns the boolean `smtp_password_set:true` and omits `smtp_password`; +when it is absent it returns `smtp_password_set:false`. Setting `value` to +the empty string deletes the setting. A dry run and the success response +both report `"value":"[redacted]"`, and the audit entry is +`{"key":"smtp_password","value":"[redacted]"}`. Setting or clearing the +password when `BOKFD_SECRET_KEY` is missing or does not decode to 32 bytes +fails with `INTERNAL`. + ### 7.5 Attachments (underlag) | Command | Args | Notes | @@ -690,7 +709,12 @@ beyond the session and calls nothing but public commands. - Passwords: Argon2id (vendored reference implementation). Tokens: 256-bit random, stored hashed, revocable, never logged. Sessions: memory only. - Audit and logs redact secrets: `session.open` records username and outcome, - never the password or token value. + never the password or token value. `settings.set smtp_password` is audited + as `[redacted]`. +- Settings secrets (`smtp_password`) are encrypted at rest with AES-256-GCM + under `BOKFD_SECRET_KEY` (32 bytes, hex or base64, read from the + environment); the key itself is never stored in the database, returned by + any command or written to a log. - Socket and database files are `0600`/`0660`; backups inherit the same discipline. - For data at rest, prefer LUKS on the host. SQLCipher support is a possible |