Skip to content

Let Pool, JDS and JDC present a pre-issued Noise certificate - #993

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

companion stratum-mining/stratum#2497

On main, Pool (and the JDS it embeds) and JDC sign their Noise certificate at every handshake, so each server host holds the authority secret key. With this PR a server presents a certificate that was issued elsewhere. The authority secret key leaves the server hosts, and keys rotate without a restart. Signing at handshake stays available as a noise_sv2 API; sv2-apps no longer offers it.

What changes in the config

main:

authority_public_key = "9auqWEzQDVyd2oe1JVGFLMLHZtCo2FFqZwtKA5gd9xbuEu7PH72"
authority_secret_key = "mkDLTBBRxdBv998612qipDYoTK3YUrqLe8uWw7gu3iXbSrn2n"
cert_validity_sec = 3600

This PR, inline:

static_private_key = "2Zdzjqd9c7EB4C9FBuqyDNzErruL4DNrJHoL5jhdE6QVArUTR8"
certificate = "11HpWbvGUzBwSTTVZMX6Dc1bVAupxFfvzkFqWfcQzXwVWWeCFQ6rQTDtrNbv4ncSx11gBb1trRbuhuCuXNptqbQBHnyx4VJKULV9e4AWew"
# optional: the certificate is checked against it at startup and before every handshake
authority_public_key = "9auqWEzQDVyd2oe1JVGFLMLHZtCo2FFqZwtKA5gd9xbuEu7PH72"

or a file holding those same fields, re-read before every handshake:

active_static_key = "/etc/sv2/active_static_key.toml"

The same fields come from the environment as POOL__STATIC_PRIVATE_KEY, POOL__CERTIFICATE, POOL__ACTIVE_STATIC_KEY, POOL__AUTHORITY_PUBLIC_KEY (JDC__ likewise), through the existing <PREFIX>__FIELD loader rather than the SV2_* names sketched on the issue, so docker needs nothing new. The environment overrides the TOML field by field, then on the merged result: an inline pair is used and active_static_key is ignored; otherwise the file is used; neither, or half a pair, refuses to start. The old fields are refused rather than ignored:

authority_secret_key and cert_validity_sec are not accepted: a server never holds the authority secret key. Issue a certificate where that key is kept and set static_private_key and certificate, or active_static_key

Rotation without a restart

With active_static_key, the server reads the file before every handshake. Write the next key file, move the symlink, and the next handshake presents the new key while open connections stay up. Each server checks its credentials once before binding (version, validity window, and the signature when authority_public_key is set) and refuses to start with the reason, so a bad file shows up as a startup error instead of as handshake rejections on the clients.

Issuing: sv2-certificate

A new binary in stratum-apps behind the cli feature, meant to run where the authority secret key is kept:

sv2-certificate keygen                       # an authority keypair, or a server static key
read -rs SV2_AUTHORITY_SECRET_KEY && export SV2_AUTHORITY_SECRET_KEY
sv2-certificate issue --valid-for 93600 --toml key_2.toml --env key_2.env --env-prefix POOL
sv2-certificate inspect <CERTIFICATE>

issue generates a static key unless --static-private-key is given, writes the active_static_key file and/or a .env of <PREFIX>__* variables, owner-readable only, never overwriting, and insists on the .toml/.env names since the two files look alike inside. The authority secret key is taken from the environment so it stays out of the shell history and of ps, and a mistyped key is reported without echoing anything derived from it. inspect prints the window with the UTC dates and whether the certificate is accepted at this moment:

version = 0
valid_from = 1794253486  # 2026-11-09 19:44:46 UTC
not_valid_after = 4294967295  # 2106-02-07 06:28:15 UTC
# accepted now, expires in 2500704047 seconds

The Template Provider key is required

noise_sv2 no longer builds an initiator without an authority key (see the companion), so connect_with_noise takes the key outright and Sv2Tp.public_key is required: it is the key the TP prints at startup as Template Provider authority key: ..., as the READMEs already said. The local-TP example configs carry the development authority key with a note that it will not match a real TP. The integration-test harness writes the test authority's secret key into the sv2_authority_key file sv2-tp loads from its data directory before starting it, so sv2-tp presents a certificate from the same authority as every role under test, and every client in the harness (sniffer, mock roles, mining device, Pool, JDC) pins that one key. The mining_device binary's --pubkey-pool flag is required for the same reason.

Examples, docker, tests

Every example config, docker/docker_env.example and the integration test harness (sniffer included) use one throwaway static key with a certificate from the development authority, whose secret key is public, valid until 2106-02-07 (the end of the certificate's u32 clock). They start out of the box and prove nothing to anyone; the comment at the keys says so and names the production path. The client-side authority_pubkey pins are unchanged. The Pool and JDC READMEs gain a "Server keys" section with the precedence rule and the issuing commands.

Code and versions

stratum-apps gains key_utils::Certificate (the 74-byte SIGNATURE_NOISE_MESSAGE as one base58check string; issuing and checks go through noise_sv2::SignatureNoiseMessage, so the module needs the core feature, which cli now pulls) and network_helpers::ResponderCredentials (the two sources above, flattened into the Pool and JDC configs); key_utils is split into submodules with the old paths re-exported. Breaking: accept_noise_connection(stream, &ResponderCredentials); connect_with_noise(stream, Secp256k1PublicKey); TemplateProviderType::Sv2Tp { public_key } no longer optional; Pool's AuthorityConfig and JDC's PoolConfig are gone; ConnectionConfig::new drops the validity; the three apps' start_downstream_server take the credentials. Bumps: stratum-apps 0.10.0, pool_sv2 0.9.0, jd_server_sv2 0.8.0, jd_client_sv2 0.8.0, translator_sv2 0.8.0 (requirement only), integration_tests_sv2 0.8.0. scripts/list-config-schema-changes.sh reports the JDC examples: authority_secret_key and cert_validity_sec gone, static_private_key and certificate new, and public_key new under [template_provider_type.Sv2Tp] in the local-TP examples.

The three apps report a refused credentials config under three different error kinds (Pool Configuration, JDS InvalidConfig, JDC NetworkHelpersError); unifying that is #992 and is not done here.

@plebhash
plebhash force-pushed the 2026-11-09-noise-preissued-cert branch 3 times, most recently from 747a471 to 9bc721c Compare November 12, 2026 14:13
Comment thread stratum-apps/src/bin/sv2-certificate.rs Resolved
Comment thread stratum-apps/src/bin/sv2-certificate.rs Resolved
@plebhash
plebhash force-pushed the 2026-11-09-noise-preissued-cert branch 2 times, most recently from b5679e7 to bdfa511 Compare November 14, 2026 14:35
Comment thread stratum-apps/src/bin/sv2-certificate.rs Outdated
Comment on lines +159 to +163
// (it exists already, or its directory does not) fails before anything is on disk.
let files = outputs
.iter()
.map(|(path, _)| create_secret_file(path))
.collect::<Result<Vec<_>, _>>()?;

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.

clanker:

Creating these files already changes the filesystem. I reproduced an empty TOML file being left behind when the subsequent environment file cannot be created. Please clean up outputs created by this invocation on failure, preserving existing files, and cover this failure path with a test.

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 on lines +193 to +198
match certificate.check_validity(now) {
Ok(()) => println!(
"# accepted now, expires in {} seconds",
not_valid_after.saturating_sub(now)
),
Err(e) => println!("# rejected now: {e}"),

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.

clanker:

This checks the version and time window, but cannot establish acceptance without the static and authority public keys. Please report “within validity window; signature not verified” here. Full verification can remain a separate operation.

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

/// Startup check: everything [`Self::responder`] does for a handshake, so a missing file, an
/// unreadable key or a certificate that does not match surfaces before the server accepts
/// connections.
pub async fn check(&self) -> Result<(), Error> {

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.

clanker:

Please extract loading and validation into a shared operation returning the resolved identity. check() can discard that identity, while responder() builds handshake state from it. File credentials should still reload for each connection so rotation keeps its current behavior.

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

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-certificate to certify a static key (generated on
the spot unless given) over a chosen validity window, and
inspect-certificate to read a certificate's window back.
issue-certificate 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. If one of the files cannot be written, the ones already
created by that run are removed.

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
`connect_with_noise` took the server's authority public key as an
`Option`, and without one the Pool and JDC connected to a Sv2 Template
Provider encrypted but unauthenticated. The Sv2 spec defines no such
mode (04-Protocol-Security.md 4.5, 4.5.3, 4.7) and `noise_sv2` no
longer offers it, so `Sv2Tp.public_key` is required: it is the key the
TP prints at startup as "Template Provider authority key", as the
Pool and JDC READMEs already say. The local-TP example configs carry
the development authority key with a note that it will not match a
real TP.

The integration-test harness installs the test authority's secret key
in sv2-tp's data directory before starting it (the `sv2_authority_key`
file sv2-tp loads, in Bitcoin Core's `CKey` serialization), so sv2-tp
presents a certificate from the same authority as every role under
test and every client in the harness, the sniffer, the mock roles and
the mining device included, pins that one key. The `mining_device`
binary's `--pubkey-pool` flag is required for the same reason.

BREAKING CHANGE: `connect_with_noise(stream, Secp256k1PublicKey)`;
`TemplateProviderType::Sv2Tp { public_key }` is no longer optional, so
Pool and JDC configs using a Sv2 Template Provider must set it. Covered
by the bumps already in this series.
@plebhash
plebhash force-pushed the 2026-11-09-noise-preissued-cert branch from bdfa511 to 785a9e5 Compare November 16, 2026 14:06
…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 785a9e5 to 165488f Compare November 16, 2026 15:51
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.

3 participants