Add custom Signature-Input parameters (RFC 9421)

SignConfig.AddCustomParam appends non-standard parameters with int64, string,
or bool values; reserved names and duplicates fail at sign time. Names must
match RFC 8941 key syntax; wrap httpsfv.ErrInvalidKeyFormat with clearer
context. MessageDetails exposes CustomParams after verification.

Tests cover round-trip, validation, and verifier config for stable clocks.

Closes #19.

Made-with: Cursor

Author: yaronf

config.go

@@ -8,6 +8,12 @@ import (
 	"time"
 )
 
+// customParam holds a single custom signature parameter name/value pair.
+type customParam struct {
+	name  string
+	value interface{} // must be int64, string, or bool
+}
+
 // SignConfig contains additional configuration for the signer.
 type SignConfig struct {
 	signAlg           bool
@@ -20,6 +26,7 @@ type SignConfig struct {
 	keyID             *string
 	maxBodySize       int64
 	schemeFromRequest func(*http.Request) string
+	customParams      []customParam
 }
 
 // NewSignConfig generates a default configuration.
@@ -109,6 +116,17 @@ func (c *SignConfig) SetSchemeFromRequest(f func(*http.Request) string) *SignCon
 	return c
 }
 
+// AddCustomParam adds a custom (non-standard) parameter to the signature.
+// The name must not conflict with reserved parameter names (created, expires, nonce, alg, tag, keyid).
+// Names must conform to the RFC 8941 "key" syntax used for Structured Field parameters: start with
+// a lowercase letter (a–z) or '*', and contain only lowercase letters, digits, and '_', '-', '.', '*'.
+// The value must be int64, string, or bool.
+// Errors (reserved name, duplicate name, unsupported type, invalid name syntax) are reported at sign time.
+func (c *SignConfig) AddCustomParam(name string, value interface{}) *SignConfig {
+	c.customParams = append(c.customParams, customParam{name, value})
+	return c
+}
+
 // VerifyConfig contains additional configuration for the verifier.
 type VerifyConfig struct {
 	verifyCreated     bool

message.go

@@ -10,13 +10,16 @@ import (
 
 // MessageDetails aggregates the details of a signed message, for a given signature
 type MessageDetails struct {
-	KeyID   *string // nil when keyid parameter is absent (RFC 9421 does not require it)
-	Alg     string
-	Fields  Fields
-	Created *time.Time
-	Expires *time.Time
-	Nonce   *string
-	Tag     *string
+	KeyID        *string // nil when keyid parameter is absent (RFC 9421 does not require it)
+	Alg          string
+	Fields       Fields
+	Created      *time.Time
+	Expires      *time.Time
+	Nonce        *string
+	Tag          *string
+	CustomParams map[string]interface{} // non-standard parameters; values are int64, string, or bool. Nil if none present.
+	// Note: when populated via RequestDetails/ResponseDetails, the message has not been cryptographically
+	// verified — treat CustomParams (and all other fields) as untrusted until verified.
 }
 
 // Message represents a parsed HTTP message ready for signature verification.

signatures.go

@@ -11,6 +11,17 @@ import (
 	"github.com/dunglas/httpsfv"
 )
 
+// reservedSigParams lists the RFC 9421 standard signature parameter names.
+// Custom parameters must not use these names.
+var reservedSigParams = map[string]bool{
+	"created": true,
+	"expires": true,
+	"nonce":   true,
+	"alg":     true,
+	"tag":     true,
+	"keyid":   true,
+}
+
 func signMessage(config SignConfig, signatureName string, signer Signer, parsedMessage, parsedAssocMessage *parsedMessage,
 	fields Fields) (signatureInput, signature, signatureBase string, err error) {
 	filtered := filterOptionalFields(fields, parsedMessage, parsedAssocMessage)
@@ -311,7 +322,31 @@ func generateSigParams(config *SignConfig, alg string, foreignSigner interface{}
 		}
 		p.Add("keyid", *config.keyID)
 	}
-	return fields.asSignatureInput(p)
+	seen := map[string]bool{}
+	for _, cp := range config.customParams {
+		if reservedSigParams[cp.name] {
+			return "", fmt.Errorf("custom param name %q conflicts with reserved parameter", cp.name)
+		}
+		if seen[cp.name] {
+			return "", fmt.Errorf("duplicate custom param name %q", cp.name)
+		}
+		seen[cp.name] = true
+		switch v := cp.value.(type) {
+		case int64:
+			p.Add(cp.name, v)
+		case string:
+			p.Add(cp.name, v)
+		case bool:
+			p.Add(cp.name, v)
+		default:
+			return "", fmt.Errorf("custom param %q: value must be int64, string, or bool", cp.name)
+		}
+	}
+	s, err := fields.asSignatureInput(p)
+	if err != nil && errors.Is(err, httpsfv.ErrInvalidKeyFormat) {
+		return "", fmt.Errorf("invalid custom signature parameter name (RFC 8941 key syntax): %w", err)
+	}
+	return s, err
 }
 
 // SignRequest signs an HTTP request. Returns the Signature-Input and the Signature header values.
@@ -545,6 +580,16 @@ func signatureDetails(signature *psiSignature) (details *MessageDetails, err err
 		details.Tag = &tag
 	}
 
+	custom := map[string]interface{}{}
+	for name, val := range signature.params {
+		if !reservedSigParams[name] {
+			custom[name] = val
+		}
+	}
+	if len(custom) > 0 {
+		details.CustomParams = custom
+	}
+
 	return details, nil
 }
 

signatures_test.go

@@ -3344,6 +3344,93 @@ func TestRequestBindingSignedResponse17(t *testing.T) {
 	assert.NoError(t, err, "validate response digest")
 }
 
+// makeHMACSignerVerifier builds a signer/verifier pair for signVerifyResponseCustomParams.
+// The verifier uses SetVerifyCreated(false) so round-trips do not flake on clock skew
+// (the signer still emits created by default; verification skips the created window check).
+func makeHMACSignerVerifier(t *testing.T, signConfig *SignConfig, fields Fields) (*Signer, *Verifier) {
+	t.Helper()
+	key, _ := base64.StdEncoding.DecodeString("uzvJfB4u3N0Jy4T7NZ75MDVcr8zSTInedJtkgcu46YW4XByzNJjxBdtjUkdJPBtbmHhIDi6pcl8jsasjlTMtDQ==")
+	signer, err := NewHMACSHA256Signer(key, signConfig, fields)
+	assert.NoError(t, err)
+	verifier, err := NewHMACSHA256Verifier(key, NewVerifyConfig().SetVerifyCreated(false), fields)
+	assert.NoError(t, err)
+	return signer, verifier
+}
+
+// Helper function for the next block of tests
+func signVerifyResponseCustomParams(t *testing.T, signConfig *SignConfig) (*MessageDetails, error) {
+	t.Helper()
+	fields := Headers("@status", "date", "content-type")
+	signer, verifier := makeHMACSignerVerifier(t, signConfig, fields)
+	res := readResponse(httpres2)
+	sigInput, sig, err := SignResponse("sig1", *signer, res, nil)
+	if err != nil {
+		return nil, err
+	}
+	res2 := readResponse(httpres2)
+	res2.Header.Add("Signature", sig)
+	res2.Header.Add("Signature-Input", sigInput)
+	msg, err := NewMessage(NewMessageConfig().WithResponse(res2, nil))
+	assert.NoError(t, err)
+	return msg.Verify("sig1", *verifier)
+}
+
+func TestCustomParamStringRoundTrip(t *testing.T) {
+	config := NewSignConfig().AddCustomParam("x-foo", "bar")
+	details, err := signVerifyResponseCustomParams(t, config)
+	assert.NoError(t, err)
+	assert.Equal(t, map[string]interface{}{"x-foo": "bar"}, details.CustomParams)
+}
+
+func TestCustomParamInt64RoundTrip(t *testing.T) {
+	config := NewSignConfig().AddCustomParam("x-num", int64(42))
+	details, err := signVerifyResponseCustomParams(t, config)
+	assert.NoError(t, err)
+	assert.Equal(t, map[string]interface{}{"x-num": int64(42)}, details.CustomParams)
+}
+
+func TestCustomParamBoolRoundTrip(t *testing.T) {
+	config := NewSignConfig().AddCustomParam("x-flag", true)
+	details, err := signVerifyResponseCustomParams(t, config)
+	assert.NoError(t, err)
+	assert.Equal(t, map[string]interface{}{"x-flag": true}, details.CustomParams)
+}
+
+func TestMultipleCustomParams(t *testing.T) {
+	config := NewSignConfig().
+		AddCustomParam("x-foo", "bar").
+		AddCustomParam("x-num", int64(99))
+	details, err := signVerifyResponseCustomParams(t, config)
+	assert.NoError(t, err)
+	assert.Equal(t, map[string]interface{}{"x-foo": "bar", "x-num": int64(99)}, details.CustomParams)
+}
+
+func TestCustomParamReservedNameRejected(t *testing.T) {
+	config := NewSignConfig().AddCustomParam("created", "oops")
+	_, err := signVerifyResponseCustomParams(t, config)
+	assert.Error(t, err)
+}
+
+func TestCustomParamDuplicateNameRejected(t *testing.T) {
+	config := NewSignConfig().
+		AddCustomParam("x-foo", "first").
+		AddCustomParam("x-foo", "second")
+	_, err := signVerifyResponseCustomParams(t, config)
+	assert.Error(t, err)
+}
+
+func TestCustomParamInvalidType(t *testing.T) {
+	config := NewSignConfig().AddCustomParam("x-foo", 3.14)
+	_, err := signVerifyResponseCustomParams(t, config)
+	assert.Error(t, err)
+}
+
+func TestCustomParamInvalidName(t *testing.T) {
+	config := NewSignConfig().AddCustomParam("INVALID", "val")
+	_, err := signVerifyResponseCustomParams(t, config)
+	assert.Error(t, err)
+}
+
 // Same as TestRequestBindingSignedResponse17 but using Message
 func TestMessageRequestBindingSignedResponse17(t *testing.T) {
 	req := readRequest(httpreq14)