From 226380d0d8b74c46df5d4666ed92836c388a5465 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Thu, 29 Oct 2026 11:03:20 +0100 Subject: [PATCH 01/33] api updated and documented --- accept_signature_builder.go | 77 ++++- accept_signature_builder_test.go | 56 ++-- asymmetric.go | 42 +-- asymmetric_test.go | 39 +-- doc.go | 19 ++ httpsig.go | 249 +++++++++++--- message.go | 57 +++- mock_key_resolver_test.go | 38 +-- nonce.go | 24 +- signature_input.go | 108 +++--- signer.go | 70 +++- signer_test.go | 39 ++- symmetric.go | 6 +- symmetric_test.go | 7 +- verifier.go | 206 +++++++++--- verifier_test.go | 544 +++++++++++++++++++++++++++---- 16 files changed, 1204 insertions(+), 377 deletions(-) create mode 100644 doc.go diff --git a/accept_signature_builder.go b/accept_signature_builder.go index 2028032..0a28c39 100644 --- a/accept_signature_builder.go +++ b/accept_signature_builder.go @@ -8,18 +8,34 @@ import ( "github.com/dunglas/httpsfv" ) +// AcceptSignatureOption configures the Accept-Signature request produced by +// NewAcceptSignature and AcceptSignatureBuilder.Build. type AcceptSignatureOption func(*AcceptSignatureBuilder) error -func WithExpectedKey(key Key) AcceptSignatureOption { +// WithExpectedSignatureAlgorithm requests that the peer use alg when signing. +// It adds the alg parameter to Accept-Signature. +func WithExpectedSignatureAlgorithm(alg SignatureAlgorithm) AcceptSignatureOption { return func(asb *AcceptSignatureBuilder) error { - asb.keyID = key.KeyID - asb.keyAlgorithm = key.Algorithm + asb.signatureAlgorithm = alg return nil } } +// WithExpectedKeyID requests keyID as the keyid signature parameter in the +// peer's response. An empty ID is omitted by the generated header. +func WithExpectedKeyID(keyID string) AcceptSignatureOption { + return func(asb *AcceptSignatureBuilder) error { + asb.keyID = keyID + + return nil + } +} + +// WithExpectedNonce supplies the nonce source for Accept-Signature. +// If ng is nil, the default random nonce source remains in use. func WithExpectedNonce(ng NonceGetter) AcceptSignatureOption { + // TODO: What can we do for profiles which make use of nonces but in a different parameter return func(asb *AcceptSignatureBuilder) error { if ng != nil { asb.nonceGetter = ng @@ -29,6 +45,9 @@ func WithExpectedNonce(ng NonceGetter) AcceptSignatureOption { } } +// WithExpectedLabel sets the dictionary label for Accept-Signature. +// An empty label is ignored. The label is a technical reference, not an +// authenticated identifier, and may be changed by intermediaries. func WithExpectedLabel(label string) AcceptSignatureOption { return func(asb *AcceptSignatureBuilder) error { if len(label) != 0 { @@ -39,6 +58,9 @@ func WithExpectedLabel(label string) AcceptSignatureOption { } } +// WithExpectedComponents requests a signature covering the listed HTTP +// fields and derived components. If content-digest is among them, Build also +// adds Want-Content-Digest according to the configured preferences. func WithExpectedComponents(identifiers ...string) AcceptSignatureOption { return func(asb *AcceptSignatureBuilder) error { identifiers, err := toComponentIdentifiers(identifiers) @@ -52,6 +74,9 @@ func WithExpectedComponents(identifiers ...string) AcceptSignatureOption { } } +// WithContentDigestAlgorithmPreferences sets the preferred digest algorithms +// for Want-Content-Digest when a covered content-digest component is requested. +// Supplying no preferences leaves the defaults unchanged. func WithContentDigestAlgorithmPreferences(prefs ...AlgorithmPreference) AcceptSignatureOption { return func(asb *AcceptSignatureBuilder) error { if len(prefs) == 0 { @@ -74,6 +99,8 @@ func WithContentDigestAlgorithmPreferences(prefs ...AlgorithmPreference) AcceptS } } +// WithExpectedTag requests an application-defined tag on the signature. +// An empty tag is omitted from the generated Accept-Signature field. func WithExpectedTag(tag string) AcceptSignatureOption { return func(asb *AcceptSignatureBuilder) error { asb.tag = tag @@ -82,6 +109,8 @@ func WithExpectedTag(tag string) AcceptSignatureOption { } } +// WithExpectedCreatedTimestamp requests that a signature contain created. +// The request is enabled by default; false removes the requirement. func WithExpectedCreatedTimestamp(flag bool) AcceptSignatureOption { return func(asb *AcceptSignatureBuilder) error { asb.addCreatedTS = flag @@ -90,6 +119,8 @@ func WithExpectedCreatedTimestamp(flag bool) AcceptSignatureOption { } } +// WithExpectedExpiresTimestamp requests that a signature contain expires. +// The request is enabled by default; false removes the requirement. func WithExpectedExpiresTimestamp(flag bool) AcceptSignatureOption { return func(asb *AcceptSignatureBuilder) error { asb.addExpiresTS = flag @@ -98,28 +129,40 @@ func WithExpectedExpiresTimestamp(flag bool) AcceptSignatureOption { } } +// AlgorithmPreference associates a Content-Digest algorithm with a numeric +// preference value for the Want-Content-Digest header. type AlgorithmPreference struct { - Algorithm DigestAlgorithm + // Algorithm is the desired digest algorithm. + Algorithm DigestAlgorithm + // Preference is the preference value serialized alongside the algorithm. Preference int } +// String formats the preference as "algorithm=preference". func (p AlgorithmPreference) String() string { return fmt.Sprintf("%s=%d", p.Algorithm, p.Preference) } +// AcceptSignatureBuilder constructs an Accept-Signature request from the +// configured parameters and component requirements. Use NewAcceptSignature +// to create a builder with defaults, then call Build to add headers. type AcceptSignatureBuilder struct { - keyAlgorithm SignatureAlgorithm - keyID string - nonceGetter NonceGetter - label string - identifiers []*componentIdentifier - cdAlgPrefs []string - tag string - addCreatedTS bool - addExpiresTS bool - wantContentDigest bool + signatureAlgorithm SignatureAlgorithm + keyID string + nonceGetter NonceGetter + label string + identifiers []*componentIdentifier + cdAlgPrefs []string + tag string + addCreatedTS bool + addExpiresTS bool + wantContentDigest bool } +// NewAcceptSignature creates an AcceptSignatureBuilder for requesting a +// signature from a peer. By default, it uses label "sig", requests created and +// expires parameters, and generates a random nonce. If Content-Digest is requested, +// the default digest preferences are SHA-256 and SHA-512. func NewAcceptSignature(opts ...AcceptSignatureOption) (*AcceptSignatureBuilder, error) { asb := &AcceptSignatureBuilder{ addCreatedTS: true, @@ -141,6 +184,10 @@ func NewAcceptSignature(opts ...AcceptSignatureOption) (*AcceptSignatureBuilder, return asb, nil } +// Build appends an Accept-Signature header to header using the configured +// signature requirements. If Content-Digest is requested, it also appends +// Want-Content-Digest preferences. The caller must provide a writable, non-nil +// http.Header. func (asb *AcceptSignatureBuilder) Build(ctx context.Context, header http.Header) error { nonce, err := asb.nonceGetter.GetNonce(ctx) if err != nil { @@ -153,7 +200,7 @@ func (asb *AcceptSignatureBuilder) Build(ctx context.Context, header http.Header asb.tag, nonce, asb.keyID, - asb.keyAlgorithm, + asb.signatureAlgorithm, asb.identifiers) dict := httpsfv.NewDictionary() diff --git a/accept_signature_builder_test.go b/accept_signature_builder_test.go index 5f14625..73a6105 100644 --- a/accept_signature_builder_test.go +++ b/accept_signature_builder_test.go @@ -10,28 +10,38 @@ import ( "github.com/stretchr/testify/require" ) -func TestWithExpectedKey(t *testing.T) { +func TestWithExpectedSignatureAlgorithm(t *testing.T) { t.Parallel() - for _, tc := range []struct { - uc string - key Key - expKeyID string - expKeyAlg SignatureAlgorithm - }{ - {uc: "no actual data provided"}, - {uc: "only KeyID provided", key: Key{KeyID: "test"}, expKeyID: "test"}, - {uc: "only KeyAlg provided", key: Key{Algorithm: RsaPssSha512}, expKeyAlg: RsaPssSha512}, - {uc: "KeyID and KeyAlg provided", key: Key{KeyID: "foo", Algorithm: EcdsaP256Sha256}, expKeyID: "foo", expKeyAlg: EcdsaP256Sha256}, + for uc, alg := range map[string]SignatureAlgorithm{ + "no actual data provided": SignatureAlgorithm(""), + "KeyAlg provided": RsaPssSha512, } { - t.Run(tc.uc, func(t *testing.T) { + t.Run(uc, func(t *testing.T) { + asb := &AcceptSignatureBuilder{} + + err := WithExpectedSignatureAlgorithm(alg)(asb) + + require.NoError(t, err) + assert.Equal(t, alg, asb.signatureAlgorithm) + }) + } +} + +func TestWithExpectedKeyID(t *testing.T) { + t.Parallel() + + for uc, keyID := range map[string]string{ + "no actual data provided": "", + "KeyAlg provided": "test", + } { + t.Run(uc, func(t *testing.T) { asb := &AcceptSignatureBuilder{} - err := WithExpectedKey(tc.key)(asb) + err := WithExpectedKeyID(keyID)(asb) require.NoError(t, err) - assert.Equal(t, tc.expKeyID, asb.keyID) - assert.Equal(t, tc.expKeyAlg, asb.keyAlgorithm) + assert.Equal(t, keyID, asb.keyID) }) } } @@ -255,7 +265,7 @@ func TestNewAcceptedSignature(t *testing.T) { assert.Empty(t, asb.identifiers) assert.Empty(t, asb.tag) assert.Empty(t, asb.keyID) - assert.Empty(t, asb.keyAlgorithm) + assert.Empty(t, asb.signatureAlgorithm) assert.True(t, asb.addCreatedTS) assert.True(t, asb.addExpiresTS) assert.Equal(t, nonceGetter{}, asb.nonceGetter) @@ -269,7 +279,8 @@ func TestNewAcceptedSignature(t *testing.T) { { uc: "all possible options provided", opts: []AcceptSignatureOption{ - WithExpectedKey(Key{KeyID: "test", Algorithm: EcdsaP256Sha256}), + WithExpectedSignatureAlgorithm(EcdsaP256Sha256), + WithExpectedKeyID("test"), WithExpectedNonce(&NonceGetterMock{}), WithExpectedLabel("foo"), WithExpectedComponents("@status", "content-digest;req"), @@ -288,7 +299,7 @@ func TestNewAcceptedSignature(t *testing.T) { assert.Equal(t, "content-digest", asb.identifiers[1].Value) assert.Equal(t, "bar", asb.tag) assert.Equal(t, "test", asb.keyID) - assert.Equal(t, EcdsaP256Sha256, asb.keyAlgorithm) + assert.Equal(t, EcdsaP256Sha256, asb.signatureAlgorithm) assert.False(t, asb.addCreatedTS) assert.False(t, asb.addExpiresTS) assert.Equal(t, &NonceGetterMock{}, asb.nonceGetter) @@ -345,7 +356,8 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { { uc: "Accept-Signature only is added", opts: []AcceptSignatureOption{ - WithExpectedKey(Key{KeyID: "test", Algorithm: EcdsaP256Sha256}), + WithExpectedSignatureAlgorithm(EcdsaP256Sha256), + WithExpectedKeyID("test"), WithExpectedComponents("@status", "x-foo-bar;req", "@method"), WithExpectedLabel("foo"), WithExpectedTag("bar"), @@ -366,7 +378,8 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { { uc: "Accept-Signature and Want-Content-Digest headers are added with default algorithms", opts: []AcceptSignatureOption{ - WithExpectedKey(Key{KeyID: "test", Algorithm: EcdsaP256Sha256}), + WithExpectedSignatureAlgorithm(EcdsaP256Sha256), + WithExpectedKeyID("test"), WithExpectedComponents("@status", "content-digest", "@method"), WithExpectedLabel("foo"), WithExpectedTag("bar"), @@ -389,7 +402,8 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { { uc: "Accept-Signature and Want-Content-Digest headers are added with supplied algorithms", opts: []AcceptSignatureOption{ - WithExpectedKey(Key{KeyID: "test", Algorithm: EcdsaP256Sha256}), + WithExpectedSignatureAlgorithm(EcdsaP256Sha256), + WithExpectedKeyID("test"), WithExpectedComponents("@status", "content-digest", "@method"), WithExpectedLabel("foo"), WithExpectedTag("bar"), diff --git a/asymmetric.go b/asymmetric.go index c6aa4d6..9dc8925 100644 --- a/asymmetric.go +++ b/asymmetric.go @@ -11,7 +11,7 @@ import ( "slices" ) -func newECDSASigner(privateKey *ecdsa.PrivateKey, kid string, alg SignatureAlgorithm) (*ecdsaSigner, error) { +func newECDSASigner(privateKey *ecdsa.PrivateKey, alg SignatureAlgorithm) (*ecdsaSigner, error) { var ( expectedBitSize int hash crypto.Hash @@ -44,7 +44,6 @@ func newECDSASigner(privateKey *ecdsa.PrivateKey, kid string, alg SignatureAlgor return &ecdsaSigner{ alg: alg, privateKey: privateKey, - kid: kid, hash: hash, }, nil } @@ -52,12 +51,9 @@ func newECDSASigner(privateKey *ecdsa.PrivateKey, kid string, alg SignatureAlgor type ecdsaSigner struct { alg SignatureAlgorithm privateKey *ecdsa.PrivateKey - kid string hash crypto.Hash } -func (ecs *ecdsaSigner) keyID() string { return ecs.kid } - func (ecs *ecdsaSigner) algorithm() SignatureAlgorithm { return ecs.alg } func (ecs *ecdsaSigner) signPayload(payload []byte) ([]byte, error) { @@ -92,7 +88,7 @@ func (ecs *ecdsaSigner) signPayload(payload []byte) ([]byte, error) { return slices.Concat(rBytesPadded, sBytesPadded), nil } -func newRSASigner(privateKey *rsa.PrivateKey, kid string, alg SignatureAlgorithm) (*rsaSigner, error) { +func newRSASigner(privateKey *rsa.PrivateKey, alg SignatureAlgorithm) (*rsaSigner, error) { var hash crypto.Hash switch alg { @@ -114,19 +110,15 @@ func newRSASigner(privateKey *rsa.PrivateKey, kid string, alg SignatureAlgorithm alg: alg, hash: hash, privateKey: privateKey, - kid: kid, }, nil } type rsaSigner struct { alg SignatureAlgorithm privateKey *rsa.PrivateKey - kid string hash crypto.Hash } -func (s *rsaSigner) keyID() string { return s.kid } - func (s *rsaSigner) algorithm() SignatureAlgorithm { return s.alg } func (s *rsaSigner) signPayload(payload []byte) ([]byte, error) { @@ -158,7 +150,7 @@ func (s *rsaSigner) signPayload(payload []byte) ([]byte, error) { return out, nil } -func newEd25519Signer(privateKey ed25519.PrivateKey, kid string, alg SignatureAlgorithm) (*ed25519Signer, error) { +func newEd25519Signer(privateKey ed25519.PrivateKey, alg SignatureAlgorithm) (*ed25519Signer, error) { if alg != Ed25519 { return nil, fmt.Errorf("%w: %s", ErrUnsupportedAlgorithm, alg) } @@ -174,25 +166,21 @@ func newEd25519Signer(privateKey ed25519.PrivateKey, kid string, alg SignatureAl return &ed25519Signer{ alg: alg, privateKey: privateKey, - kid: kid, }, nil } type ed25519Signer struct { alg SignatureAlgorithm privateKey ed25519.PrivateKey - kid string } -func (s *ed25519Signer) keyID() string { return s.kid } - func (s *ed25519Signer) algorithm() SignatureAlgorithm { return s.alg } func (s *ed25519Signer) signPayload(payload []byte) ([]byte, error) { return ed25519.Sign(s.privateKey, payload), nil } -func newECDSAVerifier(publicKey *ecdsa.PublicKey, keyID string, alg SignatureAlgorithm) (*ecdsaVerifier, error) { +func newECDSAVerifier(publicKey *ecdsa.PublicKey, alg SignatureAlgorithm) (*ecdsaVerifier, error) { var ( expectedBitSize int hash crypto.Hash @@ -225,7 +213,6 @@ func newECDSAVerifier(publicKey *ecdsa.PublicKey, keyID string, alg SignatureAlg return &ecdsaVerifier{ alg: alg, publicKey: publicKey, - kid: keyID, hash: hash, }, nil } @@ -233,14 +220,9 @@ func newECDSAVerifier(publicKey *ecdsa.PublicKey, keyID string, alg SignatureAlg type ecdsaVerifier struct { publicKey *ecdsa.PublicKey alg SignatureAlgorithm - kid string hash crypto.Hash } -func (v *ecdsaVerifier) keyID() string { return v.kid } - -func (v *ecdsaVerifier) algorithm() SignatureAlgorithm { return v.alg } - func (v *ecdsaVerifier) verifyPayload(payload []byte, signature []byte) error { hasher := v.hash.New() // According to documentation, Write() on hash never fails @@ -269,7 +251,7 @@ func (v *ecdsaVerifier) verifyPayload(payload []byte, signature []byte) error { return nil } -func newRSAVerifier(publicKey *rsa.PublicKey, kid string, alg SignatureAlgorithm) (*rsaVerifier, error) { +func newRSAVerifier(publicKey *rsa.PublicKey, alg SignatureAlgorithm) (*rsaVerifier, error) { var hash crypto.Hash switch alg { @@ -291,21 +273,15 @@ func newRSAVerifier(publicKey *rsa.PublicKey, kid string, alg SignatureAlgorithm alg: alg, hash: hash, publicKey: publicKey, - kid: kid, }, nil } type rsaVerifier struct { publicKey *rsa.PublicKey alg SignatureAlgorithm - kid string hash crypto.Hash } -func (v *rsaVerifier) keyID() string { return v.kid } - -func (v *rsaVerifier) algorithm() SignatureAlgorithm { return v.alg } - func (v *rsaVerifier) verifyPayload(payload []byte, signature []byte) error { hasher := v.hash.New() @@ -329,7 +305,7 @@ func (v *rsaVerifier) verifyPayload(payload []byte, signature []byte) error { return nil } -func newEd25519Verifier(publicKey ed25519.PublicKey, keyID string, alg SignatureAlgorithm) (*ed25519Verifier, error) { +func newEd25519Verifier(publicKey ed25519.PublicKey, alg SignatureAlgorithm) (*ed25519Verifier, error) { if alg != Ed25519 { return nil, fmt.Errorf("%w: %s", ErrUnsupportedAlgorithm, alg) } @@ -345,20 +321,14 @@ func newEd25519Verifier(publicKey ed25519.PublicKey, keyID string, alg Signature return &ed25519Verifier{ publicKey: publicKey, alg: alg, - kid: keyID, }, nil } type ed25519Verifier struct { alg SignatureAlgorithm publicKey ed25519.PublicKey - kid string } -func (v *ed25519Verifier) keyID() string { return v.kid } - -func (v *ed25519Verifier) algorithm() SignatureAlgorithm { return v.alg } - func (v *ed25519Verifier) verifyPayload(payload []byte, signature []byte) error { if ok := ed25519.Verify(v.publicKey, payload, signature); !ok { return ErrInvalidSignature diff --git a/asymmetric_test.go b/asymmetric_test.go index b80a28e..6cbdb69 100644 --- a/asymmetric_test.go +++ b/asymmetric_test.go @@ -39,7 +39,7 @@ func TestNewECDSASigner(t *testing.T) { {uc: string(EcdsaP521Sha512), alg: EcdsaP521Sha512, key: pkp521}, } { t.Run(tc.uc, func(t *testing.T) { - sig, err := newECDSASigner(tc.key, "test", tc.alg) + sig, err := newECDSASigner(tc.key, tc.alg) if tc.err != nil { require.Error(t, err) @@ -47,7 +47,6 @@ func TestNewECDSASigner(t *testing.T) { } else { require.NoError(t, err) require.NotNil(t, sig) - assert.Equal(t, "test", sig.keyID()) assert.Equal(t, tc.key, sig.privateKey) assert.Equal(t, tc.alg, sig.algorithm()) } @@ -78,7 +77,7 @@ func TestECDSASignerSignPayload(t *testing.T) { {alg: EcdsaP521Sha512, key: pkp521}, } { t.Run(string(tc.alg), func(t *testing.T) { - sig, err := newECDSASigner(tc.key, "test", tc.alg) + sig, err := newECDSASigner(tc.key, tc.alg) require.NoError(t, err) res, err := sig.signPayload(message) @@ -133,7 +132,7 @@ func TestNewRSASigner(t *testing.T) { {uc: string(RsaPssSha512), alg: RsaPssSha512, key: pk4096}, } { t.Run(tc.uc, func(t *testing.T) { - sig, err := newRSASigner(tc.key, "test", tc.alg) + sig, err := newRSASigner(tc.key, tc.alg) if tc.err != nil { require.Error(t, err) @@ -141,7 +140,6 @@ func TestNewRSASigner(t *testing.T) { } else { require.NoError(t, err) require.NotNil(t, sig) - assert.Equal(t, "test", sig.keyID()) assert.Equal(t, tc.key, sig.privateKey) assert.Equal(t, tc.alg, sig.algorithm()) } @@ -177,7 +175,7 @@ func TestRSASignerSignPayload(t *testing.T) { {uc: "4096 key with RsaPssSha512", key: pk4096, alg: RsaPssSha512}, } { t.Run(tc.uc, func(t *testing.T) { - sig, err := newRSASigner(tc.key, "test", tc.alg) + sig, err := newRSASigner(tc.key, tc.alg) require.NoError(t, err) res, err := sig.signPayload(message) @@ -227,7 +225,7 @@ func TestNewEd25519Signer(t *testing.T) { {uc: "success", alg: Ed25519, key: privKey}, } { t.Run(tc.uc, func(t *testing.T) { - sig, err := newEd25519Signer(tc.key, "test", tc.alg) + sig, err := newEd25519Signer(tc.key, tc.alg) if tc.err != nil { require.Error(t, err) @@ -235,7 +233,6 @@ func TestNewEd25519Signer(t *testing.T) { } else { require.NoError(t, err) require.NotNil(t, sig) - assert.Equal(t, "test", sig.keyID()) assert.Equal(t, tc.key, sig.privateKey) assert.Equal(t, tc.alg, sig.algorithm()) } @@ -251,7 +248,7 @@ func TestEd25519SignerSignPayload(t *testing.T) { pubKey, privKey, err := ed25519.GenerateKey(rand.Reader) require.NoError(t, err) - sig, err := newEd25519Signer(privKey, "test", Ed25519) + sig, err := newEd25519Signer(privKey, Ed25519) require.NoError(t, err) res, err := sig.signPayload(message) @@ -287,7 +284,7 @@ func TestNewECDSAVerifier(t *testing.T) { {uc: string(EcdsaP521Sha512), alg: EcdsaP521Sha512, key: &pkp521.PublicKey}, } { t.Run(tc.uc, func(t *testing.T) { - sig, err := newECDSAVerifier(tc.key, "test", tc.alg) + sig, err := newECDSAVerifier(tc.key, tc.alg) if tc.err != nil { require.Error(t, err) @@ -295,9 +292,7 @@ func TestNewECDSAVerifier(t *testing.T) { } else { require.NoError(t, err) require.NotNil(t, sig) - assert.Equal(t, "test", sig.keyID()) assert.Equal(t, tc.key, sig.publicKey) - assert.Equal(t, tc.alg, sig.algorithm()) } }) } @@ -391,14 +386,14 @@ func TestECDSAverifierVerifyPayload(t *testing.T) { } } - sig, err := newECDSASigner(tc.key, "test", tc.alg) + sig, err := newECDSASigner(tc.key, tc.alg) require.NoError(t, err) res, err := sig.signPayload(message) require.NoError(t, err) require.NotEmpty(t, res) - ver, err := newECDSAVerifier(&tc.key.PublicKey, "test", tc.alg) + ver, err := newECDSAVerifier(&tc.key.PublicKey, tc.alg) require.NoError(t, err) err = ver.verifyPayload(mutateMessage(t, message), mutateSignature(t, res)) @@ -443,7 +438,7 @@ func TestNewRSAVerifier(t *testing.T) { {uc: string(RsaPssSha512), alg: RsaPssSha512, key: &pk4096.PublicKey}, } { t.Run(tc.uc, func(t *testing.T) { - sig, err := newRSAVerifier(tc.key, "test", tc.alg) + sig, err := newRSAVerifier(tc.key, tc.alg) if tc.err != nil { require.Error(t, err) @@ -451,9 +446,7 @@ func TestNewRSAVerifier(t *testing.T) { } else { require.NoError(t, err) require.NotNil(t, sig) - assert.Equal(t, "test", sig.keyID()) assert.Equal(t, tc.key, sig.publicKey) - assert.Equal(t, tc.alg, sig.algorithm()) } }) } @@ -559,14 +552,14 @@ func TestRSAVerifierVerifyPayload(t *testing.T) { } } - sig, err := newRSASigner(tc.key, "test", tc.alg) + sig, err := newRSASigner(tc.key, tc.alg) require.NoError(t, err) res, err := sig.signPayload(message) require.NoError(t, err) require.NotEmpty(t, res) - ver, err := newRSAVerifier(&tc.key.PublicKey, "test", tc.alg) + ver, err := newRSAVerifier(&tc.key.PublicKey, tc.alg) require.NoError(t, err) err = ver.verifyPayload(mutateMessage(t, message), mutateSignature(t, res)) @@ -601,7 +594,7 @@ func TestNewEd25519Verifier(t *testing.T) { {uc: "success", alg: Ed25519, key: pubKey}, } { t.Run(tc.uc, func(t *testing.T) { - sig, err := newEd25519Verifier(tc.key, "test", tc.alg) + sig, err := newEd25519Verifier(tc.key, tc.alg) if tc.err != nil { require.Error(t, err) @@ -609,9 +602,7 @@ func TestNewEd25519Verifier(t *testing.T) { } else { require.NoError(t, err) require.NotNil(t, sig) - assert.Equal(t, "test", sig.keyID()) assert.Equal(t, tc.key, sig.publicKey) - assert.Equal(t, tc.alg, sig.algorithm()) } }) } @@ -625,13 +616,13 @@ func TestEd25519VerifierVerifyPayload(t *testing.T) { pubKey, privKey, err := ed25519.GenerateKey(rand.Reader) require.NoError(t, err) - sig, err := newEd25519Signer(privKey, "test", Ed25519) + sig, err := newEd25519Signer(privKey, Ed25519) require.NoError(t, err) res, err := sig.signPayload(message) require.NoError(t, err) - ver, err := newEd25519Verifier(pubKey, "test", sig.alg) + ver, err := newEd25519Verifier(pubKey, sig.alg) require.NoError(t, err) // valid signature diff --git a/doc.go b/doc.go new file mode 100644 index 0000000..bf52516 --- /dev/null +++ b/doc.go @@ -0,0 +1,19 @@ +// Package httpsig implements HTTP Message Signatures as specified by RFC 9421. +// It provides signing, verification, and Accept-Signature negotiation for HTTP +// requests and responses independently of a particular HTTP framework. +// +// Convert net/http messages with MessageFromRequest, MessageFromResponse, or +// MessageForResponse, then use a Signer or Verifier. Verification returns a +// VerificationResult containing the covered components, transmitted signature +// parameters, and optional key-resolution metadata for each verified signature. +// +// A KeyResolver is responsible for selecting trusted verification keys. It +// receives sender-controlled information before the cryptographic signature +// has been verified. Applications are responsible for applying profile-specific +// trust, identity, and authorization rules to the results; verifying a signature +// alone does not establish the sender's identity or permissions. +// +// Signing and digest verification may read complete message bodies. Applications +// must enforce appropriate body size limits before passing untrusted messages +// to the library. +package httpsig diff --git a/httpsig.go b/httpsig.go index d2f98c6..e8d8aef 100644 --- a/httpsig.go +++ b/httpsig.go @@ -8,38 +8,82 @@ import ( ) var ( - ErrUnsupportedKeyType = errors.New("unsupported key type/format") - ErrUnsupportedAlgorithm = errors.New("unknown/unsupported algorithm") - ErrInvalidKeySize = errors.New("invalid key size") - ErrNoKeyProvided = errors.New("no key provided") - ErrInvalidSignature = errors.New("invalid signature") - ErrVerificationFailed = errors.New("verification failed") - ErrContentDigestMismatch = errors.New("content digest mismatch") - ErrMalformedData = errors.New("malformed data") + // ErrUnsupportedKeyType indicates that the supplied key material has an unsupported Go type. + ErrUnsupportedKeyType = errors.New("unsupported key type/format") + + // ErrUnsupportedAlgorithm indicates that the requested signature or digest algorithm is unsupported. + ErrUnsupportedAlgorithm = errors.New("unknown/unsupported algorithm") + + // ErrInvalidKeySize indicates that a key has an incompatible size or curve for its algorithm. + ErrInvalidKeySize = errors.New("invalid key size") + + // ErrNoKeyProvided indicates that required key material was not supplied. + ErrNoKeyProvided = errors.New("no key provided") + + // ErrInvalidSignature indicates that cryptographic signature verification failed. + ErrInvalidSignature = errors.New("invalid signature") + + // ErrVerificationFailed indicates that verifying the selected signatures failed; it wraps the underlying error. + ErrVerificationFailed = errors.New("verification failed") + + // ErrContentDigestMismatch indicates that a covered Content-Digest does not match the message body. + ErrContentDigestMismatch = errors.New("content digest mismatch") + + // ErrMalformedData indicates malformed signature or other structured HTTP message data. + ErrMalformedData = errors.New("malformed data") + + // ErrUnsupportedComponentIdentifier indicates that a covered component identifier is unsupported. ErrUnsupportedComponentIdentifier = errors.New("unsupported component identifier") - ErrInvalidComponentIdentifier = errors.New("invalid component identifier") - ErrCanonicalization = errors.New("failed to canonicalize component") - ErrMalformedSignatureParameter = errors.New("malformed signature parameter") - ErrNoApplicableDigestFound = errors.New("no applicable digest found") - ErrVerifierCreation = errors.New("verifier creation failed") - ErrParameter = errors.New("parameter error") - ErrValidity = errors.New("validity error") - ErrMissingParameter = errors.New("missing parameter error") - ErrSignatureNegotiationError = errors.New("signature negotiation error") + + // ErrInvalidComponentIdentifier indicates malformed or invalid parameters on a component identifier. + ErrInvalidComponentIdentifier = errors.New("invalid component identifier") + + // ErrCanonicalization indicates that a covered HTTP message component could not be canonicalized. + ErrCanonicalization = errors.New("failed to canonicalize component") + + // ErrMalformedSignatureParameter indicates a signature parameter with an invalid type or value. + ErrMalformedSignatureParameter = errors.New("malformed signature parameter") + + // ErrNoApplicableDigestFound indicates that no supported digest could be checked in Content-Digest. + ErrNoApplicableDigestFound = errors.New("no applicable digest found") + + // ErrVerifierCreation indicates that the verifier configuration could not be constructed. + ErrVerifierCreation = errors.New("verifier creation failed") + + // ErrParameter indicates a failed signature parameter check or invalid option. + ErrParameter = errors.New("parameter error") + + // ErrValidity indicates that a signature failed its time validity checks. + ErrValidity = errors.New("validity error") + + // ErrMissingParameter indicates that a required signature parameter or covered component is missing. + ErrMissingParameter = errors.New("missing parameter error") + + // ErrSignatureNegotiationError indicates a failure while preparing signature negotiation. + ErrSignatureNegotiationError = errors.New("signature negotiation error") ) +// NoApplicableSignatureError indicates that a message does not contain all +// required signatures or any signature selected by the verifier. If signature +// negotiation was configured, Negotiate can add the requested headers to a +// response. It can be recognized with errors.As or errors.Is. type NoApplicableSignatureError struct { headerToAdd http.Header } +// Error returns a description of the missing applicable signature. func (e *NoApplicableSignatureError) Error() string { return "no applicable signature found" } +// Is matches another NoApplicableSignatureError for use with errors.Is. func (e *NoApplicableSignatureError) Is(err error) bool { _, ok := err.(*NoApplicableSignatureError) return ok } +// Negotiate appends any prepared Accept-Signature and related negotiation +// headers to header. If no negotiation was configured, it adds nothing. +// The caller must supply a writable, non-nil http.Header. func (e *NoApplicableSignatureError) Negotiate(header http.Header) { for name, values := range e.headerToAdd { for _, value := range values { @@ -58,64 +102,171 @@ const ( componentIdentifierContentDigest = "content-digest" ) -// SignatureAlgorithm is the signature algorithm to use. -// Available algorithms are: -// - RSASSA-PKCS1-v1_5 using SHA-256 (rsa-v1_5-sha256). -// - RSASSA-PSS using SHA-512 (rsa-pss-sha512). -// - ECDSA using curve P-256 DSS and SHA-256 (ecdsa-p256-sha256). -// - ECDSA using curve P-384 DSS and SHA-384 (ecdsa-p384-sha384). -// - EdDSA using curve edwards25519 (ed25519). -// - HMAC using SHA-256 (hmac-sha256). +// SignatureAlgorithm identifies the concrete cryptographic algorithm used +// to create or verify an HTTP message signature. The supported algorithms +// are the constants below; the selected algorithm must be compatible with +// the supplied Key.Material. type SignatureAlgorithm string const ( + // RsaPkcs1v15Sha256 selects RSA PKCS#1 v1.5 with SHA-256. RsaPkcs1v15Sha256 SignatureAlgorithm = "rsa-v1_5-sha256" + + // RsaPkcs1v15Sha384 selects RSA PKCS#1 v1.5 with SHA-384. RsaPkcs1v15Sha384 SignatureAlgorithm = "rsa-v1_5-sha384" + + // RsaPkcs1v15Sha512 selects RSA PKCS#1 v1.5 with SHA-512. RsaPkcs1v15Sha512 SignatureAlgorithm = "rsa-v1_5-sha512" - RsaPssSha256 SignatureAlgorithm = "rsa-pss-sha256" - RsaPssSha384 SignatureAlgorithm = "rsa-pss-sha384" - RsaPssSha512 SignatureAlgorithm = "rsa-pss-sha512" - EcdsaP256Sha256 SignatureAlgorithm = "ecdsa-p256-sha256" - EcdsaP384Sha384 SignatureAlgorithm = "ecdsa-p384-sha384" - EcdsaP521Sha512 SignatureAlgorithm = "ecdsa-p521-sha512" - Ed25519 SignatureAlgorithm = "ed25519" - HmacSha256 SignatureAlgorithm = "hmac-sha256" - HmacSha384 SignatureAlgorithm = "hmac-sha384" - HmacSha512 SignatureAlgorithm = "hmac-sha512" + + // RsaPssSha256 selects RSA-PSS with SHA-256. + RsaPssSha256 SignatureAlgorithm = "rsa-pss-sha256" + + // RsaPssSha384 selects RSA-PSS with SHA-384. + RsaPssSha384 SignatureAlgorithm = "rsa-pss-sha384" + + // RsaPssSha512 selects RSA-PSS with SHA-512. + RsaPssSha512 SignatureAlgorithm = "rsa-pss-sha512" + + // EcdsaP256Sha256 selects ECDSA using P-256 and SHA-256. + EcdsaP256Sha256 SignatureAlgorithm = "ecdsa-p256-sha256" + + // EcdsaP384Sha384 selects ECDSA using P-384 and SHA-384. + EcdsaP384Sha384 SignatureAlgorithm = "ecdsa-p384-sha384" + + // EcdsaP521Sha512 selects ECDSA using P-521 and SHA-512. + EcdsaP521Sha512 SignatureAlgorithm = "ecdsa-p521-sha512" + + // Ed25519 selects Ed25519 signatures. + Ed25519 SignatureAlgorithm = "ed25519" + + // HmacSha256 selects HMAC with SHA-256. + HmacSha256 SignatureAlgorithm = "hmac-sha256" + + // HmacSha384 selects HMAC with SHA-384. + HmacSha384 SignatureAlgorithm = "hmac-sha384" + + // HmacSha512 selects HMAC with SHA-512. + HmacSha512 SignatureAlgorithm = "hmac-sha512" ) -// DigestAlgorithm is the digest algorithm to use. Available algorithms are: -// - SHA-256 (sha-256). -// - SHA-512 (sha-512). +// DigestAlgorithm identifies a hash algorithm supported for HTTP Content-Digest +// generation and verification. type DigestAlgorithm string const ( + // Sha256 selects SHA-256. Sha256 DigestAlgorithm = "sha-256" + + // Sha512 selects SHA-512. Sha512 DigestAlgorithm = "sha-512" ) +// SignatureParameter names one of the standard RFC 9421 signature parameters. +// Additional, profile-specific parameter names can appear in SignatureParameters. type SignatureParameter string const ( - KeyID SignatureParameter = "keyid" - Alg SignatureParameter = "alg" + // KeyID names the keyid signature parameter. + KeyID SignatureParameter = "keyid" + + // Alg names the alg signature parameter. + Alg SignatureParameter = "alg" + + // Created names the created timestamp parameter. Created SignatureParameter = "created" + + // Expires names the expires timestamp parameter. Expires SignatureParameter = "expires" - Nonce SignatureParameter = "nonce" - Tag SignatureParameter = "tag" + + // Nonce names the nonce signature parameter. + Nonce SignatureParameter = "nonce" + + // Tag names the tag signature parameter. + Tag SignatureParameter = "tag" ) -// Key is the key to use for signing or verifying. +// SignatureParameters contains all signature parameters transmitted in a +// Signature-Input entry, including profile-specific extensions. Keys are the +// parameter names; values are decoded Structured Fields bare items (for +// example string, Token, int64, float64, bool, []byte, or time.Time). +// Display Strings are exposed as ordinary strings. +type SignatureParameters map[string]any + +// Token represents a Structured Fields token. It is distinct from string so +// applications can distinguish token values from quoted Structured Fields +// strings when validating profile-specific signature parameters. +type Token string + +// Key combines cryptographic key material with the concrete signature +// algorithm to use. Signing requires private or symmetric key material; +// verification requires public or symmetric key material. type Key struct { - // KeyID is the identifier of the key. - KeyID string - // Algorithm is the cryptographic algorithm to use with the key. + // Algorithm is the signature algorithm to use with Material. + // It must be compatible with the supplied key material. Algorithm SignatureAlgorithm - // Key is the actual key material, like public, private or a secret key. - Key any + + // Material is the private, public, or symmetric key material used by the + // chosen algorithm. The currently supported implementations accept the + // corresponding Go crypto key types or []byte for HMAC. + Material any +} + +// ResolveKey makes a statically configured Key usable as a KeyResolver. +func (k Key) ResolveKey(_ context.Context, _ SignatureInfo) (KeyInfo, error) { + return KeyInfo{Key: k}, nil +} + +// KeyInfo is returned by a KeyResolver and contains the accepted verification +// key and optional application-defined information about its resolution. +type KeyInfo struct { + // Key is the trusted key and algorithm selected for this signature. + Key Key + // Metadata is application-specific information returned alongside the key. + // It is passed through to VerifiedSignature only on successful verification. + Metadata any } -func (k Key) ResolveKey(_ context.Context, _ string) (Key, error) { return k, nil } +// SignatureInfo describes one signature being considered for verification. +// All its values are unverified and may be sender-controlled. The +// resolver implementation must treat them as untrusted input when selecting +// key material. The message and maps are shared with the verification process +// and must not be modified by the resolver (including mutable values within +// the maps). +type SignatureInfo struct { + // Label is the current Signature-Input dictionary member name. It is not + // signed and can be changed by intermediaries; it is only a technical + // reference. + Label string + + // Message is the HTTP message being verified. Not all of its fields are + // necessarily covered by the signature, and it must not be modified. + Message *Message + + // Components maps covered component identifiers to the canonicalized + // values used to construct the signature base. It excludes the synthetic + // @signature-params component. Identifier parameters are retained in keys. + Components map[string]string + + // Parameters contains the transmitted, decoded signature parameters. + Parameters SignatureParameters +} + +// KeyResolver resolves a trusted verification key for a specific HTTP message +// signature. The resolver implementation is responsible for establishing trust +// in the key // material and any required binding to a key source or credential. +// Returning KeyInfo without an error indicates that the key is acceptable for this +// verification attempt. +// +// ResolveKey is called before cryptographic verification. SignatureInfo and +// its Message contain unverified, potentially sender-controlled data. A +// resolver must not treat this data as an authenticated identity or use it +// for unrestricted remote lookups. It must not mutate SignatureInfo.Message, +// Components, Parameters, or their mutable contents: these are shared with +// the verification process and, on success, with VerifiedSignature. +type KeyResolver interface { + // ResolveKey returns the trusted key and optional metadata for info. + ResolveKey(ctx context.Context, info SignatureInfo) (KeyInfo, error) +} // nolint: gochecknoglobals var supportedAlgs = map[DigestAlgorithm]crypto.Hash{ diff --git a/message.go b/message.go index 72a9111..1b77352 100644 --- a/message.go +++ b/message.go @@ -11,6 +11,10 @@ import ( "github.com/dunglas/httpsfv" ) +// MessageFromRequest creates a Message for signing or verifying an HTTP +// request. Request headers are cloned. If the body must be read and req.GetBody +// is unavailable, the original body is buffered and replaced so it remains +// readable. Callers must enforce size limits for untrusted request bodies. func MessageFromRequest(req *http.Request) *Message { var ( getBody func() (io.ReadCloser, error) @@ -52,6 +56,11 @@ func MessageFromRequest(req *http.Request) *Message { } } +// MessageFromResponse creates a Message from a received HTTP response and +// its associated request. Response and request headers are cloned. The +// response body may be buffered and restored when a covered component needs +// it. The request body is available for ;req components only when the +// associated request has a GetBody function. func MessageFromResponse(rw *http.Response) *Message { var bodySnapshot []byte @@ -93,6 +102,10 @@ func MessageFromResponse(rw *http.Response) *Message { } } +// MessageForResponse creates a Message for signing a response to req. +// It clones the response and request headers and makes the supplied body +// available for Content-Digest and other covered components. The request +// body may be buffered and restored when a ;req component requires it. func MessageForResponse(req *http.Request, respHeader http.Header, body []byte, respCode int) *Message { var bodySnapshot []byte @@ -126,19 +139,41 @@ func MessageForResponse(req *http.Request, respHeader http.Header, body []byte, } } -// Message is a representation of an HTTP request or response, containing the values -// needed to construct or validate a signature. +// Message represents the HTTP request or response data needed to construct +// and verify an HTTP message signature. For a response, request-related +// fields supply data used by component identifiers with the ;req parameter. +// Not every field is necessarily covered by the signature. type Message struct { - Context context.Context //nolint: containedctx - Method string - Authority string - URL *url.URL - Header http.Header - Body func() (io.ReadCloser, error) + // Context is used for key resolution, nonce generation, and nonce checks. + Context context.Context //nolint: containedctx + + // Method is the associated HTTP request method. + Method string + + // Authority is the authority (host and optional port) of the request. + Authority string + + // URL is the associated HTTP request URL. + URL *url.URL + + // Header contains the headers of the request or response being processed. + // The signer may update this map with signatures and a Content-Digest. + Header http.Header + + // Body opens the body of the request or response being processed. + Body func() (io.ReadCloser, error) + + // RequestHeader contains the associated request headers for a response. RequestHeader http.Header - RequestBody func() (io.ReadCloser, error) - StatusCode int - IsRequest bool + + // RequestBody opens the associated request body for response ;req components. + RequestBody func() (io.ReadCloser, error) + + // StatusCode is the HTTP response status code (unused for requests). + StatusCode int + + // IsRequest distinguishes requests from responses for canonicalization. + IsRequest bool } func (m *Message) addSignature(label string, signature []byte, signatureInput httpsfv.InnerList) (http.Header, error) { diff --git a/mock_key_resolver_test.go b/mock_key_resolver_test.go index 70503d3..efbba93 100644 --- a/mock_key_resolver_test.go +++ b/mock_key_resolver_test.go @@ -47,25 +47,25 @@ func (_m *KeyResolverMock) EXPECT() *KeyResolverMock_Expecter { } // ResolveKey provides a mock function for the type KeyResolverMock -func (_mock *KeyResolverMock) ResolveKey(ctx context.Context, keyID string) (Key, error) { - ret := _mock.Called(ctx, keyID) +func (_mock *KeyResolverMock) ResolveKey(ctx context.Context, info SignatureInfo) (KeyInfo, error) { + ret := _mock.Called(ctx, info) if len(ret) == 0 { panic("no return value specified for ResolveKey") } - var r0 Key + var r0 KeyInfo var r1 error - if returnFunc, ok := ret.Get(0).(func(context.Context, string) (Key, error)); ok { - return returnFunc(ctx, keyID) + if returnFunc, ok := ret.Get(0).(func(context.Context, SignatureInfo) (KeyInfo, error)); ok { + return returnFunc(ctx, info) } - if returnFunc, ok := ret.Get(0).(func(context.Context, string) Key); ok { - r0 = returnFunc(ctx, keyID) + if returnFunc, ok := ret.Get(0).(func(context.Context, SignatureInfo) KeyInfo); ok { + r0 = returnFunc(ctx, info) } else { - r0 = ret.Get(0).(Key) + r0 = ret.Get(0).(KeyInfo) } - if returnFunc, ok := ret.Get(1).(func(context.Context, string) error); ok { - r1 = returnFunc(ctx, keyID) + if returnFunc, ok := ret.Get(1).(func(context.Context, SignatureInfo) error); ok { + r1 = returnFunc(ctx, info) } else { r1 = ret.Error(1) } @@ -79,20 +79,20 @@ type KeyResolverMock_ResolveKey_Call struct { // ResolveKey is a helper method to define mock.On call // - ctx context.Context -// - keyID string -func (_e *KeyResolverMock_Expecter) ResolveKey(ctx any, keyID any) *KeyResolverMock_ResolveKey_Call { - return &KeyResolverMock_ResolveKey_Call{Call: _e.mock.On("ResolveKey", ctx, keyID)} +// - info SignatureInfo +func (_e *KeyResolverMock_Expecter) ResolveKey(ctx any, info any) *KeyResolverMock_ResolveKey_Call { + return &KeyResolverMock_ResolveKey_Call{Call: _e.mock.On("ResolveKey", ctx, info)} } -func (_c *KeyResolverMock_ResolveKey_Call) Run(run func(ctx context.Context, keyID string)) *KeyResolverMock_ResolveKey_Call { +func (_c *KeyResolverMock_ResolveKey_Call) Run(run func(ctx context.Context, info SignatureInfo)) *KeyResolverMock_ResolveKey_Call { _c.Call.Run(func(args mock.Arguments) { var arg0 context.Context if args[0] != nil { arg0 = args[0].(context.Context) } - var arg1 string + var arg1 SignatureInfo if args[1] != nil { - arg1 = args[1].(string) + arg1 = args[1].(SignatureInfo) } run( arg0, @@ -102,12 +102,12 @@ func (_c *KeyResolverMock_ResolveKey_Call) Run(run func(ctx context.Context, key return _c } -func (_c *KeyResolverMock_ResolveKey_Call) Return(key Key, err error) *KeyResolverMock_ResolveKey_Call { - _c.Call.Return(key, err) +func (_c *KeyResolverMock_ResolveKey_Call) Return(keyInfo KeyInfo, err error) *KeyResolverMock_ResolveKey_Call { + _c.Call.Return(keyInfo, err) return _c } -func (_c *KeyResolverMock_ResolveKey_Call) RunAndReturn(run func(ctx context.Context, keyID string) (Key, error)) *KeyResolverMock_ResolveKey_Call { +func (_c *KeyResolverMock_ResolveKey_Call) RunAndReturn(run func(ctx context.Context, info SignatureInfo) (KeyInfo, error)) *KeyResolverMock_ResolveKey_Call { _c.Call.Return(run) return _c } diff --git a/nonce.go b/nonce.go index 060c008..dee1641 100644 --- a/nonce.go +++ b/nonce.go @@ -6,29 +6,43 @@ import ( "encoding/base64" ) -// NonceGetter represents a source of random nonces to go into resulting objects. +// NonceGetter supplies a nonce for a newly generated signature or an +// Accept-Signature negotiation request. An empty result omits the parameter; +// implementations are responsible for producing appropriate nonce values. type NonceGetter interface { + // GetNonce returns a nonce or an error for the given context. GetNonce(ctx context.Context) (string, error) } +// NonceGetterFunc adapts a function to the NonceGetter interface. type NonceGetterFunc func(ctx context.Context) (string, error) +// GetNonce calls the wrapped nonce-generating function. func (ng NonceGetterFunc) GetNonce(ctx context.Context) (string, error) { return ng(ctx) } -// NonceChecker is responsible for the verification of the nonce received in a signature, -// e.g. to prevent replay attacks, or to verify that the nonce is the expected one, like -// if requested using the Accept-Signature header. +// NonceChecker checks the nonce parameter of a signature, for example to +// enforce replay protection or correlate a negotiated signature. It receives +// both the value and whether the parameter was present. CheckNonce is called +// before the cryptographic signature check; implementations that update replay +// state must account for unsuccessful verification attempts. type NonceChecker interface { + // CheckNonce returns an error if the nonce must be rejected. CheckNonce(ctx context.Context, nonce NonceValue) error } +// NonceValue represents the received nonce parameter and its presence. +// A missing nonce and an explicitly empty nonce are different values. type NonceValue struct { + // Present is true when the signature explicitly contains nonce. Present bool - Value string + // Value is the transmitted nonce value, or empty when absent. + Value string } +// NonceCheckerFunc adapts a function to the NonceChecker interface. type NonceCheckerFunc func(ctx context.Context, nonce NonceValue) error +// CheckNonce calls the wrapped nonce-checking function. func (f NonceCheckerFunc) CheckNonce(ctx context.Context, nonce NonceValue) error { return f(ctx, nonce) } diff --git a/signature_input.go b/signature_input.go index 3209d55..eacbcb6 100644 --- a/signature_input.go +++ b/signature_input.go @@ -1,6 +1,7 @@ package httpsig import ( + "bytes" "fmt" "slices" "time" @@ -36,59 +37,39 @@ func newSignatureInput( } } -func parseSignatureInput(list httpsfv.InnerList) (*signatureInput, error) { - identifiers := make([]*componentIdentifier, 0, len(list.Items)) - - for _, item := range list.Items { - identifier, err := newComponentIdentifier(item) - if err != nil { - return nil, err +func (si *signatureInput) hasIdentifier(id *componentIdentifier) bool { + for _, identifier := range si.identifiers { + if identifier.Value == id.Value && slices.Equal(identifier.Params.Names(), id.Params.Names()) { + return true } - - identifiers = append(identifiers, identifier) - } - - if err := validateSignatureInputParameters(list.Params); err != nil { - return nil, err } - return &signatureInput{ - value: list, - identifiers: identifiers, - }, nil + return false } -func validateSignatureInputParameters(params *httpsfv.Params) error { - if params == nil { - return nil - } - - for _, name := range params.Names() { - value, _ := params.Get(name) +func (si *signatureInput) parameters() SignatureParameters { + result := make(SignatureParameters) - switch SignatureParameter(name) { - case Created, Expires: - if _, ok := value.(int64); !ok { - return fmt.Errorf("%w: %s", ErrMalformedSignatureParameter, name) - } - case KeyID, Alg, Nonce, Tag: - if _, ok := value.(string); !ok { - return fmt.Errorf("%w: %s", ErrMalformedSignatureParameter, name) - } - } + if si.value.Params == nil { + return result } - return nil -} + for _, name := range si.value.Params.Names() { + value, _ := si.value.Params.Get(name) -func (si *signatureInput) hasIdentifier(id *componentIdentifier) bool { - for _, identifier := range si.identifiers { - if identifier.Value == id.Value && slices.Equal(identifier.Params.Names(), id.Params.Names()) { - return true + switch v := value.(type) { + case httpsfv.Token: + value = Token(v) + case httpsfv.DisplayString: + value = string(v) + case []byte: + value = bytes.Clone(v) } + + result[name] = value } - return false + return result } func (si *signatureInput) parameter(name SignatureParameter) (any, bool) { @@ -128,3 +109,48 @@ func (si *signatureInput) expires() (time.Time, bool) { return si.timestamp(Expi func (si *signatureInput) nonce() (string, bool) { return si.stringParameter(Nonce) } func (si *signatureInput) keyID() (string, bool) { return si.stringParameter(KeyID) } func (si *signatureInput) tag() (string, bool) { return si.stringParameter(Tag) } + +func parseSignatureInput(list httpsfv.InnerList) (*signatureInput, error) { + identifiers := make([]*componentIdentifier, 0, len(list.Items)) + + for _, item := range list.Items { + identifier, err := newComponentIdentifier(item) + if err != nil { + return nil, err + } + + identifiers = append(identifiers, identifier) + } + + if err := validateSignatureInputParameters(list.Params); err != nil { + return nil, err + } + + return &signatureInput{ + value: list, + identifiers: identifiers, + }, nil +} + +func validateSignatureInputParameters(params *httpsfv.Params) error { + if params == nil { + return nil + } + + for _, name := range params.Names() { + value, _ := params.Get(name) + + switch SignatureParameter(name) { + case Created, Expires: + if _, ok := value.(int64); !ok { + return fmt.Errorf("%w: %s", ErrMalformedSignatureParameter, name) + } + case KeyID, Alg, Nonce, Tag: + if _, ok := value.(string); !ok { + return fmt.Errorf("%w: %s", ErrMalformedSignatureParameter, name) + } + } + } + + return nil +} diff --git a/signer.go b/signer.go index ab14538..9c4a01f 100644 --- a/signer.go +++ b/signer.go @@ -12,34 +12,43 @@ import ( "github.com/dunglas/httpsfv" ) -type Signer interface { - Sign(msg *Message) (http.Header, error) -} type payloadSigner interface { signPayload(data []byte) ([]byte, error) algorithm() SignatureAlgorithm - keyID() string } -func newPayloadSigner(signingKey any, keyID string, alg SignatureAlgorithm) (payloadSigner, error) { +func newPayloadSigner(signingKey any, alg SignatureAlgorithm) (payloadSigner, error) { switch key := signingKey.(type) { case ed25519.PrivateKey: - return newEd25519Signer(key, keyID, alg) + return newEd25519Signer(key, alg) case *rsa.PrivateKey: - return newRSASigner(key, keyID, alg) + return newRSASigner(key, alg) case *ecdsa.PrivateKey: - return newECDSASigner(key, keyID, alg) + return newECDSASigner(key, alg) case []byte: - return newSymmetricSigner(key, keyID, alg) + return newSymmetricSigner(key, alg) default: return nil, ErrUnsupportedKeyType } } +// Signer creates HTTP message signatures using a configured key, set of +// covered components, and signature parameters. +type Signer interface { + // Sign signs msg and returns its updated HTTP headers, including the + // Signature and Signature-Input fields. It also updates msg.Header and + // may update Content-Digest when that component is covered. + Sign(msg *Message) (http.Header, error) +} + +// SignerOption configures how a Signer constructs HTTP message signatures. type SignerOption func(s *signer) error -// WithLabel sets the label of the signature in the Signature-Input and Signature headers. +// WithLabel sets the desired Signature-Input and Signature dictionary label. +// The default is "sig". An empty label is ignored; labels may be renamed +// automatically if they collide with an existing signature in the message. +// Labels are not signed and must not be used as identity information. func WithLabel(label string) SignerOption { return func(s *signer) error { if len(label) != 0 { @@ -50,6 +59,9 @@ func WithLabel(label string) SignerOption { } } +// WithTTL sets how long the generated signature remains valid by controlling +// its expires parameter. The default is 30 seconds. A non-positive duration +// omits expires from the generated Signature-Input. func WithTTL(ttl time.Duration) SignerOption { return func(s *signer) error { s.ttl = ttl @@ -58,7 +70,9 @@ func WithTTL(ttl time.Duration) SignerOption { } } -// WithComponents sets the HTTP fields / derived component names to be included in signing. +// WithComponents selects HTTP fields and derived component identifiers to +// cover with the signature. If "content-digest" is selected, signing also +// generates or updates the Content-Digest field for the message body. func WithComponents(identifiers ...string) SignerOption { return func(s *signer) error { var err error @@ -69,6 +83,8 @@ func WithComponents(identifiers ...string) SignerOption { } } +// WithTag sets the application-defined tag signature parameter. An empty +// tag is ignored, leaving the tag parameter absent. func WithTag(tag string) SignerOption { return func(s *signer) error { if len(tag) != 0 { @@ -79,6 +95,9 @@ func WithTag(tag string) SignerOption { } } +// WithNonce sets the source of the nonce signature parameter. By default, +// the signer generates a random nonce. A nil getter leaves that default in +// place; a getter returning an empty string causes nonce to be omitted. func WithNonce(ng NonceGetter) SignerOption { return func(s *signer) error { if ng != nil { @@ -89,6 +108,10 @@ func WithNonce(ng NonceGetter) SignerOption { } } +// WithContentDigestAlgorithm selects the algorithm used to generate +// Content-Digest when that component is covered. Without this option, the +// signer generates both supported digests (SHA-256 and SHA-512). +// Unsupported algorithms cause an error during NewSigner. func WithContentDigestAlgorithm(alg DigestAlgorithm) SignerOption { return func(s *signer) error { if _, known := supportedAlgs[alg]; !known { @@ -101,9 +124,27 @@ func WithContentDigestAlgorithm(alg DigestAlgorithm) SignerOption { } } -// NewSigner creates a new signer with the given options. +// WithKeyID adds the keyid signature parameter with the given key ID. +// An empty value is ignored; no keyid is added unless this option supplies +// a non-empty value. +func WithKeyID(keyID string) SignerOption { + return func(s *signer) error { + if len(keyID) != 0 { + s.keyID = keyID + } + + return nil + } +} + +// NewSigner creates a Signer using key for cryptographic signing. The key +// must contain private or symmetric material compatible with its algorithm. +// By default, the generated signature uses label "sig", includes a created +// timestamp and a random nonce, expires after 30 seconds, and includes the +// selected key algorithm in the alg signature parameter. Use options to +// select covered components and other signature parameters. func NewSigner(key Key, opts ...SignerOption) (Signer, error) { - ps, err := newPayloadSigner(key.Key, key.KeyID, key.Algorithm) + ps, err := newPayloadSigner(key.Material, key.Algorithm) if err != nil { return nil, err } @@ -144,6 +185,7 @@ type signer struct { ids []*componentIdentifier ttl time.Duration tag string + keyID string ng NonceGetter ps payloadSigner cdAlg DigestAlgorithm @@ -193,7 +235,7 @@ func (s *signer) signatureInput(ctx context.Context) (*signatureInput, error) { params.Add(string(Expires), created.Add(s.ttl).Unix()) } - if keyID := s.ps.keyID(); keyID != "" { + if keyID := s.keyID; keyID != "" { params.Add(string(KeyID), keyID) } diff --git a/signer_test.go b/signer_test.go index 2cd6c47..426dff9 100644 --- a/signer_test.go +++ b/signer_test.go @@ -55,7 +55,7 @@ func TestNewPayloadSigner(t *testing.T) { {uc: "hmac signer", key: k256, alg: HmacSha256, typ: &symmetricSigner{}}, } { t.Run(tc.uc, func(t *testing.T) { - sig, err := newPayloadSigner(tc.key, "test", tc.alg) + sig, err := newPayloadSigner(tc.key, tc.alg) if tc.err != nil { require.Error(t, err) @@ -216,7 +216,7 @@ func TestNewSigner(t *testing.T) { }, { uc: "error while applying configuration options", - key: Key{KeyID: "test", Algorithm: EcdsaP384Sha384, Key: pkp384}, + key: Key{Algorithm: EcdsaP384Sha384, Material: pkp384}, opts: []SignerOption{WithComponents("@test")}, assert: func(t *testing.T, err error, _ Signer) { t.Helper() @@ -227,7 +227,7 @@ func TestNewSigner(t *testing.T) { }, { uc: "successful without configuration", - key: Key{KeyID: "test", Algorithm: EcdsaP384Sha384, Key: pkp384}, + key: Key{Algorithm: EcdsaP384Sha384, Material: pkp384}, assert: func(t *testing.T, err error, sgnr Signer) { t.Helper() @@ -246,12 +246,13 @@ func TestNewSigner(t *testing.T) { }, { uc: "successful with configuration", - key: Key{KeyID: "test", Algorithm: EcdsaP384Sha384, Key: pkp384}, + key: Key{Algorithm: EcdsaP384Sha384, Material: pkp384}, opts: []SignerOption{ WithComponents("@status"), WithTag("foo"), WithTTL(1 * time.Second), WithLabel("bar"), + WithKeyID("test"), }, assert: func(t *testing.T, err error, sgnr Signer) { t.Helper() @@ -339,7 +340,7 @@ func TestSignerSign(t *testing.T) { }{ { uc: "failed creating signature parameters", - key: Key{KeyID: "test", Algorithm: EcdsaP384Sha384, Key: pkp384}, + key: Key{Algorithm: EcdsaP384Sha384, Material: pkp384}, opts: []SignerOption{ WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", errors.New("test error") })), }, @@ -363,7 +364,7 @@ func TestSignerSign(t *testing.T) { }, { uc: "failed updating message (adding content-digest)", - key: Key{KeyID: "test", Algorithm: EcdsaP384Sha384, Key: pkp384}, + key: Key{Algorithm: EcdsaP384Sha384, Material: pkp384}, opts: []SignerOption{ WithComponents("content-digest"), }, @@ -390,7 +391,7 @@ func TestSignerSign(t *testing.T) { }, { uc: "failed creating signature base", - key: Key{KeyID: "test", Algorithm: EcdsaP384Sha384, Key: pkp384}, + key: Key{Algorithm: EcdsaP384Sha384, Material: pkp384}, opts: []SignerOption{ WithComponents("@status"), }, @@ -415,11 +416,12 @@ func TestSignerSign(t *testing.T) { { // https://www.rfc-editor.org/rfc/rfc9421.html#name-minimal-signature-using-rsa uc: "B.2.1. minimal signature using rsa-pss-sha512", - key: Key{KeyID: "test-key-rsa-pss", Algorithm: RsaPssSha512, Key: tkRSAPSS}, + key: Key{Algorithm: RsaPssSha512, Material: tkRSAPSS}, opts: []SignerOption{ WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "b3k2pp5k7z-50gnwp.yemd", nil })), WithLabel("sig-b21"), WithTTL(0), + WithKeyID("test-key-rsa-pss"), }, msg: &Message{ Method: http.MethodPost, @@ -450,7 +452,7 @@ func TestSignerSign(t *testing.T) { { // https://www.rfc-editor.org/rfc/rfc9421.html#name-selective-covered-component uc: "B.2.2. selective covered components using rsa-pss-sha512", - key: Key{KeyID: "test-key-rsa-pss", Algorithm: RsaPssSha512, Key: tkRSAPSS}, + key: Key{Algorithm: RsaPssSha512, Material: tkRSAPSS}, opts: []SignerOption{ WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), WithLabel("sig-b22"), @@ -458,6 +460,7 @@ func TestSignerSign(t *testing.T) { WithComponents("@authority", "content-digest", "@query-param;name=\"Pet\""), WithTag("header-example"), WithContentDigestAlgorithm(Sha512), + WithKeyID("test-key-rsa-pss"), }, msg: &Message{ Method: http.MethodPost, @@ -491,7 +494,7 @@ func TestSignerSign(t *testing.T) { { // https://www.rfc-editor.org/rfc/rfc9421.html#name-full-coverage-using-rsa-pss uc: "B.2.3. full coverage using rsa-pss-sha512", - key: Key{KeyID: "test-key-rsa-pss", Algorithm: RsaPssSha512, Key: tkRSAPSS}, + key: Key{Algorithm: RsaPssSha512, Material: tkRSAPSS}, opts: []SignerOption{ WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), WithLabel("sig-b23"), @@ -500,6 +503,7 @@ func TestSignerSign(t *testing.T) { "date", "@method", "@path", "@query", "@authority", "content-type", "content-digest", "content-length", ), WithContentDigestAlgorithm(Sha512), + WithKeyID("test-key-rsa-pss"), }, msg: &Message{ Method: http.MethodPost, @@ -533,13 +537,14 @@ func TestSignerSign(t *testing.T) { { // https://www.rfc-editor.org/rfc/rfc9421.html#name-signing-a-response-using-ec uc: "B.2.4. signing a response using ecdsa-p256-sha256", - key: Key{KeyID: "test-key-ecc-p256", Algorithm: EcdsaP256Sha256, Key: tkECCP256}, + key: Key{Algorithm: EcdsaP256Sha256, Material: tkECCP256}, opts: []SignerOption{ WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), WithLabel("sig-b24"), WithTTL(0), WithComponents("@status", "content-type", "content-digest", "content-length"), WithContentDigestAlgorithm(Sha512), + WithKeyID("test-key-ecc-p256"), }, msg: &Message{ Method: http.MethodPost, @@ -571,12 +576,13 @@ func TestSignerSign(t *testing.T) { { // https://www.rfc-editor.org/rfc/rfc9421.html#name-signing-a-request-using-hma uc: "B.2.5. signing a request using hmac-sha256", - key: Key{KeyID: "test-shared-secret", Algorithm: HmacSha256, Key: tkMAC}, + key: Key{Algorithm: HmacSha256, Material: tkMAC}, opts: []SignerOption{ WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), WithLabel("sig-b25"), WithTTL(0), WithComponents("date", "@authority", "content-type"), + WithKeyID("test-shared-secret"), }, msg: &Message{ Method: http.MethodPost, @@ -606,12 +612,13 @@ func TestSignerSign(t *testing.T) { { // https://www.rfc-editor.org/rfc/rfc9421.html#name-signing-a-request-using-ed2 uc: "B.2.6. signing a request using ed25519", - key: Key{KeyID: "test-key-ed25519", Algorithm: Ed25519, Key: tkEd25519}, + key: Key{Algorithm: Ed25519, Material: tkEd25519}, opts: []SignerOption{ WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), WithLabel("sig-b26"), WithTTL(0), WithComponents("date", "@method", "@path", "@authority", "content-type", "content-length"), + WithKeyID("test-key-ed25519"), }, msg: &Message{ Method: http.MethodPost, @@ -640,13 +647,14 @@ func TestSignerSign(t *testing.T) { }, { uc: "overwrites stale content-digest when signing content-digest component", - key: Key{KeyID: "test-key-rsa-pss", Algorithm: RsaPssSha512, Key: tkRSAPSS}, + key: Key{Algorithm: RsaPssSha512, Material: tkRSAPSS}, opts: []SignerOption{ WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), WithLabel("sig-content-digest"), WithTTL(0), WithComponents("content-digest"), WithContentDigestAlgorithm(Sha256), + WithKeyID("test-key-rsa-pss"), }, msg: &Message{ Method: http.MethodPost, @@ -684,13 +692,14 @@ func TestSignerSign(t *testing.T) { }, { uc: "preserves existing content-digest when content-digest component is not signed", - key: Key{KeyID: "test-key-rsa-pss", Algorithm: RsaPssSha512, Key: tkRSAPSS}, + key: Key{Algorithm: RsaPssSha512, Material: tkRSAPSS}, opts: []SignerOption{ WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), WithLabel("sig-no-content-digest"), WithTTL(0), WithComponents("date", "@method"), WithContentDigestAlgorithm(Sha256), + WithKeyID("test-key-rsa-pss"), }, msg: &Message{ Method: http.MethodPost, diff --git a/symmetric.go b/symmetric.go index 8f2db0a..ee5f42f 100644 --- a/symmetric.go +++ b/symmetric.go @@ -7,7 +7,7 @@ import ( "fmt" ) -func newSymmetricSigner(key []byte, kid string, alg SignatureAlgorithm) (*symmetricSigner, error) { +func newSymmetricSigner(key []byte, alg SignatureAlgorithm) (*symmetricSigner, error) { var hash crypto.Hash switch alg { @@ -24,7 +24,6 @@ func newSymmetricSigner(key []byte, kid string, alg SignatureAlgorithm) (*symmet return &symmetricSigner{ alg: alg, key: key, - kid: kid, hash: hash, }, nil } @@ -32,12 +31,9 @@ func newSymmetricSigner(key []byte, kid string, alg SignatureAlgorithm) (*symmet type symmetricSigner struct { alg SignatureAlgorithm key []byte - kid string hash crypto.Hash } -func (ms *symmetricSigner) keyID() string { return ms.kid } - func (ms *symmetricSigner) algorithm() SignatureAlgorithm { return ms.alg } func (ms *symmetricSigner) signPayload(data []byte) ([]byte, error) { return ms.hmac(data), nil } diff --git a/symmetric_test.go b/symmetric_test.go index 88ab982..03cf234 100644 --- a/symmetric_test.go +++ b/symmetric_test.go @@ -40,7 +40,7 @@ func TestNewSymmetricSigner(t *testing.T) { {uc: string(HmacSha512), alg: HmacSha512, key: k512}, } { t.Run(tc.uc, func(t *testing.T) { - sig, err := newSymmetricSigner(tc.key, "test", tc.alg) + sig, err := newSymmetricSigner(tc.key, tc.alg) if tc.err != nil { require.Error(t, err) @@ -48,7 +48,6 @@ func TestNewSymmetricSigner(t *testing.T) { } else { require.NoError(t, err) require.NotNil(t, sig) - assert.Equal(t, "test", sig.keyID()) assert.Equal(t, tc.key, sig.key) assert.Equal(t, tc.alg, sig.algorithm()) } @@ -86,7 +85,7 @@ func TestSymmetricSignerSignPayload(t *testing.T) { {alg: HmacSha512, key: k512}, } { t.Run(string(tc.alg), func(t *testing.T) { - sig, err := newSymmetricSigner(tc.key, "test", tc.alg) + sig, err := newSymmetricSigner(tc.key, tc.alg) require.NoError(t, err) res, err := sig.signPayload(message) @@ -113,7 +112,7 @@ func TestSymmetricSignerVerifyPayload(t *testing.T) { require.NoError(t, err) require.Equal(t, len(key), n) - sig, err := newSymmetricSigner(key, "test", HmacSha256) + sig, err := newSymmetricSigner(key, HmacSha256) require.NoError(t, err) res, err := sig.signPayload(message) diff --git a/verifier.go b/verifier.go index b61dfcd..63b1fa8 100644 --- a/verifier.go +++ b/verifier.go @@ -1,7 +1,6 @@ package httpsig import ( - "context" "crypto/ecdsa" "crypto/ed25519" "crypto/rsa" @@ -14,39 +13,46 @@ import ( "github.com/dunglas/httpsfv" ) -type Verifier interface { - Verify(msg *Message) error -} +// VerifiedSignature contains the attributes of a successfully verified HTTP +// message signature and the metadata returned by the KeyResolver. +type VerifiedSignature struct { + // Label is the received signature label. It is not cryptographically + // protected and must not be used as an identity or authorization claim. + Label string -// KeyResolver is used to resolve a key id to a verifying key. -type KeyResolver interface { - ResolveKey(ctx context.Context, keyID string) (Key, error) -} + // Components contains the canonicalized values of the covered HTTP + // message components, without the synthetic @signature-params component. + Components map[string]string -type payloadVerifier interface { - verifyPayload(data []byte, signature []byte) error - algorithm() SignatureAlgorithm - keyID() string + // Parameters contains the actual transmitted signature parameters, + // including extensions, without synthetic defaults. + Parameters SignatureParameters + + // Metadata is the application-defined metadata provided by the KeyResolver + // for this signature. + Metadata any } -func newPayloadVerifier(verificationKey any, keyID string, alg SignatureAlgorithm) (payloadVerifier, error) { - switch publicKey := verificationKey.(type) { - case ed25519.PublicKey: - return newEd25519Verifier(publicKey, keyID, alg) - case *rsa.PublicKey: - return newRSAVerifier(publicKey, keyID, alg) - case *ecdsa.PublicKey: - return newECDSAVerifier(publicKey, keyID, alg) - case []byte: - return newSymmetricSigner(publicKey, keyID, alg) - default: - return nil, ErrUnsupportedKeyType - } +// VerificationResult contains the signatures selected and successfully +// verified during one call to Verifier.Verify. +type VerificationResult []VerifiedSignature + +// Verifier verifies HTTP message signatures according to its configured +// requirements. A call succeeds only if all selected signatures pass. +type Verifier interface { + // Verify returns information about the successfully verified signatures + // or an error. + Verify(msg *Message) (VerificationResult, error) } +// VerifierOption configures which signatures to verify and which generic +// checks to apply. Options can be provided to NewVerifier or used within +// WithRequiredTag for per-tag expectations. Options such as WithNonceChecker +// configure the verifier globally even when supplied within a tag. type VerifierOption func(v *verifier, e *expectations, f bool) error -// WithRequiredComponents sets the HTTP fields / derived component names to be included in signing. +// WithRequiredComponents specifies HTTP fields or derived component +// identifiers that must be covered by a signature to which the option applies. func WithRequiredComponents(identifiers ...string) VerifierOption { return func(_ *verifier, exp *expectations, _ bool) error { var err error @@ -57,7 +63,8 @@ func WithRequiredComponents(identifiers ...string) VerifierOption { } } -// WithValidityTolerance sets the clock tolerance for verifying created and expires times. +// WithValidityTolerance allows a clock skew of d when checking the created +// and expires signature parameters. func WithValidityTolerance(d time.Duration) VerifierOption { return func(_ *verifier, e *expectations, _ bool) error { e.tolerance = d @@ -66,6 +73,8 @@ func WithValidityTolerance(d time.Duration) VerifierOption { } } +// WithMaxAge sets the maximum age of signatures with a created timestamp. +// The default for NewVerifier is 30 seconds. func WithMaxAge(d time.Duration) VerifierOption { return func(_ *verifier, e *expectations, _ bool) error { e.maxAge = d @@ -74,7 +83,12 @@ func WithMaxAge(d time.Duration) VerifierOption { } } +// WithNonceChecker sets the checker for the nonce parameter, including when +// the parameter is absent. If checker is nil, the no-op default remains. CheckNonce +// may be called before cryptographic verification has succeeded; checkers +// with replay state must account for unsuccessful verification attempts. func WithNonceChecker(checker NonceChecker) VerifierOption { + // TODO: Maybe we should use checker after cryptographic verification has succeeded return func(v *verifier, _ *expectations, _ bool) error { if checker != nil { v.nonceChecker = checker @@ -84,12 +98,18 @@ func WithNonceChecker(checker NonceChecker) VerifierOption { } } +// WithRequiredTag selects signatures with the given application tag and +// applies opts to that signature. Global options in NewVerifier provide +// defaults for unspecified per-tag requirements. Each tag may be configured +// only once. func WithRequiredTag(tag string, opts ...VerifierOption) VerifierOption { return func(ver *verifier, _ *expectations, f bool) error { if f { panic("WithRequiredTag cannot be used as option for itself") } + // TODO: check if the tag is empty, which is reserved for global expectations. such tag is not allowed + if _, configured := ver.tagExpectations[tag]; configured { return fmt.Errorf("%w: requirements for tag %s are already configured", ErrParameter, tag) } @@ -111,6 +131,9 @@ func WithRequiredTag(tag string, opts ...VerifierOption) VerifierOption { } } +// WithValidateAllSignatures verifies every signature in the message, not just +// those selected with WithRequiredTag. When a signature has a configured tag, +// its per-tag requirements apply; otherwise, global requirements apply. func WithValidateAllSignatures() VerifierOption { return func(v *verifier, _ *expectations, _ bool) error { v.validateAllSigs = true @@ -119,7 +142,11 @@ func WithValidateAllSignatures() VerifierOption { } } +// WithCreatedTimestampRequired controls whether the created parameter must +// be present. If present, it is still checked even when flag is false. +// NewVerifier requires created by default. func WithCreatedTimestampRequired(flag bool) VerifierOption { + // TODO: Same challenge as WithExpiredTimestampRequired return func(_ *verifier, exp *expectations, _ bool) error { exp.reqCreatedTS = &flag @@ -127,7 +154,12 @@ func WithCreatedTimestampRequired(flag bool) VerifierOption { } } +// WithExpiredTimestampRequired controls whether the expires parameter must +// be present. If present, it is still checked even when flag is false. +// NewVerifier requires expires by default. func WithExpiredTimestampRequired(flag bool) VerifierOption { + // TODO: if the flag is false, then the expires parameter must not be present in the signature. This must be checked. + // There is a need to think more about the semantics as different rfcs have different requirements on that parameter return func(_ *verifier, exp *expectations, _ bool) error { exp.reqExpiresTS = &flag @@ -135,6 +167,14 @@ func WithExpiredTimestampRequired(flag bool) VerifierOption { } } +// WithSignatureNegotiation enables Accept-Signature negotiation when a +// required signature or required component or parameter is missing. +// +// Negotiation reuses the relevant verifier requirements; opts specify only +// additional requests such as a key ID, nonce, algorithm, or label. A caller +// can extract NoApplicableSignatureError from a verification failure and call +// its Negotiate method to populate response headers. Negotiation configured +// globally cannot be combined with WithValidateAllSignatures. func WithSignatureNegotiation(opts ...SignatureNegotiationOption) VerifierOption { no := &sigNegotiationOpts{opts: make([]AcceptSignatureOption, 0, len(opts))} for _, opt := range opts { @@ -157,33 +197,54 @@ type sigNegotiationOpts struct { opts []AcceptSignatureOption } +// SignatureNegotiationOption configures the additional values requested by +// WithSignatureNegotiation beyond the verifier's existing requirements. type SignatureNegotiationOption func(sno *sigNegotiationOpts) -func WithRequestedKey(key Key) SignatureNegotiationOption { +// WithRequestedSignatureAlgorithm requests alg in the generated +// Accept-Signature header. +func WithRequestedSignatureAlgorithm(alg SignatureAlgorithm) SignatureNegotiationOption { return func(sno *sigNegotiationOpts) { - sno.opts = append(sno.opts, WithExpectedKey(key)) + sno.opts = append(sno.opts, WithExpectedSignatureAlgorithm(alg)) } } +// WithRequestedNonce supplies the nonce source for Accept-Signature +// negotiation. func WithRequestedNonce(ng NonceGetter) SignatureNegotiationOption { return func(sno *sigNegotiationOpts) { sno.opts = append(sno.opts, WithExpectedNonce(ng)) } } +// WithRequestedContentDigestAlgorithmPreferences sets the Want-Content-Digest +// preferences emitted when negotiation requires a content-digest component. func WithRequestedContentDigestAlgorithmPreferences(prefs ...AlgorithmPreference) SignatureNegotiationOption { return func(sno *sigNegotiationOpts) { sno.opts = append(sno.opts, WithContentDigestAlgorithmPreferences(prefs...)) } } +// WithRequestedLabel sets the technical label requested in Accept-Signature. +// Signature labels are not authenticated and must not carry identity meaning. func WithRequestedLabel(label string) SignatureNegotiationOption { return func(sno *sigNegotiationOpts) { sno.opts = append(sno.opts, WithExpectedLabel(label)) } } -// NewVerifier creates a new verifier with the given options. +// WithRequestedKeyID requests keyID as the keyid parameter in the generated +// Accept-Signature header. +func WithRequestedKeyID(keyID string) SignatureNegotiationOption { + return func(sno *sigNegotiationOpts) { + sno.opts = append(sno.opts, WithExpectedKeyID(keyID)) + } +} + +// NewVerifier creates a Verifier instance. +// Without WithValidateAllSignatures, at least one WithRequiredTag is necessary. +// By default, created and expires are required and signatures may be at most +// 30 seconds old. More specific requirements can be set through opts. // //nolint:cyclop func NewVerifier(resolver KeyResolver, opts ...VerifierOption) (Verifier, error) { @@ -267,6 +328,25 @@ func NewVerifier(resolver KeyResolver, opts ...VerifierOption) (Verifier, error) return ver, nil } +type payloadVerifier interface { + verifyPayload(data []byte, signature []byte) error +} + +func newPayloadVerifier(verificationKey any, alg SignatureAlgorithm) (payloadVerifier, error) { + switch publicKey := verificationKey.(type) { + case ed25519.PublicKey: + return newEd25519Verifier(publicKey, alg) + case *rsa.PublicKey: + return newRSAVerifier(publicKey, alg) + case *ecdsa.PublicKey: + return newECDSAVerifier(publicKey, alg) + case []byte: + return newSymmetricSigner(publicKey, alg) + default: + return nil, ErrUnsupportedKeyType + } +} + type expectations struct { tolerance time.Duration maxAge time.Duration @@ -369,29 +449,30 @@ type verifier struct { nonceChecker NonceChecker } -func (v *verifier) Verify(msg *Message) error { +func (v *verifier) Verify(msg *Message) (VerificationResult, error) { sigRefs, err := getSignatureReferences(msg.Header.Values(headerSignatureInput)) if err != nil { - return fmt.Errorf("%w: %w", ErrVerificationFailed, err) + return nil, fmt.Errorf("%w: %w", ErrVerificationFailed, err) } signatureDict, err := httpsfv.UnmarshalDictionary(msg.Header.Values(headerSignature)) if err != nil { - return fmt.Errorf("%w: %w", ErrVerificationFailed, err) + return nil, fmt.Errorf("%w: %w", ErrVerificationFailed, err) } // look if we miss any signatures for configured tags if v.hasMissingSignatures(sigRefs) { - return fmt.Errorf("%w: %w", ErrVerificationFailed, v.negotiateSignatureParameters(msg)) + return nil, fmt.Errorf("%w: %w", ErrVerificationFailed, v.negotiateSignatureParameters(msg)) } // collect those signatures, which we can verify applicableSignatures, err := v.applicableSignatures(sigRefs) if err != nil { - return fmt.Errorf("%w: %w", ErrVerificationFailed, err) + return nil, fmt.Errorf("%w: %w", ErrVerificationFailed, err) } // do the actual verification + results := make([]VerifiedSignature, 0, len(applicableSignatures)) for name, params := range applicableSignatures { tag, _ := params.tag() @@ -402,20 +483,22 @@ func (v *verifier) Verify(msg *Message) error { signature, err := v.extractSignature(signatureDict, name) if err != nil { - return fmt.Errorf("%w: %w", ErrVerificationFailed, err) + return nil, fmt.Errorf("%w: %w", ErrVerificationFailed, err) } - err = v.verifySignature(msg, signature, params, exp) + result, err := v.verifySignature(msg, name, signature, params, exp) if err != nil { if errors.Is(err, ErrMissingParameter) { - return fmt.Errorf("%w: %w", ErrVerificationFailed, v.negotiateSignatureParameters(msg)) + return nil, fmt.Errorf("%w: %w", ErrVerificationFailed, v.negotiateSignatureParameters(msg)) } - return fmt.Errorf("%w: %w", ErrVerificationFailed, err) + return nil, fmt.Errorf("%w: %w", ErrVerificationFailed, err) } + + results = append(results, result) } - return nil + return results, nil } func (v *verifier) applicableSignatures(refs map[string]*signatureInput) (map[string]*signatureInput, error) { @@ -487,37 +570,58 @@ func (v *verifier) hasMissingSignatures(sigRefs map[string]*signatureInput) bool func (v *verifier) verifySignature( msg *Message, + label string, signature []byte, si *signatureInput, exp *expectations, -) error { +) (VerifiedSignature, error) { base, err := newSignatureBase(si, msg) if err != nil { - return err + return VerifiedSignature{}, err + } + + components, err := base.components() + if err != nil { + return VerifiedSignature{}, err } - keyID, _ := si.keyID() + params := si.parameters() - key, err := v.keyResolver.ResolveKey(msg.Context, keyID) + keyInfo, err := v.keyResolver.ResolveKey(msg.Context, SignatureInfo{ + Label: label, + Message: msg, + Components: components, + Parameters: params, + }) if err != nil { - return err + return VerifiedSignature{}, err } - if err = exp.assert(si, msg, key.Algorithm, v.nonceChecker); err != nil { - return err + if err = exp.assert(si, msg, keyInfo.Key.Algorithm, v.nonceChecker); err != nil { + return VerifiedSignature{}, err } - verifier, err := newPayloadVerifier(key.Key, key.KeyID, key.Algorithm) + verifier, err := newPayloadVerifier(keyInfo.Key.Material, keyInfo.Key.Algorithm) if err != nil { - return err + return VerifiedSignature{}, err } sb, err := base.marshal() if err != nil { - return err + return VerifiedSignature{}, err + } + + err = verifier.verifyPayload(sb, signature) + if err != nil { + return VerifiedSignature{}, err } - return verifier.verifyPayload(sb, signature) + return VerifiedSignature{ + Label: label, + Components: components, + Parameters: params, + Metadata: keyInfo.Metadata, + }, nil } func getSignatureReferences(values []string) (map[string]*signatureInput, error) { diff --git a/verifier_test.go b/verifier_test.go index 94e0600..22b75b1 100644 --- a/verifier_test.go +++ b/verifier_test.go @@ -15,6 +15,7 @@ import ( "io" "net/http" "net/url" + "slices" "strings" "testing" "time" @@ -56,7 +57,7 @@ func TestNewPayloadVerifier(t *testing.T) { {uc: "hmac verifier", key: k256, alg: HmacSha256, typ: &symmetricSigner{}}, } { t.Run(tc.uc, func(t *testing.T) { - sig, err := newPayloadVerifier(tc.key, "test", tc.alg) + sig, err := newPayloadVerifier(tc.key, tc.alg) if tc.err != nil { require.Error(t, err) @@ -649,7 +650,7 @@ func TestWithSignatureNegotiation(t *testing.T) { assert.IsType(t, nonceGetter{}, asb.nonceGetter) assert.Equal(t, "sig", asb.label) assert.ElementsMatch(t, asb.cdAlgPrefs, []string{"sha-256=5", "sha-512=10"}) - assert.Empty(t, asb.keyAlgorithm) + assert.Empty(t, asb.signatureAlgorithm) assert.Empty(t, asb.keyID) // not set by any of the options assert.True(t, asb.addCreatedTS) @@ -664,7 +665,8 @@ func TestWithSignatureNegotiation(t *testing.T) { opts: []SignatureNegotiationOption{ WithRequestedLabel("foo"), WithRequestedNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), - WithRequestedKey(Key{KeyID: "bar", Algorithm: RsaPssSha512}), + WithRequestedSignatureAlgorithm(RsaPssSha512), + WithRequestedKeyID("bar"), WithRequestedContentDigestAlgorithmPreferences(AlgorithmPreference{Sha512, 2}), }, assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) { @@ -679,7 +681,7 @@ func TestWithSignatureNegotiation(t *testing.T) { require.Equal(t, "abc", nonce) assert.Equal(t, "foo", asb.label) assert.ElementsMatch(t, asb.cdAlgPrefs, []string{"sha-512=2"}) - assert.Equal(t, RsaPssSha512, asb.keyAlgorithm) + assert.Equal(t, RsaPssSha512, asb.signatureAlgorithm) assert.Equal(t, "bar", asb.keyID) // not set by any of the options assert.True(t, asb.addCreatedTS) @@ -846,7 +848,8 @@ func TestNewVerifier(t *testing.T) { WithValidityTolerance(1 * time.Second), WithRequiredComponents("@status", "content-digest"), WithSignatureNegotiation( - WithRequestedKey(Key{KeyID: "bar", Algorithm: RsaPssSha512}), + WithRequestedSignatureAlgorithm(RsaPssSha512), + WithRequestedKeyID("bar"), ), }, assert: func(t *testing.T, err error, v *verifier) { @@ -868,7 +871,7 @@ func TestNewVerifier(t *testing.T) { assert.IsType(t, nonceGetter{}, exp.asb.nonceGetter) assert.Equal(t, "sig", exp.asb.label) assert.ElementsMatch(t, exp.asb.cdAlgPrefs, []string{"sha-256=5", "sha-512=10"}) - assert.Equal(t, RsaPssSha512, exp.asb.keyAlgorithm) + assert.Equal(t, RsaPssSha512, exp.asb.signatureAlgorithm) assert.Equal(t, "bar", exp.asb.keyID) assert.True(t, exp.asb.addCreatedTS) assert.True(t, exp.asb.addExpiresTS) @@ -966,14 +969,14 @@ func TestVerifierVerify(t *testing.T) { opts []VerifierOption msg *Message configureResolver func(t *testing.T, kr *KeyResolverMock) - assert func(t *testing.T, err error) + assert func(t *testing.T, err error, results VerificationResult) }{ { uc: "without signature-input header", opts: []VerifierOption{WithValidateAllSignatures()}, msg: &Message{Header: make(http.Header)}, configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, - assert: func(t *testing.T, err error) { + assert: func(t *testing.T, err error, _ VerificationResult) { t.Helper() require.Error(t, err) @@ -990,7 +993,7 @@ func TestVerifierVerify(t *testing.T) { }, }, configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, - assert: func(t *testing.T, err error) { + assert: func(t *testing.T, err error, _ VerificationResult) { t.Helper() require.Error(t, err) @@ -1008,7 +1011,7 @@ func TestVerifierVerify(t *testing.T) { }, }, configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, - assert: func(t *testing.T, err error) { + assert: func(t *testing.T, err error, _ VerificationResult) { t.Helper() require.Error(t, err) @@ -1026,7 +1029,7 @@ func TestVerifierVerify(t *testing.T) { }, }, configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, - assert: func(t *testing.T, err error) { + assert: func(t *testing.T, err error, _ VerificationResult) { t.Helper() require.Error(t, err) @@ -1045,7 +1048,7 @@ func TestVerifierVerify(t *testing.T) { }, }, configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, - assert: func(t *testing.T, err error) { + assert: func(t *testing.T, err error, _ VerificationResult) { t.Helper() require.Error(t, err) @@ -1063,7 +1066,7 @@ func TestVerifierVerify(t *testing.T) { }, }, configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, - assert: func(t *testing.T, err error) { + assert: func(t *testing.T, err error, _ VerificationResult) { t.Helper() require.Error(t, err) @@ -1088,7 +1091,7 @@ func TestVerifierVerify(t *testing.T) { IsRequest: true, }, configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, - assert: func(t *testing.T, err error) { + assert: func(t *testing.T, err error, results VerificationResult) { t.Helper() require.Error(t, err) @@ -1108,9 +1111,17 @@ func TestVerifierVerify(t *testing.T) { configureResolver: func(t *testing.T, kr *KeyResolverMock) { t.Helper() - kr.EXPECT().ResolveKey(mock.Anything, "test").Return(Key{}, errors.New("test error")) + kr.EXPECT().ResolveKey(mock.Anything, + mock.MatchedBy(func(si SignatureInfo) bool { + return si.Label == "sig" && + si.Message != nil && + len(si.Components) == 0 && + si.Parameters["keyid"] == "test" && + si.Parameters["created"] == int64(1618884473) + })). + Return(KeyInfo{}, errors.New("test error")) }, - assert: func(t *testing.T, err error) { + assert: func(t *testing.T, err error, _ VerificationResult) { t.Helper() require.Error(t, err) @@ -1130,9 +1141,18 @@ func TestVerifierVerify(t *testing.T) { configureResolver: func(t *testing.T, kr *KeyResolverMock) { t.Helper() - kr.EXPECT().ResolveKey(mock.Anything, "test").Return(Key{}, nil) + kr.EXPECT().ResolveKey(mock.Anything, + mock.MatchedBy(func(si SignatureInfo) bool { + return si.Label == "sig" && + si.Message != nil && + len(si.Components) == 0 && + si.Parameters["expires"] == int64(1618884470) && + si.Parameters["keyid"] == "test" && + si.Parameters["tag"] == "foo" + })). + Return(KeyInfo{}, nil) }, - assert: func(t *testing.T, err error) { + assert: func(t *testing.T, err error, _ VerificationResult) { t.Helper() require.Error(t, err) @@ -1156,9 +1176,17 @@ func TestVerifierVerify(t *testing.T) { configureResolver: func(t *testing.T, kr *KeyResolverMock) { t.Helper() - kr.EXPECT().ResolveKey(mock.Anything, "test").Return(Key{Key: &rsa.PrivateKey{}}, nil) + kr.EXPECT().ResolveKey(mock.Anything, + mock.MatchedBy(func(si SignatureInfo) bool { + return si.Label == "sig" && + si.Message != nil && + len(si.Components) == 0 && + si.Parameters["keyid"] == "test" && + si.Parameters["tag"] == "foo" + })). + Return(KeyInfo{Key: Key{Material: &rsa.PrivateKey{}}}, nil) }, - assert: func(t *testing.T, err error) { + assert: func(t *testing.T, err error, _ VerificationResult) { t.Helper() require.Error(t, err) @@ -1185,10 +1213,22 @@ func TestVerifierVerify(t *testing.T) { pk2048, err := rsa.GenerateKey(rand.Reader, 2048) require.NoError(t, err) - kr.EXPECT().ResolveKey(mock.Anything, "test").Return( - Key{Key: &pk2048.PublicKey, KeyID: "test", Algorithm: RsaPkcs1v15Sha512}, nil) + kr.EXPECT().ResolveKey(mock.Anything, + mock.MatchedBy(func(si SignatureInfo) bool { + return si.Label == "sig" && + si.Message != nil && + len(si.Components) == 0 && + si.Parameters["keyid"] == "test" && + si.Parameters["tag"] == "foo" + })). + Return( + KeyInfo{ + Key: Key{Material: &pk2048.PublicKey, Algorithm: RsaPkcs1v15Sha512}, + }, + nil, + ) }, - assert: func(t *testing.T, err error) { + assert: func(t *testing.T, err error, _ VerificationResult) { t.Helper() require.Error(t, err) @@ -1202,7 +1242,8 @@ func TestVerifierVerify(t *testing.T) { WithRequiredTag("foo", WithRequiredComponents("@method", "content-digest"), WithSignatureNegotiation( - WithRequestedKey(Key{KeyID: "test-key", Algorithm: RsaPssSha512}), + WithRequestedSignatureAlgorithm(RsaPssSha512), + WithRequestedKeyID("test-key"), WithRequestedLabel("bar"), WithRequestedNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), WithRequestedContentDigestAlgorithmPreferences(AlgorithmPreference{Sha256, 1}), @@ -1211,7 +1252,7 @@ func TestVerifierVerify(t *testing.T) { }, msg: &Message{Header: http.Header{}}, configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, - assert: func(t *testing.T, err error) { + assert: func(t *testing.T, err error, _ VerificationResult) { t.Helper() var targetErr *NoApplicableSignatureError @@ -1233,7 +1274,8 @@ func TestVerifierVerify(t *testing.T) { opts: []VerifierOption{ WithRequiredTag("foo", WithSignatureNegotiation( - WithRequestedKey(Key{KeyID: "test-key", Algorithm: RsaPssSha512}), + WithRequestedSignatureAlgorithm(RsaPssSha512), + WithRequestedKeyID("test-key"), WithRequestedLabel("bar"), WithRequestedNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), WithRequestedContentDigestAlgorithmPreferences(AlgorithmPreference{Sha256, 1}), @@ -1255,10 +1297,25 @@ func TestVerifierVerify(t *testing.T) { configureResolver: func(t *testing.T, kr *KeyResolverMock) { t.Helper() - kr.EXPECT().ResolveKey(mock.Anything, "test-key").Return( - Key{Key: tkRSAPSS, KeyID: "test-key", Algorithm: RsaPssSha512}, nil) + kr.EXPECT().ResolveKey(mock.Anything, + mock.MatchedBy(func(si SignatureInfo) bool { + return si.Label == "sig" && + si.Message != nil && + si.Message.Header.Get("Content-Length") == "18" && + len(si.Components) == 0 && + si.Parameters["created"] == int64(1618884473) && + si.Parameters["keyid"] == "test-key" && + si.Parameters["nonce"] == "abc" && + si.Parameters["tag"] == "foo" + })). + Return( + KeyInfo{ + Key: Key{Material: tkRSAPSS, Algorithm: RsaPssSha512}, + }, + nil, + ) }, - assert: func(t *testing.T, err error) { + assert: func(t *testing.T, err error, _ VerificationResult) { t.Helper() var targetErr *NoApplicableSignatureError @@ -1280,14 +1337,15 @@ func TestVerifierVerify(t *testing.T) { WithRequiredTag("foo", WithRequiredComponents("@method"), WithSignatureNegotiation( - WithRequestedKey(Key{KeyID: "test-key", Algorithm: RsaPssSha512}), + WithRequestedSignatureAlgorithm(RsaPssSha512), + WithRequestedKeyID("test-key"), WithRequestedNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", errors.New("test error") })), ), ), }, msg: &Message{Header: http.Header{}}, configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, - assert: func(t *testing.T, err error) { + assert: func(t *testing.T, err error, _ VerificationResult) { t.Helper() require.Error(t, err) @@ -1324,10 +1382,26 @@ func TestVerifierVerify(t *testing.T) { configureResolver: func(t *testing.T, kr *KeyResolverMock) { t.Helper() - kr.EXPECT().ResolveKey(mock.Anything, "test-key-rsa-pss").Return( - Key{Key: tkRSAPSS, KeyID: "test-key-rsa-pss", Algorithm: RsaPssSha512}, nil) - }, - assert: func(t *testing.T, err error) { + kr.EXPECT().ResolveKey(mock.Anything, + mock.MatchedBy(func(si SignatureInfo) bool { + return si.Label == "sig-b22" && + si.Message != nil && + si.Message.Header.Get("Content-Length") == "18" && + len(si.Components) == 3 && + si.Components["@authority"] == "example.com" && + si.Components["@query-param;name=\"Pet\""] == "dog" && + si.Parameters["created"] == int64(1618884473) && + si.Parameters["keyid"] == "test-key-rsa-pss" && + si.Parameters["tag"] == "header-example" + })). + Return( + KeyInfo{ + Key: Key{Material: tkRSAPSS, Algorithm: RsaPssSha512}, + }, + nil, + ) + }, + assert: func(t *testing.T, err error, _ VerificationResult) { t.Helper() require.Error(t, err) @@ -1361,13 +1435,42 @@ func TestVerifierVerify(t *testing.T) { configureResolver: func(t *testing.T, kr *KeyResolverMock) { t.Helper() - kr.EXPECT().ResolveKey(mock.Anything, "test-key-rsa-pss").Return( - Key{Key: tkRSAPSS, KeyID: "test-key-rsa-pss", Algorithm: RsaPssSha512}, nil) + kr.EXPECT().ResolveKey(mock.Anything, + mock.MatchedBy(func(si SignatureInfo) bool { + return si.Label == "sig-b21" && + si.Message != nil && + si.Message.Header.Get("Content-Length") == "18" && + len(si.Components) == 0 && + si.Parameters["created"] == int64(1618884473) && + si.Parameters["keyid"] == "test-key-rsa-pss" && + si.Parameters["nonce"] == "b3k2pp5k7z-50gnwp.yemd" + })). + Return( + KeyInfo{ + Key: Key{Material: tkRSAPSS, Algorithm: RsaPssSha512}, + Metadata: "foo", + }, + nil, + ) }, - assert: func(t *testing.T, err error) { + assert: func(t *testing.T, err error, results VerificationResult) { t.Helper() require.NoError(t, err) + + require.Len(t, results, 1) + + sig := results[0] + assert.Equal(t, "sig-b21", sig.Label) + + assert.Empty(t, sig.Components) + + assert.Len(t, sig.Parameters, 3) + assert.Equal(t, int64(1618884473), sig.Parameters["created"]) + assert.Equal(t, "test-key-rsa-pss", sig.Parameters["keyid"]) + assert.Equal(t, "b3k2pp5k7z-50gnwp.yemd", sig.Parameters["nonce"]) + + assert.Equal(t, "foo", sig.Metadata) }, }, { @@ -1399,13 +1502,46 @@ func TestVerifierVerify(t *testing.T) { configureResolver: func(t *testing.T, kr *KeyResolverMock) { t.Helper() - kr.EXPECT().ResolveKey(mock.Anything, "test-key-rsa-pss").Return( - Key{Key: tkRSAPSS, KeyID: "test-key-rsa-pss", Algorithm: RsaPssSha512}, nil) - }, - assert: func(t *testing.T, err error) { + kr.EXPECT().ResolveKey(mock.Anything, + mock.MatchedBy(func(si SignatureInfo) bool { + return si.Label == "sig-b22" && + si.Message != nil && + si.Message.Header.Get("Content-Length") == "18" && + len(si.Components) == 3 && + si.Components["@authority"] == "example.com" && + si.Components["@query-param;name=\"Pet\""] == "dog" && + si.Parameters["created"] == int64(1618884473) && + si.Parameters["keyid"] == "test-key-rsa-pss" && + si.Parameters["tag"] == "header-example" + })). + Return( + KeyInfo{ + Key: Key{Material: tkRSAPSS, Algorithm: RsaPssSha512}, + Metadata: []string{"foo"}, + }, + nil, + ) + }, + assert: func(t *testing.T, err error, results VerificationResult) { t.Helper() require.NoError(t, err) + + require.Len(t, results, 1) + + sig := results[0] + assert.Equal(t, "sig-b22", sig.Label) + + assert.Len(t, sig.Components, 3) + assert.Equal(t, "example.com", sig.Components["@authority"]) + assert.Equal(t, "dog", sig.Components["@query-param;name=\"Pet\""]) + + assert.Len(t, sig.Parameters, 3) + assert.Equal(t, int64(1618884473), sig.Parameters["created"]) + assert.Equal(t, "test-key-rsa-pss", sig.Parameters["keyid"]) + assert.Equal(t, "header-example", sig.Parameters["tag"]) + + assert.Equal(t, []string{"foo"}, sig.Metadata) }, }, { @@ -1437,13 +1573,55 @@ func TestVerifierVerify(t *testing.T) { configureResolver: func(t *testing.T, kr *KeyResolverMock) { t.Helper() - kr.EXPECT().ResolveKey(mock.Anything, "test-key-rsa-pss").Return( - Key{Key: tkRSAPSS, KeyID: "test-key-rsa-pss", Algorithm: RsaPssSha512}, nil) - }, - assert: func(t *testing.T, err error) { + kr.EXPECT().ResolveKey(mock.Anything, + mock.MatchedBy(func(si SignatureInfo) bool { + return si.Label == "sig-b23" && + si.Message != nil && + si.Message.Header.Get("Content-Length") == "18" && + len(si.Components) == 8 && + si.Components["date"] == "Tue, 20 Apr 2021 02:07:55 GMT" && + si.Components["@method"] == "POST" && + si.Components["@path"] == "/foo" && + si.Components["@query"] == "?param=Value&Pet=dog" && + si.Components["@authority"] == "example.com" && + si.Components["content-type"] == "application/json" && + si.Components["content-digest"] == "sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==:" && + si.Components["content-length"] == "18" && + si.Parameters["created"] == int64(1618884473) && + si.Parameters["keyid"] == "test-key-rsa-pss" + })). + Return( + KeyInfo{ + Key: Key{Material: tkRSAPSS, Algorithm: RsaPssSha512}, + }, + nil, + ) + }, + assert: func(t *testing.T, err error, results VerificationResult) { t.Helper() require.NoError(t, err) + + require.Len(t, results, 1) + + sig := results[0] + assert.Equal(t, "sig-b23", sig.Label) + + assert.Len(t, sig.Components, 8) + assert.Equal(t, "Tue, 20 Apr 2021 02:07:55 GMT", sig.Components["date"]) + assert.Equal(t, "POST", sig.Components["@method"]) + assert.Equal(t, "/foo", sig.Components["@path"]) + assert.Equal(t, "?param=Value&Pet=dog", sig.Components["@query"]) + assert.Equal(t, "example.com", sig.Components["@authority"]) + assert.Equal(t, "application/json", sig.Components["content-type"]) + assert.Equal(t, "sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==:", sig.Components["content-digest"]) + assert.Equal(t, "18", sig.Components["content-length"]) + + assert.Len(t, sig.Parameters, 2) + assert.Equal(t, int64(1618884473), sig.Parameters["created"]) + assert.Equal(t, "test-key-rsa-pss", sig.Parameters["keyid"]) + + assert.Nil(t, sig.Metadata) }, }, { @@ -1473,13 +1651,47 @@ func TestVerifierVerify(t *testing.T) { configureResolver: func(t *testing.T, kr *KeyResolverMock) { t.Helper() - kr.EXPECT().ResolveKey(mock.Anything, "test-key-ecc-p256").Return( - Key{KeyID: "test-key-ecc-p256", Algorithm: EcdsaP256Sha256, Key: tkECCP256}, nil) - }, - assert: func(t *testing.T, err error) { + kr.EXPECT().ResolveKey(mock.Anything, + mock.MatchedBy(func(si SignatureInfo) bool { + return si.Label == "sig-b24" && + si.Message != nil && + len(si.Components) == 4 && + si.Components["@status"] == "200" && + si.Components["content-type"] == "application/json" && + si.Components["content-digest"] == "sha-512=:mEWXIS7MaLRuGgxOBdODa3xqM1XdEvxoYhvlCFJ41QJgJc4GTsPp29l5oGX69wWdXymyU0rjJuahq4l5aGgfLQ==:" && + si.Components["content-length"] == "23" && + si.Parameters["created"] == int64(1618884473) && + si.Parameters["keyid"] == "test-key-ecc-p256" + })). + Return( + KeyInfo{ + Key: Key{Material: tkECCP256, Algorithm: EcdsaP256Sha256}, + Metadata: map[string]int{"foo": 1}, + }, + nil, + ) + }, + assert: func(t *testing.T, err error, results VerificationResult) { t.Helper() require.NoError(t, err) + + require.Len(t, results, 1) + + sig := results[0] + assert.Equal(t, "sig-b24", sig.Label) + + assert.Len(t, sig.Components, 4) + assert.Equal(t, "200", sig.Components["@status"]) + assert.Equal(t, "application/json", sig.Components["content-type"]) + assert.Equal(t, "sha-512=:mEWXIS7MaLRuGgxOBdODa3xqM1XdEvxoYhvlCFJ41QJgJc4GTsPp29l5oGX69wWdXymyU0rjJuahq4l5aGgfLQ==:", sig.Components["content-digest"]) + assert.Equal(t, "23", sig.Components["content-length"]) + + assert.Len(t, sig.Parameters, 2) + assert.Equal(t, int64(1618884473), sig.Parameters["created"]) + assert.Equal(t, "test-key-ecc-p256", sig.Parameters["keyid"]) + + assert.Equal(t, map[string]int{"foo": 1}, sig.Metadata) }, }, { @@ -1508,13 +1720,44 @@ func TestVerifierVerify(t *testing.T) { configureResolver: func(t *testing.T, kr *KeyResolverMock) { t.Helper() - kr.EXPECT().ResolveKey(mock.Anything, "test-shared-secret").Return( - Key{KeyID: "test-shared-secret", Algorithm: HmacSha256, Key: tkMAC}, nil) + kr.EXPECT().ResolveKey(mock.Anything, + mock.MatchedBy(func(si SignatureInfo) bool { + return si.Label == "sig-b25" && + si.Message != nil && + len(si.Components) == 3 && + si.Components["date"] == "Tue, 20 Apr 2021 02:07:55 GMT" && + si.Components["@authority"] == "example.com" && + si.Components["content-type"] == "application/json" && + si.Parameters["created"] == int64(1618884473) && + si.Parameters["keyid"] == "test-shared-secret" + })). + Return( + KeyInfo{ + Key: Key{Material: tkMAC, Algorithm: HmacSha256}, + }, + nil, + ) }, - assert: func(t *testing.T, err error) { + assert: func(t *testing.T, err error, results VerificationResult) { t.Helper() require.NoError(t, err) + + require.Len(t, results, 1) + + sig := results[0] + assert.Equal(t, "sig-b25", sig.Label) + + assert.Len(t, sig.Components, 3) + assert.Equal(t, "Tue, 20 Apr 2021 02:07:55 GMT", sig.Components["date"]) + assert.Equal(t, "example.com", sig.Components["@authority"]) + assert.Equal(t, "application/json", sig.Components["content-type"]) + + assert.Len(t, sig.Parameters, 2) + assert.Equal(t, int64(1618884473), sig.Parameters["created"]) + assert.Equal(t, "test-shared-secret", sig.Parameters["keyid"]) + + assert.Empty(t, sig.Metadata) }, }, { @@ -1544,13 +1787,50 @@ func TestVerifierVerify(t *testing.T) { configureResolver: func(t *testing.T, kr *KeyResolverMock) { t.Helper() - kr.EXPECT().ResolveKey(mock.Anything, "test-key-ed25519").Return( - Key{KeyID: "test-key-ed25519", Algorithm: Ed25519, Key: tkEd25519}, nil) - }, - assert: func(t *testing.T, err error) { + kr.EXPECT().ResolveKey(mock.Anything, + mock.MatchedBy(func(si SignatureInfo) bool { + return si.Label == "sig-b26" && + si.Message != nil && + len(si.Components) == 6 && + si.Components["date"] == "Tue, 20 Apr 2021 02:07:55 GMT" && + si.Components["@method"] == "POST" && + si.Components["@path"] == "/foo" && + si.Components["@authority"] == "example.com" && + si.Components["content-type"] == "application/json" && + si.Components["content-length"] == "18" && + si.Parameters["created"] == int64(1618884473) && + si.Parameters["keyid"] == "test-key-ed25519" + })). + Return( + KeyInfo{ + Key: Key{Material: tkEd25519, Algorithm: Ed25519}, + }, + nil, + ) + }, + assert: func(t *testing.T, err error, results VerificationResult) { t.Helper() require.NoError(t, err) + + require.Len(t, results, 1) + + sig := results[0] + assert.Equal(t, "sig-b26", sig.Label) + + assert.Len(t, sig.Components, 6) + assert.Equal(t, "Tue, 20 Apr 2021 02:07:55 GMT", sig.Components["date"]) + assert.Equal(t, "POST", sig.Components["@method"]) + assert.Equal(t, "/foo", sig.Components["@path"]) + assert.Equal(t, "example.com", sig.Components["@authority"]) + assert.Equal(t, "application/json", sig.Components["content-type"]) + assert.Equal(t, "18", sig.Components["content-length"]) + + assert.Len(t, sig.Parameters, 2) + assert.Equal(t, int64(1618884473), sig.Parameters["created"]) + assert.Equal(t, "test-key-ed25519", sig.Parameters["keyid"]) + + assert.Empty(t, sig.Metadata) }, }, { @@ -1574,14 +1854,33 @@ func TestVerifierVerify(t *testing.T) { configureResolver: func(t *testing.T, kr *KeyResolverMock) { t.Helper() - kr.EXPECT().ResolveKey(mock.Anything, "test-shared-secret").Return( - Key{KeyID: "test-shared-secret", Algorithm: HmacSha256, Key: tkMAC}, nil, - ).Once() + kr.EXPECT().ResolveKey(mock.Anything, mock.Anything). + Return( + KeyInfo{ + Key: Key{Material: tkMAC, Algorithm: HmacSha256}, + Metadata: map[string]string{"foo": "bar"}, + }, + nil, + ).Once() }, - assert: func(t *testing.T, err error) { + assert: func(t *testing.T, err error, results VerificationResult) { t.Helper() require.NoError(t, err) + + require.Len(t, results, 1) + + sig := results[0] + assert.Equal(t, "valid", sig.Label) + + assert.Len(t, sig.Components, 0) + + assert.Len(t, sig.Parameters, 3) + assert.Equal(t, int64(1618884473), sig.Parameters["created"]) + assert.Equal(t, "test-shared-secret", sig.Parameters["keyid"]) + assert.Equal(t, "foo", sig.Parameters["tag"]) + + assert.Equal(t, map[string]string{"foo": "bar"}, sig.Metadata) }, }, { @@ -1605,15 +1904,126 @@ func TestVerifierVerify(t *testing.T) { configureResolver: func(t *testing.T, kr *KeyResolverMock) { t.Helper() - kr.EXPECT().ResolveKey(mock.Anything, "test-shared-secret").Return( - Key{KeyID: "test-shared-secret", Algorithm: HmacSha256, Key: tkMAC}, nil, - ) + kr.EXPECT().ResolveKey(mock.Anything, mock.Anything). + Return( + KeyInfo{ + Key: Key{Material: tkMAC, Algorithm: HmacSha256}, + }, + nil, + ) }, - assert: func(t *testing.T, err error) { + assert: func(t *testing.T, err error, results VerificationResult) { t.Helper() require.ErrorIs(t, err, ErrVerificationFailed) require.ErrorIs(t, err, ErrInvalidSignature) + + require.Empty(t, results) + }, + }, + { + uc: "multiple valid signatures with different keys and metadata", + opts: []VerifierOption{ + WithValidateAllSignatures(), + WithExpiredTimestampRequired(false), + }, + msg: &Message{ + Method: http.MethodPost, + Authority: "example.com", + URL: testURL, + Header: http.Header{ + "Date": []string{"Tue, 20 Apr 2021 02:07:55 GMT"}, + "Content-Type": []string{"application/json"}, + "Content-Length": []string{"18"}, + "Signature-Input": []string{ + `first=("date" "@authority" "content-type");created=1618884473;keyid="test-shared-secret", ` + + `second=("date" "@method" "@path" "@authority" "content-type" "content-length");created=1618884473;keyid="test-key-ed25519"`, + }, + "Signature": []string{ + `first=:pxcQw6G3AjtMBQjwo8XzkZf/bws5LelbaMk5rGIGtE8=:, ` + + `second=:wqcAqbmYJ2ji2glfAMaRy4gruYYnx2nEFN2HN6jrnDnQCK1u02Gb04v9EDgwUPiu4A0w6vuQv5lIp5WPpBKRCw==:`, + }, + }, + IsRequest: true, + }, + configureResolver: func(t *testing.T, kr *KeyResolverMock) { + t.Helper() + + kr.EXPECT().ResolveKey(mock.Anything, + mock.MatchedBy(func(si SignatureInfo) bool { + return si.Label == "first" && + si.Parameters["keyid"] == "test-shared-secret" && + si.Components["date"] == "Tue, 20 Apr 2021 02:07:55 GMT" && + si.Components["@authority"] == "example.com" && + si.Components["content-type"] == "application/json" + })). + Return(KeyInfo{ + Key: Key{Material: tkMAC, Algorithm: HmacSha256}, + Metadata: "hmac", + }, nil). + Once() + + kr.EXPECT().ResolveKey(mock.Anything, + mock.MatchedBy(func(si SignatureInfo) bool { + return si.Label == "second" && + si.Parameters["keyid"] == "test-key-ed25519" && + si.Components["@method"] == "POST" && + si.Components["@path"] == "/foo" && + si.Components["@authority"] == "example.com" + })). + Return(KeyInfo{ + Key: Key{Material: tkEd25519, Algorithm: Ed25519}, + Metadata: "ed25519", + }, nil). + Once() + }, + + assert: func(t *testing.T, err error, results VerificationResult) { + t.Helper() + + require.NoError(t, err) + require.Len(t, results, 2) + + idx := slices.IndexFunc(results, func(sig VerifiedSignature) bool { + return sig.Label == "first" + }) + require.NotEqual(t, -1, idx, "signature with label first not found") + + sig := results[idx] + assert.Equal(t, "first", sig.Label) + + assert.Len(t, sig.Components, 3) + assert.Equal(t, "Tue, 20 Apr 2021 02:07:55 GMT", sig.Components["date"]) + assert.Equal(t, "example.com", sig.Components["@authority"]) + assert.Equal(t, "application/json", sig.Components["content-type"]) + + assert.Len(t, sig.Parameters, 2) + assert.Equal(t, int64(1618884473), sig.Parameters["created"]) + assert.Equal(t, "test-shared-secret", sig.Parameters["keyid"]) + + assert.Equal(t, "hmac", sig.Metadata) + + idx = slices.IndexFunc(results, func(sig VerifiedSignature) bool { + return sig.Label == "second" + }) + require.NotEqual(t, -1, idx, "signature with label second not found") + + sig = results[idx] + assert.Equal(t, "second", sig.Label) + + assert.Len(t, sig.Components, 6) + assert.Equal(t, "Tue, 20 Apr 2021 02:07:55 GMT", sig.Components["date"]) + assert.Equal(t, "POST", sig.Components["@method"]) + assert.Equal(t, "/foo", sig.Components["@path"]) + assert.Equal(t, "example.com", sig.Components["@authority"]) + assert.Equal(t, "application/json", sig.Components["content-type"]) + assert.Equal(t, "18", sig.Components["content-length"]) + + assert.Len(t, sig.Parameters, 2) + assert.Equal(t, int64(1618884473), sig.Parameters["created"]) + assert.Equal(t, "test-key-ed25519", sig.Parameters["keyid"]) + + assert.Equal(t, "ed25519", sig.Metadata) }, }, } { @@ -1624,8 +2034,8 @@ func TestVerifierVerify(t *testing.T) { v, err := NewVerifier(kr, tc.opts...) require.NoError(t, err) - err = v.Verify(tc.msg) - tc.assert(t, err) + results, err := v.Verify(tc.msg) + tc.assert(t, err, results) }) } } From b699c8b2cb601969885093dd75a72eece8b06209 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Thu, 29 Oct 2026 11:03:30 +0100 Subject: [PATCH 02/33] readme updated --- README.md | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 423fb96..b597d13 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,8 @@ To sign an HTTP request, first, create a `Signer` instance using your preferred // Create a signer. signer, err := httpsig.NewSigner( // specify a key - httpsig.Key{KeyID: "key1", Key: privKey, Algorithm: httpsig.EcdsaP256Sha256}, + httpsig.Key{Material: privKey, Algorithm: httpsig.EcdsaP256Sha256}, + httpsig.WithKeyID("key1"), // specify the required options // duration for which the signature should be valid httpsig.WithTTL(5 * time.Second), @@ -52,8 +53,8 @@ verifier, err := httpsig.NewVerifier( // specify the required options // to detect and mitigate replay attacks httpsig.WithNonceChecker(nonceChecker), - // which components are expected to be protected by a signature - httpsig.WithRequiredComponents("@authority", "@method", "x-my-fancy-header"), + // which response components are expected to be protected + httpsig.WithRequiredComponents("@status", "content-type"), // validity time skew httpsig.WithValidityTolerance(5 * time.Second), // how old a signature is allowed to be @@ -63,8 +64,11 @@ verifier, err := httpsig.NewVerifier( ) // error handling -// Verify the response -err := verifier.Verify(httpsig.MessageFromResponse(resp)) +// Verify the response. No partial result is returned on failure. +verified, err := verifier.Verify(httpsig.MessageFromResponse(resp)) +// Each entry in verified contains the covered components, transmitted +// signature parameters, and any metadata returned by the key resolver. + // error handling ``` @@ -91,7 +95,7 @@ verifier, err := httpsig.NewVerifier( ) // error handling goes here -err = verifier.Verify(msg) +verified, err := verifier.Verify(msg) // error handling goes here ``` @@ -135,8 +139,9 @@ On the client side, you can request the server to sign the response by using the ```go // create a builder (all options are optional) builder, err := httpsig.NewAcceptSignature( - // specify which key and key algorithm the server should use for signing the response - httpsig.WithExpectedKey(Key{KeyID: "foo", Algorithm: httpsig.EcdsaP256Sha256}), + // request a key ID and signing algorithm + httpsig.WithExpectedKeyID("foo"), + httpsig.WithExpectedSignatureAlgorithm(httpsig.EcdsaP256Sha256), // specify the NonceSource for the nonce to be added httpsig.WithExpectedNonce(nonceSource), // specify which label should the server use when creating the response @@ -185,8 +190,9 @@ verifier, err := httpsig.NewVerifier( // if there is no signature tagged "myapp", or some of the required components or parameters // are not present, request a signature from the client httpsig.WithSignatureNegotiation( - // specify which key and algorithm the client should use - httpsig.WithRequestedKey(httpsig.Key{KeyID: "key1", Algorithm: httpsig.EcdsaP256Sha256}), + // request a key ID and signature algorithm + httpsig.WithRequestedKeyID("key1"), + httpsig.WithRequestedSignatureAlgorithm(httpsig.EcdsaP256Sha256), // specify the source for the nonce, the client should use httpsig.WithRequestedNonce(nonceGetter), // specify the label for the signature, the client should use @@ -196,7 +202,7 @@ verifier, err := httpsig.NewVerifier( ) // error handling goes here -err = verifier.Verify(msg) +_, err = verifier.Verify(msg) var missingSigErr *httpsig.NoApplicableSignatureError if errors.As(err, &missingSigErr) { From 5dc6d4c652f48ff7a186f99dad9d2a30ab5b45cb Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Thu, 29 Oct 2026 12:05:47 +0100 Subject: [PATCH 03/33] compiling regex only once --- serializer.go | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/serializer.go b/serializer.go index fb73a6a..fb224e7 100644 --- a/serializer.go +++ b/serializer.go @@ -11,6 +11,9 @@ import ( var errSerialization = errors.New("serialization error") +//nolint:gochecknoglobals +var byteSequenceWhitespace = regexp.MustCompile(`\s+`) + type serializer interface { serialize(v []string) ([]string, error) } @@ -51,7 +54,7 @@ func newSerializer(params *httpsfv.Params, isRequest bool) (serializer, error) { case isSf || isKey: return &strictSerializer{key: key}, nil case isBs: - return &byteSequenceSerializer{regex: regexp.MustCompile(`\s+`)}, nil + return &byteSequenceSerializer{}, nil default: return &rawSerializer{}, nil } @@ -63,9 +66,7 @@ func (s *rawSerializer) serialize(v []string) ([]string, error) { return v, nil } -type byteSequenceSerializer struct { - regex *regexp.Regexp -} +type byteSequenceSerializer struct{} func (s *byteSequenceSerializer) serialize(v []string) ([]string, error) { encoded := make([]string, len(v)) @@ -73,7 +74,7 @@ func (s *byteSequenceSerializer) serialize(v []string) ([]string, error) { for i, sv := range v { values := strings.Split(sv, ",") for j, v := range values { - values[j] = s.regex.ReplaceAllString(strings.TrimSpace(v), " ") + values[j] = byteSequenceWhitespace.ReplaceAllString(strings.TrimSpace(v), " ") } item := httpsfv.NewItem([]byte(strings.Join(values, ", "))) From 43620aaa638643f1c7477e0ecdbb93c3858c05f6 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Thu, 29 Oct 2026 12:06:33 +0100 Subject: [PATCH 04/33] reducing allocs while creating ecdsa signature --- asymmetric.go | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/asymmetric.go b/asymmetric.go index 9dc8925..18e047d 100644 --- a/asymmetric.go +++ b/asymmetric.go @@ -8,7 +8,6 @@ import ( "crypto/rsa" "fmt" "math/big" - "slices" ) func newECDSASigner(privateKey *ecdsa.PrivateKey, alg SignatureAlgorithm) (*ecdsaSigner, error) { @@ -74,18 +73,12 @@ func (ecs *ecdsaSigner) signPayload(payload []byte) ([]byte, error) { keyBytes++ } - // We serialize the outputs (r and s) into big-endian byte arrays and pad - // them with zeros on the left to make sure the sizes work out. Both arrays - // must be keyBytes long, and the output must be 2*keyBytes long. - rBytes := r.Bytes() - rBytesPadded := make([]byte, keyBytes) - copy(rBytesPadded[keyBytes-len(rBytes):], rBytes) + // Encode r and s as fixed-width, zero-padded, big-endian integers. + signature := make([]byte, 2*keyBytes) //nolint:mnd + r.FillBytes(signature[:keyBytes]) + s.FillBytes(signature[keyBytes:]) - sBytes := s.Bytes() - sBytesPadded := make([]byte, keyBytes) - copy(sBytesPadded[keyBytes-len(sBytes):], sBytes) - - return slices.Concat(rBytesPadded, sBytesPadded), nil + return signature, nil } func newRSASigner(privateKey *rsa.PrivateKey, alg SignatureAlgorithm) (*rsaSigner, error) { From a7ff4caa6afdddfb63835b408364af7996aea7d3 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Thu, 29 Oct 2026 12:07:36 +0100 Subject: [PATCH 05/33] not cloning []byte params any more --- signature_input.go | 3 --- 1 file changed, 3 deletions(-) diff --git a/signature_input.go b/signature_input.go index eacbcb6..45dd177 100644 --- a/signature_input.go +++ b/signature_input.go @@ -1,7 +1,6 @@ package httpsig import ( - "bytes" "fmt" "slices" "time" @@ -62,8 +61,6 @@ func (si *signatureInput) parameters() SignatureParameters { value = Token(v) case httpsfv.DisplayString: value = string(v) - case []byte: - value = bytes.Clone(v) } result[name] = value From 2f621b1a3daaa521af12fdf5d75b0d41b66ab01c Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Thu, 29 Oct 2026 15:29:48 +0100 Subject: [PATCH 06/33] made signature base usage more efficient --- signature_base.go | 75 +++++++++--------- signature_base_test.go | 167 +++++++++++------------------------------ 2 files changed, 85 insertions(+), 157 deletions(-) diff --git a/signature_base.go b/signature_base.go index 23afc74..1b02346 100644 --- a/signature_base.go +++ b/signature_base.go @@ -8,87 +8,94 @@ import ( "github.com/dunglas/httpsfv" ) -type signatureBase []component +type serializedComponent struct { + identifier string + value string +} + +// The entries correspond to input.identifiers by index. Signature parameters are separate. +type signatureBase struct { + input *signatureInput + entries []serializedComponent + signatureParams string +} func newSignatureBase(si *signatureInput, msg *Message) (signatureBase, error) { marshalledSigParams, err := httpsfv.Marshal(si.value) if err != nil { - return nil, err + return signatureBase{}, err } - sigBase := make(signatureBase, 0, len(si.identifiers)+1) + sigBase := signatureBase{ + input: si, + entries: make([]serializedComponent, 0, len(si.identifiers)), + signatureParams: marshalledSigParams, + } seen := make(map[string]struct{}, len(si.identifiers)) for _, ci := range si.identifiers { identifier, err := httpsfv.Marshal(ci.Item) if err != nil { - return nil, err + return signatureBase{}, err } if _, ok := seen[identifier]; ok { - return nil, fmt.Errorf("%w: duplicate component identifier %s", ErrMalformedData, identifier) + return signatureBase{}, fmt.Errorf("%w: duplicate component identifier %s", ErrMalformedData, identifier) } seen[identifier] = struct{}{} comp, err := ci.createComponent(msg) if err != nil { - return nil, err + return signatureBase{}, err } - sigBase = append(sigBase, comp) + sigBase.entries = append(sigBase.entries, serializedComponent{ + identifier: identifier, + value: comp.canonicalValue(), + }) } - sigBase = append(sigBase, component{ - key: &componentIdentifier{Item: httpsfv.NewItem("@signature-params")}, - value: []string{marshalledSigParams}, - }) - return sigBase, nil } func (s signatureBase) marshal() ([]byte, error) { var buf bytes.Buffer - for i, item := range s { - marshalledKey, err := httpsfv.Marshal(item.key.Item) - if err != nil { - return nil, err - } - + for i, item := range s.entries { if i > 0 { buf.WriteByte('\n') } - buf.WriteString(marshalledKey) + buf.WriteString(item.identifier) buf.WriteString(": ") - buf.WriteString(item.canonicalValue()) + buf.WriteString(item.value) + } + + if s.signatureParams != "" { + if len(s.entries) > 0 { + buf.WriteByte('\n') + } + + buf.WriteString(`"@signature-params": `) + buf.WriteString(s.signatureParams) } return buf.Bytes(), nil } func (s signatureBase) components() (map[string]string, error) { - result := make(map[string]string, len(s)) - - for _, component := range s { - name := component.key.Value.(string) // nolint: forcetypeassert + result := make(map[string]string, len(s.entries)) - if name == "@signature-params" { - continue - } - - identifier, err := httpsfv.Marshal(component.key.Item) - if err != nil { - return nil, err - } + for i, item := range s.entries { + name := s.input.identifiers[i].Value.(string) // nolint: forcetypeassert // Remove quotes around the component name, // preserving identifier parameters. prefix := `"` + name + `"` - key := name + strings.TrimPrefix(identifier, prefix) + key := name + strings.TrimPrefix(item.identifier, prefix) - result[key] = component.canonicalValue() + result[key] = item.value } return result, nil diff --git a/signature_base_test.go b/signature_base_test.go index 3078f49..dcbb9e5 100644 --- a/signature_base_test.go +++ b/signature_base_test.go @@ -148,21 +148,14 @@ func TestNewSignatureBase(t *testing.T) { func TestSignatureBaseMarshal(t *testing.T) { t.Parallel() - msg := &Message{Method: "GET", Authority: "foo.bar", IsRequest: true} - - ci, err := toComponentIdentifiers([]string{"@authority", "@method"}) - require.NoError(t, err) - - list := make(signatureBase, len(ci)) - - for i, id := range ci { - c, err := id.createComponent(msg) - require.NoError(t, err) - - list[i] = c + base := signatureBase{ + entries: []serializedComponent{ + {identifier: `"@authority"`, value: "foo.bar"}, + {identifier: `"@method"`, value: "GET"}, + }, } - res, err := list.marshal() + res, err := base.marshal() require.NoError(t, err) assert.Equal(t, "\"@authority\": foo.bar\n\"@method\": GET", string(res)) @@ -171,66 +164,27 @@ func TestSignatureBaseMarshal(t *testing.T) { func TestSignatureBaseComponents(t *testing.T) { t.Parallel() - petParams := httpsfv.NewParams() - petParams.Add("name", "Pet") - - catParams := httpsfv.NewParams() - catParams.Add("name", "Cat") - - agentParams := httpsfv.NewParams() - agentParams.Add("key", "sig1") - - sfParams := httpsfv.NewParams() - sfParams.Add("sf", true) - for uc, tc := range map[string]struct { - base signatureBase - expected map[string]string + names []string + entries []serializedComponent + signatureParams string + expected map[string]string }{ "empty signature base": { - base: signatureBase{}, expected: map[string]string{}, }, "excluding signature parameters": { - base: signatureBase{ - { - key: &componentIdentifier{ - Item: httpsfv.NewItem("@signature-params"), - }, - value: []string{`("@method");created=123`}, - }, - }, - expected: map[string]string{}, + signatureParams: `("@method");created=123`, + expected: map[string]string{}, }, "simple component identifiers": { - base: signatureBase{ - { - key: &componentIdentifier{ - Item: httpsfv.NewItem("@method"), - }, - value: []string{"GET"}, - }, - { - key: &componentIdentifier{ - Item: httpsfv.NewItem("@authority"), - }, - value: []string{"example.com"}, - }, - { - key: &componentIdentifier{ - Item: httpsfv.NewItem("user-agent"), - }, - value: []string{"ExampleBot/1.0"}, - }, - { - key: &componentIdentifier{ - Item: httpsfv.NewItem("@signature-params"), - }, - value: []string{ - `("@method" "@authority" "user-agent")`, - }, - }, + names: []string{"@method", "@authority", "user-agent"}, + entries: []serializedComponent{ + {identifier: `"@method"`, value: "GET"}, + {identifier: `"@authority"`, value: "example.com"}, + {identifier: `"user-agent"`, value: "ExampleBot/1.0"}, }, + signatureParams: `("@method" "@authority" "user-agent")`, expected: map[string]string{ "@method": "GET", "@authority": "example.com", @@ -238,36 +192,11 @@ func TestSignatureBaseComponents(t *testing.T) { }, }, "parameterized component identifiers": { - base: signatureBase{ - { - key: &componentIdentifier{ - Item: httpsfv.Item{ - Value: "@query-param", - Params: petParams, - }, - }, - value: []string{"dog"}, - }, - { - key: &componentIdentifier{ - Item: httpsfv.Item{ - Value: "@query-param", - Params: catParams, - }, - }, - value: []string{"meow"}, - }, - { - key: &componentIdentifier{ - Item: httpsfv.Item{ - Value: "signature-agent", - Params: agentParams, - }, - }, - value: []string{ - `"https://bots.example.com";type=cimd`, - }, - }, + names: []string{"@query-param", "@query-param", "signature-agent"}, + entries: []serializedComponent{ + {identifier: `"@query-param";name="Pet"`, value: "dog"}, + {identifier: `"@query-param";name="Cat"`, value: "meow"}, + {identifier: `"signature-agent";key="sig1"`, value: `"https://bots.example.com";type=cimd`}, }, expected: map[string]string{ `@query-param;name="Pet"`: "dog", @@ -276,46 +205,27 @@ func TestSignatureBaseComponents(t *testing.T) { }, }, "boolean identifier parameter": { - base: signatureBase{ - { - key: &componentIdentifier{ - Item: httpsfv.Item{ - Value: "content-type", - Params: sfParams, - }, - }, - value: []string{"application/json"}, - }, + names: []string{"content-type"}, + entries: []serializedComponent{ + {identifier: `"content-type";sf`, value: "application/json"}, }, expected: map[string]string{ "content-type;sf": "application/json", }, }, "multiple canonicalized values": { - base: signatureBase{ - { - key: &componentIdentifier{ - Item: httpsfv.NewItem("x-example"), - }, - value: []string{ - "first", - "second", - "third", - }, - }, + names: []string{"x-example"}, + entries: []serializedComponent{ + {identifier: `"x-example"`, value: "first, second, third"}, }, expected: map[string]string{ "x-example": "first, second, third", }, }, "empty canonicalized value": { - base: signatureBase{ - { - key: &componentIdentifier{ - Item: httpsfv.NewItem("x-empty"), - }, - value: []string{""}, - }, + names: []string{"x-empty"}, + entries: []serializedComponent{ + {identifier: `"x-empty"`, value: ""}, }, expected: map[string]string{ "x-empty": "", @@ -325,7 +235,18 @@ func TestSignatureBaseComponents(t *testing.T) { t.Run(uc, func(t *testing.T) { t.Parallel() - components, err := tc.base.components() + identifiers := make([]*componentIdentifier, len(tc.names)) + for i, name := range tc.names { + identifiers[i] = &componentIdentifier{Item: httpsfv.NewItem(name)} + } + + base := signatureBase{ + input: &signatureInput{identifiers: identifiers}, + entries: tc.entries, + signatureParams: tc.signatureParams, + } + + components, err := base.components() require.NoError(t, err) assert.Equal(t, tc.expected, components) From 04c19d924791beb0e7135bb95336d0bf6e8f77a3 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Thu, 29 Oct 2026 18:39:22 +0100 Subject: [PATCH 07/33] new WithAlg option --- patch.go | 8 ++------ signer.go | 47 ++++++++++++++++++++++++++++++++--------------- signer_test.go | 28 ++++++++++++++++++++++++++-- 3 files changed, 60 insertions(+), 23 deletions(-) diff --git a/patch.go b/patch.go index 196782e..b4290dc 100644 --- a/patch.go +++ b/patch.go @@ -2,11 +2,7 @@ package httpsig import "time" -// replaced in tests to have the behavior required to use/verify -// vectors data provided in RFC9421 +// replaced in tests to use the timestamps from the RFC 9421 test vectors. // //nolint:gochecknoglobals -var ( - currentTime = time.Now - filterAlgorithm = func(alg SignatureAlgorithm) SignatureAlgorithm { return alg } -) +var currentTime = time.Now diff --git a/signer.go b/signer.go index 9c4a01f..30ea197 100644 --- a/signer.go +++ b/signer.go @@ -12,7 +12,6 @@ import ( "github.com/dunglas/httpsfv" ) - type payloadSigner interface { signPayload(data []byte) ([]byte, error) algorithm() SignatureAlgorithm @@ -137,12 +136,20 @@ func WithKeyID(keyID string) SignerOption { } } +// WithAlg includes the alg signature parameter using Key.Algorithm. +// By default, alg is omitted. +func WithAlg() SignerOption { + return func(s *signer) error { + s.includeAlg = true + + return nil + } +} + // NewSigner creates a Signer using key for cryptographic signing. The key // must contain private or symmetric material compatible with its algorithm. // By default, the generated signature uses label "sig", includes a created -// timestamp and a random nonce, expires after 30 seconds, and includes the -// selected key algorithm in the alg signature parameter. Use options to -// select covered components and other signature parameters. +// timestamp and a random nonce, and expires after 30 seconds. func NewSigner(key Key, opts ...SignerOption) (Signer, error) { ps, err := newPayloadSigner(key.Material, key.Algorithm) if err != nil { @@ -163,6 +170,15 @@ func NewSigner(key Key, opts ...SignerOption) (Signer, error) { } } + if sig.includeAlg { + switch sig.ps.algorithm() { + case RsaPssSha512, RsaPkcs1v15Sha256, HmacSha256, EcdsaP256Sha256, EcdsaP384Sha384, Ed25519: + default: + return nil, fmt.Errorf("%w: %s is not registered for HTTP Message Signatures", + ErrUnsupportedAlgorithm, sig.ps.algorithm()) + } + } + var cmv compositeMessageUpdater for _, id := range sig.ids { @@ -181,15 +197,16 @@ func NewSigner(key Key, opts ...SignerOption) (Signer, error) { } type signer struct { - label string - ids []*componentIdentifier - ttl time.Duration - tag string - keyID string - ng NonceGetter - ps payloadSigner - cdAlg DigestAlgorithm - mu messageUpdater + label string + ids []*componentIdentifier + ttl time.Duration + tag string + keyID string + includeAlg bool + ng NonceGetter + ps payloadSigner + cdAlg DigestAlgorithm + mu messageUpdater } func (s *signer) Sign(msg *Message) (http.Header, error) { @@ -239,8 +256,8 @@ func (s *signer) signatureInput(ctx context.Context) (*signatureInput, error) { params.Add(string(KeyID), keyID) } - if alg := filterAlgorithm(s.ps.algorithm()); alg != "" { - params.Add(string(Alg), string(alg)) + if s.includeAlg { + params.Add(string(Alg), string(s.ps.algorithm())) } if len(nonce) != 0 { diff --git a/signer_test.go b/signer_test.go index 426dff9..3520234 100644 --- a/signer_test.go +++ b/signer_test.go @@ -225,6 +225,16 @@ func TestNewSigner(t *testing.T) { require.ErrorIs(t, err, ErrUnsupportedComponentIdentifier) }, }, + { + uc: "alg parameter requires a registered algorithm", + key: Key{Algorithm: HmacSha384, Material: []byte("secret")}, + opts: []SignerOption{WithAlg()}, + assert: func(t *testing.T, err error, _ Signer) { + t.Helper() + + require.ErrorIs(t, err, ErrUnsupportedAlgorithm) + }, + }, { uc: "successful without configuration", key: Key{Algorithm: EcdsaP384Sha384, Material: pkp384}, @@ -282,11 +292,9 @@ func TestNewSigner(t *testing.T) { func TestSignerSign(t *testing.T) { // used by RFC9421 in test vectors currentTime = func() time.Time { return time.Unix(1618884473, 0) } - filterAlgorithm = func(_ SignatureAlgorithm) SignatureAlgorithm { return "" } t.Cleanup(func() { currentTime = time.Now - filterAlgorithm = func(alg SignatureAlgorithm) SignatureAlgorithm { return alg } }) pkp384, err := ecdsa.GenerateKey(elliptic.P384(), rand.Reader) @@ -413,6 +421,22 @@ func TestSignerSign(t *testing.T) { require.Error(t, err) }, }, + { + uc: "include alg parameter when requested", + key: Key{Algorithm: HmacSha256, Material: tkMAC}, + opts: []SignerOption{ + WithAlg(), + WithTTL(0), + WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), + }, + msg: &Message{Header: http.Header{}, IsRequest: true}, + assert: func(t *testing.T, err error, header http.Header) { + t.Helper() + + require.NoError(t, err) + assert.Equal(t, `sig=();created=1618884473;alg="hmac-sha256"`, header.Get("Signature-Input")) + }, + }, { // https://www.rfc-editor.org/rfc/rfc9421.html#name-minimal-signature-using-rsa uc: "B.2.1. minimal signature using rsa-pss-sha512", From 6c6635bfb42b42817500f9161030806c86cf82a4 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Thu, 29 Oct 2026 18:54:11 +0100 Subject: [PATCH 08/33] not allowing empty tag for the WithRequiredTag option --- verifier.go | 6 ++++-- verifier_test.go | 14 ++++++++++++++ 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/verifier.go b/verifier.go index 63b1fa8..f25cb14 100644 --- a/verifier.go +++ b/verifier.go @@ -101,14 +101,16 @@ func WithNonceChecker(checker NonceChecker) VerifierOption { // WithRequiredTag selects signatures with the given application tag and // applies opts to that signature. Global options in NewVerifier provide // defaults for unspecified per-tag requirements. Each tag may be configured -// only once. +// only once. An empty tag is not allowed. func WithRequiredTag(tag string, opts ...VerifierOption) VerifierOption { return func(ver *verifier, _ *expectations, f bool) error { if f { panic("WithRequiredTag cannot be used as option for itself") } - // TODO: check if the tag is empty, which is reserved for global expectations. such tag is not allowed + if len(tag) == 0 { + return fmt.Errorf("%w: required tag must not be empty", ErrParameter) + } if _, configured := ver.tagExpectations[tag]; configured { return fmt.Errorf("%w: requirements for tag %s are already configured", ErrParameter, tag) diff --git a/verifier_test.go b/verifier_test.go index 22b75b1..497e407 100644 --- a/verifier_test.go +++ b/verifier_test.go @@ -759,6 +759,20 @@ func TestNewVerifier(t *testing.T) { require.ErrorContains(t, err, "unsupported component identifier: @foo") }, }, + { + uc: "with empty required tag", + resolver: &KeyResolverMock{}, + opts: []VerifierOption{ + WithRequiredTag(""), + }, + assert: func(t *testing.T, err error, _ *verifier) { + t.Helper() + + require.ErrorIs(t, err, ErrVerifierCreation) + require.ErrorIs(t, err, ErrParameter) + require.ErrorContains(t, err, "required tag must not be empty") + }, + }, { uc: "cannot verify and negotiate any possible signature", resolver: &KeyResolverMock{}, From 2ec2d85271a53eb9bc71b08309098d2eb9fcf849 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Sat, 31 Oct 2026 08:41:03 +0100 Subject: [PATCH 09/33] timestamp related TODOs removed --- verifier.go | 3 --- 1 file changed, 3 deletions(-) diff --git a/verifier.go b/verifier.go index f25cb14..90a41af 100644 --- a/verifier.go +++ b/verifier.go @@ -148,7 +148,6 @@ func WithValidateAllSignatures() VerifierOption { // be present. If present, it is still checked even when flag is false. // NewVerifier requires created by default. func WithCreatedTimestampRequired(flag bool) VerifierOption { - // TODO: Same challenge as WithExpiredTimestampRequired return func(_ *verifier, exp *expectations, _ bool) error { exp.reqCreatedTS = &flag @@ -160,8 +159,6 @@ func WithCreatedTimestampRequired(flag bool) VerifierOption { // be present. If present, it is still checked even when flag is false. // NewVerifier requires expires by default. func WithExpiredTimestampRequired(flag bool) VerifierOption { - // TODO: if the flag is false, then the expires parameter must not be present in the signature. This must be checked. - // There is a need to think more about the semantics as different rfcs have different requirements on that parameter return func(_ *verifier, exp *expectations, _ bool) error { exp.reqExpiresTS = &flag From 59815af4403f65f5b3b12019eaf49bc07d62f13f Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Mon, 2 Nov 2026 14:00:11 +0100 Subject: [PATCH 10/33] options refactored --- README.md | 26 +- accept_signature_builder.go | 123 +------ accept_signature_builder_test.go | 78 ++--- doc.go | 19 -- options.go | 559 +++++++++++++++++++++++++++++++ signer.go | 155 +++------ signer_test.go | 265 ++++++++++++++- verifier.go | 201 +---------- verifier_test.go | 114 +++---- 9 files changed, 965 insertions(+), 575 deletions(-) delete mode 100644 doc.go create mode 100644 options.go diff --git a/README.md b/README.md index b597d13..5c6a602 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ verifier, err := httpsig.NewVerifier( // to detect and mitigate replay attacks httpsig.WithNonceChecker(nonceChecker), // which response components are expected to be protected - httpsig.WithRequiredComponents("@status", "content-type"), + httpsig.WithComponents("@status", "content-type"), // validity time skew httpsig.WithValidityTolerance(5 * time.Second), // how old a signature is allowed to be @@ -86,7 +86,7 @@ verifier, err := httpsig.NewVerifier( // tag of the signature "myapp", // which components are expected to be protected by a signature - httpsig.WithRequiredComponents("@authority", "@method", "x-my-fancy-header"), + httpsig.WithComponents("@authority", "@method", "x-my-fancy-header"), // validity time skew httpsig.WithValidityTolerance(5 * time.Second), // how old a signature is allowed to be @@ -140,22 +140,22 @@ On the client side, you can request the server to sign the response by using the // create a builder (all options are optional) builder, err := httpsig.NewAcceptSignature( // request a key ID and signing algorithm - httpsig.WithExpectedKeyID("foo"), - httpsig.WithExpectedSignatureAlgorithm(httpsig.EcdsaP256Sha256), + httpsig.WithKeyID("foo"), + httpsig.WithSignatureAlgorithm(httpsig.EcdsaP256Sha256), // specify the NonceSource for the nonce to be added httpsig.WithExpectedNonce(nonceSource), // specify which label should the server use when creating the response - httpsig.WithExpectedLabel("bar"), + httpsig.WithLabel("bar"), // specify which components should be covered by the signature - httpsig.WithExpectedComponents("@status", "content-digest;req", "content-digest"), + httpsig.WithComponents("@status", "content-digest;req", "content-digest"), // specify your content digest algorithm references httpsig.WithContentDigestAlgorithmPreferences(httpsig.AlgorithmPreference{Algorithm: httpsig.Sha256, Preference: 2}), // specify which tag the server should use - httpsig.WithExpectedTag("awesome-app"), + httpsig.WithTag("awesome-app"), // specify whether you want the created time stamp to be included - httpsig.WithExpectedCreatedTimestamp(true), + httpsig.WithCreatedTimestamp(true), // specify whether you want the expires time stamp to be included - httpsig.WithExpectedExpiresTimestamp(true), + httpsig.WithExpiredTimestamp(true), ) // error handling goes here @@ -182,7 +182,7 @@ verifier, err := httpsig.NewVerifier( // tag of the signature "myapp", // which components are expected to be protected by a signature - httpsig.WithRequiredComponents("@authority", "@method", "x-my-fancy-header"), + httpsig.WithComponents("@authority", "@method", "x-my-fancy-header"), // validity time skew httpsig.WithValidityTolerance(5 * time.Second), // how old a signature is allowed to be @@ -191,12 +191,12 @@ verifier, err := httpsig.NewVerifier( // are not present, request a signature from the client httpsig.WithSignatureNegotiation( // request a key ID and signature algorithm - httpsig.WithRequestedKeyID("key1"), - httpsig.WithRequestedSignatureAlgorithm(httpsig.EcdsaP256Sha256), + httpsig.WithKeyID("key1"), + httpsig.WithSignatureAlgorithm(httpsig.EcdsaP256Sha256), // specify the source for the nonce, the client should use httpsig.WithRequestedNonce(nonceGetter), // specify the label for the signature, the client should use - httpsig.WithRequestedLabel("bar"), + httpsig.WithLabel("bar"), ), ), ) diff --git a/accept_signature_builder.go b/accept_signature_builder.go index 0a28c39..bdafe2e 100644 --- a/accept_signature_builder.go +++ b/accept_signature_builder.go @@ -8,127 +8,6 @@ import ( "github.com/dunglas/httpsfv" ) -// AcceptSignatureOption configures the Accept-Signature request produced by -// NewAcceptSignature and AcceptSignatureBuilder.Build. -type AcceptSignatureOption func(*AcceptSignatureBuilder) error - -// WithExpectedSignatureAlgorithm requests that the peer use alg when signing. -// It adds the alg parameter to Accept-Signature. -func WithExpectedSignatureAlgorithm(alg SignatureAlgorithm) AcceptSignatureOption { - return func(asb *AcceptSignatureBuilder) error { - asb.signatureAlgorithm = alg - - return nil - } -} - -// WithExpectedKeyID requests keyID as the keyid signature parameter in the -// peer's response. An empty ID is omitted by the generated header. -func WithExpectedKeyID(keyID string) AcceptSignatureOption { - return func(asb *AcceptSignatureBuilder) error { - asb.keyID = keyID - - return nil - } -} - -// WithExpectedNonce supplies the nonce source for Accept-Signature. -// If ng is nil, the default random nonce source remains in use. -func WithExpectedNonce(ng NonceGetter) AcceptSignatureOption { - // TODO: What can we do for profiles which make use of nonces but in a different parameter - return func(asb *AcceptSignatureBuilder) error { - if ng != nil { - asb.nonceGetter = ng - } - - return nil - } -} - -// WithExpectedLabel sets the dictionary label for Accept-Signature. -// An empty label is ignored. The label is a technical reference, not an -// authenticated identifier, and may be changed by intermediaries. -func WithExpectedLabel(label string) AcceptSignatureOption { - return func(asb *AcceptSignatureBuilder) error { - if len(label) != 0 { - asb.label = label - } - - return nil - } -} - -// WithExpectedComponents requests a signature covering the listed HTTP -// fields and derived components. If content-digest is among them, Build also -// adds Want-Content-Digest according to the configured preferences. -func WithExpectedComponents(identifiers ...string) AcceptSignatureOption { - return func(asb *AcceptSignatureBuilder) error { - identifiers, err := toComponentIdentifiers(identifiers) - if err != nil { - return err - } - - asb.setIdentifiers(identifiers) - - return nil - } -} - -// WithContentDigestAlgorithmPreferences sets the preferred digest algorithms -// for Want-Content-Digest when a covered content-digest component is requested. -// Supplying no preferences leaves the defaults unchanged. -func WithContentDigestAlgorithmPreferences(prefs ...AlgorithmPreference) AcceptSignatureOption { - return func(asb *AcceptSignatureBuilder) error { - if len(prefs) == 0 { - return nil - } - - algPrefs := make([]string, len(prefs)) - - for i, pref := range prefs { - if pref.Algorithm == "" { - return fmt.Errorf("%w: digest algorithm preference requires a non-empty algorithm", ErrParameter) - } - - algPrefs[i] = pref.String() - } - - asb.cdAlgPrefs = algPrefs - - return nil - } -} - -// WithExpectedTag requests an application-defined tag on the signature. -// An empty tag is omitted from the generated Accept-Signature field. -func WithExpectedTag(tag string) AcceptSignatureOption { - return func(asb *AcceptSignatureBuilder) error { - asb.tag = tag - - return nil - } -} - -// WithExpectedCreatedTimestamp requests that a signature contain created. -// The request is enabled by default; false removes the requirement. -func WithExpectedCreatedTimestamp(flag bool) AcceptSignatureOption { - return func(asb *AcceptSignatureBuilder) error { - asb.addCreatedTS = flag - - return nil - } -} - -// WithExpectedExpiresTimestamp requests that a signature contain expires. -// The request is enabled by default; false removes the requirement. -func WithExpectedExpiresTimestamp(flag bool) AcceptSignatureOption { - return func(asb *AcceptSignatureBuilder) error { - asb.addExpiresTS = flag - - return nil - } -} - // AlgorithmPreference associates a Content-Digest algorithm with a numeric // preference value for the Want-Content-Digest header. type AlgorithmPreference struct { @@ -176,7 +55,7 @@ func NewAcceptSignature(opts ...AcceptSignatureOption) (*AcceptSignatureBuilder, } for _, opt := range opts { - if err := opt(asb); err != nil { + if err := opt.applyAcceptSignatureOption(asb); err != nil { return nil, err } } diff --git a/accept_signature_builder_test.go b/accept_signature_builder_test.go index 73a6105..d69454a 100644 --- a/accept_signature_builder_test.go +++ b/accept_signature_builder_test.go @@ -10,7 +10,7 @@ import ( "github.com/stretchr/testify/require" ) -func TestWithExpectedSignatureAlgorithm(t *testing.T) { +func TestWithSignatureAlgorithmForAcceptSignature(t *testing.T) { t.Parallel() for uc, alg := range map[string]SignatureAlgorithm{ @@ -20,7 +20,7 @@ func TestWithExpectedSignatureAlgorithm(t *testing.T) { t.Run(uc, func(t *testing.T) { asb := &AcceptSignatureBuilder{} - err := WithExpectedSignatureAlgorithm(alg)(asb) + err := WithSignatureAlgorithm(alg).applyAcceptSignatureOption(asb) require.NoError(t, err) assert.Equal(t, alg, asb.signatureAlgorithm) @@ -28,7 +28,7 @@ func TestWithExpectedSignatureAlgorithm(t *testing.T) { } } -func TestWithExpectedKeyID(t *testing.T) { +func TestWithKeyIDForAcceptSignature(t *testing.T) { t.Parallel() for uc, keyID := range map[string]string{ @@ -38,7 +38,7 @@ func TestWithExpectedKeyID(t *testing.T) { t.Run(uc, func(t *testing.T) { asb := &AcceptSignatureBuilder{} - err := WithExpectedKeyID(keyID)(asb) + err := WithKeyID(keyID).applyAcceptSignatureOption(asb) require.NoError(t, err) assert.Equal(t, keyID, asb.keyID) @@ -60,7 +60,7 @@ func TestWithExpectedNonce(t *testing.T) { t.Run(tc.uc, func(t *testing.T) { asb := &AcceptSignatureBuilder{nonceGetter: nonceGetter{}} - err := WithExpectedNonce(tc.ng)(asb) + err := WithExpectedNonce(tc.ng).applyAcceptSignatureOption(asb) require.NoError(t, err) assert.Equal(t, tc.exp, asb.nonceGetter) @@ -68,7 +68,7 @@ func TestWithExpectedNonce(t *testing.T) { } } -func TestWithExpectedLabel(t *testing.T) { +func TestWithLabelForAcceptSignature(t *testing.T) { t.Parallel() for _, tc := range []struct { @@ -82,7 +82,7 @@ func TestWithExpectedLabel(t *testing.T) { t.Run(tc.uc, func(t *testing.T) { asb := &AcceptSignatureBuilder{label: "foo"} - err := WithExpectedLabel(tc.label)(asb) + err := WithLabel(tc.label).applyAcceptSignatureOption(asb) require.NoError(t, err) assert.Equal(t, tc.exp, asb.label) @@ -90,7 +90,7 @@ func TestWithExpectedLabel(t *testing.T) { } } -func TestWithExpectedComponents(t *testing.T) { +func TestWithComponentsForAcceptSignature(t *testing.T) { t.Parallel() for _, tc := range []struct { @@ -149,7 +149,7 @@ func TestWithExpectedComponents(t *testing.T) { t.Run(tc.uc, func(t *testing.T) { asb := &AcceptSignatureBuilder{label: "foo"} - err := WithExpectedComponents(tc.identifiers...)(asb) + err := WithComponents(tc.identifiers...).applyAcceptSignatureOption(asb) tc.assert(t, err, asb) }) @@ -191,7 +191,7 @@ func TestWithContentDigestAlgorithmPreferences(t *testing.T) { cdAlgPrefs: []string{defaultPreference}, } - err := WithContentDigestAlgorithmPreferences(tc.prefs...)(asb) + err := WithContentDigestAlgorithmPreferences(tc.prefs...).applyAcceptSignatureOption(asb) if tc.expErr != nil { require.Error(t, err) @@ -204,7 +204,7 @@ func TestWithContentDigestAlgorithmPreferences(t *testing.T) { } } -func TestWithExpectedTag(t *testing.T) { +func TestWithTagForAcceptSignature(t *testing.T) { t.Parallel() for _, tc := range []struct { @@ -217,7 +217,7 @@ func TestWithExpectedTag(t *testing.T) { t.Run(tc.uc, func(t *testing.T) { asb := &AcceptSignatureBuilder{} - err := WithExpectedTag(tc.tag)(asb) + err := WithTag(tc.tag).applyAcceptSignatureOption(asb) require.NoError(t, err) assert.Equal(t, tc.tag, asb.tag) @@ -225,23 +225,23 @@ func TestWithExpectedTag(t *testing.T) { } } -func TestWithExpectedCreatedTimestamp(t *testing.T) { +func TestWithCreatedTimestampForAcceptSignature(t *testing.T) { t.Parallel() asb := &AcceptSignatureBuilder{addCreatedTS: true} - err := WithExpectedCreatedTimestamp(false)(asb) + err := WithCreatedTimestamp(false).applyAcceptSignatureOption(asb) require.NoError(t, err) assert.False(t, asb.addCreatedTS) } -func TestWithExpectedExpiresTimestamp(t *testing.T) { +func TestWithExpiredTimestampForAcceptSignature(t *testing.T) { t.Parallel() asb := &AcceptSignatureBuilder{addExpiresTS: true} - err := WithExpectedExpiresTimestamp(false)(asb) + err := WithExpiredTimestamp(false).applyAcceptSignatureOption(asb) require.NoError(t, err) assert.False(t, asb.addExpiresTS) @@ -279,15 +279,15 @@ func TestNewAcceptedSignature(t *testing.T) { { uc: "all possible options provided", opts: []AcceptSignatureOption{ - WithExpectedSignatureAlgorithm(EcdsaP256Sha256), - WithExpectedKeyID("test"), + WithSignatureAlgorithm(EcdsaP256Sha256), + WithKeyID("test"), WithExpectedNonce(&NonceGetterMock{}), - WithExpectedLabel("foo"), - WithExpectedComponents("@status", "content-digest;req"), + WithLabel("foo"), + WithComponents("@status", "content-digest;req"), WithContentDigestAlgorithmPreferences(AlgorithmPreference{Sha512, 10}), - WithExpectedTag("bar"), - WithExpectedCreatedTimestamp(false), - WithExpectedExpiresTimestamp(false), + WithTag("bar"), + WithCreatedTimestamp(false), + WithExpiredTimestamp(false), }, assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) { t.Helper() @@ -312,7 +312,7 @@ func TestNewAcceptedSignature(t *testing.T) { { uc: "option raises error", opts: []AcceptSignatureOption{ - WithExpectedComponents("@foo"), + WithComponents("@foo"), }, assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) { t.Helper() @@ -356,11 +356,11 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { { uc: "Accept-Signature only is added", opts: []AcceptSignatureOption{ - WithExpectedSignatureAlgorithm(EcdsaP256Sha256), - WithExpectedKeyID("test"), - WithExpectedComponents("@status", "x-foo-bar;req", "@method"), - WithExpectedLabel("foo"), - WithExpectedTag("bar"), + WithSignatureAlgorithm(EcdsaP256Sha256), + WithKeyID("test"), + WithComponents("@status", "x-foo-bar;req", "@method"), + WithLabel("foo"), + WithTag("bar"), WithExpectedNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), }, assert: func(t *testing.T, err error, hdr http.Header) { @@ -378,11 +378,11 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { { uc: "Accept-Signature and Want-Content-Digest headers are added with default algorithms", opts: []AcceptSignatureOption{ - WithExpectedSignatureAlgorithm(EcdsaP256Sha256), - WithExpectedKeyID("test"), - WithExpectedComponents("@status", "content-digest", "@method"), - WithExpectedLabel("foo"), - WithExpectedTag("bar"), + WithSignatureAlgorithm(EcdsaP256Sha256), + WithKeyID("test"), + WithComponents("@status", "content-digest", "@method"), + WithLabel("foo"), + WithTag("bar"), WithExpectedNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), }, assert: func(t *testing.T, err error, hdr http.Header) { @@ -402,11 +402,11 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { { uc: "Accept-Signature and Want-Content-Digest headers are added with supplied algorithms", opts: []AcceptSignatureOption{ - WithExpectedSignatureAlgorithm(EcdsaP256Sha256), - WithExpectedKeyID("test"), - WithExpectedComponents("@status", "content-digest", "@method"), - WithExpectedLabel("foo"), - WithExpectedTag("bar"), + WithSignatureAlgorithm(EcdsaP256Sha256), + WithKeyID("test"), + WithComponents("@status", "content-digest", "@method"), + WithLabel("foo"), + WithTag("bar"), WithExpectedNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), WithContentDigestAlgorithmPreferences(AlgorithmPreference{Sha512, 1}), }, diff --git a/doc.go b/doc.go deleted file mode 100644 index bf52516..0000000 --- a/doc.go +++ /dev/null @@ -1,19 +0,0 @@ -// Package httpsig implements HTTP Message Signatures as specified by RFC 9421. -// It provides signing, verification, and Accept-Signature negotiation for HTTP -// requests and responses independently of a particular HTTP framework. -// -// Convert net/http messages with MessageFromRequest, MessageFromResponse, or -// MessageForResponse, then use a Signer or Verifier. Verification returns a -// VerificationResult containing the covered components, transmitted signature -// parameters, and optional key-resolution metadata for each verified signature. -// -// A KeyResolver is responsible for selecting trusted verification keys. It -// receives sender-controlled information before the cryptographic signature -// has been verified. Applications are responsible for applying profile-specific -// trust, identity, and authorization rules to the results; verifying a signature -// alone does not establish the sender's identity or permissions. -// -// Signing and digest verification may read complete message bodies. Applications -// must enforce appropriate body size limits before passing untrusted messages -// to the library. -package httpsig diff --git a/options.go b/options.go new file mode 100644 index 0000000..3a593c8 --- /dev/null +++ b/options.go @@ -0,0 +1,559 @@ +package httpsig + +import ( + "bytes" + "fmt" + "time" + + "github.com/dunglas/httpsfv" +) + +type signOptions struct { + label string + nonce string + nonceSet bool + staticParameters []parameterOption + parameters []parameterOption +} + +type sigNegotiationOptions struct { + opts []AcceptSignatureOption +} + +// SignerOption configures how a Signer constructs HTTP message signatures. +type SignerOption interface { + applySignerOption(s *signer) error +} + +// SignOption configures a single Sign call. +type SignOption interface { + applySignOption(opts *signOptions) error +} + +// SignatureNegotiationOption configures the additional values requested by +// WithSignatureNegotiation beyond the verifier's existing requirements. +type SignatureNegotiationOption interface { + applySignatureNegotiationOption(opts *sigNegotiationOptions) +} + +// VerifierOption configures which signatures to verify and which generic +// checks to apply. Options can be provided to NewVerifier or used within +// WithRequiredTag for per-tag expectations. +type VerifierOption interface { + applyVerifierOption(v *verifier, e *expectations, inTag bool) error +} + +// AcceptSignatureOption configures the Accept-Signature request produced by +// NewAcceptSignature and AcceptSignatureBuilder.Build. +type AcceptSignatureOption interface { + applyAcceptSignatureOption(builder *AcceptSignatureBuilder) error +} + +type signerOptionFunc func(*signer) error + +func (f signerOptionFunc) applySignerOption(s *signer) error { + return f(s) +} + +type signatureNegotiationOptionFunc func(*sigNegotiationOptions) + +func (f signatureNegotiationOptionFunc) applySignatureNegotiationOption(opts *sigNegotiationOptions) { + f(opts) +} + +type verifierOptionFunc func(*verifier, *expectations, bool) error + +func (f verifierOptionFunc) applyVerifierOption(v *verifier, e *expectations, inTag bool) error { + return f(v, e, inTag) +} + +type acceptSignatureOptionFunc func(*AcceptSignatureBuilder) error + +func (f acceptSignatureOptionFunc) applyAcceptSignatureOption(asb *AcceptSignatureBuilder) error { + return f(asb) +} + +// WithLabel configures the technical signature label. +// NOTE: Labels are not signed and may be renamed if they collide with existing +// signature labels in a message. +func WithLabel(label string) labelOption { + return labelOption(label) +} + +type labelOption string + +func (o labelOption) applySignerOption(s *signer) error { + if len(o) != 0 { + s.label = string(o) + } + + return nil +} + +func (o labelOption) applySignOption(opts *signOptions) error { + if len(o) != 0 { + opts.label = string(o) + } + + return nil +} + +func (o labelOption) applyAcceptSignatureOption(asb *AcceptSignatureBuilder) error { + if len(o) != 0 { + asb.label = string(o) + } + + return nil +} + +func (o labelOption) applySignatureNegotiationOption(opts *sigNegotiationOptions) { + opts.opts = append(opts.opts, o) +} + +// WithTTL sets how long the generated signature remains valid by controlling +// its expires parameter. A non-positive duration omits expires from the +// generated Signature-Input. +func WithTTL(ttl time.Duration) SignerOption { + return signerOptionFunc(func(s *signer) error { + s.ttl = ttl + + return nil + }) +} + +// WithComponents configures HTTP fields and derived component identifiers. +// NewSigner signs these components, NewVerifier requires them to be covered, +// and NewAcceptSignature requests their coverage from the peer. +// If the signer covers its own "content-digest" field, it also generates or +// updates that field from the message body. +func WithComponents(identifiers ...string) componentsOption { + return componentsOption{identifiers: identifiers} +} + +type componentsOption struct { + identifiers []string +} + +func (o componentsOption) applySignerOption(s *signer) error { + var err error + + s.ids, err = toComponentIdentifiers(o.identifiers) + + return err +} + +func (o componentsOption) applyVerifierOption(_ *verifier, exp *expectations, _ bool) error { + var err error + + exp.identifiers, err = toComponentIdentifiers(o.identifiers) + + return err +} + +func (o componentsOption) applyAcceptSignatureOption(asb *AcceptSignatureBuilder) error { + ids, err := toComponentIdentifiers(o.identifiers) + if err != nil { + return err + } + + asb.setIdentifiers(ids) + + return nil +} + +// WithTag configures the application-defined tag signature parameter. +func WithTag(tag string) tagOption { + return tagOption(tag) +} + +type tagOption string + +func (o tagOption) applySignerOption(s *signer) error { + if len(o) != 0 { + s.tag = string(o) + } + + return nil +} + +func (o tagOption) applyAcceptSignatureOption(asb *AcceptSignatureBuilder) error { + asb.tag = string(o) + + return nil +} + +// WithNonce configures the source for the nonce signature parameter. +// A nil getter leaves the configured source unchanged. If the getter returns +// an empty string, the nonce parameter is omitted. +func WithNonce(ng NonceGetter) SignerOption { + return signerOptionFunc(func(s *signer) error { + if ng != nil { + s.ng = ng + } + + return nil + }) +} + +// WithContentDigestAlgorithm selects the algorithm used to generate +// Content-Digest when that component is covered. Unsupported algorithms +// cause an error. +func WithContentDigestAlgorithm(alg DigestAlgorithm) SignerOption { + return signerOptionFunc(func(s *signer) error { + if _, known := supportedAlgs[alg]; !known { + return fmt.Errorf("%w: %s", ErrUnsupportedAlgorithm, alg) + } + + s.cdAlg = alg + + return nil + }) +} + +// WithKeyID configures the keyid signature parameter. An empty value is +// ignored by the Signer and omitted from an Accept-Signature request. +func WithKeyID(keyID string) keyIDOption { + return keyIDOption(keyID) +} + +type keyIDOption string + +func (o keyIDOption) applySignerOption(s *signer) error { + if len(o) != 0 { + s.keyID = string(o) + } + + return nil +} + +func (o keyIDOption) applyAcceptSignatureOption(asb *AcceptSignatureBuilder) error { + asb.keyID = string(o) + + return nil +} + +func (o keyIDOption) applySignatureNegotiationOption(opts *sigNegotiationOptions) { + opts.opts = append(opts.opts, o) +} + +// WithAlg includes the alg signature parameter of the given Key. +func WithAlg() SignerOption { + return signerOptionFunc(func(s *signer) error { + s.includeAlg = true + + return nil + }) +} + +// WithParameter adds a static or per-call signature parameter to Signature-Input. +// Extension values may be string, Token, bool, int, int64, float64, or []byte. +// Standard RFC 9421 parameter names are reserved, except that Sign permits +// "nonce" as a non-empty string, overriding the configured nonce source for +// that call. Duplicate parameter names are rejected. +func WithParameter(name string, value any) parameterOption { + return parameterOption{name: name, value: value} +} + +type parameterOption struct { + name string + value any +} + +func (o parameterOption) applySignerOption(s *signer) error { + return addParameter(&s.parameters, nil, o, true) +} + +func (o parameterOption) applySignOption(opts *signOptions) error { + if o.name == string(Nonce) { + if opts.nonceSet { + return fmt.Errorf("%w: duplicate signature parameter %q", ErrParameter, o.name) + } + nonce, ok := o.value.(string) + if !ok || nonce == "" { + return fmt.Errorf("%w: nonce must be a non-empty string", ErrParameter) + } + if err := validateParameter(o.name, nonce); err != nil { + return err + } + opts.nonce = nonce + opts.nonceSet = true + + return nil + } + + return addParameter(&opts.parameters, opts.staticParameters, o, false) +} + +// WithValidityTolerance allows a clock skew of d when checking the created +// and expires signature parameters. +func WithValidityTolerance(d time.Duration) VerifierOption { + return verifierOptionFunc(func(_ *verifier, e *expectations, _ bool) error { + e.tolerance = d + + return nil + }) +} + +// WithMaxAge sets the maximum age of signatures with a created timestamp. +func WithMaxAge(d time.Duration) VerifierOption { + return verifierOptionFunc(func(_ *verifier, e *expectations, _ bool) error { + e.maxAge = d + + return nil + }) +} + +// WithNonceChecker sets the checker for the nonce parameter, including when +// the parameter is absent. +func WithNonceChecker(checker NonceChecker) VerifierOption { + // TODO: Maybe we should use checker after cryptographic verification has succeeded + return verifierOptionFunc(func(v *verifier, _ *expectations, _ bool) error { + if checker != nil { + v.nonceChecker = checker + } + + return nil + }) +} + +// WithRequiredTag selects signatures with the given application tag and +// applies opts to that signature. Each tag may be configured only once. +// An empty tag is not allowed. +func WithRequiredTag(tag string, opts ...VerifierOption) VerifierOption { + return verifierOptionFunc(func(ver *verifier, _ *expectations, f bool) error { + if f { + panic("WithRequiredTag cannot be used as option for itself") + } + + if len(tag) == 0 { + return fmt.Errorf("%w: required tag must not be empty", ErrParameter) + } + + if _, configured := ver.tagExpectations[tag]; configured { + return fmt.Errorf("%w: requirements for tag %s are already configured", ErrParameter, tag) + } + + exp := &expectations{ + tolerance: -1, + maxAge: -1, + } + + for _, opt := range opts { + if err := opt.applyVerifierOption(ver, exp, true); err != nil { + return err + } + } + + ver.tagExpectations[tag] = exp + + return nil + }) +} + +// WithValidateAllSignatures verifies every signature in the message. When a +// signature has a configured tag, its per-tag requirements apply; otherwise, +// global requirements apply. +func WithValidateAllSignatures() VerifierOption { + return verifierOptionFunc(func(v *verifier, _ *expectations, _ bool) error { + v.validateAllSigs = true + + return nil + }) +} + +// WithCreatedTimestamp specifies whether created must be present during +// verification or requested in Accept-Signature. If false, a present created +// timestamp is still validated during verification. +func WithCreatedTimestamp(flag bool) createdTimestampOption { + return createdTimestampOption(flag) +} + +type createdTimestampOption bool + +func (o createdTimestampOption) applyVerifierOption(_ *verifier, exp *expectations, _ bool) error { + flag := bool(o) + exp.reqCreatedTS = &flag + + return nil +} + +func (o createdTimestampOption) applyAcceptSignatureOption(asb *AcceptSignatureBuilder) error { + asb.addCreatedTS = bool(o) + + return nil +} + +// WithExpiredTimestamp specifies whether expires must be present during +// verification or requested in Accept-Signature. If false, a present expires +// timestamp is still validated during verification. +func WithExpiredTimestamp(flag bool) expiredTimestampOption { + return expiredTimestampOption(flag) +} + +type expiredTimestampOption bool + +func (o expiredTimestampOption) applyVerifierOption(_ *verifier, exp *expectations, _ bool) error { + flag := bool(o) + exp.reqExpiresTS = &flag + + return nil +} + +func (o expiredTimestampOption) applyAcceptSignatureOption(asb *AcceptSignatureBuilder) error { + asb.addExpiresTS = bool(o) + + return nil +} + +// WithSignatureNegotiation enables Accept-Signature negotiation when a +// required signature or required component or parameter is missing. +// +// Negotiation reuses the relevant verifier requirements; opts specify only +// additional requests such as a key ID, nonce, algorithm, or label. +func WithSignatureNegotiation(opts ...SignatureNegotiationOption) VerifierOption { + no := &sigNegotiationOptions{opts: make([]AcceptSignatureOption, 0, len(opts))} + for _, opt := range opts { + opt.applySignatureNegotiationOption(no) + } + + return verifierOptionFunc(func(_ *verifier, exp *expectations, _ bool) error { + builder, err := NewAcceptSignature(no.opts...) + if err != nil { + return err + } + + exp.asb = builder + + return nil + }) +} + +// WithRequestedNonce supplies the nonce source for Accept-Signature +// negotiation. +func WithRequestedNonce(ng NonceGetter) SignatureNegotiationOption { + return signatureNegotiationOptionFunc(func(sno *sigNegotiationOptions) { + sno.opts = append(sno.opts, WithExpectedNonce(ng)) + }) +} + +// WithSignatureAlgorithm requests an alg value from the peer. +func WithSignatureAlgorithm(alg SignatureAlgorithm) signatureAlgorithmOption { + return signatureAlgorithmOption(alg) +} + +type signatureAlgorithmOption SignatureAlgorithm + +func (o signatureAlgorithmOption) applyAcceptSignatureOption(asb *AcceptSignatureBuilder) error { + asb.signatureAlgorithm = SignatureAlgorithm(o) + + return nil +} + +func (o signatureAlgorithmOption) applySignatureNegotiationOption(opts *sigNegotiationOptions) { + opts.opts = append(opts.opts, o) +} + +// WithExpectedNonce configures the nonce source for Accept-Signature. +// A nil getter leaves the configured source unchanged. +func WithExpectedNonce(ng NonceGetter) AcceptSignatureOption { + // TODO: What can we do for profiles which make use of nonces but in a different parameter + return acceptSignatureOptionFunc(func(asb *AcceptSignatureBuilder) error { + if ng != nil { + asb.nonceGetter = ng + } + + return nil + }) +} + +// WithContentDigestAlgorithmPreferences sets the Want-Content-Digest +// preferences for NewAcceptSignature or WithSignatureNegotiation when the +// requested components contain content-digest. +func WithContentDigestAlgorithmPreferences(prefs ...AlgorithmPreference) contentDigestAlgorithmPreferencesOption { + return prefs +} + +type contentDigestAlgorithmPreferencesOption []AlgorithmPreference + +func (o contentDigestAlgorithmPreferencesOption) applyAcceptSignatureOption(asb *AcceptSignatureBuilder) error { + if len(o) == 0 { + return nil + } + + algPrefs := make([]string, len(o)) + + for i, pref := range o { + if pref.Algorithm == "" { + return fmt.Errorf("%w: digest algorithm preference requires a non-empty algorithm", ErrParameter) + } + + algPrefs[i] = pref.String() + } + + asb.cdAlgPrefs = algPrefs + + return nil +} + +func (o contentDigestAlgorithmPreferencesOption) applySignatureNegotiationOption(opts *sigNegotiationOptions) { + opts.opts = append(opts.opts, o) +} + +func addParameter( + parameters *[]parameterOption, + existing []parameterOption, + option parameterOption, + copyBytes bool, +) error { + switch SignatureParameter(option.name) { + case Created, Expires, KeyID, Alg, Nonce, Tag: + return fmt.Errorf("%w: %q is a reserved signature parameter", ErrParameter, option.name) + } + + value := option.value + switch v := value.(type) { + case Token: + value = httpsfv.Token(v) + case int: + value = int64(v) + case string, bool, int64, float64, []byte, httpsfv.Token: + default: + return fmt.Errorf("%w: unsupported value type %T for signature parameter %q", ErrParameter, value, option.name) + } + + if err := validateParameter(option.name, value); err != nil { + return err + } + + for _, param := range existing { + if param.name == option.name { + return fmt.Errorf("%w: duplicate signature parameter %q", ErrParameter, option.name) + } + } + for _, param := range *parameters { + if param.name == option.name { + return fmt.Errorf("%w: duplicate signature parameter %q", ErrParameter, option.name) + } + } + + if copyBytes { + if v, ok := value.([]byte); ok { + value = bytes.Clone(v) + } + } + + *parameters = append(*parameters, parameterOption{name: option.name, value: value}) + + return nil +} + +func validateParameter(name string, value any) error { + validationParams := httpsfv.NewParams() + validationParams.Add(name, value) + + if _, err := httpsfv.Marshal(httpsfv.Item{Value: true, Params: validationParams}); err != nil { + return fmt.Errorf("%w: invalid signature parameter %q: %v", ErrParameter, name, err) + } + + return nil +} diff --git a/signer.go b/signer.go index 30ea197..ab5b1cf 100644 --- a/signer.go +++ b/signer.go @@ -38,118 +38,16 @@ type Signer interface { // Sign signs msg and returns its updated HTTP headers, including the // Signature and Signature-Input fields. It also updates msg.Header and // may update Content-Digest when that component is covered. - Sign(msg *Message) (http.Header, error) -} - -// SignerOption configures how a Signer constructs HTTP message signatures. -type SignerOption func(s *signer) error - -// WithLabel sets the desired Signature-Input and Signature dictionary label. -// The default is "sig". An empty label is ignored; labels may be renamed -// automatically if they collide with an existing signature in the message. -// Labels are not signed and must not be used as identity information. -func WithLabel(label string) SignerOption { - return func(s *signer) error { - if len(label) != 0 { - s.label = label - } - - return nil - } -} - -// WithTTL sets how long the generated signature remains valid by controlling -// its expires parameter. The default is 30 seconds. A non-positive duration -// omits expires from the generated Signature-Input. -func WithTTL(ttl time.Duration) SignerOption { - return func(s *signer) error { - s.ttl = ttl - - return nil - } -} - -// WithComponents selects HTTP fields and derived component identifiers to -// cover with the signature. If "content-digest" is selected, signing also -// generates or updates the Content-Digest field for the message body. -func WithComponents(identifiers ...string) SignerOption { - return func(s *signer) error { - var err error - - s.ids, err = toComponentIdentifiers(identifiers) - - return err - } -} - -// WithTag sets the application-defined tag signature parameter. An empty -// tag is ignored, leaving the tag parameter absent. -func WithTag(tag string) SignerOption { - return func(s *signer) error { - if len(tag) != 0 { - s.tag = tag - } - - return nil - } -} - -// WithNonce sets the source of the nonce signature parameter. By default, -// the signer generates a random nonce. A nil getter leaves that default in -// place; a getter returning an empty string causes nonce to be omitted. -func WithNonce(ng NonceGetter) SignerOption { - return func(s *signer) error { - if ng != nil { - s.ng = ng - } - - return nil - } -} - -// WithContentDigestAlgorithm selects the algorithm used to generate -// Content-Digest when that component is covered. Without this option, the -// signer generates both supported digests (SHA-256 and SHA-512). -// Unsupported algorithms cause an error during NewSigner. -func WithContentDigestAlgorithm(alg DigestAlgorithm) SignerOption { - return func(s *signer) error { - if _, known := supportedAlgs[alg]; !known { - return fmt.Errorf("%w: %s", ErrUnsupportedAlgorithm, alg) - } - - s.cdAlg = alg - - return nil - } -} - -// WithKeyID adds the keyid signature parameter with the given key ID. -// An empty value is ignored; no keyid is added unless this option supplies -// a non-empty value. -func WithKeyID(keyID string) SignerOption { - return func(s *signer) error { - if len(keyID) != 0 { - s.keyID = keyID - } - - return nil - } -} - -// WithAlg includes the alg signature parameter using Key.Algorithm. -// By default, alg is omitted. -func WithAlg() SignerOption { - return func(s *signer) error { - s.includeAlg = true - - return nil - } + // Options apply only to this invocation and do not modify the Signer. + Sign(msg *Message, opts ...SignOption) (http.Header, error) } // NewSigner creates a Signer using key for cryptographic signing. The key // must contain private or symmetric material compatible with its algorithm. -// By default, the generated signature uses label "sig", includes a created -// timestamp and a random nonce, and expires after 30 seconds. +// By default, signatures use label "sig", include created and a random nonce, +// and expire after 30 seconds. The alg, keyid, and tag parameters are omitted. +// When generating Content-Digest, the signer uses both SHA-256 and SHA-512 +// unless WithContentDigestAlgorithm selects one. func NewSigner(key Key, opts ...SignerOption) (Signer, error) { ps, err := newPayloadSigner(key.Material, key.Algorithm) if err != nil { @@ -165,7 +63,7 @@ func NewSigner(key Key, opts ...SignerOption) (Signer, error) { } for _, opt := range opts { - if err = opt(sig); err != nil { + if err = opt.applySignerOption(sig); err != nil { return nil, err } } @@ -206,11 +104,19 @@ type signer struct { ng NonceGetter ps payloadSigner cdAlg DigestAlgorithm + parameters []parameterOption mu messageUpdater } -func (s *signer) Sign(msg *Message) (http.Header, error) { - params, err := s.signatureInput(msg.Context) +func (s *signer) Sign(msg *Message, opts ...SignOption) (http.Header, error) { + callOptions := signOptions{staticParameters: s.parameters} + for _, opt := range opts { + if err := opt.applySignOption(&callOptions); err != nil { + return nil, err + } + } + + params, err := s.signatureInput(msg.Context, callOptions) if err != nil { return nil, err } @@ -234,15 +140,24 @@ func (s *signer) Sign(msg *Message) (http.Header, error) { return nil, err } - return msg.addSignature(s.label, signature, params.value) + label := s.label + if callOptions.label != "" { + label = callOptions.label + } + + return msg.addSignature(label, signature, params.value) } -func (s *signer) signatureInput(ctx context.Context) (*signatureInput, error) { +func (s *signer) signatureInput(ctx context.Context, opts signOptions) (*signatureInput, error) { created := currentTime().UTC() - nonce, err := s.ng.GetNonce(ctx) - if err != nil { - return nil, err + nonce := opts.nonce + if !opts.nonceSet { + var err error + nonce, err = s.ng.GetNonce(ctx) + if err != nil { + return nil, err + } } params := httpsfv.NewParams() @@ -268,5 +183,13 @@ func (s *signer) signatureInput(ctx context.Context) (*signatureInput, error) { params.Add(string(Tag), s.tag) } + for _, param := range s.parameters { + params.Add(param.name, param.value) + } + + for _, param := range opts.parameters { + params.Add(param.name, param.value) + } + return newSignatureInput(s.ids, params), nil } diff --git a/signer_test.go b/signer_test.go index 3520234..3ddf4e6 100644 --- a/signer_test.go +++ b/signer_test.go @@ -83,7 +83,7 @@ func TestWithLabel(t *testing.T) { t.Run(tc.uc, func(t *testing.T) { s := &signer{label: "test"} - err := WithLabel(tc.label)(s) + err := WithLabel(tc.label).applySignerOption(s) require.NoError(t, err) if tc.shouldUpdate { @@ -101,7 +101,7 @@ func TestWithTTL(t *testing.T) { ttl := 1 * time.Second s := &signer{ttl: 30 * time.Second} - err := WithTTL(ttl)(s) + err := WithTTL(ttl).applySignerOption(s) require.NoError(t, err) require.Equal(t, ttl, s.ttl) @@ -121,7 +121,7 @@ func TestWithComponentsForSigner(t *testing.T) { t.Run(tc.uc, func(t *testing.T) { s := &signer{} - err := WithComponents(tc.identifiers...)(s) + err := WithComponents(tc.identifiers...).applySignerOption(s) if tc.err != nil { require.Error(t, err) @@ -144,7 +144,7 @@ func TestWithTag(t *testing.T) { s := &signer{} - err := WithTag("test")(s) + err := WithTag("test").applySignerOption(s) require.NoError(t, err) assert.Equal(t, "test", s.tag) @@ -157,7 +157,7 @@ func TestWithNonceGetter(t *testing.T) { err := WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "foo", nil - }))(s) + })).applySignerOption(s) require.NoError(t, err) nonce, err := s.ng.GetNonce(context.TODO()) @@ -180,7 +180,7 @@ func TestWithContentDigestAlgorithm(t *testing.T) { t.Run(tc.uc, func(t *testing.T) { s := &signer{} - err := WithContentDigestAlgorithm(tc.alg)(s) + err := WithContentDigestAlgorithm(tc.alg).applySignerOption(s) if tc.err != nil { require.Error(t, err) @@ -235,6 +235,54 @@ func TestNewSigner(t *testing.T) { require.ErrorIs(t, err, ErrUnsupportedAlgorithm) }, }, + { + uc: "reserved signature parameter", + key: Key{Algorithm: EcdsaP384Sha384, Material: pkp384}, + opts: []SignerOption{WithParameter("created", int64(1))}, + assert: func(t *testing.T, err error, _ Signer) { + t.Helper() + require.ErrorIs(t, err, ErrParameter) + }, + }, + { + uc: "static nonce parameter is not allowed", + key: Key{Algorithm: EcdsaP384Sha384, Material: pkp384}, + opts: []SignerOption{WithParameter("nonce", "fixed-nonce")}, + assert: func(t *testing.T, err error, _ Signer) { + t.Helper() + require.ErrorIs(t, err, ErrParameter) + }, + }, + { + uc: "invalid signature parameter name", + key: Key{Algorithm: EcdsaP384Sha384, Material: pkp384}, + opts: []SignerOption{WithParameter("Invalid Name", "value")}, + assert: func(t *testing.T, err error, _ Signer) { + t.Helper() + require.ErrorIs(t, err, ErrParameter) + }, + }, + { + uc: "invalid signature parameter value", + key: Key{Algorithm: EcdsaP384Sha384, Material: pkp384}, + opts: []SignerOption{WithParameter("example", struct{}{})}, + assert: func(t *testing.T, err error, _ Signer) { + t.Helper() + require.ErrorIs(t, err, ErrParameter) + }, + }, + { + uc: "duplicate signature parameter", + key: Key{Algorithm: EcdsaP384Sha384, Material: pkp384}, + opts: []SignerOption{ + WithParameter("example", "a"), + WithParameter("example", "b"), + }, + assert: func(t *testing.T, err error, _ Signer) { + t.Helper() + require.ErrorIs(t, err, ErrParameter) + }, + }, { uc: "successful without configuration", key: Key{Algorithm: EcdsaP384Sha384, Material: pkp384}, @@ -340,11 +388,12 @@ func TestSignerSign(t *testing.T) { tkEd25519 := rawKey.(ed25519.PrivateKey) for _, tc := range []struct { - uc string - key Key - opts []SignerOption - msg *Message - assert func(t *testing.T, err error, header http.Header) + uc string + key Key + opts []SignerOption + signOpts []SignOption + msg *Message + assert func(t *testing.T, err error, header http.Header) }{ { uc: "failed creating signature parameters", @@ -421,6 +470,141 @@ func TestSignerSign(t *testing.T) { require.Error(t, err) }, }, + { + uc: "static extension parameters", + key: Key{Algorithm: HmacSha256, Material: []byte("secret")}, + opts: []SignerOption{ + WithTTL(0), + WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), + WithParameter("example-token", Token("hello")), + WithParameter("example-bytes", []byte("data")), + }, + msg: &Message{Header: http.Header{}, IsRequest: true}, + assert: func(t *testing.T, err error, header http.Header) { + t.Helper() + require.NoError(t, err) + assert.Equal(t, `sig=();created=1618884473;example-token=hello;example-bytes=:ZGF0YQ==:`, header.Get("Signature-Input")) + }, + }, + { + uc: "per-call label overrides configured label", + key: Key{Algorithm: HmacSha256, Material: []byte("secret")}, + opts: []SignerOption{ + WithTTL(0), + WithLabel("static"), + WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), + }, + signOpts: []SignOption{WithLabel("dynamic")}, + msg: &Message{Header: http.Header{}, IsRequest: true}, + assert: func(t *testing.T, err error, header http.Header) { + t.Helper() + require.NoError(t, err) + assert.Equal(t, `dynamic=();created=1618884473`, header.Get("Signature-Input")) + }, + }, + { + uc: "per-call nonce overrides configured getter", + key: Key{Algorithm: HmacSha256, Material: []byte("secret")}, + opts: []SignerOption{ + WithTTL(0), + WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", errors.New("getter must not be called") })), + }, + signOpts: []SignOption{WithParameter("nonce", "requested-nonce")}, + msg: &Message{Header: http.Header{}, IsRequest: true}, + assert: func(t *testing.T, err error, header http.Header) { + t.Helper() + require.NoError(t, err) + assert.Equal(t, `sig=();created=1618884473;nonce="requested-nonce"`, header.Get("Signature-Input")) + }, + }, + { + uc: "additional parameters for a single signature", + key: Key{Algorithm: HmacSha256, Material: []byte("secret")}, + opts: []SignerOption{ + WithTTL(0), + WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), + WithParameter("static", Token("hello")), + }, + signOpts: []SignOption{ + WithParameter("wimse-req-nonce", "request-nonce"), + WithParameter("dynamic-flag", true), + }, + msg: &Message{Header: http.Header{}, IsRequest: true}, + assert: func(t *testing.T, err error, header http.Header) { + t.Helper() + require.NoError(t, err) + assert.Equal(t, `sig=();created=1618884473;static=hello;wimse-req-nonce="request-nonce";dynamic-flag`, header.Get("Signature-Input")) + }, + }, + { + uc: "reserved per-call parameter", + key: Key{Algorithm: HmacSha256, Material: []byte("secret")}, + signOpts: []SignOption{WithParameter("created", int64(1))}, + msg: &Message{Header: http.Header{}, IsRequest: true}, + assert: func(t *testing.T, err error, _ http.Header) { + t.Helper() + require.ErrorIs(t, err, ErrParameter) + }, + }, + { + uc: "nonce parameter requires a string", + key: Key{Algorithm: HmacSha256, Material: []byte("secret")}, + signOpts: []SignOption{WithParameter("nonce", Token("not-a-string"))}, + msg: &Message{Header: http.Header{}, IsRequest: true}, + assert: func(t *testing.T, err error, _ http.Header) { + t.Helper() + require.ErrorIs(t, err, ErrParameter) + }, + }, + { + uc: "nonce parameter cannot be empty", + key: Key{Algorithm: HmacSha256, Material: []byte("secret")}, + signOpts: []SignOption{WithParameter("nonce", "")}, + msg: &Message{Header: http.Header{}, IsRequest: true}, + assert: func(t *testing.T, err error, _ http.Header) { + t.Helper() + require.ErrorIs(t, err, ErrParameter) + }, + }, + { + uc: "duplicate per-call nonce", + key: Key{Algorithm: HmacSha256, Material: []byte("secret")}, + signOpts: []SignOption{ + WithParameter("nonce", "one"), + WithParameter("nonce", "two"), + }, + msg: &Message{Header: http.Header{}, IsRequest: true}, + assert: func(t *testing.T, err error, _ http.Header) { + t.Helper() + require.ErrorIs(t, err, ErrParameter) + }, + }, + { + uc: "duplicate per-call parameter", + key: Key{Algorithm: HmacSha256, Material: []byte("secret")}, + signOpts: []SignOption{ + WithParameter("example", "a"), + WithParameter("example", "b"), + }, + msg: &Message{Header: http.Header{}, IsRequest: true}, + assert: func(t *testing.T, err error, _ http.Header) { + t.Helper() + require.ErrorIs(t, err, ErrParameter) + }, + }, + { + uc: "static and per-call parameter collision", + key: Key{Algorithm: HmacSha256, Material: []byte("secret")}, + opts: []SignerOption{ + WithParameter("example", "static"), + }, + signOpts: []SignOption{WithParameter("example", "dynamic")}, + msg: &Message{Header: http.Header{}, IsRequest: true}, + assert: func(t *testing.T, err error, _ http.Header) { + t.Helper() + require.ErrorIs(t, err, ErrParameter) + }, + }, { uc: "include alg parameter when requested", key: Key{Algorithm: HmacSha256, Material: tkMAC}, @@ -760,9 +944,66 @@ func TestSignerSign(t *testing.T) { s, err := NewSigner(tc.key, tc.opts...) require.NoError(t, err) - res, err := s.Sign(tc.msg) + res, err := s.Sign(tc.msg, tc.signOpts...) tc.assert(t, err, res) }) } + + t.Run("per-call label does not persist", func(t *testing.T) { + s, err := NewSigner(Key{Algorithm: HmacSha256, Material: []byte("secret")}, + WithTTL(0), + WithLabel("static"), + WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), + ) + require.NoError(t, err) + + first, err := s.Sign(&Message{Header: http.Header{}, IsRequest: true}, WithLabel("dynamic")) + require.NoError(t, err) + assert.Equal(t, `dynamic=();created=1618884473`, first.Get("Signature-Input")) + + second, err := s.Sign(&Message{Header: http.Header{}, IsRequest: true}) + require.NoError(t, err) + assert.Equal(t, `static=();created=1618884473`, second.Get("Signature-Input")) + }) + + t.Run("per-call nonce does not persist", func(t *testing.T) { + getterCalls := 0 + s, err := NewSigner(Key{Algorithm: HmacSha256, Material: []byte("secret")}, + WithTTL(0), + WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { + getterCalls++ + return "generated-nonce", nil + })), + ) + require.NoError(t, err) + + first, err := s.Sign(&Message{Header: http.Header{}, IsRequest: true}, + WithParameter("nonce", "requested-nonce")) + require.NoError(t, err) + assert.Equal(t, `sig=();created=1618884473;nonce="requested-nonce"`, first.Get("Signature-Input")) + assert.Zero(t, getterCalls) + + second, err := s.Sign(&Message{Header: http.Header{}, IsRequest: true}) + require.NoError(t, err) + assert.Equal(t, `sig=();created=1618884473;nonce="generated-nonce"`, second.Get("Signature-Input")) + assert.Equal(t, 1, getterCalls) + }) + + t.Run("per-call parameters do not persist", func(t *testing.T) { + s, err := NewSigner(Key{Algorithm: HmacSha256, Material: []byte("secret")}, + WithTTL(0), + WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), + ) + require.NoError(t, err) + + first, err := s.Sign(&Message{Header: http.Header{}, IsRequest: true}, + WithParameter("wimse-req-nonce", "request-nonce")) + require.NoError(t, err) + assert.Contains(t, first.Get("Signature-Input"), `;wimse-req-nonce="request-nonce"`) + + second, err := s.Sign(&Message{Header: http.Header{}, IsRequest: true}) + require.NoError(t, err) + assert.Equal(t, `sig=();created=1618884473`, second.Get("Signature-Input")) + }) } diff --git a/verifier.go b/verifier.go index 90a41af..534292a 100644 --- a/verifier.go +++ b/verifier.go @@ -45,205 +45,12 @@ type Verifier interface { Verify(msg *Message) (VerificationResult, error) } -// VerifierOption configures which signatures to verify and which generic -// checks to apply. Options can be provided to NewVerifier or used within -// WithRequiredTag for per-tag expectations. Options such as WithNonceChecker -// configure the verifier globally even when supplied within a tag. -type VerifierOption func(v *verifier, e *expectations, f bool) error - -// WithRequiredComponents specifies HTTP fields or derived component -// identifiers that must be covered by a signature to which the option applies. -func WithRequiredComponents(identifiers ...string) VerifierOption { - return func(_ *verifier, exp *expectations, _ bool) error { - var err error - - exp.identifiers, err = toComponentIdentifiers(identifiers) - - return err - } -} - -// WithValidityTolerance allows a clock skew of d when checking the created -// and expires signature parameters. -func WithValidityTolerance(d time.Duration) VerifierOption { - return func(_ *verifier, e *expectations, _ bool) error { - e.tolerance = d - - return nil - } -} - -// WithMaxAge sets the maximum age of signatures with a created timestamp. -// The default for NewVerifier is 30 seconds. -func WithMaxAge(d time.Duration) VerifierOption { - return func(_ *verifier, e *expectations, _ bool) error { - e.maxAge = d - - return nil - } -} - -// WithNonceChecker sets the checker for the nonce parameter, including when -// the parameter is absent. If checker is nil, the no-op default remains. CheckNonce -// may be called before cryptographic verification has succeeded; checkers -// with replay state must account for unsuccessful verification attempts. -func WithNonceChecker(checker NonceChecker) VerifierOption { - // TODO: Maybe we should use checker after cryptographic verification has succeeded - return func(v *verifier, _ *expectations, _ bool) error { - if checker != nil { - v.nonceChecker = checker - } - - return nil - } -} - -// WithRequiredTag selects signatures with the given application tag and -// applies opts to that signature. Global options in NewVerifier provide -// defaults for unspecified per-tag requirements. Each tag may be configured -// only once. An empty tag is not allowed. -func WithRequiredTag(tag string, opts ...VerifierOption) VerifierOption { - return func(ver *verifier, _ *expectations, f bool) error { - if f { - panic("WithRequiredTag cannot be used as option for itself") - } - - if len(tag) == 0 { - return fmt.Errorf("%w: required tag must not be empty", ErrParameter) - } - - if _, configured := ver.tagExpectations[tag]; configured { - return fmt.Errorf("%w: requirements for tag %s are already configured", ErrParameter, tag) - } - - exp := &expectations{ - tolerance: -1, - maxAge: -1, - } - - for _, opt := range opts { - if err := opt(ver, exp, true); err != nil { - return err - } - } - - ver.tagExpectations[tag] = exp - - return nil - } -} - -// WithValidateAllSignatures verifies every signature in the message, not just -// those selected with WithRequiredTag. When a signature has a configured tag, -// its per-tag requirements apply; otherwise, global requirements apply. -func WithValidateAllSignatures() VerifierOption { - return func(v *verifier, _ *expectations, _ bool) error { - v.validateAllSigs = true - - return nil - } -} - -// WithCreatedTimestampRequired controls whether the created parameter must -// be present. If present, it is still checked even when flag is false. -// NewVerifier requires created by default. -func WithCreatedTimestampRequired(flag bool) VerifierOption { - return func(_ *verifier, exp *expectations, _ bool) error { - exp.reqCreatedTS = &flag - - return nil - } -} - -// WithExpiredTimestampRequired controls whether the expires parameter must -// be present. If present, it is still checked even when flag is false. -// NewVerifier requires expires by default. -func WithExpiredTimestampRequired(flag bool) VerifierOption { - return func(_ *verifier, exp *expectations, _ bool) error { - exp.reqExpiresTS = &flag - - return nil - } -} - -// WithSignatureNegotiation enables Accept-Signature negotiation when a -// required signature or required component or parameter is missing. -// -// Negotiation reuses the relevant verifier requirements; opts specify only -// additional requests such as a key ID, nonce, algorithm, or label. A caller -// can extract NoApplicableSignatureError from a verification failure and call -// its Negotiate method to populate response headers. Negotiation configured -// globally cannot be combined with WithValidateAllSignatures. -func WithSignatureNegotiation(opts ...SignatureNegotiationOption) VerifierOption { - no := &sigNegotiationOpts{opts: make([]AcceptSignatureOption, 0, len(opts))} - for _, opt := range opts { - opt(no) - } - - return func(_ *verifier, exp *expectations, _ bool) error { - builder, err := NewAcceptSignature(no.opts...) - if err != nil { - return err - } - - exp.asb = builder - - return nil - } -} - -type sigNegotiationOpts struct { - opts []AcceptSignatureOption -} - -// SignatureNegotiationOption configures the additional values requested by -// WithSignatureNegotiation beyond the verifier's existing requirements. -type SignatureNegotiationOption func(sno *sigNegotiationOpts) - -// WithRequestedSignatureAlgorithm requests alg in the generated -// Accept-Signature header. -func WithRequestedSignatureAlgorithm(alg SignatureAlgorithm) SignatureNegotiationOption { - return func(sno *sigNegotiationOpts) { - sno.opts = append(sno.opts, WithExpectedSignatureAlgorithm(alg)) - } -} - -// WithRequestedNonce supplies the nonce source for Accept-Signature -// negotiation. -func WithRequestedNonce(ng NonceGetter) SignatureNegotiationOption { - return func(sno *sigNegotiationOpts) { - sno.opts = append(sno.opts, WithExpectedNonce(ng)) - } -} - -// WithRequestedContentDigestAlgorithmPreferences sets the Want-Content-Digest -// preferences emitted when negotiation requires a content-digest component. -func WithRequestedContentDigestAlgorithmPreferences(prefs ...AlgorithmPreference) SignatureNegotiationOption { - return func(sno *sigNegotiationOpts) { - sno.opts = append(sno.opts, WithContentDigestAlgorithmPreferences(prefs...)) - } -} - -// WithRequestedLabel sets the technical label requested in Accept-Signature. -// Signature labels are not authenticated and must not carry identity meaning. -func WithRequestedLabel(label string) SignatureNegotiationOption { - return func(sno *sigNegotiationOpts) { - sno.opts = append(sno.opts, WithExpectedLabel(label)) - } -} - -// WithRequestedKeyID requests keyID as the keyid parameter in the generated -// Accept-Signature header. -func WithRequestedKeyID(keyID string) SignatureNegotiationOption { - return func(sno *sigNegotiationOpts) { - sno.opts = append(sno.opts, WithExpectedKeyID(keyID)) - } -} - // NewVerifier creates a Verifier instance. // Without WithValidateAllSignatures, at least one WithRequiredTag is necessary. // By default, created and expires are required and signatures may be at most -// 30 seconds old. More specific requirements can be set through opts. +// 30 seconds old. The default nonce checker does not reject any nonce. +// Global WithSignatureNegotiation cannot be combined with +// WithValidateAllSignatures. More specific requirements can be set through opts. // //nolint:cyclop func NewVerifier(resolver KeyResolver, opts ...VerifierOption) (Verifier, error) { @@ -266,7 +73,7 @@ func NewVerifier(resolver KeyResolver, opts ...VerifierOption) (Verifier, error) } for _, opt := range opts { - if err := opt(ver, global, false); err != nil { + if err := opt.applyVerifierOption(ver, global, false); err != nil { return nil, fmt.Errorf("%w: %w", ErrVerifierCreation, err) } } diff --git a/verifier_test.go b/verifier_test.go index 497e407..9602cfa 100644 --- a/verifier_test.go +++ b/verifier_test.go @@ -427,7 +427,7 @@ func TestExpectationsAssertParameters(t *testing.T) { } } -func TestWithRequiredComponents(t *testing.T) { +func TestWithComponentsForVerifier(t *testing.T) { t.Parallel() for _, tc := range []struct { @@ -442,7 +442,7 @@ func TestWithRequiredComponents(t *testing.T) { v := &verifier{} exp := &expectations{} - err := WithRequiredComponents(tc.identifiers...)(v, exp, false) + err := WithComponents(tc.identifiers...).applyVerifierOption(v, exp, false) if tc.err != nil { require.Error(t, err) @@ -467,7 +467,7 @@ func TestWithValidityTolerance(t *testing.T) { v := &verifier{} exp := &expectations{} - err := WithValidityTolerance(1*time.Minute)(v, exp, false) + err := WithValidityTolerance(1*time.Minute).applyVerifierOption(v, exp, false) require.NoError(t, err) assert.Empty(t, v.tagExpectations) @@ -496,7 +496,7 @@ func TestWithRequiredTag(t *testing.T) { { uc: "with identifiers only", opts: []VerifierOption{ - WithRequiredComponents("@status"), + WithComponents("@status"), }, assert: func(t *testing.T, err error, exp *expectations) { t.Helper() @@ -525,7 +525,7 @@ func TestWithRequiredTag(t *testing.T) { { uc: "with all possible options", opts: []VerifierOption{ - WithRequiredComponents("@status"), + WithComponents("@status"), WithValidityTolerance(5 * time.Minute), }, assert: func(t *testing.T, err error, exp *expectations) { @@ -541,7 +541,7 @@ func TestWithRequiredTag(t *testing.T) { { uc: "with unsupported identifier", opts: []VerifierOption{ - WithRequiredComponents("@foo"), + WithComponents("@foo"), }, assert: func(t *testing.T, err error, exp *expectations) { t.Helper() @@ -586,7 +586,7 @@ func TestWithRequiredTag(t *testing.T) { } err := recoverIfPanics(t, func() error { - return WithRequiredTag("test", tc.opts...)(v, nil, false) + return WithRequiredTag("test", tc.opts...).applyVerifierOption(v, nil, false) }) if err == nil { require.Len(t, v.tagExpectations, 1) @@ -599,7 +599,7 @@ func TestWithRequiredTag(t *testing.T) { t.Run("with duplicate WithRequiredTag", func(t *testing.T) { v := &verifier{tagExpectations: map[string]*expectations{"foo": {}}} - err := WithRequiredTag("foo", nil)(v, nil, false) + err := WithRequiredTag("foo", nil).applyVerifierOption(v, nil, false) require.Error(t, err) require.ErrorIs(t, err, ErrParameter) require.ErrorContains(t, err, "already configured") @@ -612,7 +612,7 @@ func TestWithMaxAge(t *testing.T) { v := &verifier{} exp := &expectations{} - err := WithMaxAge(15*time.Minute)(v, exp, false) + err := WithMaxAge(15*time.Minute).applyVerifierOption(v, exp, false) require.NoError(t, err) assert.Equal(t, 15*time.Minute, exp.maxAge) @@ -625,7 +625,7 @@ func TestWithNonceChecker(t *testing.T) { exp := &expectations{} storage := &NonceCheckerMock{} - err := WithNonceChecker(storage)(v, exp, false) + err := WithNonceChecker(storage).applyVerifierOption(v, exp, false) require.NoError(t, err) assert.Equal(t, storage, v.nonceChecker) @@ -663,11 +663,11 @@ func TestWithSignatureNegotiation(t *testing.T) { { uc: "with all possible options", opts: []SignatureNegotiationOption{ - WithRequestedLabel("foo"), + WithLabel("foo"), WithRequestedNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), - WithRequestedSignatureAlgorithm(RsaPssSha512), - WithRequestedKeyID("bar"), - WithRequestedContentDigestAlgorithmPreferences(AlgorithmPreference{Sha512, 2}), + WithSignatureAlgorithm(RsaPssSha512), + WithKeyID("bar"), + WithContentDigestAlgorithmPreferences(AlgorithmPreference{Sha512, 2}), }, assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) { t.Helper() @@ -694,7 +694,7 @@ func TestWithSignatureNegotiation(t *testing.T) { { uc: "with error while applying the option", opts: []SignatureNegotiationOption{ - WithRequestedContentDigestAlgorithmPreferences(AlgorithmPreference{}), + WithContentDigestAlgorithmPreferences(AlgorithmPreference{}), }, assert: func(t *testing.T, err error, _ *AcceptSignatureBuilder) { t.Helper() @@ -708,7 +708,7 @@ func TestWithSignatureNegotiation(t *testing.T) { v := &verifier{} exp := &expectations{} - err := WithSignatureNegotiation(tc.opts...)(v, exp, false) + err := WithSignatureNegotiation(tc.opts...).applyVerifierOption(v, exp, false) tc.assert(t, err, exp.asb) }) @@ -749,7 +749,7 @@ func TestNewVerifier(t *testing.T) { uc: "with component identifiers configuration error", resolver: &KeyResolverMock{}, opts: []VerifierOption{ - WithRequiredComponents("@foo"), + WithComponents("@foo"), }, assert: func(t *testing.T, err error, _ *verifier) { t.Helper() @@ -810,7 +810,7 @@ func TestNewVerifier(t *testing.T) { opts: []VerifierOption{ WithRequiredTag("test", WithValidityTolerance(1*time.Second), - WithRequiredComponents("@status"), + WithComponents("@status"), ), }, assert: func(t *testing.T, err error, v *verifier) { @@ -835,7 +835,7 @@ func TestNewVerifier(t *testing.T) { opts: []VerifierOption{ WithRequiredTag("test"), WithValidityTolerance(1 * time.Second), - WithRequiredComponents("@status"), + WithComponents("@status"), }, assert: func(t *testing.T, err error, v *verifier) { t.Helper() @@ -860,10 +860,10 @@ func TestNewVerifier(t *testing.T) { opts: []VerifierOption{ WithRequiredTag("test"), WithValidityTolerance(1 * time.Second), - WithRequiredComponents("@status", "content-digest"), + WithComponents("@status", "content-digest"), WithSignatureNegotiation( - WithRequestedSignatureAlgorithm(RsaPssSha512), - WithRequestedKeyID("bar"), + WithSignatureAlgorithm(RsaPssSha512), + WithKeyID("bar"), ), }, assert: func(t *testing.T, err error, v *verifier) { @@ -900,10 +900,10 @@ func TestNewVerifier(t *testing.T) { opts: []VerifierOption{ WithRequiredTag("test", WithValidityTolerance(1*time.Second), - WithRequiredComponents("@status"), + WithComponents("@status"), ), WithValidityTolerance(1 * time.Minute), - WithRequiredComponents("@method"), + WithComponents("@method"), WithValidateAllSignatures(), }, assert: func(t *testing.T, err error, v *verifier) { @@ -1178,8 +1178,8 @@ func TestVerifierVerify(t *testing.T) { uc: "unsupported signature key", opts: []VerifierOption{ WithRequiredTag("foo"), - WithExpiredTimestampRequired(false), - WithCreatedTimestampRequired(false), + WithExpiredTimestamp(false), + WithCreatedTimestamp(false), }, msg: &Message{ Header: http.Header{ @@ -1212,8 +1212,8 @@ func TestVerifierVerify(t *testing.T) { uc: "invalid signature", opts: []VerifierOption{ WithRequiredTag("foo"), - WithExpiredTimestampRequired(false), - WithCreatedTimestampRequired(false), + WithExpiredTimestamp(false), + WithCreatedTimestamp(false), }, msg: &Message{ Header: http.Header{ @@ -1254,13 +1254,13 @@ func TestVerifierVerify(t *testing.T) { uc: "signature parameters negotiation for not present tagged signature", opts: []VerifierOption{ WithRequiredTag("foo", - WithRequiredComponents("@method", "content-digest"), + WithComponents("@method", "content-digest"), WithSignatureNegotiation( - WithRequestedSignatureAlgorithm(RsaPssSha512), - WithRequestedKeyID("test-key"), - WithRequestedLabel("bar"), + WithSignatureAlgorithm(RsaPssSha512), + WithKeyID("test-key"), + WithLabel("bar"), WithRequestedNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), - WithRequestedContentDigestAlgorithmPreferences(AlgorithmPreference{Sha256, 1}), + WithContentDigestAlgorithmPreferences(AlgorithmPreference{Sha256, 1}), ), ), }, @@ -1288,11 +1288,11 @@ func TestVerifierVerify(t *testing.T) { opts: []VerifierOption{ WithRequiredTag("foo", WithSignatureNegotiation( - WithRequestedSignatureAlgorithm(RsaPssSha512), - WithRequestedKeyID("test-key"), - WithRequestedLabel("bar"), + WithSignatureAlgorithm(RsaPssSha512), + WithKeyID("test-key"), + WithLabel("bar"), WithRequestedNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), - WithRequestedContentDigestAlgorithmPreferences(AlgorithmPreference{Sha256, 1}), + WithContentDigestAlgorithmPreferences(AlgorithmPreference{Sha256, 1}), ), ), }, @@ -1349,10 +1349,10 @@ func TestVerifierVerify(t *testing.T) { uc: "signature parameters negotiation fails because of nonce error", opts: []VerifierOption{ WithRequiredTag("foo", - WithRequiredComponents("@method"), + WithComponents("@method"), WithSignatureNegotiation( - WithRequestedSignatureAlgorithm(RsaPssSha512), - WithRequestedKeyID("test-key"), + WithSignatureAlgorithm(RsaPssSha512), + WithKeyID("test-key"), WithRequestedNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", errors.New("test error") })), ), ), @@ -1372,8 +1372,8 @@ func TestVerifierVerify(t *testing.T) { uc: "signature verification fails due to invalid second content digest", opts: []VerifierOption{ WithValidateAllSignatures(), - WithCreatedTimestampRequired(false), - WithExpiredTimestampRequired(false), + WithCreatedTimestamp(false), + WithExpiredTimestamp(false), }, msg: &Message{ Method: http.MethodPost, @@ -1428,8 +1428,8 @@ func TestVerifierVerify(t *testing.T) { uc: "B.2.1. minimal signature using rsa-pss-sha512", opts: []VerifierOption{ WithValidateAllSignatures(), - WithCreatedTimestampRequired(false), - WithExpiredTimestampRequired(false), + WithCreatedTimestamp(false), + WithExpiredTimestamp(false), }, msg: &Message{ Method: http.MethodPost, @@ -1492,8 +1492,8 @@ func TestVerifierVerify(t *testing.T) { uc: "B.2.2. selective covered components using rsa-pss-sha512", opts: []VerifierOption{ WithValidateAllSignatures(), - WithCreatedTimestampRequired(false), - WithExpiredTimestampRequired(false), + WithCreatedTimestamp(false), + WithExpiredTimestamp(false), }, msg: &Message{ Method: http.MethodPost, @@ -1563,8 +1563,8 @@ func TestVerifierVerify(t *testing.T) { uc: "B.2.3. full coverage using rsa-pss-sha512", opts: []VerifierOption{ WithValidateAllSignatures(), - WithCreatedTimestampRequired(false), - WithExpiredTimestampRequired(false), + WithCreatedTimestamp(false), + WithExpiredTimestamp(false), }, msg: &Message{ Method: http.MethodPost, @@ -1643,8 +1643,8 @@ func TestVerifierVerify(t *testing.T) { uc: "B.2.4. signing a response using ecdsa-p256-sha256 ", opts: []VerifierOption{ WithValidateAllSignatures(), - WithCreatedTimestampRequired(false), - WithExpiredTimestampRequired(false), + WithCreatedTimestamp(false), + WithExpiredTimestamp(false), }, msg: &Message{ Method: http.MethodPost, @@ -1713,8 +1713,8 @@ func TestVerifierVerify(t *testing.T) { uc: "B.2.5. signing a request using hmac-sha256", opts: []VerifierOption{ WithValidateAllSignatures(), - WithCreatedTimestampRequired(false), - WithExpiredTimestampRequired(false), + WithCreatedTimestamp(false), + WithExpiredTimestamp(false), }, msg: &Message{ Method: http.MethodPost, @@ -1779,8 +1779,8 @@ func TestVerifierVerify(t *testing.T) { uc: "B.2.6. signing a request using ed25519", opts: []VerifierOption{ WithValidateAllSignatures(), - WithCreatedTimestampRequired(false), - WithExpiredTimestampRequired(false), + WithCreatedTimestamp(false), + WithExpiredTimestamp(false), }, msg: &Message{ Method: http.MethodPost, @@ -1851,7 +1851,7 @@ func TestVerifierVerify(t *testing.T) { uc: "invalid untagged signature is ignored", opts: []VerifierOption{ WithRequiredTag("foo"), - WithExpiredTimestampRequired(false), + WithExpiredTimestamp(false), }, msg: &Message{ Header: http.Header{ @@ -1901,7 +1901,7 @@ func TestVerifierVerify(t *testing.T) { uc: "invalid untagged signature fails when validating all", opts: []VerifierOption{ WithValidateAllSignatures(), - WithExpiredTimestampRequired(false), + WithExpiredTimestamp(false), }, msg: &Message{ Header: http.Header{ @@ -1939,7 +1939,7 @@ func TestVerifierVerify(t *testing.T) { uc: "multiple valid signatures with different keys and metadata", opts: []VerifierOption{ WithValidateAllSignatures(), - WithExpiredTimestampRequired(false), + WithExpiredTimestamp(false), }, msg: &Message{ Method: http.MethodPost, From 45673c00e40a0351720f377a246df74f26a9710f Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Mon, 2 Nov 2026 15:55:04 +0100 Subject: [PATCH 11/33] NonceChecker and the corresponding option removed. Both are obsolete thanks to the updated api --- .mockery.yaml | 1 - mock_nonce_checker_test.go | 104 ----------------------------------- nonce.go | 31 ----------- nonce_test.go | 23 -------- options.go | 13 ----- verifier.go | 17 +----- verifier_test.go | 109 +------------------------------------ 7 files changed, 2 insertions(+), 296 deletions(-) delete mode 100644 mock_nonce_checker_test.go delete mode 100644 nonce_test.go diff --git a/.mockery.yaml b/.mockery.yaml index 6bc26c1..5554283 100644 --- a/.mockery.yaml +++ b/.mockery.yaml @@ -9,5 +9,4 @@ packages: github.com/dadrus/httpsig: interfaces: NonceGetter: {} - NonceChecker: {} KeyResolver: {} diff --git a/mock_nonce_checker_test.go b/mock_nonce_checker_test.go deleted file mode 100644 index 73e1a44..0000000 --- a/mock_nonce_checker_test.go +++ /dev/null @@ -1,104 +0,0 @@ -// Code generated by mockery; DO NOT EDIT. -// github.com/vektra/mockery -// template: testify - -package httpsig - -import ( - "context" - - mock "github.com/stretchr/testify/mock" -) - -// NewNonceCheckerMock creates a new instance of NonceCheckerMock. It also registers a testing interface on the mock and a cleanup function to assert the mocks expectations. -// The first argument is typically a *testing.T value. -func NewNonceCheckerMock(t interface { - mock.TestingT - Cleanup(func()) -}) *NonceCheckerMock { - if helper, ok := t.(interface{ Helper() }); ok { - helper.Helper() - } - - mock := &NonceCheckerMock{} - mock.Mock.Test(t) - - t.Cleanup(func() { - if helper, ok := t.(interface{ Helper() }); ok { - helper.Helper() - } - mock.AssertExpectations(t) - }) - - return mock -} - -// NonceCheckerMock is an autogenerated mock type for the NonceChecker type -type NonceCheckerMock struct { - mock.Mock -} - -type NonceCheckerMock_Expecter struct { - mock *mock.Mock -} - -func (_m *NonceCheckerMock) EXPECT() *NonceCheckerMock_Expecter { - return &NonceCheckerMock_Expecter{mock: &_m.Mock} -} - -// CheckNonce provides a mock function for the type NonceCheckerMock -func (_mock *NonceCheckerMock) CheckNonce(ctx context.Context, nonce NonceValue) error { - ret := _mock.Called(ctx, nonce) - - if len(ret) == 0 { - panic("no return value specified for CheckNonce") - } - - var r0 error - if returnFunc, ok := ret.Get(0).(func(context.Context, NonceValue) error); ok { - r0 = returnFunc(ctx, nonce) - } else { - r0 = ret.Error(0) - } - return r0 -} - -// NonceCheckerMock_CheckNonce_Call is a *mock.Call that shadows Run/Return methods with type explicit version for method 'CheckNonce' -type NonceCheckerMock_CheckNonce_Call struct { - *mock.Call -} - -// CheckNonce is a helper method to define mock.On call -// - ctx context.Context -// - nonce NonceValue -func (_e *NonceCheckerMock_Expecter) CheckNonce(ctx any, nonce any) *NonceCheckerMock_CheckNonce_Call { - return &NonceCheckerMock_CheckNonce_Call{Call: _e.mock.On("CheckNonce", ctx, nonce)} -} - -func (_c *NonceCheckerMock_CheckNonce_Call) Run(run func(ctx context.Context, nonce NonceValue)) *NonceCheckerMock_CheckNonce_Call { - _c.Call.Run(func(args mock.Arguments) { - var arg0 context.Context - if args[0] != nil { - arg0 = args[0].(context.Context) - } - var arg1 NonceValue - if args[1] != nil { - arg1 = args[1].(NonceValue) - } - run( - arg0, - arg1, - ) - }) - return _c -} - -func (_c *NonceCheckerMock_CheckNonce_Call) Return(err error) *NonceCheckerMock_CheckNonce_Call { - _c.Call.Return(err) - return _c -} - -func (_c *NonceCheckerMock_CheckNonce_Call) RunAndReturn(run func(ctx context.Context, nonce NonceValue) error) *NonceCheckerMock_CheckNonce_Call { - _c.Call.Return(run) - return _c -} diff --git a/nonce.go b/nonce.go index dee1641..066c4ac 100644 --- a/nonce.go +++ b/nonce.go @@ -20,37 +20,6 @@ type NonceGetterFunc func(ctx context.Context) (string, error) // GetNonce calls the wrapped nonce-generating function. func (ng NonceGetterFunc) GetNonce(ctx context.Context) (string, error) { return ng(ctx) } -// NonceChecker checks the nonce parameter of a signature, for example to -// enforce replay protection or correlate a negotiated signature. It receives -// both the value and whether the parameter was present. CheckNonce is called -// before the cryptographic signature check; implementations that update replay -// state must account for unsuccessful verification attempts. -type NonceChecker interface { - // CheckNonce returns an error if the nonce must be rejected. - CheckNonce(ctx context.Context, nonce NonceValue) error -} - -// NonceValue represents the received nonce parameter and its presence. -// A missing nonce and an explicitly empty nonce are different values. -type NonceValue struct { - // Present is true when the signature explicitly contains nonce. - Present bool - // Value is the transmitted nonce value, or empty when absent. - Value string -} - -// NonceCheckerFunc adapts a function to the NonceChecker interface. -type NonceCheckerFunc func(ctx context.Context, nonce NonceValue) error - -// CheckNonce calls the wrapped nonce-checking function. -func (f NonceCheckerFunc) CheckNonce(ctx context.Context, nonce NonceValue) error { - return f(ctx, nonce) -} - -type noopNonceChecker struct{} - -func (n noopNonceChecker) CheckNonce(_ context.Context, _ NonceValue) error { return nil } - type nonceGetter struct{} func (n nonceGetter) GetNonce(_ context.Context) (string, error) { diff --git a/nonce_test.go b/nonce_test.go deleted file mode 100644 index 77eeda7..0000000 --- a/nonce_test.go +++ /dev/null @@ -1,23 +0,0 @@ -package httpsig - -import ( - "context" - "testing" - - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" -) - -func TestNonceCheckerFuncImplementsNonceChecker(t *testing.T) { - t.Parallel() - - var checker NonceChecker = NonceCheckerFunc(func(_ context.Context, nonce NonceValue) error { - assert.True(t, nonce.Present) - assert.Equal(t, "foo", nonce.Value) - - return nil - }) - - err := checker.CheckNonce(context.Background(), NonceValue{Present: true, Value: "foo"}) - require.NoError(t, err) -} diff --git a/options.go b/options.go index 3a593c8..f2cec9c 100644 --- a/options.go +++ b/options.go @@ -303,19 +303,6 @@ func WithMaxAge(d time.Duration) VerifierOption { }) } -// WithNonceChecker sets the checker for the nonce parameter, including when -// the parameter is absent. -func WithNonceChecker(checker NonceChecker) VerifierOption { - // TODO: Maybe we should use checker after cryptographic verification has succeeded - return verifierOptionFunc(func(v *verifier, _ *expectations, _ bool) error { - if checker != nil { - v.nonceChecker = checker - } - - return nil - }) -} - // WithRequiredTag selects signatures with the given application tag and // applies opts to that signature. Each tag may be configured only once. // An empty tag is not allowed. diff --git a/verifier.go b/verifier.go index 534292a..abcd136 100644 --- a/verifier.go +++ b/verifier.go @@ -63,7 +63,6 @@ func NewVerifier(resolver KeyResolver, opts ...VerifierOption) (Verifier, error) ver := &verifier{ keyResolver: resolver, tagExpectations: make(map[string]*expectations), - nonceChecker: noopNonceChecker{}, } global := &expectations{ @@ -167,7 +166,6 @@ func (e *expectations) assert( si *signatureInput, msg *Message, keyAlg SignatureAlgorithm, - nc NonceChecker, ) error { var ( missingComponents []string @@ -175,18 +173,6 @@ func (e *expectations) assert( mv messageVerifier ) - nonce := NonceValue{} - - nonceValue, noncePresent := si.nonce() - if noncePresent { - nonce.Value = nonceValue - nonce.Present = true - } - - if err := nc.CheckNonce(msg.Context, nonce); err != nil { - return fmt.Errorf("%w: nonce validation failed: %w", ErrParameter, err) - } - algorithm, algPresent := si.algorithm() if algPresent && algorithm != keyAlg { return fmt.Errorf("%w: key algorithm %s does not match signature algorithm %s", @@ -252,7 +238,6 @@ type verifier struct { keyResolver KeyResolver tagExpectations map[string]*expectations validateAllSigs bool - nonceChecker NonceChecker } func (v *verifier) Verify(msg *Message) (VerificationResult, error) { @@ -403,7 +388,7 @@ func (v *verifier) verifySignature( return VerifiedSignature{}, err } - if err = exp.assert(si, msg, keyInfo.Key.Algorithm, v.nonceChecker); err != nil { + if err = exp.assert(si, msg, keyInfo.Key.Algorithm); err != nil { return VerifiedSignature{}, err } diff --git a/verifier_test.go b/verifier_test.go index 9602cfa..42060b8 100644 --- a/verifier_test.go +++ b/verifier_test.go @@ -75,44 +75,14 @@ func TestExpectationsAssertParameters(t *testing.T) { now := time.Now().UTC() falseVal := false trueVal := true - noNonce := NonceValue{Present: false, Value: ""} for _, tc := range []struct { uc string params httpsfv.InnerList exp expectations expAlg SignatureAlgorithm - configure func(t *testing.T, nc *NonceCheckerMock) assert func(t *testing.T, err error) }{ - { - uc: "replay attack", - params: httpsfv.InnerList{ - Params: func() *httpsfv.Params { - params := httpsfv.NewParams() - params.Add(string(Nonce), "test") - - return params - }(), - }, - exp: expectations{reqExpiresTS: &falseVal, reqCreatedTS: &falseVal}, - configure: func(t *testing.T, nc *NonceCheckerMock) { - t.Helper() - - nonce := NonceValue{ - Present: true, - Value: "test", - } - nc.EXPECT().CheckNonce(mock.Anything, nonce).Return(errors.New("test error")) - }, - assert: func(t *testing.T, err error) { - t.Helper() - - require.Error(t, err) - require.ErrorIs(t, err, ErrParameter) - require.ErrorContains(t, err, "nonce validation failed") - }, - }, { uc: "signature algorithm mismatch", params: httpsfv.InnerList{ @@ -124,11 +94,6 @@ func TestExpectationsAssertParameters(t *testing.T) { }(), }, expAlg: EcdsaP256Sha256, - configure: func(t *testing.T, nc *NonceCheckerMock) { - t.Helper() - - nc.EXPECT().CheckNonce(mock.Anything, noNonce).Return(nil) - }, assert: func(t *testing.T, err error) { t.Helper() @@ -148,11 +113,6 @@ func TestExpectationsAssertParameters(t *testing.T) { }(), }, exp: expectations{reqExpiresTS: &falseVal, reqCreatedTS: &falseVal}, - configure: func(t *testing.T, nc *NonceCheckerMock) { - t.Helper() - - nc.EXPECT().CheckNonce(mock.Anything, noNonce).Return(nil) - }, assert: func(t *testing.T, err error) { t.Helper() @@ -176,11 +136,6 @@ func TestExpectationsAssertParameters(t *testing.T) { reqCreatedTS: &falseVal, reqExpiresTS: &falseVal, }, - configure: func(t *testing.T, nc *NonceCheckerMock) { - t.Helper() - - nc.EXPECT().CheckNonce(mock.Anything, noNonce).Return(nil) - }, assert: func(t *testing.T, err error) { t.Helper() @@ -202,11 +157,6 @@ func TestExpectationsAssertParameters(t *testing.T) { reqCreatedTS: &falseVal, reqExpiresTS: &falseVal, }, - configure: func(t *testing.T, nc *NonceCheckerMock) { - t.Helper() - - nc.EXPECT().CheckNonce(mock.Anything, noNonce).Return(nil) - }, assert: func(t *testing.T, err error) { t.Helper() @@ -224,11 +174,6 @@ func TestExpectationsAssertParameters(t *testing.T) { }(), }, exp: expectations{reqCreatedTS: &falseVal, reqExpiresTS: &falseVal}, - configure: func(t *testing.T, nc *NonceCheckerMock) { - t.Helper() - - nc.EXPECT().CheckNonce(mock.Anything, noNonce).Return(nil) - }, assert: func(t *testing.T, err error) { t.Helper() @@ -252,11 +197,6 @@ func TestExpectationsAssertParameters(t *testing.T) { reqCreatedTS: &falseVal, reqExpiresTS: &falseVal, }, - configure: func(t *testing.T, nc *NonceCheckerMock) { - t.Helper() - - nc.EXPECT().CheckNonce(mock.Anything, noNonce).Return(nil) - }, assert: func(t *testing.T, err error) { t.Helper() @@ -278,11 +218,6 @@ func TestExpectationsAssertParameters(t *testing.T) { reqCreatedTS: &falseVal, reqExpiresTS: &falseVal, }, - configure: func(t *testing.T, nc *NonceCheckerMock) { - t.Helper() - - nc.EXPECT().CheckNonce(mock.Anything, noNonce).Return(nil) - }, assert: func(t *testing.T, err error) { t.Helper() @@ -300,11 +235,6 @@ func TestExpectationsAssertParameters(t *testing.T) { }(), }, exp: expectations{reqCreatedTS: &falseVal, reqExpiresTS: &falseVal}, - configure: func(t *testing.T, nc *NonceCheckerMock) { - t.Helper() - - nc.EXPECT().CheckNonce(mock.Anything, noNonce).Return(nil) - }, assert: func(t *testing.T, err error) { t.Helper() @@ -322,11 +252,6 @@ func TestExpectationsAssertParameters(t *testing.T) { return expectations{identifiers: ids, reqCreatedTS: &falseVal, reqExpiresTS: &falseVal} }(), - configure: func(t *testing.T, nc *NonceCheckerMock) { - t.Helper() - - nc.EXPECT().CheckNonce(mock.Anything, noNonce).Return(nil) - }, assert: func(t *testing.T, err error) { t.Helper() @@ -339,11 +264,6 @@ func TestExpectationsAssertParameters(t *testing.T) { uc: "expected created parameter is missing", params: httpsfv.InnerList{Params: httpsfv.NewParams()}, exp: expectations{reqCreatedTS: &trueVal, reqExpiresTS: &falseVal}, - configure: func(t *testing.T, nc *NonceCheckerMock) { - t.Helper() - - nc.EXPECT().CheckNonce(mock.Anything, noNonce).Return(nil) - }, assert: func(t *testing.T, err error) { t.Helper() @@ -356,11 +276,6 @@ func TestExpectationsAssertParameters(t *testing.T) { uc: "expected expires parameter is missing", params: httpsfv.InnerList{Params: httpsfv.NewParams()}, exp: expectations{reqCreatedTS: &falseVal, reqExpiresTS: &trueVal}, - configure: func(t *testing.T, nc *NonceCheckerMock) { - t.Helper() - - nc.EXPECT().CheckNonce(mock.Anything, noNonce).Return(nil) - }, assert: func(t *testing.T, err error) { t.Helper() @@ -398,12 +313,6 @@ func TestExpectationsAssertParameters(t *testing.T) { } }(), expAlg: EcdsaP256Sha256, - configure: func(t *testing.T, nc *NonceCheckerMock) { - t.Helper() - - nonce := NonceValue{Present: true, Value: "foo"} - nc.EXPECT().CheckNonce(mock.Anything, nonce).Return(nil) - }, assert: func(t *testing.T, err error) { t.Helper() @@ -417,10 +326,7 @@ func TestExpectationsAssertParameters(t *testing.T) { si, err := parseSignatureInput(tc.params) require.NoError(t, err) - nc := NewNonceCheckerMock(t) - tc.configure(t, nc) - - err = tc.exp.assert(si, msg, tc.expAlg, nc) + err = tc.exp.assert(si, msg, tc.expAlg) tc.assert(t, err) }) @@ -618,19 +524,6 @@ func TestWithMaxAge(t *testing.T) { assert.Equal(t, 15*time.Minute, exp.maxAge) } -func TestWithNonceChecker(t *testing.T) { - t.Parallel() - - v := &verifier{} - exp := &expectations{} - storage := &NonceCheckerMock{} - - err := WithNonceChecker(storage).applyVerifierOption(v, exp, false) - require.NoError(t, err) - - assert.Equal(t, storage, v.nonceChecker) -} - func TestWithSignatureNegotiation(t *testing.T) { t.Parallel() From d1b3349fd897ecd93ecf5c773d21e9bd75d391db Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Mon, 2 Nov 2026 18:25:46 +0100 Subject: [PATCH 12/33] golangci settings pdated --- .golangci.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.golangci.yaml b/.golangci.yaml index 2acd902..1b13fdf 100644 --- a/.golangci.yaml +++ b/.golangci.yaml @@ -21,6 +21,7 @@ linters: # deprecated - wsl - depguard + - gomodguard settings: cyclop: max-complexity: 11 @@ -75,6 +76,7 @@ linters: - mnd - goconst - varnamelen + - gocyclo path: (.+)_test\.go formatters: From 6f7c6a50799767915863b2ea50076c3241d624ea Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Mon, 2 Nov 2026 18:29:14 +0100 Subject: [PATCH 13/33] options consolidated --- README.md | 32 +- accept_signature_builder.go | 39 +- accept_signature_builder_test.go | 370 ++++-------- httpsig.go | 19 +- message.go | 2 +- nonce.go | 25 +- options.go | 217 +++---- options_test.go | 938 +++++++++++++++++++++++++++++++ signature_base.go | 8 +- signature_base_test.go | 12 +- signer.go | 38 +- signer_test.go | 185 +----- verifier.go | 17 +- verifier_test.go | 322 ++--------- 14 files changed, 1302 insertions(+), 922 deletions(-) create mode 100644 options_test.go diff --git a/README.md b/README.md index 5c6a602..478c46e 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,8 @@ To sign an HTTP request, first, create a `Signer` instance using your preferred // Create a signer. signer, err := httpsig.NewSigner( // specify a key - httpsig.Key{Material: privKey, Algorithm: httpsig.EcdsaP256Sha256}, + httpsig.Key{Material: privKey, Algorithm: httpsig.EcdsaP256Sha256}, + // the keyid parameter for the above key httpsig.WithKeyID("key1"), // specify the required options // duration for which the signature should be valid @@ -32,7 +33,11 @@ req, err := http.NewRequestWithContext(context.Background(), "GET", "https://som // error handling goes here // Sign the request -header, err := signer.Sign(httpsig.MessageFromRequest(req)) +header, err := signer.Sign( + httpsig.MessageFromRequest(req), + // add a nonce if required + httpsig.WithParameter("nonce", someNonce) +) // error handling goes here // Add the signature to the request @@ -51,8 +56,6 @@ verifier, err := httpsig.NewVerifier( // specify a key resolver to resolve the key used by the client keyResolver, // specify the required options - // to detect and mitigate replay attacks - httpsig.WithNonceChecker(nonceChecker), // which response components are expected to be protected httpsig.WithComponents("@status", "content-type"), // validity time skew @@ -73,6 +76,8 @@ verified, err := verifier.Verify(httpsig.MessageFromResponse(resp)) ``` +Once `Verify` succeeds, the application can inspect the `verified` object and perform its own policies, like e.g., the nonce correlation and replay checks. + If you need to validate a signature created by a specific application (identified by a tag), use the `WithRequiredTag` option when creating the verifier. This option allows you to specify a tag along with the same options as the `NewVerifier` function. Here’s an example: ```go @@ -80,8 +85,6 @@ verifier, err := httpsig.NewVerifier( // specify a key resolver to resolve the key used by the client keyResolver, // specify the required options - // to detect and mitigate replay attacks - httpsig.WithNonceChecker(nonceChecker), httpsig.WithRequiredTag( // tag of the signature "myapp", @@ -141,9 +144,8 @@ On the client side, you can request the server to sign the response by using the builder, err := httpsig.NewAcceptSignature( // request a key ID and signing algorithm httpsig.WithKeyID("foo"), + // specify which signature algorithm the peer should use httpsig.WithSignatureAlgorithm(httpsig.EcdsaP256Sha256), - // specify the NonceSource for the nonce to be added - httpsig.WithExpectedNonce(nonceSource), // specify which label should the server use when creating the response httpsig.WithLabel("bar"), // specify which components should be covered by the signature @@ -160,8 +162,9 @@ builder, err := httpsig.NewAcceptSignature( // error handling goes here req := ... // create your request +nonce := ... // application-generated nonce for this request -err = builder.Build(req.Context(), req.Header) +err = builder.Build(req.Context(), req.Header, httpsig.WithParameter("nonce", nonce)) // error handling goes here ``` @@ -176,8 +179,6 @@ verifier, err := httpsig.NewVerifier( // specify a key resolver keyResolver, // specify the required options - // to detect and mitigate replay attacks - httpsig.WithNonceChecker(nonceChecker), httpsig.WithRequiredTag( // tag of the signature "myapp", @@ -192,10 +193,11 @@ verifier, err := httpsig.NewVerifier( httpsig.WithSignatureNegotiation( // request a key ID and signature algorithm httpsig.WithKeyID("key1"), + // request a signature algorithm the peer should use httpsig.WithSignatureAlgorithm(httpsig.EcdsaP256Sha256), - // specify the source for the nonce, the client should use - httpsig.WithRequestedNonce(nonceGetter), - // specify the label for the signature, the client should use + // specify the source for the nonce + httpsig.WithNonceGetter(nonceGetter), + // specify the label for the signature httpsig.WithLabel("bar"), ), ), @@ -213,5 +215,7 @@ if errors.As(err, &missingSigErr) { // further error handling ``` +For automatic negotiation, the configured `NonceGetter` runs while `Verify` prepares the `Accept-Signature` headers, before `NoApplicableSignatureError` is returned. + > [!NOTE] > The `WithSignatureNegotiation` option at the top level (outside the `WithRequiredTag` option) is mutually exclusive with the `WithValidateAllSignatures` option. However, you can still use `WithSignatureNegotiation` at the top level if you want to apply the same configuration for all expected tagged signatures, thereby simplifying your code. diff --git a/accept_signature_builder.go b/accept_signature_builder.go index bdafe2e..f6453a9 100644 --- a/accept_signature_builder.go +++ b/accept_signature_builder.go @@ -39,14 +39,13 @@ type AcceptSignatureBuilder struct { } // NewAcceptSignature creates an AcceptSignatureBuilder for requesting a -// signature from a peer. By default, it uses label "sig", requests created and -// expires parameters, and generates a random nonce. If Content-Digest is requested, -// the default digest preferences are SHA-256 and SHA-512. +// signature from a peer. By default, it uses label "sig", requests created +// and expires parameters, and does not request a nonce. If Content-Digest +// is requested, the default digest preferences are SHA-256 and SHA-512. func NewAcceptSignature(opts ...AcceptSignatureOption) (*AcceptSignatureBuilder, error) { asb := &AcceptSignatureBuilder{ addCreatedTS: true, addExpiresTS: true, - nonceGetter: nonceGetter{}, label: "sig", cdAlgPrefs: []string{ AlgorithmPreference{Algorithm: Sha256, Preference: 5}.String(), //nolint: mnd @@ -65,12 +64,32 @@ func NewAcceptSignature(opts ...AcceptSignatureOption) (*AcceptSignatureBuilder, // Build appends an Accept-Signature header to header using the configured // signature requirements. If Content-Digest is requested, it also appends -// Want-Content-Digest preferences. The caller must provide a writable, non-nil -// http.Header. -func (asb *AcceptSignatureBuilder) Build(ctx context.Context, header http.Header) error { - nonce, err := asb.nonceGetter.GetNonce(ctx) - if err != nil { - return err +// Want-Content-Digest preferences. A non-empty nonce may be provided for this +// call with WithParameter("nonce", value), overriding a configured +// WithNonceGetter without invoking it. Otherwise, the configured getter is +// used if present; if neither is provided, no nonce is requested. Options +// do not modify this reusable builder. The caller must provide a writable, +// non-nil http.Header. +func (asb *AcceptSignatureBuilder) Build( + ctx context.Context, + header http.Header, + opts ...AcceptSignatureBuildOption, +) error { + callOptions := acceptSignatureBuildOptions{} + for _, opt := range opts { + if err := opt.applyAcceptSignatureBuildOption(&callOptions); err != nil { + return err + } + } + + nonce := callOptions.nonce + if !callOptions.nonceSet && asb.nonceGetter != nil { + var err error + + nonce, err = asb.nonceGetter.GetNonce(ctx) + if err != nil { + return err + } } sigReqs := newSignatureRequirements( diff --git a/accept_signature_builder_test.go b/accept_signature_builder_test.go index d69454a..cfe96a2 100644 --- a/accept_signature_builder_test.go +++ b/accept_signature_builder_test.go @@ -10,243 +10,6 @@ import ( "github.com/stretchr/testify/require" ) -func TestWithSignatureAlgorithmForAcceptSignature(t *testing.T) { - t.Parallel() - - for uc, alg := range map[string]SignatureAlgorithm{ - "no actual data provided": SignatureAlgorithm(""), - "KeyAlg provided": RsaPssSha512, - } { - t.Run(uc, func(t *testing.T) { - asb := &AcceptSignatureBuilder{} - - err := WithSignatureAlgorithm(alg).applyAcceptSignatureOption(asb) - - require.NoError(t, err) - assert.Equal(t, alg, asb.signatureAlgorithm) - }) - } -} - -func TestWithKeyIDForAcceptSignature(t *testing.T) { - t.Parallel() - - for uc, keyID := range map[string]string{ - "no actual data provided": "", - "KeyAlg provided": "test", - } { - t.Run(uc, func(t *testing.T) { - asb := &AcceptSignatureBuilder{} - - err := WithKeyID(keyID).applyAcceptSignatureOption(asb) - - require.NoError(t, err) - assert.Equal(t, keyID, asb.keyID) - }) - } -} - -func TestWithExpectedNonce(t *testing.T) { - t.Parallel() - - for _, tc := range []struct { - uc string - ng NonceGetter - exp NonceGetter - }{ - {uc: "nil NonceGetter", exp: nonceGetter{}}, - {uc: "custom NonceGetter", ng: &NonceGetterMock{}, exp: &NonceGetterMock{}}, - } { - t.Run(tc.uc, func(t *testing.T) { - asb := &AcceptSignatureBuilder{nonceGetter: nonceGetter{}} - - err := WithExpectedNonce(tc.ng).applyAcceptSignatureOption(asb) - - require.NoError(t, err) - assert.Equal(t, tc.exp, asb.nonceGetter) - }) - } -} - -func TestWithLabelForAcceptSignature(t *testing.T) { - t.Parallel() - - for _, tc := range []struct { - uc string - label string - exp string - }{ - {uc: "empty label", exp: "foo"}, - {uc: "custom label", label: "bar", exp: "bar"}, - } { - t.Run(tc.uc, func(t *testing.T) { - asb := &AcceptSignatureBuilder{label: "foo"} - - err := WithLabel(tc.label).applyAcceptSignatureOption(asb) - - require.NoError(t, err) - assert.Equal(t, tc.exp, asb.label) - }) - } -} - -func TestWithComponentsForAcceptSignature(t *testing.T) { - t.Parallel() - - for _, tc := range []struct { - uc string - identifiers []string - assert func(t *testing.T, err error, asb *AcceptSignatureBuilder) - }{ - { - uc: "no identifiers provided", - assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) { - t.Helper() - - require.NoError(t, err) - assert.False(t, asb.wantContentDigest) - assert.Empty(t, asb.identifiers) - }, - }, - { - uc: "invalid identifiers provided", - identifiers: []string{"@foo"}, - assert: func(t *testing.T, err error, _ *AcceptSignatureBuilder) { - t.Helper() - - require.Error(t, err) - require.ErrorIs(t, err, ErrUnsupportedComponentIdentifier) - }, - }, - { - uc: "valid identifiers without content-digest", - identifiers: []string{"@status", "x-foo-bar"}, - assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) { - t.Helper() - - require.NoError(t, err) - assert.False(t, asb.wantContentDigest) - assert.Len(t, asb.identifiers, 2) - assert.Equal(t, "@status", asb.identifiers[0].Value) - assert.Equal(t, "x-foo-bar", asb.identifiers[1].Value) - }, - }, - { - uc: "valid identifiers with content-digest", - identifiers: []string{"@status", "content-digest", "x-foo-bar"}, - assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) { - t.Helper() - - require.NoError(t, err) - assert.True(t, asb.wantContentDigest) - assert.Len(t, asb.identifiers, 3) - assert.Equal(t, "@status", asb.identifiers[0].Value) - assert.Equal(t, "content-digest", asb.identifiers[1].Value) - assert.Equal(t, "x-foo-bar", asb.identifiers[2].Value) - }, - }, - } { - t.Run(tc.uc, func(t *testing.T) { - asb := &AcceptSignatureBuilder{label: "foo"} - - err := WithComponents(tc.identifiers...).applyAcceptSignatureOption(asb) - - tc.assert(t, err, asb) - }) - } -} - -func TestWithContentDigestAlgorithmPreferences(t *testing.T) { - t.Parallel() - - defaultPreference := AlgorithmPreference{Algorithm: Sha256, Preference: 2}.String() - - for _, tc := range []struct { - uc string - prefs []AlgorithmPreference - expErr error - expPrefs []string - }{ - { - uc: "no preferences provided", - expPrefs: []string{defaultPreference}, - }, - { - uc: "no algorithm provided in a preference", - prefs: []AlgorithmPreference{{Sha256, 0}, {DigestAlgorithm(""), 0}}, - expErr: ErrParameter, - expPrefs: []string{defaultPreference}, - }, - { - uc: "valid options provided", - prefs: []AlgorithmPreference{{Sha512, 0}, {Sha256, 1}}, - expPrefs: []string{ - AlgorithmPreference{Sha512, 0}.String(), - AlgorithmPreference{Sha256, 1}.String(), - }, - }, - } { - t.Run(tc.uc, func(t *testing.T) { - asb := &AcceptSignatureBuilder{ - cdAlgPrefs: []string{defaultPreference}, - } - - err := WithContentDigestAlgorithmPreferences(tc.prefs...).applyAcceptSignatureOption(asb) - - if tc.expErr != nil { - require.Error(t, err) - require.ErrorIs(t, err, tc.expErr) - } else { - require.NoError(t, err) - require.ElementsMatch(t, asb.cdAlgPrefs, tc.expPrefs) - } - }) - } -} - -func TestWithTagForAcceptSignature(t *testing.T) { - t.Parallel() - - for _, tc := range []struct { - uc string - tag string - }{ - {uc: "empty tag"}, - {uc: "custom tag", tag: "foo"}, - } { - t.Run(tc.uc, func(t *testing.T) { - asb := &AcceptSignatureBuilder{} - - err := WithTag(tc.tag).applyAcceptSignatureOption(asb) - - require.NoError(t, err) - assert.Equal(t, tc.tag, asb.tag) - }) - } -} - -func TestWithCreatedTimestampForAcceptSignature(t *testing.T) { - t.Parallel() - - asb := &AcceptSignatureBuilder{addCreatedTS: true} - - err := WithCreatedTimestamp(false).applyAcceptSignatureOption(asb) - - require.NoError(t, err) - assert.False(t, asb.addCreatedTS) -} - -func TestWithExpiredTimestampForAcceptSignature(t *testing.T) { - t.Parallel() - - asb := &AcceptSignatureBuilder{addExpiresTS: true} - - err := WithExpiredTimestamp(false).applyAcceptSignatureOption(asb) - - require.NoError(t, err) - assert.False(t, asb.addExpiresTS) -} - func TestNewAcceptedSignature(t *testing.T) { t.Parallel() @@ -268,7 +31,7 @@ func TestNewAcceptedSignature(t *testing.T) { assert.Empty(t, asb.signatureAlgorithm) assert.True(t, asb.addCreatedTS) assert.True(t, asb.addExpiresTS) - assert.Equal(t, nonceGetter{}, asb.nonceGetter) + assert.Nil(t, asb.nonceGetter) assert.Equal(t, "sig", asb.label) assert.ElementsMatch(t, asb.cdAlgPrefs, []string{ AlgorithmPreference{Algorithm: Sha256, Preference: 5}.String(), @@ -281,7 +44,7 @@ func TestNewAcceptedSignature(t *testing.T) { opts: []AcceptSignatureOption{ WithSignatureAlgorithm(EcdsaP256Sha256), WithKeyID("test"), - WithExpectedNonce(&NonceGetterMock{}), + WithNonceGetter(&NonceGetterMock{}), WithLabel("foo"), WithComponents("@status", "content-digest;req"), WithContentDigestAlgorithmPreferences(AlgorithmPreference{Sha512, 10}), @@ -335,14 +98,105 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { t.Parallel() for _, tc := range []struct { - uc string - opts []AcceptSignatureOption - assert func(t *testing.T, err error, hdr http.Header) + uc string + opts []AcceptSignatureOption + buildOpts []AcceptSignatureBuildOption + assert func(t *testing.T, err error, hdr http.Header) }{ + { + uc: "no nonce by default", + assert: func(t *testing.T, err error, hdr http.Header) { + t.Helper() + require.NoError(t, err) + assert.Equal(t, `sig=();created;expires`, hdr.Get(headerAcceptSignature)) + }, + }, + { + uc: "explicit nonce at Build", + buildOpts: []AcceptSignatureBuildOption{WithParameter("nonce", "request-nonce")}, + assert: func(t *testing.T, err error, hdr http.Header) { + t.Helper() + require.NoError(t, err) + assert.Equal(t, `sig=();created;expires;nonce="request-nonce"`, hdr.Get(headerAcceptSignature)) + }, + }, + { + uc: "explicit nonce overrides getter", + opts: []AcceptSignatureOption{ + WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { + return "", errors.New("getter must not be called") + })), + }, + buildOpts: []AcceptSignatureBuildOption{WithParameter("nonce", "requested")}, + assert: func(t *testing.T, err error, hdr http.Header) { + t.Helper() + require.NoError(t, err) + assert.Equal(t, `sig=();created;expires;nonce="requested"`, hdr.Get(headerAcceptSignature)) + }, + }, + { + uc: "empty nonce returned by getter is omitted", + opts: []AcceptSignatureOption{ + WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), + }, + assert: func(t *testing.T, err error, hdr http.Header) { + t.Helper() + require.NoError(t, err) + assert.Equal(t, `sig=();created;expires`, hdr.Get(headerAcceptSignature)) + }, + }, + { + uc: "non-string nonce in Build", + buildOpts: []AcceptSignatureBuildOption{WithParameter("nonce", Token("wrong-type"))}, + assert: func(t *testing.T, err error, hdr http.Header) { + t.Helper() + require.ErrorIs(t, err, ErrParameter) + assert.Empty(t, hdr) + }, + }, + { + uc: "empty nonce in Build", + buildOpts: []AcceptSignatureBuildOption{WithParameter("nonce", "")}, + assert: func(t *testing.T, err error, hdr http.Header) { + t.Helper() + require.ErrorIs(t, err, ErrParameter) + assert.Empty(t, hdr) + }, + }, + { + uc: "invalid structured field string for nonce", + buildOpts: []AcceptSignatureBuildOption{WithParameter("nonce", "bad\nvalue")}, + assert: func(t *testing.T, err error, hdr http.Header) { + t.Helper() + require.ErrorIs(t, err, ErrParameter) + assert.Empty(t, hdr) + }, + }, + { + uc: "duplicate nonce in Build", + buildOpts: []AcceptSignatureBuildOption{ + WithParameter("nonce", "first"), + WithParameter("nonce", "second"), + }, + assert: func(t *testing.T, err error, hdr http.Header) { + t.Helper() + require.ErrorIs(t, err, ErrParameter) + assert.Empty(t, hdr) + }, + }, + { + uc: "unsupported parameter in Build", + buildOpts: []AcceptSignatureBuildOption{WithParameter("other", "value")}, + assert: func(t *testing.T, err error, hdr http.Header) { + t.Helper() + require.ErrorIs(t, err, ErrParameter) + assert.Empty(t, hdr) + }, + }, { uc: "failing getting the nonce", opts: []AcceptSignatureOption{ - WithExpectedNonce(NonceGetterFunc(func(_ context.Context) (string, error) { + WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { return "", errors.New("test error") })), }, @@ -361,7 +215,7 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { WithComponents("@status", "x-foo-bar;req", "@method"), WithLabel("foo"), WithTag("bar"), - WithExpectedNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), + WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), }, assert: func(t *testing.T, err error, hdr http.Header) { t.Helper() @@ -383,7 +237,7 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { WithComponents("@status", "content-digest", "@method"), WithLabel("foo"), WithTag("bar"), - WithExpectedNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), + WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), }, assert: func(t *testing.T, err error, hdr http.Header) { t.Helper() @@ -407,7 +261,7 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { WithComponents("@status", "content-digest", "@method"), WithLabel("foo"), WithTag("bar"), - WithExpectedNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), + WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), WithContentDigestAlgorithmPreferences(AlgorithmPreference{Sha512, 1}), }, assert: func(t *testing.T, err error, hdr http.Header) { @@ -431,9 +285,31 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { builder, err := NewAcceptSignature(tc.opts...) require.NoError(t, err) - err = builder.Build(context.TODO(), hdr) + err = builder.Build(context.TODO(), hdr, tc.buildOpts...) tc.assert(t, err, hdr) }) } + + t.Run("per-call nonce is not retained", func(t *testing.T) { + calls := 0 + builder, err := NewAcceptSignature(WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { + calls++ + + return "generated", nil + }))) + require.NoError(t, err) + + first := make(http.Header) + err = builder.Build(context.TODO(), first, WithParameter("nonce", "explicit")) + require.NoError(t, err) + assert.Equal(t, `sig=();created;expires;nonce="explicit"`, first.Get(headerAcceptSignature)) + assert.Zero(t, calls) + + second := make(http.Header) + err = builder.Build(context.TODO(), second) + require.NoError(t, err) + assert.Equal(t, `sig=();created;expires;nonce="generated"`, second.Get(headerAcceptSignature)) + assert.Equal(t, 1, calls) + }) } diff --git a/httpsig.go b/httpsig.go index e8d8aef..62f8ce3 100644 --- a/httpsig.go +++ b/httpsig.go @@ -188,7 +188,7 @@ const ( // SignatureParameters contains all signature parameters transmitted in a // Signature-Input entry, including profile-specific extensions. Keys are the // parameter names; values are decoded Structured Fields bare items (for -// example string, Token, int64, float64, bool, []byte, or time.Time). +// example string, Token, int64, float64, bool, or []byte). // Display Strings are exposed as ordinary strings. type SignatureParameters map[string]any @@ -252,19 +252,14 @@ type SignatureInfo struct { } // KeyResolver resolves a trusted verification key for a specific HTTP message -// signature. The resolver implementation is responsible for establishing trust -// in the key // material and any required binding to a key source or credential. -// Returning KeyInfo without an error indicates that the key is acceptable for this -// verification attempt. -// -// ResolveKey is called before cryptographic verification. SignatureInfo and -// its Message contain unverified, potentially sender-controlled data. A -// resolver must not treat this data as an authenticated identity or use it -// for unrestricted remote lookups. It must not mutate SignatureInfo.Message, -// Components, Parameters, or their mutable contents: these are shared with -// the verification process and, on success, with VerifiedSignature. +// signature. type KeyResolver interface { // ResolveKey returns the trusted key and optional metadata for info. + // It is called before cryptographic verification. SignatureInfo and its + // Message contain unverified, sender-controlled data. The implementation + // must not mutate SignatureInfo.Message, Components, Parameters, or their + // mutable contents: these are shared with the verification process and, on + // success, with VerifiedSignature. ResolveKey(ctx context.Context, info SignatureInfo) (KeyInfo, error) } diff --git a/message.go b/message.go index 1b77352..221705d 100644 --- a/message.go +++ b/message.go @@ -144,7 +144,7 @@ func MessageForResponse(req *http.Request, respHeader http.Header, body []byte, // fields supply data used by component identifiers with the ;req parameter. // Not every field is necessarily covered by the signature. type Message struct { - // Context is used for key resolution, nonce generation, and nonce checks. + // Context is passed to key resolution and Accept-Signature nonce generation. Context context.Context //nolint: containedctx // Method is the associated HTTP request method. diff --git a/nonce.go b/nonce.go index 066c4ac..aceec9c 100644 --- a/nonce.go +++ b/nonce.go @@ -1,14 +1,10 @@ package httpsig -import ( - "context" - "crypto/rand" - "encoding/base64" -) +import "context" -// NonceGetter supplies a nonce for a newly generated signature or an -// Accept-Signature negotiation request. An empty result omits the parameter; -// implementations are responsible for producing appropriate nonce values. +// NonceGetter supplies a nonce for an Accept-Signature request. An empty +// result omits the nonce parameter. Generating and correlating nonce values +// is the responsibility of the calling application. type NonceGetter interface { // GetNonce returns a nonce or an error for the given context. GetNonce(ctx context.Context) (string, error) @@ -17,16 +13,5 @@ type NonceGetter interface { // NonceGetterFunc adapts a function to the NonceGetter interface. type NonceGetterFunc func(ctx context.Context) (string, error) -// GetNonce calls the wrapped nonce-generating function. +// GetNonce calls the wrapped function. func (ng NonceGetterFunc) GetNonce(ctx context.Context) (string, error) { return ng(ctx) } - -type nonceGetter struct{} - -func (n nonceGetter) GetNonce(_ context.Context) (string, error) { - b := make([]byte, 16) - if _, err := rand.Read(b); err != nil { - return "", err - } - - return base64.URLEncoding.EncodeToString(b), nil -} diff --git a/options.go b/options.go index f2cec9c..94a3bd5 100644 --- a/options.go +++ b/options.go @@ -16,11 +16,16 @@ type signOptions struct { parameters []parameterOption } +type acceptSignatureBuildOptions struct { + nonce string + nonceSet bool +} + type sigNegotiationOptions struct { opts []AcceptSignatureOption } -// SignerOption configures how a Signer constructs HTTP message signatures. +// SignerOption configures the signing policy of a Signer. type SignerOption interface { applySignerOption(s *signer) error } @@ -30,52 +35,42 @@ type SignOption interface { applySignOption(opts *signOptions) error } -// SignatureNegotiationOption configures the additional values requested by -// WithSignatureNegotiation beyond the verifier's existing requirements. +// SignatureNegotiationOption configures requests additional to the verifier's +// signature requirements. type SignatureNegotiationOption interface { applySignatureNegotiationOption(opts *sigNegotiationOptions) } -// VerifierOption configures which signatures to verify and which generic -// checks to apply. Options can be provided to NewVerifier or used within -// WithRequiredTag for per-tag expectations. +// VerifierOption configures signature selection or verification requirements. +// It can also be used within WithRequiredTag for per-tag requirements. type VerifierOption interface { applyVerifierOption(v *verifier, e *expectations, inTag bool) error } -// AcceptSignatureOption configures the Accept-Signature request produced by -// NewAcceptSignature and AcceptSignatureBuilder.Build. +// AcceptSignatureOption configures an AcceptSignatureBuilder. type AcceptSignatureOption interface { applyAcceptSignatureOption(builder *AcceptSignatureBuilder) error } +// AcceptSignatureBuildOption configures a single AcceptSignatureBuilder.Build call. +type AcceptSignatureBuildOption interface { + applyAcceptSignatureBuildOption(opts *acceptSignatureBuildOptions) error +} + type signerOptionFunc func(*signer) error func (f signerOptionFunc) applySignerOption(s *signer) error { return f(s) } -type signatureNegotiationOptionFunc func(*sigNegotiationOptions) - -func (f signatureNegotiationOptionFunc) applySignatureNegotiationOption(opts *sigNegotiationOptions) { - f(opts) -} - type verifierOptionFunc func(*verifier, *expectations, bool) error func (f verifierOptionFunc) applyVerifierOption(v *verifier, e *expectations, inTag bool) error { return f(v, e, inTag) } -type acceptSignatureOptionFunc func(*AcceptSignatureBuilder) error - -func (f acceptSignatureOptionFunc) applyAcceptSignatureOption(asb *AcceptSignatureBuilder) error { - return f(asb) -} - -// WithLabel configures the technical signature label. -// NOTE: Labels are not signed and may be renamed if they collide with existing -// signature labels in a message. +// WithLabel specifies the technical label for a signature or an +// Accept-Signature request. An empty label leaves the current label unchanged. func WithLabel(label string) labelOption { return labelOption(label) } @@ -110,9 +105,8 @@ func (o labelOption) applySignatureNegotiationOption(opts *sigNegotiationOptions opts.opts = append(opts.opts, o) } -// WithTTL sets how long the generated signature remains valid by controlling -// its expires parameter. A non-positive duration omits expires from the -// generated Signature-Input. +// WithTTL specifies the interval between the created and expires signature +// parameters. A non-positive duration omits expires. func WithTTL(ttl time.Duration) SignerOption { return signerOptionFunc(func(s *signer) error { s.ttl = ttl @@ -121,11 +115,8 @@ func WithTTL(ttl time.Duration) SignerOption { }) } -// WithComponents configures HTTP fields and derived component identifiers. -// NewSigner signs these components, NewVerifier requires them to be covered, -// and NewAcceptSignature requests their coverage from the peer. -// If the signer covers its own "content-digest" field, it also generates or -// updates that field from the message body. +// WithComponents specifies component identifiers to cover when signing, +// require during verification, or request in Accept-Signature. func WithComponents(identifiers ...string) componentsOption { return componentsOption{identifiers: identifiers} } @@ -161,7 +152,8 @@ func (o componentsOption) applyAcceptSignatureOption(asb *AcceptSignatureBuilder return nil } -// WithTag configures the application-defined tag signature parameter. +// WithTag specifies an application-defined tag for signing or +// Accept-Signature requests. func WithTag(tag string) tagOption { return tagOption(tag) } @@ -182,22 +174,8 @@ func (o tagOption) applyAcceptSignatureOption(asb *AcceptSignatureBuilder) error return nil } -// WithNonce configures the source for the nonce signature parameter. -// A nil getter leaves the configured source unchanged. If the getter returns -// an empty string, the nonce parameter is omitted. -func WithNonce(ng NonceGetter) SignerOption { - return signerOptionFunc(func(s *signer) error { - if ng != nil { - s.ng = ng - } - - return nil - }) -} - -// WithContentDigestAlgorithm selects the algorithm used to generate -// Content-Digest when that component is covered. Unsupported algorithms -// cause an error. +// WithContentDigestAlgorithm selects the algorithm for generating a covered +// Content-Digest. An unsupported algorithm causes ErrUnsupportedAlgorithm. func WithContentDigestAlgorithm(alg DigestAlgorithm) SignerOption { return signerOptionFunc(func(s *signer) error { if _, known := supportedAlgs[alg]; !known { @@ -210,8 +188,8 @@ func WithContentDigestAlgorithm(alg DigestAlgorithm) SignerOption { }) } -// WithKeyID configures the keyid signature parameter. An empty value is -// ignored by the Signer and omitted from an Accept-Signature request. +// WithKeyID specifies the keyid parameter for signing or Accept-Signature. +// An empty value is ignored when signing and omitted from Accept-Signature. func WithKeyID(keyID string) keyIDOption { return keyIDOption(keyID) } @@ -236,7 +214,8 @@ func (o keyIDOption) applySignatureNegotiationOption(opts *sigNegotiationOptions opts.opts = append(opts.opts, o) } -// WithAlg includes the alg signature parameter of the given Key. +// WithAlg includes the selected Key.Algorithm as the alg signature parameter. +// It does not select or change the signing algorithm. func WithAlg() SignerOption { return signerOptionFunc(func(s *signer) error { s.includeAlg = true @@ -245,11 +224,12 @@ func WithAlg() SignerOption { }) } -// WithParameter adds a static or per-call signature parameter to Signature-Input. +// WithParameter specifies a signature parameter for NewSigner or an individual +// Sign call. It also allows AcceptSignatureBuilder.Build to request a nonce. // Extension values may be string, Token, bool, int, int64, float64, or []byte. -// Standard RFC 9421 parameter names are reserved, except that Sign permits -// "nonce" as a non-empty string, overriding the configured nonce source for -// that call. Duplicate parameter names are rejected. +// Standard RFC 9421 parameter names are reserved, except for a non-empty +// string nonce on Sign or Build. Build accepts no other parameter names. +// Duplicate names are rejected. func WithParameter(name string, value any) parameterOption { return parameterOption{name: name, value: value} } @@ -268,13 +248,12 @@ func (o parameterOption) applySignOption(opts *signOptions) error { if opts.nonceSet { return fmt.Errorf("%w: duplicate signature parameter %q", ErrParameter, o.name) } - nonce, ok := o.value.(string) - if !ok || nonce == "" { - return fmt.Errorf("%w: nonce must be a non-empty string", ErrParameter) - } - if err := validateParameter(o.name, nonce); err != nil { + + nonce, err := validateNonceOption(o.value) + if err != nil { return err } + opts.nonce = nonce opts.nonceSet = true @@ -284,8 +263,41 @@ func (o parameterOption) applySignOption(opts *signOptions) error { return addParameter(&opts.parameters, opts.staticParameters, o, false) } -// WithValidityTolerance allows a clock skew of d when checking the created -// and expires signature parameters. +func (o parameterOption) applyAcceptSignatureBuildOption(opts *acceptSignatureBuildOptions) error { + if o.name != string(Nonce) { + return fmt.Errorf("%w: unsupported Accept-Signature parameter %q", ErrParameter, o.name) + } + + if opts.nonceSet { + return fmt.Errorf("%w: duplicate signature parameter %q", ErrParameter, o.name) + } + + nonce, err := validateNonceOption(o.value) + if err != nil { + return err + } + + opts.nonce = nonce + opts.nonceSet = true + + return nil +} + +func validateNonceOption(value any) (string, error) { + nonce, ok := value.(string) + if !ok || nonce == "" { + return "", fmt.Errorf("%w: nonce must be a non-empty string", ErrParameter) + } + + if err := validateParameter(string(Nonce), nonce); err != nil { + return "", err + } + + return nonce, nil +} + +// WithValidityTolerance specifies the allowed clock skew for created and +// expires timestamp checks. func WithValidityTolerance(d time.Duration) VerifierOption { return verifierOptionFunc(func(_ *verifier, e *expectations, _ bool) error { e.tolerance = d @@ -294,7 +306,8 @@ func WithValidityTolerance(d time.Duration) VerifierOption { }) } -// WithMaxAge sets the maximum age of signatures with a created timestamp. +// WithMaxAge specifies the maximum allowed age of a signature with a +// created timestamp. func WithMaxAge(d time.Duration) VerifierOption { return verifierOptionFunc(func(_ *verifier, e *expectations, _ bool) error { e.maxAge = d @@ -303,9 +316,8 @@ func WithMaxAge(d time.Duration) VerifierOption { }) } -// WithRequiredTag selects signatures with the given application tag and -// applies opts to that signature. Each tag may be configured only once. -// An empty tag is not allowed. +// WithRequiredTag specifies a required application-defined tag and its +// per-tag verifier options. Each non-empty tag may be configured only once. func WithRequiredTag(tag string, opts ...VerifierOption) VerifierOption { return verifierOptionFunc(func(ver *verifier, _ *expectations, f bool) error { if f { @@ -337,9 +349,8 @@ func WithRequiredTag(tag string, opts ...VerifierOption) VerifierOption { }) } -// WithValidateAllSignatures verifies every signature in the message. When a -// signature has a configured tag, its per-tag requirements apply; otherwise, -// global requirements apply. +// WithValidateAllSignatures selects all signatures for verification, rather +// than only those with required tags. func WithValidateAllSignatures() VerifierOption { return verifierOptionFunc(func(v *verifier, _ *expectations, _ bool) error { v.validateAllSigs = true @@ -348,9 +359,9 @@ func WithValidateAllSignatures() VerifierOption { }) } -// WithCreatedTimestamp specifies whether created must be present during -// verification or requested in Accept-Signature. If false, a present created -// timestamp is still validated during verification. +// WithCreatedTimestamp specifies whether the created parameter is required +// during verification or requested in Accept-Signature. False makes it +// optional during verification and omits it from Accept-Signature. func WithCreatedTimestamp(flag bool) createdTimestampOption { return createdTimestampOption(flag) } @@ -370,9 +381,9 @@ func (o createdTimestampOption) applyAcceptSignatureOption(asb *AcceptSignatureB return nil } -// WithExpiredTimestamp specifies whether expires must be present during -// verification or requested in Accept-Signature. If false, a present expires -// timestamp is still validated during verification. +// WithExpiredTimestamp specifies whether the expires parameter is required +// during verification or requested in Accept-Signature. False makes it +// optional during verification and omits it from Accept-Signature. func WithExpiredTimestamp(flag bool) expiredTimestampOption { return expiredTimestampOption(flag) } @@ -392,11 +403,9 @@ func (o expiredTimestampOption) applyAcceptSignatureOption(asb *AcceptSignatureB return nil } -// WithSignatureNegotiation enables Accept-Signature negotiation when a -// required signature or required component or parameter is missing. -// -// Negotiation reuses the relevant verifier requirements; opts specify only -// additional requests such as a key ID, nonce, algorithm, or label. +// WithSignatureNegotiation enables Accept-Signature negotiation based on the +// verifier's requirements. Its options specify additional requests that cannot +// be derived from those requirements. func WithSignatureNegotiation(opts ...SignatureNegotiationOption) VerifierOption { no := &sigNegotiationOptions{opts: make([]AcceptSignatureOption, 0, len(opts))} for _, opt := range opts { @@ -415,15 +424,8 @@ func WithSignatureNegotiation(opts ...SignatureNegotiationOption) VerifierOption }) } -// WithRequestedNonce supplies the nonce source for Accept-Signature -// negotiation. -func WithRequestedNonce(ng NonceGetter) SignatureNegotiationOption { - return signatureNegotiationOptionFunc(func(sno *sigNegotiationOptions) { - sno.opts = append(sno.opts, WithExpectedNonce(ng)) - }) -} - -// WithSignatureAlgorithm requests an alg value from the peer. +// WithSignatureAlgorithm specifies an alg parameter to request in +// Accept-Signature. It does not select a signing algorithm. func WithSignatureAlgorithm(alg SignatureAlgorithm) signatureAlgorithmOption { return signatureAlgorithmOption(alg) } @@ -440,22 +442,30 @@ func (o signatureAlgorithmOption) applySignatureNegotiationOption(opts *sigNegot opts.opts = append(opts.opts, o) } -// WithExpectedNonce configures the nonce source for Accept-Signature. -// A nil getter leaves the configured source unchanged. -func WithExpectedNonce(ng NonceGetter) AcceptSignatureOption { - // TODO: What can we do for profiles which make use of nonces but in a different parameter - return acceptSignatureOptionFunc(func(asb *AcceptSignatureBuilder) error { - if ng != nil { - asb.nonceGetter = ng - } +// WithNonceGetter configures a nonce source for Accept-Signature, including +// verifier-based negotiation. A nil getter leaves the source unchanged. +func WithNonceGetter(ng NonceGetter) nonceGetterOption { + return nonceGetterOption{getter: ng} +} - return nil - }) +type nonceGetterOption struct { + getter NonceGetter } -// WithContentDigestAlgorithmPreferences sets the Want-Content-Digest -// preferences for NewAcceptSignature or WithSignatureNegotiation when the -// requested components contain content-digest. +func (o nonceGetterOption) applyAcceptSignatureOption(asb *AcceptSignatureBuilder) error { + if o.getter != nil { + asb.nonceGetter = o.getter + } + + return nil +} + +func (o nonceGetterOption) applySignatureNegotiationOption(opts *sigNegotiationOptions) { + opts.opts = append(opts.opts, o) +} + +// WithContentDigestAlgorithmPreferences specifies the algorithms and +// preferences to request in Want-Content-Digest. func WithContentDigestAlgorithmPreferences(prefs ...AlgorithmPreference) contentDigestAlgorithmPreferencesOption { return prefs } @@ -517,6 +527,7 @@ func addParameter( return fmt.Errorf("%w: duplicate signature parameter %q", ErrParameter, option.name) } } + for _, param := range *parameters { if param.name == option.name { return fmt.Errorf("%w: duplicate signature parameter %q", ErrParameter, option.name) @@ -539,7 +550,7 @@ func validateParameter(name string, value any) error { validationParams.Add(name, value) if _, err := httpsfv.Marshal(httpsfv.Item{Value: true, Params: validationParams}); err != nil { - return fmt.Errorf("%w: invalid signature parameter %q: %v", ErrParameter, name, err) + return fmt.Errorf("%w: invalid signature parameter %q: %w", ErrParameter, name, err) } return nil diff --git a/options_test.go b/options_test.go new file mode 100644 index 0000000..a6da399 --- /dev/null +++ b/options_test.go @@ -0,0 +1,938 @@ +package httpsig + +import ( + "context" + "fmt" + "strings" + "testing" + "time" + + "github.com/dunglas/httpsfv" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestWithLabelForSigner(t *testing.T) { + t.Parallel() + + for uc, tc := range map[string]struct { + label string + shouldUpdate bool + }{ + "empty label": {shouldUpdate: false}, + "not empty label": {label: "foo", shouldUpdate: true}, + } { + t.Run(uc, func(t *testing.T) { + s := &signer{label: "test"} + + err := WithLabel(tc.label).applySignerOption(s) + require.NoError(t, err) + + if tc.shouldUpdate { + require.Equal(t, tc.label, s.label) + } else { + require.Equal(t, "test", s.label) + } + }) + } +} + +func TestWithLabelForSign(t *testing.T) { + t.Parallel() + + for uc, tc := range map[string]struct { + label string + want string + }{ + "empty label leaves per-call label unchanged": {want: "initial"}, + "per-call label": {label: "request", want: "request"}, + } { + t.Run(uc, func(t *testing.T) { + opts := &signOptions{label: "initial"} + + err := WithLabel(tc.label).applySignOption(opts) + + require.NoError(t, err) + assert.Equal(t, tc.want, opts.label) + }) + } +} + +func TestWithLabelForAcceptSignature(t *testing.T) { + t.Parallel() + + for uc, tc := range map[string]struct { + label string + exp string + }{ + "empty label": {exp: "foo"}, + "custom label": {label: "bar", exp: "bar"}, + } { + t.Run(uc, func(t *testing.T) { + asb := &AcceptSignatureBuilder{label: "foo"} + + err := WithLabel(tc.label).applyAcceptSignatureOption(asb) + + require.NoError(t, err) + assert.Equal(t, tc.exp, asb.label) + }) + } +} + +func TestWithTTL(t *testing.T) { + t.Parallel() + + ttl := 1 * time.Second + s := &signer{ttl: 30 * time.Second} + + err := WithTTL(ttl).applySignerOption(s) + + require.NoError(t, err) + require.Equal(t, ttl, s.ttl) +} + +func TestWithComponentsForSigner(t *testing.T) { + t.Parallel() + + for uc, tc := range map[string]struct { + identifiers []string + err error + }{ + "multiple valid identifier": {identifiers: []string{"@status;req", "@method"}}, + "invalid identifier": {identifiers: []string{"@foo"}, err: ErrUnsupportedComponentIdentifier}, + } { + t.Run(uc, func(t *testing.T) { + s := &signer{} + + err := WithComponents(tc.identifiers...).applySignerOption(s) + + if tc.err != nil { + require.Error(t, err) + require.ErrorIs(t, err, tc.err) + } else { + require.NoError(t, err) + require.Len(t, s.ids, len(tc.identifiers)) + + for i, id := range s.ids { + vals := strings.Split(tc.identifiers[i], ";") + assert.Equal(t, vals[0], id.Value) + } + } + }) + } +} + +func TestWithComponentsForVerifier(t *testing.T) { + t.Parallel() + + for uc, tc := range map[string]struct { + identifiers []string + err error + }{ + "multiple valid identifier": {identifiers: []string{"@status;req", "@method"}}, + "invalid identifier": {identifiers: []string{"@foo"}, err: ErrUnsupportedComponentIdentifier}, + } { + t.Run(uc, func(t *testing.T) { + v := &verifier{} + exp := &expectations{} + + err := WithComponents(tc.identifiers...).applyVerifierOption(v, exp, false) + + if tc.err != nil { + require.Error(t, err) + require.ErrorIs(t, err, tc.err) + } else { + require.NoError(t, err) + assert.Empty(t, v.tagExpectations) + require.Len(t, exp.identifiers, len(tc.identifiers)) + + for i, id := range exp.identifiers { + vals := strings.Split(tc.identifiers[i], ";") + assert.Equal(t, vals[0], id.Value) + } + } + }) + } +} + +func TestWithComponentsForAcceptSignature(t *testing.T) { + t.Parallel() + + for uc, tc := range map[string]struct { + identifiers []string + assert func(t *testing.T, err error, asb *AcceptSignatureBuilder) + }{ + "no identifiers provided": { + assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) { + t.Helper() + + require.NoError(t, err) + assert.False(t, asb.wantContentDigest) + assert.Empty(t, asb.identifiers) + }, + }, + "invalid identifiers provided": { + identifiers: []string{"@foo"}, + assert: func(t *testing.T, err error, _ *AcceptSignatureBuilder) { + t.Helper() + + require.Error(t, err) + require.ErrorIs(t, err, ErrUnsupportedComponentIdentifier) + }, + }, + "valid identifiers without content-digest": { + identifiers: []string{"@status", "x-foo-bar"}, + assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) { + t.Helper() + + require.NoError(t, err) + assert.False(t, asb.wantContentDigest) + assert.Len(t, asb.identifiers, 2) + assert.Equal(t, "@status", asb.identifiers[0].Value) + assert.Equal(t, "x-foo-bar", asb.identifiers[1].Value) + }, + }, + "valid identifiers with content-digest": { + identifiers: []string{"@status", "content-digest", "x-foo-bar"}, + assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) { + t.Helper() + + require.NoError(t, err) + assert.True(t, asb.wantContentDigest) + assert.Len(t, asb.identifiers, 3) + assert.Equal(t, "@status", asb.identifiers[0].Value) + assert.Equal(t, "content-digest", asb.identifiers[1].Value) + assert.Equal(t, "x-foo-bar", asb.identifiers[2].Value) + }, + }, + } { + t.Run(uc, func(t *testing.T) { + asb := &AcceptSignatureBuilder{label: "foo"} + + err := WithComponents(tc.identifiers...).applyAcceptSignatureOption(asb) + + tc.assert(t, err, asb) + }) + } +} + +func TestWithTagForSigner(t *testing.T) { + t.Parallel() + + for uc, tc := range map[string]struct { + tag string + want string + }{ + "empty tag leaves current tag unchanged": {want: "initial"}, + "custom tag": {tag: "custom", want: "custom"}, + } { + t.Run(uc, func(t *testing.T) { + s := &signer{tag: "initial"} + + err := WithTag(tc.tag).applySignerOption(s) + + require.NoError(t, err) + assert.Equal(t, tc.want, s.tag) + }) + } +} + +func TestWithTagForAcceptSignature(t *testing.T) { + t.Parallel() + + for uc, tag := range map[string]string{ + "empty tag": "", + "custom tag": "foo", + } { + t.Run(uc, func(t *testing.T) { + asb := &AcceptSignatureBuilder{} + + err := WithTag(tag).applyAcceptSignatureOption(asb) + + require.NoError(t, err) + assert.Equal(t, tag, asb.tag) + }) + } +} + +func TestWithContentDigestAlgorithm(t *testing.T) { + t.Parallel() + + for uc, tc := range map[string]struct { + alg DigestAlgorithm + err error + }{ + "valid algorithm": {alg: Sha512}, + "invalid algorithm": {alg: DigestAlgorithm("md4"), err: ErrUnsupportedAlgorithm}, + } { + t.Run(uc, func(t *testing.T) { + s := &signer{} + + err := WithContentDigestAlgorithm(tc.alg).applySignerOption(s) + + if tc.err != nil { + require.Error(t, err) + require.ErrorIs(t, err, tc.err) + } else { + require.NoError(t, err) + assert.Equal(t, tc.alg, s.cdAlg) + } + }) + } +} + +func TestWithKeyIDForSigner(t *testing.T) { + t.Parallel() + + for uc, tc := range map[string]struct { + keyID string + want string + }{ + "empty key ID": {want: "initial"}, + "key ID set": {keyID: "new-id", want: "new-id"}, + } { + t.Run(uc, func(t *testing.T) { + s := &signer{keyID: "initial"} + + err := WithKeyID(tc.keyID).applySignerOption(s) + + require.NoError(t, err) + assert.Equal(t, tc.want, s.keyID) + }) + } +} + +func TestWithKeyIDForAcceptSignature(t *testing.T) { + t.Parallel() + + for uc, keyID := range map[string]string{ + "no actual data provided": "", + "KeyAlg provided": "test", + } { + t.Run(uc, func(t *testing.T) { + asb := &AcceptSignatureBuilder{} + + err := WithKeyID(keyID).applyAcceptSignatureOption(asb) + + require.NoError(t, err) + assert.Equal(t, keyID, asb.keyID) + }) + } +} + +func TestWithAlgForSigner(t *testing.T) { + t.Parallel() + + s := &signer{} + + err := WithAlg().applySignerOption(s) + + require.NoError(t, err) + assert.True(t, s.includeAlg) +} + +func TestWithParameterForSigner(t *testing.T) { + t.Parallel() + + t.Run("supported parameter types", func(t *testing.T) { + for uc, tc := range map[string]struct { + value any + want any + }{ + "string": {value: "value", want: "value"}, + "token": {value: Token("value"), want: httpsfv.Token("value")}, + "integer": {value: 42, want: int64(42)}, + "int64": {value: int64(42), want: int64(42)}, + "decimal": {value: 1.5, want: 1.5}, + "boolean": {value: true, want: true}, + "byte sequence": {value: []byte("value"), want: []byte("value")}, + } { + t.Run(uc, func(t *testing.T) { + s := &signer{} + + err := WithParameter("example", tc.value).applySignerOption(s) + + require.NoError(t, err) + require.Len(t, s.parameters, 1) + assert.Equal(t, "example", s.parameters[0].name) + assert.Equal(t, tc.want, s.parameters[0].value) + }) + } + }) + + t.Run("static byte sequence is copied", func(t *testing.T) { + value := []byte("before") + s := &signer{} + + err := WithParameter("example", value).applySignerOption(s) + require.NoError(t, err) + + value[0] = 'X' + assert.Equal(t, []byte("before"), s.parameters[0].value) + }) + + for uc, param := range map[string]parameterOption{ + "reserved parameter": WithParameter("created", int64(1)), + "static nonce": WithParameter("nonce", "fixed"), + "invalid name": WithParameter("invalid name", "value"), + "invalid string": WithParameter("example", "bad\nvalue"), + "unsupported type": WithParameter("example", struct{}{}), + } { + t.Run(uc, func(t *testing.T) { + s := &signer{} + + err := param.applySignerOption(s) + + require.ErrorIs(t, err, ErrParameter) + assert.Empty(t, s.parameters) + }) + } + + t.Run("duplicate parameter", func(t *testing.T) { + s := &signer{} + require.NoError(t, WithParameter("example", "first").applySignerOption(s)) + + err := WithParameter("example", "second").applySignerOption(s) + + require.ErrorIs(t, err, ErrParameter) + require.Len(t, s.parameters, 1) + assert.Equal(t, "first", s.parameters[0].value) + }) +} + +func TestWithParameterForSign(t *testing.T) { + t.Parallel() + + t.Run("per-call nonce", func(t *testing.T) { + opts := &signOptions{} + + err := WithParameter("nonce", "request-nonce").applySignOption(opts) + + require.NoError(t, err) + assert.True(t, opts.nonceSet) + assert.Equal(t, "request-nonce", opts.nonce) + assert.Empty(t, opts.parameters) + }) + + t.Run("additional parameter", func(t *testing.T) { + opts := &signOptions{} + + err := WithParameter("extension", Token("value")).applySignOption(opts) + + require.NoError(t, err) + require.Len(t, opts.parameters, 1) + assert.Equal(t, "extension", opts.parameters[0].name) + assert.Equal(t, httpsfv.Token("value"), opts.parameters[0].value) + }) + + for uc, param := range map[string]parameterOption{ + "empty nonce": WithParameter("nonce", ""), + "nonce with incorrect type": WithParameter("nonce", Token("value")), + "invalid nonce string": WithParameter("nonce", "bad\nvalue"), + "reserved parameter": WithParameter("expires", int64(1)), + } { + t.Run(uc, func(t *testing.T) { + opts := &signOptions{} + + err := param.applySignOption(opts) + + require.ErrorIs(t, err, ErrParameter) + assert.False(t, opts.nonceSet) + assert.Empty(t, opts.parameters) + }) + } + + t.Run("duplicate nonce", func(t *testing.T) { + opts := &signOptions{} + require.NoError(t, WithParameter("nonce", "first").applySignOption(opts)) + + err := WithParameter("nonce", "second").applySignOption(opts) + + require.ErrorIs(t, err, ErrParameter) + assert.Equal(t, "first", opts.nonce) + }) + + t.Run("duplicate additional parameter", func(t *testing.T) { + opts := &signOptions{} + require.NoError(t, WithParameter("extension", "first").applySignOption(opts)) + + err := WithParameter("extension", "second").applySignOption(opts) + + require.ErrorIs(t, err, ErrParameter) + require.Len(t, opts.parameters, 1) + assert.Equal(t, "first", opts.parameters[0].value) + }) + + t.Run("collision with a static parameter", func(t *testing.T) { + opts := &signOptions{ + staticParameters: []parameterOption{{name: "extension", value: "static"}}, + } + + err := WithParameter("extension", "per-call").applySignOption(opts) + + require.ErrorIs(t, err, ErrParameter) + assert.Empty(t, opts.parameters) + }) +} + +func TestWithParameterForAcceptSignatureBuild(t *testing.T) { + t.Parallel() + + for uc, tc := range map[string]struct { + param parameterOption + want string + wantErr bool + }{ + "nonce": {param: WithParameter("nonce", "request-nonce"), want: "request-nonce"}, + "other parameter": {param: WithParameter("extension", "value"), wantErr: true}, + "empty nonce": {param: WithParameter("nonce", ""), wantErr: true}, + "nonce with incorrect type": {param: WithParameter("nonce", Token("value")), wantErr: true}, + "invalid nonce string": {param: WithParameter("nonce", "bad\nvalue"), wantErr: true}, + } { + t.Run(uc, func(t *testing.T) { + opts := &acceptSignatureBuildOptions{} + + err := tc.param.applyAcceptSignatureBuildOption(opts) + + if tc.wantErr { + require.ErrorIs(t, err, ErrParameter) + assert.False(t, opts.nonceSet) + + return + } + + require.NoError(t, err) + assert.True(t, opts.nonceSet) + assert.Equal(t, tc.want, opts.nonce) + }) + } + + t.Run("duplicate nonce", func(t *testing.T) { + opts := &acceptSignatureBuildOptions{} + require.NoError(t, WithParameter("nonce", "first").applyAcceptSignatureBuildOption(opts)) + + err := WithParameter("nonce", "second").applyAcceptSignatureBuildOption(opts) + + require.ErrorIs(t, err, ErrParameter) + assert.Equal(t, "first", opts.nonce) + }) +} + +func TestWithValidityTolerance(t *testing.T) { + t.Parallel() + + v := &verifier{} + exp := &expectations{} + + err := WithValidityTolerance(1*time.Minute).applyVerifierOption(v, exp, false) + require.NoError(t, err) + + assert.Empty(t, v.tagExpectations) + assert.Equal(t, 1*time.Minute, exp.tolerance) +} + +func TestWithMaxAge(t *testing.T) { + t.Parallel() + + v := &verifier{} + exp := &expectations{} + + err := WithMaxAge(15*time.Minute).applyVerifierOption(v, exp, false) + require.NoError(t, err) + + assert.Equal(t, 15*time.Minute, exp.maxAge) +} + +func TestWithRequiredTag(t *testing.T) { + t.Parallel() + + for uc, tc := range map[string]struct { + opts []VerifierOption + assert func(t *testing.T, err error, exp *expectations) + }{ + "without options": { + assert: func(t *testing.T, err error, exp *expectations) { + t.Helper() + + require.NoError(t, err) + require.NotNil(t, exp) + assert.Empty(t, exp.identifiers) + assert.Equal(t, time.Duration(-1), exp.tolerance) //nolint:testifylint + }, + }, + "with identifiers only": { + opts: []VerifierOption{ + WithComponents("@status"), + }, + assert: func(t *testing.T, err error, exp *expectations) { + t.Helper() + + require.NoError(t, err) + require.NotNil(t, exp) + assert.Len(t, exp.identifiers, 1) + assert.Equal(t, "@status", exp.identifiers[0].Value) + assert.Equal(t, time.Duration(-1), exp.tolerance) //nolint:testifylint + }, + }, + "with tolerance only": { + opts: []VerifierOption{ + WithValidityTolerance(5 * time.Minute), + }, + assert: func(t *testing.T, err error, exp *expectations) { + t.Helper() + + require.NoError(t, err) + require.NotNil(t, exp) + assert.Empty(t, exp.identifiers) + assert.Equal(t, 5*time.Minute, exp.tolerance) + }, + }, + "with all possible options": { + opts: []VerifierOption{ + WithComponents("@status"), + WithValidityTolerance(5 * time.Minute), + }, + assert: func(t *testing.T, err error, exp *expectations) { + t.Helper() + + require.NoError(t, err) + require.NotNil(t, exp) + assert.Len(t, exp.identifiers, 1) + assert.Equal(t, "@status", exp.identifiers[0].Value) + assert.Equal(t, 5*time.Minute, exp.tolerance) + }, + }, + "with unsupported identifier": { + opts: []VerifierOption{ + WithComponents("@foo"), + }, + assert: func(t *testing.T, err error, exp *expectations) { + t.Helper() + + require.Error(t, err) + require.ErrorIs(t, err, ErrUnsupportedComponentIdentifier) + require.Nil(t, exp) + }, + }, + "with nested WithRequiredTag": { + opts: []VerifierOption{ + WithRequiredTag("foo"), + }, + assert: func(t *testing.T, err error, _ *expectations) { + t.Helper() + + require.Error(t, err) + require.ErrorContains(t, err, "WithRequiredTag") + }, + }, + } { + t.Run(uc, func(t *testing.T) { + v := &verifier{tagExpectations: make(map[string]*expectations)} + + recoverIfPanics := func(t *testing.T, f func() error) (err error) { + t.Helper() + + defer func() { + var ok bool + + if res := recover(); res != nil { + if err, ok = res.(error); !ok { + err = fmt.Errorf("%v", res) + } + } + }() + + err = f() + + return + } + + err := recoverIfPanics(t, func() error { + return WithRequiredTag("test", tc.opts...).applyVerifierOption(v, nil, false) + }) + if err == nil { + require.Len(t, v.tagExpectations, 1) + } + + tc.assert(t, err, v.tagExpectations["test"]) + }) + } + + t.Run("empty required tag", func(t *testing.T) { + v := &verifier{tagExpectations: make(map[string]*expectations)} + + err := WithRequiredTag("").applyVerifierOption(v, nil, false) + + require.ErrorIs(t, err, ErrParameter) + assert.Empty(t, v.tagExpectations) + }) + + t.Run("with duplicate WithRequiredTag", func(t *testing.T) { + v := &verifier{tagExpectations: map[string]*expectations{"foo": {}}} + + err := WithRequiredTag("foo", nil).applyVerifierOption(v, nil, false) + require.Error(t, err) + require.ErrorIs(t, err, ErrParameter) + require.ErrorContains(t, err, "already configured") + }) +} + +func TestWithValidateAllSignatures(t *testing.T) { + t.Parallel() + + v := &verifier{} + + err := WithValidateAllSignatures().applyVerifierOption(v, &expectations{}, false) + + require.NoError(t, err) + assert.True(t, v.validateAllSigs) +} + +func TestWithCreatedTimestampForVerifier(t *testing.T) { + t.Parallel() + + for uc, required := range map[string]bool{ + "timestamp required": true, + "timestamp optional": false, + } { + t.Run(uc, func(t *testing.T) { + exp := &expectations{} + + err := WithCreatedTimestamp(required).applyVerifierOption(&verifier{}, exp, false) + + require.NoError(t, err) + require.NotNil(t, exp.reqCreatedTS) + assert.Equal(t, *exp.reqCreatedTS, required) + }) + } +} + +func TestWithCreatedTimestampForAcceptSignature(t *testing.T) { + t.Parallel() + + for uc, requested := range map[string]bool{ + "timestamp requested": true, + "timestamp not requested": false, + } { + t.Run(uc, func(t *testing.T) { + asb := &AcceptSignatureBuilder{addCreatedTS: !requested} + + err := WithCreatedTimestamp(requested).applyAcceptSignatureOption(asb) + + require.NoError(t, err) + assert.Equal(t, requested, asb.addCreatedTS) + }) + } +} + +func TestWithExpiredTimestampForVerifier(t *testing.T) { + t.Parallel() + + for uc, required := range map[string]bool{ + "timestamp required": true, + "timestamp optional": false, + } { + t.Run(uc, func(t *testing.T) { + exp := &expectations{} + + err := WithExpiredTimestamp(required).applyVerifierOption(&verifier{}, exp, false) + + require.NoError(t, err) + require.NotNil(t, exp.reqExpiresTS) + assert.Equal(t, *exp.reqExpiresTS, required) + }) + } +} + +func TestWithExpiredTimestampForAcceptSignature(t *testing.T) { + t.Parallel() + + for uc, requested := range map[string]bool{ + "timestamp requested": true, + "timestamp not requested": false, + } { + t.Run(uc, func(t *testing.T) { + asb := &AcceptSignatureBuilder{addExpiresTS: !requested} + + err := WithExpiredTimestamp(requested).applyAcceptSignatureOption(asb) + + require.NoError(t, err) + assert.Equal(t, requested, asb.addExpiresTS) + }) + } +} + +func TestWithSignatureNegotiation(t *testing.T) { + t.Parallel() + + for uc, tc := range map[string]struct { + opts []SignatureNegotiationOption + assert func(t *testing.T, err error, asb *AcceptSignatureBuilder) + }{ + "without options": { + assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) { + t.Helper() + + require.NoError(t, err) + + require.NotNil(t, asb) + assert.Nil(t, asb.nonceGetter) + assert.Equal(t, "sig", asb.label) + assert.ElementsMatch(t, asb.cdAlgPrefs, []string{"sha-256=5", "sha-512=10"}) + assert.Empty(t, asb.signatureAlgorithm) + assert.Empty(t, asb.keyID) + // not set by any of the options + assert.True(t, asb.addCreatedTS) + assert.True(t, asb.addExpiresTS) + assert.False(t, asb.wantContentDigest) + assert.Empty(t, asb.tag) + assert.Empty(t, asb.identifiers) + }, + }, + "with all possible options": { + opts: []SignatureNegotiationOption{ + WithLabel("foo"), + WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), + WithSignatureAlgorithm(RsaPssSha512), + WithKeyID("bar"), + WithContentDigestAlgorithmPreferences(AlgorithmPreference{Sha512, 2}), + }, + assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) { + t.Helper() + + require.NoError(t, err) + + require.NotNil(t, asb) + require.NotNil(t, asb.nonceGetter) + nonce, err := asb.nonceGetter.GetNonce(context.TODO()) + require.NoError(t, err) + require.Equal(t, "abc", nonce) + assert.Equal(t, "foo", asb.label) + assert.ElementsMatch(t, asb.cdAlgPrefs, []string{"sha-512=2"}) + assert.Equal(t, RsaPssSha512, asb.signatureAlgorithm) + assert.Equal(t, "bar", asb.keyID) + // not set by any of the options + assert.True(t, asb.addCreatedTS) + assert.True(t, asb.addExpiresTS) + assert.False(t, asb.wantContentDigest) + assert.Empty(t, asb.tag) + assert.Empty(t, asb.identifiers) + }, + }, + "with error while applying the option": { + opts: []SignatureNegotiationOption{ + WithContentDigestAlgorithmPreferences(AlgorithmPreference{}), + }, + assert: func(t *testing.T, err error, _ *AcceptSignatureBuilder) { + t.Helper() + + require.Error(t, err) + require.ErrorIs(t, err, ErrParameter) + }, + }, + } { + t.Run(uc, func(t *testing.T) { + v := &verifier{} + exp := &expectations{} + + err := WithSignatureNegotiation(tc.opts...).applyVerifierOption(v, exp, false) + + tc.assert(t, err, exp.asb) + }) + } +} + +func TestWithSignatureAlgorithmForAcceptSignature(t *testing.T) { + t.Parallel() + + for uc, alg := range map[string]SignatureAlgorithm{ + "no actual data provided": SignatureAlgorithm(""), + "KeyAlg provided": RsaPssSha512, + } { + t.Run(uc, func(t *testing.T) { + asb := &AcceptSignatureBuilder{} + + err := WithSignatureAlgorithm(alg).applyAcceptSignatureOption(asb) + + require.NoError(t, err) + assert.Equal(t, alg, asb.signatureAlgorithm) + }) + } +} + +func TestWithNonceGetterForAcceptSignature(t *testing.T) { + t.Parallel() + + for uc, tc := range map[string]struct { + ng NonceGetter + exp NonceGetter + }{ + "nil NonceGetter": {}, + "custom NonceGetter": {ng: &NonceGetterMock{}, exp: &NonceGetterMock{}}, + } { + t.Run(uc, func(t *testing.T) { + asb := &AcceptSignatureBuilder{} + + err := WithNonceGetter(tc.ng).applyAcceptSignatureOption(asb) + + require.NoError(t, err) + assert.Equal(t, tc.exp, asb.nonceGetter) + }) + } +} + +func TestWithNonceGetterNilDoesNotReplaceExisting(t *testing.T) { + t.Parallel() + + getter := &NonceGetterMock{} + builder := &AcceptSignatureBuilder{nonceGetter: getter} + + err := WithNonceGetter(nil).applyAcceptSignatureOption(builder) + + require.NoError(t, err) + assert.Same(t, getter, builder.nonceGetter) +} + +func TestWithContentDigestAlgorithmPreferences(t *testing.T) { + t.Parallel() + + defaultPreference := AlgorithmPreference{Algorithm: Sha256, Preference: 2}.String() + + for uc, tc := range map[string]struct { + prefs []AlgorithmPreference + expErr error + expPrefs []string + }{ + "no preferences provided": { + expPrefs: []string{defaultPreference}, + }, + "no algorithm provided in a preference": { + prefs: []AlgorithmPreference{{Sha256, 0}, {DigestAlgorithm(""), 0}}, + expErr: ErrParameter, + expPrefs: []string{defaultPreference}, + }, + "valid options provided": { + prefs: []AlgorithmPreference{{Sha512, 0}, {Sha256, 1}}, + expPrefs: []string{ + AlgorithmPreference{Sha512, 0}.String(), + AlgorithmPreference{Sha256, 1}.String(), + }, + }, + } { + t.Run(uc, func(t *testing.T) { + asb := &AcceptSignatureBuilder{ + cdAlgPrefs: []string{defaultPreference}, + } + + err := WithContentDigestAlgorithmPreferences(tc.prefs...).applyAcceptSignatureOption(asb) + + if tc.expErr != nil { + require.Error(t, err) + require.ErrorIs(t, err, tc.expErr) + } else { + require.NoError(t, err) + require.ElementsMatch(t, asb.cdAlgPrefs, tc.expPrefs) + } + }) + } +} diff --git a/signature_base.go b/signature_base.go index 1b02346..e444044 100644 --- a/signature_base.go +++ b/signature_base.go @@ -59,7 +59,7 @@ func newSignatureBase(si *signatureInput, msg *Message) (signatureBase, error) { return sigBase, nil } -func (s signatureBase) marshal() ([]byte, error) { +func (s signatureBase) marshal() []byte { var buf bytes.Buffer for i, item := range s.entries { @@ -81,10 +81,10 @@ func (s signatureBase) marshal() ([]byte, error) { buf.WriteString(s.signatureParams) } - return buf.Bytes(), nil + return buf.Bytes() } -func (s signatureBase) components() (map[string]string, error) { +func (s signatureBase) components() map[string]string { result := make(map[string]string, len(s.entries)) for i, item := range s.entries { @@ -98,5 +98,5 @@ func (s signatureBase) components() (map[string]string, error) { result[key] = item.value } - return result, nil + return result } diff --git a/signature_base_test.go b/signature_base_test.go index dcbb9e5..ffbc289 100644 --- a/signature_base_test.go +++ b/signature_base_test.go @@ -62,8 +62,7 @@ func TestNewSignatureBase(t *testing.T) { "content-type": application/json "@signature-params": ("@method" "@authority" "@path" "content-digest" "content-length" "content-type");created=1618884473;keyid="test-key-rsa-pss"` - sigBase, err := base.marshal() - require.NoError(t, err) + sigBase := base.marshal() assert.Equal(t, expected, string(sigBase)) }, @@ -121,8 +120,7 @@ func TestNewSignatureBase(t *testing.T) { "@query-param";name="Cat": meow "@signature-params": ("@query-param";name="Pet" "@query-param";name="Cat");created=1618884473;keyid="test-key-rsa-pss"` - sigBase, err := base.marshal() - require.NoError(t, err) + sigBase := base.marshal() assert.Equal(t, expected, string(sigBase)) }, @@ -155,8 +153,7 @@ func TestSignatureBaseMarshal(t *testing.T) { }, } - res, err := base.marshal() - require.NoError(t, err) + res := base.marshal() assert.Equal(t, "\"@authority\": foo.bar\n\"@method\": GET", string(res)) } @@ -246,8 +243,7 @@ func TestSignatureBaseComponents(t *testing.T) { signatureParams: tc.signatureParams, } - components, err := base.components() - require.NoError(t, err) + components := base.components() assert.Equal(t, tc.expected, components) }) diff --git a/signer.go b/signer.go index ab5b1cf..f339b49 100644 --- a/signer.go +++ b/signer.go @@ -1,7 +1,6 @@ package httpsig import ( - "context" "crypto/ecdsa" "crypto/ed25519" "crypto/rsa" @@ -44,8 +43,8 @@ type Signer interface { // NewSigner creates a Signer using key for cryptographic signing. The key // must contain private or symmetric material compatible with its algorithm. -// By default, signatures use label "sig", include created and a random nonce, -// and expire after 30 seconds. The alg, keyid, and tag parameters are omitted. +// By default, signatures use label "sig", include created, and expire +// after 30 seconds. The alg, keyid, tag, and nonce parameters are omitted. // When generating Content-Digest, the signer uses both SHA-256 and SHA-512 // unless WithContentDigestAlgorithm selects one. func NewSigner(key Key, opts ...SignerOption) (Signer, error) { @@ -57,7 +56,6 @@ func NewSigner(key Key, opts ...SignerOption) (Signer, error) { sig := &signer{ label: "sig", ttl: 30 * time.Second, //nolint:mnd - ng: nonceGetter{}, ps: ps, mu: noopMessageUpdater{}, } @@ -101,7 +99,6 @@ type signer struct { tag string keyID string includeAlg bool - ng NonceGetter ps payloadSigner cdAlg DigestAlgorithm parameters []parameterOption @@ -116,12 +113,9 @@ func (s *signer) Sign(msg *Message, opts ...SignOption) (http.Header, error) { } } - params, err := s.signatureInput(msg.Context, callOptions) - if err != nil { - return nil, err - } + params := s.signatureInput(callOptions) - if err = s.mu.update(msg); err != nil { + if err := s.mu.update(msg); err != nil { return nil, err } @@ -130,12 +124,7 @@ func (s *signer) Sign(msg *Message, opts ...SignOption) (http.Header, error) { return nil, err } - sb, err := base.marshal() - if err != nil { - return nil, err - } - - signature, err := s.ps.signPayload(sb) + signature, err := s.ps.signPayload(base.marshal()) if err != nil { return nil, err } @@ -148,18 +137,9 @@ func (s *signer) Sign(msg *Message, opts ...SignOption) (http.Header, error) { return msg.addSignature(label, signature, params.value) } -func (s *signer) signatureInput(ctx context.Context, opts signOptions) (*signatureInput, error) { +func (s *signer) signatureInput(opts signOptions) *signatureInput { created := currentTime().UTC() - nonce := opts.nonce - if !opts.nonceSet { - var err error - nonce, err = s.ng.GetNonce(ctx) - if err != nil { - return nil, err - } - } - params := httpsfv.NewParams() params.Add(string(Created), created.Unix()) @@ -175,8 +155,8 @@ func (s *signer) signatureInput(ctx context.Context, opts signOptions) (*signatu params.Add(string(Alg), string(s.ps.algorithm())) } - if len(nonce) != 0 { - params.Add(string(Nonce), nonce) + if opts.nonceSet { + params.Add(string(Nonce), opts.nonce) } if len(s.tag) != 0 { @@ -191,5 +171,5 @@ func (s *signer) signatureInput(ctx context.Context, opts signOptions) (*signatu params.Add(param.name, param.value) } - return newSignatureInput(s.ids, params), nil + return newSignatureInput(s.ids, params) } diff --git a/signer_test.go b/signer_test.go index 3ddf4e6..c0ce3b9 100644 --- a/signer_test.go +++ b/signer_test.go @@ -1,7 +1,6 @@ package httpsig import ( - "context" "crypto/ecdsa" "crypto/ed25519" "crypto/elliptic" @@ -69,130 +68,6 @@ func TestNewPayloadSigner(t *testing.T) { } } -func TestWithLabel(t *testing.T) { - t.Parallel() - - for _, tc := range []struct { - uc string - label string - shouldUpdate bool - }{ - {uc: "empty label", label: "", shouldUpdate: false}, - {uc: "not empty label", label: "foo", shouldUpdate: true}, - } { - t.Run(tc.uc, func(t *testing.T) { - s := &signer{label: "test"} - - err := WithLabel(tc.label).applySignerOption(s) - require.NoError(t, err) - - if tc.shouldUpdate { - require.Equal(t, tc.label, s.label) - } else { - require.Equal(t, "test", s.label) - } - }) - } -} - -func TestWithTTL(t *testing.T) { - t.Parallel() - - ttl := 1 * time.Second - s := &signer{ttl: 30 * time.Second} - - err := WithTTL(ttl).applySignerOption(s) - - require.NoError(t, err) - require.Equal(t, ttl, s.ttl) -} - -func TestWithComponentsForSigner(t *testing.T) { - t.Parallel() - - for _, tc := range []struct { - uc string - identifiers []string - err error - }{ - {uc: "multiple valid identifier", identifiers: []string{"@status;req", "@method"}}, - {uc: "invalid identifier", identifiers: []string{"@foo"}, err: ErrUnsupportedComponentIdentifier}, - } { - t.Run(tc.uc, func(t *testing.T) { - s := &signer{} - - err := WithComponents(tc.identifiers...).applySignerOption(s) - - if tc.err != nil { - require.Error(t, err) - require.ErrorIs(t, err, tc.err) - } else { - require.NoError(t, err) - require.Len(t, s.ids, len(tc.identifiers)) - - for i, id := range s.ids { - vals := strings.Split(tc.identifiers[i], ";") - assert.Equal(t, vals[0], id.Value) - } - } - }) - } -} - -func TestWithTag(t *testing.T) { - t.Parallel() - - s := &signer{} - - err := WithTag("test").applySignerOption(s) - require.NoError(t, err) - - assert.Equal(t, "test", s.tag) -} - -func TestWithNonceGetter(t *testing.T) { - t.Parallel() - - s := &signer{} - - err := WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { - return "foo", nil - })).applySignerOption(s) - require.NoError(t, err) - - nonce, err := s.ng.GetNonce(context.TODO()) - require.NoError(t, err) - - assert.Equal(t, "foo", nonce) -} - -func TestWithContentDigestAlgorithm(t *testing.T) { - t.Parallel() - - for _, tc := range []struct { - uc string - alg DigestAlgorithm - err error - }{ - {uc: "valid algorithm", alg: Sha512}, - {uc: "invalid algorithm", alg: DigestAlgorithm("md4"), err: ErrUnsupportedAlgorithm}, - } { - t.Run(tc.uc, func(t *testing.T) { - s := &signer{} - - err := WithContentDigestAlgorithm(tc.alg).applySignerOption(s) - - if tc.err != nil { - require.Error(t, err) - require.ErrorIs(t, err, tc.err) - } else { - require.NoError(t, err) - assert.Equal(t, tc.alg, s.cdAlg) - } - }) - } -} - func TestNewSigner(t *testing.T) { t.Parallel() @@ -297,7 +172,6 @@ func TestNewSigner(t *testing.T) { assert.Equal(t, "sig", s.label) assert.Equal(t, 30*time.Second, s.ttl) assert.IsType(t, &ecdsaSigner{}, s.ps) - assert.NotNil(t, s.ng) assert.Empty(t, s.tag) assert.Empty(t, s.ids) }, @@ -323,7 +197,6 @@ func TestNewSigner(t *testing.T) { assert.Equal(t, "bar", s.label) assert.Equal(t, 1*time.Second, s.ttl) assert.IsType(t, &ecdsaSigner{}, s.ps) - assert.NotNil(t, s.ng) assert.Equal(t, "foo", s.tag) assert.NotEmpty(t, s.ids) }, @@ -396,27 +269,14 @@ func TestSignerSign(t *testing.T) { assert func(t *testing.T, err error, header http.Header) }{ { - uc: "failed creating signature parameters", - key: Key{Algorithm: EcdsaP384Sha384, Material: pkp384}, - opts: []SignerOption{ - WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", errors.New("test error") })), - }, - msg: &Message{ - Method: http.MethodPost, - Authority: "example.com", - URL: testURL, - Header: http.Header{ - "Host": []string{"example.com"}, - "Date": []string{"Tue, 20 Apr 2021 02:07:55 GMT"}, - "Content-Type": []string{"application/json"}, - "Content-Length": []string{"18"}, - }, - IsRequest: true, - }, - assert: func(t *testing.T, err error, _ http.Header) { + uc: "signer omits nonce unless supplied per call", + key: Key{Algorithm: HmacSha256, Material: []byte("secret")}, + opts: []SignerOption{WithTTL(0)}, + msg: &Message{Header: http.Header{}, IsRequest: true}, + assert: func(t *testing.T, err error, header http.Header) { t.Helper() - - require.Error(t, err) + require.NoError(t, err) + assert.Equal(t, `sig=();created=1618884473`, header.Get("Signature-Input")) }, }, { @@ -475,7 +335,6 @@ func TestSignerSign(t *testing.T) { key: Key{Algorithm: HmacSha256, Material: []byte("secret")}, opts: []SignerOption{ WithTTL(0), - WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), WithParameter("example-token", Token("hello")), WithParameter("example-bytes", []byte("data")), }, @@ -492,7 +351,6 @@ func TestSignerSign(t *testing.T) { opts: []SignerOption{ WithTTL(0), WithLabel("static"), - WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), }, signOpts: []SignOption{WithLabel("dynamic")}, msg: &Message{Header: http.Header{}, IsRequest: true}, @@ -503,11 +361,10 @@ func TestSignerSign(t *testing.T) { }, }, { - uc: "per-call nonce overrides configured getter", + uc: "per-call nonce is included", key: Key{Algorithm: HmacSha256, Material: []byte("secret")}, opts: []SignerOption{ WithTTL(0), - WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", errors.New("getter must not be called") })), }, signOpts: []SignOption{WithParameter("nonce", "requested-nonce")}, msg: &Message{Header: http.Header{}, IsRequest: true}, @@ -522,7 +379,6 @@ func TestSignerSign(t *testing.T) { key: Key{Algorithm: HmacSha256, Material: []byte("secret")}, opts: []SignerOption{ WithTTL(0), - WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), WithParameter("static", Token("hello")), }, signOpts: []SignOption{ @@ -611,7 +467,6 @@ func TestSignerSign(t *testing.T) { opts: []SignerOption{ WithAlg(), WithTTL(0), - WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), }, msg: &Message{Header: http.Header{}, IsRequest: true}, assert: func(t *testing.T, err error, header http.Header) { @@ -626,11 +481,11 @@ func TestSignerSign(t *testing.T) { uc: "B.2.1. minimal signature using rsa-pss-sha512", key: Key{Algorithm: RsaPssSha512, Material: tkRSAPSS}, opts: []SignerOption{ - WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "b3k2pp5k7z-50gnwp.yemd", nil })), WithLabel("sig-b21"), WithTTL(0), WithKeyID("test-key-rsa-pss"), }, + signOpts: []SignOption{WithParameter("nonce", "b3k2pp5k7z-50gnwp.yemd")}, msg: &Message{ Method: http.MethodPost, Authority: "example.com", @@ -662,7 +517,6 @@ func TestSignerSign(t *testing.T) { uc: "B.2.2. selective covered components using rsa-pss-sha512", key: Key{Algorithm: RsaPssSha512, Material: tkRSAPSS}, opts: []SignerOption{ - WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), WithLabel("sig-b22"), WithTTL(0), WithComponents("@authority", "content-digest", "@query-param;name=\"Pet\""), @@ -704,7 +558,6 @@ func TestSignerSign(t *testing.T) { uc: "B.2.3. full coverage using rsa-pss-sha512", key: Key{Algorithm: RsaPssSha512, Material: tkRSAPSS}, opts: []SignerOption{ - WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), WithLabel("sig-b23"), WithTTL(0), WithComponents( @@ -747,7 +600,6 @@ func TestSignerSign(t *testing.T) { uc: "B.2.4. signing a response using ecdsa-p256-sha256", key: Key{Algorithm: EcdsaP256Sha256, Material: tkECCP256}, opts: []SignerOption{ - WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), WithLabel("sig-b24"), WithTTL(0), WithComponents("@status", "content-type", "content-digest", "content-length"), @@ -786,7 +638,6 @@ func TestSignerSign(t *testing.T) { uc: "B.2.5. signing a request using hmac-sha256", key: Key{Algorithm: HmacSha256, Material: tkMAC}, opts: []SignerOption{ - WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), WithLabel("sig-b25"), WithTTL(0), WithComponents("date", "@authority", "content-type"), @@ -822,7 +673,6 @@ func TestSignerSign(t *testing.T) { uc: "B.2.6. signing a request using ed25519", key: Key{Algorithm: Ed25519, Material: tkEd25519}, opts: []SignerOption{ - WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), WithLabel("sig-b26"), WithTTL(0), WithComponents("date", "@method", "@path", "@authority", "content-type", "content-length"), @@ -857,7 +707,6 @@ func TestSignerSign(t *testing.T) { uc: "overwrites stale content-digest when signing content-digest component", key: Key{Algorithm: RsaPssSha512, Material: tkRSAPSS}, opts: []SignerOption{ - WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), WithLabel("sig-content-digest"), WithTTL(0), WithComponents("content-digest"), @@ -902,7 +751,6 @@ func TestSignerSign(t *testing.T) { uc: "preserves existing content-digest when content-digest component is not signed", key: Key{Algorithm: RsaPssSha512, Material: tkRSAPSS}, opts: []SignerOption{ - WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), WithLabel("sig-no-content-digest"), WithTTL(0), WithComponents("date", "@method"), @@ -954,7 +802,6 @@ func TestSignerSign(t *testing.T) { s, err := NewSigner(Key{Algorithm: HmacSha256, Material: []byte("secret")}, WithTTL(0), WithLabel("static"), - WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), ) require.NoError(t, err) @@ -968,32 +815,22 @@ func TestSignerSign(t *testing.T) { }) t.Run("per-call nonce does not persist", func(t *testing.T) { - getterCalls := 0 - s, err := NewSigner(Key{Algorithm: HmacSha256, Material: []byte("secret")}, - WithTTL(0), - WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { - getterCalls++ - return "generated-nonce", nil - })), - ) + s, err := NewSigner(Key{Algorithm: HmacSha256, Material: []byte("secret")}, WithTTL(0)) require.NoError(t, err) first, err := s.Sign(&Message{Header: http.Header{}, IsRequest: true}, WithParameter("nonce", "requested-nonce")) require.NoError(t, err) assert.Equal(t, `sig=();created=1618884473;nonce="requested-nonce"`, first.Get("Signature-Input")) - assert.Zero(t, getterCalls) second, err := s.Sign(&Message{Header: http.Header{}, IsRequest: true}) require.NoError(t, err) - assert.Equal(t, `sig=();created=1618884473;nonce="generated-nonce"`, second.Get("Signature-Input")) - assert.Equal(t, 1, getterCalls) + assert.Equal(t, `sig=();created=1618884473`, second.Get("Signature-Input")) }) t.Run("per-call parameters do not persist", func(t *testing.T) { s, err := NewSigner(Key{Algorithm: HmacSha256, Material: []byte("secret")}, WithTTL(0), - WithNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), ) require.NoError(t, err) diff --git a/verifier.go b/verifier.go index abcd136..107cabb 100644 --- a/verifier.go +++ b/verifier.go @@ -48,8 +48,8 @@ type Verifier interface { // NewVerifier creates a Verifier instance. // Without WithValidateAllSignatures, at least one WithRequiredTag is necessary. // By default, created and expires are required and signatures may be at most -// 30 seconds old. The default nonce checker does not reject any nonce. -// Global WithSignatureNegotiation cannot be combined with +// 30 seconds old. Optional created or expires parameters are still checked +// when present. Global WithSignatureNegotiation cannot be combined with // WithValidateAllSignatures. More specific requirements can be set through opts. // //nolint:cyclop @@ -371,11 +371,7 @@ func (v *verifier) verifySignature( return VerifiedSignature{}, err } - components, err := base.components() - if err != nil { - return VerifiedSignature{}, err - } - + components := base.components() params := si.parameters() keyInfo, err := v.keyResolver.ResolveKey(msg.Context, SignatureInfo{ @@ -397,12 +393,7 @@ func (v *verifier) verifySignature( return VerifiedSignature{}, err } - sb, err := base.marshal() - if err != nil { - return VerifiedSignature{}, err - } - - err = verifier.verifyPayload(sb, signature) + err = verifier.verifyPayload(base.marshal(), signature) if err != nil { return VerifiedSignature{}, err } diff --git a/verifier_test.go b/verifier_test.go index 42060b8..635efeb 100644 --- a/verifier_test.go +++ b/verifier_test.go @@ -11,7 +11,6 @@ import ( "encoding/base64" "encoding/pem" "errors" - "fmt" "io" "net/http" "net/url" @@ -77,11 +76,11 @@ func TestExpectationsAssertParameters(t *testing.T) { trueVal := true for _, tc := range []struct { - uc string - params httpsfv.InnerList - exp expectations - expAlg SignatureAlgorithm - assert func(t *testing.T, err error) + uc string + params httpsfv.InnerList + exp expectations + expAlg SignatureAlgorithm + assert func(t *testing.T, err error) }{ { uc: "signature algorithm mismatch", @@ -333,281 +332,6 @@ func TestExpectationsAssertParameters(t *testing.T) { } } -func TestWithComponentsForVerifier(t *testing.T) { - t.Parallel() - - for _, tc := range []struct { - uc string - identifiers []string - err error - }{ - {uc: "multiple valid identifier", identifiers: []string{"@status;req", "@method"}}, - {uc: "invalid identifier", identifiers: []string{"@foo"}, err: ErrUnsupportedComponentIdentifier}, - } { - t.Run(tc.uc, func(t *testing.T) { - v := &verifier{} - exp := &expectations{} - - err := WithComponents(tc.identifiers...).applyVerifierOption(v, exp, false) - - if tc.err != nil { - require.Error(t, err) - require.ErrorIs(t, err, tc.err) - } else { - require.NoError(t, err) - assert.Empty(t, v.tagExpectations) - require.Len(t, exp.identifiers, len(tc.identifiers)) - - for i, id := range exp.identifiers { - vals := strings.Split(tc.identifiers[i], ";") - assert.Equal(t, vals[0], id.Value) - } - } - }) - } -} - -func TestWithValidityTolerance(t *testing.T) { - t.Parallel() - - v := &verifier{} - exp := &expectations{} - - err := WithValidityTolerance(1*time.Minute).applyVerifierOption(v, exp, false) - require.NoError(t, err) - - assert.Empty(t, v.tagExpectations) - assert.Equal(t, 1*time.Minute, exp.tolerance) -} - -func TestWithRequiredTag(t *testing.T) { - t.Parallel() - - for _, tc := range []struct { - uc string - opts []VerifierOption - assert func(t *testing.T, err error, exp *expectations) - }{ - { - uc: "without options", - assert: func(t *testing.T, err error, exp *expectations) { - t.Helper() - - require.NoError(t, err) - require.NotNil(t, exp) - assert.Empty(t, exp.identifiers) - assert.Equal(t, time.Duration(-1), exp.tolerance) //nolint:testifylint - }, - }, - { - uc: "with identifiers only", - opts: []VerifierOption{ - WithComponents("@status"), - }, - assert: func(t *testing.T, err error, exp *expectations) { - t.Helper() - - require.NoError(t, err) - require.NotNil(t, exp) - assert.Len(t, exp.identifiers, 1) - assert.Equal(t, "@status", exp.identifiers[0].Value) - assert.Equal(t, time.Duration(-1), exp.tolerance) //nolint:testifylint - }, - }, - { - uc: "with tolerance only", - opts: []VerifierOption{ - WithValidityTolerance(5 * time.Minute), - }, - assert: func(t *testing.T, err error, exp *expectations) { - t.Helper() - - require.NoError(t, err) - require.NotNil(t, exp) - assert.Empty(t, exp.identifiers) - assert.Equal(t, 5*time.Minute, exp.tolerance) - }, - }, - { - uc: "with all possible options", - opts: []VerifierOption{ - WithComponents("@status"), - WithValidityTolerance(5 * time.Minute), - }, - assert: func(t *testing.T, err error, exp *expectations) { - t.Helper() - - require.NoError(t, err) - require.NotNil(t, exp) - assert.Len(t, exp.identifiers, 1) - assert.Equal(t, "@status", exp.identifiers[0].Value) - assert.Equal(t, 5*time.Minute, exp.tolerance) - }, - }, - { - uc: "with unsupported identifier", - opts: []VerifierOption{ - WithComponents("@foo"), - }, - assert: func(t *testing.T, err error, exp *expectations) { - t.Helper() - - require.Error(t, err) - require.ErrorIs(t, err, ErrUnsupportedComponentIdentifier) - require.Nil(t, exp) - }, - }, - { - uc: "with nested WithRequiredTag", - opts: []VerifierOption{ - WithRequiredTag("foo"), - }, - assert: func(t *testing.T, err error, _ *expectations) { - t.Helper() - - require.Error(t, err) - require.ErrorContains(t, err, "WithRequiredTag") - }, - }, - } { - t.Run(tc.uc, func(t *testing.T) { - v := &verifier{tagExpectations: make(map[string]*expectations)} - - recoverIfPanics := func(t *testing.T, f func() error) (err error) { - t.Helper() - - defer func() { - var ok bool - - if res := recover(); res != nil { - if err, ok = res.(error); !ok { - err = fmt.Errorf("%v", res) - } - } - }() - - err = f() - - return - } - - err := recoverIfPanics(t, func() error { - return WithRequiredTag("test", tc.opts...).applyVerifierOption(v, nil, false) - }) - if err == nil { - require.Len(t, v.tagExpectations, 1) - } - - tc.assert(t, err, v.tagExpectations["test"]) - }) - } - - t.Run("with duplicate WithRequiredTag", func(t *testing.T) { - v := &verifier{tagExpectations: map[string]*expectations{"foo": {}}} - - err := WithRequiredTag("foo", nil).applyVerifierOption(v, nil, false) - require.Error(t, err) - require.ErrorIs(t, err, ErrParameter) - require.ErrorContains(t, err, "already configured") - }) -} - -func TestWithMaxAge(t *testing.T) { - t.Parallel() - - v := &verifier{} - exp := &expectations{} - - err := WithMaxAge(15*time.Minute).applyVerifierOption(v, exp, false) - require.NoError(t, err) - - assert.Equal(t, 15*time.Minute, exp.maxAge) -} - -func TestWithSignatureNegotiation(t *testing.T) { - t.Parallel() - - for _, tc := range []struct { - uc string - opts []SignatureNegotiationOption - assert func(t *testing.T, err error, asb *AcceptSignatureBuilder) - }{ - { - uc: "without options", - assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) { - t.Helper() - - require.NoError(t, err) - - require.NotNil(t, asb) - assert.IsType(t, nonceGetter{}, asb.nonceGetter) - assert.Equal(t, "sig", asb.label) - assert.ElementsMatch(t, asb.cdAlgPrefs, []string{"sha-256=5", "sha-512=10"}) - assert.Empty(t, asb.signatureAlgorithm) - assert.Empty(t, asb.keyID) - // not set by any of the options - assert.True(t, asb.addCreatedTS) - assert.True(t, asb.addExpiresTS) - assert.False(t, asb.wantContentDigest) - assert.Empty(t, asb.tag) - assert.Empty(t, asb.identifiers) - }, - }, - { - uc: "with all possible options", - opts: []SignatureNegotiationOption{ - WithLabel("foo"), - WithRequestedNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), - WithSignatureAlgorithm(RsaPssSha512), - WithKeyID("bar"), - WithContentDigestAlgorithmPreferences(AlgorithmPreference{Sha512, 2}), - }, - assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) { - t.Helper() - - require.NoError(t, err) - - require.NotNil(t, asb) - require.NotNil(t, asb.nonceGetter) - nonce, err := asb.nonceGetter.GetNonce(context.TODO()) - require.NoError(t, err) - require.Equal(t, "abc", nonce) - assert.Equal(t, "foo", asb.label) - assert.ElementsMatch(t, asb.cdAlgPrefs, []string{"sha-512=2"}) - assert.Equal(t, RsaPssSha512, asb.signatureAlgorithm) - assert.Equal(t, "bar", asb.keyID) - // not set by any of the options - assert.True(t, asb.addCreatedTS) - assert.True(t, asb.addExpiresTS) - assert.False(t, asb.wantContentDigest) - assert.Empty(t, asb.tag) - assert.Empty(t, asb.identifiers) - }, - }, - { - uc: "with error while applying the option", - opts: []SignatureNegotiationOption{ - WithContentDigestAlgorithmPreferences(AlgorithmPreference{}), - }, - assert: func(t *testing.T, err error, _ *AcceptSignatureBuilder) { - t.Helper() - - require.Error(t, err) - require.ErrorIs(t, err, ErrParameter) - }, - }, - } { - t.Run(tc.uc, func(t *testing.T) { - v := &verifier{} - exp := &expectations{} - - err := WithSignatureNegotiation(tc.opts...).applyVerifierOption(v, exp, false) - - tc.assert(t, err, exp.asb) - }) - } -} - func TestNewVerifier(t *testing.T) { t.Parallel() @@ -775,7 +499,7 @@ func TestNewVerifier(t *testing.T) { assert.Equal(t, "content-digest", exp.identifiers[1].Value) assert.Equal(t, 1*time.Second, exp.tolerance) require.NotNil(t, exp.asb) - assert.IsType(t, nonceGetter{}, exp.asb.nonceGetter) + assert.Nil(t, exp.asb.nonceGetter) assert.Equal(t, "sig", exp.asb.label) assert.ElementsMatch(t, exp.asb.cdAlgPrefs, []string{"sha-256=5", "sha-512=10"}) assert.Equal(t, RsaPssSha512, exp.asb.signatureAlgorithm) @@ -998,7 +722,7 @@ func TestVerifierVerify(t *testing.T) { IsRequest: true, }, configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, - assert: func(t *testing.T, err error, results VerificationResult) { + assert: func(t *testing.T, err error, _ VerificationResult) { t.Helper() require.Error(t, err) @@ -1152,7 +876,7 @@ func TestVerifierVerify(t *testing.T) { WithSignatureAlgorithm(RsaPssSha512), WithKeyID("test-key"), WithLabel("bar"), - WithRequestedNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), + WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), WithContentDigestAlgorithmPreferences(AlgorithmPreference{Sha256, 1}), ), ), @@ -1176,6 +900,30 @@ func TestVerifierVerify(t *testing.T) { assert.ElementsMatch(t, hdr.Values("Want-Content-Digest"), []string{"sha-256=1"}) }, }, + { + uc: "signature negotiation without nonce getter omits nonce", + opts: []VerifierOption{ + WithRequiredTag("foo", + WithComponents("@method"), + WithSignatureNegotiation(WithLabel("foo-sig")), + ), + }, + msg: &Message{Header: http.Header{}}, + configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, + assert: func(t *testing.T, err error, _ VerificationResult) { + t.Helper() + + var targetErr *NoApplicableSignatureError + + require.ErrorIs(t, err, ErrVerificationFailed) + require.ErrorAs(t, err, &targetErr) + + hdr := make(http.Header) + targetErr.Negotiate(hdr) + + assert.Equal(t, `foo-sig=("@method");created;expires;tag="foo"`, hdr.Get(headerAcceptSignature)) + }, + }, { uc: "signature parameters negotiation for present signature with missing expires parameters", opts: []VerifierOption{ @@ -1184,7 +932,7 @@ func TestVerifierVerify(t *testing.T) { WithSignatureAlgorithm(RsaPssSha512), WithKeyID("test-key"), WithLabel("bar"), - WithRequestedNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), + WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), WithContentDigestAlgorithmPreferences(AlgorithmPreference{Sha256, 1}), ), ), @@ -1246,7 +994,7 @@ func TestVerifierVerify(t *testing.T) { WithSignatureNegotiation( WithSignatureAlgorithm(RsaPssSha512), WithKeyID("test-key"), - WithRequestedNonce(NonceGetterFunc(func(_ context.Context) (string, error) { return "", errors.New("test error") })), + WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { return "", errors.New("test error") })), ), ), }, @@ -1780,7 +1528,7 @@ func TestVerifierVerify(t *testing.T) { sig := results[0] assert.Equal(t, "valid", sig.Label) - assert.Len(t, sig.Components, 0) + assert.Empty(t, sig.Components) assert.Len(t, sig.Parameters, 3) assert.Equal(t, int64(1618884473), sig.Parameters["created"]) From 52aaf2b47eb4e37b959110195a5dc9587a068674 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Tue, 3 Nov 2026 09:56:53 +0100 Subject: [PATCH 14/33] memoization of url query parameters --- canonicalizer.go | 2 +- message.go | 16 ++++++++++++++++ 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/canonicalizer.go b/canonicalizer.go index b1ad905..7b92ef8 100644 --- a/canonicalizer.go +++ b/canonicalizer.go @@ -186,7 +186,7 @@ func canonicalizeQueryParam(msg *Message, params *httpsfv.Params) ([]string, err ErrCanonicalization, ErrInvalidComponentIdentifier) } - query := msg.URL.Query() + query := msg.queryParams() if !query.Has(name) { return nil, fmt.Errorf("%w: expected query parameter '%s' not found", ErrCanonicalization, name) } diff --git a/message.go b/message.go index 221705d..af841b2 100644 --- a/message.go +++ b/message.go @@ -7,6 +7,7 @@ import ( "io" "net/http" "net/url" + "sync" "github.com/dunglas/httpsfv" ) @@ -143,6 +144,9 @@ func MessageForResponse(req *http.Request, respHeader http.Header, body []byte, // and verify an HTTP message signature. For a response, request-related // fields supply data used by component identifiers with the ;req parameter. // Not every field is necessarily covered by the signature. +// Message data must remain stable after it is prepared for signing or +// verification, apart from headers added by signing. A Message must not be +// copied after its first use. type Message struct { // Context is passed to key resolution and Accept-Signature nonce generation. Context context.Context //nolint: containedctx @@ -174,6 +178,18 @@ type Message struct { // IsRequest distinguishes requests from responses for canonicalization. IsRequest bool + + queryOnce sync.Once + queryValues url.Values +} + +// queryParams parses the associated request query at most once per Message. +func (m *Message) queryParams() url.Values { + m.queryOnce.Do(func() { + m.queryValues = m.URL.Query() + }) + + return m.queryValues } func (m *Message) addSignature(label string, signature []byte, signatureInput httpsfv.InnerList) (http.Header, error) { From 8e270a019a799bd0cf4243185dd23297e29f8ae6 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Tue, 3 Nov 2026 09:57:40 +0100 Subject: [PATCH 15/33] precalculating components for signature base --- signature_base.go | 59 +++++++++++++----- signature_base_test.go | 133 ++++++++++++++++++++++++++++++++++------- signer.go | 33 ++++++---- verifier.go | 2 +- 4 files changed, 178 insertions(+), 49 deletions(-) diff --git a/signature_base.go b/signature_base.go index e444044..db60b2f 100644 --- a/signature_base.go +++ b/signature_base.go @@ -1,7 +1,6 @@ package httpsig import ( - "bytes" "fmt" "strings" @@ -20,7 +19,11 @@ type signatureBase struct { signatureParams string } -func newSignatureBase(si *signatureInput, msg *Message) (signatureBase, error) { +func newSignatureBase(msg *Message, si *signatureInput, prepared []string) (signatureBase, error) { + if prepared != nil && len(prepared) != len(si.identifiers) { + return signatureBase{}, fmt.Errorf("%w: mismatched serialized component identifiers", ErrMalformedData) + } + marshalledSigParams, err := httpsfv.Marshal(si.value) if err != nil { return signatureBase{}, err @@ -33,10 +36,15 @@ func newSignatureBase(si *signatureInput, msg *Message) (signatureBase, error) { } seen := make(map[string]struct{}, len(si.identifiers)) - for _, ci := range si.identifiers { - identifier, err := httpsfv.Marshal(ci.Item) - if err != nil { - return signatureBase{}, err + for i, ci := range si.identifiers { + var identifier string + if prepared == nil { + identifier, err = httpsfv.Marshal(ci.Item) + if err != nil { + return signatureBase{}, err + } + } else { + identifier = prepared[i] } if _, ok := seen[identifier]; ok { @@ -60,28 +68,49 @@ func newSignatureBase(si *signatureInput, msg *Message) (signatureBase, error) { } func (s signatureBase) marshal() []byte { - var buf bytes.Buffer + // calculate size + size := 0 + for i, item := range s.entries { + size += len(item.identifier) + len(": ") + len(item.value) + if i > 0 { + size++ + } + } + + if s.signatureParams != "" { + size += len(`"@signature-params": `) + len(s.signatureParams) + if len(s.entries) > 0 { + size++ + } + } + + if size == 0 { + return nil + } + + // do the actual marshalling + buf := make([]byte, 0, size) for i, item := range s.entries { if i > 0 { - buf.WriteByte('\n') + buf = append(buf, '\n') } - buf.WriteString(item.identifier) - buf.WriteString(": ") - buf.WriteString(item.value) + buf = append(buf, item.identifier...) + buf = append(buf, ':', ' ') + buf = append(buf, item.value...) } if s.signatureParams != "" { if len(s.entries) > 0 { - buf.WriteByte('\n') + buf = append(buf, '\n') } - buf.WriteString(`"@signature-params": `) - buf.WriteString(s.signatureParams) + buf = append(buf, `"@signature-params": `...) + buf = append(buf, s.signatureParams...) } - return buf.Bytes() + return buf } func (s signatureBase) components() map[string]string { diff --git a/signature_base_test.go b/signature_base_test.go index ffbc289..dfd1b19 100644 --- a/signature_base_test.go +++ b/signature_base_test.go @@ -39,13 +39,11 @@ func TestNewSignatureBase(t *testing.T) { created, err := time.Parse(time.RFC1123, "Tue, 20 Apr 2021 02:07:53 GMT") require.NoError(t, err) - for _, tc := range []struct { - uc string + for uc, tc := range map[string]struct { components []string assert func(t *testing.T, err error, base signatureBase) }{ - { - uc: "successful signature base creation", + "successful signature base creation": { components: []string{ "@method", "@authority", "@path", "content-digest", "content-length", "content-type", }, @@ -67,8 +65,7 @@ func TestNewSignatureBase(t *testing.T) { assert.Equal(t, expected, string(sigBase)) }, }, - { - uc: "failing for duplicate component identifier", + "failing for duplicate component identifier": { components: []string{ "@method", "@method", }, @@ -80,8 +77,7 @@ func TestNewSignatureBase(t *testing.T) { require.ErrorContains(t, err, "duplicate component identifier") }, }, - { - uc: "failing for duplicate parameterized component identifier", + "failing for duplicate parameterized component identifier": { components: []string{ `@query-param;name="Pet"`, `@query-param;name="Pet"`, @@ -94,8 +90,7 @@ func TestNewSignatureBase(t *testing.T) { require.ErrorContains(t, err, "duplicate component identifier") }, }, - { - uc: "failing for unknown component identifier", + "failing for unknown component identifier": { components: []string{"@status"}, assert: func(t *testing.T, err error, _ signatureBase) { t.Helper() @@ -105,8 +100,7 @@ func TestNewSignatureBase(t *testing.T) { require.ErrorContains(t, err, "@status") }, }, - { - uc: "allowing same component identifier with different parameters", + "allowing same component identifier with different parameters": { components: []string{ `@query-param;name="Pet"`, `@query-param;name="Cat"`, @@ -126,7 +120,7 @@ func TestNewSignatureBase(t *testing.T) { }, }, } { - t.Run(tc.uc, func(t *testing.T) { + t.Run(uc, func(t *testing.T) { identifiers, err := toComponentIdentifiers(tc.components) require.NoError(t, err) @@ -136,26 +130,121 @@ func TestNewSignatureBase(t *testing.T) { si := newSignatureInput(identifiers, params) - sigBase, err := newSignatureBase(si, msg) + sigBase, err := newSignatureBase(msg, si, nil) tc.assert(t, err, sigBase) }) } } -func TestSignatureBaseMarshal(t *testing.T) { +func TestNewSignatureBaseWithPreparedIdentifiers(t *testing.T) { t.Parallel() - base := signatureBase{ - entries: []serializedComponent{ - {identifier: `"@authority"`, value: "foo.bar"}, - {identifier: `"@method"`, value: "GET"}, - }, + for name, identifiers := range map[string][]string{ + "no covered components": {}, + "simple component": {"@method"}, + "several components": {"@method", "@authority", "x-example"}, + "parameterized components": {"@method", `@query-param;name="Pet"`, `@query-param;name="Cat"`}, + "duplicate component": {"@method", "@method"}, + "duplicate parameterized item": {`@query-param;name="Pet"`, `@query-param;name="Pet"`}, + } { + t.Run(name, func(t *testing.T) { + t.Parallel() + + sgnr, err := NewSigner( + Key{Algorithm: HmacSha256, Material: []byte("test-hmac-key")}, + WithComponents(identifiers...), + ) + require.NoError(t, err) + + s := sgnr.(*signer) + + require.Len(t, s.serializedIdentifiers, len(s.ids)) + + for i, id := range s.ids { + want, marshalErr := httpsfv.Marshal(id.Item) + require.NoError(t, marshalErr) + assert.Equal(t, want, s.serializedIdentifiers[i]) + } + + msg := &Message{ + Method: "GET", Authority: "example.com", + URL: &url.URL{Path: "/foo", RawQuery: "Pet=dog&Cat=meow"}, + Header: http.Header{"X-Example": []string{"value"}}, + IsRequest: true, + } + input := s.signatureInput(signOptions{}) + uncached, uncachedErr := newSignatureBase(msg, input, nil) + prepared, preparedErr := newSignatureBase(msg, input, s.serializedIdentifiers) + + if uncachedErr != nil { + require.ErrorIs(t, preparedErr, ErrMalformedData) + require.ErrorIs(t, uncachedErr, ErrMalformedData) + + return + } + + require.NoError(t, preparedErr) + assert.Equal(t, uncached.marshal(), prepared.marshal()) + assert.Equal(t, uncached.components(), prepared.components()) + }) } +} + +func TestNewSignatureBaseWithInvalidPreparedIdentifierCount(t *testing.T) { + t.Parallel() + + ids, err := toComponentIdentifiers([]string{"@method"}) + require.NoError(t, err) - res := base.marshal() + input := newSignatureInput(ids, httpsfv.NewParams()) + msg := &Message{Method: "GET", IsRequest: true} + + _, err = newSignatureBase(msg, input, []string{"one", "two"}) + + require.ErrorIs(t, err, ErrMalformedData) +} - assert.Equal(t, "\"@authority\": foo.bar\n\"@method\": GET", string(res)) +func TestSignatureBaseMarshal(t *testing.T) { + t.Parallel() + + for name, tc := range map[string]struct { + base signatureBase + want string + }{ + "empty": {}, + "signature parameters only": { + base: signatureBase{signatureParams: `("@method");created=123`}, + want: `"@signature-params": ("@method");created=123`, + }, + "single component without parameters": { + base: signatureBase{entries: []serializedComponent{{identifier: `"@method"`, value: "GET"}}}, + want: `"@method": GET`, + }, + "multiple components without parameters": { + base: signatureBase{entries: []serializedComponent{ + {identifier: `"@authority"`, value: "foo.bar"}, + {identifier: `"@method"`, value: "GET"}, + }}, + want: "\"@authority\": foo.bar\n\"@method\": GET", + }, + "empty and UTF-8 component values with parameters": { + base: signatureBase{ + entries: []serializedComponent{ + {identifier: `"x-empty"`, value: ""}, + {identifier: `"x-name"`, value: "Grüße"}, + }, + signatureParams: `("x-empty" "x-name");created=123`, + }, + want: "\"x-empty\": \n\"x-name\": Grüße\n\"@signature-params\": (\"x-empty\" \"x-name\");created=123", + }, + } { + t.Run(name, func(t *testing.T) { + t.Parallel() + + assert.Equal(t, tc.want, string(tc.base.marshal())) + }) + } } func TestSignatureBaseComponents(t *testing.T) { diff --git a/signer.go b/signer.go index f339b49..b2df9aa 100644 --- a/signer.go +++ b/signer.go @@ -89,20 +89,31 @@ func NewSigner(key Key, opts ...SignerOption) (Signer, error) { sig.mu = cmv } + // Covered components are fixed for the lifetime of this Signer. + // Prepare their Structured-Fields identifiers once for the signature base. + sig.serializedIdentifiers = make([]string, len(sig.ids)) + for i, id := range sig.ids { + sig.serializedIdentifiers[i], err = httpsfv.Marshal(id.Item) + if err != nil { + return nil, err + } + } + return sig, nil } type signer struct { - label string - ids []*componentIdentifier - ttl time.Duration - tag string - keyID string - includeAlg bool - ps payloadSigner - cdAlg DigestAlgorithm - parameters []parameterOption - mu messageUpdater + label string + ids []*componentIdentifier + serializedIdentifiers []string + ttl time.Duration + tag string + keyID string + includeAlg bool + ps payloadSigner + cdAlg DigestAlgorithm + parameters []parameterOption + mu messageUpdater } func (s *signer) Sign(msg *Message, opts ...SignOption) (http.Header, error) { @@ -119,7 +130,7 @@ func (s *signer) Sign(msg *Message, opts ...SignOption) (http.Header, error) { return nil, err } - base, err := newSignatureBase(params, msg) + base, err := newSignatureBase(msg, params, s.serializedIdentifiers) if err != nil { return nil, err } diff --git a/verifier.go b/verifier.go index 107cabb..bd5f165 100644 --- a/verifier.go +++ b/verifier.go @@ -366,7 +366,7 @@ func (v *verifier) verifySignature( si *signatureInput, exp *expectations, ) (VerifiedSignature, error) { - base, err := newSignatureBase(si, msg) + base, err := newSignatureBase(msg, si, nil) if err != nil { return VerifiedSignature{}, err } From bd64af5477a610465ad32e33e6e6cb1ae8154a78 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Tue, 3 Nov 2026 10:06:50 +0100 Subject: [PATCH 16/33] using known params length while creating the corresponding map --- signature_input.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/signature_input.go b/signature_input.go index 45dd177..dff609f 100644 --- a/signature_input.go +++ b/signature_input.go @@ -47,7 +47,7 @@ func (si *signatureInput) hasIdentifier(id *componentIdentifier) bool { } func (si *signatureInput) parameters() SignatureParameters { - result := make(SignatureParameters) + result := make(SignatureParameters, len(si.value.Params.Names())) if si.value.Params == nil { return result From b0c9d2eb69abac7c76726b758f9af438cfc178fd Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Tue, 3 Nov 2026 10:58:06 +0100 Subject: [PATCH 17/33] linter warnings resolved --- options.go | 1 + signer.go | 2 ++ 2 files changed, 3 insertions(+) diff --git a/options.go b/options.go index 94a3bd5..f545e2b 100644 --- a/options.go +++ b/options.go @@ -496,6 +496,7 @@ func (o contentDigestAlgorithmPreferencesOption) applySignatureNegotiationOption opts.opts = append(opts.opts, o) } +//nolint:cyclop func addParameter( parameters *[]parameterOption, existing []parameterOption, diff --git a/signer.go b/signer.go index b2df9aa..cb4e444 100644 --- a/signer.go +++ b/signer.go @@ -47,6 +47,8 @@ type Signer interface { // after 30 seconds. The alg, keyid, tag, and nonce parameters are omitted. // When generating Content-Digest, the signer uses both SHA-256 and SHA-512 // unless WithContentDigestAlgorithm selects one. +// +//nolint:cyclop func NewSigner(key Key, opts ...SignerOption) (Signer, error) { ps, err := newPayloadSigner(key.Material, key.Algorithm) if err != nil { From 0e436f649b3d611b32789ce26eb932e30d24352a Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Tue, 3 Nov 2026 15:22:51 +0100 Subject: [PATCH 18/33] asserting metadataoptions independent from key algorithm and more options for accept signature builder --- accept_signature_builder.go | 18 +- accept_signature_builder_test.go | 106 ++++++++- options.go | 53 +++-- options_test.go | 116 +++++++++- verifier.go | 28 ++- verifier_test.go | 362 +++++++++++++++++++------------ 6 files changed, 501 insertions(+), 182 deletions(-) diff --git a/accept_signature_builder.go b/accept_signature_builder.go index f6453a9..b17706c 100644 --- a/accept_signature_builder.go +++ b/accept_signature_builder.go @@ -31,6 +31,7 @@ type AcceptSignatureBuilder struct { nonceGetter NonceGetter label string identifiers []*componentIdentifier + parameters []parameterOption cdAlgPrefs []string tag string addCreatedTS bool @@ -64,18 +65,19 @@ func NewAcceptSignature(opts ...AcceptSignatureOption) (*AcceptSignatureBuilder, // Build appends an Accept-Signature header to header using the configured // signature requirements. If Content-Digest is requested, it also appends -// Want-Content-Digest preferences. A non-empty nonce may be provided for this +// Want-Content-Digest preferences. Additional extension parameters can be +// supplied with WithParameter. A non-empty nonce may be provided for this // call with WithParameter("nonce", value), overriding a configured // WithNonceGetter without invoking it. Otherwise, the configured getter is // used if present; if neither is provided, no nonce is requested. Options -// do not modify this reusable builder. The caller must provide a writable, -// non-nil http.Header. +// do not modify the builder. The caller must provide a writable, non-nil +// http.Header. func (asb *AcceptSignatureBuilder) Build( ctx context.Context, header http.Header, opts ...AcceptSignatureBuildOption, ) error { - callOptions := acceptSignatureBuildOptions{} + callOptions := acceptSignatureBuildOptions{staticParameters: asb.parameters} for _, opt := range opts { if err := opt.applyAcceptSignatureBuildOption(&callOptions); err != nil { return err @@ -101,6 +103,14 @@ func (asb *AcceptSignatureBuilder) Build( asb.signatureAlgorithm, asb.identifiers) + for _, param := range asb.parameters { + sigReqs.Params.Add(param.name, param.value) + } + + for _, param := range callOptions.parameters { + sigReqs.Params.Add(param.name, param.value) + } + dict := httpsfv.NewDictionary() dict.Add(asb.label, sigReqs.InnerList) diff --git a/accept_signature_builder_test.go b/accept_signature_builder_test.go index cfe96a2..5527bd3 100644 --- a/accept_signature_builder_test.go +++ b/accept_signature_builder_test.go @@ -32,6 +32,7 @@ func TestNewAcceptedSignature(t *testing.T) { assert.True(t, asb.addCreatedTS) assert.True(t, asb.addExpiresTS) assert.Nil(t, asb.nonceGetter) + assert.Empty(t, asb.parameters) assert.Equal(t, "sig", asb.label) assert.ElementsMatch(t, asb.cdAlgPrefs, []string{ AlgorithmPreference{Algorithm: Sha256, Preference: 5}.String(), @@ -51,6 +52,7 @@ func TestNewAcceptedSignature(t *testing.T) { WithTag("bar"), WithCreatedTimestamp(false), WithExpiredTimestamp(false), + WithParameter("audience", "service-a"), }, assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) { t.Helper() @@ -67,11 +69,24 @@ func TestNewAcceptedSignature(t *testing.T) { assert.False(t, asb.addExpiresTS) assert.Equal(t, &NonceGetterMock{}, asb.nonceGetter) assert.Equal(t, "foo", asb.label) + assert.Equal(t, []parameterOption{{name: "audience", value: "service-a"}}, asb.parameters) assert.ElementsMatch(t, asb.cdAlgPrefs, []string{ AlgorithmPreference{Algorithm: Sha512, Preference: 10}.String(), }) }, }, + { + uc: "invalid extension parameter", + opts: []AcceptSignatureOption{ + WithParameter("keyid", "reserved"), + }, + assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) { + t.Helper() + + require.ErrorIs(t, err, ErrParameter) + assert.Nil(t, asb) + }, + }, { uc: "option raises error", opts: []AcceptSignatureOption{ @@ -185,8 +200,65 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { }, }, { - uc: "unsupported parameter in Build", + uc: "additional extension at Build", buildOpts: []AcceptSignatureBuildOption{WithParameter("other", "value")}, + assert: func(t *testing.T, err error, hdr http.Header) { + t.Helper() + require.NoError(t, err) + assert.Equal(t, `sig=();created;expires;other="value"`, hdr.Get(headerAcceptSignature)) + }, + }, + { + uc: "static and dynamic extensions", + opts: []AcceptSignatureOption{ + WithParameter("audience", "service-a"), + WithParameter("flag", true), + }, + buildOpts: []AcceptSignatureBuildOption{WithParameter("challenge", Token("example"))}, + assert: func(t *testing.T, err error, hdr http.Header) { + t.Helper() + require.NoError(t, err) + assert.Equal(t, `sig=();created;expires;audience="service-a";flag;challenge=example`, hdr.Get(headerAcceptSignature)) + }, + }, + { + uc: "extension types", + opts: []AcceptSignatureOption{ + WithParameter("integer", 42), + WithParameter("decimal", 1.5), + WithParameter("bytes", []byte("hello")), + }, + assert: func(t *testing.T, err error, hdr http.Header) { + t.Helper() + require.NoError(t, err) + assert.Equal(t, `sig=();created;expires;integer=42;decimal=1.5;bytes=:aGVsbG8=:`, hdr.Get(headerAcceptSignature)) + }, + }, + { + uc: "conflicting static and dynamic extension", + opts: []AcceptSignatureOption{WithParameter("audience", "static")}, + buildOpts: []AcceptSignatureBuildOption{WithParameter("audience", "dynamic")}, + assert: func(t *testing.T, err error, hdr http.Header) { + t.Helper() + require.ErrorIs(t, err, ErrParameter) + assert.Empty(t, hdr) + }, + }, + { + uc: "duplicate extension at Build", + buildOpts: []AcceptSignatureBuildOption{ + WithParameter("audience", "first"), + WithParameter("audience", "second"), + }, + assert: func(t *testing.T, err error, hdr http.Header) { + t.Helper() + require.ErrorIs(t, err, ErrParameter) + assert.Empty(t, hdr) + }, + }, + { + uc: "invalid extension at Build", + buildOpts: []AcceptSignatureBuildOption{WithParameter("other", "bad\nvalue")}, assert: func(t *testing.T, err error, hdr http.Header) { t.Helper() require.ErrorIs(t, err, ErrParameter) @@ -312,4 +384,36 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { assert.Equal(t, `sig=();created;expires;nonce="generated"`, second.Get(headerAcceptSignature)) assert.Equal(t, 1, calls) }) + + t.Run("per-call extension is not retained", func(t *testing.T) { + builder, err := NewAcceptSignature(WithParameter("audience", "service-a")) + require.NoError(t, err) + + first := make(http.Header) + err = builder.Build(context.TODO(), first, WithParameter("challenge", "first")) + require.NoError(t, err) + assert.Equal(t, `sig=();created;expires;audience="service-a";challenge="first"`, first.Get(headerAcceptSignature)) + + second := make(http.Header) + err = builder.Build(context.TODO(), second, WithParameter("challenge", "second")) + require.NoError(t, err) + assert.Equal(t, `sig=();created;expires;audience="service-a";challenge="second"`, second.Get(headerAcceptSignature)) + + third := make(http.Header) + err = builder.Build(context.TODO(), third) + require.NoError(t, err) + assert.Equal(t, `sig=();created;expires;audience="service-a"`, third.Get(headerAcceptSignature)) + }) + + t.Run("static byte sequence is not affected by caller mutation", func(t *testing.T) { + value := []byte("before") + builder, err := NewAcceptSignature(WithParameter("bytes", value)) + require.NoError(t, err) + + value[0] = 'X' + hdr := make(http.Header) + err = builder.Build(context.TODO(), hdr) + require.NoError(t, err) + assert.Equal(t, `sig=();created;expires;bytes=:YmVmb3Jl:`, hdr.Get(headerAcceptSignature)) + }) } diff --git a/options.go b/options.go index f545e2b..9c2ac91 100644 --- a/options.go +++ b/options.go @@ -17,8 +17,10 @@ type signOptions struct { } type acceptSignatureBuildOptions struct { - nonce string - nonceSet bool + nonce string + nonceSet bool + staticParameters []parameterOption + parameters []parameterOption } type sigNegotiationOptions struct { @@ -224,12 +226,13 @@ func WithAlg() SignerOption { }) } -// WithParameter specifies a signature parameter for NewSigner or an individual -// Sign call. It also allows AcceptSignatureBuilder.Build to request a nonce. -// Extension values may be string, Token, bool, int, int64, float64, or []byte. -// Standard RFC 9421 parameter names are reserved, except for a non-empty -// string nonce on Sign or Build. Build accepts no other parameter names. -// Duplicate names are rejected. +// WithParameter specifies an extension parameter for signing or requesting a +// signature, either in the reusable configuration or for a single call. +// It can also be used in WithSignatureNegotiation. Extension values may be +// string, Token, bool, int, int64, float64, or []byte. Standard RFC 9421 +// parameter names are reserved, except for a non-empty string nonce on Sign +// or AcceptSignatureBuilder.Build. Duplicate names are rejected, including +// duplicates between builder configuration and Build options. func WithParameter(name string, value any) parameterOption { return parameterOption{name: name, value: value} } @@ -263,24 +266,32 @@ func (o parameterOption) applySignOption(opts *signOptions) error { return addParameter(&opts.parameters, opts.staticParameters, o, false) } +func (o parameterOption) applyAcceptSignatureOption(asb *AcceptSignatureBuilder) error { + return addParameter(&asb.parameters, nil, o, true) +} + +func (o parameterOption) applySignatureNegotiationOption(opts *sigNegotiationOptions) { + opts.opts = append(opts.opts, o) +} + func (o parameterOption) applyAcceptSignatureBuildOption(opts *acceptSignatureBuildOptions) error { - if o.name != string(Nonce) { - return fmt.Errorf("%w: unsupported Accept-Signature parameter %q", ErrParameter, o.name) - } + if o.name == string(Nonce) { + if opts.nonceSet { + return fmt.Errorf("%w: duplicate signature parameter %q", ErrParameter, o.name) + } - if opts.nonceSet { - return fmt.Errorf("%w: duplicate signature parameter %q", ErrParameter, o.name) - } + nonce, err := validateNonceOption(o.value) + if err != nil { + return err + } - nonce, err := validateNonceOption(o.value) - if err != nil { - return err - } + opts.nonce = nonce + opts.nonceSet = true - opts.nonce = nonce - opts.nonceSet = true + return nil + } - return nil + return addParameter(&opts.parameters, opts.staticParameters, o, false) } func validateNonceOption(value any) (string, error) { diff --git a/options_test.go b/options_test.go index a6da399..21b29b5 100644 --- a/options_test.go +++ b/options_test.go @@ -475,19 +475,87 @@ func TestWithParameterForSign(t *testing.T) { }) } +func TestWithParameterForAcceptSignature(t *testing.T) { + t.Parallel() + + for uc, tc := range map[string]struct { + value any + want any + }{ + "string": {value: "value", want: "value"}, + "token": {value: Token("value"), want: httpsfv.Token("value")}, + "integer": {value: 42, want: int64(42)}, + "decimal": {value: 1.5, want: 1.5}, + "boolean": {value: true, want: true}, + "byte sequence": {value: []byte("value"), want: []byte("value")}, + } { + t.Run(uc, func(t *testing.T) { + asb := &AcceptSignatureBuilder{} + + err := WithParameter("example", tc.value).applyAcceptSignatureOption(asb) + + require.NoError(t, err) + require.Len(t, asb.parameters, 1) + assert.Equal(t, "example", asb.parameters[0].name) + assert.Equal(t, tc.want, asb.parameters[0].value) + }) + } + + t.Run("static byte sequence is copied", func(t *testing.T) { + value := []byte("before") + asb := &AcceptSignatureBuilder{} + + err := WithParameter("example", value).applyAcceptSignatureOption(asb) + require.NoError(t, err) + + value[0] = 'X' + assert.Equal(t, []byte("before"), asb.parameters[0].value) + }) + + for uc, param := range map[string]parameterOption{ + "reserved parameter": WithParameter("created", int64(1)), + "static nonce": WithParameter("nonce", "fixed"), + "invalid name": WithParameter("invalid name", "value"), + "invalid string": WithParameter("example", "bad\nvalue"), + "unsupported type": WithParameter("example", struct{}{}), + } { + t.Run(uc, func(t *testing.T) { + asb := &AcceptSignatureBuilder{} + + err := param.applyAcceptSignatureOption(asb) + + require.ErrorIs(t, err, ErrParameter) + assert.Empty(t, asb.parameters) + }) + } + + t.Run("duplicate parameter", func(t *testing.T) { + asb := &AcceptSignatureBuilder{} + require.NoError(t, WithParameter("example", "first").applyAcceptSignatureOption(asb)) + + err := WithParameter("example", "second").applyAcceptSignatureOption(asb) + + require.ErrorIs(t, err, ErrParameter) + require.Len(t, asb.parameters, 1) + assert.Equal(t, "first", asb.parameters[0].value) + }) +} + func TestWithParameterForAcceptSignatureBuild(t *testing.T) { t.Parallel() for uc, tc := range map[string]struct { param parameterOption - want string + want any wantErr bool }{ "nonce": {param: WithParameter("nonce", "request-nonce"), want: "request-nonce"}, - "other parameter": {param: WithParameter("extension", "value"), wantErr: true}, + "extension": {param: WithParameter("extension", Token("value")), want: httpsfv.Token("value")}, "empty nonce": {param: WithParameter("nonce", ""), wantErr: true}, "nonce with incorrect type": {param: WithParameter("nonce", Token("value")), wantErr: true}, "invalid nonce string": {param: WithParameter("nonce", "bad\nvalue"), wantErr: true}, + "reserved parameter": {param: WithParameter("created", true), wantErr: true}, + "invalid extension": {param: WithParameter("extension", "bad\nvalue"), wantErr: true}, } { t.Run(uc, func(t *testing.T) { opts := &acceptSignatureBuildOptions{} @@ -497,13 +565,20 @@ func TestWithParameterForAcceptSignatureBuild(t *testing.T) { if tc.wantErr { require.ErrorIs(t, err, ErrParameter) assert.False(t, opts.nonceSet) + assert.Empty(t, opts.parameters) return } require.NoError(t, err) - assert.True(t, opts.nonceSet) - assert.Equal(t, tc.want, opts.nonce) + + if tc.param.name == "nonce" { + assert.True(t, opts.nonceSet) + assert.Equal(t, tc.want, opts.nonce) + } else { + require.Len(t, opts.parameters, 1) + assert.Equal(t, tc.want, opts.parameters[0].value) + } }) } @@ -516,6 +591,28 @@ func TestWithParameterForAcceptSignatureBuild(t *testing.T) { require.ErrorIs(t, err, ErrParameter) assert.Equal(t, "first", opts.nonce) }) + + t.Run("duplicate extension", func(t *testing.T) { + opts := &acceptSignatureBuildOptions{} + require.NoError(t, WithParameter("extension", "first").applyAcceptSignatureBuildOption(opts)) + + err := WithParameter("extension", "second").applyAcceptSignatureBuildOption(opts) + + require.ErrorIs(t, err, ErrParameter) + require.Len(t, opts.parameters, 1) + assert.Equal(t, "first", opts.parameters[0].value) + }) + + t.Run("extension conflicts with static parameter", func(t *testing.T) { + opts := &acceptSignatureBuildOptions{ + staticParameters: []parameterOption{{name: "extension", value: "static"}}, + } + + err := WithParameter("extension", "per-call").applyAcceptSignatureBuildOption(opts) + + require.ErrorIs(t, err, ErrParameter) + assert.Empty(t, opts.parameters) + }) } func TestWithValidityTolerance(t *testing.T) { @@ -795,6 +892,7 @@ func TestWithSignatureNegotiation(t *testing.T) { WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { return "abc", nil })), WithSignatureAlgorithm(RsaPssSha512), WithKeyID("bar"), + WithParameter("audience", "service-a"), WithContentDigestAlgorithmPreferences(AlgorithmPreference{Sha512, 2}), }, assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) { @@ -811,6 +909,8 @@ func TestWithSignatureNegotiation(t *testing.T) { assert.ElementsMatch(t, asb.cdAlgPrefs, []string{"sha-512=2"}) assert.Equal(t, RsaPssSha512, asb.signatureAlgorithm) assert.Equal(t, "bar", asb.keyID) + require.Len(t, asb.parameters, 1) + assert.Equal(t, parameterOption{name: "audience", value: "service-a"}, asb.parameters[0]) // not set by any of the options assert.True(t, asb.addCreatedTS) assert.True(t, asb.addExpiresTS) @@ -819,6 +919,14 @@ func TestWithSignatureNegotiation(t *testing.T) { assert.Empty(t, asb.identifiers) }, }, + "with invalid custom parameter": { + opts: []SignatureNegotiationOption{WithParameter("created", true)}, + assert: func(t *testing.T, err error, _ *AcceptSignatureBuilder) { + t.Helper() + + require.ErrorIs(t, err, ErrParameter) + }, + }, "with error while applying the option": { opts: []SignatureNegotiationOption{ WithContentDigestAlgorithmPreferences(AlgorithmPreference{}), diff --git a/verifier.go b/verifier.go index bd5f165..b9e83f8 100644 --- a/verifier.go +++ b/verifier.go @@ -162,23 +162,13 @@ type expectations struct { } // nolint: funlen, cyclop -func (e *expectations) assert( - si *signatureInput, - msg *Message, - keyAlg SignatureAlgorithm, -) error { +func (e *expectations) assertMetadata(si *signatureInput, msg *Message) error { var ( missingComponents []string cmv compositeMessageVerifier mv messageVerifier ) - algorithm, algPresent := si.algorithm() - if algPresent && algorithm != keyAlg { - return fmt.Errorf("%w: key algorithm %s does not match signature algorithm %s", - ErrParameter, algorithm, keyAlg) - } - now := currentTime().UTC() expires, expiresPresent := si.expires() @@ -234,6 +224,16 @@ func (e *expectations) assert( return mv.verify(msg) } +func (e *expectations) assertKeyAlgorithm(si *signatureInput, keyAlg SignatureAlgorithm) error { + algorithm, algPresent := si.algorithm() + if algPresent && algorithm != keyAlg { + return fmt.Errorf("%w: key algorithm %s does not match signature algorithm %s", + ErrParameter, algorithm, keyAlg) + } + + return nil +} + type verifier struct { keyResolver KeyResolver tagExpectations map[string]*expectations @@ -366,6 +366,10 @@ func (v *verifier) verifySignature( si *signatureInput, exp *expectations, ) (VerifiedSignature, error) { + if err := exp.assertMetadata(si, msg); err != nil { + return VerifiedSignature{}, err + } + base, err := newSignatureBase(msg, si, nil) if err != nil { return VerifiedSignature{}, err @@ -384,7 +388,7 @@ func (v *verifier) verifySignature( return VerifiedSignature{}, err } - if err = exp.assert(si, msg, keyInfo.Key.Algorithm); err != nil { + if err = exp.assertKeyAlgorithm(si, keyInfo.Key.Algorithm); err != nil { return VerifiedSignature{}, err } diff --git a/verifier_test.go b/verifier_test.go index 635efeb..5ee7444 100644 --- a/verifier_test.go +++ b/verifier_test.go @@ -42,20 +42,19 @@ func TestNewPayloadVerifier(t *testing.T) { require.NoError(t, err) require.Equal(t, len(k256), n) - for _, tc := range []struct { - uc string + for uc, tc := range map[string]struct { key any alg SignatureAlgorithm typ any err error }{ - {uc: "unsupported algorithm", key: "foo", err: ErrUnsupportedKeyType}, - {uc: "ed25519 verifier", key: ek25519, alg: Ed25519, typ: &ed25519Verifier{}}, - {uc: "rsa verifier", key: &pk2048.PublicKey, alg: RsaPssSha256, typ: &rsaVerifier{}}, - {uc: "ecdsa verifier", key: &pkp256.PublicKey, alg: EcdsaP256Sha256, typ: &ecdsaVerifier{}}, - {uc: "hmac verifier", key: k256, alg: HmacSha256, typ: &symmetricSigner{}}, + "unsupported algorithm": {key: "foo", err: ErrUnsupportedKeyType}, + "ed25519 verifier": {key: ek25519, alg: Ed25519, typ: &ed25519Verifier{}}, + "rsa verifier": {key: &pk2048.PublicKey, alg: RsaPssSha256, typ: &rsaVerifier{}}, + "ecdsa verifier": {key: &pkp256.PublicKey, alg: EcdsaP256Sha256, typ: &ecdsaVerifier{}}, + "hmac verifier": {key: k256, alg: HmacSha256, typ: &symmetricSigner{}}, } { - t.Run(tc.uc, func(t *testing.T) { + t.Run(uc, func(t *testing.T) { sig, err := newPayloadVerifier(tc.key, tc.alg) if tc.err != nil { @@ -70,39 +69,17 @@ func TestNewPayloadVerifier(t *testing.T) { } } -func TestExpectationsAssertParameters(t *testing.T) { +func TestExpectationsAssertMetadata(t *testing.T) { now := time.Now().UTC() falseVal := false trueVal := true - for _, tc := range []struct { - uc string + for uc, tc := range map[string]struct { params httpsfv.InnerList exp expectations - expAlg SignatureAlgorithm assert func(t *testing.T, err error) }{ - { - uc: "signature algorithm mismatch", - params: httpsfv.InnerList{ - Params: func() *httpsfv.Params { - params := httpsfv.NewParams() - params.Add(string(Alg), string(RsaPssSha512)) - - return params - }(), - }, - expAlg: EcdsaP256Sha256, - assert: func(t *testing.T, err error) { - t.Helper() - - require.Error(t, err) - require.ErrorIs(t, err, ErrParameter) - require.ErrorContains(t, err, "key algorithm rsa-pss-sha512 does not match signature algorithm ecdsa-p256-sha256") - }, - }, - { - uc: "signature expired, no tolerance specified", + "signature expired, no tolerance specified": { params: httpsfv.InnerList{ Params: func() *httpsfv.Params { params := httpsfv.NewParams() @@ -120,8 +97,7 @@ func TestExpectationsAssertParameters(t *testing.T) { require.ErrorContains(t, err, "expired") }, }, - { - uc: "signature is still valid with specified tolerance", + "signature is still valid with specified tolerance": { params: httpsfv.InnerList{ Params: func() *httpsfv.Params { params := httpsfv.NewParams() @@ -141,8 +117,7 @@ func TestExpectationsAssertParameters(t *testing.T) { require.NoError(t, err) }, }, - { - uc: "signature is valid if expires in the future", + "signature is valid if expires in the future": { params: httpsfv.InnerList{ Params: func() *httpsfv.Params { params := httpsfv.NewParams() @@ -162,8 +137,7 @@ func TestExpectationsAssertParameters(t *testing.T) { require.NoError(t, err) }, }, - { - uc: "signature not yet valid, no tolerance specified", + "signature not yet valid, no tolerance specified": { params: httpsfv.InnerList{ Params: func() *httpsfv.Params { params := httpsfv.NewParams() @@ -181,8 +155,7 @@ func TestExpectationsAssertParameters(t *testing.T) { require.ErrorContains(t, err, "not yet valid") }, }, - { - uc: "signature already valid with specified tolerance", + "signature already valid with specified tolerance": { params: httpsfv.InnerList{ Params: func() *httpsfv.Params { params := httpsfv.NewParams() @@ -202,8 +175,7 @@ func TestExpectationsAssertParameters(t *testing.T) { require.NoError(t, err) }, }, - { - uc: "signature is valid if created in the past", + "signature is valid if created in the past": { params: httpsfv.InnerList{ Params: func() *httpsfv.Params { params := httpsfv.NewParams() @@ -223,8 +195,7 @@ func TestExpectationsAssertParameters(t *testing.T) { require.NoError(t, err) }, }, - { - uc: "signature too old", + "signature too old": { params: httpsfv.InnerList{ Params: func() *httpsfv.Params { params := httpsfv.NewParams() @@ -242,8 +213,7 @@ func TestExpectationsAssertParameters(t *testing.T) { require.ErrorContains(t, err, "too old") }, }, - { - uc: "expected component identifier missing", + "expected component identifier missing": { params: httpsfv.InnerList{Params: httpsfv.NewParams()}, exp: func() expectations { ids, err := toComponentIdentifiers([]string{"@method;req", "@authority"}) @@ -259,8 +229,7 @@ func TestExpectationsAssertParameters(t *testing.T) { require.ErrorContains(t, err, `"@method";req, "@authority"`) }, }, - { - uc: "expected created parameter is missing", + "expected created parameter is missing": { params: httpsfv.InnerList{Params: httpsfv.NewParams()}, exp: expectations{reqCreatedTS: &trueVal, reqExpiresTS: &falseVal}, assert: func(t *testing.T, err error) { @@ -271,8 +240,7 @@ func TestExpectationsAssertParameters(t *testing.T) { require.ErrorContains(t, err, `created parameter`) }, }, - { - uc: "expected expires parameter is missing", + "expected expires parameter is missing": { params: httpsfv.InnerList{Params: httpsfv.NewParams()}, exp: expectations{reqCreatedTS: &falseVal, reqExpiresTS: &trueVal}, assert: func(t *testing.T, err error) { @@ -283,8 +251,7 @@ func TestExpectationsAssertParameters(t *testing.T) { require.ErrorContains(t, err, `expires parameter`) }, }, - { - uc: "successful assertion with all possible parameters", + "successful assertion with all possible parameters": { params: httpsfv.InnerList{ Params: func() *httpsfv.Params { params := httpsfv.NewParams() @@ -311,7 +278,6 @@ func TestExpectationsAssertParameters(t *testing.T) { maxAge: 5 * time.Second, } }(), - expAlg: EcdsaP256Sha256, assert: func(t *testing.T, err error) { t.Helper() @@ -319,13 +285,64 @@ func TestExpectationsAssertParameters(t *testing.T) { }, }, } { - t.Run(tc.uc, func(t *testing.T) { + t.Run(uc, func(t *testing.T) { msg := &Message{Context: context.TODO()} si, err := parseSignatureInput(tc.params) require.NoError(t, err) - err = tc.exp.assert(si, msg, tc.expAlg) + err = tc.exp.assertMetadata(si, msg) + + tc.assert(t, err) + }) + } +} + +func TestExpectationsAssertKeyAlgorithm(t *testing.T) { + for uc, tc := range map[string]struct { + parameterAlg SignatureAlgorithm + keyAlg SignatureAlgorithm + assert func(t *testing.T, err error) + }{ + "signature algorithm mismatch": { + parameterAlg: RsaPssSha512, + keyAlg: EcdsaP256Sha256, + assert: func(t *testing.T, err error) { + t.Helper() + + require.ErrorIs(t, err, ErrParameter) + require.ErrorContains(t, err, "key algorithm rsa-pss-sha512 does not match signature algorithm ecdsa-p256-sha256") + }, + }, + "signature algorithm matches": { + parameterAlg: RsaPssSha512, + keyAlg: RsaPssSha512, + assert: func(t *testing.T, err error) { + t.Helper() + + require.NoError(t, err) + }, + }, + "signature algorithm absent": { + keyAlg: EcdsaP256Sha256, + assert: func(t *testing.T, err error) { + t.Helper() + + require.NoError(t, err) + }, + }, + } { + t.Run(uc, func(t *testing.T) { + params := httpsfv.NewParams() + if tc.parameterAlg != "" { + params.Add(string(Alg), string(tc.parameterAlg)) + } + + si, err := parseSignatureInput(httpsfv.InnerList{Params: params}) + require.NoError(t, err) + + exp := &expectations{} + err = exp.assertKeyAlgorithm(si, tc.keyAlg) tc.assert(t, err) }) @@ -335,14 +352,12 @@ func TestExpectationsAssertParameters(t *testing.T) { func TestNewVerifier(t *testing.T) { t.Parallel() - for _, tc := range []struct { - uc string + for uc, tc := range map[string]struct { resolver KeyResolver opts []VerifierOption assert func(t *testing.T, err error, v *verifier) }{ - { - uc: "without key resolver", + "without key resolver": { assert: func(t *testing.T, err error, _ *verifier) { t.Helper() @@ -351,8 +366,7 @@ func TestNewVerifier(t *testing.T) { require.ErrorContains(t, err, "no key resolver") }, }, - { - uc: "with key resolver only", + "with key resolver only": { resolver: &KeyResolverMock{}, assert: func(t *testing.T, err error, _ *verifier) { t.Helper() @@ -362,8 +376,7 @@ func TestNewVerifier(t *testing.T) { require.ErrorContains(t, err, "validation of all signatures disabled, but no signature tags specified") }, }, - { - uc: "with component identifiers configuration error", + "with component identifiers configuration error": { resolver: &KeyResolverMock{}, opts: []VerifierOption{ WithComponents("@foo"), @@ -376,8 +389,7 @@ func TestNewVerifier(t *testing.T) { require.ErrorContains(t, err, "unsupported component identifier: @foo") }, }, - { - uc: "with empty required tag", + "with empty required tag": { resolver: &KeyResolverMock{}, opts: []VerifierOption{ WithRequiredTag(""), @@ -390,8 +402,7 @@ func TestNewVerifier(t *testing.T) { require.ErrorContains(t, err, "required tag must not be empty") }, }, - { - uc: "cannot verify and negotiate any possible signature", + "cannot verify and negotiate any possible signature": { resolver: &KeyResolverMock{}, opts: []VerifierOption{ WithValidateAllSignatures(), @@ -405,8 +416,7 @@ func TestNewVerifier(t *testing.T) { require.ErrorContains(t, err, "verification and negotiation") }, }, - { - uc: "with verification of all signatures enabled", + "with verification of all signatures enabled": { resolver: &KeyResolverMock{}, opts: []VerifierOption{ WithValidateAllSignatures(), @@ -421,8 +431,7 @@ func TestNewVerifier(t *testing.T) { assert.IsType(t, &KeyResolverMock{}, v.keyResolver) }, }, - { - uc: "with tag specific options only", + "with tag specific options only": { resolver: &KeyResolverMock{}, opts: []VerifierOption{ WithRequiredTag("test", @@ -446,8 +455,7 @@ func TestNewVerifier(t *testing.T) { assert.Equal(t, 1*time.Second, exp.tolerance) }, }, - { - uc: "with global defaults without signature negotiation", + "with global defaults without signature negotiation": { resolver: &KeyResolverMock{}, opts: []VerifierOption{ WithRequiredTag("test"), @@ -471,8 +479,7 @@ func TestNewVerifier(t *testing.T) { assert.Nil(t, exp.asb) }, }, - { - uc: "with global defaults with signature negotiation", + "with global defaults with signature negotiation": { resolver: &KeyResolverMock{}, opts: []VerifierOption{ WithRequiredTag("test"), @@ -511,8 +518,7 @@ func TestNewVerifier(t *testing.T) { assert.Equal(t, exp.identifiers, exp.asb.identifiers) }, }, - { - uc: "with all possible options", + "with all possible options": { resolver: &KeyResolverMock{}, opts: []VerifierOption{ WithRequiredTag("test", @@ -544,8 +550,25 @@ func TestNewVerifier(t *testing.T) { assert.Equal(t, 1*time.Second, exp.tolerance) }, }, + "duplicate negotiation parameter rejected": { + resolver: Key{Algorithm: HmacSha256, Material: []byte("secret")}, + opts: []VerifierOption{ + WithRequiredTag("profile", + WithSignatureNegotiation( + WithParameter("audience", "first"), + WithParameter("audience", "second"), + ), + ), + }, + assert: func(t *testing.T, err error, _ *verifier) { + t.Helper() + + require.ErrorIs(t, err, ErrVerifierCreation) + require.ErrorIs(t, err, ErrParameter) + }, + }, } { - t.Run(tc.uc, func(t *testing.T) { + t.Run(uc, func(t *testing.T) { res, err := NewVerifier(tc.resolver, tc.opts...) var v *verifier @@ -712,8 +735,12 @@ func TestVerifierVerify(t *testing.T) { }, }, { - uc: "signature base creation error", - opts: []VerifierOption{WithValidateAllSignatures()}, + uc: "signature base creation error", + opts: []VerifierOption{ + WithValidateAllSignatures(), + WithCreatedTimestamp(false), + WithExpiredTimestamp(false), + }, msg: &Message{ Header: http.Header{ "Signature-Input": []string{`sig=("@status");created=1618884473;keyid="test"`}, @@ -732,7 +759,7 @@ func TestVerifierVerify(t *testing.T) { }, { uc: "key resolver error", - opts: []VerifierOption{WithValidateAllSignatures()}, + opts: []VerifierOption{WithValidateAllSignatures(), WithExpiredTimestamp(false)}, msg: &Message{ Header: http.Header{ "Signature-Input": []string{`sig=();created=1618884473;keyid="test"`}, @@ -761,7 +788,7 @@ func TestVerifierVerify(t *testing.T) { }, }, { - uc: "signature parameters assertion error", + uc: "expired signature rejected before key resolution", opts: []VerifierOption{WithRequiredTag("foo"), WithValidityTolerance(1 * time.Second)}, msg: &Message{ Header: http.Header{ @@ -769,26 +796,65 @@ func TestVerifierVerify(t *testing.T) { "Signature": []string{"sig=:dGVzdA==:"}, }, }, + configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, + assert: func(t *testing.T, err error, _ VerificationResult) { + t.Helper() + + require.Error(t, err) + require.ErrorIs(t, err, ErrVerificationFailed) + require.ErrorContains(t, err, "expired") + }, + }, + { + uc: "missing required component rejected before key resolution", + opts: []VerifierOption{ + WithRequiredTag("foo", WithComponents("@method")), + WithCreatedTimestamp(false), + WithExpiredTimestamp(false), + }, + msg: &Message{ + Header: http.Header{ + "Signature-Input": []string{`sig=();tag="foo"`}, + "Signature": []string{"sig=:dGVzdA==:"}, + }, + IsRequest: true, + }, + configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, + assert: func(t *testing.T, err error, results VerificationResult) { + t.Helper() + + require.ErrorIs(t, err, ErrVerificationFailed) + require.ErrorIs(t, err, &NoApplicableSignatureError{}) + require.Empty(t, results) + }, + }, + { + uc: "signature algorithm mismatch after key resolution", + opts: []VerifierOption{ + WithValidateAllSignatures(), + WithCreatedTimestamp(false), + WithExpiredTimestamp(false), + }, + msg: &Message{ + Header: http.Header{ + "Signature-Input": []string{`sig=();alg="ed25519"`}, + "Signature": []string{"sig=:dGVzdA==:"}, + }, + }, configureResolver: func(t *testing.T, kr *KeyResolverMock) { t.Helper() - kr.EXPECT().ResolveKey(mock.Anything, - mock.MatchedBy(func(si SignatureInfo) bool { - return si.Label == "sig" && - si.Message != nil && - len(si.Components) == 0 && - si.Parameters["expires"] == int64(1618884470) && - si.Parameters["keyid"] == "test" && - si.Parameters["tag"] == "foo" - })). - Return(KeyInfo{}, nil) + kr.EXPECT().ResolveKey(mock.Anything, mock.Anything). + Return(KeyInfo{Key: Key{Algorithm: HmacSha256, Material: []byte("test")}}, nil). + Once() }, - assert: func(t *testing.T, err error, _ VerificationResult) { + assert: func(t *testing.T, err error, results VerificationResult) { t.Helper() - require.Error(t, err) require.ErrorIs(t, err, ErrVerificationFailed) - require.ErrorContains(t, err, "expired") + require.ErrorIs(t, err, ErrParameter) + require.ErrorContains(t, err, "key algorithm ed25519 does not match signature algorithm hmac-sha256") + require.Empty(t, results) }, }, { @@ -949,27 +1015,7 @@ func TestVerifierVerify(t *testing.T) { }, IsRequest: true, }, - configureResolver: func(t *testing.T, kr *KeyResolverMock) { - t.Helper() - - kr.EXPECT().ResolveKey(mock.Anything, - mock.MatchedBy(func(si SignatureInfo) bool { - return si.Label == "sig" && - si.Message != nil && - si.Message.Header.Get("Content-Length") == "18" && - len(si.Components) == 0 && - si.Parameters["created"] == int64(1618884473) && - si.Parameters["keyid"] == "test-key" && - si.Parameters["nonce"] == "abc" && - si.Parameters["tag"] == "foo" - })). - Return( - KeyInfo{ - Key: Key{Material: tkRSAPSS, Algorithm: RsaPssSha512}, - }, - nil, - ) - }, + configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, assert: func(t *testing.T, err error, _ VerificationResult) { t.Helper() @@ -1034,28 +1080,7 @@ func TestVerifierVerify(t *testing.T) { return io.NopCloser(strings.NewReader(`{"hello": "world"}`)), nil }, }, - configureResolver: func(t *testing.T, kr *KeyResolverMock) { - t.Helper() - - kr.EXPECT().ResolveKey(mock.Anything, - mock.MatchedBy(func(si SignatureInfo) bool { - return si.Label == "sig-b22" && - si.Message != nil && - si.Message.Header.Get("Content-Length") == "18" && - len(si.Components) == 3 && - si.Components["@authority"] == "example.com" && - si.Components["@query-param;name=\"Pet\""] == "dog" && - si.Parameters["created"] == int64(1618884473) && - si.Parameters["keyid"] == "test-key-rsa-pss" && - si.Parameters["tag"] == "header-example" - })). - Return( - KeyInfo{ - Key: Key{Material: tkRSAPSS, Algorithm: RsaPssSha512}, - }, - nil, - ) - }, + configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, assert: func(t *testing.T, err error, _ VerificationResult) { t.Helper() @@ -1632,7 +1657,6 @@ func TestVerifierVerify(t *testing.T) { }, nil). Once() }, - assert: func(t *testing.T, err error, results VerificationResult) { t.Helper() @@ -1681,6 +1705,64 @@ func TestVerifierVerify(t *testing.T) { assert.Equal(t, "ed25519", sig.Metadata) }, }, + { + uc: "tag-specific negotiation", + opts: []VerifierOption{ + WithRequiredTag("profile", WithSignatureNegotiation( + WithParameter("audience", "service-a"), + WithParameter("challenge", Token("example")), + )), + }, + msg: &Message{ + Method: http.MethodPost, + Authority: "example.com", + URL: testURL, + Header: http.Header{}, + }, + configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, + assert: func(t *testing.T, err error, _ VerificationResult) { + t.Helper() + + require.Error(t, err) + + var negotiation *NoApplicableSignatureError + + require.ErrorIs(t, err, ErrVerificationFailed) + require.ErrorAs(t, err, &negotiation) + + hdr := make(http.Header) + negotiation.Negotiate(hdr) + assert.Equal(t, `sig=();created;expires;tag="profile";audience="service-a";challenge=example`, hdr.Get(headerAcceptSignature)) + }, + }, + { + uc: "inherited global negotiation", + opts: []VerifierOption{ + WithSignatureNegotiation(WithParameter("audience", "service-a")), + WithRequiredTag("profile"), + }, + msg: &Message{ + Method: http.MethodPost, + Authority: "example.com", + URL: testURL, + Header: http.Header{}, + }, + configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, + assert: func(t *testing.T, err error, _ VerificationResult) { + t.Helper() + + require.Error(t, err) + + var negotiation *NoApplicableSignatureError + + require.ErrorIs(t, err, ErrVerificationFailed) + require.ErrorAs(t, err, &negotiation) + + hdr := make(http.Header) + negotiation.Negotiate(hdr) + assert.Equal(t, `sig=();created;expires;tag="profile";audience="service-a"`, hdr.Get(headerAcceptSignature)) + }, + }, } { t.Run(tc.uc, func(t *testing.T) { kr := NewKeyResolverMock(t) From b18422a3a568bda786ef4d5bbbe2f777e9b9043b Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Tue, 3 Nov 2026 15:57:30 +0100 Subject: [PATCH 19/33] signature and verification internals updated/simplified --- asymmetric.go | 27 +++++++-------------------- asymmetric_test.go | 29 +++++++++++++---------------- signer.go | 22 ++++++++++++---------- symmetric.go | 11 +++++------ symmetric_test.go | 9 ++++----- verifier.go | 5 +++-- 6 files changed, 44 insertions(+), 59 deletions(-) diff --git a/asymmetric.go b/asymmetric.go index 18e047d..9b82b7c 100644 --- a/asymmetric.go +++ b/asymmetric.go @@ -1,6 +1,7 @@ package httpsig import ( + "context" "crypto" "crypto/ecdsa" "crypto/ed25519" @@ -41,21 +42,17 @@ func newECDSASigner(privateKey *ecdsa.PrivateKey, alg SignatureAlgorithm) (*ecds } return &ecdsaSigner{ - alg: alg, privateKey: privateKey, hash: hash, }, nil } type ecdsaSigner struct { - alg SignatureAlgorithm privateKey *ecdsa.PrivateKey hash crypto.Hash } -func (ecs *ecdsaSigner) algorithm() SignatureAlgorithm { return ecs.alg } - -func (ecs *ecdsaSigner) signPayload(payload []byte) ([]byte, error) { +func (ecs *ecdsaSigner) sign(_ context.Context, payload []byte) ([]byte, error) { hasher := ecs.hash.New() // According to documentation, Write() on hash never fails _, _ = hasher.Write(payload) @@ -112,9 +109,7 @@ type rsaSigner struct { hash crypto.Hash } -func (s *rsaSigner) algorithm() SignatureAlgorithm { return s.alg } - -func (s *rsaSigner) signPayload(payload []byte) ([]byte, error) { +func (s *rsaSigner) sign(_ context.Context, payload []byte) ([]byte, error) { var ( out []byte err error @@ -157,19 +152,15 @@ func newEd25519Signer(privateKey ed25519.PrivateKey, alg SignatureAlgorithm) (*e } return &ed25519Signer{ - alg: alg, privateKey: privateKey, }, nil } type ed25519Signer struct { - alg SignatureAlgorithm privateKey ed25519.PrivateKey } -func (s *ed25519Signer) algorithm() SignatureAlgorithm { return s.alg } - -func (s *ed25519Signer) signPayload(payload []byte) ([]byte, error) { +func (s *ed25519Signer) sign(_ context.Context, payload []byte) ([]byte, error) { return ed25519.Sign(s.privateKey, payload), nil } @@ -204,7 +195,6 @@ func newECDSAVerifier(publicKey *ecdsa.PublicKey, alg SignatureAlgorithm) (*ecds } return &ecdsaVerifier{ - alg: alg, publicKey: publicKey, hash: hash, }, nil @@ -212,11 +202,10 @@ func newECDSAVerifier(publicKey *ecdsa.PublicKey, alg SignatureAlgorithm) (*ecds type ecdsaVerifier struct { publicKey *ecdsa.PublicKey - alg SignatureAlgorithm hash crypto.Hash } -func (v *ecdsaVerifier) verifyPayload(payload []byte, signature []byte) error { +func (v *ecdsaVerifier) verify(_ context.Context, payload []byte, signature []byte) error { hasher := v.hash.New() // According to documentation, Write() on hash never fails _, _ = hasher.Write(payload) @@ -275,7 +264,7 @@ type rsaVerifier struct { hash crypto.Hash } -func (v *rsaVerifier) verifyPayload(payload []byte, signature []byte) error { +func (v *rsaVerifier) verify(_ context.Context, payload []byte, signature []byte) error { hasher := v.hash.New() // According to documentation, Write() on hash never fails @@ -313,16 +302,14 @@ func newEd25519Verifier(publicKey ed25519.PublicKey, alg SignatureAlgorithm) (*e return &ed25519Verifier{ publicKey: publicKey, - alg: alg, }, nil } type ed25519Verifier struct { - alg SignatureAlgorithm publicKey ed25519.PublicKey } -func (v *ed25519Verifier) verifyPayload(payload []byte, signature []byte) error { +func (v *ed25519Verifier) verify(_ context.Context, payload []byte, signature []byte) error { if ok := ed25519.Verify(v.publicKey, payload, signature); !ok { return ErrInvalidSignature } diff --git a/asymmetric_test.go b/asymmetric_test.go index 6cbdb69..9145b17 100644 --- a/asymmetric_test.go +++ b/asymmetric_test.go @@ -48,7 +48,6 @@ func TestNewECDSASigner(t *testing.T) { require.NoError(t, err) require.NotNil(t, sig) assert.Equal(t, tc.key, sig.privateKey) - assert.Equal(t, tc.alg, sig.algorithm()) } }) } @@ -80,7 +79,7 @@ func TestECDSASignerSignPayload(t *testing.T) { sig, err := newECDSASigner(tc.key, tc.alg) require.NoError(t, err) - res, err := sig.signPayload(message) + res, err := sig.sign(t.Context(), message) require.NoError(t, err) require.NotEmpty(t, res) @@ -141,7 +140,6 @@ func TestNewRSASigner(t *testing.T) { require.NoError(t, err) require.NotNil(t, sig) assert.Equal(t, tc.key, sig.privateKey) - assert.Equal(t, tc.alg, sig.algorithm()) } }) } @@ -178,7 +176,7 @@ func TestRSASignerSignPayload(t *testing.T) { sig, err := newRSASigner(tc.key, tc.alg) require.NoError(t, err) - res, err := sig.signPayload(message) + res, err := sig.sign(t.Context(), message) if tc.err != nil { require.Error(t, err) require.ErrorIs(t, err, tc.err) @@ -234,7 +232,6 @@ func TestNewEd25519Signer(t *testing.T) { require.NoError(t, err) require.NotNil(t, sig) assert.Equal(t, tc.key, sig.privateKey) - assert.Equal(t, tc.alg, sig.algorithm()) } }) } @@ -251,7 +248,7 @@ func TestEd25519SignerSignPayload(t *testing.T) { sig, err := newEd25519Signer(privKey, Ed25519) require.NoError(t, err) - res, err := sig.signPayload(message) + res, err := sig.sign(t.Context(), message) require.NoError(t, err) ok := ed25519.Verify(pubKey, message, res) @@ -389,14 +386,14 @@ func TestECDSAverifierVerifyPayload(t *testing.T) { sig, err := newECDSASigner(tc.key, tc.alg) require.NoError(t, err) - res, err := sig.signPayload(message) + res, err := sig.sign(t.Context(), message) require.NoError(t, err) require.NotEmpty(t, res) ver, err := newECDSAVerifier(&tc.key.PublicKey, tc.alg) require.NoError(t, err) - err = ver.verifyPayload(mutateMessage(t, message), mutateSignature(t, res)) + err = ver.verify(t.Context(), mutateMessage(t, message), mutateSignature(t, res)) if tc.shouldError { require.Error(t, err) @@ -555,14 +552,14 @@ func TestRSAVerifierVerifyPayload(t *testing.T) { sig, err := newRSASigner(tc.key, tc.alg) require.NoError(t, err) - res, err := sig.signPayload(message) + res, err := sig.sign(t.Context(), message) require.NoError(t, err) require.NotEmpty(t, res) ver, err := newRSAVerifier(&tc.key.PublicKey, tc.alg) require.NoError(t, err) - err = ver.verifyPayload(mutateMessage(t, message), mutateSignature(t, res)) + err = ver.verify(t.Context(), mutateMessage(t, message), mutateSignature(t, res)) if tc.shouldError { require.Error(t, err) @@ -619,28 +616,28 @@ func TestEd25519VerifierVerifyPayload(t *testing.T) { sig, err := newEd25519Signer(privKey, Ed25519) require.NoError(t, err) - res, err := sig.signPayload(message) + res, err := sig.sign(t.Context(), message) require.NoError(t, err) - ver, err := newEd25519Verifier(pubKey, sig.alg) + ver, err := newEd25519Verifier(pubKey, Ed25519) require.NoError(t, err) // valid signature - err = ver.verifyPayload(message, res) + err = ver.verify(t.Context(), message, res) require.NoError(t, err) // invalid signature for the given message - err = ver.verifyPayload([]byte("test"), res) + err = ver.verify(t.Context(), []byte("test"), res) require.Error(t, err) require.ErrorIs(t, err, ErrInvalidSignature) // too short signature - err = ver.verifyPayload(message, res[0:len(res)-1]) + err = ver.verify(t.Context(), message, res[0:len(res)-1]) require.Error(t, err) require.ErrorIs(t, err, ErrInvalidSignature) // too long signature - err = ver.verifyPayload(message, append(res, 0x00)) + err = ver.verify(t.Context(), message, append(res, 0x00)) require.Error(t, err) require.ErrorIs(t, err, ErrInvalidSignature) } diff --git a/signer.go b/signer.go index cb4e444..3e82c9f 100644 --- a/signer.go +++ b/signer.go @@ -1,6 +1,7 @@ package httpsig import ( + "context" "crypto/ecdsa" "crypto/ed25519" "crypto/rsa" @@ -12,8 +13,7 @@ import ( ) type payloadSigner interface { - signPayload(data []byte) ([]byte, error) - algorithm() SignatureAlgorithm + sign(ctx context.Context, data []byte) ([]byte, error) } func newPayloadSigner(signingKey any, alg SignatureAlgorithm) (payloadSigner, error) { @@ -56,10 +56,11 @@ func NewSigner(key Key, opts ...SignerOption) (Signer, error) { } sig := &signer{ - label: "sig", - ttl: 30 * time.Second, //nolint:mnd - ps: ps, - mu: noopMessageUpdater{}, + label: "sig", + ttl: 30 * time.Second, //nolint:mnd + ps: ps, + mu: noopMessageUpdater{}, + sigAlg: key.Algorithm, } for _, opt := range opts { @@ -69,11 +70,11 @@ func NewSigner(key Key, opts ...SignerOption) (Signer, error) { } if sig.includeAlg { - switch sig.ps.algorithm() { + switch key.Algorithm { case RsaPssSha512, RsaPkcs1v15Sha256, HmacSha256, EcdsaP256Sha256, EcdsaP384Sha384, Ed25519: default: return nil, fmt.Errorf("%w: %s is not registered for HTTP Message Signatures", - ErrUnsupportedAlgorithm, sig.ps.algorithm()) + ErrUnsupportedAlgorithm, key.Algorithm) } } @@ -113,6 +114,7 @@ type signer struct { keyID string includeAlg bool ps payloadSigner + sigAlg SignatureAlgorithm cdAlg DigestAlgorithm parameters []parameterOption mu messageUpdater @@ -137,7 +139,7 @@ func (s *signer) Sign(msg *Message, opts ...SignOption) (http.Header, error) { return nil, err } - signature, err := s.ps.signPayload(base.marshal()) + signature, err := s.ps.sign(msg.Context, base.marshal()) if err != nil { return nil, err } @@ -165,7 +167,7 @@ func (s *signer) signatureInput(opts signOptions) *signatureInput { } if s.includeAlg { - params.Add(string(Alg), string(s.ps.algorithm())) + params.Add(string(Alg), string(s.sigAlg)) } if opts.nonceSet { diff --git a/symmetric.go b/symmetric.go index ee5f42f..613befd 100644 --- a/symmetric.go +++ b/symmetric.go @@ -1,6 +1,7 @@ package httpsig import ( + "context" "crypto" "crypto/hmac" "crypto/subtle" @@ -22,23 +23,21 @@ func newSymmetricSigner(key []byte, alg SignatureAlgorithm) (*symmetricSigner, e } return &symmetricSigner{ - alg: alg, key: key, hash: hash, }, nil } type symmetricSigner struct { - alg SignatureAlgorithm key []byte hash crypto.Hash } -func (ms *symmetricSigner) algorithm() SignatureAlgorithm { return ms.alg } - -func (ms *symmetricSigner) signPayload(data []byte) ([]byte, error) { return ms.hmac(data), nil } +func (ms *symmetricSigner) sign(_ context.Context, data []byte) ([]byte, error) { + return ms.hmac(data), nil +} -func (ms *symmetricSigner) verifyPayload(data []byte, mac []byte) error { +func (ms *symmetricSigner) verify(_ context.Context, data []byte, mac []byte) error { if match := subtle.ConstantTimeCompare(mac, ms.hmac(data)); match != 1 { return ErrInvalidSignature } diff --git a/symmetric_test.go b/symmetric_test.go index 03cf234..eeda942 100644 --- a/symmetric_test.go +++ b/symmetric_test.go @@ -49,7 +49,6 @@ func TestNewSymmetricSigner(t *testing.T) { require.NoError(t, err) require.NotNil(t, sig) assert.Equal(t, tc.key, sig.key) - assert.Equal(t, tc.alg, sig.algorithm()) } }) } @@ -88,7 +87,7 @@ func TestSymmetricSignerSignPayload(t *testing.T) { sig, err := newSymmetricSigner(tc.key, tc.alg) require.NoError(t, err) - res, err := sig.signPayload(message) + res, err := sig.sign(t.Context(), message) require.NoError(t, err) require.NotEmpty(t, res) @@ -115,13 +114,13 @@ func TestSymmetricSignerVerifyPayload(t *testing.T) { sig, err := newSymmetricSigner(key, HmacSha256) require.NoError(t, err) - res, err := sig.signPayload(message) + res, err := sig.sign(t.Context(), message) require.NoError(t, err) - err = sig.verifyPayload(message, res) + err = sig.verify(t.Context(), message, res) require.NoError(t, err) - err = sig.verifyPayload([]byte("test"), res) + err = sig.verify(t.Context(), []byte("test"), res) require.Error(t, err) require.ErrorIs(t, err, ErrInvalidSignature) } diff --git a/verifier.go b/verifier.go index b9e83f8..ec452a8 100644 --- a/verifier.go +++ b/verifier.go @@ -1,6 +1,7 @@ package httpsig import ( + "context" "crypto/ecdsa" "crypto/ed25519" "crypto/rsa" @@ -134,7 +135,7 @@ func NewVerifier(resolver KeyResolver, opts ...VerifierOption) (Verifier, error) } type payloadVerifier interface { - verifyPayload(data []byte, signature []byte) error + verify(ctx context.Context, data []byte, signature []byte) error } func newPayloadVerifier(verificationKey any, alg SignatureAlgorithm) (payloadVerifier, error) { @@ -397,7 +398,7 @@ func (v *verifier) verifySignature( return VerifiedSignature{}, err } - err = verifier.verifyPayload(base.marshal(), signature) + err = verifier.verify(msg.Context, base.marshal(), signature) if err != nil { return VerifiedSignature{}, err } From 5a6a846dcc342029749d740e0651fd930cf9f1fc Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Wed, 4 Nov 2026 07:55:59 +0100 Subject: [PATCH 20/33] expectations renamed to verificationPolicy; propagating configuration to Accept-Signature builder --- options.go | 157 ++++++-- options_test.go | 44 +- verification_policy.go | 343 ++++++++++++++++ verification_policy_test.go | 427 ++++++++++++++++++++ verifier.go | 212 +++------- verifier_test.go | 781 ++++++++++++++++++++++-------------- 6 files changed, 1445 insertions(+), 519 deletions(-) create mode 100644 verification_policy.go create mode 100644 verification_policy_test.go diff --git a/options.go b/options.go index 9c2ac91..60dd4bb 100644 --- a/options.go +++ b/options.go @@ -46,7 +46,12 @@ type SignatureNegotiationOption interface { // VerifierOption configures signature selection or verification requirements. // It can also be used within WithRequiredTag for per-tag requirements. type VerifierOption interface { - applyVerifierOption(v *verifier, e *expectations, inTag bool) error + applyVerifierOption(v *verifier, e *verificationPolicy, inTag bool) error +} + +// VerifyOption adds requirements for a single Verify call. +type VerifyOption interface { + applyVerifyOption(e *verificationPolicy) error } // AcceptSignatureOption configures an AcceptSignatureBuilder. @@ -65,9 +70,9 @@ func (f signerOptionFunc) applySignerOption(s *signer) error { return f(s) } -type verifierOptionFunc func(*verifier, *expectations, bool) error +type verifierOptionFunc func(*verifier, *verificationPolicy, bool) error -func (f verifierOptionFunc) applyVerifierOption(v *verifier, e *expectations, inTag bool) error { +func (f verifierOptionFunc) applyVerifierOption(v *verifier, e *verificationPolicy, inTag bool) error { return f(v, e, inTag) } @@ -135,10 +140,10 @@ func (o componentsOption) applySignerOption(s *signer) error { return err } -func (o componentsOption) applyVerifierOption(_ *verifier, exp *expectations, _ bool) error { +func (o componentsOption) applyVerifierOption(_ *verifier, policy *verificationPolicy, _ bool) error { var err error - exp.identifiers, err = toComponentIdentifiers(o.identifiers) + policy.identifiers, err = toComponentIdentifiers(o.identifiers) return err } @@ -226,13 +231,15 @@ func WithAlg() SignerOption { }) } -// WithParameter specifies an extension parameter for signing or requesting a -// signature, either in the reusable configuration or for a single call. -// It can also be used in WithSignatureNegotiation. Extension values may be +// WithParameter specifies an extension parameter for signing, verifying, or +// requesting a signature, either statically or for a single call. It can also +// be used in WithSignatureNegotiation. Extension values may be // string, Token, bool, int, int64, float64, or []byte. Standard RFC 9421 -// parameter names are reserved, except for a non-empty string nonce on Sign -// or AcceptSignatureBuilder.Build. Duplicate names are rejected, including -// duplicates between builder configuration and Build options. +// parameter names are reserved, except for a non-empty string nonce on Verify, +// Sign, or AcceptSignatureBuilder.Build. Verification requirements are additive; +// an invocation cannot override static requirements. Duplicate signing or +// builder parameters are rejected. Do not use secret expected values: verification +// compares them before the signature has been authenticated. func WithParameter(name string, value any) parameterOption { return parameterOption{name: name, value: value} } @@ -274,6 +281,57 @@ func (o parameterOption) applySignatureNegotiationOption(opts *sigNegotiationOpt opts.opts = append(opts.opts, o) } +func (o parameterOption) applyVerifierOption(_ *verifier, policy *verificationPolicy, _ bool) error { + return o.applyVerifyOption(policy) +} + +func (o parameterOption) applyVerifyOption(policy *verificationPolicy) error { + return policy.addExpectedParameter(o) +} + +// WithRequiredParameters requires the named signature parameters to be present. +// It does not check their application-specific semantics. +func WithRequiredParameters(names ...string) requiredParametersOption { + return names +} + +type requiredParametersOption []string + +func (o requiredParametersOption) applyVerifierOption(_ *verifier, policy *verificationPolicy, _ bool) error { + return o.applyVerifyOption(policy) +} + +func (o requiredParametersOption) applyVerifyOption(policy *verificationPolicy) error { + for _, name := range o { + if err := policy.addRequiredParameter(name); err != nil { + return err + } + } + + return nil +} + +// WithForbiddenParameters rejects signatures containing any named parameter. +func WithForbiddenParameters(names ...string) forbiddenParametersOption { + return names +} + +type forbiddenParametersOption []string + +func (o forbiddenParametersOption) applyVerifierOption(_ *verifier, policy *verificationPolicy, _ bool) error { + return o.applyVerifyOption(policy) +} + +func (o forbiddenParametersOption) applyVerifyOption(policy *verificationPolicy) error { + for _, name := range o { + if err := policy.addForbiddenParameter(name); err != nil { + return err + } + } + + return nil +} + func (o parameterOption) applyAcceptSignatureBuildOption(opts *acceptSignatureBuildOptions) error { if o.name == string(Nonce) { if opts.nonceSet { @@ -310,7 +368,7 @@ func validateNonceOption(value any) (string, error) { // WithValidityTolerance specifies the allowed clock skew for created and // expires timestamp checks. func WithValidityTolerance(d time.Duration) VerifierOption { - return verifierOptionFunc(func(_ *verifier, e *expectations, _ bool) error { + return verifierOptionFunc(func(_ *verifier, e *verificationPolicy, _ bool) error { e.tolerance = d return nil @@ -320,7 +378,7 @@ func WithValidityTolerance(d time.Duration) VerifierOption { // WithMaxAge specifies the maximum allowed age of a signature with a // created timestamp. func WithMaxAge(d time.Duration) VerifierOption { - return verifierOptionFunc(func(_ *verifier, e *expectations, _ bool) error { + return verifierOptionFunc(func(_ *verifier, e *verificationPolicy, _ bool) error { e.maxAge = d return nil @@ -330,7 +388,7 @@ func WithMaxAge(d time.Duration) VerifierOption { // WithRequiredTag specifies a required application-defined tag and its // per-tag verifier options. Each non-empty tag may be configured only once. func WithRequiredTag(tag string, opts ...VerifierOption) VerifierOption { - return verifierOptionFunc(func(ver *verifier, _ *expectations, f bool) error { + return verifierOptionFunc(func(ver *verifier, _ *verificationPolicy, f bool) error { if f { panic("WithRequiredTag cannot be used as option for itself") } @@ -339,22 +397,22 @@ func WithRequiredTag(tag string, opts ...VerifierOption) VerifierOption { return fmt.Errorf("%w: required tag must not be empty", ErrParameter) } - if _, configured := ver.tagExpectations[tag]; configured { + if _, configured := ver.tagPolicies[tag]; configured { return fmt.Errorf("%w: requirements for tag %s are already configured", ErrParameter, tag) } - exp := &expectations{ + policy := &verificationPolicy{ tolerance: -1, maxAge: -1, } for _, opt := range opts { - if err := opt.applyVerifierOption(ver, exp, true); err != nil { + if err := opt.applyVerifierOption(ver, policy, true); err != nil { return err } } - ver.tagExpectations[tag] = exp + ver.tagPolicies[tag] = policy return nil }) @@ -363,7 +421,7 @@ func WithRequiredTag(tag string, opts ...VerifierOption) VerifierOption { // WithValidateAllSignatures selects all signatures for verification, rather // than only those with required tags. func WithValidateAllSignatures() VerifierOption { - return verifierOptionFunc(func(v *verifier, _ *expectations, _ bool) error { + return verifierOptionFunc(func(v *verifier, _ *verificationPolicy, _ bool) error { v.validateAllSigs = true return nil @@ -379,9 +437,9 @@ func WithCreatedTimestamp(flag bool) createdTimestampOption { type createdTimestampOption bool -func (o createdTimestampOption) applyVerifierOption(_ *verifier, exp *expectations, _ bool) error { +func (o createdTimestampOption) applyVerifierOption(_ *verifier, policy *verificationPolicy, _ bool) error { flag := bool(o) - exp.reqCreatedTS = &flag + policy.reqCreatedTS = &flag return nil } @@ -401,9 +459,9 @@ func WithExpiredTimestamp(flag bool) expiredTimestampOption { type expiredTimestampOption bool -func (o expiredTimestampOption) applyVerifierOption(_ *verifier, exp *expectations, _ bool) error { +func (o expiredTimestampOption) applyVerifierOption(_ *verifier, policy *verificationPolicy, _ bool) error { flag := bool(o) - exp.reqExpiresTS = &flag + policy.reqExpiresTS = &flag return nil } @@ -423,13 +481,13 @@ func WithSignatureNegotiation(opts ...SignatureNegotiationOption) VerifierOption opt.applySignatureNegotiationOption(no) } - return verifierOptionFunc(func(_ *verifier, exp *expectations, _ bool) error { + return verifierOptionFunc(func(_ *verifier, policy *verificationPolicy, _ bool) error { builder, err := NewAcceptSignature(no.opts...) if err != nil { return err } - exp.asb = builder + policy.asb = builder return nil }) @@ -514,23 +572,10 @@ func addParameter( option parameterOption, copyBytes bool, ) error { - switch SignatureParameter(option.name) { - case Created, Expires, KeyID, Alg, Nonce, Tag: - return fmt.Errorf("%w: %q is a reserved signature parameter", ErrParameter, option.name) - } - - value := option.value - switch v := value.(type) { - case Token: - value = httpsfv.Token(v) - case int: - value = int64(v) - case string, bool, int64, float64, []byte, httpsfv.Token: - default: - return fmt.Errorf("%w: unsupported value type %T for signature parameter %q", ErrParameter, value, option.name) - } + var err error - if err := validateParameter(option.name, value); err != nil { + option, err = normalizeParameter(option) + if err != nil { return err } @@ -547,16 +592,40 @@ func addParameter( } if copyBytes { - if v, ok := value.([]byte); ok { - value = bytes.Clone(v) + if v, ok := option.value.([]byte); ok { + option.value = bytes.Clone(v) } } - *parameters = append(*parameters, parameterOption{name: option.name, value: value}) + *parameters = append(*parameters, option) return nil } +func normalizeParameter(option parameterOption) (parameterOption, error) { + switch SignatureParameter(option.name) { + case Created, Expires, KeyID, Alg, Nonce, Tag: + return option, fmt.Errorf("%w: %q is a reserved signature parameter", ErrParameter, option.name) + } + + switch v := option.value.(type) { + case Token: + option.value = httpsfv.Token(v) + case int: + option.value = int64(v) + case string, bool, int64, float64, []byte, httpsfv.Token: + default: + return option, fmt.Errorf("%w: unsupported value type %T for signature parameter %q", + ErrParameter, option.value, option.name) + } + + if err := validateParameter(option.name, option.value); err != nil { + return option, err + } + + return option, nil +} + func validateParameter(name string, value any) error { validationParams := httpsfv.NewParams() validationParams.Add(name, value) diff --git a/options_test.go b/options_test.go index 21b29b5..a53fb56 100644 --- a/options_test.go +++ b/options_test.go @@ -134,7 +134,7 @@ func TestWithComponentsForVerifier(t *testing.T) { } { t.Run(uc, func(t *testing.T) { v := &verifier{} - exp := &expectations{} + exp := &verificationPolicy{} err := WithComponents(tc.identifiers...).applyVerifierOption(v, exp, false) @@ -143,7 +143,7 @@ func TestWithComponentsForVerifier(t *testing.T) { require.ErrorIs(t, err, tc.err) } else { require.NoError(t, err) - assert.Empty(t, v.tagExpectations) + assert.Empty(t, v.tagPolicies) require.Len(t, exp.identifiers, len(tc.identifiers)) for i, id := range exp.identifiers { @@ -619,12 +619,12 @@ func TestWithValidityTolerance(t *testing.T) { t.Parallel() v := &verifier{} - exp := &expectations{} + exp := &verificationPolicy{} err := WithValidityTolerance(1*time.Minute).applyVerifierOption(v, exp, false) require.NoError(t, err) - assert.Empty(t, v.tagExpectations) + assert.Empty(t, v.tagPolicies) assert.Equal(t, 1*time.Minute, exp.tolerance) } @@ -632,7 +632,7 @@ func TestWithMaxAge(t *testing.T) { t.Parallel() v := &verifier{} - exp := &expectations{} + exp := &verificationPolicy{} err := WithMaxAge(15*time.Minute).applyVerifierOption(v, exp, false) require.NoError(t, err) @@ -645,10 +645,10 @@ func TestWithRequiredTag(t *testing.T) { for uc, tc := range map[string]struct { opts []VerifierOption - assert func(t *testing.T, err error, exp *expectations) + assert func(t *testing.T, err error, exp *verificationPolicy) }{ "without options": { - assert: func(t *testing.T, err error, exp *expectations) { + assert: func(t *testing.T, err error, exp *verificationPolicy) { t.Helper() require.NoError(t, err) @@ -661,7 +661,7 @@ func TestWithRequiredTag(t *testing.T) { opts: []VerifierOption{ WithComponents("@status"), }, - assert: func(t *testing.T, err error, exp *expectations) { + assert: func(t *testing.T, err error, exp *verificationPolicy) { t.Helper() require.NoError(t, err) @@ -675,7 +675,7 @@ func TestWithRequiredTag(t *testing.T) { opts: []VerifierOption{ WithValidityTolerance(5 * time.Minute), }, - assert: func(t *testing.T, err error, exp *expectations) { + assert: func(t *testing.T, err error, exp *verificationPolicy) { t.Helper() require.NoError(t, err) @@ -689,7 +689,7 @@ func TestWithRequiredTag(t *testing.T) { WithComponents("@status"), WithValidityTolerance(5 * time.Minute), }, - assert: func(t *testing.T, err error, exp *expectations) { + assert: func(t *testing.T, err error, exp *verificationPolicy) { t.Helper() require.NoError(t, err) @@ -703,7 +703,7 @@ func TestWithRequiredTag(t *testing.T) { opts: []VerifierOption{ WithComponents("@foo"), }, - assert: func(t *testing.T, err error, exp *expectations) { + assert: func(t *testing.T, err error, exp *verificationPolicy) { t.Helper() require.Error(t, err) @@ -715,7 +715,7 @@ func TestWithRequiredTag(t *testing.T) { opts: []VerifierOption{ WithRequiredTag("foo"), }, - assert: func(t *testing.T, err error, _ *expectations) { + assert: func(t *testing.T, err error, _ *verificationPolicy) { t.Helper() require.Error(t, err) @@ -724,7 +724,7 @@ func TestWithRequiredTag(t *testing.T) { }, } { t.Run(uc, func(t *testing.T) { - v := &verifier{tagExpectations: make(map[string]*expectations)} + v := &verifier{tagPolicies: make(map[string]*verificationPolicy)} recoverIfPanics := func(t *testing.T, f func() error) (err error) { t.Helper() @@ -748,24 +748,24 @@ func TestWithRequiredTag(t *testing.T) { return WithRequiredTag("test", tc.opts...).applyVerifierOption(v, nil, false) }) if err == nil { - require.Len(t, v.tagExpectations, 1) + require.Len(t, v.tagPolicies, 1) } - tc.assert(t, err, v.tagExpectations["test"]) + tc.assert(t, err, v.tagPolicies["test"]) }) } t.Run("empty required tag", func(t *testing.T) { - v := &verifier{tagExpectations: make(map[string]*expectations)} + v := &verifier{tagPolicies: make(map[string]*verificationPolicy)} err := WithRequiredTag("").applyVerifierOption(v, nil, false) require.ErrorIs(t, err, ErrParameter) - assert.Empty(t, v.tagExpectations) + assert.Empty(t, v.tagPolicies) }) t.Run("with duplicate WithRequiredTag", func(t *testing.T) { - v := &verifier{tagExpectations: map[string]*expectations{"foo": {}}} + v := &verifier{tagPolicies: map[string]*verificationPolicy{"foo": {}}} err := WithRequiredTag("foo", nil).applyVerifierOption(v, nil, false) require.Error(t, err) @@ -779,7 +779,7 @@ func TestWithValidateAllSignatures(t *testing.T) { v := &verifier{} - err := WithValidateAllSignatures().applyVerifierOption(v, &expectations{}, false) + err := WithValidateAllSignatures().applyVerifierOption(v, &verificationPolicy{}, false) require.NoError(t, err) assert.True(t, v.validateAllSigs) @@ -793,7 +793,7 @@ func TestWithCreatedTimestampForVerifier(t *testing.T) { "timestamp optional": false, } { t.Run(uc, func(t *testing.T) { - exp := &expectations{} + exp := &verificationPolicy{} err := WithCreatedTimestamp(required).applyVerifierOption(&verifier{}, exp, false) @@ -830,7 +830,7 @@ func TestWithExpiredTimestampForVerifier(t *testing.T) { "timestamp optional": false, } { t.Run(uc, func(t *testing.T) { - exp := &expectations{} + exp := &verificationPolicy{} err := WithExpiredTimestamp(required).applyVerifierOption(&verifier{}, exp, false) @@ -941,7 +941,7 @@ func TestWithSignatureNegotiation(t *testing.T) { } { t.Run(uc, func(t *testing.T) { v := &verifier{} - exp := &expectations{} + exp := &verificationPolicy{} err := WithSignatureNegotiation(tc.opts...).applyVerifierOption(v, exp, false) diff --git a/verification_policy.go b/verification_policy.go new file mode 100644 index 0000000..dbc6053 --- /dev/null +++ b/verification_policy.go @@ -0,0 +1,343 @@ +package httpsig + +import ( + "bytes" + "fmt" + "reflect" + "slices" + "strings" + "time" + + "github.com/dunglas/httpsfv" +) + +type verificationPolicy struct { + tolerance time.Duration + maxAge time.Duration + identifiers []*componentIdentifier + asb *AcceptSignatureBuilder + reqCreatedTS *bool + reqExpiresTS *bool + requiredParameters []string + forbiddenParameters []string + expectedParameters []parameterOption +} + +// clone copies the parameter slices for per-call options. Other fields are +// shared because VerifyOption does not modify them. +func (e *verificationPolicy) clone() *verificationPolicy { + clone := *e + clone.requiredParameters = slices.Clone(e.requiredParameters) + clone.forbiddenParameters = slices.Clone(e.forbiddenParameters) + clone.expectedParameters = slices.Clone(e.expectedParameters) + + return &clone +} + +// withOptions applies per-call options without changing the configured policy. +func (e *verificationPolicy) withOptions(tag string, opts []VerifyOption) (*verificationPolicy, error) { + if len(opts) == 0 { + return e, nil + } + + effective := e.clone() + for _, opt := range opts { + if err := opt.applyVerifyOption(effective); err != nil { + return nil, err + } + } + + if err := effective.validateParameters(tag); err != nil { + return nil, err + } + + return effective, nil +} + +// inherit applies global requirements to a tag-specific configuration. +// Tag-specific values take precedence, while parameter requirements remain additive. +func (e *verificationPolicy) inherit(globalPolicy *verificationPolicy, tag string) error { + if e.tolerance == -1 { + e.tolerance = globalPolicy.tolerance + } + + if e.maxAge == -1 { + e.maxAge = globalPolicy.maxAge + } + + if len(globalPolicy.identifiers) != 0 && len(e.identifiers) == 0 { + e.identifiers = globalPolicy.identifiers + } + + if e.reqExpiresTS == nil { + e.reqExpiresTS = globalPolicy.reqExpiresTS + } + + if e.reqCreatedTS == nil { + e.reqCreatedTS = globalPolicy.reqCreatedTS + } + + if globalPolicy.asb != nil && e.asb == nil { + // Keep negotiation configuration independent for each required tag. + tmp := *globalPolicy.asb + e.asb = &tmp + } + + if err := e.inheritParameters(globalPolicy); err != nil { + return err + } + + return e.prepare(tag) +} + +func (e *verificationPolicy) prepare(tag string) error { + if err := e.validateParameters(tag); err != nil { + return err + } + + if e.asb != nil { + e.asb.setIdentifiers(e.identifiers) + e.asb.tag = tag + e.asb.addCreatedTS = *e.reqCreatedTS + e.asb.addExpiresTS = *e.reqExpiresTS + } + + return nil +} + +func (e *verificationPolicy) inheritParameters(globalPolicy *verificationPolicy) error { + for _, name := range globalPolicy.requiredParameters { + if err := e.requireParameter(name); err != nil { + return err + } + } + + for _, name := range globalPolicy.forbiddenParameters { + if err := e.forbidParameter(name); err != nil { + return err + } + } + + for _, param := range globalPolicy.expectedParameters { + if err := e.expectParameter(param); err != nil { + return err + } + } + + return nil +} + +func (e *verificationPolicy) addRequiredParameter(name string) error { + if err := validateParameter(name, true); err != nil { + return err + } + + return e.requireParameter(name) +} + +func (e *verificationPolicy) requireParameter(name string) error { + if slices.Contains(e.forbiddenParameters, name) { + return fmt.Errorf("%w: required parameter %q is forbidden", ErrParameter, name) + } + + if !slices.Contains(e.requiredParameters, name) { + e.requiredParameters = append(e.requiredParameters, name) + } + + return nil +} + +func (e *verificationPolicy) addForbiddenParameter(name string) error { + if err := validateParameter(name, true); err != nil { + return err + } + + return e.forbidParameter(name) +} + +func (e *verificationPolicy) forbidParameter(name string) error { + if slices.Contains(e.requiredParameters, name) { + return fmt.Errorf("%w: required parameter %q is forbidden", ErrParameter, name) + } + + for _, param := range e.expectedParameters { + if param.name == name { + return fmt.Errorf("%w: expected parameter %q is forbidden", ErrParameter, name) + } + } + + if !slices.Contains(e.forbiddenParameters, name) { + e.forbiddenParameters = append(e.forbiddenParameters, name) + } + + return nil +} + +func (e *verificationPolicy) addExpectedParameter(option parameterOption) error { + if slices.Contains(e.forbiddenParameters, option.name) { + return fmt.Errorf("%w: expected parameter %q is forbidden", ErrParameter, option.name) + } + + if option.name == string(Nonce) { + if _, err := validateNonceOption(option.value); err != nil { + return err + } + } else { + var err error + + option, err = normalizeParameter(option) + if err != nil { + return err + } + } + + // Structured Fields sends decimal values rounded to three places. Compare + // the parsed wire value, not the caller's higher-precision float64. + if _, isDecimal := option.value.(float64); isDecimal { + encoded, err := httpsfv.Marshal(httpsfv.Item{Value: option.value, Params: httpsfv.NewParams()}) + if err != nil { + return fmt.Errorf("%w: %w", ErrParameter, err) + } + + parsed, err := httpsfv.UnmarshalItem([]string{encoded}) + if err != nil { + return fmt.Errorf("%w: %w", ErrParameter, err) + } + + option.value = parsed.Value + } + + if v, ok := option.value.([]byte); ok { + option.value = bytes.Clone(v) + } + + return e.expectParameter(option) +} + +func (e *verificationPolicy) expectParameter(option parameterOption) error { + if slices.Contains(e.forbiddenParameters, option.name) { + return fmt.Errorf("%w: expected parameter %q is forbidden", ErrParameter, option.name) + } + + for _, existing := range e.expectedParameters { + if existing.name == option.name { + if reflect.DeepEqual(existing.value, option.value) { + return nil + } + + return fmt.Errorf("%w: conflicting expectations for parameter %q", ErrParameter, option.name) + } + } + + e.expectedParameters = append(e.expectedParameters, option) + + return nil +} + +func (e *verificationPolicy) validateParameters(tag string) error { + for _, name := range e.forbiddenParameters { + if name == string(Tag) && tag != "" || + name == string(Created) && *e.reqCreatedTS || + name == string(Expires) && *e.reqExpiresTS { + return fmt.Errorf("%w: required signature parameter %q is forbidden", ErrParameter, name) + } + } + + return nil +} + +// nolint: funlen, cyclop, gocognit +func (e *verificationPolicy) assertMetadata(si *signatureInput, msg *Message) error { + var ( + missingComponents []string + cmv compositeMessageVerifier + mv messageVerifier + ) + + now := currentTime().UTC() + + expires, expiresPresent := si.expires() + if !expiresPresent { + if *e.reqExpiresTS { + return fmt.Errorf("%w: expected expires parameter not present", ErrMissingParameter) + } + } else if now.After(expires.Add(e.tolerance)) { + return fmt.Errorf("%w: signature expired", ErrValidity) + } + + created, createdPresent := si.created() + if !createdPresent { + if *e.reqCreatedTS { + return fmt.Errorf("%w: expected created parameter not present", ErrMissingParameter) + } + } else { + if now.Before(created.Add(-1 * e.tolerance)) { + return fmt.Errorf("%w: signature not yet valid", ErrValidity) + } + + if created.Add(e.maxAge).Before(now) { + return fmt.Errorf("%w: signature too old", ErrValidity) + } + } + + for _, expIdentifier := range e.identifiers { + if !si.hasIdentifier(expIdentifier) { + res, _ := httpsfv.Marshal(expIdentifier) + missingComponents = append(missingComponents, res) + } + } + + if len(missingComponents) > 0 { + return fmt.Errorf("%w: missing component identifiers: %s", + ErrMissingParameter, strings.Join(missingComponents, ", ")) + } + + for _, name := range e.requiredParameters { + if _, present := si.parameter(SignatureParameter(name)); !present { + return fmt.Errorf("%w: required signature parameter %q is missing", ErrParameter, name) + } + } + + for _, name := range e.forbiddenParameters { + if _, present := si.parameter(SignatureParameter(name)); present { + return fmt.Errorf("%w: forbidden signature parameter %q is present", ErrParameter, name) + } + } + + for _, param := range e.expectedParameters { + value, present := si.parameter(SignatureParameter(param.name)) + if !present { + return fmt.Errorf("%w: expected signature parameter %q is missing", ErrMissingParameter, param.name) + } + + if !reflect.DeepEqual(value, param.value) { + return fmt.Errorf("%w: unexpected value for signature parameter %q", ErrParameter, param.name) + } + } + + for _, id := range si.identifiers { + if id.Value == "content-digest" { + _, fromReq := id.Params.Get("req") + + cmv = append(cmv, contentDigester{fromRequest: fromReq}) + } + } + + if len(cmv) == 0 { + mv = noopMessageVerifier{} + } else { + mv = cmv + } + + return mv.verify(msg) +} + +func (e *verificationPolicy) assertKeyAlgorithm(si *signatureInput, keyAlg SignatureAlgorithm) error { + algorithm, algPresent := si.algorithm() + if algPresent && algorithm != keyAlg { + return fmt.Errorf("%w: key algorithm %s does not match signature algorithm %s", + ErrParameter, algorithm, keyAlg) + } + + return nil +} diff --git a/verification_policy_test.go b/verification_policy_test.go new file mode 100644 index 0000000..beb251b --- /dev/null +++ b/verification_policy_test.go @@ -0,0 +1,427 @@ +package httpsig + +import ( + "context" + "testing" + "time" + + "github.com/dunglas/httpsfv" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestVerificationPolicyClone(t *testing.T) { + t.Parallel() + + original := &verificationPolicy{ + requiredParameters: []string{"nonce"}, + forbiddenParameters: []string{"alg"}, + expectedParameters: []parameterOption{{name: "audience", value: "service-a"}}, + } + + clone := original.clone() + require.NotSame(t, original, clone) + + clone.requiredParameters[0] = "created" + clone.forbiddenParameters[0] = "keyid" + clone.expectedParameters[0] = parameterOption{name: "audience", value: "service-b"} + + assert.Equal(t, []string{"nonce"}, original.requiredParameters) + assert.Equal(t, []string{"alg"}, original.forbiddenParameters) + assert.Equal(t, []parameterOption{{name: "audience", value: "service-a"}}, original.expectedParameters) +} + +func TestVerificationPolicyWithOptions(t *testing.T) { + t.Parallel() + + required := true + original := &verificationPolicy{reqCreatedTS: &required, reqExpiresTS: &required} + + unchanged, err := original.withOptions("profile", nil) + require.NoError(t, err) + assert.Same(t, original, unchanged) + + effective, err := original.withOptions("profile", []VerifyOption{WithRequiredParameters("nonce")}) + require.NoError(t, err) + require.NotSame(t, original, effective) + assert.Equal(t, []string{"nonce"}, effective.requiredParameters) + assert.Empty(t, original.requiredParameters) + + _, err = original.withOptions("profile", []VerifyOption{WithForbiddenParameters("tag")}) + require.ErrorIs(t, err, ErrParameter) + assert.Empty(t, original.forbiddenParameters) +} + +func TestVerificationPolicyInherit(t *testing.T) { + t.Parallel() + + globalIDs, err := toComponentIdentifiers([]string{"@method", "content-digest"}) + require.NoError(t, err) + + required := true + global := &verificationPolicy{ + tolerance: 2 * time.Second, + maxAge: 30 * time.Second, + identifiers: globalIDs, + reqCreatedTS: &required, + reqExpiresTS: &required, + asb: &AcceptSignatureBuilder{label: "sig"}, + requiredParameters: []string{"nonce"}, + forbiddenParameters: []string{"alg"}, + expectedParameters: []parameterOption{{name: "audience", value: "service-a"}}, + } + + t.Run("inherits global configuration", func(t *testing.T) { + t.Parallel() + + local := &verificationPolicy{tolerance: -1, maxAge: -1} + require.NoError(t, local.inherit(global, "profile")) + + assert.Equal(t, global.tolerance, local.tolerance) + assert.Equal(t, global.maxAge, local.maxAge) + assert.Equal(t, global.identifiers, local.identifiers) + assert.Equal(t, global.reqCreatedTS, local.reqCreatedTS) + assert.Equal(t, global.reqExpiresTS, local.reqExpiresTS) + assert.Equal(t, global.requiredParameters, local.requiredParameters) + assert.Equal(t, global.forbiddenParameters, local.forbiddenParameters) + assert.Equal(t, global.expectedParameters, local.expectedParameters) + + require.NotSame(t, global.asb, local.asb) + assert.Equal(t, "profile", local.asb.tag) + assert.Empty(t, global.asb.tag) + assert.True(t, local.asb.wantContentDigest) + assert.True(t, local.asb.addCreatedTS) + assert.True(t, local.asb.addExpiresTS) + }) + + t.Run("keeps local overrides", func(t *testing.T) { + t.Parallel() + + created := false + expires := false + localIDs, err := toComponentIdentifiers([]string{"@status"}) + require.NoError(t, err) + + localBuilder := &AcceptSignatureBuilder{label: "custom"} + local := &verificationPolicy{ + tolerance: time.Second, + maxAge: 5 * time.Second, + identifiers: localIDs, + reqCreatedTS: &created, + reqExpiresTS: &expires, + asb: localBuilder, + } + require.NoError(t, local.inherit(global, "profile")) + + assert.Equal(t, time.Second, local.tolerance) + assert.Equal(t, 5*time.Second, local.maxAge) + assert.Equal(t, localIDs, local.identifiers) + assert.False(t, *local.reqCreatedTS) + assert.False(t, *local.reqExpiresTS) + assert.Same(t, localBuilder, local.asb) + assert.Equal(t, "custom", local.asb.label) + assert.False(t, local.asb.wantContentDigest) + assert.False(t, local.asb.addCreatedTS) + assert.False(t, local.asb.addExpiresTS) + }) + + for uc, local := range map[string]verificationPolicy{ + "local requirement conflicts with global prohibition": { + requiredParameters: []string{"alg"}, + }, + "local prohibition conflicts with global required parameter": { + forbiddenParameters: []string{"nonce"}, + }, + "local value conflicts with global expectation": { + expectedParameters: []parameterOption{{name: "audience", value: "other"}}, + }, + } { + t.Run(uc, func(t *testing.T) { + t.Parallel() + + local.tolerance = -1 + local.maxAge = -1 + require.ErrorIs(t, local.inherit(global, "profile"), ErrParameter) + }) + } +} + +func TestVerificationPolicyAssertMetadata(t *testing.T) { + now := time.Now().UTC() + falseVal := false + trueVal := true + + for uc, tc := range map[string]struct { + params httpsfv.InnerList + exp verificationPolicy + assert func(t *testing.T, err error) + }{ + "signature expired, no tolerance specified": { + params: httpsfv.InnerList{ + Params: func() *httpsfv.Params { + params := httpsfv.NewParams() + params.Add(string(Expires), now.Add(-2*time.Second).Unix()) + + return params + }(), + }, + exp: verificationPolicy{reqExpiresTS: &falseVal, reqCreatedTS: &falseVal}, + assert: func(t *testing.T, err error) { + t.Helper() + + require.Error(t, err) + require.ErrorIs(t, err, ErrValidity) + require.ErrorContains(t, err, "expired") + }, + }, + "signature is still valid with specified tolerance": { + params: httpsfv.InnerList{ + Params: func() *httpsfv.Params { + params := httpsfv.NewParams() + params.Add(string(Expires), now.Add(-2*time.Second).Unix()) + + return params + }(), + }, + exp: verificationPolicy{ + tolerance: 3 * time.Second, + reqCreatedTS: &falseVal, + reqExpiresTS: &falseVal, + }, + assert: func(t *testing.T, err error) { + t.Helper() + + require.NoError(t, err) + }, + }, + "signature is valid if expires in the future": { + params: httpsfv.InnerList{ + Params: func() *httpsfv.Params { + params := httpsfv.NewParams() + params.Add(string(Expires), now.Add(2*time.Second).Unix()) + + return params + }(), + }, + exp: verificationPolicy{ + tolerance: 2 * time.Second, + reqCreatedTS: &falseVal, + reqExpiresTS: &falseVal, + }, + assert: func(t *testing.T, err error) { + t.Helper() + + require.NoError(t, err) + }, + }, + "signature not yet valid, no tolerance specified": { + params: httpsfv.InnerList{ + Params: func() *httpsfv.Params { + params := httpsfv.NewParams() + params.Add(string(Created), now.Add(2*time.Second).Unix()) + + return params + }(), + }, + exp: verificationPolicy{reqCreatedTS: &falseVal, reqExpiresTS: &falseVal}, + assert: func(t *testing.T, err error) { + t.Helper() + + require.Error(t, err) + require.ErrorIs(t, err, ErrValidity) + require.ErrorContains(t, err, "not yet valid") + }, + }, + "signature already valid with specified tolerance": { + params: httpsfv.InnerList{ + Params: func() *httpsfv.Params { + params := httpsfv.NewParams() + params.Add(string(Created), now.Add(2*time.Second).Unix()) + + return params + }(), + }, + exp: verificationPolicy{ + tolerance: 3 * time.Second, + reqCreatedTS: &falseVal, + reqExpiresTS: &falseVal, + }, + assert: func(t *testing.T, err error) { + t.Helper() + + require.NoError(t, err) + }, + }, + "signature is valid if created in the past": { + params: httpsfv.InnerList{ + Params: func() *httpsfv.Params { + params := httpsfv.NewParams() + params.Add(string(Created), now.Add(-2*time.Second).Unix()) + + return params + }(), + }, + exp: verificationPolicy{ + maxAge: 30 * time.Second, + reqCreatedTS: &falseVal, + reqExpiresTS: &falseVal, + }, + assert: func(t *testing.T, err error) { + t.Helper() + + require.NoError(t, err) + }, + }, + "signature too old": { + params: httpsfv.InnerList{ + Params: func() *httpsfv.Params { + params := httpsfv.NewParams() + params.Add(string(Created), now.Add(-2*time.Second).Unix()) + + return params + }(), + }, + exp: verificationPolicy{reqCreatedTS: &falseVal, reqExpiresTS: &falseVal}, + assert: func(t *testing.T, err error) { + t.Helper() + + require.Error(t, err) + require.ErrorIs(t, err, ErrValidity) + require.ErrorContains(t, err, "too old") + }, + }, + "expected component identifier missing": { + params: httpsfv.InnerList{Params: httpsfv.NewParams()}, + exp: func() verificationPolicy { + ids, err := toComponentIdentifiers([]string{"@method;req", "@authority"}) + require.NoError(t, err) + + return verificationPolicy{identifiers: ids, reqCreatedTS: &falseVal, reqExpiresTS: &falseVal} + }(), + assert: func(t *testing.T, err error) { + t.Helper() + + require.Error(t, err) + require.ErrorIs(t, err, ErrMissingParameter) + require.ErrorContains(t, err, `"@method";req, "@authority"`) + }, + }, + "expected created parameter is missing": { + params: httpsfv.InnerList{Params: httpsfv.NewParams()}, + exp: verificationPolicy{reqCreatedTS: &trueVal, reqExpiresTS: &falseVal}, + assert: func(t *testing.T, err error) { + t.Helper() + + require.Error(t, err) + require.ErrorIs(t, err, ErrMissingParameter) + require.ErrorContains(t, err, `created parameter`) + }, + }, + "expected expires parameter is missing": { + params: httpsfv.InnerList{Params: httpsfv.NewParams()}, + exp: verificationPolicy{reqCreatedTS: &falseVal, reqExpiresTS: &trueVal}, + assert: func(t *testing.T, err error) { + t.Helper() + + require.Error(t, err) + require.ErrorIs(t, err, ErrMissingParameter) + require.ErrorContains(t, err, `expires parameter`) + }, + }, + "successful assertion with all possible parameters": { + params: httpsfv.InnerList{ + Params: func() *httpsfv.Params { + params := httpsfv.NewParams() + params.Add(string(Created), now.Add(-3*time.Second).Unix()) + params.Add(string(Expires), now.Add(3*time.Second).Unix()) + params.Add(string(Alg), string(EcdsaP256Sha256)) + params.Add(string(KeyID), "test") + params.Add(string(Nonce), "foo") + params.Add(string(Tag), "test") + + return params + }(), + Items: []httpsfv.Item{ + httpsfv.NewItem("@method"), + httpsfv.NewItem("@authority"), + }, + }, + exp: func() verificationPolicy { + ids, err := toComponentIdentifiers([]string{"@authority", "@method"}) + require.NoError(t, err) + + return verificationPolicy{ + identifiers: ids, + maxAge: 5 * time.Second, + } + }(), + assert: func(t *testing.T, err error) { + t.Helper() + + require.NoError(t, err) + }, + }, + } { + t.Run(uc, func(t *testing.T) { + msg := &Message{Context: context.TODO()} + + si, err := parseSignatureInput(tc.params) + require.NoError(t, err) + + err = tc.exp.assertMetadata(si, msg) + + tc.assert(t, err) + }) + } +} + +func TestVerificationPolicyAssertKeyAlgorithm(t *testing.T) { + for uc, tc := range map[string]struct { + parameterAlg SignatureAlgorithm + keyAlg SignatureAlgorithm + assert func(t *testing.T, err error) + }{ + "signature algorithm mismatch": { + parameterAlg: RsaPssSha512, + keyAlg: EcdsaP256Sha256, + assert: func(t *testing.T, err error) { + t.Helper() + + require.ErrorIs(t, err, ErrParameter) + require.ErrorContains(t, err, "key algorithm rsa-pss-sha512 does not match signature algorithm ecdsa-p256-sha256") + }, + }, + "signature algorithm matches": { + parameterAlg: RsaPssSha512, + keyAlg: RsaPssSha512, + assert: func(t *testing.T, err error) { + t.Helper() + + require.NoError(t, err) + }, + }, + "signature algorithm absent": { + keyAlg: EcdsaP256Sha256, + assert: func(t *testing.T, err error) { + t.Helper() + + require.NoError(t, err) + }, + }, + } { + t.Run(uc, func(t *testing.T) { + params := httpsfv.NewParams() + if tc.parameterAlg != "" { + params.Add(string(Alg), string(tc.parameterAlg)) + } + + si, err := parseSignatureInput(httpsfv.InnerList{Params: params}) + require.NoError(t, err) + + exp := &verificationPolicy{} + err = exp.assertKeyAlgorithm(si, tc.keyAlg) + + tc.assert(t, err) + }) + } +} diff --git a/verifier.go b/verifier.go index ec452a8..14a29e2 100644 --- a/verifier.go +++ b/verifier.go @@ -8,7 +8,6 @@ import ( "errors" "fmt" "net/http" - "strings" "time" "github.com/dunglas/httpsfv" @@ -42,8 +41,8 @@ type VerificationResult []VerifiedSignature // requirements. A call succeeds only if all selected signatures pass. type Verifier interface { // Verify returns information about the successfully verified signatures - // or an error. - Verify(msg *Message) (VerificationResult, error) + // or an error. Per-call requirements do not change the Verifier. + Verify(msg *Message, opts ...VerifyOption) (VerificationResult, error) } // NewVerifier creates a Verifier instance. @@ -59,76 +58,45 @@ func NewVerifier(resolver KeyResolver, opts ...VerifierOption) (Verifier, error) return nil, fmt.Errorf("%w: no key resolver provided", ErrVerifierCreation) } - trueValue := true - ver := &verifier{ - keyResolver: resolver, - tagExpectations: make(map[string]*expectations), + keyResolver: resolver, + tagPolicies: make(map[string]*verificationPolicy), } - global := &expectations{ + globalPolicy := &verificationPolicy{ maxAge: 30 * time.Second, //nolint:mnd - reqExpiresTS: &trueValue, - reqCreatedTS: &trueValue, + reqExpiresTS: new(true), + reqCreatedTS: new(true), } for _, opt := range opts { - if err := opt.applyVerifierOption(ver, global, false); err != nil { + if err := opt.applyVerifierOption(ver, globalPolicy, false); err != nil { return nil, fmt.Errorf("%w: %w", ErrVerifierCreation, err) } } - if !ver.validateAllSigs && len(ver.tagExpectations) == 0 { + if !ver.validateAllSigs && len(ver.tagPolicies) == 0 { return nil, fmt.Errorf("%w: validation of all signatures disabled, but no signature tags specified", ErrVerifierCreation) } - if global.asb != nil && ver.validateAllSigs { + if globalPolicy.asb != nil && ver.validateAllSigs { return nil, fmt.Errorf("%w: verification and negotiation of all posible signature is not possible", ErrVerifierCreation) } - if global.asb != nil { - global.asb.setIdentifiers(global.identifiers) - } - - for tag, exp := range ver.tagExpectations { - if exp.tolerance == -1 { - exp.tolerance = global.tolerance - } - - if exp.maxAge == -1 { - exp.maxAge = global.maxAge - } - - if len(global.identifiers) != 0 && len(exp.identifiers) == 0 { - exp.identifiers = global.identifiers - } - - if exp.reqExpiresTS == nil { - exp.reqExpiresTS = global.reqExpiresTS - } - - if exp.reqCreatedTS == nil { - exp.reqCreatedTS = global.reqCreatedTS - } - - if global.asb != nil && exp.asb == nil { - // create a copy - tmp := *global.asb - exp.asb = &tmp - } - - if exp.asb != nil { - exp.asb.setIdentifiers(exp.identifiers) - exp.asb.tag = tag - exp.asb.addCreatedTS = *exp.reqCreatedTS - exp.asb.addExpiresTS = *exp.reqExpiresTS + for tag, policy := range ver.tagPolicies { + if err := policy.inherit(globalPolicy, tag); err != nil { + return nil, fmt.Errorf("%w: %w", ErrVerifierCreation, err) } } if ver.validateAllSigs { - ver.tagExpectations[""] = global + if err := globalPolicy.prepare(""); err != nil { + return nil, fmt.Errorf("%w: %w", ErrVerifierCreation, err) + } + + ver.tagPolicies[""] = globalPolicy } return ver, nil @@ -153,95 +121,18 @@ func newPayloadVerifier(verificationKey any, alg SignatureAlgorithm) (payloadVer } } -type expectations struct { - tolerance time.Duration - maxAge time.Duration - identifiers []*componentIdentifier - asb *AcceptSignatureBuilder - reqCreatedTS *bool - reqExpiresTS *bool -} - -// nolint: funlen, cyclop -func (e *expectations) assertMetadata(si *signatureInput, msg *Message) error { - var ( - missingComponents []string - cmv compositeMessageVerifier - mv messageVerifier - ) - - now := currentTime().UTC() - - expires, expiresPresent := si.expires() - if !expiresPresent { - if *e.reqExpiresTS { - return fmt.Errorf("%w: expected expires parameter not present", ErrMissingParameter) - } - } else if now.After(expires.Add(e.tolerance)) { - return fmt.Errorf("%w: signature expired", ErrValidity) - } - - created, createdPresent := si.created() - if !createdPresent { - if *e.reqCreatedTS { - return fmt.Errorf("%w: expected created parameter not present", ErrMissingParameter) - } - } else { - if now.Before(created.Add(-1 * e.tolerance)) { - return fmt.Errorf("%w: signature not yet valid", ErrValidity) - } - - if created.Add(e.maxAge).Before(now) { - return fmt.Errorf("%w: signature too old", ErrValidity) - } - } - - for _, expIdentifier := range e.identifiers { - if !si.hasIdentifier(expIdentifier) { - res, _ := httpsfv.Marshal(expIdentifier) - missingComponents = append(missingComponents, res) - } - } - - if len(missingComponents) > 0 { - return fmt.Errorf("%w: missing component identifiers: %s", - ErrMissingParameter, strings.Join(missingComponents, ", ")) - } - - for _, id := range si.identifiers { - if id.Value == "content-digest" { - _, fromReq := id.Params.Get("req") - - cmv = append(cmv, contentDigester{fromRequest: fromReq}) - } - } - - if len(cmv) == 0 { - mv = noopMessageVerifier{} - } else { - mv = cmv - } - - return mv.verify(msg) -} - -func (e *expectations) assertKeyAlgorithm(si *signatureInput, keyAlg SignatureAlgorithm) error { - algorithm, algPresent := si.algorithm() - if algPresent && algorithm != keyAlg { - return fmt.Errorf("%w: key algorithm %s does not match signature algorithm %s", - ErrParameter, algorithm, keyAlg) - } - - return nil -} - type verifier struct { keyResolver KeyResolver - tagExpectations map[string]*expectations + tagPolicies map[string]*verificationPolicy validateAllSigs bool } -func (v *verifier) Verify(msg *Message) (VerificationResult, error) { +func (v *verifier) Verify(msg *Message, opts ...VerifyOption) (VerificationResult, error) { + policiesByTag, err := v.policiesForCall(opts) + if err != nil { + return nil, fmt.Errorf("%w: %w", ErrVerificationFailed, err) + } + sigRefs, err := getSignatureReferences(msg.Header.Values(headerSignatureInput)) if err != nil { return nil, fmt.Errorf("%w: %w", ErrVerificationFailed, err) @@ -254,7 +145,7 @@ func (v *verifier) Verify(msg *Message) (VerificationResult, error) { // look if we miss any signatures for configured tags if v.hasMissingSignatures(sigRefs) { - return nil, fmt.Errorf("%w: %w", ErrVerificationFailed, v.negotiateSignatureParameters(msg)) + return nil, fmt.Errorf("%w: %w", ErrVerificationFailed, v.negotiateSignatureParameters(msg, policiesByTag)) } // collect those signatures, which we can verify @@ -268,9 +159,9 @@ func (v *verifier) Verify(msg *Message) (VerificationResult, error) { for name, params := range applicableSignatures { tag, _ := params.tag() - exp, exists := v.tagExpectations[tag] + policy, exists := policiesByTag[tag] if !exists { - exp = v.tagExpectations[""] + policy = policiesByTag[""] } signature, err := v.extractSignature(signatureDict, name) @@ -278,10 +169,10 @@ func (v *verifier) Verify(msg *Message) (VerificationResult, error) { return nil, fmt.Errorf("%w: %w", ErrVerificationFailed, err) } - result, err := v.verifySignature(msg, name, signature, params, exp) + result, err := v.verifySignature(msg, name, signature, params, policy) if err != nil { if errors.Is(err, ErrMissingParameter) { - return nil, fmt.Errorf("%w: %w", ErrVerificationFailed, v.negotiateSignatureParameters(msg)) + return nil, fmt.Errorf("%w: %w", ErrVerificationFailed, v.negotiateSignatureParameters(msg, policiesByTag)) } return nil, fmt.Errorf("%w: %w", ErrVerificationFailed, err) @@ -293,6 +184,24 @@ func (v *verifier) Verify(msg *Message) (VerificationResult, error) { return results, nil } +func (v *verifier) policiesForCall(opts []VerifyOption) (map[string]*verificationPolicy, error) { + if len(opts) == 0 { + return v.tagPolicies, nil + } + + result := make(map[string]*verificationPolicy, len(v.tagPolicies)) + for tag, original := range v.tagPolicies { + effective, err := original.withOptions(tag, opts) + if err != nil { + return nil, err + } + + result[tag] = effective + } + + return result, nil +} + func (v *verifier) applicableSignatures(refs map[string]*signatureInput) (map[string]*signatureInput, error) { if !v.validateAllSigs { for name, input := range refs { @@ -303,7 +212,7 @@ func (v *verifier) applicableSignatures(refs map[string]*signatureInput) (map[st continue } - if _, required := v.tagExpectations[tag]; !required { + if _, required := v.tagPolicies[tag]; !required { delete(refs, name) } } @@ -316,15 +225,20 @@ func (v *verifier) applicableSignatures(refs map[string]*signatureInput) (map[st return refs, nil } -func (v *verifier) negotiateSignatureParameters(msg *Message) error { +func (v *verifier) negotiateSignatureParameters(msg *Message, policiesByTag map[string]*verificationPolicy) error { hdr := http.Header{} - for sigTag, exp := range v.tagExpectations { - if exp.asb == nil || len(sigTag) == 0 { + for sigTag, policy := range policiesByTag { + if policy.asb == nil || len(sigTag) == 0 { continue } - err := exp.asb.Build(msg.Context, hdr) + buildOpts := make([]AcceptSignatureBuildOption, len(policy.expectedParameters)) + for i, param := range policy.expectedParameters { + buildOpts[i] = param + } + + err := policy.asb.Build(msg.Context, hdr, buildOpts...) if err != nil { return fmt.Errorf("%w: failed to negotiate signature for tag %s: %w", ErrSignatureNegotiationError, sigTag, err) } @@ -334,9 +248,9 @@ func (v *verifier) negotiateSignatureParameters(msg *Message) error { } func (v *verifier) hasMissingSignatures(sigRefs map[string]*signatureInput) bool { - for sigTag := range v.tagExpectations { + for sigTag := range v.tagPolicies { if len(sigTag) == 0 { - // empty tag is used for expectations for all signatures + // empty tag is used for a policy applying to all signatures // ignoring it continue } @@ -365,9 +279,9 @@ func (v *verifier) verifySignature( label string, signature []byte, si *signatureInput, - exp *expectations, + policy *verificationPolicy, ) (VerifiedSignature, error) { - if err := exp.assertMetadata(si, msg); err != nil { + if err := policy.assertMetadata(si, msg); err != nil { return VerifiedSignature{}, err } @@ -389,7 +303,7 @@ func (v *verifier) verifySignature( return VerifiedSignature{}, err } - if err = exp.assertKeyAlgorithm(si, keyInfo.Key.Algorithm); err != nil { + if err = policy.assertKeyAlgorithm(si, keyInfo.Key.Algorithm); err != nil { return VerifiedSignature{}, err } diff --git a/verifier_test.go b/verifier_test.go index 5ee7444..5307781 100644 --- a/verifier_test.go +++ b/verifier_test.go @@ -16,6 +16,7 @@ import ( "net/url" "slices" "strings" + "sync" "testing" "time" @@ -69,286 +70,6 @@ func TestNewPayloadVerifier(t *testing.T) { } } -func TestExpectationsAssertMetadata(t *testing.T) { - now := time.Now().UTC() - falseVal := false - trueVal := true - - for uc, tc := range map[string]struct { - params httpsfv.InnerList - exp expectations - assert func(t *testing.T, err error) - }{ - "signature expired, no tolerance specified": { - params: httpsfv.InnerList{ - Params: func() *httpsfv.Params { - params := httpsfv.NewParams() - params.Add(string(Expires), now.Add(-2*time.Second).Unix()) - - return params - }(), - }, - exp: expectations{reqExpiresTS: &falseVal, reqCreatedTS: &falseVal}, - assert: func(t *testing.T, err error) { - t.Helper() - - require.Error(t, err) - require.ErrorIs(t, err, ErrValidity) - require.ErrorContains(t, err, "expired") - }, - }, - "signature is still valid with specified tolerance": { - params: httpsfv.InnerList{ - Params: func() *httpsfv.Params { - params := httpsfv.NewParams() - params.Add(string(Expires), now.Add(-2*time.Second).Unix()) - - return params - }(), - }, - exp: expectations{ - tolerance: 3 * time.Second, - reqCreatedTS: &falseVal, - reqExpiresTS: &falseVal, - }, - assert: func(t *testing.T, err error) { - t.Helper() - - require.NoError(t, err) - }, - }, - "signature is valid if expires in the future": { - params: httpsfv.InnerList{ - Params: func() *httpsfv.Params { - params := httpsfv.NewParams() - params.Add(string(Expires), now.Add(2*time.Second).Unix()) - - return params - }(), - }, - exp: expectations{ - tolerance: 2 * time.Second, - reqCreatedTS: &falseVal, - reqExpiresTS: &falseVal, - }, - assert: func(t *testing.T, err error) { - t.Helper() - - require.NoError(t, err) - }, - }, - "signature not yet valid, no tolerance specified": { - params: httpsfv.InnerList{ - Params: func() *httpsfv.Params { - params := httpsfv.NewParams() - params.Add(string(Created), now.Add(2*time.Second).Unix()) - - return params - }(), - }, - exp: expectations{reqCreatedTS: &falseVal, reqExpiresTS: &falseVal}, - assert: func(t *testing.T, err error) { - t.Helper() - - require.Error(t, err) - require.ErrorIs(t, err, ErrValidity) - require.ErrorContains(t, err, "not yet valid") - }, - }, - "signature already valid with specified tolerance": { - params: httpsfv.InnerList{ - Params: func() *httpsfv.Params { - params := httpsfv.NewParams() - params.Add(string(Created), now.Add(2*time.Second).Unix()) - - return params - }(), - }, - exp: expectations{ - tolerance: 3 * time.Second, - reqCreatedTS: &falseVal, - reqExpiresTS: &falseVal, - }, - assert: func(t *testing.T, err error) { - t.Helper() - - require.NoError(t, err) - }, - }, - "signature is valid if created in the past": { - params: httpsfv.InnerList{ - Params: func() *httpsfv.Params { - params := httpsfv.NewParams() - params.Add(string(Created), now.Add(-2*time.Second).Unix()) - - return params - }(), - }, - exp: expectations{ - maxAge: 30 * time.Second, - reqCreatedTS: &falseVal, - reqExpiresTS: &falseVal, - }, - assert: func(t *testing.T, err error) { - t.Helper() - - require.NoError(t, err) - }, - }, - "signature too old": { - params: httpsfv.InnerList{ - Params: func() *httpsfv.Params { - params := httpsfv.NewParams() - params.Add(string(Created), now.Add(-2*time.Second).Unix()) - - return params - }(), - }, - exp: expectations{reqCreatedTS: &falseVal, reqExpiresTS: &falseVal}, - assert: func(t *testing.T, err error) { - t.Helper() - - require.Error(t, err) - require.ErrorIs(t, err, ErrValidity) - require.ErrorContains(t, err, "too old") - }, - }, - "expected component identifier missing": { - params: httpsfv.InnerList{Params: httpsfv.NewParams()}, - exp: func() expectations { - ids, err := toComponentIdentifiers([]string{"@method;req", "@authority"}) - require.NoError(t, err) - - return expectations{identifiers: ids, reqCreatedTS: &falseVal, reqExpiresTS: &falseVal} - }(), - assert: func(t *testing.T, err error) { - t.Helper() - - require.Error(t, err) - require.ErrorIs(t, err, ErrMissingParameter) - require.ErrorContains(t, err, `"@method";req, "@authority"`) - }, - }, - "expected created parameter is missing": { - params: httpsfv.InnerList{Params: httpsfv.NewParams()}, - exp: expectations{reqCreatedTS: &trueVal, reqExpiresTS: &falseVal}, - assert: func(t *testing.T, err error) { - t.Helper() - - require.Error(t, err) - require.ErrorIs(t, err, ErrMissingParameter) - require.ErrorContains(t, err, `created parameter`) - }, - }, - "expected expires parameter is missing": { - params: httpsfv.InnerList{Params: httpsfv.NewParams()}, - exp: expectations{reqCreatedTS: &falseVal, reqExpiresTS: &trueVal}, - assert: func(t *testing.T, err error) { - t.Helper() - - require.Error(t, err) - require.ErrorIs(t, err, ErrMissingParameter) - require.ErrorContains(t, err, `expires parameter`) - }, - }, - "successful assertion with all possible parameters": { - params: httpsfv.InnerList{ - Params: func() *httpsfv.Params { - params := httpsfv.NewParams() - params.Add(string(Created), now.Add(-3*time.Second).Unix()) - params.Add(string(Expires), now.Add(3*time.Second).Unix()) - params.Add(string(Alg), string(EcdsaP256Sha256)) - params.Add(string(KeyID), "test") - params.Add(string(Nonce), "foo") - params.Add(string(Tag), "test") - - return params - }(), - Items: []httpsfv.Item{ - httpsfv.NewItem("@method"), - httpsfv.NewItem("@authority"), - }, - }, - exp: func() expectations { - ids, err := toComponentIdentifiers([]string{"@authority", "@method"}) - require.NoError(t, err) - - return expectations{ - identifiers: ids, - maxAge: 5 * time.Second, - } - }(), - assert: func(t *testing.T, err error) { - t.Helper() - - require.NoError(t, err) - }, - }, - } { - t.Run(uc, func(t *testing.T) { - msg := &Message{Context: context.TODO()} - - si, err := parseSignatureInput(tc.params) - require.NoError(t, err) - - err = tc.exp.assertMetadata(si, msg) - - tc.assert(t, err) - }) - } -} - -func TestExpectationsAssertKeyAlgorithm(t *testing.T) { - for uc, tc := range map[string]struct { - parameterAlg SignatureAlgorithm - keyAlg SignatureAlgorithm - assert func(t *testing.T, err error) - }{ - "signature algorithm mismatch": { - parameterAlg: RsaPssSha512, - keyAlg: EcdsaP256Sha256, - assert: func(t *testing.T, err error) { - t.Helper() - - require.ErrorIs(t, err, ErrParameter) - require.ErrorContains(t, err, "key algorithm rsa-pss-sha512 does not match signature algorithm ecdsa-p256-sha256") - }, - }, - "signature algorithm matches": { - parameterAlg: RsaPssSha512, - keyAlg: RsaPssSha512, - assert: func(t *testing.T, err error) { - t.Helper() - - require.NoError(t, err) - }, - }, - "signature algorithm absent": { - keyAlg: EcdsaP256Sha256, - assert: func(t *testing.T, err error) { - t.Helper() - - require.NoError(t, err) - }, - }, - } { - t.Run(uc, func(t *testing.T) { - params := httpsfv.NewParams() - if tc.parameterAlg != "" { - params.Add(string(Alg), string(tc.parameterAlg)) - } - - si, err := parseSignatureInput(httpsfv.InnerList{Params: params}) - require.NoError(t, err) - - exp := &expectations{} - err = exp.assertKeyAlgorithm(si, tc.keyAlg) - - tc.assert(t, err) - }) - } -} - func TestNewVerifier(t *testing.T) { t.Parallel() @@ -416,6 +137,19 @@ func TestNewVerifier(t *testing.T) { require.ErrorContains(t, err, "verification and negotiation") }, }, + "global parameter conflict with validation of all signatures": { + resolver: &KeyResolverMock{}, + opts: []VerifierOption{ + WithValidateAllSignatures(), + WithForbiddenParameters("created"), + }, + assert: func(t *testing.T, err error, _ *verifier) { + t.Helper() + + require.ErrorIs(t, err, ErrVerifierCreation) + require.ErrorIs(t, err, ErrParameter) + }, + }, "with verification of all signatures enabled": { resolver: &KeyResolverMock{}, opts: []VerifierOption{ @@ -426,8 +160,8 @@ func TestNewVerifier(t *testing.T) { require.NoError(t, err) assert.True(t, v.validateAllSigs) - assert.Len(t, v.tagExpectations, 1) - assert.Contains(t, v.tagExpectations, "") + assert.Len(t, v.tagPolicies, 1) + assert.Contains(t, v.tagPolicies, "") assert.IsType(t, &KeyResolverMock{}, v.keyResolver) }, }, @@ -445,11 +179,11 @@ func TestNewVerifier(t *testing.T) { require.NoError(t, err) assert.False(t, v.validateAllSigs) assert.IsType(t, &KeyResolverMock{}, v.keyResolver) - assert.Len(t, v.tagExpectations, 1) - assert.NotContains(t, v.tagExpectations, "") - require.Contains(t, v.tagExpectations, "test") + assert.Len(t, v.tagPolicies, 1) + assert.NotContains(t, v.tagPolicies, "") + require.Contains(t, v.tagPolicies, "test") - exp := v.tagExpectations["test"] + exp := v.tagPolicies["test"] assert.Len(t, exp.identifiers, 1) assert.Equal(t, "@status", exp.identifiers[0].Value) assert.Equal(t, 1*time.Second, exp.tolerance) @@ -468,11 +202,11 @@ func TestNewVerifier(t *testing.T) { require.NoError(t, err) assert.False(t, v.validateAllSigs) assert.IsType(t, &KeyResolverMock{}, v.keyResolver) - assert.Len(t, v.tagExpectations, 1) - assert.NotContains(t, v.tagExpectations, "") - require.Contains(t, v.tagExpectations, "test") + assert.Len(t, v.tagPolicies, 1) + assert.NotContains(t, v.tagPolicies, "") + require.Contains(t, v.tagPolicies, "test") - exp := v.tagExpectations["test"] + exp := v.tagPolicies["test"] assert.Len(t, exp.identifiers, 1) assert.Equal(t, "@status", exp.identifiers[0].Value) assert.Equal(t, 1*time.Second, exp.tolerance) @@ -496,11 +230,11 @@ func TestNewVerifier(t *testing.T) { require.NoError(t, err) assert.False(t, v.validateAllSigs) assert.IsType(t, &KeyResolverMock{}, v.keyResolver) - assert.Len(t, v.tagExpectations, 1) - assert.NotContains(t, v.tagExpectations, "") - require.Contains(t, v.tagExpectations, "test") + assert.Len(t, v.tagPolicies, 1) + assert.NotContains(t, v.tagPolicies, "") + require.Contains(t, v.tagPolicies, "test") - exp := v.tagExpectations["test"] + exp := v.tagPolicies["test"] assert.Len(t, exp.identifiers, 2) assert.Equal(t, "@status", exp.identifiers[0].Value) assert.Equal(t, "content-digest", exp.identifiers[1].Value) @@ -535,21 +269,152 @@ func TestNewVerifier(t *testing.T) { require.NoError(t, err) assert.True(t, v.validateAllSigs) assert.IsType(t, &KeyResolverMock{}, v.keyResolver) - assert.Len(t, v.tagExpectations, 2) + assert.Len(t, v.tagPolicies, 2) - require.Contains(t, v.tagExpectations, "") - exp := v.tagExpectations[""] + require.Contains(t, v.tagPolicies, "") + exp := v.tagPolicies[""] assert.Len(t, exp.identifiers, 1) assert.Equal(t, "@method", exp.identifiers[0].Value) assert.Equal(t, 1*time.Minute, exp.tolerance) - require.Contains(t, v.tagExpectations, "test") - exp = v.tagExpectations["test"] + require.Contains(t, v.tagPolicies, "test") + exp = v.tagPolicies["test"] assert.Len(t, exp.identifiers, 1) assert.Equal(t, "@status", exp.identifiers[0].Value) assert.Equal(t, 1*time.Second, exp.tolerance) }, }, + "parameter rules inherited from global configuration": { + resolver: &KeyResolverMock{}, + opts: []VerifierOption{ + WithRequiredTag("profile", WithRequiredParameters("nonce"), WithParameter("audience", "service-a")), + WithForbiddenParameters("alg", "keyid"), + }, + assert: func(t *testing.T, err error, v *verifier) { + t.Helper() + + require.NoError(t, err) + + exp := v.tagPolicies["profile"] + assert.Equal(t, []string{"nonce"}, exp.requiredParameters) + assert.Equal(t, []string{"alg", "keyid"}, exp.forbiddenParameters) + assert.Equal(t, []parameterOption{{name: "audience", value: "service-a"}}, exp.expectedParameters) + }, + }, + "identical global and tag-specific expectations are compatible": { + resolver: &KeyResolverMock{}, + opts: []VerifierOption{ + WithParameter("audience", "service-a"), + WithRequiredTag("profile", WithParameter("audience", "service-a"), WithRequiredParameters("audience")), + }, + assert: func(t *testing.T, err error, v *verifier) { + t.Helper() + + require.NoError(t, err) + assert.Len(t, v.tagPolicies["profile"].expectedParameters, 1) + }, + }, + "global and tag-specific parameter conflict": { + resolver: &KeyResolverMock{}, + opts: []VerifierOption{ + WithRequiredTag("profile", WithRequiredParameters("nonce")), + WithForbiddenParameters("nonce"), + }, + assert: func(t *testing.T, err error, _ *verifier) { + t.Helper() + + require.ErrorIs(t, err, ErrVerifierCreation) + require.ErrorIs(t, err, ErrParameter) + }, + }, + "conflicting expected values": { + resolver: &KeyResolverMock{}, + opts: []VerifierOption{ + WithRequiredTag("profile", WithParameter("audience", "first")), + WithParameter("audience", "second"), + }, + assert: func(t *testing.T, err error, _ *verifier) { + t.Helper() + + require.ErrorIs(t, err, ErrVerifierCreation) + require.ErrorIs(t, err, ErrParameter) + }, + }, + "required tag cannot be forbidden": { + resolver: &KeyResolverMock{}, + opts: []VerifierOption{ + WithRequiredTag("profile", WithForbiddenParameters("tag")), + }, + assert: func(t *testing.T, err error, _ *verifier) { + t.Helper() + + require.ErrorIs(t, err, ErrVerifierCreation) + require.ErrorIs(t, err, ErrParameter) + }, + }, + "required timestamp cannot be forbidden": { + resolver: &KeyResolverMock{}, + opts: []VerifierOption{ + WithRequiredTag("profile"), + WithForbiddenParameters("created"), + }, + assert: func(t *testing.T, err error, _ *verifier) { + t.Helper() + + require.ErrorIs(t, err, ErrVerifierCreation) + require.ErrorIs(t, err, ErrParameter) + }, + }, + "optional timestamp may be forbidden": { + resolver: &KeyResolverMock{}, + opts: []VerifierOption{ + WithRequiredTag("profile"), + WithForbiddenParameters("created"), + WithCreatedTimestamp(false), + }, + assert: func(t *testing.T, err error, v *verifier) { + t.Helper() + + require.NoError(t, err) + assert.Equal(t, []string{"created"}, v.tagPolicies["profile"].forbiddenParameters) + }, + }, + "invalid parameter name": { + resolver: &KeyResolverMock{}, + opts: []VerifierOption{ + WithRequiredTag("profile", WithRequiredParameters("not a name")), + }, + assert: func(t *testing.T, err error, _ *verifier) { + t.Helper() + + require.ErrorIs(t, err, ErrVerifierCreation) + require.ErrorIs(t, err, ErrParameter) + }, + }, + "unsupported expected standard parameter": { + resolver: &KeyResolverMock{}, + opts: []VerifierOption{ + WithRequiredTag("profile", WithParameter("alg", "ed25519")), + }, + assert: func(t *testing.T, err error, _ *verifier) { + t.Helper() + + require.ErrorIs(t, err, ErrVerifierCreation) + require.ErrorIs(t, err, ErrParameter) + }, + }, + "invalid expected nonce": { + resolver: &KeyResolverMock{}, + opts: []VerifierOption{ + WithRequiredTag("profile", WithParameter("nonce", "")), + }, + assert: func(t *testing.T, err error, _ *verifier) { + t.Helper() + + require.ErrorIs(t, err, ErrVerifierCreation) + require.ErrorIs(t, err, ErrParameter) + }, + }, "duplicate negotiation parameter rejected": { resolver: Key{Algorithm: HmacSha256, Material: []byte("secret")}, opts: []VerifierOption{ @@ -621,6 +486,7 @@ func TestVerifierVerify(t *testing.T) { for _, tc := range []struct { uc string opts []VerifierOption + verifyOpts []VerifyOption msg *Message configureResolver func(t *testing.T, kr *KeyResolverMock) assert func(t *testing.T, err error, results VerificationResult) @@ -828,6 +694,203 @@ func TestVerifierVerify(t *testing.T) { require.Empty(t, results) }, }, + { + uc: "required extension missing before key resolution", + opts: []VerifierOption{ + WithRequiredTag("profile", WithRequiredParameters("nonce")), + WithCreatedTimestamp(false), WithExpiredTimestamp(false), + }, + msg: &Message{Header: http.Header{ + "Signature-Input": {`sig=();tag="profile"`}, + "Signature": {"sig=:dGVzdA==:"}, + }}, + configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, + assert: func(t *testing.T, err error, results VerificationResult) { + t.Helper() + + require.ErrorIs(t, err, ErrVerificationFailed) + require.ErrorIs(t, err, ErrParameter) + require.NotErrorIs(t, err, &NoApplicableSignatureError{}) + require.Empty(t, results) + }, + }, + { + uc: "forbidden parameter rejected before key resolution", + opts: []VerifierOption{ + WithRequiredTag("profile", WithForbiddenParameters("keyid", "alg")), + WithCreatedTimestamp(false), WithExpiredTimestamp(false), + }, + msg: &Message{Header: http.Header{ + "Signature-Input": {`sig=();keyid="key";tag="profile"`}, + "Signature": {"sig=:dGVzdA==:"}, + }}, + configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, + assert: func(t *testing.T, err error, results VerificationResult) { + t.Helper() + + require.ErrorIs(t, err, ErrVerificationFailed) + require.ErrorIs(t, err, ErrParameter) + require.Empty(t, results) + }, + }, + { + uc: "dynamic parameter expectation checked before key resolution", + opts: []VerifierOption{ + WithRequiredTag("profile"), + WithCreatedTimestamp(false), WithExpiredTimestamp(false), + }, + verifyOpts: []VerifyOption{WithParameter("audience", "expected")}, + msg: &Message{Header: http.Header{ + "Signature-Input": {`sig=();tag="profile";audience="other"`}, + "Signature": {"sig=:dGVzdA==:"}, + }}, + configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, + assert: func(t *testing.T, err error, results VerificationResult) { + t.Helper() + + require.ErrorIs(t, err, ErrVerificationFailed) + require.ErrorIs(t, err, ErrParameter) + require.Empty(t, results) + }, + }, + { + uc: "dynamic expectations cannot override static values", + opts: []VerifierOption{ + WithRequiredTag("profile", WithParameter("audience", "static")), + }, + verifyOpts: []VerifyOption{WithParameter("audience", "dynamic")}, + msg: &Message{Header: make(http.Header)}, + configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, + assert: func(t *testing.T, err error, results VerificationResult) { + t.Helper() + + require.ErrorIs(t, err, ErrVerificationFailed) + require.ErrorIs(t, err, ErrParameter) + require.Empty(t, results) + }, + }, + { + uc: "dynamic rules cannot forbid required timestamps", + opts: []VerifierOption{WithRequiredTag("profile")}, + verifyOpts: []VerifyOption{WithForbiddenParameters("created")}, + msg: &Message{Header: make(http.Header)}, + configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, + assert: func(t *testing.T, err error, results VerificationResult) { + t.Helper() + + require.ErrorIs(t, err, ErrVerificationFailed) + require.ErrorIs(t, err, ErrParameter) + require.Empty(t, results) + }, + }, + { + uc: "dynamic audience requested in negotiation", + opts: []VerifierOption{ + WithRequiredTag("profile", WithSignatureNegotiation()), + }, + verifyOpts: []VerifyOption{WithParameter("audience", "service-a")}, + msg: &Message{Header: http.Header{ + "Signature-Input": {`sig=();created=1618884473;expires=1618884600;tag="profile"`}, + "Signature": {"sig=:dGVzdA==:"}, + }}, + configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, + assert: func(t *testing.T, err error, results VerificationResult) { + t.Helper() + + var negotiation *NoApplicableSignatureError + require.ErrorAs(t, err, &negotiation) + require.Empty(t, results) + + hdr := make(http.Header) + negotiation.Negotiate(hdr) + assert.Equal(t, `sig=();created;expires;tag="profile";audience="service-a"`, hdr.Get(headerAcceptSignature)) + }, + }, + { + uc: "static audience requested for missing signature", + opts: []VerifierOption{ + WithParameter("audience", "service-a"), + WithRequiredTag("profile", WithSignatureNegotiation()), + }, + msg: &Message{Header: make(http.Header)}, + configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, + assert: func(t *testing.T, err error, results VerificationResult) { + t.Helper() + + var negotiation *NoApplicableSignatureError + require.ErrorAs(t, err, &negotiation) + require.Empty(t, results) + + hdr := make(http.Header) + negotiation.Negotiate(hdr) + assert.Equal(t, `sig=();created;expires;tag="profile";audience="service-a"`, hdr.Get(headerAcceptSignature)) + }, + }, + { + uc: "expected nonce overrides negotiation getter", + opts: []VerifierOption{ + WithRequiredTag("profile", WithSignatureNegotiation( + WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { + return "getter", errors.New("getter must not be called") + })), + )), + }, + verifyOpts: []VerifyOption{WithParameter("nonce", "expected-nonce")}, + msg: &Message{Header: make(http.Header)}, + configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, + assert: func(t *testing.T, err error, results VerificationResult) { + t.Helper() + + var negotiation *NoApplicableSignatureError + require.ErrorAs(t, err, &negotiation) + require.Empty(t, results) + + hdr := make(http.Header) + negotiation.Negotiate(hdr) + assert.Equal(t, `sig=();created;expires;nonce="expected-nonce";tag="profile"`, hdr.Get(headerAcceptSignature)) + }, + }, + { + uc: "dynamic expectations projected for all required tags", + opts: []VerifierOption{ + WithRequiredTag("first", WithSignatureNegotiation()), + WithRequiredTag("second", WithSignatureNegotiation()), + }, + verifyOpts: []VerifyOption{WithParameter("audience", "service-a")}, + msg: &Message{Header: make(http.Header)}, + configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, + assert: func(t *testing.T, err error, results VerificationResult) { + t.Helper() + + var negotiation *NoApplicableSignatureError + require.ErrorAs(t, err, &negotiation) + require.Empty(t, results) + + hdr := make(http.Header) + negotiation.Negotiate(hdr) + assert.ElementsMatch(t, []string{ + `sig=();created;expires;tag="first";audience="service-a"`, + `sig=();created;expires;tag="second";audience="service-a"`, + }, hdr.Values(headerAcceptSignature)) + }, + }, + { + uc: "conflicting explicit negotiation parameter is rejected", + opts: []VerifierOption{ + WithRequiredTag("profile", WithParameter("audience", "expected"), WithSignatureNegotiation( + WithParameter("audience", "builder"), + )), + }, + msg: &Message{Header: make(http.Header)}, + configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, + assert: func(t *testing.T, err error, results VerificationResult) { + t.Helper() + + require.ErrorIs(t, err, ErrSignatureNegotiationError) + require.ErrorIs(t, err, ErrParameter) + require.Empty(t, results) + }, + }, { uc: "signature algorithm mismatch after key resolution", opts: []VerifierOption{ @@ -966,6 +1029,30 @@ func TestVerifierVerify(t *testing.T) { assert.ElementsMatch(t, hdr.Values("Want-Content-Digest"), []string{"sha-256=1"}) }, }, + { + uc: "global content-digest requirement overridden for negotiated tag", + opts: []VerifierOption{ + WithComponents("content-digest"), + WithSignatureNegotiation(), + WithRequiredTag("foo", WithComponents("@method")), + }, + msg: &Message{Header: http.Header{}}, + configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, + assert: func(t *testing.T, err error, _ VerificationResult) { + t.Helper() + + var negotiation *NoApplicableSignatureError + + require.ErrorIs(t, err, ErrVerificationFailed) + require.ErrorAs(t, err, &negotiation) + + hdr := make(http.Header) + negotiation.Negotiate(hdr) + + assert.Equal(t, `sig=("@method");created;expires;tag="foo"`, hdr.Get(headerAcceptSignature)) + assert.Empty(t, hdr.Values(headerWantContentDigest)) + }, + }, { uc: "signature negotiation without nonce getter omits nonce", opts: []VerifierOption{ @@ -1771,10 +1858,96 @@ func TestVerifierVerify(t *testing.T) { v, err := NewVerifier(kr, tc.opts...) require.NoError(t, err) - results, err := v.Verify(tc.msg) + results, err := v.Verify(tc.msg, tc.verifyOpts...) tc.assert(t, err, results) }) } + + t.Run("signed extensions with static and dynamic requirements", func(t *testing.T) { + key := Key{Algorithm: HmacSha256, Material: []byte("secret")} + inputBytes := []byte("data") + signer, err := NewSigner(key, + WithTag("profile"), + WithComponents("@method"), + WithParameter("audience", "service-a"), + WithParameter("score", 1.2349), + WithParameter("mode", Token("example")), + WithParameter("flag", true), + WithParameter("opaque", inputBytes), + ) + require.NoError(t, err) + + msg := &Message{ + Context: context.Background(), + Header: make(http.Header), + Method: http.MethodGet, + Authority: "example.com", + URL: testURL, + IsRequest: true, + } + _, err = signer.Sign(msg, WithParameter("nonce", "request-nonce")) + require.NoError(t, err) + + ver, err := NewVerifier(key, + WithRequiredTag("profile", + WithComponents("@method"), + WithRequiredParameters("nonce"), + WithForbiddenParameters("keyid", "alg"), + WithParameter("score", 1.2349), + WithParameter("mode", Token("example")), + WithParameter("flag", true), + WithParameter("opaque", inputBytes), + ), + ) + require.NoError(t, err) + + inputBytes[0] = 'X' // Neither signer nor verifier may retain this mutable input. + + for _, opts := range [][]VerifyOption{ + {WithParameter("audience", "service-a")}, + {WithParameter("audience", "service-a"), WithRequiredParameters("mode")}, + nil, + } { + results, err := ver.Verify(msg, opts...) + require.NoError(t, err) + require.Len(t, results, 1) + assert.Equal(t, "service-a", results[0].Parameters["audience"]) + } + + _, err = ver.Verify(msg, WithParameter("audience", "other")) + require.ErrorIs(t, err, ErrParameter) + + results, err := ver.Verify(msg) + require.NoError(t, err) + require.Len(t, results, 1) // A failed per-call override did not mutate the verifier. + + _, err = ver.Verify(msg, WithForbiddenParameters("nonce")) + require.ErrorIs(t, err, ErrParameter) + + // A Structured-Fields Token is not interchangeable with a String. + withString, err := NewVerifier(key, WithRequiredTag("profile", WithParameter("mode", "example"))) + require.NoError(t, err) + _, err = withString.Verify(msg) + require.ErrorIs(t, err, ErrParameter) + + var wg sync.WaitGroup + + errors := make(chan error, 16) + + for range 16 { + wg.Go(func() { + _, err := ver.Verify(msg, WithParameter("audience", "service-a")) + errors <- err + }) + } + + wg.Wait() + close(errors) + + for err := range errors { + require.NoError(t, err) + } + }) } func TestVerifierApplicableSignatures(t *testing.T) { @@ -1794,7 +1967,7 @@ func TestVerifierApplicableSignatures(t *testing.T) { }{ "only required signatures are applicable": { verifier: verifier{ - tagExpectations: map[string]*expectations{"foo": {}}, + tagPolicies: map[string]*verificationPolicy{"foo": {}}, }, refs: map[string]*signatureInput{ "matching": withTag("foo"), @@ -1812,7 +1985,7 @@ func TestVerifierApplicableSignatures(t *testing.T) { }, "no matching signature": { verifier: verifier{ - tagExpectations: map[string]*expectations{"foo": {}}, + tagPolicies: map[string]*verificationPolicy{"foo": {}}, }, refs: map[string]*signatureInput{ "other": withTag("bar"), @@ -1826,7 +1999,7 @@ func TestVerifierApplicableSignatures(t *testing.T) { }, "missing tag": { verifier: verifier{ - tagExpectations: map[string]*expectations{"foo": {}}, + tagPolicies: map[string]*verificationPolicy{"foo": {}}, }, refs: map[string]*signatureInput{ "untagged": newSignatureInput(nil, nil), @@ -1860,7 +2033,7 @@ func TestVerifierApplicableSignatures(t *testing.T) { "validate all with required tag": { verifier: verifier{ validateAllSigs: true, - tagExpectations: map[string]*expectations{"foo": {}}, + tagPolicies: map[string]*verificationPolicy{"foo": {}}, }, refs: map[string]*signatureInput{ "matching": withTag("foo"), From 07c8ef89b8d78467a3ee15abb3d80273d7901ebe Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Wed, 4 Nov 2026 07:58:14 +0100 Subject: [PATCH 21/33] WithExpiredTimestamp renamed to WithExpiresTimestamp --- accept_signature_builder_test.go | 2 +- options.go | 4 ++-- options_test.go | 8 +++---- verifier_test.go | 38 ++++++++++++++++---------------- 4 files changed, 26 insertions(+), 26 deletions(-) diff --git a/accept_signature_builder_test.go b/accept_signature_builder_test.go index 5527bd3..4527942 100644 --- a/accept_signature_builder_test.go +++ b/accept_signature_builder_test.go @@ -51,7 +51,7 @@ func TestNewAcceptedSignature(t *testing.T) { WithContentDigestAlgorithmPreferences(AlgorithmPreference{Sha512, 10}), WithTag("bar"), WithCreatedTimestamp(false), - WithExpiredTimestamp(false), + WithExpiresTimestamp(false), WithParameter("audience", "service-a"), }, assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) { diff --git a/options.go b/options.go index 60dd4bb..04d8005 100644 --- a/options.go +++ b/options.go @@ -450,10 +450,10 @@ func (o createdTimestampOption) applyAcceptSignatureOption(asb *AcceptSignatureB return nil } -// WithExpiredTimestamp specifies whether the expires parameter is required +// WithExpiresTimestamp specifies whether the expires parameter is required // during verification or requested in Accept-Signature. False makes it // optional during verification and omits it from Accept-Signature. -func WithExpiredTimestamp(flag bool) expiredTimestampOption { +func WithExpiresTimestamp(flag bool) expiredTimestampOption { return expiredTimestampOption(flag) } diff --git a/options_test.go b/options_test.go index a53fb56..06e9683 100644 --- a/options_test.go +++ b/options_test.go @@ -822,7 +822,7 @@ func TestWithCreatedTimestampForAcceptSignature(t *testing.T) { } } -func TestWithExpiredTimestampForVerifier(t *testing.T) { +func TestWithExpiresTimestampForVerifier(t *testing.T) { t.Parallel() for uc, required := range map[string]bool{ @@ -832,7 +832,7 @@ func TestWithExpiredTimestampForVerifier(t *testing.T) { t.Run(uc, func(t *testing.T) { exp := &verificationPolicy{} - err := WithExpiredTimestamp(required).applyVerifierOption(&verifier{}, exp, false) + err := WithExpiresTimestamp(required).applyVerifierOption(&verifier{}, exp, false) require.NoError(t, err) require.NotNil(t, exp.reqExpiresTS) @@ -841,7 +841,7 @@ func TestWithExpiredTimestampForVerifier(t *testing.T) { } } -func TestWithExpiredTimestampForAcceptSignature(t *testing.T) { +func TestWithExpiresTimestampForAcceptSignature(t *testing.T) { t.Parallel() for uc, requested := range map[string]bool{ @@ -851,7 +851,7 @@ func TestWithExpiredTimestampForAcceptSignature(t *testing.T) { t.Run(uc, func(t *testing.T) { asb := &AcceptSignatureBuilder{addExpiresTS: !requested} - err := WithExpiredTimestamp(requested).applyAcceptSignatureOption(asb) + err := WithExpiresTimestamp(requested).applyAcceptSignatureOption(asb) require.NoError(t, err) assert.Equal(t, requested, asb.addExpiresTS) diff --git a/verifier_test.go b/verifier_test.go index 5307781..963c1d4 100644 --- a/verifier_test.go +++ b/verifier_test.go @@ -605,7 +605,7 @@ func TestVerifierVerify(t *testing.T) { opts: []VerifierOption{ WithValidateAllSignatures(), WithCreatedTimestamp(false), - WithExpiredTimestamp(false), + WithExpiresTimestamp(false), }, msg: &Message{ Header: http.Header{ @@ -625,7 +625,7 @@ func TestVerifierVerify(t *testing.T) { }, { uc: "key resolver error", - opts: []VerifierOption{WithValidateAllSignatures(), WithExpiredTimestamp(false)}, + opts: []VerifierOption{WithValidateAllSignatures(), WithExpiresTimestamp(false)}, msg: &Message{ Header: http.Header{ "Signature-Input": []string{`sig=();created=1618884473;keyid="test"`}, @@ -676,7 +676,7 @@ func TestVerifierVerify(t *testing.T) { opts: []VerifierOption{ WithRequiredTag("foo", WithComponents("@method")), WithCreatedTimestamp(false), - WithExpiredTimestamp(false), + WithExpiresTimestamp(false), }, msg: &Message{ Header: http.Header{ @@ -698,7 +698,7 @@ func TestVerifierVerify(t *testing.T) { uc: "required extension missing before key resolution", opts: []VerifierOption{ WithRequiredTag("profile", WithRequiredParameters("nonce")), - WithCreatedTimestamp(false), WithExpiredTimestamp(false), + WithCreatedTimestamp(false), WithExpiresTimestamp(false), }, msg: &Message{Header: http.Header{ "Signature-Input": {`sig=();tag="profile"`}, @@ -718,7 +718,7 @@ func TestVerifierVerify(t *testing.T) { uc: "forbidden parameter rejected before key resolution", opts: []VerifierOption{ WithRequiredTag("profile", WithForbiddenParameters("keyid", "alg")), - WithCreatedTimestamp(false), WithExpiredTimestamp(false), + WithCreatedTimestamp(false), WithExpiresTimestamp(false), }, msg: &Message{Header: http.Header{ "Signature-Input": {`sig=();keyid="key";tag="profile"`}, @@ -737,7 +737,7 @@ func TestVerifierVerify(t *testing.T) { uc: "dynamic parameter expectation checked before key resolution", opts: []VerifierOption{ WithRequiredTag("profile"), - WithCreatedTimestamp(false), WithExpiredTimestamp(false), + WithCreatedTimestamp(false), WithExpiresTimestamp(false), }, verifyOpts: []VerifyOption{WithParameter("audience", "expected")}, msg: &Message{Header: http.Header{ @@ -896,7 +896,7 @@ func TestVerifierVerify(t *testing.T) { opts: []VerifierOption{ WithValidateAllSignatures(), WithCreatedTimestamp(false), - WithExpiredTimestamp(false), + WithExpiresTimestamp(false), }, msg: &Message{ Header: http.Header{ @@ -924,7 +924,7 @@ func TestVerifierVerify(t *testing.T) { uc: "unsupported signature key", opts: []VerifierOption{ WithRequiredTag("foo"), - WithExpiredTimestamp(false), + WithExpiresTimestamp(false), WithCreatedTimestamp(false), }, msg: &Message{ @@ -958,7 +958,7 @@ func TestVerifierVerify(t *testing.T) { uc: "invalid signature", opts: []VerifierOption{ WithRequiredTag("foo"), - WithExpiredTimestamp(false), + WithExpiresTimestamp(false), WithCreatedTimestamp(false), }, msg: &Message{ @@ -1147,7 +1147,7 @@ func TestVerifierVerify(t *testing.T) { opts: []VerifierOption{ WithValidateAllSignatures(), WithCreatedTimestamp(false), - WithExpiredTimestamp(false), + WithExpiresTimestamp(false), }, msg: &Message{ Method: http.MethodPost, @@ -1182,7 +1182,7 @@ func TestVerifierVerify(t *testing.T) { opts: []VerifierOption{ WithValidateAllSignatures(), WithCreatedTimestamp(false), - WithExpiredTimestamp(false), + WithExpiresTimestamp(false), }, msg: &Message{ Method: http.MethodPost, @@ -1246,7 +1246,7 @@ func TestVerifierVerify(t *testing.T) { opts: []VerifierOption{ WithValidateAllSignatures(), WithCreatedTimestamp(false), - WithExpiredTimestamp(false), + WithExpiresTimestamp(false), }, msg: &Message{ Method: http.MethodPost, @@ -1317,7 +1317,7 @@ func TestVerifierVerify(t *testing.T) { opts: []VerifierOption{ WithValidateAllSignatures(), WithCreatedTimestamp(false), - WithExpiredTimestamp(false), + WithExpiresTimestamp(false), }, msg: &Message{ Method: http.MethodPost, @@ -1397,7 +1397,7 @@ func TestVerifierVerify(t *testing.T) { opts: []VerifierOption{ WithValidateAllSignatures(), WithCreatedTimestamp(false), - WithExpiredTimestamp(false), + WithExpiresTimestamp(false), }, msg: &Message{ Method: http.MethodPost, @@ -1467,7 +1467,7 @@ func TestVerifierVerify(t *testing.T) { opts: []VerifierOption{ WithValidateAllSignatures(), WithCreatedTimestamp(false), - WithExpiredTimestamp(false), + WithExpiresTimestamp(false), }, msg: &Message{ Method: http.MethodPost, @@ -1533,7 +1533,7 @@ func TestVerifierVerify(t *testing.T) { opts: []VerifierOption{ WithValidateAllSignatures(), WithCreatedTimestamp(false), - WithExpiredTimestamp(false), + WithExpiresTimestamp(false), }, msg: &Message{ Method: http.MethodPost, @@ -1604,7 +1604,7 @@ func TestVerifierVerify(t *testing.T) { uc: "invalid untagged signature is ignored", opts: []VerifierOption{ WithRequiredTag("foo"), - WithExpiredTimestamp(false), + WithExpiresTimestamp(false), }, msg: &Message{ Header: http.Header{ @@ -1654,7 +1654,7 @@ func TestVerifierVerify(t *testing.T) { uc: "invalid untagged signature fails when validating all", opts: []VerifierOption{ WithValidateAllSignatures(), - WithExpiredTimestamp(false), + WithExpiresTimestamp(false), }, msg: &Message{ Header: http.Header{ @@ -1692,7 +1692,7 @@ func TestVerifierVerify(t *testing.T) { uc: "multiple valid signatures with different keys and metadata", opts: []VerifierOption{ WithValidateAllSignatures(), - WithExpiredTimestamp(false), + WithExpiresTimestamp(false), }, msg: &Message{ Method: http.MethodPost, From 1211e6088234de322dd1f55cd031503ed236501a Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Wed, 4 Nov 2026 08:38:02 +0100 Subject: [PATCH 22/33] nil pointer fix for signature parameters --- signature_input.go | 6 +++--- signature_input_test.go | 36 ++++++++++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+), 3 deletions(-) diff --git a/signature_input.go b/signature_input.go index dff609f..0cf63f3 100644 --- a/signature_input.go +++ b/signature_input.go @@ -47,12 +47,12 @@ func (si *signatureInput) hasIdentifier(id *componentIdentifier) bool { } func (si *signatureInput) parameters() SignatureParameters { - result := make(SignatureParameters, len(si.value.Params.Names())) - if si.value.Params == nil { - return result + return SignatureParameters{} } + result := make(SignatureParameters, len(si.value.Params.Names())) + for _, name := range si.value.Params.Names() { value, _ := si.value.Params.Get(name) diff --git a/signature_input_test.go b/signature_input_test.go index fcbf896..da98022 100644 --- a/signature_input_test.go +++ b/signature_input_test.go @@ -327,6 +327,42 @@ func TestValidateSignatureInputParameters(t *testing.T) { } } +func TestSignatureInputParameters(t *testing.T) { + t.Parallel() + + for uc, tc := range map[string]struct { + params *httpsfv.Params + want SignatureParameters + }{ + "nil parameters": { + want: SignatureParameters{}, + }, + "empty parameters": { + params: httpsfv.NewParams(), + want: SignatureParameters{}, + }, + "with parameters": { + params: func() *httpsfv.Params { + params := httpsfv.NewParams() + params.Add(string(Created), int64(1577836800)) + params.Add("example", httpsfv.Token("hello")) + + return params + }(), + want: SignatureParameters{ + string(Created): int64(1577836800), + "example": Token("hello"), + }, + }, + } { + t.Run(uc, func(t *testing.T) { + input := &signatureInput{value: httpsfv.InnerList{Params: tc.params}} + + assert.Equal(t, tc.want, input.parameters()) + }) + } +} + func TestSignatureInputParameter(t *testing.T) { t.Parallel() From b287809d97532ec84df376f3d076f0a9cf3fe064 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Wed, 4 Nov 2026 08:42:10 +0100 Subject: [PATCH 23/33] avoid panic on malformed Signature in addSignature --- message.go | 4 ++++ message_test.go | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) diff --git a/message.go b/message.go index af841b2..8536ec4 100644 --- a/message.go +++ b/message.go @@ -208,6 +208,10 @@ func (m *Message) addSignature(label string, signature []byte, signatureInput ht signatureHeaderDict = httpsfv.NewDictionary() } + if err != nil { + return nil, err + } + if inputHeader := m.Header.Values(headerSignatureInput); len(inputHeader) != 0 { inputHeaderDict, err = httpsfv.UnmarshalDictionary(inputHeader) } else { diff --git a/message_test.go b/message_test.go index 44ee571..8022905 100644 --- a/message_test.go +++ b/message_test.go @@ -61,6 +61,38 @@ func TestCreateUniqueLabel(t *testing.T) { } } +func TestMessageAddSignature(t *testing.T) { + t.Parallel() + + for uc, tc := range map[string]struct { + signature string + signatureInput string + }{ + "malformed Signature with valid Signature-Input": { + signature: "not a dictionary", + signatureInput: "previous=()", + }, + "valid Signature with malformed Signature-Input": { + signature: "previous=:c2ln:", + signatureInput: "not a dictionary", + }, + } { + t.Run(uc, func(t *testing.T) { + header := make(http.Header) + header.Set(headerSignature, tc.signature) + header.Set(headerSignatureInput, tc.signatureInput) + msg := &Message{Header: header} + original := header.Clone() + + result, err := msg.addSignature("new", []byte("signature"), httpsfv.InnerList{}) + + require.Error(t, err) + assert.Nil(t, result) + assert.Equal(t, original, msg.Header) + }) + } +} + func TestMessageFromRequest(t *testing.T) { t.Parallel() From bc528571874cf1b0edb7d061e69a8e84139c9a46 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Wed, 4 Nov 2026 08:53:32 +0100 Subject: [PATCH 24/33] better test coverage for signatureInput.parameters --- signature_input_test.go | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/signature_input_test.go b/signature_input_test.go index da98022..09827fa 100644 --- a/signature_input_test.go +++ b/signature_input_test.go @@ -341,17 +341,19 @@ func TestSignatureInputParameters(t *testing.T) { params: httpsfv.NewParams(), want: SignatureParameters{}, }, - "with parameters": { + "with multiple parameters": { params: func() *httpsfv.Params { params := httpsfv.NewParams() params.Add(string(Created), int64(1577836800)) - params.Add("example", httpsfv.Token("hello")) + params.Add("foo", httpsfv.Token("hello")) + params.Add("bar", httpsfv.DisplayString("hello")) return params }(), want: SignatureParameters{ string(Created): int64(1577836800), - "example": Token("hello"), + "foo": Token("hello"), + "bar": "hello", }, }, } { From f7ea9806351e77cc2d4c48d2cef696da4d461196 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Wed, 4 Nov 2026 09:08:13 +0100 Subject: [PATCH 25/33] better test coverage for message.addSignature --- message_test.go | 212 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 196 insertions(+), 16 deletions(-) diff --git a/message_test.go b/message_test.go index 8022905..0dcab1e 100644 --- a/message_test.go +++ b/message_test.go @@ -65,30 +65,210 @@ func TestMessageAddSignature(t *testing.T) { t.Parallel() for uc, tc := range map[string]struct { - signature string - signatureInput string + label string + message *Message + signatureInput httpsfv.InnerList + assert func(t *testing.T, msg *Message, header http.Header, err error) }{ + "without existing signatures": { + label: "new", + message: &Message{Header: make(http.Header)}, + signatureInput: httpsfv.InnerList{ + Items: []httpsfv.Item{httpsfv.NewItem("@method")}, + Params: httpsfv.NewParams(), + }, + assert: func(t *testing.T, msg *Message, header http.Header, err error) { + t.Helper() + + require.NoError(t, err) + assert.Equal(t, http.Header{ + headerSignature: {`new=:c2lnbmF0dXJl:`}, + headerSignatureInput: {`new=("@method")`}, + }, header) + assert.Equal(t, header, msg.Header) + }, + }, + "with existing signatures": { + label: "new", + message: &Message{Header: http.Header{ + headerSignature: {`previous=:c2ln:`}, + headerSignatureInput: {`previous=("@path")`}, + "X-Test": {"value"}, + }}, + signatureInput: httpsfv.InnerList{ + Items: []httpsfv.Item{httpsfv.NewItem("@method")}, + Params: httpsfv.NewParams(), + }, + assert: func(t *testing.T, msg *Message, header http.Header, err error) { + t.Helper() + + require.NoError(t, err) + assert.Equal(t, http.Header{ + headerSignature: {`previous=:c2ln:, new=:c2lnbmF0dXJl:`}, + headerSignatureInput: {`previous=("@path"), new=("@method")`}, + "X-Test": {"value"}, + }, header) + assert.Equal(t, header, msg.Header) + }, + }, + "with Signature only": { + label: "new", + message: &Message{Header: http.Header{ + headerSignature: {`previous=:c2ln:`}, + }}, + signatureInput: httpsfv.InnerList{ + Items: []httpsfv.Item{httpsfv.NewItem("@method")}, + Params: httpsfv.NewParams(), + }, + assert: func(t *testing.T, msg *Message, header http.Header, err error) { + t.Helper() + + require.NoError(t, err) + assert.Equal(t, http.Header{ + headerSignature: {`previous=:c2ln:, new=:c2lnbmF0dXJl:`}, + headerSignatureInput: {`new=("@method")`}, + }, header) + assert.Equal(t, header, msg.Header) + }, + }, + "with Signature-Input only": { + label: "new", + message: &Message{Header: http.Header{ + headerSignatureInput: {`previous=("@path")`}, + }}, + signatureInput: httpsfv.InnerList{ + Items: []httpsfv.Item{httpsfv.NewItem("@method")}, + Params: httpsfv.NewParams(), + }, + assert: func(t *testing.T, msg *Message, header http.Header, err error) { + t.Helper() + + require.NoError(t, err) + assert.Equal(t, http.Header{ + headerSignature: {`new=:c2lnbmF0dXJl:`}, + headerSignatureInput: {`previous=("@path"), new=("@method")`}, + }, header) + assert.Equal(t, header, msg.Header) + }, + }, + "with duplicate label": { + label: "new", + message: &Message{Header: http.Header{ + headerSignature: {`new=:c2ln:`}, + headerSignatureInput: {`new=("@path")`}, + }}, + signatureInput: httpsfv.InnerList{ + Items: []httpsfv.Item{httpsfv.NewItem("@method")}, + Params: httpsfv.NewParams(), + }, + assert: func(t *testing.T, msg *Message, header http.Header, err error) { + t.Helper() + + require.NoError(t, err) + assert.Equal(t, http.Header{ + headerSignature: {`new=:c2ln:, new1=:c2lnbmF0dXJl:`}, + headerSignatureInput: {`new=("@path"), new1=("@method")`}, + }, header) + assert.Equal(t, header, msg.Header) + }, + }, + "with multiple duplicate labels": { + label: "new", + message: &Message{Header: http.Header{ + headerSignature: {`new=:c2ln:, new1=:c2ln:`}, + headerSignatureInput: {`new=("@path"), new1=("@query")`}, + }}, + signatureInput: httpsfv.InnerList{ + Items: []httpsfv.Item{httpsfv.NewItem("@method")}, + Params: httpsfv.NewParams(), + }, + assert: func(t *testing.T, msg *Message, header http.Header, err error) { + t.Helper() + + require.NoError(t, err) + assert.Equal(t, http.Header{ + headerSignature: {`new=:c2ln:, new1=:c2ln:, new2=:c2lnbmF0dXJl:`}, + headerSignatureInput: {`new=("@path"), new1=("@query"), new2=("@method")`}, + }, header) + assert.Equal(t, header, msg.Header) + }, + }, "malformed Signature with valid Signature-Input": { - signature: "not a dictionary", - signatureInput: "previous=()", + label: "new", + message: &Message{Header: http.Header{ + headerSignature: {"not a dictionary"}, + headerSignatureInput: {"previous=()"}, + }}, + signatureInput: httpsfv.InnerList{ + Items: []httpsfv.Item{httpsfv.NewItem("@method")}, + Params: httpsfv.NewParams(), + }, + assert: func(t *testing.T, msg *Message, header http.Header, err error) { + t.Helper() + + require.Error(t, err) + assert.Nil(t, header) + assert.Equal(t, http.Header{ + headerSignature: {"not a dictionary"}, + headerSignatureInput: {"previous=()"}, + }, msg.Header) + }, }, "valid Signature with malformed Signature-Input": { - signature: "previous=:c2ln:", - signatureInput: "not a dictionary", + label: "new", + message: &Message{Header: http.Header{ + headerSignature: {"previous=:c2ln:"}, + headerSignatureInput: {"not a dictionary"}, + }}, + signatureInput: httpsfv.InnerList{ + Items: []httpsfv.Item{httpsfv.NewItem("@method")}, + Params: httpsfv.NewParams(), + }, + assert: func(t *testing.T, msg *Message, header http.Header, err error) { + t.Helper() + + require.Error(t, err) + assert.Nil(t, header) + assert.Equal(t, http.Header{ + headerSignature: {"previous=:c2ln:"}, + headerSignatureInput: {"not a dictionary"}, + }, msg.Header) + }, + }, + "invalid label": { + label: "Invalid", + message: &Message{Header: make(http.Header)}, + signatureInput: httpsfv.InnerList{ + Items: []httpsfv.Item{httpsfv.NewItem("@method")}, + Params: httpsfv.NewParams(), + }, + assert: func(t *testing.T, msg *Message, header http.Header, err error) { + t.Helper() + + require.Error(t, err) + assert.Nil(t, header) + assert.Empty(t, msg.Header) + }, + }, + "invalid signature input": { + label: "new", + message: &Message{Header: make(http.Header)}, + signatureInput: httpsfv.InnerList{ + Items: []httpsfv.Item{httpsfv.NewItem("@method")}, + }, + assert: func(t *testing.T, msg *Message, header http.Header, err error) { + t.Helper() + + require.Error(t, err) + assert.Nil(t, header) + assert.Empty(t, msg.Header) + }, }, } { t.Run(uc, func(t *testing.T) { - header := make(http.Header) - header.Set(headerSignature, tc.signature) - header.Set(headerSignatureInput, tc.signatureInput) - msg := &Message{Header: header} - original := header.Clone() - - result, err := msg.addSignature("new", []byte("signature"), httpsfv.InnerList{}) + header, err := tc.message.addSignature(tc.label, []byte("signature"), tc.signatureInput) - require.Error(t, err) - assert.Nil(t, result) - assert.Equal(t, original, msg.Header) + tc.assert(t, tc.message, header, err) }) } } From 68f8f8d9181aa50af966f6376d17603b738bf3b3 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Wed, 4 Nov 2026 09:11:22 +0100 Subject: [PATCH 26/33] small test restructuring --- message_test.go | 53 ++++++++++++++++++------------------------------- 1 file changed, 19 insertions(+), 34 deletions(-) diff --git a/message_test.go b/message_test.go index 0dcab1e..e476a41 100644 --- a/message_test.go +++ b/message_test.go @@ -17,20 +17,17 @@ import ( func TestCreateUniqueLabel(t *testing.T) { t.Parallel() - for _, tc := range []struct { - uc string + for uc, tc := range map[string]struct { label string dict *httpsfv.Dictionary expectedLabel string }{ - { - uc: "given label not already taken", + "given label not already taken": { label: "foo", dict: httpsfv.NewDictionary(), expectedLabel: "foo", }, - { - uc: "given label already taken #1", + "given label already taken #1": { label: "foo", dict: func() *httpsfv.Dictionary { dict := httpsfv.NewDictionary() @@ -40,8 +37,7 @@ func TestCreateUniqueLabel(t *testing.T) { }(), expectedLabel: "foo1", }, - { - uc: "given label already taken #2", + "given label already taken #2": { label: "foo", dict: func() *httpsfv.Dictionary { dict := httpsfv.NewDictionary() @@ -53,7 +49,7 @@ func TestCreateUniqueLabel(t *testing.T) { expectedLabel: "foo2", }, } { - t.Run(tc.uc, func(t *testing.T) { + t.Run(uc, func(t *testing.T) { label := createUniqueLabel(tc.label, tc.dict) assert.Equal(t, tc.expectedLabel, label) @@ -279,13 +275,11 @@ func TestMessageFromRequest(t *testing.T) { expURL, err := url.Parse("http://example.com?foo=bar") require.NoError(t, err) - for _, tc := range []struct { - uc string + for uc, tc := range map[string]struct { req *http.Request assert func(t *testing.T, msg *Message) }{ - { - uc: "outbound request without body", + "outbound request without body": { req: func() *http.Request { req, err := http.NewRequestWithContext( t.Context(), @@ -330,8 +324,7 @@ func TestMessageFromRequest(t *testing.T) { assert.Empty(t, data1) }, }, - { - uc: "inbound request without body", + "inbound request without body": { req: func() *http.Request { req := httptest.NewRequestWithContext( t.Context(), @@ -374,8 +367,7 @@ func TestMessageFromRequest(t *testing.T) { assert.Empty(t, data1) }, }, - { - uc: "outbound request with body", + "outbound request with body": { req: func() *http.Request { req, err := http.NewRequestWithContext( t.Context(), @@ -420,8 +412,7 @@ func TestMessageFromRequest(t *testing.T) { assert.JSONEq(t, `{"hello": "world"}`, string(data1)) }, }, - { - uc: "inbound request with body", + "inbound request with body": { req: func() *http.Request { req := httptest.NewRequestWithContext( t.Context(), @@ -463,7 +454,7 @@ func TestMessageFromRequest(t *testing.T) { }, }, } { - t.Run(tc.uc, func(t *testing.T) { + t.Run(uc, func(t *testing.T) { msg := MessageFromRequest(tc.req) tc.assert(t, msg) @@ -494,13 +485,11 @@ Content-Length: 23 expURL, err := url.Parse("http://example.com?foo=bar") require.NoError(t, err) - for _, tc := range []struct { - uc string + for uc, tc := range map[string]struct { resp *http.Response assert func(t *testing.T, msg *Message) }{ - { - uc: "response without body", + "response without body": { resp: func() *http.Response { req, err := http.NewRequestWithContext( t.Context(), @@ -563,8 +552,7 @@ Content-Length: 23 assert.Empty(t, data1) }, }, - { - uc: "response with body", + "response with body": { resp: func() *http.Response { req, err := http.NewRequestWithContext( t.Context(), @@ -628,7 +616,7 @@ Content-Length: 23 }, }, } { - t.Run(tc.uc, func(t *testing.T) { + t.Run(uc, func(t *testing.T) { msg := MessageFromResponse(tc.resp) tc.assert(t, msg) @@ -642,15 +630,13 @@ func TestMessageForResponse(t *testing.T) { expURL, err := url.Parse("http://example.com?foo=bar") require.NoError(t, err) - for _, tc := range []struct { - uc string + for uc, tc := range map[string]struct { req *http.Request respHeader http.Header respBody []byte assert func(t *testing.T, msg *Message) }{ - { - uc: "response without body", + "response without body": { req: func() *http.Request { req, err := http.NewRequestWithContext( t.Context(), @@ -714,8 +700,7 @@ func TestMessageForResponse(t *testing.T) { assert.Empty(t, data1) }, }, - { - uc: "response with body", + "response with body": { req: func() *http.Request { req, err := http.NewRequestWithContext( t.Context(), @@ -781,7 +766,7 @@ func TestMessageForResponse(t *testing.T) { }, }, } { - t.Run(tc.uc, func(t *testing.T) { + t.Run(uc, func(t *testing.T) { msg := MessageForResponse(tc.req, tc.respHeader, tc.respBody, http.StatusOK) tc.assert(t, msg) From 7e2d84248fde61c8fade381d86e592bd08ebbc4d Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Wed, 4 Nov 2026 09:17:44 +0100 Subject: [PATCH 27/33] further test reformatting --- accept_signature_builder_test.go | 104 ++++++++++++++----------------- 1 file changed, 47 insertions(+), 57 deletions(-) diff --git a/accept_signature_builder_test.go b/accept_signature_builder_test.go index 4527942..5e01022 100644 --- a/accept_signature_builder_test.go +++ b/accept_signature_builder_test.go @@ -13,13 +13,11 @@ import ( func TestNewAcceptedSignature(t *testing.T) { t.Parallel() - for _, tc := range []struct { - uc string + for uc, tc := range map[string]struct { opts []AcceptSignatureOption assert func(t *testing.T, err error, asb *AcceptSignatureBuilder) }{ - { - uc: "no options provided", + "no options provided": { assert: func(t *testing.T, err error, asb *AcceptSignatureBuilder) { t.Helper() @@ -40,8 +38,7 @@ func TestNewAcceptedSignature(t *testing.T) { }) }, }, - { - uc: "all possible options provided", + "all possible options provided": { opts: []AcceptSignatureOption{ WithSignatureAlgorithm(EcdsaP256Sha256), WithKeyID("test"), @@ -75,8 +72,7 @@ func TestNewAcceptedSignature(t *testing.T) { }) }, }, - { - uc: "invalid extension parameter", + "invalid extension parameter": { opts: []AcceptSignatureOption{ WithParameter("keyid", "reserved"), }, @@ -87,8 +83,7 @@ func TestNewAcceptedSignature(t *testing.T) { assert.Nil(t, asb) }, }, - { - uc: "option raises error", + "option raises error": { opts: []AcceptSignatureOption{ WithComponents("@foo"), }, @@ -101,7 +96,7 @@ func TestNewAcceptedSignature(t *testing.T) { }, }, } { - t.Run(tc.uc, func(t *testing.T) { + t.Run(uc, func(t *testing.T) { builder, err := NewAcceptSignature(tc.opts...) tc.assert(t, err, builder) @@ -112,31 +107,29 @@ func TestNewAcceptedSignature(t *testing.T) { func TestAcceptSignatureBuilderBuild(t *testing.T) { t.Parallel() - for _, tc := range []struct { - uc string + for uc, tc := range map[string]struct { opts []AcceptSignatureOption buildOpts []AcceptSignatureBuildOption assert func(t *testing.T, err error, hdr http.Header) }{ - { - uc: "no nonce by default", + "no nonce by default": { assert: func(t *testing.T, err error, hdr http.Header) { t.Helper() require.NoError(t, err) assert.Equal(t, `sig=();created;expires`, hdr.Get(headerAcceptSignature)) }, }, - { - uc: "explicit nonce at Build", - buildOpts: []AcceptSignatureBuildOption{WithParameter("nonce", "request-nonce")}, + "explicit nonce at Build": { + buildOpts: []AcceptSignatureBuildOption{ + WithParameter("nonce", "request-nonce"), + }, assert: func(t *testing.T, err error, hdr http.Header) { t.Helper() require.NoError(t, err) assert.Equal(t, `sig=();created;expires;nonce="request-nonce"`, hdr.Get(headerAcceptSignature)) }, }, - { - uc: "explicit nonce overrides getter", + "explicit nonce overrides getter": { opts: []AcceptSignatureOption{ WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { return "", errors.New("getter must not be called") @@ -149,8 +142,7 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { assert.Equal(t, `sig=();created;expires;nonce="requested"`, hdr.Get(headerAcceptSignature)) }, }, - { - uc: "empty nonce returned by getter is omitted", + "empty nonce returned by getter is omitted": { opts: []AcceptSignatureOption{ WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { return "", nil })), }, @@ -160,8 +152,7 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { assert.Equal(t, `sig=();created;expires`, hdr.Get(headerAcceptSignature)) }, }, - { - uc: "non-string nonce in Build", + "non-string nonce in Build": { buildOpts: []AcceptSignatureBuildOption{WithParameter("nonce", Token("wrong-type"))}, assert: func(t *testing.T, err error, hdr http.Header) { t.Helper() @@ -169,26 +160,27 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { assert.Empty(t, hdr) }, }, - { - uc: "empty nonce in Build", - buildOpts: []AcceptSignatureBuildOption{WithParameter("nonce", "")}, + "empty nonce in Build": { + buildOpts: []AcceptSignatureBuildOption{ + WithParameter("nonce", ""), + }, assert: func(t *testing.T, err error, hdr http.Header) { t.Helper() require.ErrorIs(t, err, ErrParameter) assert.Empty(t, hdr) }, }, - { - uc: "invalid structured field string for nonce", - buildOpts: []AcceptSignatureBuildOption{WithParameter("nonce", "bad\nvalue")}, + "invalid structured field string for nonce": { + buildOpts: []AcceptSignatureBuildOption{ + WithParameter("nonce", "bad\nvalue"), + }, assert: func(t *testing.T, err error, hdr http.Header) { t.Helper() require.ErrorIs(t, err, ErrParameter) assert.Empty(t, hdr) }, }, - { - uc: "duplicate nonce in Build", + "duplicate nonce in Build": { buildOpts: []AcceptSignatureBuildOption{ WithParameter("nonce", "first"), WithParameter("nonce", "second"), @@ -199,17 +191,17 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { assert.Empty(t, hdr) }, }, - { - uc: "additional extension at Build", - buildOpts: []AcceptSignatureBuildOption{WithParameter("other", "value")}, + "additional extension at Build": { + buildOpts: []AcceptSignatureBuildOption{ + WithParameter("other", "value"), + }, assert: func(t *testing.T, err error, hdr http.Header) { t.Helper() require.NoError(t, err) assert.Equal(t, `sig=();created;expires;other="value"`, hdr.Get(headerAcceptSignature)) }, }, - { - uc: "static and dynamic extensions", + "static and dynamic extensions": { opts: []AcceptSignatureOption{ WithParameter("audience", "service-a"), WithParameter("flag", true), @@ -221,8 +213,7 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { assert.Equal(t, `sig=();created;expires;audience="service-a";flag;challenge=example`, hdr.Get(headerAcceptSignature)) }, }, - { - uc: "extension types", + "extension types": { opts: []AcceptSignatureOption{ WithParameter("integer", 42), WithParameter("decimal", 1.5), @@ -234,18 +225,20 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { assert.Equal(t, `sig=();created;expires;integer=42;decimal=1.5;bytes=:aGVsbG8=:`, hdr.Get(headerAcceptSignature)) }, }, - { - uc: "conflicting static and dynamic extension", - opts: []AcceptSignatureOption{WithParameter("audience", "static")}, - buildOpts: []AcceptSignatureBuildOption{WithParameter("audience", "dynamic")}, + "conflicting static and dynamic extension": { + opts: []AcceptSignatureOption{ + WithParameter("audience", "static"), + }, + buildOpts: []AcceptSignatureBuildOption{ + WithParameter("audience", "dynamic"), + }, assert: func(t *testing.T, err error, hdr http.Header) { t.Helper() require.ErrorIs(t, err, ErrParameter) assert.Empty(t, hdr) }, }, - { - uc: "duplicate extension at Build", + "duplicate extension at Build": { buildOpts: []AcceptSignatureBuildOption{ WithParameter("audience", "first"), WithParameter("audience", "second"), @@ -256,17 +249,17 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { assert.Empty(t, hdr) }, }, - { - uc: "invalid extension at Build", - buildOpts: []AcceptSignatureBuildOption{WithParameter("other", "bad\nvalue")}, + "invalid extension at Build": { + buildOpts: []AcceptSignatureBuildOption{ + WithParameter("other", "bad\nvalue"), + }, assert: func(t *testing.T, err error, hdr http.Header) { t.Helper() require.ErrorIs(t, err, ErrParameter) assert.Empty(t, hdr) }, }, - { - uc: "failing getting the nonce", + "failing getting the nonce": { opts: []AcceptSignatureOption{ WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { return "", errors.New("test error") @@ -279,8 +272,7 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { require.Contains(t, err.Error(), "test error") }, }, - { - uc: "Accept-Signature only is added", + "Accept-Signature only is added": { opts: []AcceptSignatureOption{ WithSignatureAlgorithm(EcdsaP256Sha256), WithKeyID("test"), @@ -301,8 +293,7 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { assert.Empty(t, hdr.Values(headerWantContentDigest)) }, }, - { - uc: "Accept-Signature and Want-Content-Digest headers are added with default algorithms", + "Accept-Signature and Want-Content-Digest headers are added with default algorithms": { opts: []AcceptSignatureOption{ WithSignatureAlgorithm(EcdsaP256Sha256), WithKeyID("test"), @@ -325,8 +316,7 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { assert.ElementsMatch(t, values, []string{"sha-256=5", "sha-512=10"}) }, }, - { - uc: "Accept-Signature and Want-Content-Digest headers are added with supplied algorithms", + "Accept-Signature and Want-Content-Digest headers are added with supplied algorithms": { opts: []AcceptSignatureOption{ WithSignatureAlgorithm(EcdsaP256Sha256), WithKeyID("test"), @@ -351,7 +341,7 @@ func TestAcceptSignatureBuilderBuild(t *testing.T) { }, }, } { - t.Run(tc.uc, func(t *testing.T) { + t.Run(uc, func(t *testing.T) { hdr := make(http.Header) builder, err := NewAcceptSignature(tc.opts...) From 4c3749d3e723ed6f79441bcbea174ac7aee221bb Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Wed, 4 Nov 2026 09:56:11 +0100 Subject: [PATCH 28/33] type-safe signature parameter access --- accept_signature_builder.go | 4 +- httpsig.go | 48 +++++++- httpsig_test.go | 221 ++++++++++++++++++++++++++++++++++++ options.go | 24 ++-- options_test.go | 6 +- signature_input.go | 2 +- signature_input_test.go | 6 +- signer.go | 4 +- verification_policy.go | 26 ++--- verification_policy_test.go | 18 +-- verifier_test.go | 6 +- 11 files changed, 314 insertions(+), 51 deletions(-) create mode 100644 httpsig_test.go diff --git a/accept_signature_builder.go b/accept_signature_builder.go index b17706c..c1376eb 100644 --- a/accept_signature_builder.go +++ b/accept_signature_builder.go @@ -104,11 +104,11 @@ func (asb *AcceptSignatureBuilder) Build( asb.identifiers) for _, param := range asb.parameters { - sigReqs.Params.Add(param.name, param.value) + sigReqs.Params.Add(string(param.name), param.value) } for _, param := range callOptions.parameters { - sigReqs.Params.Add(param.name, param.value) + sigReqs.Params.Add(string(param.name), param.value) } dict := httpsfv.NewDictionary() diff --git a/httpsig.go b/httpsig.go index 62f8ce3..0fab889 100644 --- a/httpsig.go +++ b/httpsig.go @@ -161,8 +161,8 @@ const ( Sha512 DigestAlgorithm = "sha-512" ) -// SignatureParameter names one of the standard RFC 9421 signature parameters. -// Additional, profile-specific parameter names can appear in SignatureParameters. +// SignatureParameter names an RFC 9421 signature parameter or a +// profile-specific extension parameter. type SignatureParameter string const ( @@ -190,7 +190,49 @@ const ( // parameter names; values are decoded Structured Fields bare items (for // example string, Token, int64, float64, bool, or []byte). // Display Strings are exposed as ordinary strings. -type SignatureParameters map[string]any +type SignatureParameters map[SignatureParameter]any + +// KeyID returns the keyid parameter if present and of the expected type. +func (p SignatureParameters) KeyID() (string, bool) { + value, ok := p[KeyID].(string) + + return value, ok +} + +// Alg returns the alg parameter if present and of the expected type. +func (p SignatureParameters) Alg() (string, bool) { + value, ok := p[Alg].(string) + + return value, ok +} + +// Created returns the created parameter as a Unix timestamp if it has the expected type. +func (p SignatureParameters) Created() (int64, bool) { + value, ok := p[Created].(int64) + + return value, ok +} + +// Expires returns the expires parameter as a Unix timestamp if it has the expected type. +func (p SignatureParameters) Expires() (int64, bool) { + value, ok := p[Expires].(int64) + + return value, ok +} + +// Nonce returns the nonce parameter if present and of the expected type. +func (p SignatureParameters) Nonce() (string, bool) { + value, ok := p[Nonce].(string) + + return value, ok +} + +// Tag returns the tag parameter if present and of the expected type. +func (p SignatureParameters) Tag() (string, bool) { + value, ok := p[Tag].(string) + + return value, ok +} // Token represents a Structured Fields token. It is distinct from string so // applications can distinguish token values from quoted Structured Fields diff --git a/httpsig_test.go b/httpsig_test.go new file mode 100644 index 0000000..0279c6a --- /dev/null +++ b/httpsig_test.go @@ -0,0 +1,221 @@ +package httpsig + +import ( + "testing" + + "github.com/stretchr/testify/assert" +) + +func TestSignatureParametersKeyID(t *testing.T) { + t.Parallel() + + for name, tc := range map[string]struct { + params SignatureParameters + want string + wantOK bool + }{ + "present": { + params: SignatureParameters{KeyID: "test-key"}, + want: "test-key", + wantOK: true, + }, + "empty string": { + params: SignatureParameters{KeyID: ""}, + wantOK: true, + }, + "missing": { + params: SignatureParameters{}, + }, + "nil map": {}, + "wrong type": { + params: SignatureParameters{KeyID: int64(1234)}, + }, + } { + t.Run(name, func(t *testing.T) { + got, ok := tc.params.KeyID() + + assert.Equal(t, tc.want, got) + assert.Equal(t, tc.wantOK, ok) + }) + } +} + +func TestSignatureParametersAlg(t *testing.T) { + t.Parallel() + + for name, tc := range map[string]struct { + params SignatureParameters + want string + wantOK bool + }{ + "present": { + params: SignatureParameters{Alg: "ed25519"}, + want: "ed25519", + wantOK: true, + }, + "empty string": { + params: SignatureParameters{Alg: ""}, + wantOK: true, + }, + "missing": { + params: SignatureParameters{}, + }, + "nil map": {}, + "wrong type": { + params: SignatureParameters{Alg: int64(1234)}, + }, + } { + t.Run(name, func(t *testing.T) { + got, ok := tc.params.Alg() + + assert.Equal(t, tc.want, got) + assert.Equal(t, tc.wantOK, ok) + }) + } +} + +func TestSignatureParametersCreated(t *testing.T) { + t.Parallel() + + for name, tc := range map[string]struct { + params SignatureParameters + want int64 + wantOK bool + }{ + "present": { + params: SignatureParameters{Created: int64(1234)}, + want: 1234, + wantOK: true, + }, + "zero value": { + params: SignatureParameters{Created: int64(0)}, + wantOK: true, + }, + "missing": { + params: SignatureParameters{}, + }, + "nil map": {}, + "wrong type": { + params: SignatureParameters{Created: "1234"}, + }, + } { + t.Run(name, func(t *testing.T) { + got, ok := tc.params.Created() + + assert.Equal(t, tc.want, got) + assert.Equal(t, tc.wantOK, ok) + }) + } +} + +func TestSignatureParametersExpires(t *testing.T) { + t.Parallel() + + for name, tc := range map[string]struct { + params SignatureParameters + want int64 + wantOK bool + }{ + "present": { + params: SignatureParameters{Expires: int64(5678)}, + want: 5678, + wantOK: true, + }, + "zero value": { + params: SignatureParameters{Expires: int64(0)}, + wantOK: true, + }, + "missing": { + params: SignatureParameters{}, + }, + "nil map": {}, + "wrong type": { + params: SignatureParameters{Expires: "5678"}, + }, + } { + t.Run(name, func(t *testing.T) { + got, ok := tc.params.Expires() + + assert.Equal(t, tc.want, got) + assert.Equal(t, tc.wantOK, ok) + }) + } +} + +func TestSignatureParametersNonce(t *testing.T) { + t.Parallel() + + for name, tc := range map[string]struct { + params SignatureParameters + want string + wantOK bool + }{ + "present": { + params: SignatureParameters{Nonce: "request-nonce"}, + want: "request-nonce", + wantOK: true, + }, + "empty string": { + params: SignatureParameters{Nonce: ""}, + wantOK: true, + }, + "missing": { + params: SignatureParameters{}, + }, + "nil map": {}, + "wrong type": { + params: SignatureParameters{Nonce: int64(1234)}, + }, + } { + t.Run(name, func(t *testing.T) { + got, ok := tc.params.Nonce() + + assert.Equal(t, tc.want, got) + assert.Equal(t, tc.wantOK, ok) + }) + } +} + +func TestSignatureParametersTag(t *testing.T) { + t.Parallel() + + for name, tc := range map[string]struct { + params SignatureParameters + want string + wantOK bool + }{ + "present": { + params: SignatureParameters{Tag: "profile"}, + want: "profile", + wantOK: true, + }, + "empty string": { + params: SignatureParameters{Tag: ""}, + wantOK: true, + }, + "missing": { + params: SignatureParameters{}, + }, + "nil map": {}, + "wrong type": { + params: SignatureParameters{Tag: int64(1234)}, + }, + } { + t.Run(name, func(t *testing.T) { + got, ok := tc.params.Tag() + + assert.Equal(t, tc.want, got) + assert.Equal(t, tc.wantOK, ok) + }) + } +} + +func TestSignatureParametersExtension(t *testing.T) { + t.Parallel() + + name := SignatureParameter("wimse-aud") + params := SignatureParameters{name: "service-a"} + + assert.Equal(t, "service-a", params[name]) + assert.Equal(t, "service-a", params["wimse-aud"]) +} diff --git a/options.go b/options.go index 04d8005..31cebb4 100644 --- a/options.go +++ b/options.go @@ -240,12 +240,12 @@ func WithAlg() SignerOption { // an invocation cannot override static requirements. Duplicate signing or // builder parameters are rejected. Do not use secret expected values: verification // compares them before the signature has been authenticated. -func WithParameter(name string, value any) parameterOption { +func WithParameter(name SignatureParameter, value any) parameterOption { return parameterOption{name: name, value: value} } type parameterOption struct { - name string + name SignatureParameter value any } @@ -254,7 +254,7 @@ func (o parameterOption) applySignerOption(s *signer) error { } func (o parameterOption) applySignOption(opts *signOptions) error { - if o.name == string(Nonce) { + if o.name == Nonce { if opts.nonceSet { return fmt.Errorf("%w: duplicate signature parameter %q", ErrParameter, o.name) } @@ -291,11 +291,11 @@ func (o parameterOption) applyVerifyOption(policy *verificationPolicy) error { // WithRequiredParameters requires the named signature parameters to be present. // It does not check their application-specific semantics. -func WithRequiredParameters(names ...string) requiredParametersOption { +func WithRequiredParameters(names ...SignatureParameter) requiredParametersOption { return names } -type requiredParametersOption []string +type requiredParametersOption []SignatureParameter func (o requiredParametersOption) applyVerifierOption(_ *verifier, policy *verificationPolicy, _ bool) error { return o.applyVerifyOption(policy) @@ -312,11 +312,11 @@ func (o requiredParametersOption) applyVerifyOption(policy *verificationPolicy) } // WithForbiddenParameters rejects signatures containing any named parameter. -func WithForbiddenParameters(names ...string) forbiddenParametersOption { +func WithForbiddenParameters(names ...SignatureParameter) forbiddenParametersOption { return names } -type forbiddenParametersOption []string +type forbiddenParametersOption []SignatureParameter func (o forbiddenParametersOption) applyVerifierOption(_ *verifier, policy *verificationPolicy, _ bool) error { return o.applyVerifyOption(policy) @@ -333,7 +333,7 @@ func (o forbiddenParametersOption) applyVerifyOption(policy *verificationPolicy) } func (o parameterOption) applyAcceptSignatureBuildOption(opts *acceptSignatureBuildOptions) error { - if o.name == string(Nonce) { + if o.name == Nonce { if opts.nonceSet { return fmt.Errorf("%w: duplicate signature parameter %q", ErrParameter, o.name) } @@ -358,7 +358,7 @@ func validateNonceOption(value any) (string, error) { return "", fmt.Errorf("%w: nonce must be a non-empty string", ErrParameter) } - if err := validateParameter(string(Nonce), nonce); err != nil { + if err := validateParameter(Nonce, nonce); err != nil { return "", err } @@ -603,7 +603,7 @@ func addParameter( } func normalizeParameter(option parameterOption) (parameterOption, error) { - switch SignatureParameter(option.name) { + switch option.name { case Created, Expires, KeyID, Alg, Nonce, Tag: return option, fmt.Errorf("%w: %q is a reserved signature parameter", ErrParameter, option.name) } @@ -626,9 +626,9 @@ func normalizeParameter(option parameterOption) (parameterOption, error) { return option, nil } -func validateParameter(name string, value any) error { +func validateParameter(name SignatureParameter, value any) error { validationParams := httpsfv.NewParams() - validationParams.Add(name, value) + validationParams.Add(string(name), value) if _, err := httpsfv.Marshal(httpsfv.Item{Value: true, Params: validationParams}); err != nil { return fmt.Errorf("%w: invalid signature parameter %q: %w", ErrParameter, name, err) diff --git a/options_test.go b/options_test.go index 06e9683..f2d8523 100644 --- a/options_test.go +++ b/options_test.go @@ -354,7 +354,7 @@ func TestWithParameterForSigner(t *testing.T) { require.NoError(t, err) require.Len(t, s.parameters, 1) - assert.Equal(t, "example", s.parameters[0].name) + assert.Equal(t, SignatureParameter("example"), s.parameters[0].name) assert.Equal(t, tc.want, s.parameters[0].value) }) } @@ -421,7 +421,7 @@ func TestWithParameterForSign(t *testing.T) { require.NoError(t, err) require.Len(t, opts.parameters, 1) - assert.Equal(t, "extension", opts.parameters[0].name) + assert.Equal(t, SignatureParameter("extension"), opts.parameters[0].name) assert.Equal(t, httpsfv.Token("value"), opts.parameters[0].value) }) @@ -496,7 +496,7 @@ func TestWithParameterForAcceptSignature(t *testing.T) { require.NoError(t, err) require.Len(t, asb.parameters, 1) - assert.Equal(t, "example", asb.parameters[0].name) + assert.Equal(t, SignatureParameter("example"), asb.parameters[0].name) assert.Equal(t, tc.want, asb.parameters[0].value) }) } diff --git a/signature_input.go b/signature_input.go index 0cf63f3..030a9db 100644 --- a/signature_input.go +++ b/signature_input.go @@ -63,7 +63,7 @@ func (si *signatureInput) parameters() SignatureParameters { value = string(v) } - result[name] = value + result[SignatureParameter(name)] = value } return result diff --git a/signature_input_test.go b/signature_input_test.go index 09827fa..befbd86 100644 --- a/signature_input_test.go +++ b/signature_input_test.go @@ -351,9 +351,9 @@ func TestSignatureInputParameters(t *testing.T) { return params }(), want: SignatureParameters{ - string(Created): int64(1577836800), - "foo": Token("hello"), - "bar": "hello", + Created: int64(1577836800), + "foo": Token("hello"), + "bar": "hello", }, }, } { diff --git a/signer.go b/signer.go index 3e82c9f..ed8ac20 100644 --- a/signer.go +++ b/signer.go @@ -179,11 +179,11 @@ func (s *signer) signatureInput(opts signOptions) *signatureInput { } for _, param := range s.parameters { - params.Add(param.name, param.value) + params.Add(string(param.name), param.value) } for _, param := range opts.parameters { - params.Add(param.name, param.value) + params.Add(string(param.name), param.value) } return newSignatureInput(s.ids, params) diff --git a/verification_policy.go b/verification_policy.go index dbc6053..5ee8956 100644 --- a/verification_policy.go +++ b/verification_policy.go @@ -18,8 +18,8 @@ type verificationPolicy struct { asb *AcceptSignatureBuilder reqCreatedTS *bool reqExpiresTS *bool - requiredParameters []string - forbiddenParameters []string + requiredParameters []SignatureParameter + forbiddenParameters []SignatureParameter expectedParameters []parameterOption } @@ -127,7 +127,7 @@ func (e *verificationPolicy) inheritParameters(globalPolicy *verificationPolicy) return nil } -func (e *verificationPolicy) addRequiredParameter(name string) error { +func (e *verificationPolicy) addRequiredParameter(name SignatureParameter) error { if err := validateParameter(name, true); err != nil { return err } @@ -135,7 +135,7 @@ func (e *verificationPolicy) addRequiredParameter(name string) error { return e.requireParameter(name) } -func (e *verificationPolicy) requireParameter(name string) error { +func (e *verificationPolicy) requireParameter(name SignatureParameter) error { if slices.Contains(e.forbiddenParameters, name) { return fmt.Errorf("%w: required parameter %q is forbidden", ErrParameter, name) } @@ -147,7 +147,7 @@ func (e *verificationPolicy) requireParameter(name string) error { return nil } -func (e *verificationPolicy) addForbiddenParameter(name string) error { +func (e *verificationPolicy) addForbiddenParameter(name SignatureParameter) error { if err := validateParameter(name, true); err != nil { return err } @@ -155,7 +155,7 @@ func (e *verificationPolicy) addForbiddenParameter(name string) error { return e.forbidParameter(name) } -func (e *verificationPolicy) forbidParameter(name string) error { +func (e *verificationPolicy) forbidParameter(name SignatureParameter) error { if slices.Contains(e.requiredParameters, name) { return fmt.Errorf("%w: required parameter %q is forbidden", ErrParameter, name) } @@ -178,7 +178,7 @@ func (e *verificationPolicy) addExpectedParameter(option parameterOption) error return fmt.Errorf("%w: expected parameter %q is forbidden", ErrParameter, option.name) } - if option.name == string(Nonce) { + if option.name == Nonce { if _, err := validateNonceOption(option.value); err != nil { return err } @@ -236,9 +236,9 @@ func (e *verificationPolicy) expectParameter(option parameterOption) error { func (e *verificationPolicy) validateParameters(tag string) error { for _, name := range e.forbiddenParameters { - if name == string(Tag) && tag != "" || - name == string(Created) && *e.reqCreatedTS || - name == string(Expires) && *e.reqExpiresTS { + if name == Tag && tag != "" || + name == Created && *e.reqCreatedTS || + name == Expires && *e.reqExpiresTS { return fmt.Errorf("%w: required signature parameter %q is forbidden", ErrParameter, name) } } @@ -293,19 +293,19 @@ func (e *verificationPolicy) assertMetadata(si *signatureInput, msg *Message) er } for _, name := range e.requiredParameters { - if _, present := si.parameter(SignatureParameter(name)); !present { + if _, present := si.parameter(name); !present { return fmt.Errorf("%w: required signature parameter %q is missing", ErrParameter, name) } } for _, name := range e.forbiddenParameters { - if _, present := si.parameter(SignatureParameter(name)); present { + if _, present := si.parameter(name); present { return fmt.Errorf("%w: forbidden signature parameter %q is present", ErrParameter, name) } } for _, param := range e.expectedParameters { - value, present := si.parameter(SignatureParameter(param.name)) + value, present := si.parameter(param.name) if !present { return fmt.Errorf("%w: expected signature parameter %q is missing", ErrMissingParameter, param.name) } diff --git a/verification_policy_test.go b/verification_policy_test.go index beb251b..869b4cf 100644 --- a/verification_policy_test.go +++ b/verification_policy_test.go @@ -14,8 +14,8 @@ func TestVerificationPolicyClone(t *testing.T) { t.Parallel() original := &verificationPolicy{ - requiredParameters: []string{"nonce"}, - forbiddenParameters: []string{"alg"}, + requiredParameters: []SignatureParameter{Nonce}, + forbiddenParameters: []SignatureParameter{Alg}, expectedParameters: []parameterOption{{name: "audience", value: "service-a"}}, } @@ -26,8 +26,8 @@ func TestVerificationPolicyClone(t *testing.T) { clone.forbiddenParameters[0] = "keyid" clone.expectedParameters[0] = parameterOption{name: "audience", value: "service-b"} - assert.Equal(t, []string{"nonce"}, original.requiredParameters) - assert.Equal(t, []string{"alg"}, original.forbiddenParameters) + assert.Equal(t, []SignatureParameter{Nonce}, original.requiredParameters) + assert.Equal(t, []SignatureParameter{Alg}, original.forbiddenParameters) assert.Equal(t, []parameterOption{{name: "audience", value: "service-a"}}, original.expectedParameters) } @@ -44,7 +44,7 @@ func TestVerificationPolicyWithOptions(t *testing.T) { effective, err := original.withOptions("profile", []VerifyOption{WithRequiredParameters("nonce")}) require.NoError(t, err) require.NotSame(t, original, effective) - assert.Equal(t, []string{"nonce"}, effective.requiredParameters) + assert.Equal(t, []SignatureParameter{Nonce}, effective.requiredParameters) assert.Empty(t, original.requiredParameters) _, err = original.withOptions("profile", []VerifyOption{WithForbiddenParameters("tag")}) @@ -66,8 +66,8 @@ func TestVerificationPolicyInherit(t *testing.T) { reqCreatedTS: &required, reqExpiresTS: &required, asb: &AcceptSignatureBuilder{label: "sig"}, - requiredParameters: []string{"nonce"}, - forbiddenParameters: []string{"alg"}, + requiredParameters: []SignatureParameter{Nonce}, + forbiddenParameters: []SignatureParameter{Alg}, expectedParameters: []parameterOption{{name: "audience", value: "service-a"}}, } @@ -127,10 +127,10 @@ func TestVerificationPolicyInherit(t *testing.T) { for uc, local := range map[string]verificationPolicy{ "local requirement conflicts with global prohibition": { - requiredParameters: []string{"alg"}, + requiredParameters: []SignatureParameter{Alg}, }, "local prohibition conflicts with global required parameter": { - forbiddenParameters: []string{"nonce"}, + forbiddenParameters: []SignatureParameter{Nonce}, }, "local value conflicts with global expectation": { expectedParameters: []parameterOption{{name: "audience", value: "other"}}, diff --git a/verifier_test.go b/verifier_test.go index 963c1d4..90940a4 100644 --- a/verifier_test.go +++ b/verifier_test.go @@ -296,8 +296,8 @@ func TestNewVerifier(t *testing.T) { require.NoError(t, err) exp := v.tagPolicies["profile"] - assert.Equal(t, []string{"nonce"}, exp.requiredParameters) - assert.Equal(t, []string{"alg", "keyid"}, exp.forbiddenParameters) + assert.Equal(t, []SignatureParameter{Nonce}, exp.requiredParameters) + assert.Equal(t, []SignatureParameter{Alg, KeyID}, exp.forbiddenParameters) assert.Equal(t, []parameterOption{{name: "audience", value: "service-a"}}, exp.expectedParameters) }, }, @@ -376,7 +376,7 @@ func TestNewVerifier(t *testing.T) { t.Helper() require.NoError(t, err) - assert.Equal(t, []string{"created"}, v.tagPolicies["profile"].forbiddenParameters) + assert.Equal(t, []SignatureParameter{Created}, v.tagPolicies["profile"].forbiddenParameters) }, }, "invalid parameter name": { From c04ed972b6689accf3856980874afa7f56111150 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Wed, 4 Nov 2026 12:03:36 +0100 Subject: [PATCH 29/33] further api consolitdation --- httpsig.go | 4 ++-- httpsig_test.go | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/httpsig.go b/httpsig.go index 0fab889..fa500a8 100644 --- a/httpsig.go +++ b/httpsig.go @@ -200,10 +200,10 @@ func (p SignatureParameters) KeyID() (string, bool) { } // Alg returns the alg parameter if present and of the expected type. -func (p SignatureParameters) Alg() (string, bool) { +func (p SignatureParameters) Alg() (SignatureAlgorithm, bool) { value, ok := p[Alg].(string) - return value, ok + return SignatureAlgorithm(value), ok } // Created returns the created parameter as a Unix timestamp if it has the expected type. diff --git a/httpsig_test.go b/httpsig_test.go index 0279c6a..3709ffa 100644 --- a/httpsig_test.go +++ b/httpsig_test.go @@ -45,12 +45,12 @@ func TestSignatureParametersAlg(t *testing.T) { for name, tc := range map[string]struct { params SignatureParameters - want string + want SignatureAlgorithm wantOK bool }{ "present": { params: SignatureParameters{Alg: "ed25519"}, - want: "ed25519", + want: Ed25519, wantOK: true, }, "empty string": { From ca76d42b555d208136ecfd04b983bd647a7a0a4e Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Wed, 4 Nov 2026 12:22:15 +0100 Subject: [PATCH 30/33] code formatting --- verifier_test.go | 314 +++++++++++++++++++++++++++-------------------- 1 file changed, 180 insertions(+), 134 deletions(-) diff --git a/verifier_test.go b/verifier_test.go index 90940a4..05649a7 100644 --- a/verifier_test.go +++ b/verifier_test.go @@ -287,7 +287,10 @@ func TestNewVerifier(t *testing.T) { "parameter rules inherited from global configuration": { resolver: &KeyResolverMock{}, opts: []VerifierOption{ - WithRequiredTag("profile", WithRequiredParameters("nonce"), WithParameter("audience", "service-a")), + WithRequiredTag("profile", + WithRequiredParameters("nonce"), + WithParameter("audience", "service-a"), + ), WithForbiddenParameters("alg", "keyid"), }, assert: func(t *testing.T, err error, v *verifier) { @@ -305,7 +308,10 @@ func TestNewVerifier(t *testing.T) { resolver: &KeyResolverMock{}, opts: []VerifierOption{ WithParameter("audience", "service-a"), - WithRequiredTag("profile", WithParameter("audience", "service-a"), WithRequiredParameters("audience")), + WithRequiredTag("profile", + WithParameter("audience", "service-a"), + WithRequiredParameters("audience"), + ), }, assert: func(t *testing.T, err error, v *verifier) { t.Helper() @@ -317,7 +323,9 @@ func TestNewVerifier(t *testing.T) { "global and tag-specific parameter conflict": { resolver: &KeyResolverMock{}, opts: []VerifierOption{ - WithRequiredTag("profile", WithRequiredParameters("nonce")), + WithRequiredTag("profile", + WithRequiredParameters("nonce"), + ), WithForbiddenParameters("nonce"), }, assert: func(t *testing.T, err error, _ *verifier) { @@ -330,7 +338,9 @@ func TestNewVerifier(t *testing.T) { "conflicting expected values": { resolver: &KeyResolverMock{}, opts: []VerifierOption{ - WithRequiredTag("profile", WithParameter("audience", "first")), + WithRequiredTag("profile", + WithParameter("audience", "first"), + ), WithParameter("audience", "second"), }, assert: func(t *testing.T, err error, _ *verifier) { @@ -343,7 +353,9 @@ func TestNewVerifier(t *testing.T) { "required tag cannot be forbidden": { resolver: &KeyResolverMock{}, opts: []VerifierOption{ - WithRequiredTag("profile", WithForbiddenParameters("tag")), + WithRequiredTag("profile", + WithForbiddenParameters("tag"), + ), }, assert: func(t *testing.T, err error, _ *verifier) { t.Helper() @@ -382,7 +394,9 @@ func TestNewVerifier(t *testing.T) { "invalid parameter name": { resolver: &KeyResolverMock{}, opts: []VerifierOption{ - WithRequiredTag("profile", WithRequiredParameters("not a name")), + WithRequiredTag("profile", + WithRequiredParameters("not a name"), + ), }, assert: func(t *testing.T, err error, _ *verifier) { t.Helper() @@ -394,7 +408,9 @@ func TestNewVerifier(t *testing.T) { "unsupported expected standard parameter": { resolver: &KeyResolverMock{}, opts: []VerifierOption{ - WithRequiredTag("profile", WithParameter("alg", "ed25519")), + WithRequiredTag("profile", + WithParameter("alg", "ed25519"), + ), }, assert: func(t *testing.T, err error, _ *verifier) { t.Helper() @@ -406,7 +422,9 @@ func TestNewVerifier(t *testing.T) { "invalid expected nonce": { resolver: &KeyResolverMock{}, opts: []VerifierOption{ - WithRequiredTag("profile", WithParameter("nonce", "")), + WithRequiredTag("profile", + WithParameter("nonce", ""), + ), }, assert: func(t *testing.T, err error, _ *verifier) { t.Helper() @@ -416,7 +434,7 @@ func TestNewVerifier(t *testing.T) { }, }, "duplicate negotiation parameter rejected": { - resolver: Key{Algorithm: HmacSha256, Material: []byte("secret")}, + resolver: &KeyResolverMock{}, opts: []VerifierOption{ WithRequiredTag("profile", WithSignatureNegotiation( @@ -483,17 +501,17 @@ func TestVerifierVerify(t *testing.T) { tkEd25519, ok := key.(ed25519.PublicKey) require.True(t, ok) - for _, tc := range []struct { - uc string + for uc, tc := range map[string]struct { opts []VerifierOption verifyOpts []VerifyOption msg *Message configureResolver func(t *testing.T, kr *KeyResolverMock) assert func(t *testing.T, err error, results VerificationResult) }{ - { - uc: "without signature-input header", - opts: []VerifierOption{WithValidateAllSignatures()}, + "without signature-input header": { + opts: []VerifierOption{ + WithValidateAllSignatures(), + }, msg: &Message{Header: make(http.Header)}, configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, assert: func(t *testing.T, err error, _ VerificationResult) { @@ -504,9 +522,10 @@ func TestVerifierVerify(t *testing.T) { require.ErrorIs(t, err, &NoApplicableSignatureError{}) }, }, - { - uc: "malformed signature-input header items definition", - opts: []VerifierOption{WithValidateAllSignatures()}, + "malformed signature-input header items definition": { + opts: []VerifierOption{ + WithValidateAllSignatures(), + }, msg: &Message{ Header: http.Header{ "Signature-Input": []string{`sig=(,);created=1618884473;keyid="test"`}, @@ -522,9 +541,10 @@ func TestVerifierVerify(t *testing.T) { require.ErrorContains(t, err, "unrecognized character") }, }, - { - uc: "malformed signature-input header parameter", - opts: []VerifierOption{WithValidateAllSignatures()}, + "malformed signature-input header parameter": { + opts: []VerifierOption{ + WithValidateAllSignatures(), + }, msg: &Message{ Header: http.Header{ "Signature-Input": []string{`sig=();created=1618884473;keyid=test`}, @@ -540,9 +560,10 @@ func TestVerifierVerify(t *testing.T) { require.ErrorContains(t, err, "keyid") }, }, - { - uc: "without signature header", - opts: []VerifierOption{WithValidateAllSignatures()}, + "without signature header": { + opts: []VerifierOption{ + WithValidateAllSignatures(), + }, msg: &Message{ Header: http.Header{ "Signature-Input": []string{`sig=();created=1618884473;keyid="test"`}, @@ -558,9 +579,10 @@ func TestVerifierVerify(t *testing.T) { require.ErrorContains(t, err, "no signature present") }, }, - { - uc: "malformed signature header", - opts: []VerifierOption{WithRequiredTag("foo")}, + "malformed signature header": { + opts: []VerifierOption{ + WithRequiredTag("foo"), + }, msg: &Message{ Header: http.Header{ "Signature-Input": []string{`sig=();created=1618884473;keyid="test"`}, @@ -576,9 +598,10 @@ func TestVerifierVerify(t *testing.T) { require.ErrorContains(t, err, "format") }, }, - { - uc: "no applicable signature present", - opts: []VerifierOption{WithRequiredTag("foo")}, + "no applicable signature present": { + opts: []VerifierOption{ + WithRequiredTag("foo"), + }, msg: &Message{ Header: http.Header{ "Signature-Input": []string{`sig=();created=1618884473;keyid="test"`}, @@ -600,8 +623,7 @@ func TestVerifierVerify(t *testing.T) { require.Empty(t, hdr) }, }, - { - uc: "signature base creation error", + "signature base creation error": { opts: []VerifierOption{ WithValidateAllSignatures(), WithCreatedTimestamp(false), @@ -623,9 +645,11 @@ func TestVerifierVerify(t *testing.T) { require.ErrorContains(t, err, "@status not valid for requests") }, }, - { - uc: "key resolver error", - opts: []VerifierOption{WithValidateAllSignatures(), WithExpiresTimestamp(false)}, + "key resolver error": { + opts: []VerifierOption{ + WithValidateAllSignatures(), + WithExpiresTimestamp(false), + }, msg: &Message{ Header: http.Header{ "Signature-Input": []string{`sig=();created=1618884473;keyid="test"`}, @@ -653,9 +677,11 @@ func TestVerifierVerify(t *testing.T) { require.ErrorContains(t, err, "test error") }, }, - { - uc: "expired signature rejected before key resolution", - opts: []VerifierOption{WithRequiredTag("foo"), WithValidityTolerance(1 * time.Second)}, + "expired signature rejected before key resolution": { + opts: []VerifierOption{ + WithRequiredTag("foo"), + WithValidityTolerance(1 * time.Second), + }, msg: &Message{ Header: http.Header{ "Signature-Input": []string{`sig=();expires=1618884470;keyid="test";tag="foo"`}, @@ -671,10 +697,11 @@ func TestVerifierVerify(t *testing.T) { require.ErrorContains(t, err, "expired") }, }, - { - uc: "missing required component rejected before key resolution", + "missing required component rejected before key resolution": { opts: []VerifierOption{ - WithRequiredTag("foo", WithComponents("@method")), + WithRequiredTag("foo", + WithComponents("@method"), + ), WithCreatedTimestamp(false), WithExpiresTimestamp(false), }, @@ -694,11 +721,13 @@ func TestVerifierVerify(t *testing.T) { require.Empty(t, results) }, }, - { - uc: "required extension missing before key resolution", + "required extension missing before key resolution": { opts: []VerifierOption{ - WithRequiredTag("profile", WithRequiredParameters("nonce")), - WithCreatedTimestamp(false), WithExpiresTimestamp(false), + WithRequiredTag("profile", + WithRequiredParameters("nonce"), + ), + WithCreatedTimestamp(false), + WithExpiresTimestamp(false), }, msg: &Message{Header: http.Header{ "Signature-Input": {`sig=();tag="profile"`}, @@ -714,11 +743,13 @@ func TestVerifierVerify(t *testing.T) { require.Empty(t, results) }, }, - { - uc: "forbidden parameter rejected before key resolution", + "forbidden parameter rejected before key resolution": { opts: []VerifierOption{ - WithRequiredTag("profile", WithForbiddenParameters("keyid", "alg")), - WithCreatedTimestamp(false), WithExpiresTimestamp(false), + WithRequiredTag("profile", + WithForbiddenParameters("keyid", "alg"), + ), + WithCreatedTimestamp(false), + WithExpiresTimestamp(false), }, msg: &Message{Header: http.Header{ "Signature-Input": {`sig=();keyid="key";tag="profile"`}, @@ -733,11 +764,11 @@ func TestVerifierVerify(t *testing.T) { require.Empty(t, results) }, }, - { - uc: "dynamic parameter expectation checked before key resolution", + "dynamic parameter expectation checked before key resolution": { opts: []VerifierOption{ WithRequiredTag("profile"), - WithCreatedTimestamp(false), WithExpiresTimestamp(false), + WithCreatedTimestamp(false), + WithExpiresTimestamp(false), }, verifyOpts: []VerifyOption{WithParameter("audience", "expected")}, msg: &Message{Header: http.Header{ @@ -753,10 +784,11 @@ func TestVerifierVerify(t *testing.T) { require.Empty(t, results) }, }, - { - uc: "dynamic expectations cannot override static values", + "dynamic expectations cannot override static values": { opts: []VerifierOption{ - WithRequiredTag("profile", WithParameter("audience", "static")), + WithRequiredTag("profile", + WithParameter("audience", "static"), + ), }, verifyOpts: []VerifyOption{WithParameter("audience", "dynamic")}, msg: &Message{Header: make(http.Header)}, @@ -769,10 +801,13 @@ func TestVerifierVerify(t *testing.T) { require.Empty(t, results) }, }, - { - uc: "dynamic rules cannot forbid required timestamps", - opts: []VerifierOption{WithRequiredTag("profile")}, - verifyOpts: []VerifyOption{WithForbiddenParameters("created")}, + "dynamic rules cannot forbid required timestamps": { + opts: []VerifierOption{ + WithRequiredTag("profile"), + }, + verifyOpts: []VerifyOption{ + WithForbiddenParameters("created"), + }, msg: &Message{Header: make(http.Header)}, configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, assert: func(t *testing.T, err error, results VerificationResult) { @@ -783,12 +818,15 @@ func TestVerifierVerify(t *testing.T) { require.Empty(t, results) }, }, - { - uc: "dynamic audience requested in negotiation", + "dynamic audience requested in negotiation": { opts: []VerifierOption{ - WithRequiredTag("profile", WithSignatureNegotiation()), + WithRequiredTag("profile", + WithSignatureNegotiation(), + ), + }, + verifyOpts: []VerifyOption{ + WithParameter("audience", "service-a"), }, - verifyOpts: []VerifyOption{WithParameter("audience", "service-a")}, msg: &Message{Header: http.Header{ "Signature-Input": {`sig=();created=1618884473;expires=1618884600;tag="profile"`}, "Signature": {"sig=:dGVzdA==:"}, @@ -806,11 +844,12 @@ func TestVerifierVerify(t *testing.T) { assert.Equal(t, `sig=();created;expires;tag="profile";audience="service-a"`, hdr.Get(headerAcceptSignature)) }, }, - { - uc: "static audience requested for missing signature", + "static audience requested for missing signature": { opts: []VerifierOption{ WithParameter("audience", "service-a"), - WithRequiredTag("profile", WithSignatureNegotiation()), + WithRequiredTag("profile", + WithSignatureNegotiation(), + ), }, msg: &Message{Header: make(http.Header)}, configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, @@ -826,16 +865,19 @@ func TestVerifierVerify(t *testing.T) { assert.Equal(t, `sig=();created;expires;tag="profile";audience="service-a"`, hdr.Get(headerAcceptSignature)) }, }, - { - uc: "expected nonce overrides negotiation getter", + "expected nonce overrides negotiation getter": { opts: []VerifierOption{ - WithRequiredTag("profile", WithSignatureNegotiation( - WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { - return "getter", errors.New("getter must not be called") - })), - )), + WithRequiredTag("profile", + WithSignatureNegotiation( + WithNonceGetter(NonceGetterFunc(func(_ context.Context) (string, error) { + return "getter", errors.New("getter must not be called") + })), + ), + ), + }, + verifyOpts: []VerifyOption{ + WithParameter("nonce", "expected-nonce"), }, - verifyOpts: []VerifyOption{WithParameter("nonce", "expected-nonce")}, msg: &Message{Header: make(http.Header)}, configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, assert: func(t *testing.T, err error, results VerificationResult) { @@ -850,13 +892,18 @@ func TestVerifierVerify(t *testing.T) { assert.Equal(t, `sig=();created;expires;nonce="expected-nonce";tag="profile"`, hdr.Get(headerAcceptSignature)) }, }, - { - uc: "dynamic expectations projected for all required tags", + "dynamic expectations projected for all required tags": { opts: []VerifierOption{ - WithRequiredTag("first", WithSignatureNegotiation()), - WithRequiredTag("second", WithSignatureNegotiation()), + WithRequiredTag("first", + WithSignatureNegotiation(), + ), + WithRequiredTag("second", + WithSignatureNegotiation(), + ), + }, + verifyOpts: []VerifyOption{ + WithParameter("audience", "service-a"), }, - verifyOpts: []VerifyOption{WithParameter("audience", "service-a")}, msg: &Message{Header: make(http.Header)}, configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, assert: func(t *testing.T, err error, results VerificationResult) { @@ -874,12 +921,14 @@ func TestVerifierVerify(t *testing.T) { }, hdr.Values(headerAcceptSignature)) }, }, - { - uc: "conflicting explicit negotiation parameter is rejected", + "conflicting explicit negotiation parameter is rejected": { opts: []VerifierOption{ - WithRequiredTag("profile", WithParameter("audience", "expected"), WithSignatureNegotiation( - WithParameter("audience", "builder"), - )), + WithRequiredTag("profile", + WithParameter("audience", "expected"), + WithSignatureNegotiation( + WithParameter("audience", "builder"), + ), + ), }, msg: &Message{Header: make(http.Header)}, configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, @@ -891,8 +940,7 @@ func TestVerifierVerify(t *testing.T) { require.Empty(t, results) }, }, - { - uc: "signature algorithm mismatch after key resolution", + "signature algorithm mismatch after key resolution": { opts: []VerifierOption{ WithValidateAllSignatures(), WithCreatedTimestamp(false), @@ -920,8 +968,7 @@ func TestVerifierVerify(t *testing.T) { require.Empty(t, results) }, }, - { - uc: "unsupported signature key", + "unsupported signature key": { opts: []VerifierOption{ WithRequiredTag("foo"), WithExpiresTimestamp(false), @@ -954,8 +1001,7 @@ func TestVerifierVerify(t *testing.T) { require.ErrorContains(t, err, "unsupported key") }, }, - { - uc: "invalid signature", + "invalid signature": { opts: []VerifierOption{ WithRequiredTag("foo"), WithExpiresTimestamp(false), @@ -996,8 +1042,7 @@ func TestVerifierVerify(t *testing.T) { require.ErrorContains(t, err, "invalid signature") }, }, - { - uc: "signature parameters negotiation for not present tagged signature", + "signature parameters negotiation for not present tagged signature": { opts: []VerifierOption{ WithRequiredTag("foo", WithComponents("@method", "content-digest"), @@ -1029,12 +1074,13 @@ func TestVerifierVerify(t *testing.T) { assert.ElementsMatch(t, hdr.Values("Want-Content-Digest"), []string{"sha-256=1"}) }, }, - { - uc: "global content-digest requirement overridden for negotiated tag", + "global content-digest requirement overridden for negotiated tag": { opts: []VerifierOption{ WithComponents("content-digest"), WithSignatureNegotiation(), - WithRequiredTag("foo", WithComponents("@method")), + WithRequiredTag("foo", + WithComponents("@method"), + ), }, msg: &Message{Header: http.Header{}}, configureResolver: func(t *testing.T, _ *KeyResolverMock) { t.Helper() }, @@ -1053,12 +1099,13 @@ func TestVerifierVerify(t *testing.T) { assert.Empty(t, hdr.Values(headerWantContentDigest)) }, }, - { - uc: "signature negotiation without nonce getter omits nonce", + "signature negotiation without nonce getter omits nonce": { opts: []VerifierOption{ WithRequiredTag("foo", WithComponents("@method"), - WithSignatureNegotiation(WithLabel("foo-sig")), + WithSignatureNegotiation( + WithLabel("foo-sig"), + ), ), }, msg: &Message{Header: http.Header{}}, @@ -1077,8 +1124,7 @@ func TestVerifierVerify(t *testing.T) { assert.Equal(t, `foo-sig=("@method");created;expires;tag="foo"`, hdr.Get(headerAcceptSignature)) }, }, - { - uc: "signature parameters negotiation for present signature with missing expires parameters", + "signature parameters negotiation for present signature with missing expires parameters": { opts: []VerifierOption{ WithRequiredTag("foo", WithSignatureNegotiation( @@ -1119,8 +1165,7 @@ func TestVerifierVerify(t *testing.T) { assert.Equal(t, `bar=();created;expires;keyid="test-key";alg="rsa-pss-sha512";nonce="abc";tag="foo"`, hdr.Get("Accept-Signature")) }, }, - { - uc: "signature parameters negotiation fails because of nonce error", + "signature parameters negotiation fails because of nonce error": { opts: []VerifierOption{ WithRequiredTag("foo", WithComponents("@method"), @@ -1142,8 +1187,7 @@ func TestVerifierVerify(t *testing.T) { require.ErrorContains(t, err, "test error") }, }, - { - uc: "signature verification fails due to invalid second content digest", + "signature verification fails due to invalid second content digest": { opts: []VerifierOption{ WithValidateAllSignatures(), WithCreatedTimestamp(false), @@ -1176,9 +1220,8 @@ func TestVerifierVerify(t *testing.T) { require.ErrorIs(t, err, ErrContentDigestMismatch) }, }, - { + "B.2.1. minimal signature using rsa-pss-sha512": { // https://www.rfc-editor.org/rfc/rfc9421.html#name-minimal-signature-using-rsa - uc: "B.2.1. minimal signature using rsa-pss-sha512", opts: []VerifierOption{ WithValidateAllSignatures(), WithCreatedTimestamp(false), @@ -1240,9 +1283,8 @@ func TestVerifierVerify(t *testing.T) { assert.Equal(t, "foo", sig.Metadata) }, }, - { + "B.2.2. selective covered components using rsa-pss-sha512": { // https://www.rfc-editor.org/rfc/rfc9421.html#name-selective-covered-component - uc: "B.2.2. selective covered components using rsa-pss-sha512", opts: []VerifierOption{ WithValidateAllSignatures(), WithCreatedTimestamp(false), @@ -1311,9 +1353,8 @@ func TestVerifierVerify(t *testing.T) { assert.Equal(t, []string{"foo"}, sig.Metadata) }, }, - { + "B.2.3. full coverage using rsa-pss-sha512": { // https://www.rfc-editor.org/rfc/rfc9421.html#name-full-coverage-using-rsa-pss - uc: "B.2.3. full coverage using rsa-pss-sha512", opts: []VerifierOption{ WithValidateAllSignatures(), WithCreatedTimestamp(false), @@ -1391,9 +1432,8 @@ func TestVerifierVerify(t *testing.T) { assert.Nil(t, sig.Metadata) }, }, - { + "B.2.4. signing a response using ecdsa-p256-sha256": { // https://www.rfc-editor.org/rfc/rfc9421.html#name-signing-a-response-using-ec - uc: "B.2.4. signing a response using ecdsa-p256-sha256 ", opts: []VerifierOption{ WithValidateAllSignatures(), WithCreatedTimestamp(false), @@ -1461,9 +1501,8 @@ func TestVerifierVerify(t *testing.T) { assert.Equal(t, map[string]int{"foo": 1}, sig.Metadata) }, }, - { + "B.2.5. signing a request using hmac-sha256": { // https://www.rfc-editor.org/rfc/rfc9421.html#name-signing-a-request-using-hma - uc: "B.2.5. signing a request using hmac-sha256", opts: []VerifierOption{ WithValidateAllSignatures(), WithCreatedTimestamp(false), @@ -1527,9 +1566,8 @@ func TestVerifierVerify(t *testing.T) { assert.Empty(t, sig.Metadata) }, }, - { + "B.2.6. signing a request using ed25519": { // https://www.rfc-editor.org/rfc/rfc9421.html#name-signing-a-request-using-ed2 - uc: "B.2.6. signing a request using ed25519", opts: []VerifierOption{ WithValidateAllSignatures(), WithCreatedTimestamp(false), @@ -1600,8 +1638,7 @@ func TestVerifierVerify(t *testing.T) { assert.Empty(t, sig.Metadata) }, }, - { - uc: "invalid untagged signature is ignored", + "invalid untagged signature is ignored": { opts: []VerifierOption{ WithRequiredTag("foo"), WithExpiresTimestamp(false), @@ -1650,8 +1687,7 @@ func TestVerifierVerify(t *testing.T) { assert.Equal(t, map[string]string{"foo": "bar"}, sig.Metadata) }, }, - { - uc: "invalid untagged signature fails when validating all", + "invalid untagged signature fails when validating all": { opts: []VerifierOption{ WithValidateAllSignatures(), WithExpiresTimestamp(false), @@ -1688,8 +1724,7 @@ func TestVerifierVerify(t *testing.T) { require.Empty(t, results) }, }, - { - uc: "multiple valid signatures with different keys and metadata", + "multiple valid signatures with different keys and metadata": { opts: []VerifierOption{ WithValidateAllSignatures(), WithExpiresTimestamp(false), @@ -1792,13 +1827,14 @@ func TestVerifierVerify(t *testing.T) { assert.Equal(t, "ed25519", sig.Metadata) }, }, - { - uc: "tag-specific negotiation", + "tag-specific negotiation": { opts: []VerifierOption{ - WithRequiredTag("profile", WithSignatureNegotiation( - WithParameter("audience", "service-a"), - WithParameter("challenge", Token("example")), - )), + WithRequiredTag("profile", + WithSignatureNegotiation( + WithParameter("audience", "service-a"), + WithParameter("challenge", Token("example")), + ), + ), }, msg: &Message{ Method: http.MethodPost, @@ -1822,10 +1858,11 @@ func TestVerifierVerify(t *testing.T) { assert.Equal(t, `sig=();created;expires;tag="profile";audience="service-a";challenge=example`, hdr.Get(headerAcceptSignature)) }, }, - { - uc: "inherited global negotiation", + "inherited global negotiation": { opts: []VerifierOption{ - WithSignatureNegotiation(WithParameter("audience", "service-a")), + WithSignatureNegotiation( + WithParameter("audience", "service-a"), + ), WithRequiredTag("profile"), }, msg: &Message{ @@ -1851,7 +1888,7 @@ func TestVerifierVerify(t *testing.T) { }, }, } { - t.Run(tc.uc, func(t *testing.T) { + t.Run(uc, func(t *testing.T) { kr := NewKeyResolverMock(t) tc.configureResolver(t, kr) @@ -1904,8 +1941,13 @@ func TestVerifierVerify(t *testing.T) { inputBytes[0] = 'X' // Neither signer nor verifier may retain this mutable input. for _, opts := range [][]VerifyOption{ - {WithParameter("audience", "service-a")}, - {WithParameter("audience", "service-a"), WithRequiredParameters("mode")}, + { + WithParameter("audience", "service-a"), + }, + { + WithParameter("audience", "service-a"), + WithRequiredParameters("mode"), + }, nil, } { results, err := ver.Verify(msg, opts...) @@ -1925,7 +1967,11 @@ func TestVerifierVerify(t *testing.T) { require.ErrorIs(t, err, ErrParameter) // A Structured-Fields Token is not interchangeable with a String. - withString, err := NewVerifier(key, WithRequiredTag("profile", WithParameter("mode", "example"))) + withString, err := NewVerifier(key, + WithRequiredTag("profile", + WithParameter("mode", "example"), + ), + ) require.NoError(t, err) _, err = withString.Verify(msg) require.ErrorIs(t, err, ErrParameter) From 06e11cf69421285a76bfd829a5c71fc2bfd64de7 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Wed, 4 Nov 2026 16:16:32 +0100 Subject: [PATCH 31/33] readme updated --- README.md | 238 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 231 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 478c46e..77a6830 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,16 @@ [![CI](https://github.com/dadrus/httpsig/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/dadrus/httpsig/actions/workflows/ci.yml) [![Codecov](https://codecov.io/gh/dadrus/httpsig/branch/main/graph/badge.svg)](https://codecov.io/gh/dadrus/httpsig) -[![Go Report Card](https://goreportcard.com/badge/github.com/dadrus/httpsig)](https://goreportcard.com/report/github.com/dadrus/httpsig) [![Go Reference](https://pkg.go.dev/badge/github.com/dadrus/httpsig.svg)](https://pkg.go.dev/github.com/dadrus/httpsig) -## Introduction +## Introduction and Scope `httpsig` is a library that facilitates the signing and verification of HTTP requests in compliance with the [RFC 9421 HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421.html) standard. -## Standalone Signing and Verification +Its `Message` abstraction allows integration with different HTTP frameworks. + +## Usage + +### Standalone Signing and Verification To sign an HTTP request, first, create a `Signer` instance using your preferred key and signing algorithm: @@ -102,12 +105,16 @@ verified, err := verifier.Verify(msg) // error handling goes here ``` +Global verifier options act as defaults for all required tags. Explicit tag-specific options take precedence (for example, a tag's `WithComponents` replaces the global component list), while required, forbidden, and expected signature parameters are additive. Automatic signature negotiation reflects the effective requirements for each tag. + While the examples demonstrate signing a request and verifying a response, you can also verify requests and sign responses. Both the `Verifier.Verify()` and `Signer.Sign()` methods require a `Message` object, which can be created for requests and responses on both client and server sides using the following functions: * `MessageFromRequest` - creates a `Message` from an `http.Request`. Can be used for outbound (client-side) and inbound (server-side) requests. * `MessageFromResponse` - creates a `Message` from an `http.Response`. Can be used for inbound (client-side) responses from a server. * `MessageForResponse` - creates a Message from an outbound (server-side) response. +For middleware integration, see [HTTP Frameworks](#http-frameworks). + Both the `Signer` and `Verifier` respect the `"content-digest"` component identifier as highlighted in the [Security Considerations](https://www.rfc-editor.org/rfc/rfc9421.html#name-message-content) of the RFC. This is handled as follows: * On the `Signer` side, if `"content-digest"` is configured to be included via the `WithComponents` option and the `WithContentDigestAlgorithm` option is not used, the implementation will calculate a message digest over the body using the `sha-256` and `sha-512` algorithms (the only supported algorithms according to [RFC 9530](https://www.rfc-editor.org/rfc/rfc9530.html)). It will then create or replace the `"Content-Digest"` header with the calculated values in addition to the signature-related headers. If the `WithContentDigestAlgorithm` option is used, the message digest will be calculated using the specified algorithm and the `"Content-Digest"` header will be created or replaced with that value. @@ -119,7 +126,35 @@ Both the `Signer` and `Verifier` respect the `"content-digest"` component identi > > For server-side request handling, consider using `http.MaxBytesReader`; for other contexts, use `io.LimitedReader` or an equivalent mechanism. The library restores the body after reading it, so it can still be consumed by subsequent handlers, but it does not impose global body size limits on behalf of the application. -## Signature Negotiation +### Key Resolution + +A `Verifier` uses a `KeyResolver` to select the key for each signature. `ResolveKey` receives `SignatureInfo` before cryptographic verification, so its parameters, components, and message are still unverified. + +```go +type trustedKeys map[string]httpsig.Key + +func (keys trustedKeys) ResolveKey(_ context.Context, info httpsig.SignatureInfo) (httpsig.KeyInfo, error) { + keyID, ok := info.Parameters.KeyID() + if !ok { + return httpsig.KeyInfo{}, errors.New("missing keyid") + } + + key, ok := keys[keyID] + if !ok { + return httpsig.KeyInfo{}, errors.New("unknown key") + } + + return httpsig.KeyInfo{Key: key}, nil +} +``` + +This example looks up a previously trusted key by `keyid`. A fixed `httpsig.Key` can also serve directly as a `KeyResolver`. `KeyInfo` can carry optional application-specific `Metadata`. + +### Identity + +After `Verify` succeeds, `VerifiedSignature` provides the verified signature parameters and covered component values. The application uses these values according to its protocol to establish a principal and make authorization decisions. Signature labels are not signed and must not be used as identities. + +### Signature Negotiation The library not only supports signing and verifying HTTP messages but also facilitates signature negotiation, as defined in the [RFC 9421 HTTP Message Signatures - Requesting Signatures](https://www.rfc-editor.org/rfc/rfc9421.html#name-requesting-signatures), by utilizing the `"Accept-Signature"` header. @@ -135,7 +170,7 @@ The library not only supports signing and verifying HTTP messages but also facil > > As a result, the current implementation does not enforce label consistency, even though you can specify them. The only reliable method to ensure effective signature negotiation is by utilizing the `tag` parameter, as also recommended in the statement above. -### Requesting Signatures on the Client-Side from the Server +#### Requesting Signatures on the Client-Side from the Server On the client side, you can request the server to sign the response by using the `AcceptSignatureBuilder`. This builder can be created with the `NewAcceptSignature` function, which accepts several options to specify parameters and components that you want the server to include in the response. Here’s an example: @@ -157,7 +192,7 @@ builder, err := httpsig.NewAcceptSignature( // specify whether you want the created time stamp to be included httpsig.WithCreatedTimestamp(true), // specify whether you want the expires time stamp to be included - httpsig.WithExpiredTimestamp(true), + httpsig.WithExpiresTimestamp(true), ) // error handling goes here @@ -170,7 +205,7 @@ err = builder.Build(req.Context(), req.Header, httpsig.WithParameter("nonce", no When the above code executes, it will add an `"Accept-Signature"` header to the request with a value like: `bar=("@status", "content-digest";req, "content-digest");keyid="foo";alg="ecdsa-p256-sha256";nonce="...";tag="awesome-app";created;expires`. -### Requesting Signatures on the Server-Side from the Client +#### Requesting Signatures on the Server-Side from the Client Signature negotiation on the server side works differently from the client-side. Instead of using the `AcceptSignatureBuilder`, you specify the corresponding options when creating the `Verifier`. This ensures that there are no discrepancies between what the `Verifier` expects and what is included in the `"Accept-Signature"` response header if an expected signature is not present or required parameters/components are missing. Here’s an example, building on the earlier `Verifier` creation example: @@ -219,3 +254,192 @@ For automatic negotiation, the configured `NonceGetter` runs while `Verify` prep > [!NOTE] > The `WithSignatureNegotiation` option at the top level (outside the `WithRequiredTag` option) is mutually exclusive with the `WithValidateAllSignatures` option. However, you can still use `WithSignatureNegotiation` at the top level if you want to apply the same configuration for all expected tagged signatures, thereby simplifying your code. + +### Reusing Signers and Verifiers + +A `Signer` or `Verifier` represents a reusable signing or verification policy. Create an instance once per policy and reuse it across messages. This allows most of the configuration work to happen upfront, keeping the per-message overhead low. Message-specific values can be supplied through per-call options. + +## Protocols and Profiles + +### WIMSE Workload-to-Workload HTTP Signatures + +The [WIMSE HTTP Signatures draft](https://datatracker.ietf.org/doc/html/draft-ietf-wimse-http-signature-08) binds signed requests to Workload Identity Tokens (WITs). For an ordinary request carrying a `Workload-Identity-Token` header: + +```go +// Sender +signer, err := httpsig.NewSigner( + httpsig.Key{Material: privateKey, Algorithm: httpsig.Ed25519}, + httpsig.WithTag("wimse-workload-to-workload"), + httpsig.WithComponents("@method", "@path", "@query", "workload-identity-token"), +) + +req.Header, err = signer.Sign(httpsig.MessageFromRequest(req), + httpsig.WithParameter(httpsig.Nonce, nonce), + httpsig.WithParameter("wimse-aud", audience), +) + +// Recipient +verifier, err := httpsig.NewVerifier(witKeyResolver, + httpsig.WithRequiredTag("wimse-workload-to-workload", + httpsig.WithComponents("@method", "@path", "@query", "workload-identity-token"), + httpsig.WithRequiredParameters(httpsig.Nonce), + httpsig.WithForbiddenParameters(httpsig.KeyID, httpsig.Alg), + httpsig.WithParameter("wimse-aud", expectedAudience), + ), +) + +result, err = verifier.Verify(httpsig.MessageFromRequest(req)) +``` + +Include `content-digest` for requests with a body and cover any other headers required by the draft when present. The application validates the WIT and enforces replay rules. + +### Web Bot Auth + +The [Web Bot Auth draft](https://datatracker.ietf.org/doc/html/draft-ietf-webbotauth-httpsig-protocol-01) uses a signed `Signature-Agent` dictionary member to advertise the signer's key directory. + +```go +// Sender: the dictionary member matches the signature label. +req.Header.Set("Signature-Agent", `sig1="https://agent.example/keys.jwks"`) +signer, err := httpsig.NewSigner( + httpsig.Key{Material: privateKey, Algorithm: httpsig.Ed25519}, + httpsig.WithLabel("sig1"), + httpsig.WithTag("web-bot-auth"), + httpsig.WithKeyID(jwkThumbprint), + httpsig.WithComponents("@authority", `signature-agent;key="sig1"`), +) + +req.Header, err = signer.Sign(httpsig.MessageFromRequest(req)) + +// Recipient +verifier, err := httpsig.NewVerifier(webBotKeyResolver, + httpsig.WithRequiredTag("web-bot-auth", + httpsig.WithComponents("@authority"), + httpsig.WithRequiredParameters(httpsig.KeyID), + ), +) + +verified, err := verifier.Verify(httpsig.MessageFromRequest(req)) +``` + +`webBotKeyResolver` resolves keys from `Signature-Agent` and validates their thumbprints. + +### AAuth + +The [AAuth Protocol draft](https://datatracker.ietf.org/doc/html/draft-hardt-oauth-aauth-protocol-11) authenticates agents using HTTP Message Signatures and a signed `Signature-Key` header containing key information. + +```go +// Agent +req.Header.Set("Signature-Key", `sig=jwt;jwt="`+agentToken+`"`) +signer, err := httpsig.NewSigner( + httpsig.Key{Material: privateKey, Algorithm: httpsig.Ed25519}, + httpsig.WithLabel("sig"), + httpsig.WithTTL(0), + httpsig.WithComponents("@method", "@authority", "@path", "signature-key"), +) +req.Header, err = signer.Sign(httpsig.MessageFromRequest(req)) + +// Resource server +verifier, err := httpsig.NewVerifier(aauthKeyResolver, + httpsig.WithValidateAllSignatures(), + httpsig.WithComponents("@method", "@authority", "@path", "signature-key"), + httpsig.WithExpiresTimestamp(false), + httpsig.WithMaxAge(time.Minute), +) +_, err = verifier.Verify(httpsig.MessageFromRequest(req)) +``` + +`aauthKeyResolver` validates the agent token and resolves its signing key via `Signature-Key`. For requests with bodies to person or access servers and revocation endpoints, also cover `content-digest` and `content-type`. + +### OAuth Proof-of-Possession Tokens + +The [OAuth HTTP Signature PoP draft](https://datatracker.ietf.org/doc/html/draft-richer-oauth-httpsig-03) binds access tokens to signing keys. For a resource request carrying an `Authorization` header: + +```go +// Client +signer, err := httpsig.NewSigner( + httpsig.Key{Material: privateKey, Algorithm: httpsig.Ed25519}, + httpsig.WithTag("httpsig-oauth"), + httpsig.WithTTL(0), + httpsig.WithComponents("@method", "@target-uri", "authorization"), +) + +req.Header, err = signer.Sign(httpsig.MessageFromRequest(req), + httpsig.WithParameter(httpsig.Nonce, nonce), +) + +// Resource server +verifier, err := httpsig.NewVerifier(tokenBoundKeyResolver, + httpsig.WithRequiredTag("httpsig-oauth", + httpsig.WithComponents("@method", "@target-uri", "authorization"), + httpsig.WithExpiresTimestamp(false), + httpsig.WithRequiredParameters(httpsig.Nonce), + httpsig.WithForbiddenParameters(httpsig.KeyID, httpsig.Alg, "pub"), + ), +) + +_, err = verifier.Verify(httpsig.MessageFromRequest(req)) +``` + +The resource server validates the access token, supplies its bound key through `KeyResolver`, and checks nonce reuse. For requests with bodies, also cover `content-digest`. + +## HTTP Frameworks + +The examples below verify incoming requests. The same signing, verification, and signature negotiation APIs can be used in client middleware and for responses as well. + +**net/http** + +```go +http.Handle("/api", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + // Retain Verify's result if a principal is needed for the next handler. + if _, err := verifier.Verify(httpsig.MessageFromRequest(r)); err != nil { + http.Error(w, "Unauthorized", http.StatusUnauthorized) + + return + } + + handler.ServeHTTP(w, r) +})) +``` + +**Gin** + +```go +router.Use(func(c *gin.Context) { + // Retain Verify's result if a principal is needed downstream. + if _, err := verifier.Verify(httpsig.MessageFromRequest(c.Request)); err != nil { + c.AbortWithStatus(http.StatusUnauthorized) + + return + } + + c.Next() +}) +``` + +**Fiber v3 (`fasthttp`)** + +```go +app.Use(func(c fiber.Ctx) error { + req, err := adaptor.ConvertRequest(c, true) + if err != nil { + return err + } + + // Retain Verify's result if a principal is needed downstream. + if _, err := verifier.Verify(httpsig.MessageFromRequest(req)); err != nil { + return c.SendStatus(fiber.StatusUnauthorized) + } + + return c.Next() +}) +``` + +## Security Considerations + +* **Coverage:** Require the components your application relies on. For messages with bodies, sign and verify `content-digest` when body integrity matters. +* **Key trust:** `KeyResolver` receives unverified message data. Select and validate keys according to the application protocol; never treat a reported key ID as proof of identity. +* **Replay:** Enforce the required freshness and nonce checks after successful signature verification. +* **Multiple signatures:** Labels are not signed, and `VerificationResult` has no defined order. Choose the required tags or validate all signatures as appropriate. +* **HTTP intermediaries:** Proxies can rewrite covered components. Apply the body-size limits described above before hashing untrusted content. + +See [RFC 9421 Security Considerations](https://www.rfc-editor.org/rfc/rfc9421.html#section-7). From c63ee968ab5c51a40451c5a225b9b034866713e3 Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Wed, 4 Nov 2026 16:28:34 +0100 Subject: [PATCH 32/33] Comment extended to cover the order of the verified signatures --- verifier.go | 1 + 1 file changed, 1 insertion(+) diff --git a/verifier.go b/verifier.go index 14a29e2..dad0abd 100644 --- a/verifier.go +++ b/verifier.go @@ -35,6 +35,7 @@ type VerifiedSignature struct { // VerificationResult contains the signatures selected and successfully // verified during one call to Verifier.Verify. +// The order of the signatures is not guaranteed. type VerificationResult []VerifiedSignature // Verifier verifies HTTP message signatures according to its configured From 3e301ead876440107dfc6d89b448d5a2055d3deb Mon Sep 17 00:00:00 2001 From: Dimitrij Drus Date: Thu, 5 Nov 2026 00:19:10 +0100 Subject: [PATCH 33/33] further readme updates --- README.md | 142 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 87 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 77a6830..c815f63 100644 --- a/README.md +++ b/README.md @@ -4,28 +4,30 @@ ## Introduction and Scope -`httpsig` is a library that facilitates the signing and verification of HTTP requests in compliance with the [RFC 9421 HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421.html) standard. +`httpsig` is a library for signing and verifying HTTP requests and responses according to [RFC 9421 (HTTP Message Signatures)](https://www.rfc-editor.org/rfc/rfc9421.html). It combines reusable signing and verification policies with support for application-specific signature requirements and signature negotiation using `Accept-Signature`. -Its `Message` abstraction allows integration with different HTTP frameworks. +The `Message` abstraction keeps these capabilities independent of any particular HTTP framework. For API details and option semantics, see the [Go reference](https://pkg.go.dev/github.com/dadrus/httpsig). ## Usage ### Standalone Signing and Verification -To sign an HTTP request, first, create a `Signer` instance using your preferred key and signing algorithm: +The following snippets show two independent flows: signing an outgoing request and verifying a received response. They assume application-provided keys and other values; routine error handling is abbreviated. + +To sign a request, configure a `Signer` with the signing key and the HTTP components to protect: ```go -// Create a signer. -signer, err := httpsig.NewSigner( +// Configure the signing policy. +signer, err := httpsig.NewSigner( // specify a key - httpsig.Key{Material: privKey, Algorithm: httpsig.EcdsaP256Sha256}, + httpsig.Key{Material: privKey, Algorithm: httpsig.EcdsaP256Sha256}, // the keyid parameter for the above key httpsig.WithKeyID("key1"), // specify the required options // duration for which the signature should be valid - httpsig.WithTTL(5 * time.Second), + httpsig.WithTTL(5 * time.Second), // which components should be protected by a signature - httpsig.WithComponents("@authority", "@method", "x-my-fancy-header"), + httpsig.WithComponents("@authority", "@method", "x-my-fancy-header"), // a tag for your specific application httpsig.WithTag("myapp"), ) @@ -34,20 +36,24 @@ signer, err := httpsig.NewSigner( // Create a request req, err := http.NewRequestWithContext(context.Background(), "GET", "https://some-url.com", nil) // error handling goes here +req.Header.Set("X-My-Fancy-Header", "example-value") + +nonce := ... // generate a nonce // Sign the request header, err := signer.Sign( - httpsig.MessageFromRequest(req), + httpsig.MessageFromRequest(req), // add a nonce if required - httpsig.WithParameter("nonce", someNonce) + httpsig.WithParameter(httpsig.Nonce, nonce), ) // error handling goes here -// Add the signature to the request +// MessageFromRequest clones the headers; use the headers returned by Sign. req.Header = header +// send the request ``` -To verify a response, create a `Verifier` using your preferred key and signing algorithm: +To verify a response, create a `Verifier` with a `KeyResolver` that supplies trusted verification keys (see [Key Resolution](#key-resolution)). `WithValidateAllSignatures` checks every signature present in the message; use `WithRequiredTag` instead when your protocol expects particular signed tags. ```go // Receive a response from the server @@ -56,7 +62,7 @@ resp, err := client.Post("https://some-url.com", "application/json", &buf) // Create a verifier verifier, err := httpsig.NewVerifier( - // specify a key resolver to resolve the key used by the client + // specify a key resolver to resolve the key keyResolver, // specify the required options // which response components are expected to be protected @@ -79,9 +85,9 @@ verified, err := verifier.Verify(httpsig.MessageFromResponse(resp)) ``` -Once `Verify` succeeds, the application can inspect the `verified` object and perform its own policies, like e.g., the nonce correlation and replay checks. +Once `Verify` succeeds, your application can inspect the `verified` object and enforce protocol-specific rules, such as nonce correlation, replay protection, and authorization. -If you need to validate a signature created by a specific application (identified by a tag), use the `WithRequiredTag` option when creating the verifier. This option allows you to specify a tag along with the same options as the `NewVerifier` function. Here’s an example: +If a protocol requires a signature with a particular `tag`, use `WithRequiredTag`. Unlike `WithValidateAllSignatures`, tag-based verification selects signatures carrying the required tag; unrelated signatures are not verified unless all-signature verification is also enabled. For example: ```go verifier, err := httpsig.NewVerifier( @@ -105,21 +111,20 @@ verified, err := verifier.Verify(msg) // error handling goes here ``` -Global verifier options act as defaults for all required tags. Explicit tag-specific options take precedence (for example, a tag's `WithComponents` replaces the global component list), while required, forbidden, and expected signature parameters are additive. Automatic signature negotiation reflects the effective requirements for each tag. +Global verifier options act as defaults for required tags. Tag-specific options take precedence (for example, `WithComponents` replaces the global component list), while required, forbidden, and expected signature-parameter constraints are additive. Automatic signature negotiation uses these effective per-tag requirements. -While the examples demonstrate signing a request and verifying a response, you can also verify requests and sign responses. Both the `Verifier.Verify()` and `Signer.Sign()` methods require a `Message` object, which can be created for requests and responses on both client and server sides using the following functions: +The same APIs also verify incoming requests and sign outgoing responses. Both `Signer.Sign` and `Verifier.Verify` operate on a `Message`, created for the corresponding HTTP direction: -* `MessageFromRequest` - creates a `Message` from an `http.Request`. Can be used for outbound (client-side) and inbound (server-side) requests. -* `MessageFromResponse` - creates a `Message` from an `http.Response`. Can be used for inbound (client-side) responses from a server. -* `MessageForResponse` - creates a Message from an outbound (server-side) response. +* `MessageFromRequest` — outbound client requests or inbound server requests. +* `MessageFromResponse` — responses received by clients. +* `MessageForResponse` — responses produced by servers. For middleware integration, see [HTTP Frameworks](#http-frameworks). -Both the `Signer` and `Verifier` respect the `"content-digest"` component identifier as highlighted in the [Security Considerations](https://www.rfc-editor.org/rfc/rfc9421.html#name-message-content) of the RFC. This is handled as follows: - -* On the `Signer` side, if `"content-digest"` is configured to be included via the `WithComponents` option and the `WithContentDigestAlgorithm` option is not used, the implementation will calculate a message digest over the body using the `sha-256` and `sha-512` algorithms (the only supported algorithms according to [RFC 9530](https://www.rfc-editor.org/rfc/rfc9530.html)). It will then create or replace the `"Content-Digest"` header with the calculated values in addition to the signature-related headers. If the `WithContentDigestAlgorithm` option is used, the message digest will be calculated using the specified algorithm and the `"Content-Digest"` header will be created or replaced with that value. +To protect a message body, include `"content-digest"` among the covered components (see [RFC 9421's discussion of message content](https://www.rfc-editor.org/rfc/rfc9421.html#name-message-content)): -* On the `Verifier` side, verification of the corresponding hash values is done by default with no additional configuration required. If the `"Signature-Input"` header value contains a `"content-digest"` component, the implementation expects the `"Content-Digest"` header to be present and uses the supplied algorithm names and values to calculate the digest over the body and compare these values to the received ones. If the `"Content-Digest"` header is missing, references unsupported hash algorithms (only `sha-256` and `sha-512` are supported), or there is a mismatch between the calculated and provided values, the message verification will fail with an error. +* **Signing:** The `Signer` calculates the digest and creates or replaces `Content-Digest` before signing. By default, it uses both `sha-256` and `sha-512` (as defined in [RFC 9530](https://www.rfc-editor.org/rfc/rfc9530.html)); `WithContentDigestAlgorithm` selects a single algorithm. +* **Verification:** If the signature covers `content-digest`, the `Verifier` also checks the digest against the body. Verification fails if the header is missing, no supported digest is present, or any supported digest mismatches. Only `sha-256` and `sha-512` are checked. > [!IMPORTANT] > Signing or verifying `"content-digest"` requires reading the message body. Since request and response bodies may be attacker-controlled input, callers are responsible for enforcing appropriate body size limits before passing messages to this library. @@ -156,32 +161,23 @@ After `Verify` succeeds, `VerifiedSignature` provides the verified signature par ### Signature Negotiation -The library not only supports signing and verifying HTTP messages but also facilitates signature negotiation, as defined in the [RFC 9421 HTTP Message Signatures - Requesting Signatures](https://www.rfc-editor.org/rfc/rfc9421.html#name-requesting-signatures), by utilizing the `"Accept-Signature"` header. +Signature negotiation uses the `Accept-Signature` header defined in [RFC 9421](https://www.rfc-editor.org/rfc/rfc9421.html#name-requesting-signatures). A client can explicitly request a signed response; a server can derive a request for missing client signatures from its verification policy. -> [!NOTE] -> While [Chapter 5.2 - Processing an Accept-Signature](https://www.rfc-editor.org/rfc/rfc9421.html#name-processing-an-accept-signat) of the RFC mandates that -> -> > ... a target message MUST have the same label ... -> -> this requirement conflicts with [Chapter 7.2.5 - Signature Labels](https://www.rfc-editor.org/rfc/rfc9421.html#name-signature-labels), which clearly states: -> -> > An intermediary is allowed to relabel an existing signature when processing the message. -> > Therefore, applications **should not** rely on specific labels being present, and applications **should not** put semantic meaning on the labels themselves. Instead, additional signature parameters can be used to convey whatever additional meaning is required to be attached to, and covered by, the signature. In particular, the `tag` parameter can be used to define an application-specific value. -> -> As a result, the current implementation does not enforce label consistency, even though you can specify them. The only reliable method to ensure effective signature negotiation is by utilizing the `tag` parameter, as also recommended in the statement above. +> [!NOTE] +> [RFC 9421 §5.2](https://www.rfc-editor.org/rfc/rfc9421.html#name-processing-an-accept-signat) requires a negotiated signature to use the requested label, but [§7.2.5](https://www.rfc-editor.org/rfc/rfc9421.html#name-signature-labels) permits intermediaries to relabel signatures and warns against assigning labels application semantics. `httpsig` therefore does not enforce label consistency. Use the signed `tag` parameter to identify application-specific signatures instead. #### Requesting Signatures on the Client-Side from the Server -On the client side, you can request the server to sign the response by using the `AcceptSignatureBuilder`. This builder can be created with the `NewAcceptSignature` function, which accepts several options to specify parameters and components that you want the server to include in the response. Here’s an example: +Use `AcceptSignatureBuilder` when a client needs to request a signed response. It constructs the `Accept-Signature` header independently of any verifier policy, so the client can specify the components and parameters it expects the server to sign: ```go // create a builder (all options are optional) builder, err := httpsig.NewAcceptSignature( - // request a key ID and signing algorithm + // request a key identifier and signing algorithm httpsig.WithKeyID("foo"), // specify which signature algorithm the peer should use httpsig.WithSignatureAlgorithm(httpsig.EcdsaP256Sha256), - // specify which label should the server use when creating the response + // request the label and covered components httpsig.WithLabel("bar"), // specify which components should be covered by the signature httpsig.WithComponents("@status", "content-digest;req", "content-digest"), @@ -203,11 +199,20 @@ err = builder.Build(req.Context(), req.Header, httpsig.WithParameter("nonce", no // error handling goes here ``` -When the above code executes, it will add an `"Accept-Signature"` header to the request with a value like: `bar=("@status", "content-digest";req, "content-digest");keyid="foo";alg="ecdsa-p256-sha256";nonce="...";tag="awesome-app";created;expires`. +This adds an `Accept-Signature` header with a value such as: + +```http +Accept-Signature: bar=("@status" "content-digest";req "content-digest");created;expires;keyid="foo";alg="ecdsa-p256-sha256";nonce="...";tag="awesome-app" +Want-Content-Digest: sha-256=2 +``` + +The `Want-Content-Digest` header is also added because the requested signature covers `content-digest`. #### Requesting Signatures on the Server-Side from the Client -Signature negotiation on the server side works differently from the client-side. Instead of using the `AcceptSignatureBuilder`, you specify the corresponding options when creating the `Verifier`. This ensures that there are no discrepancies between what the `Verifier` expects and what is included in the `"Accept-Signature"` response header if an expected signature is not present or required parameters/components are missing. Here’s an example, building on the earlier `Verifier` creation example: +On the server side, the `Verifier` can derive `Accept-Signature` requirements from its configured policy. This avoids defining component and parameter requirements separately for verification and negotiation. If a required signature, component, or parameter is missing, `Verify` returns an error wrapping `NoApplicableSignatureError`; use `errors.As` to retrieve it and call `Negotiate` to add the prepared headers to the response. An invalid cryptographic signature is still a verification failure, not a negotiation request. + +For example, extending the earlier tag-based verifier: ```go verifier, err := httpsig.NewVerifier( @@ -310,10 +315,10 @@ signer, err := httpsig.NewSigner( req.Header, err = signer.Sign(httpsig.MessageFromRequest(req)) -// Recipient +// Recipient: resolve the covered Signature-Agent member dynamically. verifier, err := httpsig.NewVerifier(webBotKeyResolver, httpsig.WithRequiredTag("web-bot-auth", - httpsig.WithComponents("@authority"), + httpsig.WithComponents("@authority", `signature-agent;key="sig1"`), httpsig.WithRequiredParameters(httpsig.KeyID), ), ) @@ -321,7 +326,7 @@ verifier, err := httpsig.NewVerifier(webBotKeyResolver, verified, err := verifier.Verify(httpsig.MessageFromRequest(req)) ``` -`webBotKeyResolver` resolves keys from `Signature-Agent` and validates their thumbprints. +`webBotKeyResolver` implementation needs to resolve the signing key using the `Signature-Agent` member covered by the signature. ### AAuth @@ -380,7 +385,7 @@ verifier, err := httpsig.NewVerifier(tokenBoundKeyResolver, _, err = verifier.Verify(httpsig.MessageFromRequest(req)) ``` -The resource server validates the access token, supplies its bound key through `KeyResolver`, and checks nonce reuse. For requests with bodies, also cover `content-digest`. +The resource server validates the access token, supplies its bound key through `KeyResolver`, and checks nonce reuse. For requests with bodies, also cover `content-digest`. When verifying `@target-uri` on incoming requests, use the externally visible absolute URL, reconstructed from trusted server or proxy configuration. ## HTTP Frameworks @@ -390,13 +395,16 @@ The examples below verify incoming requests. The same signing, verification, and ```go http.Handle("/api", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - // Retain Verify's result if a principal is needed for the next handler. - if _, err := verifier.Verify(httpsig.MessageFromRequest(r)); err != nil { + result, err := verifier.Verify(httpsig.MessageFromRequest(r)) + if err != nil { http.Error(w, "Unauthorized", http.StatusUnauthorized) return } + // establish a principal from the result object + // and propagate it downstream + handler.ServeHTTP(w, r) })) ``` @@ -405,13 +413,16 @@ http.Handle("/api", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request ```go router.Use(func(c *gin.Context) { - // Retain Verify's result if a principal is needed downstream. - if _, err := verifier.Verify(httpsig.MessageFromRequest(c.Request)); err != nil { + result, err := verifier.Verify(httpsig.MessageFromRequest(c.Request)) + if err != nil { c.AbortWithStatus(http.StatusUnauthorized) return } + // establish a principal from the result object + // and propagate it downstream + c.Next() }) ``` @@ -420,16 +431,38 @@ router.Use(func(c *gin.Context) { ```go app.Use(func(c fiber.Ctx) error { - req, err := adaptor.ConvertRequest(c, true) + targetURL, err := url.Parse(c.FullURL()) if err != nil { return err } - // Retain Verify's result if a principal is needed downstream. - if _, err := verifier.Verify(httpsig.MessageFromRequest(req)); err != nil { + headers := make(http.Header) + for name, values := range c.GetReqHeaders() { + for _, value := range values { + headers.Add(name, value) + } + } + + msg := &httpsig.Message{ + Context: c.Context(), + Method: c.Method(), + Authority: c.Host(), + URL: targetURL, + Header: headers, + Body: func() (io.ReadCloser, error) { + return io.NopCloser(bytes.NewReader(c.BodyRaw())), nil + }, + IsRequest: true, + } + + result, err := verifier.Verify(msg) + if err != nil { return c.SendStatus(fiber.StatusUnauthorized) } + // establish a principal from the result object + // and propagate it downstream + return c.Next() }) ``` @@ -437,9 +470,8 @@ app.Use(func(c fiber.Ctx) error { ## Security Considerations * **Coverage:** Require the components your application relies on. For messages with bodies, sign and verify `content-digest` when body integrity matters. -* **Key trust:** `KeyResolver` receives unverified message data. Select and validate keys according to the application protocol; never treat a reported key ID as proof of identity. -* **Replay:** Enforce the required freshness and nonce checks after successful signature verification. +* **Key trust:** `KeyResolver` receives unverified message data. Select and validate keys according to your application protocol. +* **Replay:** Enforce the required nonce checks after successful signature verification. * **Multiple signatures:** Labels are not signed, and `VerificationResult` has no defined order. Choose the required tags or validate all signatures as appropriate. -* **HTTP intermediaries:** Proxies can rewrite covered components. Apply the body-size limits described above before hashing untrusted content. See [RFC 9421 Security Considerations](https://www.rfc-editor.org/rfc/rfc9421.html#section-7).