idnits 2.17.1 draft-ietf-oauth-jwk-thumbprint-uri-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 18 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 16, 2022) is 711 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group M. Jones 3 Internet-Draft K. Yasuda 4 Intended status: Standards Track Microsoft 5 Expires: November 17, 2022 May 16, 2022 7 JWK Thumbprint URI 8 draft-ietf-oauth-jwk-thumbprint-uri-02 10 Abstract 12 This specification registers a kind of URI that represents a JSON Web 13 Key (JWK) Thumbprint value. JWK Thumbprints are defined in RFC 7638. 14 This enables JWK Thumbprints to be used, for instance, as key 15 identifiers in contexts requiring URIs. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on November 17, 2022. 34 Copyright Notice 36 Copyright (c) 2022 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 2. Requirements Notation and Conventions . . . . . . . . . . . . 2 53 3. JWK Thumbprint URI . . . . . . . . . . . . . . . . . . . . . 3 54 4. Hash Algorithms Identifier . . . . . . . . . . . . . . . . . 3 55 5. Mandatory to Implement Hash Algorithm . . . . . . . . . . . . 3 56 6. Example JWK Thumbprint URI . . . . . . . . . . . . . . . . . 3 57 7. Security Considerations . . . . . . . . . . . . . . . . . . . 3 58 7.1. Multiple Public Keys per Private Key . . . . . . . . . . 3 59 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 60 8.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 4 61 8.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 4 62 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 9.1. Normative References . . . . . . . . . . . . . . . . . . 4 64 9.2. Informative References . . . . . . . . . . . . . . . . . 5 65 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 5 66 Appendix B. Document History . . . . . . . . . . . . . . . . . . 6 67 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 6 69 1. Introduction 71 A JSON Web Key (JWK) Thumbprint [RFC7638] is a URL-safe 72 representation of a hash value over a JSON Web Key (JWK) [RFC7517]. 73 This specification defines a URI prefix indicating that the portion 74 of the URI following the prefix is a JWK Thumbprint. This enables 75 JWK Thumbprints to be communicated in contexts requiring URIs, 76 including in specific JSON Web Token (JWT) [RFC7519] claims. 78 JWK Thumbprints URIs are being used in the [SIOPv2] specification as 79 one kind of subject identifier in a context requiring that the 80 identifier be a URI. In this case, the subject identifier is derived 81 from a public key represented as a JWK. Expressing the identifier as 82 JWK Thumbprint URI enables this kind of identifier to be 83 differentiated from other kinds of identifiers that are also URIs, 84 such as Decentralized Identifiers (DIDs) [DID-Core]. 86 2. Requirements Notation and Conventions 88 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 89 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 90 "OPTIONAL" in this document are to be interpreted as described in BCP 91 14 [RFC2119] [RFC8174] when, and only when, they appear in all 92 capitals, as shown here. 94 3. JWK Thumbprint URI 96 The following URI prefix is defined to indicate that the portion of 97 the URI following the prefix is a JWK Thumbprint: 99 o "urn:ietf:params:oauth:jwk-thumbprint" 101 To make it explicit in a URI which hash algorithm is used, the prefix 102 is followed by a hash algorithm identifier and a JWK Thumbprint 103 value, each separated by a colon character to form a URI representing 104 a JWK Thumbprint. 106 4. Hash Algorithms Identifier 108 Hash algorithm identifiers used in JWK Thumbprint URIs MUST be values 109 from the "Hash Name String" column in the IANA "Named Information 110 Hash Algorithm" registry [IANA.Hash.Algorithms]. JWK Thumbprint URIs 111 with hash algorithm identifiers not found in this registry are 112 considered invalid and applications will need to detect and handle 113 this error, should it occur. 115 5. Mandatory to Implement Hash Algorithm 117 To promote interoperability among implementations, the SHA-256 hash 118 algorithm is mandatory to implement. 120 6. Example JWK Thumbprint URI 122 Section 3.1 of [RFC7638] contains the following example JWK 123 Thumbprint value: 125 NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs 127 A complete JWK Thumbprint URI using the above JWK Thumbprint and 128 SHA-256 hash algorithm is: 130 urn:ietf:params:oauth:jwk-thumbprint:sha-256:NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs 132 7. Security Considerations 134 The security considerations of [RFC7638] also apply when using this 135 specification. 137 7.1. Multiple Public Keys per Private Key 139 There are cryptographic algorithms for which multiple public keys 140 correspond to the same private key. This is described in the 141 security considerations of [RFC7748] as follows: 143 Designers using these curves should be aware that for each public 144 key, there are several publicly computable public keys that are 145 equivalent to it, i.e., they produce the same shared secrets. 146 Thus using a public key as an identifier and knowledge of a shared 147 secret as proof of ownership (without including the public keys in 148 the key derivation) might lead to subtle vulnerabilities. 150 This consideration for public keys as identifiers equally applies to 151 JWK Thumbprint URIs used as identifiers. A recommended way to ensure 152 that the JWK Thumbprint URI corresponds to the actual public key used 153 is to sign a message containing the correct public key with the 154 private key. This signed message could also contain the JWK 155 Thumbprint URI (although, by definition, it could also be computed 156 directly from the public key). 158 8. IANA Considerations 160 8.1. OAuth URI Registration 162 This specification registers the following value in the IANA "OAuth 163 URI" registry [IANA.OAuth.Parameters] established by [RFC6755]. 165 8.1.1. Registry Contents 167 o URN: urn:ietf:params:oauth:jwk-thumbprint 168 o Common Name: JWK Thumbprint URI 169 o Change controller: IESG 170 o Specification Document: [[ this specification ]] 172 9. References 174 9.1. Normative References 176 [IANA.OAuth.Parameters] 177 IANA, "OAuth Parameters", 178 . 180 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 181 Requirement Levels", BCP 14, RFC 2119, 182 DOI 10.17487/RFC2119, March 1997, 183 . 185 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) 186 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 187 2015, . 189 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 190 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 191 May 2017, . 193 9.2. Informative References 195 [DID-Core] 196 Sporny, M., Guy, A., Sabadello, M., and D. Reed, 197 "Decentralized Identifiers (DIDs) v1.0", Aug 2021, 198 . 200 [IANA.Hash.Algorithms] 201 IANA, "Named Information Hash Algorithm Registry", 202 . 205 [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace 206 for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, 207 . 209 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 210 DOI 10.17487/RFC7517, May 2015, 211 . 213 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 214 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 215 . 217 [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 218 for Security", RFC 7748, DOI 10.17487/RFC7748, January 219 2016, . 221 [SIOPv2] Yasuda, K. and M. B. Jones, "Self-Issued OpenID Provider 222 v2", December 2021, . 225 Appendix A. Acknowledgements 227 Use cases for this specification were developed in the OpenID Connect 228 Working Group of the OpenID Foundation. Specifically, it is being 229 used a key identifier in the [SIOPv2] specification. 231 The following individuals also contributed to the creation of this 232 specification: John Bradley, Scott Bradner, Brian Campbell, Roman 233 Danyliw, Vladimir Dzhuvinov, Adam Lemmon, Neil Madden, James Manger, 234 Aaron Parecki, Gonzalo Salgueiro, Rifaat Shekh-Yusef, Robert Sparks, 235 and David Waite. 237 Appendix B. Document History 239 [[ to be removed by the RFC Editor before publication as an RFC ]] 241 -02 243 o Addressed IETF last call comments by clarifying the requirement to 244 use registered hash algorithm identifiers. 246 -01 248 o Added security considerations about multiple public keys 249 coresponding to the same private key. 250 o Added hash algorithm identifier after the JWK thumbprint URI 251 prefix to make it explicit in a URI which hash algorithm is used. 252 o Added reference to a registry for hash algorithm identifiers. 253 o Added SHA-256 as a mandatory to implement hash algorithm to 254 promote interoperability. 256 -00 258 o Created initial working group draft from draft-jones-oauth-jwk- 259 thumbprint-uri-01. 261 Authors' Addresses 263 Michael B. Jones 264 Microsoft 266 Email: mbj@microsoft.com 267 URI: https://self-issued.info/ 269 Kristina Yasuda 270 Microsoft 272 Email: kryasuda@microsoft.com 273 URI: https://twitter.com/kristinayasuda