Repository navigation
Conversation
This was referenced Oct 17, 2026
plebhash
force-pushed
the
2026-10-16-noise-certificate-ux
branch
5 times, most recently
from
October 17, 2026 14:56
ce3bb6f to
7d05e18
Compare
No content change. The module is split into submodules next, and git records a split as a rename only when the file that keeps most of the content leaves its path; with the root at key_utils.rs the split can move it into key_utils/keys.rs and put the index back at mod.rs.
One file held the key encodings, the Schnorr signature service and the error type. Give each its own module, re-exported from key_utils so every existing path still resolves, and drop the no_std attribute and alloc import that had no effect inside a module of a std crate.
A server that keeps its authority private key off the host needs a certificate issued for its static key somewhere else, and a way to check at startup that the certificate it was handed matches that key and that authority. Certificate is the 74-byte SIGNATURE_NOISE_MESSAGE (Sv2 spec 4.5.2) as one base58check string, the encoding the keys already use. Its layout, the digest it signs over the version, the validity window and the x-only static key (spec 4.5.3), and the clock tolerance Sv2 initiators apply all come from noise_sv2's SignatureNoiseMessage, which stratum-core re-exports, so the apps keep no copy of the format and the module needs the `core` feature. It exposes the window so operators can log when it expires and reports each check a certificate can fail with its own error. A certificate issued outside this code base is checked as a test vector. ref stratum-mining/stratum#2437
Every server that accepts Noise connections builds its Responder from the authority keypair and a validity period, so it has to hold the authority private key and sign a certificate per handshake. ResponderCredentials names where a server's static key and certificate come from instead, one of: - a static private key and a certificate issued for it elsewhere, loaded once with the configuration; - the path of a TOML file holding the same, read before every handshake, so replacing the file (or the symlink it is) rotates the key without a restart and without touching open connections. Signing per handshake stays available on noise_sv2's Responder for library users, but no server built on stratum-apps does it: the authority secret key never belongs on a server, so the fields of that setup (authority_secret_key, cert_validity_sec) are refused with a reason instead of being ignored. It deserializes from flat fields, so application configs embed it with #[serde(flatten)] and the same fields work from the environment. Inline fields win over the file. A pre-issued certificate is checked for version and validity window before every handshake, and against the authority public key when one is configured, so a bad rotation is reported with a reason instead of as rejected handshakes. network_helpers::Error gains a variant for those refusals, which breaks exhaustive matches on it. ref stratum-mining/stratum#2437
The three servers read authority_public_key, authority_secret_key and cert_validity_sec and passed them to every accepted connection through accept_noise_connection, so the authority private key had to sit in each server's configuration. accept_noise_connection now takes a ResponderCredentials, and the servers' configs flatten one in place of those fields: a server sets static_private_key and certificate, or active_static_key pointing at a file that is re-read per handshake; authority_public_key stays as the optional key to check the certificate against, and the other two are refused with a reason. JDS embedded in a Pool inherits the Pool's credentials as it inherited its keys. Each downstream server checks its credentials once before binding, so a misconfiguration fails startup with a reason. The programmatic constructors take the credentials directly: Pool's AuthorityConfig and JDC's PoolConfig held nothing else and are gone, and ConnectionConfig no longer carries a certificate validity. The test harness, including the sniffer that stands in for a server, presents a throwaway static key with a certificate from the shared test authority valid until the year 2106, so the harness no longer holds that authority's secret key. ref stratum-mining/stratum#2437
A server configured with a pre-issued certificate needs someone to issue it, on the machine that holds the authority secret key rather than on the server. sv2-certificate does that in three commands: keygen for an authority or static keypair, issue to certify a static key (generated on the spot unless given) over a chosen validity window, and inspect to read a certificate's window back. issue prints the result and, on request, writes it as the TOML file a server's active_static_key points at and/or as a .env file of <PREFIX>__* variables for the config loader. Those files hold a private key, so they are created owner-readable only and never overwrite an existing file: a rotation writes a new file and moves a symlink. ref stratum-mining/stratum#2437
Every config example and env file carried the shared test authority secret key next to the server's listen address, and the servers no longer accept it. Give them instead a throwaway static key and the certificate the development authority issued for it, valid until the year 2106, the end of the certificate's 32-bit clock, so they still start out of the box, and say where the keys are set that this proves nothing to anyone: that authority's secret key is public. Name the file alternative re-read per handshake and the tool that issues real certificates, and give the Pool and JDC READMEs a "Server keys" section with the rotation workflow. ref stratum-mining/stratum#2437
…ssued-cert Temporary commit so CI builds against stratum-mining/stratum#2497. Drop it and update stratum-core to stratum main once that PR is merged.
`Certificate::verify` wrapped `SignatureNoiseMessage::verify_with_now` while that answered with a bool, so it checked the version and the validity window itself first and called whatever failed after that a bad signature. noise_sv2 now says which check failed: `verify` runs the checks through it, in the order the initiator applies them, and maps the reason onto the existing `Error` variants. `check_validity` keeps its own window check, since without an authority key noise_sv2 checks only the version. stratum-mining/stratum#2425
When an initiator verifies the upstream's certificate against its configured authority key, log the certificate: its version, validity window, server static pubkey and authority pubkey, the latter in the same encoding operators use to configure it. An operator can then see the validity window an upstream's certificate carries, and when it expires, before handshakes start failing. Connections without an authority key have no verified certificate and log none. A rejected certificate already reaches the logs through the codec error, which now names the check it failed. stratum-mining/stratum#2425
jd-client logged a failed handshake with the pool, the JDS or the template provider with `Debug`, so a rejected certificate showed up as a nested struct dump carrying the 64-byte signature, instead of the readable reason the codec error's `Display` gives (which check failed, and the clock reading for time checks). Log those failures with `Display`. The upstream retry warning now prints the error kind alone: its action only decides whether to retry, and a shutdown has already returned by then. The responder-side handshake log is untouched: a responder never verifies a certificate. stratum-mining/stratum#2425
The pool logged a failed handshake with the template provider with `Debug`, so a rejected certificate showed up as a nested struct dump carrying the 64-byte signature, instead of the readable reason the codec error's `Display` gives (which check failed, and the clock reading for time checks). Log it with `Display`. The responder-side handshake log is untouched: a responder never verifies a certificate. stratum-mining/stratum#2425
Besides its readable handshake error line, the translator followed every failed upstream attempt with a `Debug` dump of the error, so a rejected certificate also showed up as a nested struct dump carrying the 64-byte signature. The retry warning now prints the error kind with `Display`, and the kind's `Display` renders its network error with `Display` too, which reaches the codec error's readable reason (which check failed, and the clock reading for time checks). The warning drops the error's action: it only decides whether to retry, and a shutdown has already returned by then. stratum-mining/stratum#2425
…ificate-ux Temporary commit so CI builds against stratum-mining/stratum#2426. Drop it and update stratum-core to stratum main once that PR is merged.
plebhash
force-pushed
the
2026-10-16-noise-certificate-ux
branch
from
November 12, 2026 18:30
7d05e18 to
b7c114c
Compare
plebhash
marked this pull request as ready for review
November 12, 2026 18:40
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
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.
companion stratum-mining/stratum#2426
ref stratum-mining/stratum#2425
built on top of #993, which should land first: its commits come first here
key_utils::Certificate::verifytakes its verdict fromnoise_sv2, which now says which check failed, instead of pre-checking the window to tell a bad signature apartDebug(a struct dump with the 64-byte signature); they now useDisplay, which names the failed checksuccess:
failure, before:
failure, after:
no version bump:
stratum-appsis already at 0.10.0 over the published 0.9.0TODO
stratum-coreto the companion branchstratum-coreonce the stratum PR is merged