Skip to content

noise_sv2: let a Responder present a pre-issued certificate - #2497

Open
plebhash wants to merge 9 commits into
stratum-mining:mainfrom
plebhash:2026-11-09-noise-preissued-cert
Open

plebhash wants to merge 9 commits into
stratum-mining:mainfrom
plebhash:2026-11-09-noise-preissued-cert

Conversation

@plebhash

@plebhash plebhash commented Nov 9, 2026 •

Copy link
Copy Markdown
Member

closes #2437
companion stratum-mining/sv2-apps#993

Responder::from_certificate(static_keypair, certificate) (and from_certificate_with_rng) builds a responder from the server's static keypair and a SIGNATURE_NOISE_MESSAGE (spec 4.5.2) issued for it elsewhere. step_1 sends it verbatim, so the authority private key never has to be on the internet-facing host and the validity window is the one the issuer signed. Internally the responder always holds a static key and a certificate over it: Responder::new now signs its certificate when the responder is built instead of in step_1, so the responder never stores the authority keypair, and step_1 needs neither the time nor a random number generator. step_1_with_now_rng is therefore removed (also on codec_sv2::Handshake<Responder>), new_with_rng becomes new_with_now_rng, and the validity window starts at construction. from_authority_kp and from_authority_kp_with_rng are removed: a caller with raw bytes builds the Keypair and calls new. Responder::step_1 and Initiator::step_2/step_2_with_now now take self: Box<Self>, so a step cannot be taken twice and the handshake secrets are erased on drop whether it succeeds or fails. The rustdoc of new carries a # Security section spelling out what signing on the server implies (authority key on the host, static key that cannot be certified in advance, lifetime chosen by the host, no revocation), and the crate overview and README get a short "Authority key custody" note pointing at from_certificate.

SignatureNoiseMessage is now re-exported, so an issuer builds the certificate with the crate's own format instead of re-implementing it: sign and sign_with_rng issue the message from a validity window, the static key and the authority keypair, the From conversions give its 74 bytes and back, verify borrows it, and CERTIFICATE_TIME_LEEWAY is public so a load-time check applies the same clock tolerance as the initiator. The responder signs through the same sign_with_rng. from_certificate takes the certificate as that type and does not verify it; the initiator rejects a certificate that does not match the static key, the authority key or the current time, and the test covers the expired case. The load-time check lives in the sv2-apps companion. As agreed in review, verify and verify_with_now take the authority key outright instead of an Option, so the API no longer offers unauthenticated verification as a state; an Initiator without a pinned key still checks only the certificate version, as before, and a test pins that down. #2426 is outdated and will be rebased on top of this.

The same reasoning applies to the Initiator, so it now always pins the responder's authority public key: new and new_with_rng take it outright and without_pk is gone. Chapter 4 of the spec makes the handshake optional on a local network and mandatory for remote access, and the handshake it defines is "Noise_NX augmented by server authentication" whose third step is the initiator validating the server's certificate (4.5, 4.5.3, 4.7); there is no encrypted-but-unauthenticated state in it, and the one this crate offered was an SRI invention. The fuzz target loses its anonymous peer mode.

Breaking, noise_sv2 2.1.0 → 3.0.0, for the Initiator constructors and for verify/verify_with_now: SignatureNoiseMessage was not nameable in 2.1.0, but a value of it comes out of Error::InvalidCertificate, so its changed method signatures count under SemVer even though cargo semver-checks cannot see them (rustdoc JSON omits unnameable items). codec_sv2 carries noise_sv2::Error in its own Error and stratum-core re-exports the crate, so they move to 9.0.0 and 0.8.0 with their requirements (CONTRIBUTING.md factor 3). The sv2-apps side is stratum-mining/sv2-apps#993: both UX approaches from the issue (inline/environment and active_static_key file), plus the sv2-certificate issuing tool.

plebhash added a commit to plebhash/sv2-apps that referenced this pull request Nov 9, 2026
…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.
plebhash added a commit to plebhash/sv2-apps that referenced this pull request Nov 9, 2026
…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.
plebhash added a commit to plebhash/sv2-apps that referenced this pull request Nov 9, 2026
…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.
@plebhash
plebhash requested a review from bit-aloo November 10, 2026 16:45
@Jolah1

Jolah1 commented Nov 11, 2026

Copy link
Copy Markdown
Contributor

tACK 0c0dc0b

Ran the noise_sv2 tests and the no_std build locally. Also tried from_certificate with odd and even parity static/authority keys, and with certs for the wrong static key, wrong authority, expired and not yet valid. A pinned
initiator accepts the good ones and rejects the rest. Old constructors behave the same.

Comment thread sv2/noise-sv2/src/responder.rs Resolved
Comment thread sv2/noise-sv2/src/test.rs Resolved
plebhash added a commit to plebhash/sv2-apps that referenced this pull request Nov 12, 2026
…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.
plebhash added a commit to plebhash/sv2-apps that referenced this pull request Nov 12, 2026
…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.
@plebhash
plebhash force-pushed the 2026-11-09-noise-preissued-cert branch from 98f9834 to a6214a5 Compare November 12, 2026 14:10
plebhash added a commit to plebhash/sv2-apps that referenced this pull request Nov 12, 2026
…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.

@bit-aloo bit-aloo left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With this new authentication way, a responder can authenticate in three ways, at least as supported by noise_sv2: unauthenticated, using an authority private key, or using a certificate and static key.

Our existing APIs were mostly built around the first two, which is why we have optional public keys in a few places. Now that we're extending the authentication options, I think we should revisit these APIs and introduce proper authentication states, each with its own set of API guarantees.

Let me know what you think!

@bit-aloo
bit-aloo force-pushed the 2026-11-09-noise-preissued-cert branch from 6fad570 to a6214a5 Compare November 13, 2026 12:29
@bit-aloo

Copy link
Copy Markdown
Member

To show what I meant above, I had my agent put together a rough implementation: bit-aloo@4630a8f. It’s not meant to be final, just a sketch of how we could approach this.

Comment thread sv2/noise-sv2/src/signature_message.rs Resolved
@plebhash
plebhash force-pushed the 2026-11-09-noise-preissued-cert branch from a6214a5 to 4334eaa Compare November 13, 2026 19:37
plebhash added a commit to plebhash/sv2-apps that referenced this pull request Nov 13, 2026
…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.

@bit-aloo bit-aloo left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Few suggestions. Looking pretty solid

Comment thread sv2/noise-sv2/src/responder.rs Resolved
Comment thread sv2/noise-sv2/src/responder.rs Resolved
Comment thread sv2/noise-sv2/src/responder.rs Resolved
Comment thread sv2/noise-sv2/src/signature_message.rs Resolved
Comment thread sv2/noise-sv2/src/signature_message.rs Resolved
Comment thread sv2/noise-sv2/src/signature_message.rs Resolved
Comment thread sv2/noise-sv2/src/signature_message.rs Resolved
Comment thread sv2/noise-sv2/src/signature_message.rs Resolved
Comment thread sv2/noise-sv2/src/signature_message.rs Resolved
Comment thread sv2/noise-sv2/src/responder.rs Resolved
@plebhash
plebhash force-pushed the 2026-11-09-noise-preissued-cert branch from 4334eaa to 6d37cda Compare November 14, 2026 14:34
plebhash added a commit to plebhash/sv2-apps that referenced this pull request Nov 14, 2026
…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.

@bit-aloo bit-aloo left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Few more suggestions and ask's 😅

Comment thread sv2/noise-sv2/src/responder.rs Outdated
/// for another handshake.
#[cfg(feature = "std")]
pub fn step_1(
&mut self,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lets consume the responder here. Considering, after the usage of this API, that state of responder is not really useful. Same goes for the rng variant.

Suggested change
&mut self,
self,

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

clanker is pushing back:

Consuming makes sense, but a plain self has a catch: the constructors return Box<Responder>, so self moves the struct out of the box onto the stack, and the heap allocation is freed without being wiped. Drop only erases the moved copy. It would have to be self: Box<Self> to keep the secrets in one place.

Two other things it touches:

  • the tests that check the erasure inspect the responder after step_1, which is no longer possible once it is consumed.
  • Initiator::step_2 has the same shape, so it would need the same treatment.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What I want us to do here, is to consume the responder, instead of passing a mutable reference to it. Even the points the clanker mentioned, we can just amend them.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

Comment thread sv2/noise-sv2/src/responder.rs Outdated
/// and a certificate issued where the authority private key is kept: see
/// [`Self::from_certificate`].
#[cfg(feature = "std")]
pub fn new(a: Keypair, cert_validity: u32) -> Box<Self> {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These names are so bad. sometimes become difficult to understand.

Suggested change
pub fn new(a: Keypair, cert_validity: u32) -> Box<Self> {
pub fn new(authority_key: Keypair, cert_validity: u32) -> Box<Self> {

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

Comment thread sv2/noise-sv2/src/responder.rs Outdated
Comment on lines 282 to 301

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know, why we even have these APIs, like its equivalent to new and new_with_rng. Lets remove these.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

Comment thread sv2/noise-sv2/src/responder.rs Outdated
@@ -174,6 +198,59 @@ impl Responder {
a: Keypair,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
a: Keypair,
authority_key: Keypair,

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

Comment thread sv2/noise-sv2/src/responder.rs Outdated
Comment on lines 87 to 103
certificate: CertificateSource,
}

// The `SIGNATURE_NOISE_MESSAGE` (spec 4.5.2) a [`Responder`] sends is either signed on the spot
// or supplied by the caller, already issued.
enum CertificateSource {
// Sign a fresh certificate over the static key at handshake time, valid from the handshake's
// `now` for `cert_validity` seconds. Needs the authority private key on the host; see the
// security note on [`Responder::new`].
SignAtHandshake {
authority: Keypair,
cert_validity: u32,
},
// Send this certificate verbatim; it was issued where the authority private key is kept. See
// [`Responder::from_certificate`].
PreIssued(SignatureNoiseMessage),
}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can drop CertificateSource. Even on the authority-key path we end up with the same two things as from_certificate: a static key and a certificate over it. So the constructor can sign the certificate right away, and the Responder never needs to keep the authority keypair in memory.

The only behavioural change is that the certificate is signed when the Responder is constructed instead of in step_1. We create the Responder when the connection opens and keep it until the cipher states exist, so the validity window would start at construction, which is when the connection actually begins.

A side benefit: step_1 would no longer need now or an RNG, so step_1_with_now_rng can go away.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

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` and shape it
for that use: `sign` and `sign_with_rng` issue the message from a
validity window, the static key and the authority keypair instead of
filling in a byte buffer, `verify` borrows it, the conversion into its
74 bytes is added, and the leeway is a crate constant. `from_certificate`
takes the certificate as that type rather than as raw bytes, and the
responder signs through the same `sign_with_rng`.
`SignatureNoiseMessage::verify` and `verify_with_now` took the authority
public key as an `Option` and, without one, accepted any message of the
supported version, so the certificate API offered unauthenticated
verification as a state. Take the key outright. An `Initiator` built
without a pinned key still skips the verification itself and checks
only the certificate version, so its API and behaviour are unchanged;
two tests now pin that down.

BREAKING CHANGE: both methods lose the `Option`. `SignatureNoiseMessage`
was not re-exported in 2.1.0, but a value of it is reachable through
`Error::InvalidCertificate`, so the methods could already be called;
`cargo semver-checks` cannot see the change because rustdoc omits
unnameable items. noise_sv2 goes to 3.0.0. `codec_sv2` carries
`noise_sv2::Error` in its own `Error` and `stratum-core` re-exports the
crate, so they move to 9.0.0 and 0.8.0 with their requirements.
`Initiator::new` took the responder authority public key as an `Option`
and `without_pk` built an initiator with none. Such an initiator
completed the handshake with any responder whose certificate carried
the supported version, yielding an encrypted but unauthenticated
session. The Sv2 spec defines no such state: the handshake is "Noise_NX
augmented by server authentication", its third step is the initiator
validating the server's certificate, and the authority public key is a
precondition of using the scheme (04-Protocol-Security.md 4.5, 4.5.3,
4.7). The one unauthenticated option the spec leaves is not running the
handshake at all, on a local network.

Make the key mandatory: `new` and `new_with_rng` take it outright,
`without_pk` and `without_pk_with_rng` are gone, and `step_2` always
verifies the certificate. The fuzz target drops its anonymous peer
mode.

BREAKING CHANGE: `Initiator::new` and `new_with_rng` take
`XOnlyPublicKey` instead of `Option<XOnlyPublicKey>`;
`Initiator::without_pk` and `without_pk_with_rng` are removed. Covered
by the 3.0.0 bump of noise_sv2 in the previous commit.
`from_authority_kp` and `from_authority_kp_with_rng` built a keypair from
raw bytes and called `new`. A caller holding raw bytes can build the
`Keypair` itself, and a public key passed only to be compared with the one
derived from the private key is not worth a constructor.

The callers were tests, a bench and an example in codec_sv2, which now
build the keypair and call `Responder::new`. That needs secp256k1 as a
dev-dependency there.

`Error::InvalidRawPrivateKey` is no longer returned by anything and is kept
so the error enum does not change.

BREAKING CHANGE: `Responder::from_authority_kp` and
`Responder::from_authority_kp_with_rng` are removed. Use `Responder::new`
or `Responder::new_with_rng` with a `secp256k1::Keypair`.
…onstruction

Both ways of building a `Responder` end with the same two things: a static
key and a certificate over it. `Responder::new` now signs that certificate
right away and stores it, the same as `from_certificate` does with one
issued in advance, so the `Responder` no longer carries the authority
keypair until `step_1` and the private `CertificateSource` enum is gone.

`step_1` needed the current time and a random number generator only for
that signature, so `step_1_with_now_rng` is removed, here and on
`codec_sv2::Handshake<Responder>`, and `step_1` is available without
`std`. The time moves to the constructor: `new_with_rng` becomes
`new_with_now_rng`.

A `Responder` serves one handshake, so the certificate still covers one
connection. Its validity window now starts when the `Responder` is built
instead of when the initiator's first message arrives, and the signature
is computed whether or not that message ever comes.

In the noise_sv2 benches, `step_1_responder` no longer includes the
signature, and `handshake` builds the `Responder` inside the measured
closure so that it still does.

BREAKING CHANGE: `Responder::step_1_with_now_rng` and
`Handshake::<Responder>::step_1_with_now_rng` are removed; call `step_1`.
`Responder::new_with_rng` is replaced by `Responder::new_with_now_rng`,
which takes the current time.
@plebhash
plebhash force-pushed the 2026-11-09-noise-preissued-cert branch from 6d37cda to 2533181 Compare November 16, 2026 13:47
plebhash added a commit to plebhash/sv2-apps that referenced this pull request Nov 16, 2026
…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.
step_1 took `&mut self` and erased the handshake secrets only on
success, leaving a Responder that could be passed around but not used.
It now takes `self: Box<Self>`, so a second call does not compile and
the secrets are erased by `Drop` on every path, including a failed
step.

The receiver is the `Box` the constructors return rather than a plain
`self`: moving the struct out of the box would copy the secrets to the
stack and free the heap allocation without wiping it.

The test that inspected the Responder after step_1 is replaced by one
that drops a Responder in place and checks the secrets are gone.

BREAKING CHANGE: `Responder::step_1` takes `self: Box<Self>` instead
of `&mut self`.
The same change as for `Responder::step_1`: `step_2` and
`step_2_with_now` take `self: Box<Self>` instead of `&mut self`, so
the step cannot be taken twice and `Drop` erases the handshake secrets
on every path, including a rejected certificate.

codec_sv2's `InitiatorSent` now holds the `Box<Initiator>` it is
given instead of moving the `Initiator` out of it, which also stops
`Handshake::step_0` from copying the ephemeral key out of an allocation
that is then freed without being wiped.

The test that inspected the Initiator after step_2 is replaced by one
that drops an Initiator in place and checks the secrets are gone.

BREAKING CHANGE: `Initiator::step_2` and `Initiator::step_2_with_now`
take `self: Box<Self>` instead of `&mut self`.
plebhash added a commit to plebhash/sv2-apps that referenced this pull request Nov 16, 2026
…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.
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: let a server present a pre-issued certificate

4 participants