JSON Web Signature (JWS)
Extracted elements (28)
Base64url encoding is used without padding ('=' characters omitted) to produce representations that are valid in URIs and HTTP headers without percent-encoding, while still allowing unambiguous decoding since the payload length is determinable from context.
Header Parameter names are intentionally kept short (RECOMMENDED not to exceed 8 characters) because a core goal is compact serialized representations. Names are registered in IANA to prevent collisions while preserving brevity.
Two serializations are defined with different trade-offs: the JWS Compact Serialization is compact and URL-safe for space-constrained environments (e.g., HTTP Authorization headers, URI query parameters), while the JWS JSON Serialization enables multiple signatures over the same payload at the cost of compactness and URL-safety.
A 'typ' or 'cty' value not containing a '/' character MUST be treated by recipients as if 'application/' were prepended (e.g., 'JWT' means 'application/JWT'). This shorthand SHOULD be used by producers to keep messages compact, but only when the media type value itself contains no '/'.
JWS implementations only need to implement the serialization features required by the applications they support. Applications using JWS must specify which serializations and features (e.g., single vs. multiple signatures) are required, enabling constrained implementations.
All JSON string comparisons for Header Parameter names and algorithm names MUST use the equality rules from RFC 7159 Section 8.3 (verbatim comparison after escape processing), except for 'typ' and 'cty' values. Unicode escape sequences must be compared literally.
Any JSON inputs not conforming to the JSON-text syntax defined in RFC 7159 MUST be rejected in their entirety by JSON parsers. JWSs with trailing extra characters after a valid JSON object MUST be considered invalid.
Implementations supporting 'jku' and/or 'x5u' Header Parameters MUST support TLS. Confidentiality protection MUST be applied using TLS with a ciphersuite providing confidentiality and integrity. The TLS server identity MUST be verified per RFC 6125 Section 6.
JWS parsers MUST either reject JWSs with duplicate Header Parameter names or use a JSON parser that returns only the lexically last duplicate member name, as specified in ECMAScript 5.1 Section 15.12.
Producers MUST NOT include Header Parameter names defined by JWS/JWA, duplicate names, or names not present in the JOSE Header within the 'crit' list. Producers MUST NOT use the empty list '[]' as the 'crit' value.
The 'alg' Header Parameter MUST be present in the JOSE Header and MUST accurately represent the algorithm used to construct the JWS Signature. Implementations MUST ensure algorithm information encoded inside the signature (e.g., RSASSA-PKCS1-v1_5 hash OID) corresponds to the 'alg' value.
When multiple JWS Signature values are present, at least one MUST successfully validate or the JWS MUST be considered invalid. Which signatures must validate is an application decision.
The 'alg' (Algorithm) Header Parameter identifies the cryptographic algorithm used to secure the JWS. Its value is a case-sensitive ASCII StringOrURI. This Header Parameter MUST be present and MUST be understood and processed by implementations.
The 'crit' (Critical) Header Parameter is a JSON array listing Header Parameter names whose extensions MUST be understood and processed. If any listed extension is not understood, the JWS is invalid. The 'crit' parameter MUST occur only within the JWS Protected Header and MUST NOT contain an empty list.
The Flattened JWS JSON Serialization is a single-signature variant of the General JWS JSON Serialization that elevates 'protected', 'header', and 'signature' to the top-level JSON object alongside 'payload'. The 'signatures' member MUST NOT be present.
The General JWS JSON Serialization is a JSON object with a 'payload' member (BASE64URL(JWS Payload)) and a 'signatures' array. Each element of the array contains 'protected' (BASE64URL(UTF8(JWS Protected Header))), 'header' (JWS Unprotected Header), and 'signature' (BASE64URL(JWS Signature)) members. This format supports multiple signatures or MACs over the same payload.
The 'jku' (JWK Set URL) Header Parameter is a URI referencing a JWK Set containing the public key used to sign the JWS. The resource MUST be retrieved using TLS with server identity validation per RFC 6125.
The JWS Compact Serialization represents a JWS as BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload) || '.' || BASE64URL(JWS Signature). It is a compact, URL-safe string supporting exactly one signature or MAC and no JWS Unprotected Header.
The 'x5c' (X.509 Certificate Chain) Header Parameter contains a JSON array of base64-encoded (not base64url) DER PKIX certificate values. The first certificate MUST contain the signing public key. Recipients MUST validate the certificate chain according to RFC 5280.
The 'x5t#S256' Header Parameter is a base64url-encoded SHA-256 thumbprint of the DER-encoded X.509 certificate corresponding to the signing key. It is preferred over the SHA-1 'x5t' parameter for stronger collision resistance.
RFC 7515 establishes the IANA 'JSON Web Signature and Encryption Header Parameters' registry for Header Parameter names. Registration requires Specification Required review via [email protected]. Initial contents include: alg, jku, jwk, kid, x5u, x5c, x5t, x5t#S256, typ, cty, and crit.
RFC 7515 registers two IANA media types: 'application/jose' (for JWS/JWE using Compact Serialization) and 'application/jose+json' (for JWS/JWE using JSON Serialization), both in the 'Media Types' registry.
Algorithm substitution attacks allow an attacker to reuse an existing signature value with a different algorithm. Mitigations include: using only algorithms not vulnerable to substitution (all JWA-defined algorithms use SHA-2), requiring 'alg' in the JWS Protected Header, and including the algorithm in the application payload for independent verification.
Implementations must use constant-time comparison for cryptographic operations to prevent timing attacks, as differing execution times for successful vs. unsuccessful operations can leak key material.
MACs provide integrity but not non-repudiation: a MAC key must be shared among all verifying parties, so validation only proves the message originated from one of the key holders. Digital signatures (asymmetric keys) are required when third-party proof of origination is needed.
The 'x5t' SHA-1 thumbprint parameter is included for compatibility reasons only. An attacker with write access to a certificate store could create a colliding certificate; use of 'x5t#S256' (SHA-256) is preferred where possible.
Base64url encoding uses the URL- and filename-safe character set from RFC 4648 Section 5, with all trailing '=' padding characters omitted and no line breaks or whitespace. The base64url encoding of the empty octet sequence is the empty string.
JWS Signing Input is defined as ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload)). This is the exact octet sequence over which the digital signature or MAC is computed.