RFC 7638

JSON Web Key (JWK) Thumbprint

📅 published September 2015, from ietf

RFC 7638: JSON Web Key (JWK) Thumbprint 🔑✨

okay bestie, so this is RFC 7638, which is a Standards Track doc from the IETF 🎀 It was published in September 2015 by M. Jones (Microsoft) and N. Sakimura (Nomura Research Institute) and has ISSN 2070-1721. It doesn't obsolete or update anything, since there's no "Obsoletes" or "Updates" line in the header. Iconic, clean start 💅

Abstract

okay so the whole point is giving fingerprint for a key 🦋 This spec defines how to compute a hash value over a JSON Web Key (JWK). It tells you which fields of the JWK get hashed, how to build a canonical form out of those fields, and how to turn the resulting Unicode string into bytes to hash. The hash can then be used to identify or select the key that the JWK represents. ngl this is so smart 🧚

Status of This Memo

this is an Internet Standards Track document 🌸

it's a product of the Internet Engineering Task Force (IETF) and represents the consensus of the IETF community. it got public review and was approved for publication by the Internet Engineering Steering Group (IESG). if you want more on Internet Standards, check Section 2 of RFC 5741 📚

for the current status, errata, and how to give feedback, go to http://www.rfc-editor.org/info/rfc7638 💌

© 2015 IETF Trust and the persons identified as the document authors. All rights reserved. 🎀

this document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as in effect on the date of publication. read those carefully, bestie, because they explain your rights and restrictions. also, any Code Components pulled out of this document must include the Simplified BSD License text described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the Simplified BSD License 🫶

Table of Contents 📑

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
  1.1.  Notational Conventions  . . . . . . . . . . . . . . . . .   2
2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
3.  JSON Web Key (JWK) Thumbprint . . . . . . . . . . . . . . . .   3
  3.1.  Example JWK Thumbprint Computation  . . . . . . . . . . .   4
  3.2.  JWK Members Used in the Thumbprint Computation  . . . . .   6
    3.2.1.  JWK Thumbprint of a Private Key . . . . . . . . . . .   6
    3.2.2.  Why Not Include Optional Members? . . . . . . . . . .   7
  3.3.  Order and Representation of Members in Hash Input . . . .   7
  3.4.  Selection of Hash Function  . . . . . . . . . . . . . . .   8
  3.5.  JWK Thumbprints of Keys Not in JWK Format . . . . . . . .   8
4.  Practical JSON and Unicode Considerations . . . . . . . . . .   8
5.  Relationship to Digests of X.509 Values . . . . . . . . . . .   9
6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  10
7.  Security Considerations . . . . . . . . . . . . . . . . . . .  10
8.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  11
  8.1.  Normative References  . . . . . . . . . . . . . . . . . .  11
  8.2.  Informative References  . . . . . . . . . . . . . . . . .  12
Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  13
Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  13

1. Introduction ✨

so this spec defines a method for computing a hash value (a.k.a. digest) over a JSON Web Key (JWK) [JWK] 🔑 It says which fields in a JWK get used in the hash, how to make a canonical form for those fields, and how to convert the resulting Unicode string into a byte sequence to hash. The hash can identify or select the key the JWK represents. For example, you can use the base64url-encoded JWK Thumbprint value as a "kid" (key ID) value 🦋

1.1. Notational Conventions 💅

the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be read as described in "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119]. the interpretation should only apply when the terms show up in all capital letters. so lowercase "must" is just a regular word, periodt 🙈

2. Terminology 📖

this spec uses the same terminology as the "JSON Web Key (JWK)" [JWK], "JSON Web Signature (JWS)" [JWS], and "JSON Web Algorithms (JWA)" [JWA] specs.

it also defines one term of its own:

  • JWK Thumbprint: the digest value for a JWK. 🎀

3. JSON Web Key (JWK) Thumbprint 🌈

okay so here's how you get the thumbprint of a JSON Web Key (JWK):

  1. Build a JSON object [RFC7159] that has only the required members of a JWK representing the key. There's no whitespace or line breaks before or after any syntactic elements, and the required members are sorted lexicographically by the Unicode [UNICODE] code points of their member names. (This JSON object is itself a legal JWK representation of the key. it's giving self-aware 😭)
  2. Hash the octets of the UTF-8 representation of this JSON object with a cryptographic hash function H. For example, SHA-256 [SHS] might be used as H. See Section 3.4 for a discussion on choosing the hash function 🔥

the result is the JWK Thumbprint with H of the JWK. the details get broken down in the sections that follow 💖

3.1. Example JWK Thumbprint Computation 🧁

this section walks through the JWK Thumbprint computation for the JWK below. the long line is broken up for display only ✨

{
 "kty": "RSA",
 "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAt
       VT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn6
       4tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FD
       W2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n9
       1CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINH
       aQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
 "e": "AQAB",
 "alg": "RS256",
 "kid": "2011-04-29"
}

as defined in "JSON Web Key (JWK)" [JWK] and "JSON Web Algorithms (JWA)" [JWA], the required members for an RSA public key are:

  • "kty"
  • "n"
  • "e"

so those are the members used in the thumbprint computation 🎯

their lexicographic order, per Section 3.3, is:

  • "e"
  • "kty"
  • "n"

so the JSON object built as an intermediate step in the computation is as follows. the line is broken for display only 🌸

{"e":"AQAB","kty":"RSA","n":"0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2
aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCi
FV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65Y
GjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n
91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_x
BniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw"}

the octets of the UTF-8 representation of this JSON object are:

[123, 34, 101, 34, 58, 34, 65, 81, 65, 66, 34, 44, 34, 107, 116, 121,
34, 58, 34, 82, 83, 65, 34, 44, 34, 110, 34, 58, 34, 48, 118, 120,
55, 97, 103, 111, 101, 98, 71, 99, 81, 83, 117, 117, 80, 105, 76, 74,
88, 90, 112, 116, 78, 57, 110, 110, 100, 114, 81, 109, 98, 88, 69,
112, 115, 50, 97, 105, 65, 70, 98, 87, 104, 77, 55, 56, 76, 104, 87,
120, 52, 99, 98, 98, 102, 65, 65, 116, 86, 84, 56, 54, 122, 119, 117,
49, 82, 75, 55, 97, 80, 70, 70, 120, 117, 104, 68, 82, 49, 76, 54,
116, 83, 111, 99, 95, 66, 74, 69, 67, 80, 101, 98, 87, 75, 82, 88,
106, 66, 90, 67, 105, 70, 86, 52, 110, 51, 111, 107, 110, 106, 104,
77, 115, 116, 110, 54, 52, 116, 90, 95, 50, 87, 45, 53, 74, 115, 71,
89, 52, 72, 99, 53, 110, 57, 121, 66, 88, 65, 114, 119, 108, 57, 51,
108, 113, 116, 55, 95, 82, 78, 53, 119, 54, 67, 102, 48, 104, 52, 81,
121, 81, 53, 118, 45, 54, 53, 89, 71, 106, 81, 82, 48, 95, 70, 68,
87, 50, 81, 118, 122, 113, 89, 51, 54, 56, 81, 81, 77, 105, 99, 65,
116, 97, 83, 113, 122, 115, 56, 75, 74, 90, 103, 110, 89, 98, 57, 99,
55, 100, 48, 122, 103, 100, 65, 90, 72, 122, 117, 54, 113, 77, 81,
118, 82, 76, 53, 104, 97, 106, 114, 110, 49, 110, 57, 49, 67, 98, 79,
112, 98, 73, 83, 68, 48, 56, 113, 78, 76, 121, 114, 100, 107, 116,
45, 98, 70, 84, 87, 104, 65, 73, 52, 118, 77, 81, 70, 104, 54, 87,
101, 90, 117, 48, 102, 77, 52, 108, 70, 100, 50, 78, 99, 82, 119,
114, 51, 88, 80, 107, 115, 73, 78, 72, 97, 81, 45, 71, 95, 120, 66,
110, 105, 73, 113, 98, 119, 48, 76, 115, 49, 106, 70, 52, 52, 45, 99,
115, 70, 67, 117, 114, 45, 107, 69, 103, 85, 56, 97, 119, 97, 112,
74, 122, 75, 110, 113, 68, 75, 103, 119, 34, 125]

using SHA-256 [SHS] as the hash function H, the JWK SHA-256 Thumbprint value is the SHA-256 hash of those octets, specifically:

[55, 54, 203, 177, 120, 124, 184, 48, 156, 119, 238, 140, 55, 5, 197,
225, 111, 251, 158, 133, 151, 21, 144, 31, 30, 76, 89, 177, 17, 130,
245, 123]

and the base64url encoding [JWS] of this JWK SHA-256 Thumbprint value (which might, for instance, be used as a "kid" (key ID) value) is:

NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs

3.2.2. Why Not Include Optional Members? 🎀

okay so bestie, optional members of a JWK are deliberately left OUT of the JWK Thumbprint computation 🙈 so that whether they're there or not doesn't change the result 💅 the thumbprint is a digest of the members needed to represent the key as a JWK, NOT of all the extra stuff that might ride along with the key ✨

the reason is that optional members are not included so the JWK Thumbprint refers to a key, not a key plus a bunch of attributes 🦋 different apps might include different optional attributes in their JWKs, and if those got hashed in, the same key would end up with different thumbprints 😭 which is literally the opposite of the point. the benefit is that the JWK Thumbprint of any JWK representing the key stays the same, no matter what other attributes are present 👑

different kinds of thumbprints could be defined by other specs that include some or all of the extra JWK members, if use cases ever come up where that would be useful 🌈 and if you want notes on some ways to cryptographically bind attributes to a key, check out Section 9.1 of RFC 7517 [JWK] 🧚

3.3. Order and Representation of Members in Hash Input 🍓

okay this part is lowkey the most detail-obsessed bit 🤓 the required members going into the hash function get ordered lexicographically by the Unicode code points of their member names ✨

characters in member names and member values MUST be represented WITHOUT being escaped 💀 so thumbprints of JWKs that need such characters are NOT defined by this spec. (not expected to be a big deal tho, bc JWK members aren't expected to use any of those characters 🫶) the characters that need escaping per Section 7 of [RFC7159] are quotation mark, reverse solidus (a.k.a. backslash), and the control characters U+0000 through U+001F 🔥

if the JWK key type uses members whose values are themselves JSON objects, then the members of THOSE objects MUST likewise be lexicographically ordered 💅 (as of writing, none are defined that do, so no cap, nothing to worry about yet 🌸)

if the JWK key type uses members whose values are JSON numbers, AND those numbers are integers, then they MUST be represented as a JSON number as defined in Section 6 of [RFC7159] WITHOUT a fraction part or exponent part 💖 for example, the value "1.024e3" MUST be represented as "1024" ✨ this means thumbprints of JWKs using numbers that aren't integers are NOT defined by this spec 🙈

also, as noted in "The I-JSON Message Format" [RFC7493], implementations cannot expect an integer whose absolute value is greater than 9007199254740991 (i.e., outside the range [-(253)+1, (253)-1]) to be treated as an exact value 😭 (again, as of writing, none are defined that use JSON numbers, so we're chillin 🦋)

see Section 4 for a discussion of further practical considerations about representing the hash input. go read it, it's giving important 👀

3.4. Selection of Hash Function 🔮

an application MUST choose a specific hash function to compute the hash value of the hash input 💜 for example, SHA-256 [SHS] might be used as the hash function by the application. SHA-256 is a good default choice at the time of writing, but the hash function of choice can be expected to change over time as the crypto landscape evolves 🌈

ngl, in many cases only the party that CREATES a key needs to know which hash function was used 🫶 a typical usage is for the producer of the key to use the base64url-encoded JWK Thumbprint value as a "kid" (key ID) value 🍓 in that case, the consumer of the "kid" treats it as an opaque value that it uses to select the key ✨

BUT, in some cases, multiple parties will be reproducing the JWK Thumbprint calculation and comparing the results 👯 in those cases, the parties will need to know which hash function was used and use the SAME one 💅

3.5. JWK Thumbprints of Keys Not in JWK Format 🧚

a key does NOT need to be in JWK format to create a JWK Thumbprint of it ✨ the only prerequisites are that the JWK representation of the key be defined, and that the party creating the thumbprint be in possession of the necessary key material 🔑 those are enough to create the hash input from the JWK representation of the key, as described in Section 3.3 🌸

4. Practical JSON and Unicode Considerations 💖

okay so implementations will almost certainly use the platform's JSON support when parsing the JWK and emitting the JSON object used as the hash input 💻 practically speaking, future JWK member names and values SHOULD be avoided if different platforms or libraries might emit different representations 😭 as of writing, all defined JWK member names and values use only printable ASCII characters, which should not have this problem ✨ BUT, note that JSON.stringify() can NOT be counted on to lexicographically sort the members of JSON objects 💀 so while it could emit some kinds of member values, different code is likely needed to do the sorting 🙈

in particular, ordering member names by their Unicode code points is well defined, BUT different platform sort functions may produce different results for non-ASCII characters, in ways that aren't obvious to devs 🫠 if writers of future specs defining new JWK key type values choose to stick to printable ASCII member names and values (which are for machine, not human, consumption anyway 🤖), some future interop problems might be avoided 🦋

however, if new JWK members are defined that use non-ASCII member names or values, their definitions SHOULD specify the exact Unicode code point sequences used to represent them 👑 this is especially important where Unicode normalization could transform one set of code points into another under any circumstances 🔥

use of escaped characters in JWKs for which JWK Thumbprints will be computed SHOULD be avoided 🌈 and use of escaped characters in the hash input JWKs derived from these original JWKs is PROHIBITED 🚫

there is a natural representation to use for numeric values that are integers ✨ however, this spec does NOT attempt to define a standard representation for numbers that aren't integers or that contain an exponent component 🧚 not expected to be a problem in practice, since the required members of JWK representations are expected to use only integer numbers 💜

use of number representations containing fraction or exponent parts in JWKs for which JWK Thumbprints will be computed SHOULD be avoided 🌸

all of these practical considerations are really an instance of Jon Postel's principle: "Be liberal in what you accept, and conservative in what you send." 🫶💅

5. Relationship to Digests of X.509 Values 🎀

okay so JWK Thumbprint values are computed on the JWK members REQUIRED to represent a key, NOT all the members of the JWK the key is represented in 🙌 which makes them more analogous to apps that use digests of X.509 Subject Public Key Info (SPKI) values (defined in Section 4.1.2.7 of [RFC5280]) than to apps that use digests of complete certificate values 🦋 like the "x5t" (X.509 certificate SHA-1 thumbprint) [JWS] value defined for X.509 certificate objects does ✨

while logically equivalent to a digest of the SPKI representation of the key, a JWK Thumbprint is computed over a JSON representation of that key, rather than over an ASN.1 representation of it 🧠✨

6. IANA Considerations 🌷

this spec adds to the instructions for the Designated Experts of the following IANA registries, all of which are in the "JSON Object Signing and Encryption (JOSE)" registry [IANA.JOSE]:

  • JSON Web Key Types
  • JSON Web Key Elliptic Curve
  • JSON Web Key Parameters

IANA has added a link to this specification in the Reference sections of these registries 🔗💖

for these registries, because of the practical JSON and Unicode considerations in Section 4, the Designated Experts MUST either:

  1. require that JWK member names and values being registered use only printable ASCII characters excluding double quote ('"') and backslash ('\') (the Unicode characters with code points U+0021, U+0023 through U+005B, and U+005D through U+007E), OR
  2. if new JWK members or values are defined that use other code points, require that their definitions specify the exact Unicode code point sequences used to represent them. Furthermore, proposed registrations that use Unicode code points that can only be represented in JSON strings as escaped characters MUST NOT be accepted 🚫😭

7. Security Considerations 🔐

okay bestie, this section is SERIOUS so let's go 💀

the JSON Security Considerations and Unicode Comparison Security Considerations described in Sections 10.12 and 10.13 of "JSON Web Signature (JWS)" [JWS] ALSO apply to this specification 🫡

as described in Section 4, some implementations may produce INCORRECT results if esoteric or escaped characters are used in the member names 😵 the security implications of this appear to be limited for JWK Thumbprints of public keys, because while it may result in implementations failing to identify the intended key, it should NOT leak information 🙏 the information in a public key is already public in nature, by definition 🌊

a hash of a symmetric key has the potential to leak information about the key value 🚨 thus, the JWK Thumbprint of a symmetric key SHOULD typically be concealed from parties NOT in possession of the symmetric key, UNLESS in the application context, the cryptographic hash used (such as SHA-256) is known to provide sufficient protection against disclosure of the key value 🔒

a JWK Thumbprint will ONLY uniquely identify a particular key if a single unambiguous JWK representation for that key is defined AND used when computing the JWK Thumbprint 💎 (such representations are defined for all the key types defined in "JSON Web Algorithms (JWA)" [JWA] 🧁) for example, if an RSA key were to use "e":"AAEAAQ" (representing [0, 1, 0, 1]) rather than the specified correct representation of "e":"AQAB" (representing [1, 0, 1]), then a DIFFERENT thumbprint value would be produced for what could be effectively the same key, at least for implementations that are lax in validating the JWK values they accept 😬 thus, JWK Thumbprint values can ONLY be relied upon to be unique for a given key if the implementation ALSO validates that the correct representation of the key is used ✅

even MORE insidious: an attacker may supply a key that is a transformation of a legal key to make it appear to be a different key 😱 for instance, if a legitimate RSA key uses a modulus value N and an attacker supplies a key with modulus 3*N, the modified key would still work about 1/3 of the time, but would APPEAR to be a different key 🫣 thus, while thumbprint values are valuable for identifying legitimate keys, comparing thumbprint values is NOT a reliable means of excluding (blacklisting) the use of particular keys (or transformations thereof) 🚫🖤

8. References 📚

8.1. Normative References 📚

These are the docs you have to read to get this spec, bestie. Nothing skippable here 💅

8.2. Informative References 🧠

These ones are the extra-credit reading. Super helpful for background, not required to implement 🌸

Acknowledgements 🫶

James Manger and John Bradley were part of the chats that led to this spec existing at all, so big thank yous to them ✨ Thanks also to Joel Halpern, Barry Leiba, Adam Montville, Kathleen Moriarty, and Jim Schaad for reviewing it. Iconic reviewers, honestly 👑

Authors' Addresses 🎀

Michael B. Jones Microsoft

Email: mbj@microsoft.com URI: http://self-issued.info/

Nat Sakimura Nomura Research Institute

Email: n-sakimura@nri.co.jp URI: http://nat.sakimura.org/

That's the whole RFC, bestie! Everything from the JWK Thumbprint math to the security stuff is wrapped up 🦋💖

📦 where this page comes from