draft-ietf-httpbis-message-signatures-10.txt   draft-ietf-httpbis-message-signatures-latest.txt 
HTTP Working Group A. Backman, Ed. HTTP Working Group A. Backman, Ed.
Internet-Draft Amazon Internet-Draft Amazon
Intended status: Standards Track J. Richer Intended status: Standards Track J. Richer
Expires: November 27, 2022 Bespoke Engineering Expires: December 25, 2022 Bespoke Engineering
M. Sporny M. Sporny
Digital Bazaar Digital Bazaar
May 26, 2022 June 23, 2022
HTTP Message Signatures HTTP Message Signatures
draft-ietf-httpbis-message-signatures-10 draft-ietf-httpbis-message-signatures-latest
Abstract Abstract
This document describes a mechanism for creating, encoding, and This document describes a mechanism for creating, encoding, and
verifying digital signatures or message authentication codes over verifying digital signatures or message authentication codes over
components of an HTTP message. This mechanism supports use cases components of an HTTP message. This mechanism supports use cases
where the full HTTP message may not be known to the signer, and where where the full HTTP message may not be known to the signer, and where
the message may be transformed (e.g., by intermediaries) before the message may be transformed (e.g., by intermediaries) before
reaching the verifier. This document also describes a means for reaching the verifier. This document also describes a means for
requesting that a signature be applied to a subsequent HTTP message requesting that a signature be applied to a subsequent HTTP message
skipping to change at page 2, line 10 skipping to change at page 2, line 10
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 27, 2022. This Internet-Draft will expire on December 25, 2022.
Copyright Notice Copyright Notice
Copyright (c) 2022 IETF Trust and the persons identified as the Copyright (c) 2022 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 37 skipping to change at page 2, line 37
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Requirements Discussion . . . . . . . . . . . . . . . . . 5 1.1. Requirements Discussion . . . . . . . . . . . . . . . . . 5
1.2. HTTP Message Transformations . . . . . . . . . . . . . . 6 1.2. HTTP Message Transformations . . . . . . . . . . . . . . 6
1.3. Conventions and Terminology . . . . . . . . . . . . . . . 7 1.3. Conventions and Terminology . . . . . . . . . . . . . . . 7
1.4. Application of HTTP Message Signatures . . . . . . . . . 10 1.4. Application of HTTP Message Signatures . . . . . . . . . 10
2. HTTP Message Components . . . . . . . . . . . . . . . . . . . 11 2. HTTP Message Components . . . . . . . . . . . . . . . . . . . 11
2.1. HTTP Fields . . . . . . . . . . . . . . . . . . . . . . . 12 2.1. HTTP Fields . . . . . . . . . . . . . . . . . . . . . . . 12
2.1.1. Canonicalized Structured HTTP Fields . . . . . . . . 14 2.1.1. Canonicalized Structured HTTP Fields . . . . . . . . 14
2.1.2. Dictionary Structured Field Members . . . . . . . . . 14 2.1.2. Dictionary Structured Field Members . . . . . . . . . 15
2.2. Derived Components . . . . . . . . . . . . . . . . . . . 15 2.2. Derived Components . . . . . . . . . . . . . . . . . . . 16
2.2.1. Signature Parameters . . . . . . . . . . . . . . . . 17 2.2.1. Signature Parameters . . . . . . . . . . . . . . . . 17
2.2.2. Method . . . . . . . . . . . . . . . . . . . . . . . 18 2.2.2. Method . . . . . . . . . . . . . . . . . . . . . . . 19
2.2.3. Target URI . . . . . . . . . . . . . . . . . . . . . 19 2.2.3. Target URI . . . . . . . . . . . . . . . . . . . . . 19
2.2.4. Authority . . . . . . . . . . . . . . . . . . . . . . 19 2.2.4. Authority . . . . . . . . . . . . . . . . . . . . . . 20
2.2.5. Scheme . . . . . . . . . . . . . . . . . . . . . . . 20 2.2.5. Scheme . . . . . . . . . . . . . . . . . . . . . . . 20
2.2.6. Request Target . . . . . . . . . . . . . . . . . . . 20 2.2.6. Request Target . . . . . . . . . . . . . . . . . . . 21
2.2.7. Path . . . . . . . . . . . . . . . . . . . . . . . . 22 2.2.7. Path . . . . . . . . . . . . . . . . . . . . . . . . 22
2.2.8. Query . . . . . . . . . . . . . . . . . . . . . . . . 22 2.2.8. Query . . . . . . . . . . . . . . . . . . . . . . . . 23
2.2.9. Query Parameters . . . . . . . . . . . . . . . . . . 23 2.2.9. Query Parameters . . . . . . . . . . . . . . . . . . 24
2.2.10. Status Code . . . . . . . . . . . . . . . . . . . . . 24 2.2.10. Status Code . . . . . . . . . . . . . . . . . . . . . 25
2.3. Request-Response Signature Binding . . . . . . . . . . . 25 2.3. Request-Response Signature Binding . . . . . . . . . . . 25
2.4. Creating the Signature Base . . . . . . . . . . . . . . . 28 2.4. Creating the Signature Base . . . . . . . . . . . . . . . 28
3. HTTP Message Signatures . . . . . . . . . . . . . . . . . . . 31 3. HTTP Message Signatures . . . . . . . . . . . . . . . . . . . 31
3.1. Creating a Signature . . . . . . . . . . . . . . . . . . 31 3.1. Creating a Signature . . . . . . . . . . . . . . . . . . 31
3.2. Verifying a Signature . . . . . . . . . . . . . . . . . . 33 3.2. Verifying a Signature . . . . . . . . . . . . . . . . . . 33
3.2.1. Enforcing Application Requirements . . . . . . . . . 36 3.2.1. Enforcing Application Requirements . . . . . . . . . 36
3.3. Signature Algorithm Methods . . . . . . . . . . . . . . . 37 3.3. Signature Algorithm Methods . . . . . . . . . . . . . . . 37
3.3.1. RSASSA-PSS using SHA-512 . . . . . . . . . . . . . . 38 3.3.1. RSASSA-PSS using SHA-512 . . . . . . . . . . . . . . 38
3.3.2. RSASSA-PKCS1-v1_5 using SHA-256 . . . . . . . . . . . 38 3.3.2. RSASSA-PKCS1-v1_5 using SHA-256 . . . . . . . . . . . 38
3.3.3. HMAC using SHA-256 . . . . . . . . . . . . . . . . . 39 3.3.3. HMAC using SHA-256 . . . . . . . . . . . . . . . . . 39
3.3.4. ECDSA using curve P-256 DSS and SHA-256 . . . . . . . 39 3.3.4. ECDSA using curve P-256 DSS and SHA-256 . . . . . . . 39
3.3.5. EdDSA using curve edwards25519 . . . . . . . . . . . 40 3.3.5. EdDSA using curve edwards25519 . . . . . . . . . . . 40
3.3.6. JSON Web Signature (JWS) algorithms . . . . . . . . . 41 3.3.6. JSON Web Signature (JWS) algorithms . . . . . . . . . 41
4. Including a Message Signature in a Message . . . . . . . . . 41 4. Including a Message Signature in a Message . . . . . . . . . 41
4.1. The Signature-Input HTTP Field . . . . . . . . . . . . . 42 4.1. The Signature-Input HTTP Field . . . . . . . . . . . . . 42
4.2. The Signature HTTP Field . . . . . . . . . . . . . . . . 42 4.2. The Signature HTTP Field . . . . . . . . . . . . . . . . 42
4.3. Multiple Signatures . . . . . . . . . . . . . . . . . . . 43 4.3. Multiple Signatures . . . . . . . . . . . . . . . . . . . 43
5. Requesting Signatures . . . . . . . . . . . . . . . . . . . . 46 5. Requesting Signatures . . . . . . . . . . . . . . . . . . . . 46
5.1. The Accept-Signature Field . . . . . . . . . . . . . . . 47 5.1. The Accept-Signature Field . . . . . . . . . . . . . . . 47
5.2. Processing an Accept-Signature . . . . . . . . . . . . . 48 5.2. Processing an Accept-Signature . . . . . . . . . . . . . 48
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 49 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48
6.1. HTTP Signature Algorithms Registry . . . . . . . . . . . 49 6.1. HTTP Signature Algorithms Registry . . . . . . . . . . . 49
6.1.1. Registration Template . . . . . . . . . . . . . . . . 49 6.1.1. Registration Template . . . . . . . . . . . . . . . . 49
6.1.2. Initial Contents . . . . . . . . . . . . . . . . . . 50 6.1.2. Initial Contents . . . . . . . . . . . . . . . . . . 50
6.2. HTTP Signature Metadata Parameters Registry . . . . . . . 50 6.2. HTTP Signature Metadata Parameters Registry . . . . . . . 50
6.2.1. Registration Template . . . . . . . . . . . . . . . . 51 6.2.1. Registration Template . . . . . . . . . . . . . . . . 50
6.2.2. Initial Contents . . . . . . . . . . . . . . . . . . 51 6.2.2. Initial Contents . . . . . . . . . . . . . . . . . . 51
6.3. HTTP Signature Derived Component Names Registry . . . . . 52 6.3. HTTP Signature Derived Component Names Registry . . . . . 51
6.3.1. Registration Template . . . . . . . . . . . . . . . . 52 6.3.1. Registration Template . . . . . . . . . . . . . . . . 52
6.3.2. Initial Contents . . . . . . . . . . . . . . . . . . 53 6.3.2. Initial Contents . . . . . . . . . . . . . . . . . . 52
6.4. HTTP Signature Component Parameters Registry . . . . . . 54 6.4. HTTP Signature Component Parameters Registry . . . . . . 54
6.4.1. Registration Template . . . . . . . . . . . . . . . . 54 6.4.1. Registration Template . . . . . . . . . . . . . . . . 54
6.4.2. Initial Contents . . . . . . . . . . . . . . . . . . 55 6.4.2. Initial Contents . . . . . . . . . . . . . . . . . . 55
7. Security Considerations . . . . . . . . . . . . . . . . . . . 56 7. Security Considerations . . . . . . . . . . . . . . . . . . . 55
7.1. Signature Verification Skipping . . . . . . . . . . . . . 56 7.1. Signature Verification Skipping . . . . . . . . . . . . . 56
7.2. Use of TLS . . . . . . . . . . . . . . . . . . . . . . . 56 7.2. Use of TLS . . . . . . . . . . . . . . . . . . . . . . . 56
7.3. Signature Replay . . . . . . . . . . . . . . . . . . . . 57 7.3. Signature Replay . . . . . . . . . . . . . . . . . . . . 56
7.4. Insufficient Coverage . . . . . . . . . . . . . . . . . . 57 7.4. Insufficient Coverage . . . . . . . . . . . . . . . . . . 57
7.5. Cryptography and Signature Collision . . . . . . . . . . 58 7.5. Cryptography and Signature Collision . . . . . . . . . . 57
7.6. Key Theft . . . . . . . . . . . . . . . . . . . . . . . . 58 7.6. Key Theft . . . . . . . . . . . . . . . . . . . . . . . . 58
7.7. Modification of Required Message Parameters . . . . . . . 59 7.7. Modification of Required Message Parameters . . . . . . . 58
7.8. Mismatch of Signature Parameters from Message . . . . . . 59 7.8. Mismatch of Signature Parameters from Message . . . . . . 59
7.9. Multiple Signature Confusion . . . . . . . . . . . . . . 59 7.9. Multiple Signature Confusion . . . . . . . . . . . . . . 59
7.10. Signature Labels . . . . . . . . . . . . . . . . . . . . 60 7.10. Signature Labels . . . . . . . . . . . . . . . . . . . . 59
7.11. Symmetric Cryptography . . . . . . . . . . . . . . . . . 60 7.11. Symmetric Cryptography . . . . . . . . . . . . . . . . . 60
7.12. Canonicalization Attacks . . . . . . . . . . . . . . . . 61 7.12. Canonicalization Attacks . . . . . . . . . . . . . . . . 60
7.13. Key Specification Mix-Up . . . . . . . . . . . . . . . . 61 7.13. Key Specification Mix-Up . . . . . . . . . . . . . . . . 61
7.14. HTTP Versions and Component Ambiguity . . . . . . . . . . 61 7.14. HTTP Versions and Component Ambiguity . . . . . . . . . . 61
7.15. Key and Algorithm Specification Downgrades . . . . . . . 62 7.15. Key and Algorithm Specification Downgrades . . . . . . . 61
7.16. Parsing Structured Field Values . . . . . . . . . . . . . 62 7.16. Parsing Structured Field Values . . . . . . . . . . . . . 62
7.17. Choosing Message Components . . . . . . . . . . . . . . . 63 7.17. Choosing Message Components . . . . . . . . . . . . . . . 62
7.18. Confusing HTTP Field Names for Derived Component Names . 63 7.18. Confusing HTTP Field Names for Derived Component Names . 63
7.19. Non-deterministic Signature Primitives . . . . . . . . . 64 7.19. Non-deterministic Signature Primitives . . . . . . . . . 63
7.20. Choosing Signature Parameters and Derived Components over 7.20. Choosing Signature Parameters and Derived Components over
HTTP Fields . . . . . . . . . . . . . . . . . . . . . . . 64 HTTP Fields . . . . . . . . . . . . . . . . . . . . . . . 64
7.21. Semantically Equivalent Field Values . . . . . . . . . . 65 7.21. Semantically Equivalent Field Values . . . . . . . . . . 64
7.22. Message Content . . . . . . . . . . . . . . . . . . . . . 65 7.22. Message Content . . . . . . . . . . . . . . . . . . . . . 65
8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 66 7.23. Non-List Field Values . . . . . . . . . . . . . . . . . . 66
8.1. Identification through Keys . . . . . . . . . . . . . . . 66 7.24. Padding Attacks with Multiple Field Values . . . . . . . 67
8.2. Signatures do not provide confidentiality . . . . . . . . 67 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 68
8.3. Oracles . . . . . . . . . . . . . . . . . . . . . . . . . 67 8.1. Identification through Keys . . . . . . . . . . . . . . . 68
8.4. Required Content . . . . . . . . . . . . . . . . . . . . 67 8.2. Signatures do not provide confidentiality . . . . . . . . 68
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 68 8.3. Oracles . . . . . . . . . . . . . . . . . . . . . . . . . 68
9.1. Normative References . . . . . . . . . . . . . . . . . . 68 8.4. Required Content . . . . . . . . . . . . . . . . . . . . 69
9.2. Informative References . . . . . . . . . . . . . . . . . 69 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 69
9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 70 9.1. Normative References . . . . . . . . . . . . . . . . . . 69
Appendix A. Detecting HTTP Message Signatures . . . . . . . . . 70 9.2. Informative References . . . . . . . . . . . . . . . . . 71
Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 70 9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 72
B.1. Example Keys . . . . . . . . . . . . . . . . . . . . . . 71 Appendix A. Detecting HTTP Message Signatures . . . . . . . . . 72
B.1.1. Example Key RSA test . . . . . . . . . . . . . . . . 71 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 72
B.1.2. Example RSA PSS Key . . . . . . . . . . . . . . . . . 72 B.1. Example Keys . . . . . . . . . . . . . . . . . . . . . . 72
B.1.3. Example ECC P-256 Test Key . . . . . . . . . . . . . 73 B.1.1. Example Key RSA test . . . . . . . . . . . . . . . . 73
B.1.4. Example Ed25519 Test Key . . . . . . . . . . . . . . 74 B.1.2. Example RSA PSS Key . . . . . . . . . . . . . . . . . 74
B.1.5. Example Shared Secret . . . . . . . . . . . . . . . . 74 B.1.3. Example ECC P-256 Test Key . . . . . . . . . . . . . 75
B.2. Test Cases . . . . . . . . . . . . . . . . . . . . . . . 74 B.1.4. Example Ed25519 Test Key . . . . . . . . . . . . . . 76
B.2.1. Minimal Signature Using rsa-pss-sha512 . . . . . . . 75 B.1.5. Example Shared Secret . . . . . . . . . . . . . . . . 76
B.2.2. Selective Covered Components using rsa-pss-sha512 . . 76 B.2. Test Cases . . . . . . . . . . . . . . . . . . . . . . . 76
B.2.3. Full Coverage using rsa-pss-sha512 . . . . . . . . . 77 B.2.1. Minimal Signature Using rsa-pss-sha512 . . . . . . . 77
B.2.4. Signing a Response using ecdsa-p256-sha256 . . . . . 78 B.2.2. Selective Covered Components using rsa-pss-sha512 . . 78
B.2.5. Signing a Request using hmac-sha256 . . . . . . . . . 79 B.2.3. Full Coverage using rsa-pss-sha512 . . . . . . . . . 79
B.2.6. Signing a Request using ed25519 . . . . . . . . . . . 79 B.2.4. Signing a Response using ecdsa-p256-sha256 . . . . . 80
B.3. TLS-Terminating Proxies . . . . . . . . . . . . . . . . . 80 B.2.5. Signing a Request using hmac-sha256 . . . . . . . . . 81
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 82 B.2.6. Signing a Request using ed25519 . . . . . . . . . . . 81
Document History . . . . . . . . . . . . . . . . . . . . . . . . 83 B.3. TLS-Terminating Proxies . . . . . . . . . . . . . . . . . 82
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 88 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 85
Document History . . . . . . . . . . . . . . . . . . . . . . . . 86
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 90
1. Introduction 1. Introduction
Message integrity and authenticity are important security properties Message integrity and authenticity are important security properties
that are critical to the secure operation of many HTTP applications. that are critical to the secure operation of many HTTP applications.
Application developers typically rely on the transport layer to Application developers typically rely on the transport layer to
provide these properties, by operating their application over [TLS]. provide these properties, by operating their application over [TLS].
However, TLS only guarantees these properties over a single TLS However, TLS only guarantees these properties over a single TLS
connection, and the path between client and application may be connection, and the path between client and application may be
composed of multiple independent TLS connections (for example, if the composed of multiple independent TLS connections (for example, if the
skipping to change at page 6, line 36 skipping to change at page 6, line 38
1.2. HTTP Message Transformations 1.2. HTTP Message Transformations
As mentioned earlier, HTTP explicitly permits and in some cases As mentioned earlier, HTTP explicitly permits and in some cases
requires implementations to transform messages in a variety of ways. requires implementations to transform messages in a variety of ways.
Implementations are required to tolerate many of these Implementations are required to tolerate many of these
transformations. What follows is a non-normative and non-exhaustive transformations. What follows is a non-normative and non-exhaustive
list of transformations that may occur under HTTP, provided as list of transformations that may occur under HTTP, provided as
context: context:
o Re-ordering of header fields with different header field names o Re-ordering of header fields with different header field names
(Section 3.2.2 of [HTTP1]). (Section 5.3 of [HTTP]).
o Combination of header fields with the same field name o Combination of header fields with the same field name (Section 5.2
(Section 3.2.2 of [HTTP1]). of [HTTP]).
o Removal of header fields listed in the "Connection" header field o Removal of header fields listed in the Connection header field
(Section 6.1 of [HTTP1]). (Section 7.6.1 of [HTTP]).
o Addition of header fields that indicate control options o Addition of header fields that indicate control options
(Section 6.1 of [HTTP1]). (Section 7.6.1 of [HTTP]).
o Addition or removal of a transfer coding (Section 5.7.2 of o Addition or removal of a transfer coding (Section 7.7 of [HTTP]).
[HTTP1]).
o Addition of header fields such as "Via" (Section 5.7.1 of [HTTP1]) o Addition of header fields such as "Via" (Section 7.6.3 of [HTTP])
and "Forwarded" (Section 4 of [RFC7239]). and "Forwarded" (Section 4 of [RFC7239]).
Based on the definition of HTTP and the requirements described above, Based on the definition of HTTP and the requirements described above,
we can identify certain types of transformations that should not we can identify certain types of transformations that should not
prevent signature verification, even when performed on message prevent signature verification, even when performed on message
components covered by the signature. The following list describes components covered by the signature. The following non-exhaustive
those transformations: list describes some of those transformations:
o Combination of header fields with the same field name. o Combination of header fields with the same field name.
o Reordering of header fields with different names. o Reordering of header fields with different names.
o Conversion between different versions of the HTTP protocol (e.g., o Conversion between different versions of the HTTP protocol (e.g.,
HTTP/1.x to HTTP/2, or vice-versa). HTTP/1.x to HTTP/2, or vice-versa).
o Changes in casing (e.g., "Origin" to "origin") of any case- o Changes in casing (e.g., "Origin" to "origin") of any case-
insensitive components such as header field names, request URI insensitive components such as header field names, request URI
scheme, or host. scheme, or host.
o Addition or removal of leading or trailing whitespace to a header o Addition or removal of leading or trailing whitespace to a field
field value. value.
o Addition or removal of "obs-folds". o Addition or removal of "obs-folds" from field values.
o Changes to the "request-target" and "Host" header field that when o Changes to the request target and authority that when applied
applied together do not result in a change to the message's together do not result in a change to the message's target URI, as
effective request URI, as defined in Section 5.5 of [HTTP1]. defined in Section 7.1 of [HTTP].
Additionally, all changes to components not covered by the signature Additionally, all changes to components not covered by the signature
are considered safe. are considered safe.
1.3. Conventions and Terminology 1.3. Conventions and Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
The terms "HTTP message", "HTTP request", "HTTP response", "absolute- The terms "HTTP message", "HTTP request", "HTTP response", "target
form", "absolute-path", "effective request URI", "gateway", "header URI", "gateway", "header field", "intermediary", "request target",
field", "intermediary", "request-target", "sender", and "recipient" "sender", "method", and "recipient" are used as defined in [HTTP].
are used as defined in [HTTP1].
The term "method" is to be interpreted as defined in Section 4 of
[HTTP].
For brevity, the term "signature" on its own is used in this document For brevity, the term "signature" on its own is used in this document
to refer to both digital signatures (which use asymmetric to refer to both digital signatures (which use asymmetric
cryptography) and keyed MACs (which use symmetric cryptography). cryptography) and keyed MACs (which use symmetric cryptography).
Similarly, the verb "sign" refers to the generation of either a Similarly, the verb "sign" refers to the generation of either a
digital signature or keyed MAC over a given input string. The digital signature or keyed MAC over a given signature base. The
qualified term "digital signature" refers specifically to the output qualified term "digital signature" refers specifically to the output
of an asymmetric cryptographic signing operation. of an asymmetric cryptographic signing operation.
This document uses the following terminology from Section 3 of
[STRUCTURED-FIELDS] to specify data types: List, Inner List,
Dictionary, Item, String, Integer, Byte Sequence, and Boolean.
This document defines several string constructions using [ABNF] and
uses the following ABNF rules: "VCHAR", "SP", "DQUOTE", "LF". This
document also uses the following ABNF rules from [STRUCTURED-FIELDS]:
"sf-string", "inner-list", "parameters". This document also uses the
following ABNF rules from [HTTP]: "field-content".
In addition to those listed above, this document uses the following In addition to those listed above, this document uses the following
terms: terms:
HTTP Message Signature: HTTP Message Signature:
A digital signature or keyed MAC that covers one or more portions A digital signature or keyed MAC that covers one or more portions
of an HTTP message. Note that a given HTTP Message can contain of an HTTP message. Note that a given HTTP Message can contain
multiple HTTP Message Signatures. multiple HTTP Message Signatures.
Signer: Signer:
skipping to change at page 10, line 7 skipping to change at page 10, line 17
asserted by the signer. asserted by the signer.
The term "Unix time" is defined by [POSIX.1], Section 4.16 [2]. The term "Unix time" is defined by [POSIX.1], Section 4.16 [2].
This document contains non-normative examples of partial and complete This document contains non-normative examples of partial and complete
HTTP messages. Some examples use a single trailing backslash '' to HTTP messages. Some examples use a single trailing backslash '' to
indicate line wrapping for long values, as per [RFC8792]. The "\" indicate line wrapping for long values, as per [RFC8792]. The "\"
character and leading spaces on wrapped lines are not part of the character and leading spaces on wrapped lines are not part of the
value. value.
This document uses the following terminology from Section 3 of
[STRUCTURED-FIELDS] to specify syntax and parsing: List, Inner List,
Dictionary, String, Integer, Byte Sequence, and Boolean. This
document uses the following ABNF rules from [STRUCTURED-FIELDS] where
applicable: "sf-string", "key", "parameters".
1.4. Application of HTTP Message Signatures 1.4. Application of HTTP Message Signatures
HTTP Message Signatures are designed to be a general-purpose security HTTP Message Signatures are designed to be a general-purpose security
mechanism applicable in a wide variety of circumstances and mechanism applicable in a wide variety of circumstances and
applications. In order to properly and safely apply HTTP Message applications. In order to properly and safely apply HTTP Message
Signatures, an application or profile of this specification MUST Signatures, an application or profile of this specification MUST
specify all of the following items: specify all of the following items:
o The set of component identifiers (Section 2) that are expected and o The set of component identifiers (Section 2) that are expected and
required. For example, an authorization protocol could mandate required. For example, an authorization protocol could mandate
skipping to change at page 11, line 21 skipping to change at page 11, line 26
additional considerations are discussed in Section 7. additional considerations are discussed in Section 7.
2. HTTP Message Components 2. HTTP Message Components
In order to allow signers and verifiers to establish which components In order to allow signers and verifiers to establish which components
are covered by a signature, this document defines component are covered by a signature, this document defines component
identifiers for components covered by an HTTP Message Signature, a identifiers for components covered by an HTTP Message Signature, a
set of rules for deriving and canonicalizing the values associated set of rules for deriving and canonicalizing the values associated
with these component identifiers from the HTTP Message, and the means with these component identifiers from the HTTP Message, and the means
for combining these canonicalized values into a signature base. The for combining these canonicalized values into a signature base. The
values for these items MUST be accessible to both the signer and the context for deriving these values MUST be accessible to both the
verifier of the message, which means these are usually derived from signer and the verifier of the message.
aspects of the HTTP message or signature itself.
Some HTTP message components can undergo transformations that change
the bitwise value without altering meaning of the component's value
(for example, the merging together of header fields with the same
name). Message component values must therefore be canonicalized
before it is signed, to ensure that a signature can be verified
despite such intermediary transformations. This document defines
rules for each component identifier that transform the identifier's
associated component value into such a canonical form.
Component identifiers are serialized using the production grammar
defined by [STRUCTURED-FIELDS], Section 4. The component identifier
has a component name, which is a String value serialized using the
"sf-string" ABNF rule. The component identifier MAY also include
defined parameters which are serialized using the "parameters" rule.
component-identifier = component-name parameters
component-name = sf-string
Note that this means the serialization of the component name itself A component identifier is composed of a component name and any
is encased in double quotes, with parameters following as a parameters associated with that name. Each component name is either
semicolon-separated list, such as ""cache-control"", ""date"", or an HTTP field name Section 2.1 or a registered derived component name
""@signature-params"", and ""example-dictionary";key="foo"". Section 2.2. The possible parameters for a component identifier are
dependent on the component identifier, and a registry cataloging all
possible parameters is defined in Section 6.2.
One component identifier is distinct from another if either the Within a single list of covered components, each component identifier
component name or its parameters differ. Within a single list of MUST be distinct from every other component identifier. One
covered components, each component identifier MUST be distinct from component identifier is distinct from another if either the component
every other component identifier. Multiple component identifiers name or its parameters differ. Multiple component identifiers having
having the same component name MAY be included if they have the same component name MAY be included if they have parameters that
parameters that make them distinct. make them distinct. The order of parameters MUST be preserved when
processing a component identifier (such as when parsing during
verification), but the order of parameters is not significant when
comparing two component identifiers for equality.
The component value associated with a component identifier is defined The component value associated with a component identifier is defined
by the identifier itself. Component values MUST NOT contain newline by the identifier itself. Component values MUST NOT contain newline
("\n") characters. ("\n") characters. Some HTTP message components can undergo
transformations that change the bitwise value without altering
meaning of the component's value (for example, the merging together
of header fields with the same name). Message component values must
therefore be canonicalized before they are signed, to ensure that a
signature can be verified despite such intermediary transformations.
This document defines rules for each component identifier that
transform the identifier's associated component value into such a
canonical form.
The following sections define component identifier types, their The following sections define component identifier names, their
parameters, their associated values, and the canonicalization rules parameters, their associated values, and the canonicalization rules
for their values. The method for combining component identifiers for their values. The method for combining component identifiers
into the signature base is defined in Section 2.4. into the signature base is defined in Section 2.4.
2.1. HTTP Fields 2.1. HTTP Fields
The component name for an HTTP field is the lowercased form of its The component name for an HTTP field is the lowercased form of its
field name. While HTTP field names are case-insensitive, field name. While HTTP field names are case-insensitive,
implementations MUST use lowercased field names (e.g., "content- implementations MUST use lowercased field names (e.g., "content-
type", "date", "etag") when using them as component names. type", "date", "etag") when using them as component names.
Unless overridden by additional parameters and rules, the HTTP field Unless overridden by additional parameters and rules, the HTTP field
value MUST be canonicalized as a single combined value as defined in value MUST be canonicalized as a single combined value as defined in
Section 5.2 of [HTTP]. Section 5.2 of [HTTP]. Note that some HTTP fields, such as Set-
Cookie [COOKIE], do not follow a syntax that allows for combination
of field values in this manner such that the combined output is
unambiguous from multiple inputs. However, the canonicalized
component value is never parsed by the message signature process,
merely used as part of the signature base in Section 2.4. Even so,
caution needs to be taken when including such fields in signatures,
see Section 7.23 for more discussion of this issue.
If the combined value is not available for a given header, the If the combined value is not available for a given header, the
following algorithm will produce canonicalized results for an following algorithm will produce canonicalized results for an
implementation: implementation:
1. Create an ordered list of the field values of each instance of 1. Create an ordered list of the field values of each instance of
the field in the message, in the order that they occur (or will the field in the message, in the order that they occur (or will
occur) in the message. occur) in the message.
2. Strip leading and trailing whitespace from each item in the list. 2. Strip leading and trailing whitespace from each item in the list.
skipping to change at page 14, line 6 skipping to change at page 14, line 14
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
"x-empty-header": \ "x-empty-header": \
Note: these are shown here using the line wrapping algorithm in Note: these are shown here using the line wrapping algorithm in
[RFC8792] due to limitations in the document format that strips [RFC8792] due to limitations in the document format that strips
trailing spaces from diagrams. trailing spaces from diagrams.
Any HTTP field component identifiers MAY have the following Any HTTP field component identifiers MAY have the following
parameters in specific circumstances. parameters in specific circumstances, each described in detail in
their own sections:
sf A boolean flag indicating that the field value is to be sf A boolean flag indicating that the field value is to be
canonicalized using strict encoding of the structured field value. canonicalized using strict encoding of the structured field value.
Section 2.1.1 Section 2.1.1
key A string parameter used to select a single member value from a key A string parameter used to select a single member value from a
dictionary structured field. Section 2.1.2 dictionary structured field. Section 2.1.2
req Indicates that the component value is derived from the request
that triggered this response message and not from the response
message directly. Note that this parameter can also be applied to
many derived component identifiers. Section 2.3
Additional parameters MAY be defined in a registry established in
Section 6.2.
2.1.1. Canonicalized Structured HTTP Fields 2.1.1. Canonicalized Structured HTTP Fields
If the value of the the HTTP field in question is a structured field If the value of the the HTTP field in question is known by the
([STRUCTURED-FIELDS]), the component identifier MAY include the "sf" application to be a structured field ([STRUCTURED-FIELDS]), the
parameter to indicate it is a known structured field. If this component identifier MAY include the "sf" parameter to indicate it is
parameter is included with a component identifier, the HTTP field a known structured field. If this parameter is included with a
value MUST be serialized using the rules specified in Section 4 of component identifier, the HTTP field value MUST be serialized using
[STRUCTURED-FIELDS] applicable to the type of the HTTP field. Note the rules specified in Section 4 of [STRUCTURED-FIELDS] applicable to
that this process will replace any optional internal whitespace with the type of the HTTP field. Note that this process will replace any
a single space character, among other potential transformations of optional internal whitespace with a single space character, among
the value. other potential transformations of the value.
For example, the following dictionary field is a valid serialization: For example, the following dictionary field is a valid serialization:
Example-Dict: a=1, b=2;x=1;y=2, c=(a b c) Example-Dict: a=1, b=2;x=1;y=2, c=(a b c)
If included in the input string as-is, it would be: If included in the signature base without parameters, its value would
be:
"example-dict": a=1, b=2;x=1;y=2, c=(a b c) "example-dict": a=1, b=2;x=1;y=2, c=(a b c)
However, if the "sf" parameter is added, the value is re-serialized However, if the "sf" parameter is added, the value is re-serialized
as follows: as follows:
"example-dict";sf: a=1, b=2;x=1;y=2, c=(a b c) "example-dict";sf: a=1, b=2;x=1;y=2, c=(a b c)
The resulting string is used as the component value in Section 2.1. The resulting string is used as the component value in Section 2.1.
2.1.2. Dictionary Structured Field Members 2.1.2. Dictionary Structured Field Members
If a given field is known by the application to be a Dictionary If a given field is known by the application to be a Dictionary
skipping to change at page 16, line 47 skipping to change at page 17, line 15
signing a response, the signer can include any derived components signing a response, the signer can include any derived components
from the originating request by using the request-response signature from the originating request by using the request-response signature
binding parameter (Section 2.3). binding parameter (Section 2.3).
request: Values derived from and results applied to an HTTP request request: Values derived from and results applied to an HTTP request
message as described in Section 3.4 of [HTTP]. message as described in Section 3.4 of [HTTP].
response: Values derived from and results applied to an HTTP response: Values derived from and results applied to an HTTP
response message as described in Section 3.4 of [HTTP]. response message as described in Section 3.4 of [HTTP].
A derived component definition MUST define all targets to which it A derived component definition MUST define all target messages to
can be applied. which it can be applied.
The component value MUST be derived from the HTTP message being
signed or the context in which the derivation occurs. The derived
component value MUST be of the following form:
derived-component-value = *VCHAR Derived component values MUST be limited to printable characters and
spaces and MUST NOT contain any newline characters.
2.2.1. Signature Parameters 2.2.1. Signature Parameters
HTTP Message Signatures have metadata properties that provide HTTP Message Signatures have metadata properties that provide
information regarding the signature's generation and verification, information regarding the signature's generation and verification,
such as the set of covered components, a timestamp, identifiers for such as the set of covered components, a timestamp, identifiers for
verification key material, and other utilities. verification key material, and other utilities.
The signature parameters component name is "@signature-params". This The signature parameters component name is "@signature-params". This
message component's value is REQUIRED as part of the signature base message component's value is REQUIRED as part of the signature base
skipping to change at page 24, line 19 skipping to change at page 24, line 38
signature base generation. signature base generation.
For example for the following request: For example for the following request:
POST /path?param=value&foo=bar&baz=batman&qux= HTTP/1.1 POST /path?param=value&foo=bar&baz=batman&qux= HTTP/1.1
Host: www.example.com Host: www.example.com
Indicating the "baz", "qux" and "param" named query parameters in Indicating the "baz", "qux" and "param" named query parameters in
would result in the following "@query-param" component values: would result in the following "@query-param" component values:
_baz:_ "batman" _baz_: "batman"
_qux:_ an empty string _qux_: an empty string
_param:_ "value" _param_: "value"
And the following signature base lines: And the following signature base lines:
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
"@query-param";name="baz": batman "@query-param";name="baz": batman
"@query-param";name="qux": \ "@query-param";name="qux": \
"@query-param";name="param": value "@query-param";name="param": value
If a parameter name occurs multiple times in a request, all parameter If a parameter name occurs multiple times in a request, all parameter
values of that name MUST be included in separate signature base lines values of that name MUST be included in separate signature base lines
in the order in which the parameters occur in the target URI. Note in the order in which the parameters occur in the target URI. Note
that in some implementations, the order of parsed query parameters is that in some implementations, the order of parsed query parameters is
not stable, and this situation could lead to unexpected results. If not stable, and this situation could lead to unexpected results. If
multiple parameters are common within an application, it is multiple parameters are common within an application, it is
RECOMMENDED to sign the entire query string using the "@query" RECOMMENDED to sign the entire query string using the "@query"
component identifier defined in Section 2.2.8. component identifier defined in Section 2.2.8.
2.2.10. Status Code 2.2.10. Status Code
skipping to change at page 26, line 36 skipping to change at page 26, line 48
This would result in the following unsigned response message: This would result in the following unsigned response message:
HTTP/1.1 503 Service Unavailable HTTP/1.1 503 Service Unavailable
Date: Tue, 20 Apr 2021 02:07:56 GMT Date: Tue, 20 Apr 2021 02:07:56 GMT
Content-Type: application/json Content-Type: application/json
Content-Length: 62 Content-Length: 62
{"busy": true, "message": "Your call is very important to us"} {"busy": true, "message": "Your call is very important to us"}
To cryptographically link the response to the request, the server To cryptographically link the response to the request, the server
signs the response with its own key and includes the signature of signs the response with its own key and includes the method,
"sig1" from the request in the covered components of the response. authority, and the signature value "sig1" from the request in the
The signature base for this example is: covered components of the response. The signature base for this
example is:
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
"@status": 503 "@status": 503
"content-length": 62 "content-length": 62
"content-type": application/json "content-type": application/json
"signature";req;key="sig1": :LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJRGziC\ "signature";req;key="sig1": :LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJRGziC\
LuD8r5MW9S0RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVdwXyY\ LuD8r5MW9S0RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVdwXyY\
/UkBIS1M8Brc8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMTe0QE\ /UkBIS1M8Brc8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMTe0QE\
3IpWINTEzpxjqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuTZ9Hd\ 3IpWINTEzpxjqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuTZ9Hd\
bD2Tr65+BXeTG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S1ag3\ bD2Tr65+BXeTG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S1ag3\
LZElYyUKaAIjZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==: LZElYyUKaAIjZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==:
"@authority";req: example.com
"@method";req: POST
"@signature-params": ("@status" "content-length" "content-type" \ "@signature-params": ("@status" "content-length" "content-type" \
"signature";req;key="sig1");created=1618884479\ "signature";req;key="sig1" "@authority";req "@method";req)\
;keyid="test-key-ecc-p256" ;created=1618884479;keyid="test-key-ecc-p256"
The signed response message is: The signed response message is:
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
HTTP/1.1 503 Service Unavailable HTTP/1.1 503 Service Unavailable
Date: Tue, 20 Apr 2021 02:07:56 GMT Date: Tue, 20 Apr 2021 02:07:56 GMT
Content-Type: application/json Content-Type: application/json
Content-Length: 62 Content-Length: 62
Signature-Input: reqres=("@status" "content-length" "content-type" \ Signature-Input: reqres=("@status" "content-length" "content-type" \
"signature";req;key="sig1");created=1618884479\ "signature";req;key="sig1" "@authority";req "@method";req)\
;keyid="test-key-ecc-p256" ;created=1618884479;keyid="test-key-ecc-p256"
Signature: reqres=:vR1E+sDgh0J3dZyVdPc7mK0ZbEMW3N47eDpFjXLE9g95Gx1K\ Signature: reqres=:mh17P4TbYYBmBwsXPT4nsyVzW4Rp9Fb8WcvnfqKCQLoMvzOB\
QLpdOmDQfedgdLzaFCqfD0WPn9e9/jubyUuZRw==: LD/n32tL/GPW6XE5GAS5bdsg1khK6lBzV1Cx/Q==:
{"busy": true, "message": "Your call is very important to us"} {"busy": true, "message": "Your call is very important to us"}
Since the request's signature value itself is not repeated in the Since the request's signature value itself is not repeated in the
response, the requester MUST keep the original signature value around response, the requester MUST keep the original signature value around
long enough to validate the signature of the response that uses this long enough to validate the signature of the response that uses this
component identifier. component identifier.
Note that the ECDSA algorithm in use here is non-deterministic, Note that the ECDSA algorithm in use here is non-deterministic,
meaning a different signature value will be created every time the meaning a different signature value will be created every time the
algorithm is run. The signature value provided here can be validated algorithm is run. The signature value provided here can be validated
against the given keys, but newly-generated signature values are not against the given keys, but newly-generated signature values are not
expected to match the example. See Section 7.19. expected to match the example. See Section 7.19.
The "req" parameter MUST NOT be used with a request message. The "req" parameter MUST NOT be used in a signature that targets a
request message.
2.4. Creating the Signature Base 2.4. Creating the Signature Base
The signature base is a US-ASCII string containing the canonicalized The signature base is a US-ASCII string containing the canonicalized
HTTP message components covered by the signature. The input to the HTTP message components covered by the signature. The input to the
signature base creation algorithm is the list of covered component signature base creation algorithm is the list of covered component
identifiers and their associated values, along with any additional identifiers and their associated values, along with any additional
signature parameters. The output is the ordered set of bytes that signature parameters.
form the signature base, which conforms to the following ABNF:
signature-base = *( signature-base-line LF ) signature-params-line Component identifiers are serialized using the production grammar
signature-base-line = component-identifier ":" SP defined by [STRUCTURED-FIELDS], Section 4. The component identifier
( derived-component-value / field-value ) has a component name, which is a String Item value serialized using
signature-params-line = DQUOTE "@signature-params" DQUOTE ":" SP inner-list the "sf-string" ABNF rule. The component identifier MAY also include
defined parameters which are serialized using the "parameters" ABNF
rule. The signature parameters line defined in Section 2.2.1 follows
this same pattern, but the component identifier is a String Item with
a fixed value and no parameters, and the component value is always an
Inner List with optional parameters.
Note that this means the serialization of the component name itself
is encased in double quotes, with parameters following as a
semicolon-separated list, such as ""cache-control"", ""@authority"",
""@signature-params"", or ""example-dictionary";key="foo"".
The output is the ordered set of bytes that form the signature base,
which conforms to the following ABNF:
signature-base = *( signature-base-line LF ) signature-params-line
signature-base-line = component-identifier ":" SP
( derived-component-value / field-content ) ; no obs-fold
component-identifier = component-name parameters
component-name = sf-string
derived-component-value = *( VCHAR / SP )
signature-params-line = DQUOTE "@signature-params" DQUOTE
":" SP inner-list
To create the signature base, the signer or verifier concatenates To create the signature base, the signer or verifier concatenates
together entries for each identifier in the signature's covered together entries for each component identifier in the signature's
components (including their parameters) using the following covered components (including their parameters) using the following
algorithm: algorithm. All errors produced as described immediately MUST fail
the algorithm and there is no signature output base created.
1. Let the output be an empty string. 1. Let the output be an empty string.
2. For each message component item in the covered components set (in 2. For each message component item in the covered components set (in
order): order):
1. Append the component identifier for the covered component 1. Append the component identifier for the covered component
serialized according to the "component-identifier" rule. serialized according to the "component-identifier" ABNF rule.
Note that this serialization places the component name in Note that this serialization places the component name in
double quotes and appends any parameters outside of the double quotes and appends any parameters outside of the
quotes. quotes.
2. Append a single colon ":" 2. Append a single colon ":"
3. Append a single space " " 3. Append a single space " "
4. Determine the component value for the component identifier. 4. Determine the component value for the component identifier.
+ If the component identifier has a parameter that is not
understood, produce an error.
+ If the component name starts with an "at" character ("@"), + If the component name starts with an "at" character ("@"),
derive the component's value from the message according to derive the component's value from the message according to
the specific rules defined for the derived component, as the specific rules defined for the derived component, as
in Section 2.2. If the derived component name is unknown in Section 2.2, including processing of any known valid
or the value cannot be derived, produce an error. parameters. If the derived component name is unknown or
the value cannot be derived, produce an error.
+ If the component name does not start with an "at" + If the component name does not start with an "at"
character ("@"), canonicalize the HTTP field value as character ("@"), canonicalize the HTTP field value as
described in Section 2.1. If the value cannot be described in Section 2.1, including processing of any
calculated, produce an error. known valid parameters. If the field cannot be found in
the message, or the value cannot be obtained in the
context, produce an error.
5. Append the covered component's canonicalized component value. 5. Append the covered component's canonicalized component value.
6. Append a single newline "\n" 6. Append a single newline "\n"
3. Append the signature parameters component (Section 2.2.1) as 3. Append the signature parameters component (Section 2.2.1)
follows: according to the "signature-params-line" as follows:
1. Append the component identifier for the signature parameters 1. Append the component identifier for the signature parameters
serialized according to the "component-identifier" rule, i.e. serialized according to the "component-identifier" rule, i.e.
""@signature-params"" the exact value ""@signature-params"" (including double
quotes)
2. Append a single colon ":" 2. Append a single colon ":"
3. Append a single space " " 3. Append a single space " "
4. Append the signature parameters' canonicalized component 4. Append the signature parameters' canonicalized component
value as defined in Section 2.2.1 value as defined in Section 2.2.1, i.e. an Inner List
structured field value with parameters
4. Return the output string. 4. Return the output string.
If covered components reference a component identifier that cannot be If covered components reference a component identifier that cannot be
resolved to a component value in the message, the implementation MUST resolved to a component value in the message, the implementation MUST
produce an error and not create an input string. Such situations are produce an error and not create a signature base. Such situations
included but not limited to: are included but not limited to:
o The signer or verifier does not understand the derived component o The signer or verifier does not understand the derived component
name. name.
o The component name identifies a field that is not present in the o The component name identifies a field that is not present in the
message or whose value is malformed. message or whose value is malformed.
o The component identifier includes a parameter that is unknown or
does not apply to the component identifier to which it is
attached.
o The component identifier indicates that a structured field o The component identifier indicates that a structured field
serialization is used (via the "sf" parameter), but the field in serialization is used (via the "sf" parameter), but the field in
question is known to not be a structured field or the type of question is known to not be a structured field or the type of
structured field is not known to the implementation. structured field is not known to the implementation.
o The component identifier is a dictionary member identifier that o The component identifier is a dictionary member identifier that
references a field that is not present in the message, is not a references a field that is not present in the message, is not a
Dictionary Structured Field, or whose value is malformed. Dictionary Structured Field, or whose value is malformed.
o The component identifier is a dictionary member identifier or a o The component identifier is a dictionary member identifier or a
named query parameter identifier that references a member that is named query parameter identifier that references a member that is
not present in the component value, or whose value is malformed. not present in the component value, or whose value is malformed.
E.g., the identifier is ""example-dict";key="c"" and the value of E.g., the identifier is ""example-dict";key="c"" and the value of
the "Example-Dict" header field is "a=1, b=2", which does not have the Example-Dict header field is "a=1, b=2", which does not have
the "c" value. the "c" value.
In the following non-normative example, the HTTP message being signed In the following non-normative example, the HTTP message being signed
is the following request: is the following request:
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
POST /foo?param=Value&Pet=dog HTTP/1.1 POST /foo?param=Value&Pet=dog HTTP/1.1
Host: example.com Host: example.com
Date: Tue, 20 Apr 2021 02:07:55 GMT Date: Tue, 20 Apr 2021 02:07:55 GMT
skipping to change at page 31, line 37 skipping to change at page 31, line 46
a subset of the components of an HTTP message in addition to metadata a subset of the components of an HTTP message in addition to metadata
about the signature itself. When successfully verified against an about the signature itself. When successfully verified against an
HTTP message, an HTTP Message Signature provides cryptographic proof HTTP message, an HTTP Message Signature provides cryptographic proof
that the message is semantically equivalent to the message for which that the message is semantically equivalent to the message for which
the signature was generated, with respect to the subset of message the signature was generated, with respect to the subset of message
components that was signed. components that was signed.
3.1. Creating a Signature 3.1. Creating a Signature
Creation of an HTTP message signature is a process that takes as its Creation of an HTTP message signature is a process that takes as its
input the message and the requirements for the application. The input the message context and the requirements for the application.
output is a signature value and set of signature parameters that can The output is a signature value and set of signature parameters that
be applied to the message. can be communicated to the verifier by adding them to the message.
In order to create a signature, a signer MUST follow the following In order to create a signature, a signer MUST follow the following
algorithm: algorithm:
1. The signer chooses an HTTP signature algorithm and key material 1. The signer chooses an HTTP signature algorithm and key material
for signing. The signer MUST choose key material that is for signing. The signer MUST choose key material that is
appropriate for the signature's algorithm, and that conforms to appropriate for the signature's algorithm, and that conforms to
any requirements defined by the algorithm, such as key size or any requirements defined by the algorithm, such as key size or
format. The mechanism by which the signer chooses the algorithm format. The mechanism by which the signer chooses the algorithm
and key material is out of scope for this document. and key material is out of scope for this document.
skipping to change at page 32, line 21 skipping to change at page 32, line 34
4. The signer creates an ordered set of component identifiers 4. The signer creates an ordered set of component identifiers
representing the message components to be covered by the representing the message components to be covered by the
signature, and attaches signature metadata parameters to this signature, and attaches signature metadata parameters to this
set. The serialized value of this is later used as the value of set. The serialized value of this is later used as the value of
the Signature-Input field as described in Section 4.1. the Signature-Input field as described in Section 4.1.
* Once an order of covered components is chosen, the order MUST * Once an order of covered components is chosen, the order MUST
NOT change for the life of the signature. NOT change for the life of the signature.
* Each covered component identifier MUST be either an HTTP field * Each covered component identifier MUST be either an HTTP field
in the message Section 2.1 or a derived component listed in in the message context Section 2.1 or a derived component
Section 2.2 or its associated registry. listed in Section 2.2 or its associated registry.
* Signers of a request SHOULD include some or all of the message * Signers of a request SHOULD include some or all of the message
control data in the covered components, such as the "@method", control data in the covered components, such as the "@method",
"@authority", "@target-uri", or some combination thereof. "@authority", "@target-uri", or some combination thereof.
* Signers SHOULD include the "created" signature metadata * Signers SHOULD include the "created" signature metadata
parameter to indicate when the signature was created. parameter to indicate when the signature was created.
* The "@signature-params" derived component identifier is not * The "@signature-params" derived component identifier MUST NOT
explicitly listed in the list of covered component be listed in the list of covered component identifiers. The
identifiers, because it is required to always be present as derived component is required to always be the last line in
the last line in the signature base. This ensures that a the signature base. This practice ensures that a signature
signature always covers its own metadata. always covers its own metadata and the metadata cannot be
substituted.
* Further guidance on what to include in this set and in what * Further guidance on what to include in this set and in what
order is out of scope for this document. order is out of scope for this document.
5. The signer creates the signature base using these parameters and 5. The signer creates the signature base using these parameters and
the signature base creation algorithm. (Section 2.4) the signature base creation algorithm. (Section 2.4)
6. The signer uses the "HTTP_SIGN" primitive function to sign the 6. The signer uses the "HTTP_SIGN" primitive function to sign the
signature base with the chosen signing algorithm using the key signature base with the chosen signing algorithm using the key
material chosen by the signer. The "HTTP_SIGN" primitive and material chosen by the signer. The "HTTP_SIGN" primitive and
several concrete applications of signing algorithms are defined several concrete applications of signing algorithms are defined
in in Section 3.3. in in Section 3.3.
7. The byte array output of the signature function is the HTTP 7. The byte array output of the signature function is the HTTP
message signature output value to be included in the "Signature" message signature output value to be included in the Signature
field as defined in Section 4.2. field as defined in Section 4.2.
For example, given the HTTP message and signature parameters in the For example, given the HTTP message and signature parameters in the
example in Section 2.4, the example signature base is signed with the example in Section 2.4, the example signature base is signed with the
"test-key-rsa-pss" key in Appendix B.1.2 and the RSA PSS algorithm "test-key-rsa-pss" key in Appendix B.1.2 and the RSA PSS algorithm
described in Section 3.3.1, giving the following message signature described in Section 3.3.1, giving the following message signature
output value, encoded in Base64: output value, encoded in Base64:
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
skipping to change at page 50, line 16 skipping to change at page 50, line 12
Specification document(s): Specification document(s):
Reference to the document(s) that specify the algorithm, Reference to the document(s) that specify the algorithm,
preferably including a URI that can be used to retrieve a copy of preferably including a URI that can be used to retrieve a copy of
the document(s). An indication of the relevant sections may also the document(s). An indication of the relevant sections may also
be included but is not required. be included but is not required.
6.1.2. Initial Contents 6.1.2. Initial Contents
+---------------------+--------------------+--------+---------------+ +---------------------+-------------------+--------+----------------+
| Algorithm Name | Description | Status | Specification | | Algorithm Name | Description | Status | Specification |
| | | | document(s) | | | | | document(s) |
+---------------------+--------------------+--------+---------------+ +---------------------+-------------------+--------+----------------+
| "rsa-pss-sha512" | RSASSA-PSS using | Active | Section 3.3.1 | | "rsa-pss-sha512" | RSASSA-PSS using | Active | Section 3.3.1 |
| | SHA-512 | | of RFC nnnn | | | SHA-512 | | of RFC nnnn |
| "rsa-v1_5-sha256" | RSASSA-PKCS1-v1_5 | Active | Section 3.3.2 | | "rsa-v1_5-sha256" | RSASSA-PKCS1-v1_5 | Active | Section 3.3.2 |
| | using SHA-256 | | of RFC nnnn | | | using SHA-256 | | of RFC nnnn |
| "hmac-sha256" | HMAC using SHA-256 | Active | Section 3.3.3 | | "hmac-sha256" | HMAC using | Active | Section 3.3.3 |
| | | | of RFC nnnn | | | SHA-256 | | of RFC nnnn |
| "ecdsa-p256-sha256" | ECDSA using curve | Active | Section 3.3.4 | | "ecdsa-p256-sha256" | ECDSA using curve | Active | Section 3.3.4 |
| | P-256 DSS and | | of RFC nnnn | | | P-256 DSS and | | of RFC nnnn |
| | SHA-256 | | | | | SHA-256 | | |
| "ed25519" | Edwards Curve DSA | Active | Section 3.3.5 | | "ed25519" | Edwards Curve DSA | Active | Section 3.3.5 |
| | using curve | | of RFC nnnn | | | using curve | | of RFC nnnn |
| | edwards25519 | | | | | edwards25519 | | |
+---------------------+--------------------+--------+---------------+ +---------------------+-------------------+--------+----------------+
Initial contents of the HTTP Signature Algorithms Registry. Initial contents of the HTTP Signature Algorithms Registry.
6.2. HTTP Signature Metadata Parameters Registry 6.2. HTTP Signature Metadata Parameters Registry
This document defines the signature parameters structure, the values This document defines the signature parameters structure, the values
of which may have parameters containing metadata about a message of which may have parameters containing metadata about a message
signature. IANA is asked to create and maintain a new registry signature. IANA is asked to create and maintain a new registry
titled "HTTP Signature Metadata Parameters" to record and maintain titled "HTTP Signature Metadata Parameters" to record and maintain
the set of parameters defined for use with member values in the the set of parameters defined for use with member values in the
skipping to change at page 53, line 12 skipping to change at page 52, line 51
Reference to the document(s) that specify the derived component, Reference to the document(s) that specify the derived component,
preferably including a URI that can be used to retrieve a copy of preferably including a URI that can be used to retrieve a copy of
the document(s). An indication of the relevant sections may also the document(s). An indication of the relevant sections may also
be included but is not required. be included but is not required.
6.3.2. Initial Contents 6.3.2. Initial Contents
The table below contains the initial contents of the HTTP Signature The table below contains the initial contents of the HTTP Signature
Derived Component Names Registry. Derived Component Names Registry.
+---------------+----------+--------+---------+------------+--------+ +-------------------+------------+-------+----------+---------------+
| Name | Descript | Status | Target | Specificat | | | Name | Descriptio | Statu | Target | Specification |
| | ion | | | ion docume | | | | n | s | | document(s) |
| | | | | nt(s) | | +-------------------+------------+-------+----------+---------------+
+---------------+----------+--------+---------+------------+--------+ | "@signature- | Signature | Activ | Request, | Section 2.2.1 |
| "@signature- | Signatur | Active | Request | Section 2. | | | params" | parameters | e | Response | of RFC nnnn |
| params" | e parame | | , Respo | 2.1 of RFC | | | | , | | | |
| | ters, in | | nse | nnnn | | | | including | | | |
| | cluding | | | | | | | covered | | | |
| | covered | | | | | | | content | | | |
| | content | | | | | | | list | | | |
| | list | | | | | | "@method" | The HTTP | Activ | Request | Section 2.2.2 |
| "@method" | The HTTP | Active | Request | Section 2. | | | | request | e | | of RFC nnnn |
| | request | | | 2.2 of RFC | | | | method | | | |
| | method | | | nnnn | | | "@authority" | The HTTP | Activ | Request | Section 2.2.4 |
| "@authority" | The HTTP | Active | Request | Section 2. | | | | authority, | e | | of RFC nnnn |
| | authorit | | | 2.4 of RFC | | | | or target | | | |
| | y, or | | | nnnn | | | | host | | | |
| | target | | | | | | "@scheme" | The URI | Activ | Request | Section 2.2.5 |
| | host | | | | | | | scheme of | e | | of RFC nnnn |
| "@scheme" | The URI | Active | Request | Section 2. | | | | the | | | |
| | scheme | | | 2.5 of RFC | | | | request | | | |
| | of the | | | nnnn | | | | URI | | | |
| | request | | | | | | "@target-uri" | The full | Activ | Request | Section 2.2.3 |
| | URI | | | | | | | target URI | e | | of RFC nnnn |
| "@target-uri" | The full | Active | Request | Section 2. | | | | of the | | | |
| | target | | | 2.3 of RFC | | | | request | | | |
| | URI of | | | nnnn | | | "@request-target" | The | Activ | Request | Section 2.2.6 |
| | the | | | | | | | request | e | | of RFC nnnn |
| | request | | | | | | | target of | | | |
| "@request- | The | Active | Request | Section 2. | | | | the | | | |
| target" | request | | | 2.6 of RFC | | | | request | | | |
| | target | | | nnnn | | | "@path" | The full | Activ | Request | Section 2.2.7 |
| | of the | | | | | | | path of | e | | of RFC nnnn |
| | request | | | | | | | the | | | |
| "@path" | The full | Active | Request | Section 2. | | | | request | | | |
| | path of | | | 2.7 of RFC | | | | URI | | | |
| | the | | | nnnn | | | "@query" | The full | Activ | Request | Section 2.2.8 |
| | request | | | | | | | query of | e | | of RFC nnnn |
| | URI | | | | | | | the | | | |
| "@query" | The full | Active | Request | Section 2. | | | | request | | | |
| | query of | | | 2.8 of RFC | | | | URI | | | |
| | the | | | nnnn | | | "@query-param" | A single | Activ | Request | Section 2.2.9 |
| | request | | | | | | | named | e | | of RFC nnnn |
| | URI | | | | | | | query | | | |
| "@query- | | A | Active | Request | Sectio | | | parameter | | | |
| param" | | single | | | n 2.2. | | "@status" | The status | Activ | Response | Section 2.2.1 |
| | | named | | | 9 of | | | code of | e | | 0 of RFC nnnn |
| | | query | | | RFC | | | the | | | |
| | | parame | | | nnnn | | | response | | | |
| | | ter | | | | +-------------------+------------+-------+----------+---------------+
| "@status" | The | Active | Respons | Section 2. | |
| | status | | e | 2.10 of | |
| | code of | | | RFC nnnn | |
| | the | | | | |
| | response | | | | |
+---------------+----------+--------+---------+------------+--------+
Initial contents of the HTTP Signature Derived Component Names Initial contents of the HTTP Signature Derived Component Names
Registry. Registry.
6.4. HTTP Signature Component Parameters Registry 6.4. HTTP Signature Component Parameters Registry
This document defines several kinds of component identifiers, some of This document defines several kinds of component identifiers, some of
which can be parameterized in specific circumstances to provide which can be parameterized in specific circumstances to provide
unique modified behavior. IANA is asked to create and maintain a new unique modified behavior. IANA is asked to create and maintain a new
registry typed "HTTP Signature Component Parameters" to record and registry typed "HTTP Signature Component Parameters" to record and
skipping to change at page 55, line 14 skipping to change at page 54, line 46
Status: Status:
A brief text description of the status of the parameter. The A brief text description of the status of the parameter. The
description MUST begin with one of "Active" or "Deprecated", and description MUST begin with one of "Active" or "Deprecated", and
MAY provide further context or explanation as to the reason for MAY provide further context or explanation as to the reason for
the status. the status.
Target: Target:
The applicable component identifiers for the parmeter. Can be a The applicable component identifiers for the parameter. Can be a
combination of one or more derived component identifiers as combination of one or more derived component identifiers as
described in Section 2.2, one or more specific HTTP field names, described in Section 2.2, one or more specific HTTP field names,
the special value "Field Value" meaning all HTTP fields, or a the special value "Field Value" meaning all HTTP fields, or a
separate human-readable description of the target. separate human-readable description of the target.
Specification document(s): Specification document(s):
Reference to the document(s) that specify the derived component, Reference to the document(s) that specify the derived component,
preferably including a URI that can be used to retrieve a copy of preferably including a URI that can be used to retrieve a copy of
the document(s). An indication of the relevant sections may also the document(s). An indication of the relevant sections may also
skipping to change at page 58, line 20 skipping to change at page 58, line 5
The HTTP Message Signatures specification does not define any of its The HTTP Message Signatures specification does not define any of its
own cryptographic primitives, and instead relies on other own cryptographic primitives, and instead relies on other
specifications to define such elements. If the signature algorithm specifications to define such elements. If the signature algorithm
or key used to process the signature base is vulnerable to any or key used to process the signature base is vulnerable to any
attacks, the resulting signature will also be susceptible to these attacks, the resulting signature will also be susceptible to these
same attacks. same attacks.
A common attack against signature systems is to force a signature A common attack against signature systems is to force a signature
collision, where the same signature value successfully verifies collision, where the same signature value successfully verifies
against multiple different inputs. Since this specification relies against multiple different inputs. Since this specification relies
on reconstruction of the input string based on an HTTP message, and on reconstruction of the signature base from an HTTP message, and the
the list of components signed is fixed in the signature, it is list of components signed is fixed in the signature, it is difficult
difficult but not impossible for an attacker to effect such a but not impossible for an attacker to effect such a collision. An
collision. An attacker would need to manipulate the HTTP message and attacker would need to manipulate the HTTP message and its covered
its covered message components in order to make the collision message components in order to make the collision effective.
effective.
To counter this, only vetted keys and signature algorithms should be To counter this, only vetted keys and signature algorithms should be
used to sign HTTP messages. The HTTP Message Signatures Algorithm used to sign HTTP messages. The HTTP Message Signatures Algorithm
Registry is one source of potential trusted algorithms. Registry is one source of potential trusted algorithms.
While it is possible for an attacker to substitute the signature While it is possible for an attacker to substitute the signature
parameters value or the signature value separately, the signature parameters value or the signature value separately, the signature
base generation algorithm (Section 2.4) always covers the signature base generation algorithm (Section 2.4) always covers the signature
parameters as the final value in the input string using a parameters as the final value in the signature base using a
deterministic serialization method. This step strongly binds the deterministic serialization method. This step strongly binds the
signature base with the signature value in a way that makes it much signature base with the signature value in a way that makes it much
more difficult for an attacker to perform a partial substitution on more difficult for an attacker to perform a partial substitution on
the signature bases. the signature bases.
7.6. Key Theft 7.6. Key Theft
A foundational assumption of signature-based cryptographic systems is A foundational assumption of signature-based cryptographic systems is
that the signing key is not compromised by an attacker. If the keys that the signing key is not compromised by an attacker. If the keys
used to sign the message are exfiltrated or stolen, the attacker will used to sign the message are exfiltrated or stolen, the attacker will
skipping to change at page 60, line 20 skipping to change at page 60, line 4
HTTP Message Signature values are identified in the Signature and HTTP Message Signature values are identified in the Signature and
Signature-Input field values by unique labels. These labels are Signature-Input field values by unique labels. These labels are
chosen only when attaching the signature values to the message and chosen only when attaching the signature values to the message and
are not accounted for in the signing process. An intermediary adding are not accounted for in the signing process. An intermediary adding
its own signature is allowed to re-label an existing signature when its own signature is allowed to re-label an existing signature when
processing the message. processing the message.
Therefore, applications should not rely on specific labels being Therefore, applications should not rely on specific labels being
present, and applications should not put semantic meaning on the present, and applications should not put semantic meaning on the
labels themselves. Instead, additional signature parmeters can be labels themselves. Instead, additional signature parameters can be
used to convey whatever additional meaning is required to be attached used to convey whatever additional meaning is required to be attached
to and covered by the signature. to and covered by the signature.
7.11. Symmetric Cryptography 7.11. Symmetric Cryptography
The HTTP Message Signatures specification allows for both asymmetric The HTTP Message Signatures specification allows for both asymmetric
and symmetric cryptography to be applied to HTTP messages. By its and symmetric cryptography to be applied to HTTP messages. By its
nature, symmetric cryptographic methods require the same key material nature, symmetric cryptographic methods require the same key material
to be known by both the signer and verifier. This effectively means to be known by both the signer and verifier. This effectively means
that a verifier is capable of generating a valid signature, since that a verifier is capable of generating a valid signature, since
skipping to change at page 61, line 23 skipping to change at page 61, line 4
processing by taking the single value of a field and using it as the processing by taking the single value of a field and using it as the
direct component value without processing it appropriately. direct component value without processing it appropriately.
For example, if the handling of "obs-fold" field values does not For example, if the handling of "obs-fold" field values does not
remove the internal line folding and whitespace, additional newlines remove the internal line folding and whitespace, additional newlines
could be introduced into the signature base by the signer, providing could be introduced into the signature base by the signer, providing
a potential place for an attacker to mount a signature collision a potential place for an attacker to mount a signature collision
(Section 7.5) attack. Alternatively, if header fields that appear (Section 7.5) attack. Alternatively, if header fields that appear
multiple times are not joined into a single string value, as is multiple times are not joined into a single string value, as is
required by this specification, similar attacks can be mounted as a required by this specification, similar attacks can be mounted as a
signed component value would show up in the input string more than signed component value would show up in the signature base more than
once and could be substituted or otherwise attacked in this way. once and could be substituted or otherwise attacked in this way.
To counter this, the entire field processing algorithm needs to be To counter this, the entire field processing algorithm needs to be
implemented by all implementations of signers and verifiers. implemented by all implementations of signers and verifiers.
7.13. Key Specification Mix-Up 7.13. Key Specification Mix-Up
The existence of a valid signature on an HTTP message is not The existence of a valid signature on an HTTP message is not
sufficient to prove that the message has been signed by the sufficient to prove that the message has been signed by the
appropriate party. It is up to the verifier to ensure that a given appropriate party. It is up to the verifier to ensure that a given
skipping to change at page 66, line 23 skipping to change at page 66, line 4
follows: follows:
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Content-Digest: \ Content-Digest: \
sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
{"hello": "world"} {"hello": "world"}
This field can be included in a signature base just like any other This field can be included in a signature base just like any other
field along with the basic signature parameters: field along with the basic signature parameters:
"@status": 200 "@status": 200
"content-digest": \ "content-digest": \
sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
"@signature-input": ("@status" "content-digest") "@signature-input": ("@status" "content-digest")
From here, the signing process proceeds as usual. From here, the signing process proceeds as usual.
Upon verification, it is important that the verifier validate not Upon verification, it is important that the verifier validate not
only the signature but also the value of the Content-Digest field only the signature but also the value of the Content-Digest field
itself against the actual received content. Unless the verifier itself against the actual received content. Unless the verifier
performs this step, it would be possible for an attacker to performs this step, it would be possible for an attacker to
substitute the message content but leave the Content-Digest field substitute the message content but leave the Content-Digest field
value untouched. Since only the field value is covered by the value untouched. Since only the field value is covered by the
signature directly, checking only the signature is not sufficient signature directly, checking only the signature is not sufficient
protection against such a substitution attack. protection against such a substitution attack.
7.23. Non-List Field Values
When an HTTP field occurs multiple times in a single message, these
values need to be combined into a single one-line string value to be
included in the HTTP signature base, as described in Section 2.4.
Not all HTTP fields can be combined into a single value in this way
and still be a valid value for the field. For the purposes of
generating the signature base, the message component value is never
meant to be read back out of the signature base string or used in the
application. Therefore it is considered best practice to treat the
signature base generation algorithm separately from processing the
field values by the application, particularly for fields that are
known to have this property. If the field values that are being
signed do not validate, the signed message should also be rejected.
If an HTTP field allows for unquoted commas within its values,
combining multiple field values can lead to a situation where two
semantically different messages produce the same line in a signature
base. For example, take the following hypothetical header field with
an internal comma in its syntax, here used to define two separate
lists of values:
Example-Header: value, with, lots
Example-Header: of, commas
For this header field, sending all of these values as a single field
value results in a single list of values:
Example-Header: value, with, lots, of, commas
Both of these messages would create the following line in the
signature base:
"example-header": value, with, lots, of, commas
Since two semantically distinct inputs can create the same output in
the signature base, special care has to be taken when handling such
values.
Specifically, the Set-Cookie field [COOKIE] defines an internal
syntax that does not conform to the List syntax in
[STRUCTURED-FIELDS]. In particular some portions allow unquoted
commas, and the field is typically sent as multiple separate field
lines with distinct values when sending multiple cookies. When
multiple Set-Cookie fields are sent in the same message, it is not
generally possible to combine these into a single line and be able to
parse and use the results, as discussed in [HTTP], Section 5.3.
Therefore, all the cookies need to be processed from their separate
header values, without being combined, while the signature base needs
to be processed from the special combined value generated solely for
this purpose. If the cookie value is invalid, the signed message
ought to be rejected as this is a possible padding attack as
described in Section 7.24.
To deal with this, an application can choose to limit signing of
problematic fields like Set-Cookie, such as including the field in a
signature only when a single field value is present and the results
would be unambiguous. Similar caution needs to be taken with all
fields that could have non-deterministic mappings into the signature
base.
7.24. Padding Attacks with Multiple Field Values
Since HTTP field values need to be combined in a single string value
to be included in the HTTP signature base, as described in
Section 2.4, it is possible for an attacker to inject an additional
value for a given field and add this to the signature base of the
verifier.
In most circumstances, this causes the signature validation to fail
as expected, since the new signature base value will not match the
one used by the signer to create the signature. However, it is
theoretically possible for the attacker to inject both a garbage
value to a field and a desired value to another field in order to
force a particular input. This is a variation of the collision
attack described in Section 7.5, where the attacker accomplishes
their change in the message by adding to existing field values.
To counter this, an application needs to validate the content of the
fields covered in the signature in addition to ensuring that the
signature itself validates. With such protections, the attacker's
padding attack would be rejected by the field value processor, even
in the case where the attacker could force a signature collision.
8. Privacy Considerations 8. Privacy Considerations
8.1. Identification through Keys 8.1. Identification through Keys
If a signer uses the same key with multiple verifiers, or uses the If a signer uses the same key with multiple verifiers, or uses the
same key over time with a single verifier, the ongoing use of that same key over time with a single verifier, the ongoing use of that
key can be used to track the signer throughout the set of verifiers key can be used to track the signer throughout the set of verifiers
that messages are sent to. Since cryptographic keys are meant to be that messages are sent to. Since cryptographic keys are meant to be
functionally unique, the use of the same key over time is a strong functionally unique, the use of the same key over time is a strong
indicator that it is the same party signing multiple messages. indicator that it is the same party signing multiple messages.
skipping to change at page 68, line 13 skipping to change at page 69, line 31
intermediary to verify the signature itself, then modifying the intermediary to verify the signature itself, then modifying the
message to remove the privacy-sensitive information. The message to remove the privacy-sensitive information. The
intermediary can add its own signature at this point to signal to the intermediary can add its own signature at this point to signal to the
next destination that the incoming signature was validated, as is next destination that the incoming signature was validated, as is
shown in the example in Section 4.3. shown in the example in Section 4.3.
9. References 9. References
9.1. Normative References 9.1. Normative References
[ABNF] Ogier, R., "OSPF Database Exchange Summary List
Optimization", RFC 5243, DOI 10.17487/RFC5243, May 2008,
<https://www.rfc-editor.org/info/rfc5243>.
[FIPS186-4] [FIPS186-4]
"Digital Signature Standard (DSS)", 2013, "Digital Signature Standard (DSS)", 2013,
<https://csrc.nist.gov/publications/detail/fips/186/4/ <https://csrc.nist.gov/publications/detail/fips/186/4/
final>. final>.
[HTMLURL] "URL (Living Standard)", 2021, [HTMLURL] "URL (Living Standard)", 2021,
<https://url.spec.whatwg.org/>. <https://url.spec.whatwg.org/>.
[HTTP] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Semantics", draft-ietf-httpbis-semantics-19 (work in Ed., "HTTP Semantics", STD 97, RFC 9110,
progress), September 2021. DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/info/rfc9110>.
[HTTP1] Fielding, R. T., Nottingham, M., and J. Reschke, [HTTP1] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
"HTTP/1.1", draft-ietf-httpbis-messaging-19 (work in Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112,
progress), September 2021. June 2022, <https://www.rfc-editor.org/info/rfc9112>.
[POSIX.1] "The Open Group Base Specifications Issue 7, 2018 [POSIX.1] "The Open Group Base Specifications Issue 7, 2018
edition", 2018, edition", 2018,
<https://pubs.opengroup.org/onlinepubs/9699919799/>. <https://pubs.opengroup.org/onlinepubs/9699919799/>.
[RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
Hashing for Message Authentication", RFC 2104, Hashing for Message Authentication", RFC 2104,
DOI 10.17487/RFC2104, February 1997, DOI 10.17487/RFC2104, February 1997,
<https://www.rfc-editor.org/info/rfc2104>. <https://www.rfc-editor.org/info/rfc2104>.
skipping to change at page 69, line 47 skipping to change at page 71, line 25
9.2. Informative References 9.2. Informative References
[BCP195] Consisting of: [RFC7525], and [RFC8996], [BCP195] Consisting of: [RFC7525], and [RFC8996],
<https://www.rfc-editor.org/info/bcp195>. <https://www.rfc-editor.org/info/bcp195>.
[CLIENT-CERT] [CLIENT-CERT]
Campbell, B. and M. Bishop, "Client-Cert HTTP Header Campbell, B. and M. Bishop, "Client-Cert HTTP Header
Field", draft-ietf-httpbis-client-cert-field-02 (work in Field", draft-ietf-httpbis-client-cert-field-02 (work in
progress), May 2022. progress), May 2022.
[COOKIE] Barth, A., "HTTP State Management Mechanism", RFC 6265,
DOI 10.17487/RFC6265, April 2011,
<https://www.rfc-editor.org/info/rfc6265>.
[DIGEST] Polli, R. and L. Pardue, "Digest Fields", draft-ietf- [DIGEST] Polli, R. and L. Pardue, "Digest Fields", draft-ietf-
httpbis-digest-headers-09 (work in progress), May 2022. httpbis-digest-headers-10 (work in progress), June 2022.
[RFC7239] Petersson, A. and M. Nilsson, "Forwarded HTTP Extension", [RFC7239] Petersson, A. and M. Nilsson, "Forwarded HTTP Extension",
RFC 7239, DOI 10.17487/RFC7239, June 2014, RFC 7239, DOI 10.17487/RFC7239, June 2014,
<https://www.rfc-editor.org/info/rfc7239>. <https://www.rfc-editor.org/info/rfc7239>.
[RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre,
"Recommendations for Secure Use of Transport Layer "Recommendations for Secure Use of Transport Layer
Security (TLS) and Datagram Transport Layer Security Security (TLS) and Datagram Transport Layer Security
(DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May
2015, <https://www.rfc-editor.org/info/rfc7525>. 2015, <https://www.rfc-editor.org/info/rfc7525>.
skipping to change at page 76, line 33 skipping to change at page 78, line 33
See Section 7.4 for more discussion. See Section 7.4 for more discussion.
Note that the RSA PSS algorithm in use here is non-deterministic, Note that the RSA PSS algorithm in use here is non-deterministic,
meaning a different signature value will be created every time the meaning a different signature value will be created every time the
algorithm is run. The signature value provided here can be validated algorithm is run. The signature value provided here can be validated
against the given keys, but newly-generated signature values are not against the given keys, but newly-generated signature values are not
expected to match the example. See Section 7.19. expected to match the example. See Section 7.19.
B.2.2. Selective Covered Components using rsa-pss-sha512 B.2.2. Selective Covered Components using rsa-pss-sha512
This example covers additional components in "test-request" using the This example covers additional components (the authority, the
"rsa-pss-sha512" algorithm. Content-Digest header field, and a single named query parameter) in
"test-request" using the "rsa-pss-sha512" algorithm.
The corresponding signature base is: The corresponding signature base is:
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
"@authority": example.com "@authority": example.com
"content-digest": sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX\ "content-digest": sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX\
+TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: +TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==:
"@signature-params": ("@authority" "content-digest")\ "@query-param";name="Pet": dog
"@signature-params": ("@authority" "content-digest" \
"@query-param";name="Pet")\
;created=1618884473;keyid="test-key-rsa-pss" ;created=1618884473;keyid="test-key-rsa-pss"
This results in the following Signature-Input and Signature headers This results in the following Signature-Input and Signature headers
being added to the message under the label "sig-b22": being added to the message under the label "sig-b22":
NOTE: '\' line wrapping per RFC 8792 NOTE: '\' line wrapping per RFC 8792
Signature-Input: sig-b22=("@authority" "content-digest")\ Signature-Input: sig-b22=("@authority" "content-digest" \
;created=1618884473;keyid="test-key-rsa-pss" "@query-param";name="Pet");created=1618884473\
Signature: sig-b22=:Fee1uy9YGZq5UUwwYU6vz4dZNvfw3GYrFl1L6YlVIyUMuWs\ ;keyid="test-key-rsa-pss"
wWDNSvql4dVtSeidYjYZUm7SBCENIb5KYy2ByoC3bI+7gydd2i4OAT5lyDtmeapnA\ Signature: sig-b22=:W2kxR52X0tXN9u7yjyPeWa0T3D0SVG8KkPo+lOWyb2TGdLz\
a8uP/b9xUpg+VSPElbBs6JWBIQsd+nMdHDe+ls/IwVMwXktC37SqsnbNyhNp6kcvc\ ixWjUlbehjnNhzA+wFWnE6+hdKH8KR6Z9FvsxCc+44XrqxzT7Vcsror5SjMyfx6Nq\
WpevjzFcD2VqdZleUz4jN7P+W5A3wHiMGfIjIWn36KXNB+RKyrlGnIS8yaBBrom5r\ tELklj1u2L4JovANI80BSoVobSoc+v9NRVWJZU7WAVow8H2CucCcv2cy1tKFCTMyc\
cZWLrLbtg6VlrH1+/07RV+kgTh/l10h8qgpl9zQHu7mWbDKTq0tJ8K4ywcPoC4s2I\ m9LQrIz63Tg5tcGWj64b12nmwj9TwwkCygfz0MTyIytjYLVzKw7mXpL4jGFZ5lsw2\
4rU88jzDKDGdTTQFZoTVZxZmuTM1FvHfzIw==: VT2eB3qpF2d/Psy0p1heKhrkz9uvKeCoj+P5QjLMS4eirHDqpKqe9YmCaMsJAUYSU\
M86qC8qO6vMQhTMegTkEe25DquVcTiOAEAw==:
Note that the RSA PSS algorithm in use here is non-deterministic, Note that the RSA PSS algorithm in use here is non-deterministic,
meaning a different signature value will be created every time the meaning a different signature value will be created every time the
algorithm is run. The signature value provided here can be validated algorithm is run. The signature value provided here can be validated
against the given keys, but newly-generated signature values are not against the given keys, but newly-generated signature values are not
expected to match the example. See Section 7.19. expected to match the example. See Section 7.19.
B.2.3. Full Coverage using rsa-pss-sha512 B.2.3. Full Coverage using rsa-pss-sha512
This example covers all applicable message components in "test- This example covers all applicable message components in "test-
skipping to change at page 83, line 19 skipping to change at page 86, line 11
Michael Richardson, Wojciech Rygielski, Rich Salz, Adam Scarr, Cory Michael Richardson, Wojciech Rygielski, Rich Salz, Adam Scarr, Cory
J. Slep, Dirk Stein, Henry Story, Lukasz Szewc, Chris Webber, and J. Slep, Dirk Stein, Henry Story, Lukasz Szewc, Chris Webber, and
Jeffrey Yasskin. Jeffrey Yasskin.
Document History Document History
_RFC EDITOR: please remove this section before publication_ _RFC EDITOR: please remove this section before publication_
o draft-ietf-httpbis-message-signatures o draft-ietf-httpbis-message-signatures
* -11
+ Added ABNF references, coalesced ABNF rules.
+ Editorial and formatting fixes.
+ Update examples.
* -10 * -10
+ Removed "related response" and "@request-response" in favor + Removed "related response" and "@request-response" in favor
of generic "req" parameter. of generic "req" parameter.
+ Editorial fixes to comply with HTTP extension style + Editorial fixes to comply with HTTP extension style
guidelines. guidelines.
+ Add security consideration on message content. + Add security consideration on message content.
 End of changes. 96 change blocks. 
288 lines changed or deleted 429 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/