Skip to content

Commit baf75fb

Browse files
authored
feat: Support for RFC 9651 types in signature parameters (#201)
1 parent 8c7ee2d commit baf75fb

9 files changed

Lines changed: 482 additions & 224 deletions

‎README.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
## Introduction and Scope
66

7-
`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).
7+
`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). In addition to the Structured Fields types defined by [RFC 8941](https://www.rfc-editor.org/rfc/rfc8941.html?utm_source=chatgpt.com), it also supports the `Date` and `Display String` types introduced by [RFC 9651](https://www.rfc-editor.org/rfc/rfc9651.html?utm_source=chatgpt.com).
88

99
Its key features include:
1010

@@ -48,6 +48,12 @@ signer, err := httpsig.NewSigner(
4848
httpsig.WithComponents("@authority", "@method", "x-my-fancy-header"),
4949
// a tag for your specific application
5050
httpsig.WithTag("myapp"),
51+
// custom parameter
52+
httpsig.WithParameter("first", "value 1"),
53+
// custom parameter
54+
httpsig.WithParameter("second", httpsig.DisplayString("öäü")),
55+
// custom parameter
56+
httpsig.WithParameter("third", httpsig.Date(time.Now())),
5157
)
5258
// error handling goes here
5359

‎httpsig.go‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -189,8 +189,8 @@ const (
189189
// SignatureParameters contains all signature parameters transmitted in a
190190
// Signature-Input entry, including profile-specific extensions. Keys are the
191191
// parameter names; values are decoded Structured Fields bare items (for
192-
// example string, Token, int64, float64, bool, or []byte).
193-
// Display Strings are exposed as ordinary strings.
192+
// example string, Token, DisplayString, time.Time, int64, float64, bool, or
193+
// []byte).
194194
type SignatureParameters map[SignatureParameter]any
195195

196196
// KeyID returns the keyid parameter if present and of the expected type.
@@ -240,6 +240,10 @@ func (p SignatureParameters) Tag() (string, bool) {
240240
// strings when validating profile-specific signature parameters.
241241
type Token string
242242

243+
// DisplayString represents an RFC 9651 Structured Fields Display String.
244+
// Unlike an ordinary Structured Fields string, it may contain Unicode.
245+
type DisplayString string
246+
243247
// MessageSigner signs the complete HTTP signature base using an
244248
// application-provided implementation. The implementation is responsible for
245249
// all cryptographic processing and must return signature bytes in the format

‎integration_test.go‎

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import (
77
"crypto/rand"
88
"net/http"
99
"testing"
10+
"time"
1011

1112
"github.com/stretchr/testify/assert"
1213
"github.com/stretchr/testify/require"
@@ -19,12 +20,14 @@ func TestSignAndVerifyParsedSignatureRequest(t *testing.T) {
1920
require.NoError(t, err)
2021

2122
requests, err := ParseAcceptSignature(http.Header{headerAcceptSignature: {
22-
`sig1=("@method" "@authority");keyid="key1";nonce="abc";tag="app";created;audience="service-a"`,
23+
`sig1=("@method" "@authority");keyid="key1";nonce="abc";tag="app";created;audience="service-a";nickname=%"Gr%c3%bc%c3%9fe";reviewed=@1794000000`,
2324
}})
2425
require.NoError(t, err)
2526
require.Len(t, requests, 1)
2627

2728
request := requests[0]
29+
require.Equal(t, DisplayString("Grüße"), request.Extensions["nickname"])
30+
require.Equal(t, time.Unix(1794000000, 0), request.Extensions["reviewed"])
2831

2932
signer, err := NewSigner(
3033
Key{Material: privKey, Algorithm: EcdsaP256Sha256},
@@ -33,6 +36,8 @@ func TestSignAndVerifyParsedSignatureRequest(t *testing.T) {
3336
WithComponents(request.Components...),
3437
WithTag(request.Tag),
3538
WithParameter("audience", request.Extensions["audience"]),
39+
WithParameter("nickname", request.Extensions["nickname"]),
40+
WithParameter("reviewed", request.Extensions["reviewed"]),
3641
)
3742
require.NoError(t, err)
3843

@@ -46,7 +51,12 @@ func TestSignAndVerifyParsedSignatureRequest(t *testing.T) {
4651

4752
verifier, err := NewVerifier(
4853
Key{Material: privKey.Public(), Algorithm: EcdsaP256Sha256},
49-
WithRequiredTag(request.Tag, WithComponents(request.Components...), WithParameter("audience", "service-a")),
54+
WithRequiredTag(request.Tag,
55+
WithComponents(request.Components...),
56+
WithParameter("audience", "service-a"),
57+
WithParameter("nickname", DisplayString("Grüße")),
58+
WithParameter("reviewed", time.Unix(1794000000, 750000000).In(time.FixedZone("UTC+2", 2*60*60))),
59+
),
5060
)
5161
require.NoError(t, err)
5262

@@ -58,6 +68,8 @@ func TestSignAndVerifyParsedSignatureRequest(t *testing.T) {
5868
require.True(t, ok)
5969
assert.Equal(t, request.Nonce, nonce)
6070
assert.Equal(t, request.Label, verified[0].Label)
71+
assert.Equal(t, DisplayString("Grüße"), verified[0].Parameters["nickname"])
72+
assert.Equal(t, time.Unix(1794000000, 0), verified[0].Parameters["reviewed"])
6173
}
6274

6375
func TestParseAcceptSignatureBuilderOutput(t *testing.T) {
@@ -70,12 +82,16 @@ func TestParseAcceptSignatureBuilderOutput(t *testing.T) {
7082
WithComponents("@status", "content-digest;req", `@query-param;name="Pet"`),
7183
WithTag("awesome-app"),
7284
WithParameter("audience", "service-a"),
85+
WithParameter("nickname", DisplayString("Grüße")),
86+
WithParameter("reviewed", time.Unix(1794000000, 0)),
7387
WithExpiresTimestamp(false),
7488
)
7589
require.NoError(t, err)
7690

7791
header := http.Header{}
7892
require.NoError(t, builder.Build(context.Background(), header, WithParameter(Nonce, "abc")))
93+
assert.Contains(t, header.Get(headerAcceptSignature), `;nickname=%"Gr%c3%bc%c3%9fe"`)
94+
assert.Contains(t, header.Get(headerAcceptSignature), `;reviewed=@1794000000`)
7995

8096
requests, err := ParseAcceptSignature(header)
8197

@@ -88,7 +104,11 @@ func TestParseAcceptSignatureBuilderOutput(t *testing.T) {
88104
Tag: "awesome-app",
89105
Nonce: "abc",
90106
Created: true,
91-
Extensions: SignatureParameters{"audience": "service-a"},
107+
Extensions: SignatureParameters{
108+
"audience": "service-a",
109+
"nickname": DisplayString("Grüße"),
110+
"reviewed": time.Unix(1794000000, 0),
111+
},
92112
}}, requests)
93113
}
94114

‎options.go‎

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import (
44
"bytes"
55
"fmt"
66
"time"
7+
"unicode/utf8"
78

89
"github.com/dunglas/httpsfv"
910
)
@@ -238,12 +239,13 @@ func WithAlg() SignerOption {
238239
// WithParameter specifies an extension parameter for signing, verifying, or
239240
// requesting a signature, either statically or for a single call. It can also
240241
// be used in WithSignatureNegotiation. Extension values may be
241-
// string, Token, bool, int, int64, float64, or []byte. Standard RFC 9421
242+
// string, Token, DisplayString, time.Time (RFC 9651 Date), bool, int, int64,
243+
// float64, or []byte. DisplayString must contain valid UTF-8, and Date values
244+
// are transmitted with second precision. Standard RFC 9421
242245
// parameter names are reserved, except for a non-empty string nonce on Verify,
243246
// Sign, or AcceptSignatureBuilder.Build. Verification requirements are additive;
244247
// an invocation cannot override static requirements. Duplicate signing or
245-
// builder parameters are rejected. Do not use secret expected values: verification
246-
// compares them before the signature has been authenticated.
248+
// builder parameters are rejected.
247249
func WithParameter(name SignatureParameter, value any) parameterOption {
248250
return parameterOption{name: name, value: value}
249251
}
@@ -629,11 +631,20 @@ func normalizeParameter(option parameterOption) (parameterOption, error) {
629631
return option, fmt.Errorf("%w: %q is a reserved signature parameter", ErrParameter, option.name)
630632
}
631633

632-
switch v := option.value.(type) {
634+
switch val := option.value.(type) {
633635
case Token:
634-
option.value = httpsfv.Token(v)
636+
option.value = httpsfv.Token(val)
637+
case DisplayString:
638+
if !utf8.ValidString(string(val)) {
639+
return option, fmt.Errorf("%w: invalid UTF-8 in signature parameter %q", ErrParameter, option.name)
640+
}
641+
642+
option.value = httpsfv.DisplayString(val)
643+
case time.Time:
644+
// RFC 9651 Date values have Unix-second precision.
645+
option.value = time.Unix(val.Unix(), 0).UTC()
635646
case int:
636-
option.value = int64(v)
647+
option.value = int64(val)
637648
case string, bool, int64, float64, []byte, httpsfv.Token:
638649
default:
639650
return option, fmt.Errorf("%w: unsupported value type %T for signature parameter %q",

0 commit comments

Comments
 (0)