Skip to content
Open
Show file tree
Hide file tree
Changes from 20 commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
381ae63
net: bind verifications to an address, require iat, bound key fetches
samlown Nov 13, 2026
5bfe840
net: cap authority countersignatures at 90 days
samlown Nov 13, 2026
19efe34
net: bind registrations and verifications to the subject's key
samlown Nov 13, 2026
2cdeefb
net: FindVerification takes the subject
samlown Nov 13, 2026
f6c65ca
net: spell out and cite ACME, RFC 7638 and RFC 7800
samlown Nov 13, 2026
62e54e6
net: require cnf on verifier countersignatures
samlown Nov 13, 2026
e7b0f9e
net: authorities register only verified parties; trust verifiers dire…
samlown Nov 15, 2026
1c46ab6
net: FindVerifications returns every valid verification
samlown Nov 15, 2026
2994b8d
net: address Copilot review comments
samlown Nov 15, 2026
700b886
net: cover dialing, FindVerifications inputs and unsigned pairs
samlown Nov 15, 2026
7f4fd5d
net: rewrite the spec for readability
samlown Nov 15, 2026
7b7e9f0
net: address further review comments
samlown Nov 15, 2026
1ffe994
net: refuse every special-purpose range that is not globally reachable
samlown Nov 15, 2026
d273609
net: bind key changes to the new key, and follow no redirects
samlown Nov 15, 2026
9a9b755
net: simplify key lineage and add SignKeyChange
samlown Nov 15, 2026
d63d22a
net: reject envelopes whose document does not match its digest
samlown Nov 15, 2026
9fde915
net: document signature bindings and add a tampering suite
samlown Nov 15, 2026
a31effb
net: reject envelopes with no document, and tamper with dig
samlown Nov 15, 2026
4080ac9
net: add key changes to the bindings table
samlown Nov 15, 2026
b23083b
net: fold the digest check changelog into net-verifier-audience
samlown Nov 19, 2026
6655883
net: fix review findings on endorsements, confirmations and dialing
samlown Nov 19, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions changes/unreleased/net-verifier-audience.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
## Changed

- `net`: **breaking**: verifier countersignatures count only when their `aud` is the envelope's `from` address, so each address needs its own verification, and they need a `cnf` naming the subject key the verifier saw.
- `net`: **breaking**: authority countersignatures need an `iat` no later than the present and an `exp` at most 90 days after it.
- `net`: **breaking**: `Client.VerifyDelivery` and `Client.Who` need an `iat` no later than the present, and a key that is still valid when the envelope is received.
- `net`: **breaking**: authority countersignatures need a `cnf` naming the key of a signature that confirms the envelope's `from` and `to`; `Endorsement.Key` reports it.
- `net`: **breaking**: `Client.VerifySender(ctx, env)` takes a delivered envelope, requires a verified sender, and requires the envelope to be signed with the sender's endorsed key.
- `net`: **breaking**: `Client.VerifyAuthority` is replaced by `Client.VerifyEndorsement`. Authority countersignatures must name a verifier whose countersignature is valid, and there is no registered-only status; `Endorsement.Verified`, `ErrUnknownAuthority` and `ErrNotVerified` are removed in favour of `ErrNotEndorsed`.
- `net`: `WithVerifiers` sets verifiers a client accepts directly, without an authority, when their `cnf` names the sender's key. There are none by default.
- `net`: `Client.DeliveryKeys` returns the keys confirming a delivery, `Client.DeliveryConfirmations` adds each signature's signing time and `cnf`, and `Client.FindVerifications` reads the valid countersignatures of a verifier, for authorities tracking key lineage.
- `net`: in a key change the current key's confirming signature names the new key with `cnf`, which `SignKeyChange` does, and authorities count only confirming signatures made within `MaxRequestAge` (5 minutes) of a registration request. A first registration takes one key, and a key bound before cannot start a lineage again.
- `head`: `WithConfirmation` sets an RFC 7800 `cnf` claim, read from `SigningPayload.Confirmation`.
- `dsig`: `JKT` returns a key's RFC 7638 thumbprint in base64url form.
- `net`: only the first four signatures by one issuer are checked against its keys.
- `net`: a countersignature with a `verifier` claim never counts as a verification.

## Fixed

- `net`: `HTTPFetcher` dials the addresses it has checked, rather than resolving the host again.
- `net`: `HTTPFetcher` dial and lookup errors wrap their cause as well as `ErrUnavailable`.
- `net`: a delivery with no valid signature reports why the last candidate failed.
- `net`: `HTTPFetcher` refuses every IANA special-purpose range that is not globally reachable, and the NAT64, 6to4 and Teredo ranges.
- `net`: `HTTPFetcher` follows no redirects, and reports one as a definitive `ErrFetchFailed`.
- `net`: `Client.VerifyDelivery`, `Client.Who`, `Client.VerifyEndorsement` and `Client.FindVerifications` reject an envelope with no document, or whose document does not match its digest.
22 changes: 22 additions & 0 deletions dsig/key.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import (
"crypto/ecdsa"
"crypto/elliptic"
"crypto/rand"
"encoding/base64"
"encoding/json"
"errors"
"fmt"
Expand Down Expand Up @@ -175,6 +176,27 @@ func (k *PublicKey) Thumbprint() string {
return keyThumbprint(k.jwk)
}

// JKT returns the key's RFC 7638 SHA-256 thumbprint, base64url-encoded
// without padding, as used in an RFC 7800 `cnf` claim's `jkt` member.
func (k *PrivateKey) JKT() string {
return keyJKT(k.jwk)
}

// JKT returns the key's RFC 7638 SHA-256 thumbprint, base64url-encoded
// without padding, as used in an RFC 7800 `cnf` claim's `jkt` member.
func (k *PublicKey) JKT() string {
return keyJKT(k.jwk)
}

func keyJKT(jwk *jose.JSONWebKey) string {
pub := jwk.Public()
d, err := pub.Thumbprint(crypto.SHA256)
if err != nil {
return ""
}
return base64.RawURLEncoding.EncodeToString(d)
}

func keyThumbprint(jwk *jose.JSONWebKey) string {
d, err := jwk.Thumbprint(crypto.SHA256)
if err != nil {
Expand Down
5 changes: 5 additions & 0 deletions dsig/key_internal_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -124,3 +124,8 @@ func TestPublicKeyValidateInvalidJOSE(t *testing.T) {
require.Error(t, err)
assert.Contains(t, err.Error(), "jose key is invalid")
}

func TestKeyJKTInvalid(t *testing.T) {
k := &PublicKey{jwk: &jose.JSONWebKey{KeyID: "x", Key: "not-a-key"}}
assert.Empty(t, k.JKT())
}
8 changes: 8 additions & 0 deletions dsig/key_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -139,3 +139,11 @@ func TestPrivateKeySignAndVerify(t *testing.T) {
assert.Equal(t, "hello world", str)
})
}

func TestKeyJKT(t *testing.T) {
k := dsig.NewES256Key()
jkt := k.JKT()
assert.Len(t, jkt, 43, "base64url SHA-256 without padding")
assert.Equal(t, jkt, k.Public().JKT())
assert.NotEqual(t, jkt, dsig.NewES256Key().JKT())
}
39 changes: 31 additions & 8 deletions head/header.go
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,9 @@ func (h *Header) Link(category, key cbc.Key) *Link {
// address of the participant that performed identity verification
// (KYC/KYB) of the party; it is asserted by a registration
// authority on its countersignature and is confirmed by the named
// verifier's own countersignature on the same envelope. Header
// verifier's own countersignature for the same subject. Confirmation
// (optional, set via head.WithConfirmation) is the RFC 7800 `cnf`
// claim binding the signature's statement to the subject's key. Header
// stamps, links, tags, meta, notes and the (unsigned, intent-level)
// From/To fields can still be modified after signing.
type SigningPayload struct {
Expand All @@ -185,6 +187,14 @@ type SigningPayload struct {
IssuedAt int64 `json:"iat,omitempty"`
ExpiresAt int64 `json:"exp,omitempty"`
Verifier string `json:"verifier,omitempty"`

Confirmation *Confirmation `json:"cnf,omitempty"`
}

// Confirmation is an RFC 7800 confirmation claim, identifying a key by
// its RFC 7638 SHA-256 JWK thumbprint.
type Confirmation struct {
JKT string `json:"jkt"`
}

// SignOption configures a call to Header.Sign / Envelope.Sign.
Expand All @@ -195,6 +205,7 @@ type signOptions struct {
aud string
exp int64
verifier string
jkt string
signer []dsig.SignerOption
}

Expand Down Expand Up @@ -230,22 +241,34 @@ func WithExpiration(t time.Time) SignOption {
return func(o *signOptions) { o.exp = t.UTC().Unix() }
}

// WithConfirmation sets the RFC 7800 `cnf` claim in the signed
// payload to the given RFC 7638 key thumbprint, base64url-encoded
// without padding as returned by dsig.PublicKey's JKT, binding the
// signature to the holder of that key.
func WithConfirmation(jkt string) SignOption {
return func(o *signOptions) { o.jkt = jkt }
}

// WithSignerOption forwards a low-level dsig.SignerOption (e.g.
// dsig.WithJKU) through to the underlying JWS signer.
func WithSignerOption(opts ...dsig.SignerOption) SignOption {
return func(o *signOptions) { o.signer = append(o.signer, opts...) }
}

func (h *Header) payload(iss, aud string, iat, exp int64, verifier string) *SigningPayload {
return &SigningPayload{
func (h *Header) payload(so *signOptions, iat int64) *SigningPayload {
p := &SigningPayload{
UUID: h.UUID,
Digest: h.Digest,
Iss: iss,
Aud: aud,
Iss: so.iss,
Aud: so.aud,
IssuedAt: iat,
ExpiresAt: exp,
Verifier: verifier,
ExpiresAt: so.exp,
Verifier: so.verifier,
}
if so.jkt != "" {
p.Confirmation = &Confirmation{JKT: so.jkt}
}
return p
}

// Sign creates a JWS signature over the header's document identity
Expand All @@ -262,7 +285,7 @@ func (h *Header) Sign(key *dsig.PrivateKey, opts ...SignOption) (*dsig.Signature
opt(so)
}
iat := time.Now().UTC().Unix()
return dsig.NewSignature(key, h.payload(so.iss, so.aud, iat, so.exp, so.verifier), so.signer...)
return dsig.NewSignature(key, h.payload(so, iat), so.signer...)
}

// Verify checks that the signature covers this header's document
Expand Down
22 changes: 22 additions & 0 deletions head/header_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -351,6 +351,28 @@ func TestHeaderSignWithVerifier(t *testing.T) {
assert.Equal(t, "authority.example", p.Iss)
}

func TestHeaderSignWithConfirmation(t *testing.T) {
priv := dsig.NewES256Key()
h := head.NewHeader()
h.UUID = uuid.V7()
h.Digest = dsig.NewSHA256Digest([]byte(`{"x":1}`))

sig, err := h.Sign(priv, head.WithIssuer("authority.example"))
require.NoError(t, err)
p, err := head.SignedPayload(sig)
require.NoError(t, err)
assert.Nil(t, p.Confirmation, "no cnf by default")

sig, err = h.Sign(priv,
head.WithIssuer("authority.example"),
head.WithConfirmation("thumb"))
require.NoError(t, err)
p, err = head.SignedPayload(sig)
require.NoError(t, err)
require.NotNil(t, p.Confirmation)
assert.Equal(t, "thumb", p.Confirmation.JKT)
}

func TestHeaderSignWithExpiration(t *testing.T) {
priv := dsig.NewES256Key()
h := head.NewHeader()
Expand Down
Loading
Loading