draft-ietf-jose-jwk-thumbprint-08.txt   rfc7638.txt 
JOSE Working Group M. Jones Internet Engineering Task Force (IETF) M. Jones
Internet-Draft Microsoft Request for Comments: 7638 Microsoft
Intended status: Standards Track N. Sakimura Category: Standards Track N. Sakimura
Expires: January 10, 2016 NRI ISSN: 2070-1721 Nomura Research Institute
July 9, 2015 September 2015
JSON Web Key (JWK) Thumbprint JSON Web Key (JWK) Thumbprint
draft-ietf-jose-jwk-thumbprint-08
Abstract Abstract
This specification defines a method for computing a hash value over a This specification defines a method for computing a hash value over a
JSON Web Key (JWK). It defines which fields in a JWK are used in the JSON Web Key (JWK). It defines which fields in a JWK are used in the
hash computation, the method of creating a canonical form for those hash computation, the method of creating a canonical form for those
fields, and how to convert the resulting Unicode string into a byte fields, and how to convert the resulting Unicode string into a byte
sequence to be hashed. The resulting hash value can be used for sequence to be hashed. The resulting hash value can be used for
identifying or selecting the key represented by the JWK that is the identifying or selecting the key represented by the JWK that is the
subject of the thumbprint. subject of the thumbprint.
Status of this Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering This is an Internet Standards Track document.
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741.
This Internet-Draft will expire on January 10, 2016. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc7638.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. JSON Web Key (JWK) Thumbprint . . . . . . . . . . . . . . . . 3 3. JSON Web Key (JWK) Thumbprint . . . . . . . . . . . . . . . . 3
3.1. Example JWK Thumbprint Computation . . . . . . . . . . . . 4 3.1. Example JWK Thumbprint Computation . . . . . . . . . . . 4
3.2. JWK Members Used in the Thumbprint Computation . . . . . . 5 3.2. JWK Members Used in the Thumbprint Computation . . . . . 6
3.2.1. JWK Thumbprint of a Private Key . . . . . . . . . . . 6 3.2.1. JWK Thumbprint of a Private Key . . . . . . . . . . . 6
3.2.2. Why Not Include Optional Members? . . . . . . . . . . 6 3.2.2. Why Not Include Optional Members? . . . . . . . . . . 7
3.3. Order and Representation of Members in Hash Input . . . . 7 3.3. Order and Representation of Members in Hash Input . . . . 7
3.4. Selection of Hash Function . . . . . . . . . . . . . . . . 8 3.4. Selection of Hash Function . . . . . . . . . . . . . . . 8
3.5. JWK Thumbprints of Keys Not in JWK Format . . . . . . . . 8 3.5. JWK Thumbprints of Keys Not in JWK Format . . . . . . . . 8
4. Practical JSON and Unicode Considerations . . . . . . . . . . 8 4. Practical JSON and Unicode Considerations . . . . . . . . . . 8
5. Relationship to Digests of X.509 Values . . . . . . . . . . . 9 5. Relationship to Digests of X.509 Values . . . . . . . . . . . 9
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
7. Security Considerations . . . . . . . . . . . . . . . . . . . 10 7. Security Considerations . . . . . . . . . . . . . . . . . . . 10
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11
8.1. Normative References . . . . . . . . . . . . . . . . . . . 11 8.1. Normative References . . . . . . . . . . . . . . . . . . 11
8.2. Informative References . . . . . . . . . . . . . . . . . . 12 8.2. Informative References . . . . . . . . . . . . . . . . . 12
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 12 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 13
Appendix B. Document History . . . . . . . . . . . . . . . . . . 12 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13
1. Introduction 1. Introduction
This specification defines a method for computing a hash value This specification defines a method for computing a hash value
(a.k.a. digest) over a JSON Web Key (JWK) [JWK]. It defines which (a.k.a. digest) over a JSON Web Key (JWK) [JWK]. It defines which
fields in a JWK are used in the hash computation, the method of fields in a JWK are used in the hash computation, the method of
creating a canonical form for those fields, and how to convert the creating a canonical form for those fields, and how to convert the
resulting Unicode string into a byte sequence to be hashed. The resulting Unicode string into a byte sequence to be hashed. The
resulting hash value can be used for identifying or selecting the key resulting hash value can be used for identifying or selecting the key
represented by the JWK that is the subject of the thumbprint, for represented by the JWK that is the subject of the thumbprint, for
skipping to change at page 3, line 49 skipping to change at page 3, line 28
The thumbprint of a JSON Web Key (JWK) is computed as follows: The thumbprint of a JSON Web Key (JWK) is computed as follows:
1. Construct a JSON object [RFC7159] containing only the required 1. Construct a JSON object [RFC7159] containing only the required
members of a JWK representing the key and with no whitespace or members of a JWK representing the key and with no whitespace or
line breaks before or after any syntactic elements and with the line breaks before or after any syntactic elements and with the
required members ordered lexicographically by the Unicode required members ordered lexicographically by the Unicode
[UNICODE] code points of the member names. (This JSON object is [UNICODE] code points of the member names. (This JSON object is
itself a legal JWK representation of the key.) itself a legal JWK representation of the key.)
2. Hash the octets of the UTF-8 representation of this JSON object 2. Hash the octets of the UTF-8 representation of this JSON object
with a cryptographic hash function H. For example, SHA-256 [SHS] with a cryptographic hash function H. For example, SHA-256 [SHS]
might be used as H. See Section 3.4 for a discussion on the might be used as H. See Section 3.4 for a discussion on the
choice of hash function. choice of hash function.
The resulting value is the JWK Thumbprint with H of the JWK. The The resulting value is the JWK Thumbprint with H of the JWK. The
details of this computation are further described in subsequent details of this computation are further described in subsequent
sections. sections.
3.1. Example JWK Thumbprint Computation 3.1. Example JWK Thumbprint Computation
This section demonstrates the JWK Thumbprint computation for the JWK This section demonstrates the JWK Thumbprint computation for the JWK
below (with long lines broken for display purposes only): below (with the long line broken for display purposes only):
{ {
"kty": "RSA", "kty": "RSA",
"n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAt "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAt
VT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn6 VT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn6
4tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FD 4tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FD
W2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n9 W2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n9
1CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINH 1CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINH
aQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw", aQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
"e": "AQAB", "e": "AQAB",
skipping to change at page 4, line 43 skipping to change at page 4, line 38
o "e" o "e"
Therefore, these are the members used in the thumbprint computation. Therefore, these are the members used in the thumbprint computation.
Their lexicographic order, per Section 3.3, is: Their lexicographic order, per Section 3.3, is:
o "e" o "e"
o "kty" o "kty"
o "n" o "n"
Therefore the JSON object constructed as an intermediate step in the Therefore, the JSON object constructed as an intermediate step in the
computation is as follows (with long lines broken for display computation is as follows (with the line broken for display purposes
purposes only): only):
{"e":"AQAB","kty":"RSA","n":"0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2 {"e":"AQAB","kty":"RSA","n":"0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2
aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCi aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCi
FV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65Y FV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65Y
GjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n GjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n
91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_x 91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_x
BniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw"} BniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw"}
The octets of the UTF-8 representation of this JSON object are: The octets of the UTF-8 representation of this JSON object are:
skipping to change at page 5, line 51 skipping to change at page 6, line 11
(which might, for instance, be used as a "kid" (key ID) value) is: (which might, for instance, be used as a "kid" (key ID) value) is:
NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs
3.2. JWK Members Used in the Thumbprint Computation 3.2. JWK Members Used in the Thumbprint Computation
Only the required members of a key's representation are used when Only the required members of a key's representation are used when
computing its JWK Thumbprint value. As defined in "JSON Web Key computing its JWK Thumbprint value. As defined in "JSON Web Key
(JWK)" [JWK] and "JSON Web Algorithms (JWA)" [JWA], the required (JWK)" [JWK] and "JSON Web Algorithms (JWA)" [JWA], the required
members for an elliptic curve public key for the curves specified in members for an elliptic curve public key for the curves specified in
Section 6.2.1.1 of [JWK], in lexicographic order, are: Section 6.2.1.1 of RFC 7518 [JWA], in lexicographic order, are:
o "crv" o "crv"
o "kty" o "kty"
o "x" o "x"
o "y" o "y"
the required members for an RSA public key, in lexicographic order, The required members for an RSA public key, in lexicographic order,
are: are:
o "e" o "e"
o "kty" o "kty"
o "n" o "n"
and the required members for a symmetric key, in lexicographic order, The required members for a symmetric key, in lexicographic order,
are: are:
o "k" o "k"
o "kty" o "kty"
As other "kty" (key type) values are defined, the specifications As other "kty" (key type) values are defined, the specifications
defining them should be similarly consulted to determine which defining them should be similarly consulted to determine which
members, in addition to "kty", are required. members, in addition to "kty", are required.
3.2.1. JWK Thumbprint of a Private Key 3.2.1. JWK Thumbprint of a Private Key
The JWK Thumbprint of a JWK representing a private key is computed as The JWK Thumbprint of a JWK representing a private key is computed as
the JWK Thumbprint of a JWK representing the corresponding public the JWK Thumbprint of a JWK representing the corresponding public
key. This has the intentional benefit that the same JWK Thumbprint key. This has the intentional benefit that the same JWK Thumbprint
value can be computed both by parties using either the public or 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 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 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 if the public or private key is the one being referred to by the JWK
the JWK Thumbprint. Thumbprint.
This specification defines the method of computing JWK Thumbprints of This specification defines the method of computing JWK Thumbprints of
JWKs representing private keys for interoperability reasons -- so JWKs representing private keys for interoperability reasons -- so
that different implementations computing JWK Thumbprints of private that different implementations computing JWK Thumbprints of private
keys will produce the same result. keys will produce the same result.
3.2.2. Why Not Include Optional Members? 3.2.2. Why Not Include Optional Members?
Optional members of JWKs are intentionally not included in the JWK Optional members of JWKs are intentionally not included in the JWK
Thumbprint computation so that their absence or presence in the JWK Thumbprint computation so that their absence or presence in the JWK
does not alter the resulting value. The JWK Thumbprint value is a does not alter the resulting value. The JWK Thumbprint value is a
digest of the members required to represent the key as a JWK -- not digest of the members required to represent the key as a JWK -- not
of additional data that may also accompany the key. of additional data that may also accompany the key.
Optional members are not included so that the JWK Thumbprint refers 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 to a key -- not a key with an associated set of key attributes.
has the benefit that while in different application contexts Different application contexts might or might not include different
different subsets of attributes about the key might or might not be subsets of optional attributes about the key in the JWK. If these
included in the JWK, the JWK Thumbprint of any JWK representing the were included in the calculation of the JWK thumbprint, the values
key remains the same regardless of which optional attributes are would be different for those JWKs, even though the keys are the same.
present. Different kinds of thumbprints could be defined by other The benefit of including only the JWK required members is that the
JWK Thumbprint of any JWK representing the key remains the same,
regardless of any other attributes that are present.
Different kinds of thumbprints could be defined by other
specifications that might include some or all additional JWK members, specifications that might include some or all additional JWK members,
should use cases arise where such different kinds of thumbprints if use cases arise where such different kinds of thumbprints would be
would be useful. See Section 9.1 of [JWK] for notes on some ways to useful. See Section 9.1 of RFC 7517 [JWK] for notes on some ways to
cryptographically bind attributes to a key. cryptographically bind attributes to a key.
3.3. Order and Representation of Members in Hash Input 3.3. Order and Representation of Members in Hash Input
The required members in the input to the hash function are ordered The required members in the input to the hash function are ordered
lexicographically by the Unicode code points of the member names. lexicographically by the Unicode code points of the member names.
Characters in member names and member values MUST be represented Characters in member names and member values MUST be represented
without being escaped. This means that thumbprints of JWKs that without being escaped. This means that thumbprints of JWKs that
require such characters are not defined by this specification. (This require such characters are not defined by this specification. (This
is not expected to limit the applicability of this specification, in is not expected to limit the applicability of this specification, in
practice, as the members of JWK representations are not expected to practice, as the members of JWK representations are not expected to
use any of these characters.) The characters specified as requiring use any of these characters.) The characters specified as requiring
escaping by Section 7 of [RFC7159] are quotation mark, reverse escaping by Section 7 of [RFC7159] are quotation mark, reverse
solidus (a.k.a. backslash), and the control characters U+0000 through solidus (a.k.a. backslash), and the control characters U+0000 through
U+001F. U+001F.
If the JWK key type uses members whose values are themselves JSON If the JWK key type uses members whose values are themselves JSON
objects, the members of those objects MUST likewise be objects, then the members of those objects MUST likewise be
lexicographically ordered. (As of the time of this writing, none are lexicographically ordered. (As of the time of this writing, none are
defined that do.) defined that do.)
If the JWK key type uses members whose values are JSON numbers, if If the JWK key type uses members whose values are JSON numbers, and
the numbers are integers, they MUST be represented as a JSON number if those numbers are integers, then they MUST be represented as a
as defined in Section 6 of [RFC7159] without including a fraction JSON number as defined in Section 6 of [RFC7159] without including a
part or exponent part. For instance, the value "1.024e3" MUST be fraction part or exponent part. For instance, the value "1.024e3"
represented as "1024". This means that thumbprints of JWKs that use MUST be represented as "1024". This means that thumbprints of JWKs
numbers that are not integers are not defined by this specification. using numbers that are not integers are not defined by this
Also, as noted in "The I-JSON Message Format" [RFC7493], specification. Also, as noted in "The I-JSON Message Format"
implementations cannot expect an integer whose absolute value is [RFC7493], implementations cannot expect an integer whose absolute
greater than 9007199254740991 (i.e., that is outside the range value is greater than 9007199254740991 (i.e., that is outside the
[-(2**53)+1, (2**53)-1]) to be treated as an exact value. (As of the range [-(2**53)+1, (2**53)-1]) to be treated as an exact value. (As
time of this writing, none are defined that use JSON numbers.) of the time of this writing, none are defined that use JSON numbers.)
See Section 4 for a discussion of further practical considerations See Section 4 for a discussion of further practical considerations
pertaining to the representation of the hash input. pertaining to the representation of the hash input.
3.4. Selection of Hash Function 3.4. Selection of Hash Function
A specific hash function must be chosen by an application to compute A specific hash function must be chosen by an application to compute
the hash value of the hash input. For example, SHA-256 [SHS] might the hash value of the hash input. For example, SHA-256 [SHS] might
be used as the hash function by the application. While SHA-256 is a be used as the hash function by the application. While SHA-256 is a
good default choice at the time of this writing, the hash function of good default choice at the time of this writing, the hash function of
skipping to change at page 8, line 29 skipping to change at page 8, line 39
However, in some cases, multiple parties will be reproducing the JWK However, in some cases, multiple parties will be reproducing the JWK
Thumbprint calculation and comparing the results. In these cases, Thumbprint calculation and comparing the results. In these cases,
the parties will need to know which hash function was used and use the parties will need to know which hash function was used and use
the same one. the same one.
3.5. JWK Thumbprints of Keys Not in JWK Format 3.5. JWK Thumbprints of Keys Not in JWK Format
Note that a key need not be in JWK format to create a JWK Thumbprint 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 of it. The only prerequisites are that the JWK representation of the
key be defined and the party creating the JWK Thumbprint is in key be defined and the party creating the JWK Thumbprint be in
possession of the necessary key material. These are sufficient to possession of the necessary key material. These are sufficient to
create the hash input from the JWK representation of the key, as create the hash input from the JWK representation of the key, as
described in Section 3.3. described in Section 3.3.
4. Practical JSON and Unicode Considerations 4. Practical JSON and Unicode Considerations
Implementations will almost certainly use functionality provided by Implementations will almost certainly use functionality provided by
the platform's JSON support when parsing the JWK and emitting the the platform's JSON support when parsing the JWK and emitting the
JSON object used as the hash input. As a practical consideration, JSON object used as the hash input. As a practical consideration,
future JWK member names and values should be avoided for which future JWK member names and values should be avoided for which
different platforms or libraries might emit different different platforms or libraries might emit different
representations. As of the time of this writing, currently all representations. As of the time of this writing, all defined JWK
defined JWK member names and values use only printable ASCII member names and values use only printable ASCII characters, which
characters, which should not exhibit this problem. Note however, should not exhibit this problem. Note however, that JSON.stringify()
that JSON.stringify() cannot be counted on to lexicographically sort cannot be counted on to lexicographically sort the members of JSON
the members of JSON objects, so while it may be able to be used to objects, so while it could be used to emit some kinds of member
emit some kinds of member values, different code is likely to be values, different code is likely to be needed to perform the sorting.
needed to perform the sorting.
In particular, while the operation of lexicographically ordering In particular, while the operation of lexicographically ordering
member names by their Unicode code points is well defined, different member names by their Unicode code points is well defined, different
platform sort functions may produce different results for non-ASCII platform sort functions may produce different results for non-ASCII
characters, in ways that may not be obvious to developers. If characters, in ways that may not be obvious to developers. If
writers of future specifications defining new JWK key type values writers of future specifications defining new JWK key type values
choose to restrict themselves to printable ASCII member names and choose to restrict themselves to printable ASCII member names and
values (which are for machine and not human consumption anyway), some values (which are for machine and not human consumption anyway), some
future interoperability problems might be avoided. future interoperability problems might be avoided.
skipping to change at page 10, line 7 skipping to change at page 10, line 12
defined in Section 4.1.2.7 of [RFC5280], than to applications that defined in Section 4.1.2.7 of [RFC5280], than to applications that
use digests of complete certificate values, as the "x5t" (X.509 use digests of complete certificate values, as the "x5t" (X.509
certificate SHA-1 thumbprint) [JWS] value defined for X.509 certificate SHA-1 thumbprint) [JWS] value defined for X.509
certificate objects does. While logically equivalent to a digest of certificate objects does. While logically equivalent to a digest of
the SPKI representation of the key, a JWK Thumbprint is computed over the SPKI representation of the key, a JWK Thumbprint is computed over
a JSON representation of that key, rather than over an ASN.1 a JSON representation of that key, rather than over an ASN.1
representation of it. representation of it.
6. IANA Considerations 6. IANA Considerations
This specification adds to the instructions to the Designated Experts This specification adds to the instructions for the Designated
for the following IANA registries, all of which are in the JSON Experts of the following IANA registries, all of which are in the
Object Signing and Encryption (JOSE) protocol category [IANA.JOSE]: "JSON Object Signing and Encryption (JOSE)" registry [IANA.JOSE]:
o JSON Web Key Types o JSON Web Key Types
o JSON Web Key Elliptic Curve o JSON Web Key Elliptic Curve
o JSON Web Key Parameters o JSON Web Key Parameters
IANA, please add a link to this specification in the Reference IANA has added a link to this specification in the Reference sections
sections of these registries after the existing links to RFC 7518 for of these registries.
the first two and the link to RFC 7517 for the last.
Because of the practical JSON and Unicode considerations described in For these registries, because of the practical JSON and Unicode
Section 4, for these registries, the Designated Experts must either considerations described in Section 4, the Designated Experts must
require that JWK member names and values being registered use only either:
printable ASCII characters excluding double quote ('"') and
(a) 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, backslash ('\') (the Unicode characters with code points U+0021,
U+0023 through U+005B, and U+005D through U+007E) or if new JWK U+0023 through U+005B, and U+005D through U+007E), or
members or values are defined that use other code points, require
that their definitions specify the exact Unicode code point sequences (b) if new JWK members or values are defined that use other code
used to represent them. Furthermore, proposed registrations must not points, require that their definitions specify the exact Unicode code
be accepted that use Unicode code points that can only be represented point sequences used to represent them. Furthermore, proposed
in JSON strings as escaped characters. registrations that use Unicode code points that can only be
represented in JSON strings as escaped characters must not be
accepted.
7. Security Considerations 7. Security Considerations
The JSON Security Considerations and Unicode Comparison Security The JSON Security Considerations and Unicode Comparison Security
Considerations described in Sections 10.2 and 10.3 of "JSON Web Considerations described in Sections 10.12 and 10.13 of "JSON Web
Signature (JWS)" [JWS] also apply to this specification. Signature (JWS)" [JWS] also apply to this specification.
Also, as described in Section 4, some implementations may produce Also, as described in Section 4, some implementations may produce
incorrect results if esoteric or escaped characters are used in the incorrect results if esoteric or escaped characters are used in the
member names. The security implications of this appear to be limited member names. The security implications of this appear to be limited
for JWK Thumbprints of public keys, since while it may result in for JWK Thumbprints of public keys, because while it may result in
implementations failing to identify the intended key, it should not implementations failing to identify the intended key, it should not
leak information, since the information in a public key is already leak information. The information in a public key is already public
public in nature, by definition. in nature, by definition.
A hash of a symmetric key has the potential to leak information about 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 the key value. Thus, the JWK Thumbprint of a symmetric key should
typically be concealed from parties not in possession of the typically be concealed from parties not in possession of the
symmetric key, unless in the application context, the cryptographic symmetric key, unless in the application context, the cryptographic
hash used, such as SHA-256, is known to provide sufficient protection hash used, such as SHA-256, is known to provide sufficient protection
against disclosure of the key value. against disclosure of the key value.
A JWK Thumbprint will only uniquely identify a particular key if a A JWK Thumbprint will only uniquely identify a particular key if a
single unambiguous JWK representation for that key is defined and single unambiguous JWK representation for that key is defined and
used when computing the JWK Thumbprint. (Such representations are used when computing the JWK Thumbprint. (Such representations are
defined for all the key types defined in "JSON Web Algorithms (JWA)" defined for all the key types defined in "JSON Web Algorithms (JWA)"
[JWA].) For example, if an RSA key were to use "e":"AAEAAQ" [JWA].) For example, if an RSA key were to use "e":"AAEAAQ"
(representing [0, 1, 0, 1]) rather than the specified correct (representing [0, 1, 0, 1]) rather than the specified correct
representation of "e":"AQAB" (representing [1, 0, 1]), a different representation of "e":"AQAB" (representing [1, 0, 1]), then a
thumbprint value would be produced for what could be effectively the different thumbprint value would be produced for what could be
same key, at least for implementations that are lax in validating the effectively the same key, at least for implementations that are lax
JWK values that they accept. Thus, JWK Thumbprint values can only be in validating the JWK values that they accept. Thus, JWK Thumbprint
relied upon to be unique for a given key if the implementation also values can only be relied upon to be unique for a given key if the
validates that the correct representation of the key is used. 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 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 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 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 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 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 different key. Thus, while thumbprint values are valuable for
identifying legitimate keys, comparing thumbprint values is not a identifying legitimate keys, comparing thumbprint values is not a
reliable means of excluding (blacklisting) the use of particular keys reliable means of excluding (blacklisting) the use of particular keys
(or transformations thereof). (or transformations thereof).
8. References 8. References
8.1. Normative References 8.1. Normative References
[IANA.JOSE] [IANA.JOSE] IANA, "JSON Object Signing and Encryption (JOSE)",
IANA, "JSON Object Signing and Encryption (JOSE)", <http://www.iana.org/assignments/jose>.
<http://www.iana.org/assignments/jose>.
[JWA] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, [JWA] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,
May 2015, <http://www.rfc-editor.org/info/rfc7518>. DOI 10.17487/RFC7518, May 2015,
<http://www.rfc-editor.org/info/rfc7518>.
[JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517, May 2015, [JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517,
<http://www.rfc-editor.org/info/rfc7517>. DOI 10.17487/RFC7517, May 2015,
<http://www.rfc-editor.org/info/rfc7517>.
[JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, May 2015, Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
<http://www.rfc-editor.org/info/rfc7515>. 2015, <http://www.rfc-editor.org/info/rfc7515>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON)
Interchange Format", RFC 7159, March 2014. Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159,
March 2014, <http://www.rfc-editor.org/info/rfc7159>.
[SHS] National Institute of Standards and Technology, "Secure [SHS] National Institute of Standards and Technology, "Secure
Hash Standard (SHS)", FIPS PUB 180-4, March 2012, <http:// Hash Standard (SHS)", FIPS PUB 180-4, March 2012,
csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf>. <http://csrc.nist.gov/publications/fips/fips180-4/
fips-180-4.pdf>.
[UNICODE] The Unicode Consortium, "The Unicode Standard", [UNICODE] The Unicode Consortium, "The Unicode Standard",
<http://www.unicode.org/versions/latest/>. <http://www.unicode.org/versions/latest/>.
8.2. Informative References 8.2. Informative References
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List Infrastructure Certificate and Certificate Revocation
(CRL) Profile", RFC 5280, May 2008. List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May
2008, <http://www.rfc-editor.org/info/rfc5280>.
[RFC7493] Bray, T., "The I-JSON Message Format", RFC 7493, [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493,
March 2015. DOI 10.17487/RFC7493, March 2015,
<http://www.rfc-editor.org/info/rfc7493>.
Appendix A. Acknowledgements Acknowledgements
James Manger and John Bradley participated in discussions that led to James Manger and John Bradley participated in discussions that led to
the creation of this specification. Thanks also to Joel Halpern, the creation of this specification. Thanks also to Joel Halpern,
Barry Leiba, Adam Montville, Kathleen Moriarty, and Jim Schaad for Barry Leiba, Adam Montville, Kathleen Moriarty, and Jim Schaad for
their reviews of this specification. their reviews of this specification.
Appendix B. Document History
[[ to be removed by the RFC editor before publication as an RFC ]]
-08
o Added IANA instructions in response to a comment by Barry Leiba.
-07
o Addressed Gen-ART review comment by Joel Halpern.
-06
o Addressed comments in SecDir review by Adam Montville.
-05
o Addressed comments in Kathleen Moriarty's AD review.
-04
o Addressed additional review comments by Jim Schaad, which resulted
in several clarifications and some corrections to the case of RFC
2119 keywords.
-03
o Addressed review comments by James Manger and Jim Schaad,
including adding a section on the relationship to digests of X.509
values.
-02
o 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.
o Added security considerations about the measures needed to ensure
that a unique JWK Thumbprint value is produced for a key.
o Added text saying that the base64url encoded JWK Thumbprint value
could be used as a "kid" (key ID) value.
o Broke a sentence up that used to be way too long.
-01
o 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.
o Added Nat Sakimura as an editor.
-00
o Created draft-ietf-jose-jwk-thumbprint-00 from
draft-jones-jose-jwk-thumbprint-01 with no normative changes.
Authors' Addresses Authors' Addresses
Michael B. Jones Michael B. Jones
Microsoft Microsoft
Email: mbj@microsoft.com Email: mbj@microsoft.com
URI: http://self-issued.info/ URI: http://self-issued.info/
Nat Sakimura Nat Sakimura
Nomura Research Institute Nomura Research Institute
Email: n-sakimura@nri.co.jp Email: n-sakimura@nri.co.jp
URI: http://nat.sakimura.org/ URI: http://nat.sakimura.org/
 End of changes. 42 change blocks. 
191 lines changed or deleted 143 lines changed or added

This html diff was produced by rfcdiff 1.42. The latest version is available from http://tools.ietf.org/tools/rfcdiff/