JSON Web Signature (JWS) Unencoded Payload Option
updates
- rfc-7519 — JSON Web Token (JWT)
Extracted elements (19)
The "b64" option was introduced because base64url-encoding large payloads is unnecessary overhead when the payload is already being transmitted intact between parties. Avoiding encoding eliminates additional storage allocation for the encoded form and the encoding computation itself, yielding significant space and time improvements for large-payload deployments.
The primary intended use case for "b64":false is large or detached payloads, as described in JWS Appendix F. The option is deliberately optional and application-profile-driven rather than a global default, to preserve backward compatibility and avoid inadvertent misuse.
An unencoded JWS JSON Serialization payload must consist of the octets of the UTF-8 encoding of Unicode code points representable in a JSON string, after performing JSON string escape processing per RFC 7159 Section 8.3. For example, the JSON strings "$.02" and "\u0024.02" represent equivalent payloads.
Because the character sets allowed for unencoded non-detached payloads differ between the JWS Compact Serialization and JWS JSON Serialization, some JWSs using "b64":false cannot be syntactically converted between the two serialization forms.
For interoperability reasons, JSON Web Tokens (JWTs) MUST NOT use "b64" with a "false" value. This updates RFC 7519.
For unencoded JWS JSON Serialization payloads, unassigned Unicode code point values MUST NOT be used to represent the payload.
If a JWS has multiple signatures and/or MACs, the "b64" Header Parameter value MUST be the same for all of them.
If an application uses a content encoding when representing a detached payload, it MUST specify whether the signature or MAC is performed over the content-encoded or the unencoded content.
It is NOT RECOMMENDED that the "b64" parameter value be dynamically varied with different payloads in the same application context; application profiles should specify consistently whether "b64" false is used.
It is RECOMMENDED that "b64" simply be omitted when its value would be "true", since omitting it selects the default behavior already specified in RFC 7515.
The "b64" Header Parameter MUST occur only within the JWS Protected Header, because it must be integrity protected.
The "crit" Header Parameter MUST be included with "b64" in its set of values when the "b64" Header Parameter is used, so that implementations not supporting "b64" will reject the JWS rather than misinterpret it.
Unencoded non-detached payloads containing a period ('.') character MUST NOT be used with the JWS Compact Serialization, as the period is the field delimiter and would cause parsing errors.
When transmitting a JWS Compact Serialization with a non-detached unencoded payload in a context that requires URL-safe characters, the application MUST ensure the payload contains only URL-safe characters ('a'-'z', 'A'-'Z', '0'-'9', '-', '_', '~').
The "b64" (base64url-encode payload) JWS Header Parameter controls whether the payload is represented as ASCII(BASE64URL(JWS Payload)) or as the raw JWS Payload value. It is a JSON boolean with a default of "true" and MUST occur only within the JWS Protected Header.
This specification registers the "b64" Header Parameter in the IANA "JSON Web Signature and Encryption Header Parameters" registry. Header Parameter Name: "b64"; Description: Base64url-Encode Payload; Usage Location: JWS; Change Controller: IESG; Specification: RFC 7797 Section 3.
If a JWS is created with "b64":false but without including "crit":["b64"], an implementation not supporting "b64" will still verify the signature but will misinterpret the payload as the base64url decoding of the received value (e.g., interpreting "NDA1" as "405" instead of the literal string). Requiring "crit" prevents this silent misinterpretation.
When "b64" is false, the base64url encoding that normally restricts payload characters to avoid JWS delimiters ('.' in Compact Serialization, '"' in JSON Serialization) is no longer applied. It becomes the application's responsibility to ensure payloads contain only safe characters and that the payload will not be modified during transmission.
When "b64" is true, the JWS Signing Input is ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload)). When "b64" is false, the signing input is ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.') || JWS Payload, i.e., the raw payload bytes are appended after the period delimiter without encoding.