draft-ietf-jose-jwk-thumbprint-02.txt   draft-ietf-jose-jwk-thumbprint-03.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 23, 2015 NRI Expires: August 30, 2015 NRI
February 19, 2015 February 26, 2015
JSON Web Key (JWK) Thumbprint JSON Web Key (JWK) Thumbprint
draft-ietf-jose-jwk-thumbprint-02 draft-ietf-jose-jwk-thumbprint-03
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 JSON Web Key (JWK) objects analogous to the "x5t" (a.k.a. digest) of a key represented as a JSON Web Key (JWK).
(X.509 Certificate SHA-1 Thumbprint) value defined for X.509
certificate objects.
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 23, 2015. This Internet-Draft will expire on August 30, 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 20 skipping to change at page 2, line 20
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. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9
7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 7. Relationship to Digests of X.509 Values . . . . . . . . . . . 10
7.1. Normative References . . . . . . . . . . . . . . . . . . . 9 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10
7.2. Informative References . . . . . . . . . . . . . . . . . . 10 8.1. Normative References . . . . . . . . . . . . . . . . . . . 10
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10 8.2. Informative References . . . . . . . . . . . . . . . . . . 10
Appendix B. Document History . . . . . . . . . . . . . . . . . . 10 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11 Appendix B. Document History . . . . . . . . . . . . . . . . . . 11
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 JSON Web Key (JWK) [JWK] objects analogous to the (a.k.a. digest) of a key represented as a JSON Web Key (JWK). This
"x5t" (X.509 Certificate SHA-1 Thumbprint) value defined for X.509 value can be used for identifying or selecting the key that is the
certificate objects. This value can be used for identifying or subject of the thumbprint, for instance, by using the base64url
selecting the key that is the subject of the thumbprint, for encoded JWK Thumbprint value as a "kid" (key ID) value.
instance, by using the base64url encoded JWK Thumbprint value as a
"kid" (key ID) value.
1.1. Notational Conventions 1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in Key "OPTIONAL" in this document are to be interpreted as described in Key
words for use in RFCs to Indicate Requirement Levels [RFC2119]. words for use in RFCs to Indicate Requirement Levels [RFC2119].
2. Terminology 2. Terminology
This specification uses the same terminology as the JSON Web Key This specification uses the same terminology as the JSON Web Key
(JWK) [JWK], JSON Web Signature (JWS) [JWS], JSON Web Encryption (JWK) [JWK], JSON Web Signature (JWS) [JWS], and JSON Web Algorithms
(JWE) [JWE], and JSON Web Algorithms (JWA) [JWA] specifications. (JWA) [JWA] specifications.
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:
skipping to change at page 6, line 42 skipping to change at page 6, line 40
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 doesn't 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
include some or all additional JWK members, should use cases arise include some or all additional JWK members, should use cases arise
where such different kinds of thumbprints would be useful. See where such different kinds of thumbprints would be useful. See
Section 9.1 of [JWK] for notes on some ways to cryptographically bind Section 9.1 of [JWK] for notes on some ways to cryptographically bind
attributes to a key. 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 REQUIRED members of JWK representations are not practice, as the members of JWK representations are not expected to
expected to use any of these characters.) The characters specified use any of these characters.) The characters specified as requiring
as requiring escaping by Section 7 of [RFC7159] are quotation mark, escaping by Section 7 of [RFC7159] are quotation mark, reverse
reverse solidus (a.k.a. backslash), and the control characters U+0000 solidus (a.k.a. backslash), and the control characters U+0000 through
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
skipping to change at page 8, line 11 skipping to change at page 8, line 9
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 is 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, such as the JavaScript JSON.parse() the platform's JSON support when parsing the JWK and emitting the
JSON.stringify() functions, 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 should be avoided for which different future JWK member names should be avoided for which different
platforms or libraries might emit different representations. As of platforms or libraries might emit different representations. As of
the time of this writing, currently all defined JWK member names use the time of this writing, currently all defined JWK member names use
only printable ASCII characters, which should not exhibit this only printable ASCII characters, which should not exhibit this
problem. Note however, that JSON.stringify() cannot be counted on to problem. Note however, that JSON.stringify() cannot be counted on to
lexicographically sort the members of JSON objects, so while it may lexicographically sort the members of JSON objects, so while it may
be able to be used to emit some kinds of member values, different be able to be used to emit some kinds of member values, different
code is likely to be needed to perform the sorting. code is likely to be 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 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
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 Use of escaped characters in the input JWK representation SHOULD be
avoided. avoided.
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 doesn't 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 the input JWK representation 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. IANA Considerations
skipping to change at page 9, line 43 skipping to change at page 9, line 43
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]), a different
thumbprint value would be produced for what could be effectively the thumbprint value would be produced for what could be effectively the
same key, at least for implementations that are lax in validating 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 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 relied upon to be unique for a given key if the implementation also
validates that the correct representation of the key is used. validates that the correct representation of the key is used.
7. References 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).
7.1. Normative References 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.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.
[JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
draft-ietf-jose-json-web-encryption (work in progress),
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),
January 2015. January 2015.
[JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", draft-ietf-jose-json-web-signature (work Signature (JWS)", draft-ietf-jose-json-web-signature (work
in progress), January 2015. in progress), January 2015.
[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, March 1997.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, March 2014. Interchange Format", RFC 7159, March 2014.
[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. Hash Standard (SHS)", FIPS PUB 180-4, March 2012.
[UNICODE] The Unicode Consortium, "The Unicode Standard", 1991-, [UNICODE] The Unicode Consortium, "The Unicode Standard", 1991-,
<http://www.unicode.org/versions/latest/>. <http://www.unicode.org/versions/latest/>.
7.2. Informative References 8.2. Informative References
[I-D.ietf-json-i-json] [I-D.ietf-json-i-json]
Bray, T., "The I-JSON Message Format", Bray, T., "The I-JSON Message Format",
draft-ietf-json-i-json-06 (work in progress), draft-ietf-json-i-json-06 (work in progress),
January 2015. January 2015.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, May 2008.
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 ]]
-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 -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)
member name "jkt" (JWK SHA-256 Thumbprint) for holding these member name "jkt" (JWK SHA-256 Thumbprint) for holding these
values. values.
o Added security considerations about the measures needed to ensure o Added security considerations about the measures needed to ensure
that a unique JWK Thumbprint value is produced for a key. that a unique JWK Thumbprint value is produced for a key.
 End of changes. 20 change blocks. 
39 lines changed or deleted 72 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/