JSON Web Key (JWK)
Extracted elements (28)
JWK parameter names are intentionally kept short (recommended not to exceed 8 characters) because a core design goal is compact representations. This applies to the parameter name registry template and is why all built-in parameters are 2–8 characters long.
String comparison rules for JWK parameter names follow the same rules defined in Section 5.3 of JWS (RFC 7515), which mandates case-sensitive, byte-by-byte Unicode string comparison.
When optional members such as "use", "alg", or "key_ops" are present alongside X.509 certificate parameters ("x5u", "x5c", "x5t", "x5t#S256"), including them may improve interoperability for applications that do not handle PKIX certificates, though doing so is not required.
Access to JWKs containing non-public key material by parties without legitimate access MUST be prevented. Encrypting the JWK as a JWE is recommended; a "cty" header value of "jwk+json" MUST be used to signal that JWE content is a JWK.
Additional members present in a JWK that are not understood by an implementation MUST be ignored. This applies equally to JWK Sets and their additional members.
Duplicate key operation values MUST NOT be present in the "key_ops" array. Multiple unrelated key operations SHOULD NOT be specified for a key due to vulnerabilities from using the same key with multiple algorithms.
If optional JWK members such as "use" or "alg" are present alongside "x5c", "x5u", "x5t", or "x5t#S256", the contents of those members MUST be semantically consistent with the related fields in the first certificate.
Implementations SHOULD ignore JWKs within a JWK Set that use "kty" values they do not understand, that are missing required members, or for which values are out of the supported ranges.
Member names within a JWK MUST be unique. JWK parsers MUST either reject JWKs with duplicate member names or use a JSON parser that returns only the lexically last duplicate, per ECMAScript 5.1 Section 15.12.
The JWK Set JSON object MUST have a "keys" member containing an array of JWKs. Member names within a JWK Set MUST be unique with the same duplicate-handling rules as JWKs.
The "kty" member MUST be present in a JWK. It identifies the cryptographic algorithm family (e.g., "RSA", "EC", "oct") and determines which additional key-type-specific members are required.
The "use" and "key_ops" JWK members SHOULD NOT be used together; if both are present, the information they convey MUST be consistent. Applications should specify which of these members they use.
When fetching a certificate via the "x5u" parameter, the protocol MUST provide integrity protection; an HTTP GET MUST use TLS and the server identity MUST be validated per RFC 6125 Section 6.
A JSON Web Key (JWK) is a JSON object that represents a cryptographic key. The members of the object represent properties of the key, including its value. The "kty" parameter is the only required member; all other common parameters are optional.
A JWK Set is a JSON object that represents a set of JWKs. It MUST have a "keys" member whose value is an array of JWK values. By default, the order of JWKs within the array does not imply an order of preference.
The "alg" (algorithm) parameter identifies the algorithm intended for use with the key. Its value is a case-sensitive ASCII string; use is OPTIONAL and values should be registered in the IANA "JSON Web Signature and Encryption Algorithms" registry or use a Collision-Resistant Name.
The "key_ops" (key operations) parameter is an array of string values identifying intended key operations: "sign", "verify", "encrypt", "decrypt", "wrapKey", "unwrapKey", "deriveKey", and "deriveBits". Values are case-sensitive and duplicate entries MUST NOT be present.
The "kid" (key ID) parameter is an OPTIONAL case-sensitive string used to match a specific key within a JWK Set, for example during key rollover. Different keys within a JWK Set SHOULD use distinct "kid" values.
The "kty" (key type) parameter identifies the cryptographic algorithm family used with the key, such as "RSA" or "EC". The value is a case-sensitive string and MUST be present in every JWK.
The "use" (public key use) parameter indicates whether a public key is used for encryption ("enc") or signature verification ("sig"). Use of this member is OPTIONAL unless required by the application; key agreement and key wrapping also use "enc".
The "x5c" (X.509 certificate chain) parameter contains a JSON array of base64-encoded (not base64url) DER-encoded PKIX certificates. The first certificate MUST contain the key value, followed optionally by the issuing chain; the key in the first certificate MUST match the JWK's public key.
The "x5t" and "x5t#S256" parameters are base64url-encoded SHA-1 and SHA-256 thumbprints (digests) of the DER encoding of an X.509 certificate, respectively. The key in the referenced certificate MUST match the public key represented by other JWK members.
The "x5u" (X.509 URL) parameter is a URI pointing to an X.509 certificate or certificate chain in PEM-encoded form. The resource MUST be retrieved via TLS with server identity validation, and the key in the first certificate MUST match the JWK's public key.
RFC 7517 establishes the IANA "JSON Web Key Set Parameters" registry for JWK Set parameter names. The initial entry is "keys" (Array of JWK Values). It also registers the "application/jwk+json" and "application/jwk-set+json" media types.
Key entropy and random value generation are critical; implementations must follow the guidance in Section 10.1 of JWS (RFC 7515) regarding sufficient entropy for key generation.
Private and symmetric keys MUST be protected from disclosure to unintended parties. The recommended mechanism is to encrypt the JWK or JWK Set as a JWE; a secure channel for the encryption key must also be established.
RSA key blinding (a defense against timing attacks) requires all of the values "n", "e", and "d". RSA private key representations that omit the public exponent "e" (such as Java's RSAPrivateKeySpec) should be avoided; RSAPrivateCrtKeySpec is preferred.
Trust in data secured by a key should not exceed the trustworthiness of the method by which the key was obtained and the entity asserting the key association. Applications typically bind attributes to JWKs via PKIX certificates in "x5c" or via JWT claims referencing the JWK.