Skip to content

document authority key management and rotation - #234

Open
plebhash wants to merge 2 commits into
stratum-mining:mainfrom
plebhash:2026-09-21-key-management
Open

plebhash wants to merge 2 commits into
stratum-mining:mainfrom
plebhash:2026-09-21-key-management

Conversation

@plebhash

@plebhash plebhash commented Sep 21, 2026 •

Copy link
Copy Markdown
Member

Chapter 4 never says which key is which or how rotation works, so a reader can conclude that the key in the mining URL is the server's static Noise key and that rotating it disconnects every client.

This PR adds 4.8 Key Management and Rotation. A table contrasts the authority key (out of band, trust anchor) with the server's static key (in band, trusted through its certificate), followed by four subsections:

  • 4.8.1 Private key custody. The authority private key SHOULD stay off internet-facing servers and MAY be derived from a BIP32 hierarchy. A server holds a static key and a certificate issued elsewhere, replaceable at any time with no client impact. Handshake-time signing and per-connection static keys SHOULD NOT be used outside development and testing.
  • 4.8.2 Rotating the authority key. A new key reaches clients out of band. A client MAY hold several authority keys for one endpoint, so an operator publishes the next key ahead of use and switches without coordinating with clients. A leaked key keeps verifying until a client drops it.
  • 4.8.3 Certificate validity. Expiry is the only bound on a leaked static key, so certificates SHOULD be short-lived and renewed onto a new static key. Clock skew, established sessions at expiry, and devices without a clock are covered.
  • 4.8.4 Failed certificate verification. Terminate and fall back, or retry with a backoff when there is no fallback. A way to continue regardless SHOULD NOT be the default.

4.7 allows more than one authority key in the URL path, separated by commas; a client that accepts a single key uses the first.

It also drops the Pool qualifier from Authority Key, since any server can hold one. The 4.7 anchor changes from #47-url-scheme-and-pool-authority-key to #47-url-scheme-and-authority-key.

Shaped by #235. Authority key rotation needs no protocol extension. Nothing changes on the wire or in the cryptography, and no new MUST is introduced; server guidance is SHOULD and SHOULD NOT with a carve-out for development and testing, so current implementations remain compliant.

@plebhash
plebhash marked this pull request as draft September 21, 2026 14:44
@plebhash plebhash changed the title document key management and rotation WIP document key management and rotation Sep 21, 2026
@plebhash
plebhash force-pushed the 2026-09-21-key-management branch 2 times, most recently from 5fd415b to 8994fff Compare September 21, 2026 14:47
@plebhash plebhash changed the title WIP document key management and rotation document key management and rotation Sep 21, 2026
@plebhash
plebhash marked this pull request as ready for review September 21, 2026 14:53
@plebhash
plebhash requested a review from bit-aloo September 21, 2026 14:55

@TheBlueMatt TheBlueMatt left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

lgtm, some tiny nits

Comment thread 04-Protocol-Security.md Resolved
Comment thread 04-Protocol-Security.md Resolved
Comment thread 04-Protocol-Security.md Resolved
@plebhash
plebhash force-pushed the 2026-09-21-key-management branch from 10ecfe2 to 36ddc78 Compare September 22, 2026 00:46
Comment thread 03-Protocol-Overview.md Resolved
Comment thread 03-Protocol-Overview.md Resolved
Comment thread 04-Protocol-Security.md Resolved
Comment thread 04-Protocol-Security.md Resolved
@plebhash
plebhash force-pushed the 2026-09-21-key-management branch from 36ddc78 to cc4dc16 Compare September 23, 2026 20:06
@plebhash plebhash changed the title document key management and rotation document authority key management and rotation Sep 23, 2026
@plebhash
plebhash force-pushed the 2026-09-21-key-management branch from cc4dc16 to 41f5a47 Compare September 23, 2026 22:54
Comment thread 04-Protocol-Security.md Resolved
Comment thread 04-Protocol-Security.md Resolved
Comment thread .gitignore Resolved
Comment thread AGENTS.md Resolved
Comment thread 04-Protocol-Security.md Resolved
@plebhash
plebhash force-pushed the 2026-09-21-key-management branch from 41f5a47 to a24f821 Compare September 25, 2026 22:46
@plebhash
plebhash force-pushed the 2026-09-21-key-management branch 4 times, most recently from 32b0ee5 to 9baf3fa Compare October 12, 2026 19:40
The trust anchor is named inconsistently. Section 4.7 calls it the Pool
Authority Public Key, while 4.3.1.1, the rest of 4.7 and 4.5.3 call it the
Authority public key, an authority, or the Certificate Authority, and the
CERTIFICATE field is authority_public_key. Only 4.7 and 3.6.5 attach a pool to
it.

The qualifier is also wrong. The introduction to chapter 4 makes the handshake
mandatory for job declaration services and template distributors as well as
pool mining services, and optional between a mining device and a local proxy.
In each of those cases the client is configured with the authority key of
whatever it connects to, which need not be a pool, and for a self-hosted proxy
is usually the operator's own key.

Drop the qualifier rather than replace it, so the term converges on the
unqualified form the chapter already uses elsewhere, and leave
authority_public_key untouched.

The closing sentence of 3.6.5 goes with it. It described the threat as a
compromised pool server redirecting hashrate, which put the pool back into a
paragraph the rename had just generalized. Reconnect is a common protocol
message, so the server that sends it is whichever one the client is connected
to, and the guarantee holds for every subprotocol.

Other references to the pool as a party are left alone: this changes what the
key is called, and which servers the reconnect threat covers, not who operates
them.
@plebhash
plebhash force-pushed the 2026-09-21-key-management branch 5 times, most recently from 1830195 to 3db9b50 Compare October 12, 2026 21:22
@plebhash

plebhash commented Oct 12, 2026 •

Copy link
Copy Markdown
Member Author

lgtm, some tiny nits

@TheBlueMatt thanks for your first round of reviews

since the WG call, we had more discussions which led me to push some updates to this PR

would be willing to give it another round of reviews?

I'm particularly curious to hear your thoughts around the new section §4.8.2

Comment thread 04-Protocol-Security.md Resolved
Chapter 4 defines the handshake and the certificate precisely but never
says which key is which. An implementer can conclude that the key in the
mining URL is the server's static Noise key, and from there that rotating
keys either disconnects every client or requires the server to keep an
active set of keys, neither of which the design implies.

Add 4.8 Key Management and Rotation. It opens with a table contrasting
the authority key, configured out of band (4.7) and acting as the trust
anchor, with the server's static key, delivered in the handshake (4.5.2)
and trusted only through the certificate that binds it to the authority
(4.5.3), and states why no message carries an authority key. Four
subsections follow:

- 4.8.1 Private key custody: what a leaked authority private key enables
  (certificates that verify) and what it does not (no session, and no
  client until the attacker is also the endpoint that client reaches),
  so the key SHOULD stay off internet-facing servers and MAY come from a
  BIP32 hierarchy. A server holds only a static key and a certificate
  issued elsewhere. "Static" is the Noise term for the key brought to a
  handshake, not a claim about its lifetime, and such a key can be
  replaced freely. Outside development and testing a server SHOULD NOT
  sign at handshake time nor generate a static key per connection, since
  that leaves nothing to certify in advance.

- 4.8.2 Rotating the authority key: a new key reaches clients out of
  band like the first. A client MAY hold several authority keys for one
  endpoint, which lets an operator publish the next key ahead of use and
  switch without coordinating with clients. A leaked key keeps verifying
  until a client drops it, so a compromise announcement names the key to
  remove as well as the key to add.

- 4.8.3 Certificate validity: with no revocation, expiry is the only
  bound on a leaked static key, so certificates SHOULD be short-lived
  and renewed onto a new static key. Timestamps are evaluated against
  the initiator's clock at handshake time, with skew tolerance, no
  termination of established sessions at expiry, and NTP for devices
  without a reliable clock.

- 4.8.4 Failed certificate verification: the client SHOULD terminate and
  fall back to its next configured server, or retry with a backoff when
  it has none. A missed rotation and an active attacker look the same to
  the client, so a way to continue regardless SHOULD NOT be enabled by
  default and is presented as unauthenticated operation.

Section 4.7 allows more than one authority key in the URL path,
separated by commas, a client that accepts a single key using the first,
and gains a second example. 3.6.5 points at 4.8. BIP32 is added as
reference 9.

Nothing on the wire or in the cryptography changes and no MUST is
introduced. Guidance for servers is SHOULD and SHOULD NOT with an
explicit carve-out for development and testing, so an implementation
that signs certificates at handshake time remains compliant. Multiple
authority keys are a client-side configuration matter: the server still
presents one certificate signed by one authority.

Discussion: stratum-mining#235
@plebhash
plebhash force-pushed the 2026-09-21-key-management branch from 3db9b50 to a0a32bd Compare October 28, 2026 16:21
Comment thread 03-Protocol-Overview.md
This ensures that an attacker will not be able to redirect hashrate to an arbitrary server should the pool server get compromised and instructed to send reconnects to a new location.
For security reasons, it is not possible to reconnect to a server with a certificate signed by a different authority key (see 4.8).
The message intentionally does not contain an **authority public key** and thus cannot be used to reconnect to a server under a different authority.
This ensures that an attacker will not be able to redirect the client to an arbitrary server should its present server get compromised and instructed to send reconnects to a new location.

@coleFD coleFD Oct 29, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

This is true in any case the authority pubkey gets compromised. If a key is compromised and the client still has the old compromised pubkey in the local set, that client is still vulnerable to this until the actual pool servers update to the new key. If the authority pubkey was sent in band, the pool could add to it's local set immediately and log which clients havent updated yet and notify them to get off the old key. Honestly i still think sending the desired authority pubkey in band is the best solution for zero downtime rotations and ensuring clients are off of compromised keys as soon as possible.

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.

hmm I'm a bit confused with your rationale

first:

that client is still vulnerable to this until the actual pool servers update to the new key.

assuming MITM is also part of the threat model, the client is vulnerable until the client removes the compromised key from its configuration... I don't see how any actions from pool really protect the client in a meaningful way?

then, we need to clarify our threat model... it's important we don't automatically conflate:

  • A: authority key compromise
  • B: MITM and server impersonation

A alone buys nothing for the attacker's ability to do real damage.

and if the attack consists of A+B, whatever in-band mechanism for updating keys also runs through the attacker, who simply drops it

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

If the pool supports both public keys and can send the certificate based on the in-band public key, the clients that update their public key are just as safe in both models (with in-band public key or not). The comment makes it sound like it's safer that the public key isn't in-band, and I dont think that is necessarily true.

In your A/B example, B cant happen without A. I'm referring to B. If B happens, you dont necessarily assume it happens to all clients. It may be that only one site is compromised. That doesnt mean the pool needs to drop all clients that arent affected that havent updated keys. I believe the way it should work is:

  1. There is an event of MITM at a site
  2. pool rotates authority keys and tells all customers to move to the new key. The pool now supports 2 authority keypairs
  3. pool monitors which customers are still using the compromised keys (most likely unaffected sites that havent updated yet) and keeps reminding remaining clients to update to the new keys with a deadline
  4. Pool deprecates the old key

regarding and if the attack consists of A+B, whatever in-band mechanism for updating keys also runs through the attacker, who simply drops it. This doesnt really make sense to me. The client would be sending the pubkey that tells the server what certificate to use so that the server responds with the expected certificate the first time. The MITM attacker cant just drop it. It either has the corresponding certificate or not

@coleFD coleFD Oct 30, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

I'm bringing this up because i realized the current proposal still doesn't allow for all customers, even unaffected ones, to continue mining if they haven't updated their miners immediately after another unrelated customers site was compromised. It leaves pools in a weird spot. The pool either rotates keys to appease the compromised site while dropping all of the other customers who didn't update to the new key immediately. Or the pool can tell the affected customer it has to wait until the other clients move to the new keys. I think the only real alternative is requiring pools to do infra updates to support extra ports or domains, and i think that will add complexity for both client and pools. Pools have to do the infra updates and clients have to change ports instead of just relying on the one standard well known ports or domains like they currently do

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.

In your A/B example, B cant happen without A. I'm referring to B. If B happens, you dont necessarily assume it happens to all clients. It may be that only one site is compromised. That doesnt mean the pool needs to drop all clients that arent affected that havent updated keys.

B can happen without A, if a server’s static key and corresponding certificate get compromised. Agree, this will not happen to all the clients, only to a portion of them. The Pool doesn’t have to drop all the clients, because their corresponding static key and certificate were not compromised. For a scenario like this, certificates usually come with an expiry, and once a certificate expires, the client gets a new valid one on the next handshake. In B, an attacker can’t do much: the Pool will rotate the static key associated with the server and send a fresh certificate and static pubkey to the client. Once the stolen certificate expires, the attacker won’t have leverage anymore.

regarding and if the attack consists of A+B, whatever in-band mechanism for updating keys also runs through the attacker, who simply drops it. This doesnt really make sense to me. The client would be sending the pubkey that tells the server what certificate to use so that the server responds with the expected certificate the first time. The MITM attacker cant just drop it. It either has the corresponding certificate or not

Let’s say we go with your solution of sending the pubkey to the server before accepting the certificate, and an attacker has a compromised static key and its certificate, so it can MITM the client until that certificate expires. During that window, the attacker can block the Pool’s in-band rotation message, or, if the client accepts authority keys in-band, send its own authority pubkey, which the client adds to its local set. On reconnect, the client goes through the attacker again (because the MITM is still underway) and sends that pubkey to tell the server which authority key it expects. The attacker already has a valid certificate for that pubkey, because it holds the private key. And boom, even after the stolen certificate expires, every connection still goes through the attacker, so the Pool never gets a chance to deliver a new pubkey in-band.

I think we should keep static keys and authority keys distinct. Static keys identify the server, and the server can rotate them whenever it wants without any client action, as long as each new static key has a certificate signed by the authority key. Authority keys should be kept offline and used only to sign certificates. Pools can still rotate authority keys, for example after an org restructuring. They would do that by switching to another key from a list they published in advance. Clients configured with that whole list will accept certificates signed by any key in it, so the switch doesn’t disrupt their mining. Clients configured with only the old key still have to be updated out of band.

@plebhash plebhash Oct 30, 2026 •

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.

the current proposal still doesn't allow for all customers, even unaffected ones, to continue mining if they haven't updated their miners immediately after another unrelated customers site was compromised.

I don't think that's true, and it makes me wonder if the proposal is being interpreted correctly.

the goal of this proposal is to allow scenarios where since the beginning (before any key is compromised), Pool always publishes a set of keys, where some of them are backups for future rotations.

so all clients have the backup keys in their configs since the beginning, and are able to validate certificates against backup keys regardless of whether these same clients were affected by an attack or not.

in summary, "if they haven't updated their miners immediately" shouldn't matter: the only update a client ever needs is picking up the published set, once, before anything happens. that's the whole point of allowing multiple authority keys.

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.

We had a call today (@coleFD, Derrick, @GitGab19, @bit-aloo and me) and it turned out we were talking past each other here.

What Cole is proposing is neither a server→client message nor an Sv2 extension: the client appends the authority key it is configured with to the first handshake message, and the server answers with the certificate signed by that key. That allows Pools to monitor whether all meaningful clients have moved away from a specific authority key before retiring it for good. Unfortunately it's a breaking change, so it would be costly to coordinate with the ecosystem.

My point above about the in-band message running through the attacker was aimed at a server→client key and doesn't apply to this.

The goal is availability and visibility during a key switch on a single endpoint rather than the security of the trust anchor, and on that we're on the same page.

We also agreed it's a change to the handshake itself, so it can't ride on this PR or on an extension.

Cole's view is that once the client names its authority key in the handshake, clients are better off with a single key, so the multikey in 4.8.2 would be of little help then.

Comment thread 04-Protocol-Security.md
```

## 4.7 URL Scheme and Pool Authority Key
## 4.7 URL Scheme and Authority Key

@jakubtrnka jakubtrnka Oct 31, 2026 •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

This is still a brainstorm, but I was thinking about a different direction: managing authority keys separately from mining URLs, through a general trust store mapping pools/endpoints to their accepted and revoked authority keys.

The trust store could be maintained locally or updated from sources chosen by the operator. An SRI-hosted file signed by designated SRI members could be one source, but it wouldn’t be mandatory or exclusive. GPG signatures and a web of trust might be useful here; I’d leave the exact mechanism open for now. Clients could also operate without subscribing to any source, using manually configured authority keys.

My main motivation is avoiding interruptions when authority-key deployment and distribution get out of sync—for example, when a pool starts using a new authority key before that key reaches the client’s trust store.

I’m proposing roughly this behavior:

  1. The certificate verifies against a trusted authority key for the pool: proceed with authenticated operation.
  2. No known authority key verifies: allow encrypted but unauthenticated operation with a warning, unless the client/operator policy explicitly prohibits it.
  3. The certificate verifies against a known revoked authority key: always reject it, regardless of the fallback policy.

An unavailable or stale trust store should produce a warning rather than necessarily stop mining. The client should still verify against whatever trusted keys it already has.

Since the handshake doesn’t identify the signing authority, the client would need to try the pool’s known keys. That also means retaining revoked keys to recognize signatures made with them. For a small number of keys, checking them during connection setup seems acceptable.

This deliberately trades authentication guarantees for availability in the fallback case. The client cannot distinguish a legitimate rotation it hasn’t learned about from an attacker presenting an untrusted certificate. I’d like that tradeoff to be an operator-controlled policy, while making key distribution and revocation easier to manage.

@rkuester rkuester left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Some client-side comments from Mujina.

Firmware isn't the only consumer of pool configuration. Operators at scale configure their miners with fleet management tools, so our designs should serve those tools as well as a person setting up one miner.

Multiple keys and existing clients

04-Protocol-Security.md L398

A client that accepts more than one authority key (4.8.2) takes them from the same path, separated by commas; a client that accepts only one uses the first.

If this is meant for backward compatibility, I don't think it works. Existing clients won't ignore the extra keys. A comma will likely break their parsing, and the longer URL may exceed their length limits, so they'll need updates to handle multiple keys.

Since clients need updating either way, and a client that handles one key can surely handle a few, perhaps the spec should require a small minimum number of keys, such as three.

A connection profile instead of a longer URL

04-Protocol-Security.md L408--413

stratum2+tcp://thepool.com:34254/9bXiEd8boQVhq7WddEcERUL5tyyJVFYdU8th3HfbNXK3Yw6GRXh
stratum2+tcp://thepool.com:34254/9bXiEd8boQVhq7WddEcERUL5tyyJVFYdU8th3HfbNXK3Yw6GRXh,9auqWEzQDVyd2oe1JVGFLMLHZtCo2FFqZwtKA5gd9xbuEu7PH72

Perhaps we're outgrowing the URL. It was clever with one key, but with several it's looking tortured. The URL never appears in the protocol. It's only a recommended way to pass configuration from upstream operators to miner operators and their tools. Since no existing client supports multiple keys anyway, perhaps it's time for a richer format, a connection profile such as:

{
  "stratum2": 1,
  "name": "The Pool",
  "endpoints": [
    { "host": "us.thepool.com", "port": 34254 },
    { "host": "eu.thepool.com", "port": 34254 }
  ],
  "authority_keys": [
    { "key": "9bXiEd8boQVhq7WddEcERUL5tyyJVFYdU8th3HfbNXK3Yw6GRXh",
      "label": "current" },
    { "key": "9auqWEzQDVyd2oe1JVGFLMLHZtCo2FFqZwtKA5gd9xbuEu7PH72",
      "label": "backup" }
  ]
}

A profile is just an interchange format. Firmware and fleet tools would still show connection settings in their own forms, and import a profile, by paste or from a file, to fill them in.

A profile also reads better on a pool's website, with no very long lines, and it isn't sensitive to line breaks or to spaces after commas. Clients ignore unknown fields, so the format can grow.

Served from a well-known location, such as https://thepool.com/.well-known/stratum2.json, a profile could be imported from the domain alone, with the operator confirming it once at setup. Tools could also poll it and notify the operator when keys are added or removed. A revoked key is simply absent from the list.

Either way, configuration and key management stay out of band, as we prefer, while the ecosystem gets a recommended, tool-friendly way to do it.

If this idea for a connection profile has any legs, perhaps it belongs in a preparatory PR, ahead of this one.

Devices without a reliable clock

04-Protocol-Security.md L474

  • A device without a reliable clock SHOULD obtain the current time from a network time source such as NTP before the handshake, and proceeds without enforcing the window if none is reachable.

For what it's worth, SRI can't do this yet. In noise_sv2 1.4.2, the only way to skip the validity window is to pass no authority key, which skips the signature check too. Callers can supply the time (step_2_with_now) but not skip the window, and connect_with_noise uses the system clock. The library assumes that clock is right.

NTP is a reasonable SHOULD, but we should assume some miners run simple software with no real-time clock and no NTP, and design certificate expiry and other time checks with them in mind. NTP also brings trust issues of its own. Plain NTP is unauthenticated, so an attacker on the path can feed a miner a wrong time, or block NTP to trigger the fallback above.

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.

6 participants