summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc7797.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc7797.txt')
-rw-r--r--doc/rfc/rfc7797.txt619
1 files changed, 619 insertions, 0 deletions
diff --git a/doc/rfc/rfc7797.txt b/doc/rfc/rfc7797.txt
new file mode 100644
index 0000000..f173e75
--- /dev/null
+++ b/doc/rfc/rfc7797.txt
@@ -0,0 +1,619 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) M. Jones
+Request for Comments: 7797 Microsoft
+Updates: 7519 February 2016
+Category: Standards Track
+ISSN: 2070-1721
+
+
+ JSON Web Signature (JWS) Unencoded Payload Option
+
+Abstract
+
+ JSON Web Signature (JWS) represents the payload of a JWS as a
+ base64url-encoded value and uses this value in the JWS Signature
+ computation. While this enables arbitrary payloads to be integrity
+ protected, some have described use cases in which the base64url
+ encoding is unnecessary and/or an impediment to adoption, especially
+ when the payload is large and/or detached. This specification
+ defines a means of accommodating these use cases by defining an
+ option to change the JWS Signing Input computation to not base64url-
+ encode the payload. This option is intended to broaden the set of
+ use cases for which the use of JWS is a good fit.
+
+ This specification updates RFC 7519 by stating that JSON Web Tokens
+ (JWTs) MUST NOT use the unencoded payload option defined by this
+ specification.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc7797.
+
+
+
+
+
+
+
+
+
+
+
+
+Jones Standards Track [Page 1]
+
+RFC 7797 JWS Unencoded Payload Option February 2016
+
+
+Copyright Notice
+
+ Copyright (c) 2016 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (http://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Simplified BSD License text as described in Section 4.e of
+ the Trust Legal Provisions and are provided without warranty as
+ described in the Simplified BSD License.
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
+ 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
+ 3. The "b64" Header Parameter . . . . . . . . . . . . . . . . . 4
+ 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 5
+ 4.1. Example with Header Parameters {"alg":"HS256"} . . . . . 6
+ 4.2. Example with Header Parameters
+ {"alg":"HS256","b64":false,"crit":["b64"]} . . . . . . . 7
+ 5. Unencoded Payload Content Restrictions . . . . . . . . . . . 7
+ 5.1. Unencoded Detached Payload . . . . . . . . . . . . . . . 8
+ 5.2. Unencoded JWS Compact Serialization Payload . . . . . . . 8
+ 5.3. Unencoded JWS JSON Serialization Payload . . . . . . . . 8
+ 6. Using "crit" with "b64" . . . . . . . . . . . . . . . . . . . 9
+ 7. Intended Use by Applications . . . . . . . . . . . . . . . . 9
+ 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9
+ 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
+ 9.1. JSON Web Signature and Encryption Header Parameter
+ Registration . . . . . . . . . . . . . . . . . . . . . . 10
+ 9.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 10
+ 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
+ 10.1. Normative References . . . . . . . . . . . . . . . . . . 10
+ 10.2. Informative References . . . . . . . . . . . . . . . . . 11
+ Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 11
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11
+
+
+
+
+
+
+
+
+
+
+Jones Standards Track [Page 2]
+
+RFC 7797 JWS Unencoded Payload Option February 2016
+
+
+1. Introduction
+
+ The "JSON Web Signature (JWS)" [JWS] specification defines the JWS
+ Signing Input as the input to the digital signature or Message
+ Authentication Code (MAC) computation, with the value
+ ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS
+ Payload)). While this works well in practice for many use cases,
+ including those accommodating arbitrary payload values, other use
+ cases have been described in which base64url-encoding the payload is
+ unnecessary and/or an impediment to adoption, particularly when the
+ payload is large and/or detached.
+
+ This specification introduces a new JWS Header Parameter value that
+ generalizes the JWS Signing Input computation in a manner that makes
+ base64url-encoding the payload selectable and optional. The primary
+ set of use cases where this enhancement may be helpful are those in
+ which the payload may be very large and where means are already in
+ place to enable the payload to be communicated between the parties
+ without modifications. Appendix F of [JWS] describes how to
+ represent JWSs with detached content, which would typically be used
+ for these use cases.
+
+ The advantages of not having to base64url-encode a large payload are
+ that allocation of the additional storage to hold the base64url-
+ encoded form is avoided and the base64url-encoding computation never
+ has to be performed. In summary, this option can help avoid
+ unnecessary copying and transformations of the potentially large
+ payload, resulting in sometimes significant space and time
+ improvements for deployments.
+
+1.1. Notational Conventions
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+ "OPTIONAL" in this document are to be interpreted as described in
+ "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119].
+ The interpretation should only be applied when the terms appear in
+ all capital letters.
+
+ BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per
+ Section 2 of [JWS].
+
+ UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation
+ of STRING, where STRING is a sequence of zero or more Unicode
+ [UNICODE] characters.
+
+
+
+
+
+
+Jones Standards Track [Page 3]
+
+RFC 7797 JWS Unencoded Payload Option February 2016
+
+
+ ASCII(STRING) denotes the octets of the ASCII [RFC20] representation
+ of STRING, where STRING is a sequence of zero or more ASCII
+ characters.
+
+ The concatenation of two values A and B is denoted as A || B.
+
+2. Terminology
+
+ This specification uses the same terminology as the "JSON Web
+ Signature" [JWS] and "JSON Web Algorithms" [JWA] specifications.
+
+3. The "b64" Header Parameter
+
+ This Header Parameter modifies the JWS Payload representation and the
+ JWS Signing Input computation in the following way:
+
+ b64
+ The "b64" (base64url-encode payload) Header Parameter determines
+ whether the payload is represented in the JWS and the JWS Signing
+ Input as ASCII(BASE64URL(JWS Payload)) or as the JWS Payload value
+ itself with no encoding performed. When the "b64" value is
+ "false", the payload is represented simply as the JWS Payload
+ value; otherwise, it is represented as ASCII(BASE64URL(JWS
+ Payload)). The "b64" value is a JSON boolean, with a default
+ value of "true". When used, this Header Parameter MUST be
+ integrity protected; therefore, it MUST occur only within the JWS
+ Protected Header. Use of this Header Parameter is OPTIONAL. If
+ the JWS has multiple signatures and/or MACs, the "b64" Header
+ Parameter value MUST be the same for all of them. Note that
+ unless the payload is detached, many payload values would cause
+ errors parsing the resulting JWSs, as described in Section 5.
+
+ The following table shows the JWS Signing Input computation,
+ depending upon the value of this parameter:
+
+ +-------+-----------------------------------------------------------+
+ | "b64" | JWS Signing Input Formula |
+ +-------+-----------------------------------------------------------+
+ | true | ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || |
+ | | BASE64URL(JWS Payload)) |
+ | | |
+ | false | ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.') || |
+ | | JWS Payload |
+ +-------+-----------------------------------------------------------+
+
+
+
+
+
+
+
+Jones Standards Track [Page 4]
+
+RFC 7797 JWS Unencoded Payload Option February 2016
+
+
+4. Examples
+
+ This section gives examples of JWSs showing the difference that using
+ the "b64" Header Parameter makes. The examples all use the JWS
+ Payload value [36, 46, 48, 50]. This octet sequence represents the
+ ASCII characters "$.02"; its base64url-encoded representation is
+ "JC4wMg".
+
+ The following table shows a set of Header Parameter values without
+ using a false "b64" Header Parameter value and a set using it, with
+ the resulting JWS Signing Input values represented as ASCII
+ characters:
+
+ +-----------------------------+-------------------------------------+
+ | JWS Protected Header | JWS Signing Input Value |
+ +-----------------------------+-------------------------------------+
+ | {"alg":"HS256"} | eyJhbGciOiJIUzI1NiJ9.JC4wMg |
+ | | |
+ | {"alg":"HS256","b64":false, | eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2U |
+ | "crit":["b64"]} | sImNyaXQiOlsiYjY0Il19.$.02 |
+ +-----------------------------+-------------------------------------+
+
+ These examples use the Hash-based Message Authentication Code (HMAC)
+ key from Appendix A.1 of [JWS], which is represented below as a JSON
+ Web Key [JWK] (with line breaks within values for display purposes
+ only):
+
+ {
+ "kty":"oct",
+ "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75
+ aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow"
+ }
+
+ The rest of this section shows complete representations for the two
+ JWSs above.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Jones Standards Track [Page 5]
+
+RFC 7797 JWS Unencoded Payload Option February 2016
+
+
+4.1. Example with Header Parameters {"alg":"HS256"}
+
+ The complete JWS representation for this example using the JWS
+ Compact Serialization and a non-detached payload (with line breaks
+ for display purposes only) is:
+
+ eyJhbGciOiJIUzI1NiJ9
+ .
+ JC4wMg
+ .
+ 5mvfOroL-g7HyqJoozehmsaqmvTYGEq5jTI1gVvoEoQ
+
+ Note that this JWS uses only features defined by [JWS] and does not
+ use the new "b64" Header Parameter. It is the "control" so that
+ differences when it is used can be easily seen.
+
+ The equivalent representation for this example using the flattened
+ JWS JSON Serialization is:
+
+ {
+ "protected":
+ "eyJhbGciOiJIUzI1NiJ9",
+ "payload":
+ "JC4wMg",
+ "signature":
+ "5mvfOroL-g7HyqJoozehmsaqmvTYGEq5jTI1gVvoEoQ"
+ }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Jones Standards Track [Page 6]
+
+RFC 7797 JWS Unencoded Payload Option February 2016
+
+
+4.2. Example with Header Parameters
+ {"alg":"HS256","b64":false,"crit":["b64"]}
+
+ The complete JWS representation for this example using the JWS
+ Compact Serialization and a detached payload (with line breaks for
+ display purposes only) is:
+
+ eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19
+ .
+ .
+ A5dxf2s96_n5FLueVuW1Z_vh161FwXZC4YLPff6dmDY
+
+ Note that the payload "$.02" cannot be represented in this JWS in its
+ unencoded form because it contains a period ('.') character, which
+ would cause parsing problems. This JWS is therefore shown with a
+ detached payload.
+
+ The complete JWS representation for this example using the flattened
+ JWS JSON Serialization and a non-detached payload is:
+
+ {
+ "protected":
+ "eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19",
+ "payload":
+ "$.02",
+ "signature":
+ "A5dxf2s96_n5FLueVuW1Z_vh161FwXZC4YLPff6dmDY"
+ }
+
+ If using a detached payload with the JWS JSON Serialization, the
+ "payload" element would be omitted.
+
+5. Unencoded Payload Content Restrictions
+
+ When the "b64" value is "false", different restrictions on the
+ payload contents apply, depending upon the circumstances, as
+ described in this section. The restrictions prevent the use of
+ payload values that would cause errors parsing the resulting JWSs.
+
+ Note that because the character sets that can be used for unencoded
+ non-detached payloads differ between the two serializations, some
+ JWSs using a "b64" value of "false" cannot be syntactically converted
+ between the JWS JSON Serialization and the JWS Compact Serialization.
+ See Section 8 for security considerations on using unencoded
+ payloads.
+
+
+
+
+
+
+Jones Standards Track [Page 7]
+
+RFC 7797 JWS Unencoded Payload Option February 2016
+
+
+5.1. Unencoded Detached Payload
+
+ Appendix F of [JWS] describes how to represent JWSs with detached
+ content. A detached payload can contain any octet sequence
+ representable by the application. The payload value will not cause
+ problems parsing the JWS, since it is not represented as part of the
+ JWS. If an application uses a content encoding when representing the
+ payload, then it MUST specify whether the signature or MAC is
+ performed over the content-encoded representation or over the
+ unencoded content.
+
+5.2. Unencoded JWS Compact Serialization Payload
+
+ When using the JWS Compact Serialization, unencoded non-detached
+ payloads using period ('.') characters would cause parsing errors;
+ such payloads MUST NOT be used with the JWS Compact Serialization.
+ Similarly, if a JWS using the JWS Compact Serialization and a
+ non-detached payload is to be transmitted in a context that requires
+ URL-safe characters, then the application MUST ensure that the
+ payload contains only the URL-safe characters 'a'-'z', 'A'-'Z',
+ '0'-'9', dash ('-'), underscore ('_'), and tilde ('~'). The payload
+ value is the ASCII representation of the characters in the payload
+ string. The ASCII space character and all printable ASCII characters
+ other than period ('.') (those characters in the ranges %x20-2D and
+ %x2F-7E) MAY be included in a non-detached payload using the JWS
+ Compact Serialization, provided that the application can transmit the
+ resulting JWS without modification.
+
+ No meaning or special semantics are attached to any characters in the
+ payload. For instance, the percent ('%') character represents itself
+ and is not used by JWS objects for percent-encoding [RFC3986].
+ Applications, of course, are free to utilize content-encoding rules
+ of their choosing, provided that the encoded representations utilize
+ only allowed payload characters.
+
+5.3. Unencoded JWS JSON Serialization Payload
+
+ When using the JWS JSON Serialization, unencoded non-detached
+ payloads must consist of the octets of the UTF-8 encoding of a
+ sequence of Unicode code points that are representable in a JSON
+ string. The payload value is determined after performing any JSON
+ string escape processing, per Section 8.3 of RFC 7159 [RFC7159], and
+ then UTF-8-encoding the resulting Unicode code points. This means,
+ for instance, that these payloads represented as JSON strings are
+ equivalent ("$.02", "\u0024.02"). Unassigned Unicode code point
+ values MUST NOT be used to represent the payload.
+
+
+
+
+
+Jones Standards Track [Page 8]
+
+RFC 7797 JWS Unencoded Payload Option February 2016
+
+
+6. Using "crit" with "b64"
+
+ The "crit" Header Parameter MUST be included with "b64" in its set of
+ values when using the "b64" Header Parameter to cause implementations
+ not implementing "b64" to reject the JWS (instead of it being
+ misinterpreted).
+
+7. Intended Use by Applications
+
+ Application profiles should specify whether "b64" with a "false"
+ value is to be used by the application in each application context or
+ not, with it then being consistently applied in each application
+ context. For instance, an application that uses detached payloads
+ might specify that "b64" with a "false" value always be used. It is
+ NOT RECOMMENDED that this parameter value be dynamically varied with
+ different payloads in the same application context.
+
+ While it is legal to use "b64" with a "true" value, it is RECOMMENDED
+ that "b64" simply be omitted in this case, since it would be
+ selecting the behavior already specified in [JWS].
+
+ For interoperability reasons, JSON Web Tokens [JWT] MUST NOT use
+ "b64" with a "false" value.
+
+8. Security Considerations
+
+ [JWS] base64url-encodes the JWS Payload to restrict the set of
+ characters used to represent it so that the representation does not
+ contain characters used for delimiters in JWS representations. Those
+ delimiters are the period ('.') character for the JWS Compact
+ Serialization and the double-quote ('"') character for the JWS JSON
+ Serialization. When the "b64" (base64url-encode payload) value is
+ "false", these properties are lost. It then becomes the
+ responsibility of the application to ensure that payloads only
+ contain characters that will not cause parsing problems for the
+ serialization used, as described in Section 5. The application also
+ incurs the responsibility to ensure that the payload will not be
+ modified during transmission.
+
+ Note that if a JWS were to be created with a "b64" value of "false"
+ without including the "crit" Header Parameter with "b64" in its set
+ of values and it were to be received by an implementation not
+ supporting the "b64" Header Parameter, then the signature or MAC
+ would still verify but the recipient would believe that the intended
+ JWS Payload value is the base64url decoding of the payload value
+ received, rather than the payload value received itself. For
+ example, if the payload value received were "NDA1", an implementation
+ not supporting this extension would interpret the intended payload as
+
+
+
+Jones Standards Track [Page 9]
+
+RFC 7797 JWS Unencoded Payload Option February 2016
+
+
+ being the base64url decoding of this value, which is "405".
+ Requiring the use of the "crit" Header Parameter with "b64" in the
+ set of values prevents this misinterpretation.
+
+9. IANA Considerations
+
+9.1. JSON Web Signature and Encryption Header Parameter Registration
+
+ This specification registers the "b64" Header Parameter defined in
+ Section 3 in the IANA "JSON Web Signature and Encryption Header
+ Parameters" registry [IANA.JOSE] established by [JWS].
+
+9.1.1. Registry Contents
+
+ o Header Parameter Name: "b64"
+ o Header Parameter Description: Base64url-Encode Payload
+ o Header Parameter Usage Location(s): JWS
+ o Change Controller: IESG
+ o Specification Document(s): Section 3 of RFC 7797
+
+10. References
+
+10.1. Normative References
+
+ [IANA.JOSE]
+ IANA, "JSON Object Signing and Encryption (JOSE)",
+ <http://www.iana.org/assignments/jose>.
+
+ [JWA] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,
+ DOI 10.17487/RFC7518, May 2015,
+ <http://www.rfc-editor.org/info/rfc7518>.
+
+ [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
+ Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
+ 2015, <http://www.rfc-editor.org/info/rfc7515>.
+
+ [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
+ (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
+ <http://www.rfc-editor.org/info/rfc7519>.
+
+ [RFC20] Cerf, V., "ASCII format for Network Interchange", STD 80,
+ RFC 20, October 1969,
+ <http://www.rfc-editor.org/info/rfc20>.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119,
+ DOI 10.17487/RFC2119, March 1997,
+ <http://www.rfc-editor.org/info/rfc2119>.
+
+
+
+Jones Standards Track [Page 10]
+
+RFC 7797 JWS Unencoded Payload Option February 2016
+
+
+ [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
+ 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
+ 2003, <http://www.rfc-editor.org/info/rfc3629>.
+
+ [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
+ Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
+ 2014, <http://www.rfc-editor.org/info/rfc7159>.
+
+ [UNICODE] The Unicode Consortium, "The Unicode Standard",
+ <http://www.unicode.org/versions/latest/>.
+
+10.2. Informative References
+
+ [JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517,
+ DOI 10.17487/RFC7517, May 2015,
+ <http://www.rfc-editor.org/info/rfc7517>.
+
+ [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
+ Resource Identifier (URI): Generic Syntax", STD 66,
+ RFC 3986, DOI 10.17487/RFC3986, January 2005,
+ <http://www.rfc-editor.org/info/rfc3986>.
+
+Acknowledgements
+
+ Anders Rundgren, Richard Barnes, Phillip Hallam-Baker, Jim Schaad,
+ Matt Miller, Martin Thomson, and others have all made the case for
+ being able to use a representation of the payload that is not
+ base64url encoded in contexts in which it safe to do so.
+
+ Thanks to Sergey Beryozkin, Stephen Farrell, Benjamin Kaduk, James
+ Manger, Kathleen Moriarty, Axel Nennker, Anders Rundgren, Nat
+ Sakimura, Jim Schaad, Robert Sparks, and Matias Woloski for their
+ reviews of the specification, and thanks to Vladimir Dzhuvinov for
+ verifying the examples.
+
+Author's Address
+
+ Michael B. Jones
+ Microsoft
+
+ Email: mbj@microsoft.com
+ URI: http://self-issued.info/
+
+
+
+
+
+
+
+
+
+Jones Standards Track [Page 11]
+