JSON Web Algorithms (JWA)
updated by
- rfc-9864 — Fully-Specified Algorithms for JSON Object Signing and Encryption (JOSE) and CBOR Object Signing and Encryption (COSE)
Extracted elements (30)
Algorithm identifier names defined by JWA are intentionally kept short because a core goal is for the resulting JOSE representations to be compact. This is why 'HS256' is used rather than a longer descriptive name.
In the AES_CBC_HMAC_SHA2 key K, the MAC key occupies the initial (first) octets and the ENC key occupies the final octets — the opposite order from the algorithm name 'AES_CBC_HMAC_SHA2'. This non-obvious ordering is explicitly called out in the specification to prevent implementation errors.
SEC1 point compression is not supported for EC keys (P-256, P-384, P-521) represented as JWKs. Some cryptographic libraries prefix an extra zero-valued octet to RSA modulus representations (e.g., 257 octets for a 2048-bit key); implementations must omit this extra octet from Base64urlUInt encoding.
A key of size 2048 bits or larger MUST be used with RSASSA-PSS algorithms (PS256/PS384/PS512). Salt size equals hash output size; MGF1 uses the same hash function as the main RSASSA-PSS hash.
A key of the same size as the hash output or larger MUST be used with HMAC SHA-2 algorithms. For HS256, HS384, and HS512, this means minimum key sizes of 256, 384, and 512 bits, respectively.
A new ephemeral public key value MUST be generated for each ECDH-ES key agreement operation. In Direct Key Agreement mode, the Concat KDF output MUST be a key of the same length as required by the 'enc' algorithm.
For AES GCM content encryption (A128GCM/A192GCM/A256GCM), use of a 96-bit IV is REQUIRED and the Authentication Tag output MUST be 128 bits regardless of key size.
For AES GCM key encryption (A128GCMKW/A192GCMKW/A256GCMKW), use of a 96-bit IV is REQUIRED, and the Authentication Tag output MUST be 128 bits regardless of key size. The 'iv' and 'tag' Header Parameters MUST be present and processed.
For PBES2 key encryption, a minimum iteration count of 1000 is RECOMMENDED for the 'p2c' (PBES2 count) Header Parameter. The iteration count adds computational expense to resist brute-force attacks.
For PBES2 key encryption, a Salt Input value containing 8 or more octets MUST be used, and a new Salt Input MUST be generated randomly for every encryption operation. The actual PBKDF2 salt is UTF8(Alg) || 0x00 || Salt Input.
Implementations MUST NOT accept Unsecured JWSs (alg='none') by default, and applications MUST NOT signal acceptance at a global level. Acceptance must be signaled per-object to mitigate downgrade attacks.
The comparison of the computed HMAC value to the JWS Signature value MUST be done in a constant-time manner to thwart timing attacks. Alternatively, both values may be base64url encoded before comparison, also in constant-time.
AES_CBC_HMAC_SHA2 is a composite authenticated encryption family using AES-CBC (PKCS#7 padding) plus HMAC. The input key K is split: MAC_KEY occupies the initial half, ENC_KEY the final half. MAC input is A || IV || E || AL (where AL is the 64-bit big-endian bit-length of AAD), and the tag is the first T_LEN octets of the HMAC output.
EC JWK public keys require 'crv' (P-256, P-384, or P-521), 'x', and 'y' parameters as base64url-encoded coordinate octet strings whose length MUST be the full coordinate size for the curve. Private keys additionally require 'd' with length ceiling(log2(n)/8) octets. SEC1 point compression is not supported.
ECDH-ES key derivation uses the Concat KDF (NIST SP 800-56A Section 5.8.1) with SHA-256, using parameters Z (shared secret), keydatalen, AlgorithmID (enc or alg value as ASCII), PartyUInfo (from 'apu'), PartyVInfo (from 'apv'), SuppPubInfo (keydatalen as 32-bit big-endian), and empty SuppPrivInfo. The 'apu' and 'apv' values MUST be distinct when used.
RSA JWK public keys require 'n' (modulus) and 'e' (exponent) as Base64urlUInt-encoded values. Private keys require 'd' and SHOULD include 'p', 'q', 'dp', 'dq', 'qi' for CRT optimization; if any optional CRT parameter is present, all MUST be present. The 'oth' parameter MUST only be present for keys with more than two prime factors.
Symmetric JWK keys use 'kty'='oct' and carry the key value in the 'k' parameter as base64url-encoded octets. An 'alg' member SHOULD also be present to identify the intended algorithm unless another mechanism determines the algorithm.
The 'alg' Header Parameter values for JWE key management are defined, including RSA1_5 (Recommended-), RSA-OAEP (Recommended+), A128KW/A256KW (Recommended), dir (Recommended), ECDH-ES (Recommended+), ECDH-ES+A128KW/A256KW (Recommended), A128GCMKW/A192GCMKW/A256GCMKW (Optional), and PBES2 variants (Optional).
The 'alg' Header Parameter values for JWS are defined as: HS256 (Required), HS384/HS512 (Optional), RS256 (Recommended), RS384/RS512 (Optional), ES256 (Recommended+), ES384/ES512 (Optional), PS256/PS384/PS512 (Optional), and 'none' (Optional). Each maps to a specific cryptographic algorithm for digital signatures or MACs.
The 'enc' Header Parameter values for JWE content encryption are: A128CBC-HS256 and A256CBC-HS512 (Required), A192CBC-HS384 (Optional), A128GCM and A256GCM (Recommended), A192GCM (Optional). All use an IV value and produce Ciphertext and Authentication Tag values.
The 'epk' (ephemeral public key) Header Parameter carries the originator's ephemeral public key as a JWK value for ECDH key agreement. It MUST contain only public key parameters and MUST be present and processed when ECDH-ES algorithms are used.
The 'JSON Web Encryption Compression Algorithms' IANA registry is established with initial value 'DEF' (DEFLATE per RFC 1951). Registration uses the Specification Required process.
The 'JSON Web Key Elliptic Curve' IANA registry is established with initial values P-256, P-384, and P-521 from FIPS DSS. Registration of additional curves must define the parameters used to represent keys for those curves.
The 'JSON Web Key Types' IANA registry is established with initial values EC (Recommended+), RSA (Required), and oct (Required). Registration requires Specification Required review.
The 'JSON Web Signature and Encryption Algorithms' IANA registry is established for JWS/JWE 'alg' and 'enc' Header Parameter values. Registration requires Specification Required review; fields include Algorithm Name, Description, Usage Locations, Implementation Requirements, and Change Controller. Implementation requirements may be updated over time via Specification Required process.
AES GCM is vulnerable to catastrophic failure if an IV is ever reused with the same key. For AES GCM content encryption, a 96-bit IV is required and must never be reused; direct encryption ('dir') with AES GCM requires careful IV management over the key's lifetime.
Passwords used with PBES2 algorithms have limited entropy and are susceptible to brute-force and dictionary attacks. A high PBKDF2 iteration count and a unique random salt per operation are essential mitigations; the password input MUST be UTF-8 encoded when supplied as text.
RSAES-PKCS1-v1_5 (RSA1_5) is vulnerable to adaptive chosen-ciphertext attacks (Bleichenbacher attack). Implementations MUST use constant-time decryption and random padding checks to mitigate this; its Implementation Requirement is marked Recommended- indicating likely future deprecation.
Unsecured JWSs (alg='none') provide no integrity protection. Applications accepting them are vulnerable to downgrade attacks where an attacker strips a valid signature and presents an unsigned token. Per-object acceptance control is required to mitigate this.
The ECDSA JWS Signature value is the fixed-length concatenation of the R and S integers as big-endian octet sequences. For ES256, R and S are each 32 octets (64 total); for ES384, 48 octets each (96 total); for ES512, 66 octets each (132 total). Leading zero octets MUST NOT be omitted.