Skip to content

log the verified Noise certificate, and handshake failures readably - #931

Open
plebhash wants to merge 14 commits into
stratum-mining:mainfrom
plebhash:2026-10-16-noise-certificate-ux
Open

plebhash wants to merge 14 commits into
stratum-mining:mainfrom
plebhash:2026-10-16-noise-certificate-ux

Conversation

@plebhash

@plebhash plebhash commented Oct 17, 2026 •

Copy link
Copy Markdown
Member

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::verify takes its verdict from noise_sv2, which now says which check failed, instead of pre-checking the window to tell a bad signature apart
  • every Noise initiator logs the certificate it verified, formatting it here: both pubkeys in base58-check, the encoding spec 4.7 defines for the authority pubkey
  • jd-client, pool and translator logged handshake failures with Debug (a struct dump with the 64-byte signature); they now use Display, which names the failed check

success:

INFO stratum_apps::network_helpers::noise_stream: Noise handshake verified certificate version 0, valid from 1792197676 until 1792201276 (unix time), server static pubkey 9c8nFm6PWDFXaxi5FNv29vXr2iKDNgnqxmx7774cFrZHYuTKJ2G, authority pubkey 9auqWEzQDVyd2oe1JVGFLMLHZtCo2FFqZwtKA5gd9xbuEu7PH72

failure, before:

WARN jd_client_sv2::jdc_runtime: Attempt 1/3 failed for pool=...:3333, jds=...:3334: JDCError { kind: NetworkHelpersError(CodecError(NoiseSv2Error(InvalidCertificate(SignatureNoiseMessage { version: 0, valid_from: 1792197676, not_valid_after: 1792201276, signature: [110, 144, 222, ...] })))), action: Fallback, _owner: PhantomData<...> }

failure, after:

WARN jd_client_sv2::jdc_runtime: Attempt 1/3 failed for pool=...:3333, jds=...:3334: Network error: Invalid Certificate (expired, local clock reads 1792201300): signature noise message version 0, valid from 1792197676 until 1792201276 (unix time)

no version bump: stratum-apps is already at 0.10.0 over the published 0.9.0

TODO

  • temporary commit pointing stratum-core to the companion branch
  • drop it and update stratum-core once the stratum PR is merged

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
plebhash force-pushed the 2026-10-16-noise-certificate-ux branch from 7d05e18 to b7c114c Compare November 12, 2026 18:30
@plebhash
plebhash marked this pull request as ready for review November 12, 2026 18:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant