JSON Web Key (JWK) Thumbprint
Extracted elements (20)
JWK Thumbprints are analogous to digests of X.509 Subject Public Key Info (SPKI) values rather than digests of complete certificates, since they are computed over only the key material members rather than all JWK members.
Only required JWK members are used in the thumbprint computation so that optional attributes do not alter the result. This means the thumbprint identifies a key itself, not a key with a particular set of attributes, allowing the same thumbprint regardless of which optional members are present.
The hash function is not mandated by this specification; SHA-256 is suggested as a good default but applications choose their hash function. The choice is expected to evolve as the cryptographic landscape changes.
The JWK Thumbprint of a private key is computed as the JWK Thumbprint of the corresponding public key, intentionally allowing both parties using either key to compute the same thumbprint value and use it to refer to the key pair.
Different platform sort functions may produce different results for non-ASCII characters; future JWK key type definitions should restrict member names and values to printable ASCII to avoid interoperability problems in thumbprint computation.
JSON.stringify() cannot be relied upon to lexicographically sort members of JSON objects, so implementations must use separate code for the required member ordering step.
When multiple parties need to reproduce and compare JWK Thumbprint calculations, they must agree on and use the same hash function; in the common case where only the key producer computes the thumbprint (e.g., as a 'kid'), consumers treat it as an opaque value.
Characters in member names and member values MUST be represented without being escaped in the hash input JSON object.
If JWK member values are JSON integers, they MUST be represented as a JSON number without a fraction part or exponent part (e.g., '1024' not '1.024e3').
If the JWK key type uses members whose values are themselves JSON objects, then the members of those objects MUST likewise be lexicographically ordered in the hash input.
Use of escaped characters in the hash input JWKs derived from original JWKs is prohibited; use of escaped characters in original JWKs for which thumbprints will be computed should be avoided.
A JWK Thumbprint is computed by constructing a JSON object containing only the required members of the JWK, with no whitespace, members ordered lexicographically by Unicode code points, then hashing the UTF-8 representation with a cryptographic hash function H.
The required members for a symmetric key thumbprint computation, in lexicographic order, are: 'k' and 'kty'.
The required members for an elliptic curve public key thumbprint computation, in lexicographic order, are: 'crv', 'kty', 'x', and 'y'.
The required members for an RSA public key thumbprint computation, in lexicographic order, are: 'e', 'kty', and 'n'.
This specification adds to the instructions for Designated Experts of the JSON Web Key Types, JSON Web Key Elliptic Curve, and JSON Web Key Parameters registries under the JOSE registry, requiring that new member names and values use only printable ASCII excluding double quote and backslash, or specify exact Unicode code point sequences.
A hash of a symmetric key may leak information about the key value; the JWK Thumbprint of a symmetric key should typically be concealed from parties not in possession of the key, unless the hash function provides sufficient protection.
Comparing thumbprint values is not a reliable means of blacklisting keys, because an attacker can supply a transformed key (e.g., RSA modulus 3*N) that produces a different thumbprint but still functions for some operations.
JWK Thumbprint values uniquely identify a key only if a single unambiguous JWK representation is defined and used; implementations must validate correct key representation (e.g., canonical base64url encoding) or different thumbprints may result for the same effective key.
The hash input is the UTF-8 encoded byte sequence of the canonical JSON object containing only required JWK members with lexicographically ordered names and no whitespace. The output is the raw hash bytes, typically base64url-encoded for use as a 'kid' value.