Sign and verify optional headers

Author: yaronf

fields.go

@@ -8,6 +8,13 @@ import (
 
 // Fields is a list of fields to be signed or verified. To initialize, use Headers or for more complex
 // cases, NewFields followed by a chain of Add... methods.
+//
+// Several component types may be marked as optional. When signing a message, an optional component (e.g., header)
+// is signed if it exists in the message to be signed, otherwise it is not included in the signature input.
+// Upon verification, a field marked optional must be included in the signed components if it appears at all.
+// This allows for intuitive handling of application components (headers, query parameters) whose presence in
+// the message depends on application logic. Please do NOT use this functionality for headers that may legitimately be
+// added by a proxy, such as X-Forwarded-For.
 type Fields struct {
 	f []field
 }
@@ -94,6 +101,15 @@ func (fs *Fields) AddHeader(hdr string) *Fields {
 	return fs
 }
 
+// AddOptionalHeader appends a bare header name, e.g. "cache-control". The field is optional, see type documentation
+// for details.
+func (fs *Fields) AddOptionalHeader(hdr string) *Fields {
+	f := fromHeaderName(hdr)
+	f.markOptional()
+	fs.f = append(fs.f, *f)
+	return fs
+}
+
 func fromQueryParam(qp string) *field {
 	q := strings.ToLower(qp)
 	i := httpsfv.NewItem("@query-params")
@@ -120,6 +136,15 @@ func (fs *Fields) AddQueryParam(qp string) *Fields {
 	return fs
 }
 
+// AddOptionalQueryParam indicates a request for a specific query parameter to be signed. The field is optional,
+// see type documentation for details.
+func (fs *Fields) AddOptionalQueryParam(qp string) *Fields {
+	f := fromQueryParam(qp)
+	f.markOptional()
+	fs.f = append(fs.f, *f)
+	return fs
+}
+
 func fromDictHeader(hdr, key string) *field {
 	h := strings.ToLower(hdr)
 	i := httpsfv.NewItem(h)
@@ -143,6 +168,15 @@ func (fs *Fields) AddDictHeader(hdr, key string) *Fields {
 	return fs
 }
 
+// AddOptionalDictHeader indicates that out of a header structured as a dictionary, a specific key value is signed/verified.
+// The field is optional, see type documentation for details.
+func (fs *Fields) AddOptionalDictHeader(hdr, key string) *Fields {
+	f := fromDictHeader(hdr, key)
+	f.markOptional()
+	fs.f = append(fs.f, *f)
+	return fs
+}
+
 func fromStructuredField(hdr string) *field {
 	h := strings.ToLower(hdr)
 	i := httpsfv.NewItem(h)
@@ -163,6 +197,15 @@ func (fs *Fields) AddStructuredField(hdr string) *Fields {
 	return fs
 }
 
+// AddOptionalStructuredField indicates that a header should be interpreted as a structured field, per RFC 8941.
+// The field is optional, see type documentation for details.
+func (fs *Fields) AddOptionalStructuredField(hdr string) *Fields {
+	f := fromStructuredField(hdr)
+	f.markOptional()
+	fs.f = append(fs.f, *f)
+	return fs
+}
+
 func fromRequestResponse(sigName string) *field {
 	i := httpsfv.NewItem("@request-response")
 	i.Params.Add("key", sigName)
@@ -179,6 +222,50 @@ func (f field) asSignatureInput() (string, error) {
 	return s, err
 }
 
+func (f field) markOptional() {
+	if f.Params == nil {
+		f.Params = httpsfv.NewParams()
+	}
+	f.Params.Add("optional", true)
+}
+
+func (f field) unmarkOptional() {
+	if f.Params == nil {
+		f.Params = httpsfv.NewParams()
+	}
+	f.Params.Del("optional")
+}
+
+func (f field) isOptional() bool {
+	if f.Params != nil {
+		v, ok := f.Params.Get("optional")
+		if ok {
+			vv, ok2 := v.(bool)
+			if ok2 {
+				return vv
+			}
+		}
+	}
+	return false
+}
+
+// Not a full deep copy, but good enough for mutating params
+func (f field) copy() field {
+	ff := field{
+		Value: f.Value,
+	}
+	if f.Params == nil {
+		ff.Params = nil
+	} else {
+		ff.Params = httpsfv.NewParams()
+		for _, n := range f.Params.Names() {
+			v, _ := f.Params.Get(n)
+			ff.Params.Add(n, v)
+		}
+	}
+	return ff
+}
+
 func (fs *Fields) asSignatureInput(p *httpsfv.Params) (string, error) {
 	il := httpsfv.InnerList{
 		Items:  []httpsfv.Item{},

signatures.go

@@ -18,12 +18,13 @@ import (
 
 func signMessage(config SignConfig, signatureName string, signer Signer, parsedMessage parsedMessage,
 	fields Fields) (signatureInputHeader, signature, signatureInput string, err error) {
-	sigParams, err := generateSigParams(&config, signer.keyID, signer.alg, signer.foreignSigner, fields)
+	filtered := filterOptionalFields(fields, parsedMessage)
+	sigParams, err := generateSigParams(&config, signer.keyID, signer.alg, signer.foreignSigner, filtered)
 	if err != nil {
 		return "", "", "", err
 	}
 	signatureInputHeader = fmt.Sprintf("%s=%s", signatureName, sigParams)
-	signatureInput, err = generateSignatureInput(parsedMessage, fields, sigParams)
+	signatureInput, err = generateSignatureInput(parsedMessage, filtered, sigParams)
 	if err != nil {
 		return "", "", "", err
 	}
@@ -34,6 +35,23 @@ func signMessage(config SignConfig, signatureName string, signer Signer, parsedM
 	return signatureInputHeader, signature, signatureInput, nil
 }
 
+func filterOptionalFields(fields Fields, message parsedMessage) Fields {
+	filtered := *NewFields()
+	for _, f := range fields.f {
+		if !f.isOptional() {
+			filtered.f = append(filtered.f, f)
+		} else {
+			_, err := generateFieldValues(f, message)
+			if err == nil { // value was found
+				ff := f.copy()
+				ff.unmarkOptional()
+				filtered.f = append(filtered.f, ff)
+			}
+		}
+	}
+	return filtered
+}
+
 func generateSignature(name string, signer Signer, input string) (string, error) {
 	raw, err := signer.sign([]byte(input))
 	if err != nil {
@@ -385,7 +403,8 @@ func verifyMessage(config VerifyConfig, name string, verifier Verifier, message
 	if err != nil {
 		return "", err
 	}
-	if !(psiSig.fields.contains(&fields)) {
+	filtered := filterOptionalFields(fields, message)
+	if !(psiSig.fields.contains(&filtered)) {
 		return "", fmt.Errorf("actual signature does not cover all required fields")
 	}
 	err = applyVerificationPolicy(verifier, message, psiSig, config)

signatures_test.go

@@ -1489,3 +1489,59 @@ func TestVerifyResponse(t *testing.T) {
 		})
 	}
 }
+
+func TestOptionalSign(t *testing.T) {
+	req := readRequest(httpreq2)
+	f := NewFields().AddHeader("date").AddOptionalHeader("x-optional")
+	key1 := bytes.Repeat([]byte{0x55}, 64)
+	signer, err := NewHMACSHA256Signer("key1", key1, NewSignConfig().setFakeCreated(9999), *f)
+	assert.NoError(t, err, "Could not create signer")
+	sigInputHeader, _, sigInput, err := signRequestDebug("sig1", *signer, req)
+	assert.NoError(t, err, "Should not fail with optional header absent")
+	assert.Equal(t, "sig1=(\"date\");created=9999;alg=\"hmac-sha256\";keyid=\"key1\"", sigInputHeader)
+	assert.Equal(t, "\"date\": Tue, 20 Apr 2021 02:07:55 GMT\n\"@signature-params\": (\"date\");created=9999;alg=\"hmac-sha256\";keyid=\"key1\"", sigInput)
+
+	req.Header.Add("X-Optional", "value")
+	sigInputHeader, _, sigInput, err = signRequestDebug("sig1", *signer, req)
+	assert.NoError(t, err, "Should not fail with optional header present")
+	assert.Equal(t, "sig1=(\"date\" \"x-optional\");created=9999;alg=\"hmac-sha256\";keyid=\"key1\"", sigInputHeader)
+	assert.Equal(t, "\"date\": Tue, 20 Apr 2021 02:07:55 GMT\n\"x-optional\": value\n\"@signature-params\": (\"date\" \"x-optional\");created=9999;alg=\"hmac-sha256\";keyid=\"key1\"", sigInput)
+}
+
+func TestOptionalVerify(t *testing.T) {
+	req := readRequest(httpreq2)
+	req.Header.Add("X-Opt1", "val1")
+	f1 := NewFields().AddHeader("date").AddOptionalHeader("x-opt1")
+	key1 := bytes.Repeat([]byte{0x66}, 64)
+	signer, err := NewHMACSHA256Signer("key1", key1, NewSignConfig().setFakeCreated(8888), *f1)
+	assert.NoError(t, err, "Could not create signer")
+	sigInputHeader, signature, err := SignRequest("sig1", *signer, req)
+	assert.NoError(t, err, "Should not fail with optional header present")
+	req.Header.Add("Signature-Input", sigInputHeader)
+	req.Header.Add("Signature", signature)
+
+	verifier, err := NewHMACSHA256Verifier("key1", key1, NewVerifyConfig().SetVerifyCreated(false), *f1)
+	assert.NoError(t, err, "Could not create verifier")
+	err = VerifyRequest("sig1", *verifier, req)
+	assert.NoError(t, err, "Should not fail: present and signed")
+
+	req.Header.Del("X-Opt1") // header absent but included in covered components
+	err = VerifyRequest("sig1", *verifier, req)
+	assert.Error(t, err, "Should fail: absent and signed")
+
+	req = readRequest(httpreq2) // header present but not signed
+	req.Header.Add("X-Opt1", "val1")
+	f2 := NewFields().AddHeader("date") // without the optional header
+	signer, err = NewHMACSHA256Signer("key1", key1, NewSignConfig().setFakeCreated(2222), *f2)
+	sigInputHeader, signature, err = SignRequest("sig1", *signer, req)
+	assert.NoError(t, err, "Should not fail with redundant header present")
+	req.Header.Add("Signature-Input", sigInputHeader)
+	req.Header.Add("Signature", signature)
+
+	err = VerifyRequest("sig1", *verifier, req)
+	assert.Error(t, err, "Should fail: present and not signed")
+
+	req.Header.Del("X-Opt1")
+	err = VerifyRequest("sig1", *verifier, req)
+	assert.NoError(t, err, "Should not fail: absent and not signed")
+}