RFC 9278

JWK Thumbprint URI

📅 published August 2022, from ietf

RFC 9278: JWK Thumbprint URI 🎀

  • RFC number and title: RFC 9278, "JWK Thumbprint URI" 🦋
  • Authors: Michael B. Jones and Kristina Yasuda, both from Microsoft 💜
  • Category: Standards Track 🔥
  • ISSN: 2070-1721
  • Date: August 2022 🌸
  • Obsoletes / Updates: its header doesn't name any RFC it obsoletes or updates ✨

Table of Contents 💅

1.  Introduction
2.  Requirements Notation and Conventions
3.  JWK Thumbprint URI
4.  Hash Algorithms Identifier
5.  Mandatory to Implement Hash Algorithm
6.  Example JWK Thumbprint URI
7.  Security Considerations
  7.1.  Multiple Public Keys per Private Key
8.  IANA Considerations
  8.1.  OAuth URI Registration
    8.1.1.  Registry Contents
9.  References
  9.1.  Normative References
  9.2.  Informative References
Acknowledgements
Authors' Addresses

Abstract 🦋

Okay bestie, this spec registers a kind of URI that represents a JSON Web Key (JWK) Thumbprint value. JWK Thumbprints are defined in RFC 7638 🧚. The payoff is that you can use a JWK Thumbprint as a key identifier in places that need a URI. Iconic. ✨

Status of This Memo 📜

This is an Internet Standards Track document. 🎀

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841 🌈.

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc9278. 💌

Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved. 💖

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, because they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions, and they are provided without warranty as described in the Revised BSD License. 🙈

1. Introduction 🌸

A JSON Web Key (JWK) Thumbprint [RFC7638] is a URL-safe representation of a hash value over a JWK [RFC7517]. This specification defines a URI prefix that tells you the part of the URI after the prefix is a JWK Thumbprint. That means JWK Thumbprints can travel in places that need URIs, including inside certain JSON Web Token (JWT) [RFC7519] claims. 🧚

JWK Thumbprint URIs are already being used in the [SIOPv2] specification as one kind of subject identifier, in a context that requires the identifier to be a URI. In that case, the subject identifier is derived from a public key represented as a JWK. Writing the identifier as a JWK Thumbprint URI lets it stand apart from other URI-shaped identifiers, such as Decentralized Identifiers (DIDs) [DID-Core]. Main character energy. 👑

2. Requirements Notation and Conventions 🎀

Here's the rule. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. Only the all-caps versions count, so the lowercase ones are just regular words. 🫶

3. JWK Thumbprint URI 🦋

The following URI prefix is defined to indicate that the portion of the URI following the prefix is a JWK Thumbprint:

urn:ietf:params:oauth:jwk-thumbprint

To make the hash algorithm explicit in a URI, the prefix is followed by a hash algorithm identifier and then a JWK Thumbprint value. Each of those is separated by a colon character, and together they form a URI that represents a JWK Thumbprint. 🌈

4. Hash Algorithms Identifier 🔥

Hash algorithm identifiers used in JWK Thumbprint URIs MUST be values from the "Hash Name String" column in the IANA "Named Information Hash Algorithm Registry" [IANA.Hash.Algorithms]. JWK Thumbprint URIs with hash algorithm identifiers that aren't found in this registry are not considered valid, and applications will need to detect and handle that error, should it occur. Not a valid URI, no cap. 💀

5. Mandatory to Implement Hash Algorithm 💜

To promote interoperability among implementations, the SHA-256 hash algorithm is mandatory to implement. Everyone agreeing on one hash is so iconic. 🫶

6. Example JWK Thumbprint URI ✨

Section 3.1 of [RFC7638] contains the following example JWK Thumbprint value:

NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs

Here's a complete JWK Thumbprint URI that uses the JWK Thumbprint above and the SHA-256 hash algorithm:

urn:ietf:params:oauth:jwk-thumbprint:sha-256:NzbLsXh8uDCcd-
6MNwXF4W_7noWXFZAfHkxZsRGC9Xs

7. Security Considerations 😭

Okay, this part is serious, so pay attention 🚨. The security considerations of [RFC7638] also apply when you use this specification. Don't skip them. 💀

7.1. Multiple Public Keys per Private Key 🔐

Some cryptographic algorithms have multiple public keys that correspond to the same private key. The security considerations of [RFC7748] describe it like this:

Designers using these curves should be aware that for each public key, there are several publicly computable public keys that are equivalent to it, i.e., they produce the same shared secrets. Thus using a public key as an identifier and knowledge of a shared secret as proof of ownership (without including the public keys in the key derivation) might lead to subtle vulnerabilities.

This concern about public keys as identifiers applies equally to JWK Thumbprint URIs used as identifiers, so it's giving déjà vu. One recommended way to make sure the JWK Thumbprint URI matches the actual public key in use is to sign a message containing the correct public key with the private key. That signed message could also contain the JWK Thumbprint URI, although by definition the URI could also be computed directly from the public key. 🙈

8. IANA Considerations 📋

8.1. OAuth URI Registration 🧚

This specification registers the following value in the IANA "OAuth URI" registry [IANA.OAuth.Parameters] that was established by [RFC6755]. 💖

8.1.1. Registry Contents 🍓

URN:  urn:ietf:params:oauth:jwk-thumbprint

Common Name:  JWK Thumbprint URI

Change controller:  IESG

Specification Document:  RFC 9278

9. References 📚

9.1. Normative References 🔥

9.2. Informative References 🌷

Acknowledgements 🫶

Use cases for this specification were developed in the OpenID Connect Working Group of the OpenID Foundation. Specifically, it is being used as a key identifier in the [SIOPv2] specification. 🌈

The following individuals also contributed to the creation of this specification: John Bradley, Scott Bradner, Brian Campbell, Roman Danyliw, Vladimir Dzhuvinov, Lars Eggert, Warren Kumari, Adam Lemmon, Neil Madden, James Manger, Francesca Palombini, Aaron Parecki, Gonzalo Salgueiro, Rifaat Shekh-Yusef, Robert Sparks, David Waite, Robert Wilton, and Paul Wouters. Thank you all, you're literally the best. 👑

Authors' Addresses 💌

Michael B. Jones Microsoft Email: mbj@microsoft.com URI: https://self-issued.info/

Kristina Yasuda Microsoft Email: kryasuda@microsoft.com URI: https://twitter.com/kristinayasuda

📦 where this page comes from