Skip to main content

4. JOSE Header

For a JWE, the members of the JSON object representing the JOSE Header describe the encryption applied to the Plaintext and optionally additional properties of the JWE. The Header Parameter names within the JOSE Header MUST be unique, as specified in Section 4 of [JWS]. The rules about handling Header Parameters that are not understood by the implementation are also the same. The classes of Header Parameter names are likewise the same.

4.1 Registered Header Parameter Names​

The following Header Parameter names for use in JWEs are registered in the IANA "JSON Web Signature and Encryption Header Parameters" registry established by [JWS], with meanings as defined below.

As indicated by the common registry, JWS and JWE share a common Header Parameter space; when a parameter is used by both specifications, its usage must be compatible between the specifications.

4.1.1 "alg" (Algorithm) Header Parameter​

The meaning, syntax, and processing rules for the "alg" Header Parameter are the same as defined in Section 4.1.1 of [JWS], except that the Header Parameter identifies the cryptographic algorithm used to encrypt or determine the value of the CEK. If the "alg" value does not represent a supported algorithm, or if there is not a key for use with that algorithm available to the recipient, then the encrypted content cannot be decrypted.

A list of defined "alg" values for this use can be found in the IANA "JSON Web Signature and Encryption Algorithms" registry established by [JWA]; the initial contents of this registry are the values defined in Section 4.1 of [JWA].

4.1.2 "enc" (Encryption Algorithm) Header Parameter​

The "enc" (encryption algorithm) Header Parameter identifies the content encryption algorithm used to perform authenticated encryption on the plaintext to produce the ciphertext and the Authentication Tag. This algorithm MUST be an AEAD algorithm with a specified key length. If the "enc" value does not represent a supported algorithm, then the encrypted content cannot be decrypted. The "enc" value should either be registered in the IANA "JSON Web Signature and Encryption Algorithms" registry established by [JWA] or be a value that contains a Collision-Resistant Name. The "enc" value is a case-sensitive ASCII string containing a StringOrURI value. This Header Parameter MUST be present and MUST be understood and processed by implementations.

A list of defined "enc" values for this use can be found in the IANA "JSON Web Signature and Encryption Algorithms" registry established by [JWA]; the initial contents of this registry are the values defined in Section 5.1 of [JWA].

4.1.3 "zip" (Compression Algorithm) Header Parameter​

The "zip" (compression algorithm) applied to the plaintext before encryption, if any. The "zip" value defined by this specification is:

  • "DEF" - Compression with the DEFLATE [RFC1951] algorithm

Other values MAY be used. Compression algorithm values can be registered in the IANA "JSON Web Encryption Compression Algorithms" registry established by [JWA]. The "zip" value is a case-sensitive string. If no "zip" parameter is present, no compression is applied to the plaintext before encryption. When used, this Header Parameter MUST be integrity protected; therefore, it MUST occur only within the JWE Protected Header. Use of this Header Parameter is OPTIONAL. This Header Parameter MUST be understood and processed by implementations.

4.1.4 "jku" (JWK Set URL) Header Parameter​

The meaning, syntax, and processing rules for the "jku" Header Parameter are the same as defined in Section 4.1.2 of [JWS], except that the JWK Set resource contains the public key to which the JWE was encrypted; this can be used to determine the private key needed to decrypt the JWE.

4.1.5 "jwk" (JSON Web Key) Header Parameter​

The meaning, syntax, and processing rules for the "jwk" Header Parameter are the same as defined in Section 4.1.3 of [JWS], except that the key is the public key to which the JWE was encrypted; this can be used to determine the private key needed to decrypt the JWE.

4.1.6 "kid" (Key ID) Header Parameter​

The meaning, syntax, and processing rules for the "kid" Header Parameter are the same as defined in Section 4.1.4 of [JWS], except that the key hint references the public key to which the JWE was encrypted; this can be used to determine the private key needed to decrypt the JWE. This parameter allows originators to explicitly signal a change of key to JWE recipients.

4.1.7 "x5u" (X.509 URL) Header Parameter​

The meaning, syntax, and processing rules for the "x5u" Header Parameter are the same as defined in Section 4.1.5 of [JWS], except that the X.509 public key certificate or certificate chain [RFC5280] contains the public key to which the JWE was encrypted; this can be used to determine the private key needed to decrypt the JWE.

4.1.8 "x5c" (X.509 Certificate Chain) Header Parameter​

The meaning, syntax, and processing rules for the "x5c" Header Parameter are the same as defined in Section 4.1.6 of [JWS], except that the X.509 public key certificate or certificate chain [RFC5280] contains the public key to which the JWE was encrypted; this can be used to determine the private key needed to decrypt the JWE.

See Appendix B of [JWS] for an example "x5c" value.

4.1.9 "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter​

The meaning, syntax, and processing rules for the "x5t" Header Parameter are the same as defined in Section 4.1.7 of [JWS], except that the certificate referenced by the thumbprint contains the public key to which the JWE was encrypted; this can be used to determine the private key needed to decrypt the JWE. Note that certificate thumbprints are also sometimes known as certificate fingerprints.

4.1.10 "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header Parameter​

The meaning, syntax, and processing rules for the "x5t#S256" Header Parameter are the same as defined in Section 4.1.8 of [JWS], except that the certificate referenced by the thumbprint contains the public key to which the JWE was encrypted; this can be used to determine the private key needed to decrypt the JWE. Note that certificate thumbprints are also sometimes known as certificate fingerprints.

4.1.11 "typ" (Type) Header Parameter​

The meaning, syntax, and processing rules for the "typ" Header Parameter are the same as defined in Section 4.1.9 of [JWS], except that the type is of this complete JWE.

4.1.12 "cty" (Content Type) Header Parameter​

The meaning, syntax, and processing rules for the "cty" Header Parameter are the same as defined in Section 4.1.10 of [JWS], except that the type is of the secured content (the plaintext).

4.1.13 "crit" (Critical) Header Parameter​

The meaning, syntax, and processing rules for the "crit" Header Parameter are the same as defined in Section 4.1.11 of [JWS], except that Header Parameters for a JWE are being referred to, rather than Header Parameters for a JWS.

4.2 Public Header Parameter Names​

Additional Header Parameter names can be defined by those using JWEs. However, in order to prevent collisions, any new Header Parameter name should either be registered in the IANA "JSON Web Signature and Encryption Header Parameters" registry established by [JWS] or be a Public Name: a value that contains a Collision-Resistant Name. In each case, the definer of the name or value needs to take reasonable precautions to make sure they are in control of the part of the namespace they use to define the Header Parameter name.

New Header Parameters should be introduced sparingly, as they can result in non-interoperable JWEs.

4.3 Private Header Parameter Names​

A producer and consumer of a JWE may agree to use Header Parameter names that are Private Names: names that are not Registered Header Parameter names (Section 4.1) or Public Header Parameter names (Section 4.2). Unlike Public Header Parameter Names, Private Header Parameter Names are subject to collision and should be used with caution.

Last updated on