Skip to content

noise_sv2: report why a certificate was rejected, expose the verified one - #2426

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

plebhash wants to merge 5 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

noise_sv2: report why a certificate was rejected, expose the verified one

close #2425

companion stratum-mining/sv2-apps#931

built on top of #2497, which should land first: the first three commits here are that PR's

the handshake now hands applications typed results instead of text to parse (#2425 (comment)):

  • failure: Error::InvalidCertificate { signature_noise_message, reason }, where reason is a CertificateError (UnsupportedVersion, InvalidSignature, NotYetValid { now }, Expired { now }, now being the local clock reading)
  • success: NoiseEngine::certificate() / Transport::certificate() return the verified Certificate (signature_noise_message, server_static_pubkey, authority_pubkey), or None without an authority key (without_pk, responder)
  • SignatureNoiseMessage::verify / verify_with_now, public since noise_sv2: let a Responder present a pre-issued certificate #2497 for whoever loads a pre-issued certificate, return the same Result<(), CertificateError> in place of a bool

the certificate (spec 4.5.3) and the SIGNATURE_NOISE_MESSAGE (spec 4.5.2) are kept apart in code and docs; the signature is checked before the validity window, so a forged certificate or a wrong key is reported as InvalidSignature, never as expired

Certificate has no Display: the spec (4.7) encodes the authority pubkey in base58-check, which noise_sv2 has no encoder for, so the apps format it; SignatureNoiseMessage and CertificateError keep theirs for the codec error text

as logged by the apps:

# success
Noise handshake verified certificate version 0, valid from 1792197676 until 1792201276 (unix time), server static pubkey 9c8nFm6PWDFXaxi5FNv29vXr2iKDNgnqxmx7774cFrZHYuTKJ2G, authority pubkey 9auqWEzQDVyd2oe1JVGFLMLHZtCo2FFqZwtKA5gd9xbuEu7PH72

# failure
Invalid Certificate (expired, local clock reads 1792201300): signature noise message version 0, valid from 1792197676 until 1792201276 (unix time)
Invalid Certificate (not yet valid, local clock reads 1792197000): signature noise message version 0, valid from 1792197676 until 1792201276 (unix time)
Invalid Certificate (signature does not verify for this server static pubkey and authority pubkey): signature noise message version 0, valid from 1792197676 until 1792201276 (unix time)

breaking: noise_sv2 3.0.0, codec_sv2 9.0.0, stratum-core 0.8.0 (each exposes the one below)

heads-up: sv2-ui parses the old error text (stratum-mining/sv2-ui#383)

@plebhash
plebhash force-pushed the 2026-10-16-noise-certificate-ux branch from 5420fba to b03df1f Compare October 17, 2026 01:27
plebhash added a commit to plebhash/sv2-apps that referenced this pull request Oct 17, 2026
…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 b03df1f to 88b7391 Compare October 17, 2026 01:34
plebhash added a commit to plebhash/sv2-apps that referenced this pull request Oct 17, 2026
…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 88b7391 to ba2b862 Compare October 17, 2026 14:36
plebhash added a commit to plebhash/sv2-apps that referenced this pull request Oct 17, 2026
…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 ba2b862 to bd155ec Compare October 17, 2026 14:43
plebhash added a commit to plebhash/sv2-apps that referenced this pull request Oct 17, 2026
…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 2 times, most recently from 7701e54 to 77ec4ba Compare October 17, 2026 14:55
plebhash added a commit to plebhash/sv2-apps that referenced this pull request Oct 17, 2026
…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 77ec4ba to aad73ee Compare November 12, 2026 18:19
plebhash added a commit to plebhash/sv2-apps that referenced this pull request Nov 12, 2026
…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.
Every Responder so far signed a fresh certificate at handshake time over
a static key generated for that one handshake, which puts the authority
private key on the internet-facing host and leaves the certificate
lifetime up to that host.

Responder::from_certificate takes the server's static keypair and a
SIGNATURE_NOISE_MESSAGE (spec 4.5.2) issued for it elsewhere; step_1
sends those bytes verbatim, so the authority private key never has to
be on the server and the validity window is the one the issuer signed.
The existing constructors keep signing at handshake time.

ref stratum-mining#2437
Responder::new and Responder::from_authority_kp need the authority
private key on the internet-facing host, generate a static key that
cannot be certified in advance, and let that host pick the certificate
lifetime. Say so on both constructors, in the crate overview and in the
README, and point servers outside development and testing at
Responder::from_certificate.

Closes stratum-mining#2437
`Responder::from_certificate` accepts a certificate signed elsewhere, but
the type that defines its byte layout, signed digest and clock leeway was
private, so an issuer had to re-implement all three and keep them in
step with the initiator. Re-export `SignatureNoiseMessage`, add the
conversion into its 74 bytes so an issuer can encode the header it
signs, and make the leeway a crate constant.
A failed handshake used to return the `SignatureNoiseMessage` alone,
leaving the operator to compare raw unix timestamps against the clock
to guess what went wrong, and an application nothing to act on short of
parsing a log line. Verification now returns a `CertificateError`
naming the failed check (unsupported version, bad signature, not yet
valid, expired), with the clock reading the time checks were made
against, and `Error::InvalidCertificate` carries it next to the
`SignatureNoiseMessage`.

The signature is checked before the validity window, so a reported
`NotYetValid` or `Expired` always refers to timestamps the authority
signed: a forged certificate, or one that does not verify for this
server static pubkey and authority pubkey, is reported as
`InvalidSignature` whatever timestamps it carries.

`SignatureNoiseMessage::verify` and `verify_with_now` return the same
`Result<(), CertificateError>` in place of a bool, so whoever loads a
pre-issued certificate for `Responder::from_certificate` can run the
initiator's checks ahead of any handshake and learn which one failed,
instead of re-implementing them. The `SignatureNoiseMessage` `Display`
drops the hex signature, which means nothing in a log line (`Debug`
still has it), and codec_sv2 prints the reason ahead of it.
`CertificateError` is re-exported next to `SignatureNoiseMessage`. The
docs around them now tell the `SIGNATURE_NOISE_MESSAGE` apart from the
certificate it forms with the responder's static key, as the spec does.

noise_sv2 3.0.0, codec_sv2 9.0.0 and stratum-core 0.8.0, since each
exposes the one below in its public API.

stratum-mining#2425
A successful handshake discarded the certificate, so an initiator could
not log which certificate it accepted or when it expires.
`NoiseEngine::certificate` and codec_sv2's `Transport::certificate` now
return it as a `Certificate`: the spec's CERTIFICATE, formed by the
`SignatureNoiseMessage` and the server's static public key its
signature covers, together with the authority public key that signature
was verified against.

A certificate needs an authority key, so an initiator built with
`Initiator::without_pk` gets `None`, as does the responder. That also
lets callers tell an authenticated session from an unauthenticated one
without tracking which constructor they used
(stratum-mining#2391).

stratum-mining#2425
@plebhash
plebhash force-pushed the 2026-10-16-noise-certificate-ux branch from aad73ee to 735556d Compare November 13, 2026 19:34
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.

noise_sv2: handshake does not expose why a certificate was rejected, nor the certificate it accepted

1 participant