bitcoinafterlife/bal-server
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

docs(pusher): document v2 onion delegation and legacy ping defaults

Browse Source 
- Correct WELIST_ALLOW_LEGACY_PING: legacy pings are accepted by default,
  the flag only disables them.
- Describe onion delegation: v2-only inclusion, service-side host
  normalization, strict expiry check, deployment order and rollback.
- Warn that disabled delegation rejects onion pings when SSL_KEY_PATH is
  the dedicated ping key.
- Document certificate lifetime and revocation limits, offline master
  key requirements, helper --days bounds, and a delegation verification
  checklist.
- Fix the bal-pusher.sh comment about the service-side defaults.
This commit is contained in:
svatantrya
2026-11-09 00:15:00 -04:00
parent 4af1ca8220
commit 78e4f72255
4 changed files with 127 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
docs/05_api_reference.md
View File

@@ -169,14 +169,19 @@ scheme is selected with `WELIST_PING_SIG_VERSION`:
or from a v3 `.onion` address. No HTTP callback to `/.pub_key.pem` is made.
For `.onion` URLs the pusher includes a `delegation` object when
`WELIST_PING_DELEGATION_FILE` is set. The onion identity key signs that
certificate offline; `SSL_KEY_PATH` is then the dedicated ping key, and the
service verifies the certificate before checking the ping signature. The
pusher validates the certificate at startup: `onion` must match the configured
host, `valid_until` must be in the future, and `key` must match `SSL_KEY_PATH`.
If the file is missing or malformed, or any check fails, the pusher logs a
warning and sends no `delegation` object. It then signs with `SSL_KEY_PATH`
directly, which works only when that key is the onion identity key.
`WELIST_PING_DELEGATION_FILE` is set and `WELIST_PING_SIG_VERSION=2`. The onion
identity key signs that certificate offline; `SSL_KEY_PATH` is then the
dedicated ping key, and the service verifies the certificate before checking
the ping signature. The service normalizes `onion` (lowercase, trailing dot
removed) before comparing it with the ping host; the pusher's startup check uses
the exact configured host, so issue lowercase certificates.
The pusher validates the certificate at startup: `onion` must match the
configured host, `valid_until` must be in the future, and `key` must match
`SSL_KEY_PATH`. If the file is missing or malformed, or any check fails, the
pusher logs a warning and sends no `delegation` object. It then signs with
`SSL_KEY_PATH` directly; in the recommended setup that key is the dedicated
ping key, so the service rejects the pings until delegation is restored.
The `url` is trimmed of surrounding whitespace and trailing slashes, and the
`chain` is lowercase, matching the service-side canonicalization.