RFC 7797
JSON Web Signature (JWS) Unencoded Payload Option
RFC 7797: JSON Web Signature (JWS) Unencoded Payload Option 🎀
Okay so bestie, this is RFC 7797, titled JSON Web Signature (JWS) Unencoded Payload Option. It's a Standards Track doc from the IETF, dated February 2016, and it's written by M. Jones from Microsoft 💖. It's Standards Track, ISSN 2070-1721. It updates RFC 7519 (JWT) and doesn't obsolete anything. Let's go 💅
Abstract ✨
So JSON Web Signature (JWS) takes the payload and base64url-encodes it before using that value in the signature computation. That means you can protect any payload, which is iconic, but some people have pointed out that the base64url encoding is pointless and kind of a blocker for adoption, especially when the payload is big and/or detached 😭. This spec adds an option that changes the JWS Signing Input computation so the payload is not base64url-encoded. The goal is to make JWS a good fit for way more use cases 🦋.
It also updates RFC 7519 by saying that JSON Web Tokens (JWTs) MUST NOT use this unencoded payload option. Hard no for JWTs, periodt 🙅♀️.
Status of This Memo
This is an Internet Standards Track document 🌸.
It's a product of the Internet Engineering Task Force (IETF), so it represents the consensus of the IETF community. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). If you want more info on Internet Standards, check Section 2 of RFC 5741 📚.
For the current status, any errata, and how to give feedback, go to http://www.rfc-editor.org/info/rfc7797 ✨.
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) as they were in effect on the publication date. Please read these carefully, because they spell out your rights and restrictions for this document 🧾. Code Components pulled out of this document must include the Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come 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 . . . . . . . . . . . . . . . . . . . . . . . . 111. Introduction 🧚
The "JSON Web Signature (JWS)" [JWS] spec defines the JWS Signing Input as the input to the digital signature or Message Authentication Code (MAC) computation. The value is ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload)). This works really well for a lot of cases, including ones with arbitrary payload values. But other folks have found that base64url-encoding the payload is unnecessary and/or a blocker for adoption, especially when the payload is large and/or detached 😩.
So this spec introduces a new JWS Header Parameter value that generalizes the JWS Signing Input computation. It makes base64url-encoding the payload selectable and optional 🦋. The biggest wins show up when the payload is super large and there's already a way to get it to the other parties without changes. Appendix F of [JWS] explains how to represent JWSs with detached content, which is usually what you'd use for those cases 💅.
Not having to base64url-encode a big payload is a whole vibe, because you skip allocating extra storage for the encoded form and you never run the base64url-encoding computation at all. Basically this option helps you avoid unnecessary copying and transforming of a potentially huge payload, which can mean real 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) is the base64url encoding of OCTETS, per Section 2 of [JWS] 🫶.
UTF8(STRING) is the octets of the UTF-8 [RFC3629] representation of STRING, where STRING is a sequence of zero or more Unicode [UNICODE] characters 🌈.
ASCII(STRING) is 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 written as A || B 💜.
2. Terminology 📖
This spec uses the same terminology as the "JSON Web Signature" [JWS] and "JSON Web Algorithms" [JWA] specs. No new vocab, we're good 🍓.
3. The "b64" Header Parameter 💖
This Header Parameter changes the JWS Payload representation and the JWS Signing Input computation in the following way:
- b64: The "b64" (base64url-encode payload) Header Parameter decides 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 done. When the "b64" value isfalse, the payload is represented simply as the JWS Payload value. Otherwise it's represented asASCII(BASE64URL(JWS Payload)). The "b64" value is a JSON boolean, with a default value oftrue. When it's used, this Header Parameter MUST be integrity protected, so it MUST occur only within the JWS Protected Header. Using 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. Also, unless the payload is detached, a lot of payload values would cause errors when parsing the resulting JWSs, as described in Section 5 😬.
Here's the JWS Signing Input computation depending on 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 |
+-------+-----------------------------------------------------------+4. Examples 🎀
This section shows examples of JWSs so you can see the difference the "b64" Header Parameter makes 👀. All the examples use the JWS Payload value [36, 46, 48, 50]. That octet sequence is the ASCII characters "$.02", and its base64url-encoded form is "JC4wMg" 🍭.
This table shows a set of Header Parameter values without a false "b64" value, and then a set that uses it. The resulting JWS Signing Input values are shown 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]. It's shown below as a JSON Web Key [JWK] (line breaks inside values are just for display 🔑):
{
"kty":"oct",
"k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75
aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow"
}The rest of this section has the complete representations for the two JWSs above ✨.
4.1. Example with Header Parameters {"alg":"HS256"}
Here's the complete JWS representation for this example. It uses the JWS Compact Serialization and a non-detached payload (line breaks are just for display 🌸):
eyJhbGciOiJIUzI1NiJ9
.
JC4wMg
.
5mvfOroL-g7HyqJoozehmsaqmvTYGEq5jTI1gVvoEoQThis JWS only uses features defined by [JWS] and doesn't use the new "b64" Header Parameter. It's the "control" example, so you can easily see the differences when "b64" gets used 🧪.
The equivalent representation for this example, using the flattened JWS JSON Serialization, is:
{
"protected":
"eyJhbGciOiJIUzI1NiJ9",
"payload":
"JC4wMg",
"signature":
"5mvfOroL-g7HyqJoozehmsaqmvTYGEq5jTI1gVvoEoQ"
}4.2. Example with Header Parameters ✨
okay bestie, this example stacks two header parameters at once 🎀 The JOSE header is:
{"alg":"HS256","b64":false,"crit":["b64"]}the complete JWS representation using the JWS Compact Serialization and a detached payload is (line breaks are just for display 💅):
eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19
.
.
A5dxf2s96_n5FLueVuW1Z_vh161FwXZC4YLPff6dmDYngl the payload $.02 can't go in this JWS unencoded, because it has a period (.) in it, and that would cause parsing problems 💀 So this one gets shown as a detached payload 🦋
the complete JWS representation for the flattened JWS JSON Serialization with a non-detached payload looks like this 🌸
{
"protected":
"eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19",
"payload":
"$.02",
"signature":
"A5dxf2s96_n5FLueVuW1Z_vh161FwXZC4YLPff6dmDY"
}and if you're using a detached payload with the JWS JSON Serialization, the "payload" element just gets omitted 🙈
5. Unencoded Payload Content Restrictions
okay so when "b64" is "false", different restrictions on the payload contents apply depending on the situation 🔥 these restrictions exist to stop payload values from causing errors when you go to parse the resulting JWSs 💖
heads up though: the character sets allowed for unencoded non-detached payloads are different between the two serializations. So some JWSs using a "b64" value of "false" can't be syntactically converted between the JWS JSON Serialization and the JWS Compact Serialization 😭 And see Section 8 for the security considerations on using unencoded payloads. Don't skip that one, it's serious 👑
5.1. Unencoded Detached Payload
Appendix F of [JWS] explains how to represent JWSs with detached content 🧚 A detached payload can hold any octet sequence the application can represent. The payload value won't cause parsing problems for the JWS, because it isn't part of the JWS representation at all ✨ If an application uses a content encoding when it represents the payload, then it MUST specify whether the signature or MAC is performed over the content-encoded representation or over the unencoded content. That part is non-negotiable, bestie 💅
5.2. Unencoded JWS Compact Serialization Payload
when you're using the JWS Compact Serialization, unencoded non-detached payloads with period (.) characters would cause parsing errors 💀 So those payloads MUST NOT be used with the JWS Compact Serialization. Also, if a JWS using the JWS Compact Serialization with a non-detached payload needs to travel in a context that requires URL-safe characters, then the application MUST ensure 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 ('.') (the ones in the ranges %x20-2D and %x2F-7E) MAY be included in a non-detached payload using the JWS Compact Serialization, as long as 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 just represents itself, and JWS objects don't use it for percent-encoding [RFC3986]. Applications are totally free to use whatever content-encoding rules they like, as long as the encoded representations only use allowed payload characters 💜
5.3. Unencoded JWS JSON Serialization Payload
when you're 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 can be represented in a JSON string 🍓 The payload value is figured out after doing any JSON string escape processing, per Section 8.3 of RFC 7159 [RFC7159], and then UTF-8-encoding the resulting Unicode code points. So for example, these payloads written as JSON strings are equivalent: ("$.02", "\u0024.02") 🌸 Unassigned Unicode code point values MUST NOT be used to represent the payload 🚫
6. Using "crit" with "b64"
the "crit" Header Parameter MUST be included with "b64" in its set of values when you're using the "b64" Header Parameter. That way, implementations that don't implement "b64" will reject the JWS (instead of misinterpreting it) 👑
7. Intended Use by Applications
application profiles should say whether "b64" with a "false" value is used by the application in each application context or not. Once that's decided, it gets applied consistently 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 🙅♀️
it's legal to use "b64" with a "true" value, but it is RECOMMENDED that "b64" simply be omitted in that case, since it would just 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
okay this section is dramatic and I love it, but it's also really important 😭
[JWS] base64url-encodes the JWS Payload to restrict the set of characters used to represent it, so the representation doesn't contain characters used as 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. Then it becomes the responsibility of the application to make sure payloads only contain characters that won't cause parsing problems for the serialization being used, as described in Section 5. The application also takes on the responsibility of making sure the payload won't be modified during transmission 🚨
⚠️ Note that if a JWS were created with a"b64"value of"false"without including the"crit"Header Parameter with"b64"in its set of values, and it were received by an implementation that doesn't support the"b64"Header Parameter, then the signature or MAC would still verify. But the recipient would believe 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 read the intended payload as the base64url decoding of that 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], which was established by [JWS] 🌸
9.1.1. Registry Contents
the registry entry looks like this 📋
Header Parameter Name: "b64"
Header Parameter Description: Base64url-Encode Payload
Header Parameter Usage Location(s): JWS
Change Controller: IESG
Specification Document(s): Section 3 of RFC 779710. References
10.1. Normative References
these are the references that are required reading, no skipping 📚
[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>.
[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
these ones are just helpful background reading 🧚
[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/
the end, bestie, we made it through the whole RFC 🌈✨💖
📦 where this page comes from
- ietf: rfc7797 2016-02
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms