Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

## Introduction and Scope

`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).
`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).

Its key features include:

Expand Down Expand Up @@ -48,6 +48,12 @@ signer, err := httpsig.NewSigner(
httpsig.WithComponents("@authority", "@method", "x-my-fancy-header"),
// a tag for your specific application
httpsig.WithTag("myapp"),
// custom parameter
httpsig.WithParameter("first", "value 1"),
// custom parameter
httpsig.WithParameter("second", httpsig.DisplayString("öäü")),
// custom parameter
httpsig.WithParameter("third", httpsig.Date(time.Now())),
)
// error handling goes here

Expand Down
8 changes: 6 additions & 2 deletions httpsig.go
Original file line number Diff line number Diff line change
Expand Up @@ -189,8 +189,8 @@ 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, or []byte).
// Display Strings are exposed as ordinary strings.
// example string, Token, DisplayString, time.Time, int64, float64, bool, or
// []byte).
type SignatureParameters map[SignatureParameter]any

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

// DisplayString represents an RFC 9651 Structured Fields Display String.
// Unlike an ordinary Structured Fields string, it may contain Unicode.
type DisplayString string

// MessageSigner signs the complete HTTP signature base using an
// application-provided implementation. The implementation is responsible for
// all cryptographic processing and must return signature bytes in the format
Expand Down
26 changes: 23 additions & 3 deletions integration_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import (
"crypto/rand"
"net/http"
"testing"
"time"

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

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

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

signer, err := NewSigner(
Key{Material: privKey, Algorithm: EcdsaP256Sha256},
Expand All @@ -33,6 +36,8 @@ func TestSignAndVerifyParsedSignatureRequest(t *testing.T) {
WithComponents(request.Components...),
WithTag(request.Tag),
WithParameter("audience", request.Extensions["audience"]),
WithParameter("nickname", request.Extensions["nickname"]),
WithParameter("reviewed", request.Extensions["reviewed"]),
)
require.NoError(t, err)

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

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

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

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

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

requests, err := ParseAcceptSignature(header)

Expand All @@ -88,7 +104,11 @@ func TestParseAcceptSignatureBuilderOutput(t *testing.T) {
Tag: "awesome-app",
Nonce: "abc",
Created: true,
Extensions: SignatureParameters{"audience": "service-a"},
Extensions: SignatureParameters{
"audience": "service-a",
"nickname": DisplayString("Grüße"),
"reviewed": time.Unix(1794000000, 0),
},
}}, requests)
}

Expand Down
23 changes: 17 additions & 6 deletions options.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import (
"bytes"
"fmt"
"time"
"unicode/utf8"

"github.com/dunglas/httpsfv"
)
Expand Down Expand Up @@ -238,12 +239,13 @@ func WithAlg() SignerOption {
// 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
// string, Token, DisplayString, time.Time (RFC 9651 Date), bool, int, int64,
// float64, or []byte. DisplayString must contain valid UTF-8, and Date values
// are transmitted with second precision. Standard RFC 9421
// 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.
// builder parameters are rejected.
func WithParameter(name SignatureParameter, value any) parameterOption {
return parameterOption{name: name, value: value}
}
Expand Down Expand Up @@ -629,11 +631,20 @@ func normalizeParameter(option parameterOption) (parameterOption, error) {
return option, fmt.Errorf("%w: %q is a reserved signature parameter", ErrParameter, option.name)
}

switch v := option.value.(type) {
switch val := option.value.(type) {
case Token:
option.value = httpsfv.Token(v)
option.value = httpsfv.Token(val)
case DisplayString:
if !utf8.ValidString(string(val)) {
return option, fmt.Errorf("%w: invalid UTF-8 in signature parameter %q", ErrParameter, option.name)
}

option.value = httpsfv.DisplayString(val)
case time.Time:
// RFC 9651 Date values have Unix-second precision.
option.value = time.Unix(val.Unix(), 0).UTC()
case int:
option.value = int64(v)
option.value = int64(val)
case string, bool, int64, float64, []byte, httpsfv.Token:
default:
return option, fmt.Errorf("%w: unsupported value type %T for signature parameter %q",
Expand Down
Loading
Loading