draft-ietf-jose-jwk-thumbprint-03.txt   draft-ietf-jose-jwk-thumbprint-04.txt 
JOSE Working Group M. Jones JOSE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track N. Sakimura Intended status: Standards Track N. Sakimura
Expires: August 30, 2015 NRI Expires: September 4, 2015 NRI
February 26, 2015 March 3, 2015
JSON Web Key (JWK) Thumbprint JSON Web Key (JWK) Thumbprint
draft-ietf-jose-jwk-thumbprint-03 draft-ietf-jose-jwk-thumbprint-04
Abstract Abstract
This specification defines a means of computing a thumbprint value This specification defines a means of computing a thumbprint value
(a.k.a. digest) of a key represented as a JSON Web Key (JWK). (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.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on August 30, 2015. This Internet-Draft will expire on September 4, 2015.
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
skipping to change at page 2, line 18 skipping to change at page 2, line 18
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3
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 . . . . . . 5
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? . . . . . . . . . . 6
3.3. Order and Representation of Members in Hash Input . . . . 7 3.3. Order and Representation of Members in Hash Input . . . . 7
3.4. JWK Thumbprints of Keys Not in JWK Format . . . . . . . . 7 3.4. JWK Thumbprints of Keys Not in JWK Format . . . . . . . . 7
4. Practical JSON and Unicode Considerations . . . . . . . . . . 8 4. Practical JSON and Unicode Considerations . . . . . . . . . . 8
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 5. Relationship to Digests of X.509 Values . . . . . . . . . . . 9
6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
7. Relationship to Digests of X.509 Values . . . . . . . . . . . 10 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10
8.1. Normative References . . . . . . . . . . . . . . . . . . . 10 8.1. Normative References . . . . . . . . . . . . . . . . . . . 10
8.2. Informative References . . . . . . . . . . . . . . . . . . 10 8.2. Informative References . . . . . . . . . . . . . . . . . . 11
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11
Appendix B. Document History . . . . . . . . . . . . . . . . . . 11 Appendix B. Document History . . . . . . . . . . . . . . . . . . 11
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12
1. Introduction 1. Introduction
This specification defines a means of computing a thumbprint value 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 (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 value can be used for identifying or selecting the key that is the
subject of the thumbprint, for instance, by using the base64url subject of the thumbprint, for instance, by using the base64url
skipping to change at page 3, line 36 skipping to change at page 3, line 36
This term is defined by this specification: This term is defined by this specification:
JWK Thumbprint JWK Thumbprint
The digest value for a key that is the subject of this The digest value for a key that is the subject of this
specification. specification.
3. JSON Web Key (JWK) Thumbprint 3. JSON Web Key (JWK) Thumbprint
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 white space or members of a JWK representing the key and with no white space 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. might be used as H.
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.
skipping to change at page 4, line 24 skipping to change at page 4, line 24
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",
"alg": "RS256", "alg": "RS256",
"kid": "2011-04-29" "kid": "2011-04-29"
} }
As defined in JSON Web Key (JWK) [JWK] and JSON Web Algorithms (JWA) As defined in JSON Web Key (JWK) [JWK] and JSON Web Algorithms (JWA)
[JWA], the REQUIRED members of an RSA public key are: [JWA], the required members of an RSA public key are:
o "kty" o "kty"
o "n" o "n"
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 (see more about this in Section 3.3) is: Their lexicographic order (see more about this in Section 3.3) is:
o "e" o "e"
skipping to change at page 5, line 41 skipping to change at page 5, line 41
225, 111, 251, 158, 133, 151, 21, 144, 31, 30, 76, 89, 177, 17, 130, 225, 111, 251, 158, 133, 151, 21, 144, 31, 30, 76, 89, 177, 17, 130,
245, 123] 245, 123]
The base64url encoding [JWS] of this JWK SHA-256 Thumbprint value The base64url encoding [JWS] of this JWK SHA-256 Thumbprint value
(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 (JWK) computing its JWK Thumbprint value. As defined in JSON Web Key (JWK)
[JWK] and JSON Web Algorithms (JWA) [JWA], the REQUIRED members of an [JWK] and JSON Web Algorithms (JWA) [JWA], the required members of an
elliptic curve public key for the curves specified in Section 6.2.1.1 elliptic curve public key for the curves specified in Section 6.2.1.1
of [JWK], in lexicographic order, are: of [JWK], in lexicographic order, are:
o "crv" o "crv"
o "kty" o "kty"
o "x" o "x"
o "y" o "y"
the REQUIRED members of an RSA public key, in lexicographic order, the required members of 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 of a symmetric key, in lexicographic order, and the required members of a symmetric key, in lexicographic order,
are: are:
o "k" o "k"
o "kty" o "kty"
As other key type values are defined, the specifications defining As other key type values are defined, the specifications defining
them should be similarly consulted to determine which members, in them should be similarly consulted to determine which members, in
addition to "kty", are REQUIRED. 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 private key is computed as the JWK Thumbprint The JWK Thumbprint of a private key is computed as the JWK Thumbprint
of the corresponding public key. This has the intentional benefit of the corresponding public key. This has the intentional benefit
that the same JWK Thumbprint value can be computed both by parties that the same JWK Thumbprint value can be computed both by parties
using either the public or private key. The JWK Thumbprint can then 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 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 can be used to determine whether the public or the private key is the
one being referred to by the JWK Thumbprint. one being referred to by the JWK Thumbprint.
This specification defines the method of computing JWK Thumbprints of This specification defines the method of computing JWK Thumbprints of
private keys for interoperability reasons -- so that different private keys for interoperability reasons -- so that different
implementations computing JWK Thumbprints of private keys will implementations computing JWK Thumbprints of private keys will
produce the same result. 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
doesn't 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 key value itself -- not of additional data that may digest of the key value itself -- not of additional data that may
also accompany the key. 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. This
has the benefit that while in different application contexts has the benefit that while in different application contexts
different subsets of attributes about the key might or might not be 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 included in the JWK, the JWK Thumbprint of the key remains the same
regardless of which optional attributes are present. Different kinds regardless of which optional attributes are present. Different kinds
of thumbprints could be defined by other specifications that might of thumbprints could be defined by other specifications that might
skipping to change at page 7, line 27 skipping to change at page 7, line 27
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 (as of the time of this writing, none are defined that do), objects (as of the time of this writing, none are defined that do),
the members of those objects must likewise be lexicographically the members of those objects MUST likewise be lexicographically
ordered. ordered.
If the JWK key type uses members whose values are JSON numbers (as of 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 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 are integers, they MUST be represented as a JSON number as defined in
Section 6 of [RFC7159] without including a fraction part or exponent Section 6 of [RFC7159] without including a fraction part or exponent
part. For instance, the value "1.024e3" MUST be represented as part. For instance, the value "1.024e3" MUST be represented as
"1024". This means that thumbprints of JWKs that use numbers that "1024". This means that thumbprints of JWKs that use numbers that
are not integers are not defined by this specification. Also, as are not integers are not defined by this specification. Also, as
noted in The I-JSON Message Format [I-D.ietf-json-i-json], noted in The I-JSON Message Format [I-D.ietf-json-i-json],
skipping to change at page 8, line 35 skipping to change at page 8, line 35
choose to restrict themselves to ASCII member names (which are for choose to restrict themselves to ASCII member names (which are for
machine and not human consumption anyway), some future machine and not human consumption anyway), some future
interoperability problems might be avoided. interoperability problems might be avoided.
However, if new JWK members are defined that use non-ASCII member However, if new JWK members are defined that use non-ASCII member
names, their definitions should specify the exact Unicode code point names, their definitions should specify the exact Unicode code point
sequences used to represent them, particularly in cases in which sequences used to represent them, particularly in cases in which
Unicode normalization could result in the transformation of one set Unicode normalization could result in the transformation of one set
of code points into another under any circumstances. of code points into another under any circumstances.
Use of escaped characters in the input JWK representation SHOULD be Use of escaped characters in JWKs for which JWK Thumbprints will be
avoided. computed should be avoided. (Use of escaped characters in the hash
input JWKs derived from these original JWKs is prohibited.)
While there is a natural representation to use for numeric values While there is a natural representation to use for numeric values
that are integers, this specification doesn't attempt to define a that are integers, this specification does not attempt to define a
standard representation for numbers that are not integers or that standard representation for numbers that are not integers or that
contain an exponent component. This is not expected to be a problem contain an exponent component. This is not expected to be a problem
in practice, as the required members of JWK representations are not in practice, as the required members of JWK representations are not
expected to use numbers that are not integers. expected to use numbers that are not integers.
Use of number representations containing fraction or exponent parts Use of number representations containing fraction or exponent parts
in the input JWK representation SHOULD be avoided. in JWKs for which JWK Thumbprints will be computed should be avoided.
All of these practical considerations are really an instance of Jon All of these practical considerations are really an instance of Jon
Postel's principle: "Be liberal in what you accept, and conservative Postel's principle: "Be liberal in what you accept, and conservative
in what you send." in what you send."
5. IANA Considerations 5. Relationship to Digests of X.509 Values
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 [RFC5280], than to applications that
use digests of complete certificate values, as 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 specification makes no requests of IANA. This specification makes no requests of IANA.
6. 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.2 and 10.3 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, since 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
skipping to change at page 10, line 5 skipping to change at page 10, line 24
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).
7. Relationship to Digests of X.509 Values
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 [RFC5280], than to applications that
use digests of complete certificate values, as 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.
8. References 8. References
8.1. Normative References 8.1. Normative References
[JWA] Jones, M., "JSON Web Algorithms (JWA)", [JWA] Jones, M., "JSON Web Algorithms (JWA)",
draft-ietf-jose-json-web-algorithms (work in progress), draft-ietf-jose-json-web-algorithms (work in progress),
January 2015. January 2015.
[JWK] Jones, M., "JSON Web Key (JWK)", [JWK] Jones, M., "JSON Web Key (JWK)",
draft-ietf-jose-json-web-key (work in progress), draft-ietf-jose-json-web-key (work in progress),
skipping to change at page 11, line 21 skipping to change at page 11, line 27
Appendix A. Acknowledgements Appendix A. 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. Jim Schaad also contributed to the creation of this specification. Jim Schaad also contributed to
this specification. this specification.
Appendix B. Document History Appendix B. Document History
[[ to be removed by the RFC editor before publication as an RFC ]] [[ to be removed by the RFC editor before publication as an RFC ]]
-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 -03
o Addressed review comments by James Manger and Jim Schaad, o Addressed review comments by James Manger and Jim Schaad,
including adding a section on the relationship to digests of X.509 including adding a section on the relationship to digests of X.509
values. values.
-02 -02
o No longer register the new JSON Web Signature (JWS) and JSON Web o No longer register the new JSON Web Signature (JWS) and JSON Web
Encryption (JWE) Header Parameters and the new JSON Web Key (JWK) Encryption (JWE) Header Parameters and the new JSON Web Key (JWK)
 End of changes. 23 change blocks. 
39 lines changed or deleted 48 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/