JSON Web Key (JWK) ThumbprintMicrosoftmbj@microsoft.comhttp://self-issued.info/Nomura Research Instituten-sakimura@nri.co.jphttp://nat.sakimura.org/
Security
JOSE Working GroupRFCRequest for CommentsI-DInternet-DraftJavaScript Object NotationJSONJSON Web KeyJWKThumbprintFingerprint
This specification defines a means of computing a thumbprint value (a.k.a. digest)
of a key represented as a JSON Web Key (JWK).
This specification defines a means of computing a thumbprint value (a.k.a. digest)
of a key represented as a JSON Web Key (JWK).
This value can be used for identifying or selecting the key that
is the subject of the thumbprint, for instance,
by using the base64url encoded JWK Thumbprint value
as a kid (key ID) value.
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 interpreted as
described in
Key words for use in RFCs to Indicate Requirement Levels .
This specification uses the same terminology as the
JSON Web Key (JWK) ,
JSON Web Signature (JWS) ,
and
JSON Web Algorithms (JWA)
specifications.
This term is defined by this specification:
The digest value for a key that is the subject of this specification.
The thumbprint of a JSON Web Key (JWK) is computed as follows:
Construct a JSON object
containing only the REQUIRED members of a JWK representing the key
and with no white space or line breaks before or after any syntactic elements
and with the REQUIRED members ordered lexicographically
by the Unicode code points of the member names.
(This JSON object is itself a legal JWK representation of the key.)
Hash the octets of the UTF-8 representation of this JSON object with
a cryptographic hash function H.
For example, SHA-256 might be used as H.
The resulting value is the JWK Thumbprint with H of the JWK.
The details of this computation are further described in subsequent sections.
This section demonstrates the JWK Thumbprint computation for the JWK below
(with long lines broken for display purposes only):
As defined in
JSON Web Key (JWK) and
JSON Web Algorithms (JWA) ,
the REQUIRED members of an RSA public key are:
ktyne
Therefore, these are the members used in the thumbprint computation.
Their lexicographic order
(see more about this in ) is:
ektyn
Therefore the JSON object constructed as an intermediate step
in the computation is as follows
(with long lines broken for display purposes only):
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 as the hash function H,
the JWK SHA-256 Thumbprint value is the SHA-256 hash of these 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]
The base64url encoding of this JWK SHA-256 Thumbprint value
(which might, for instance, be used as a kid (key ID) value) is:
Only the REQUIRED members of a key's representation are used
when computing its JWK Thumbprint value.
As defined in
JSON Web Key (JWK) and
JSON Web Algorithms (JWA) ,
the REQUIRED members of an elliptic curve public key
for the curves specified in Section 6.2.1.1 of ,
in lexicographic order, are:
crvktyxy
the REQUIRED members of an RSA public key, in lexicographic order, are:
ektyn
and the REQUIRED members of a symmetric key, in lexicographic order, are:
kkty
As other key type values are defined, the specifications defining them
should be similarly consulted to determine which members,
in addition to kty, are REQUIRED.
The JWK Thumbprint of a private key is computed as
the JWK Thumbprint of the corresponding public key.
This has the intentional benefit that the same JWK Thumbprint value
can be computed both by parties using either the public or private key.
The JWK Thumbprint can then be used to refer to both keys of the key pair.
Application context can be used to determine whether
the public or the private key is the one being referred to
by the JWK Thumbprint.
This specification defines the method of computing JWK Thumbprints
of private keys for interoperability reasons
-- so that different implementations computing JWK Thumbprints
of private keys will produce the same result.
Optional members of JWKs are intentionally not included in
the JWK Thumbprint computation so that their absence or presence
in the JWK doesn't alter the resulting value.
The JWK Thumbprint value is a digest of the key value itself --
not of additional data that may also accompany the key.
Optional members are not included so that the JWK Thumbprint refers to
a key -- not a key with an associated set of key attributes.
This has the benefit that while in different application contexts
different subsets of attributes about the key might or might not be
included in the JWK, the JWK Thumbprint of the key remains the same
regardless of which optional attributes are present.
Different kinds of thumbprints could be defined by other specifications
that might include some or all additional JWK members, should use cases
arise where such different kinds of thumbprints would be useful.
See Section 9.1 of for notes on some ways
to cryptographically bind attributes to a key.
The required members in the input to the hash function are
ordered lexicographically by the Unicode code points of the member names.
Characters in member names and member values MUST be represented
without being escaped.
This means that thumbprints of JWKs that require such characters
are not defined by this specification.
(This is not expected to limit the applicability of this specification,
in practice, as the members of JWK representations
are not expected to use any of these characters.)
The characters specified as requiring escaping
by Section 7 of
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
(as of the time of this writing, none are defined that do),
the members of those objects must likewise be lexicographically ordered.
If the JWK key type uses members whose values are JSON numbers
(as of the time of this writing, none are defined that do),
if the numbers are integers, they MUST be represented
as a JSON number as defined in Section 6 of
without including a fraction part or exponent part.
For instance, the value 1.024e3 MUST be
represented as 1024.
This means that thumbprints of JWKs that use numbers that are not integers
are not defined by this specification.
Also, as noted in The I-JSON Message Format ,
implementations cannot expect an integer
whose absolute value is greater than 9007199254740991
(i.e., that is outside the range [-(2**53)+1, (2**53)-1])
to be treated as an exact value.
See for a discussion of
further practical considerations pertaining to the
representation of the hash input.
Note that a key need not 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 the party creating the JWK Thumbprint is in possession
of the necessary key material.
These are sufficient to create the hash input
from the JWK representation of the key,
as described in .
Implementations will almost certainly use functionality
provided by the platform's JSON support
when parsing the JWK and emitting the JSON object used as
the hash input.
As a practical consideration,
future JWK member names should be avoided for which different
platforms or libraries might emit different representations.
As of the time of this writing, currently all defined JWK member names
use only printable ASCII characters, which should not exhibit this problem.
Note however, that JSON.stringify() cannot be counted on to lexicographically sort
the members of JSON objects, so while it may be able to be used to emit
some kinds of member values, different code is likely to be needed
to perform the sorting.
In particular, while the operation of
lexicographically ordering member names by their Unicode code points
is well defined, different platform sort functions may produce different results
for non-ASCII characters, in ways that may not be obvious to developers.
If writers of future specifications defining new
JWK Key Type values choose to restrict themselves to ASCII member names
(which are for machine and not human consumption anyway),
some future interoperability problems might be avoided.
However, if new JWK members are defined that use non-ASCII member names,
their definitions should specify the exact Unicode code point sequences
used to represent them,
particularly in cases in which Unicode normalization could result in
the transformation of one set of code points into another under any circumstances.
Use of escaped characters in the input JWK representation SHOULD be avoided.
While there is a natural representation to use for numeric values
that are integers, this specification doesn't attempt to define
a standard representation for numbers that are not integers or
that contain an exponent component.
This is not expected to be a problem in practice,
as the required members of JWK representations
are not expected to use numbers that are not integers.
Use of number representations containing fraction or exponent parts
in the input JWK representation 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."
This specification makes no requests of IANA.
The JSON Security Considerations and Unicode Comparison Security Considerations described in
Sections 10.2 and 10.3 of JSON Web Signature (JWS)
also apply to this specification.
Also, as described in ,
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, since while it may result in implementations failing
to identify the intended key, it should not leak information,
since 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 be 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) .)
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]),
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 that 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 is that an attacker may supply a key that is a transformation
of a legal key in order to have 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).
JWK Thumbprint values are computed on the members required to represent a key,
rather than all members of a JWK that the key is represented in.
Thus, they are more analogous to applications that use digests of
X.509 Subject Public Key Info (SPKI) values, which are defined in
Section 4.1.2.7 of ,
than to applications that use digests of complete certificate values, as the
x5t (X.509 Certificate SHA-1 Thumbprint)
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.
JSON Web Key (JWK)Microsoftmbj@microsoft.comhttp://self-issued.info/JSON Web Signature (JWS)Microsoftmbj@microsoft.comhttp://self-issued.info/Ping Identityve7jtb@ve7jtb.comNomura Research Instituten-sakimura@nri.co.jpJSON Web Algorithms (JWA)Microsoftmbj@microsoft.comhttp://self-issued.info/The Unicode StandardThe Unicode ConsortiumSecure Hash Standard (SHS)National Institute of Standards and
Technology
James Manger and John Bradley participated in discussions
that led to the creation of this specification.
Jim Schaad
also contributed to this specification.
[[ to be removed by the RFC editor before publication as an RFC ]]
-03
Addressed review comments by James Manger and Jim Schaad,
including adding a section on the relationship to digests of X.509 values.
-02
No longer register the new
JSON Web Signature (JWS) and
JSON Web Encryption (JWE)
Header Parameters and
the new JSON Web Key (JWK) member name
jkt (JWK SHA-256 Thumbprint)
for holding these values.
Added security considerations about the measures needed to ensure that
a unique JWK Thumbprint value is produced for a key.
Added text saying that the base64url encoded JWK Thumbprint value
could be used as a kid (key ID) value.
Broke a sentence up that used to be way too long.
-01
Addressed issues pointed out by Jim Schaad,
including defining the JWK Thumbprint computation in a manner
that allows different hash functions to be used over time.
Added Nat Sakimura as an editor.
-00
Created draft-ietf-jose-jwk-thumbprint-00 from
draft-jones-jose-jwk-thumbprint-01 with no normative changes.