RFC 9679

CBOR Object Signing and Encryption (COSE) Key Thumbprint

📅 published December 2024, from ietf

RFC 9679 🎀 CBOR Object Signing and Encryption (COSE) Key Thumbprint

Okay bestie, first the paperwork, but make it cute 💅

  • RFC number: 9679
  • Title: CBOR Object Signing and Encryption (COSE) Key Thumbprint
  • Authors: K. Isobe (SECOM CO., LTD.), H. Tschofenig (H-BRS), and O. Steele (Transmute) 🧚
  • Category: Standards Track, so it's an actual Internet standard and not just vibes ✨
  • ISSN: 2070-1721
  • Date: December 2024 🍓
  • Obsoletes / Updates: Nothing listed in the header, so it doesn't replace or update any earlier RFCs 🌸

Abstract 📜

This spec is giving "how to hash a COSE Key" 🔥. It says which fields inside the COSE Key structure get included in the hash, how to build a canonical version of those fields, and how to hash the resulting bytes. The output is called a "thumbprint," and you can use it to identify or select the matching key 🦋.

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.

Info about the current status of this document, any errata, and how to give feedback on it can be found at https://www.rfc-editor.org/info/rfc9679 ✨

Copyright (c) 2024 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, since they spell out 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're provided without warranty as described in the Revised BSD License 🫶

Table of Contents 🗂️

1.  Introduction
2.  Terminology
3.  COSE Key Thumbprint
4.  Required COSE Key Parameters
  4.1.  Octet Key Pair (OKP)
  4.2.  Elliptic Curve Keys with X- and Y-Coordinates
  4.3.  RSA Public Keys
  4.4.  Symmetric Keys
  4.5.  HSS-LMS Keys
  4.6.  Others
5.  Miscellaneous Considerations
  5.1.  Why Not Include Optional COSE Key Parameters?
  5.2.  Selection of Hash Function
  5.3.  Thumbprints of Keys Not in COSE Key Format
  5.4.  Relationship to Digests of X.509 Values
  5.5.  Relationship to JSON Web Key Thumbprints
  5.6.  Confirmation Method
  5.7.  COSE Key Thumbprint URIs
6.  Example
7.  Security Considerations
8.  IANA Considerations
9.  References
  9.1.  Normative References
  9.2.  Informative References
Acknowledgements
Authors' Addresses

1. Introduction ✨

This spec lets you run a cryptographic hash function over a CBOR Object Signing and Encryption (COSE) Key structure [RFC9052]. The result is a hash value called a "thumbprint" 🦋. To make that work, the document defines which fields in the COSE Key structure go into the hash, how to turn those fields into a canonical form, and how to hash the resulting byte sequence.

The big use case is naming. You can use the COSE Key Thumbprint value as a "kid" (key ID), which is a super clean way to identify or select a key 💖. Another key use involves key derivation functions. They take the thumbprints of public keys from the endpoints, plus other application context, and use all that to derive a symmetric key 🔐.

This spec explains how thumbprints get generated for both asymmetric and symmetric keys (see Sections 3 and 4). It also introduces a new CBOR Web Token (CWT) confirmation method, which has been added to the IANA "CWT Confirmation Methods" registry established by [RFC8747]. If you want the full scoop on using a confirmation claim in a CWT with a proof-of-possession key, check out Section 3.1 of [RFC8747] 🎀

2. Terminology 📖

Here's the important part: the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document get interpreted as BCP 14 [RFC2119] [RFC8174] describes, but only when they show up in all capitals, exactly like that 🧠 Lowercase versions are just regular words, so no drama.

3. COSE Key Thumbprint 🔑

So how do you actually compute one? The thumbprint of a COSE Key MUST be computed as follows:

  1. Construct a COSE_Key structure (see Section 7 of [RFC9052]) containing only the required parameters representing the key as described in Section 4 of this document.
  2. Apply the deterministic encoding described in Section 4.2.1 of [RFC8949] to the representation constructed in step 1.
  3. Hash the bytes produced in step 2 with a cryptographic hash function H. For example, SHA-256 [RFC6234] may be used as a hash function.

The details of this computation get broken down further in the later sections 💅

Quick must-know: The SHA-256 hash algorithm MUST be supported 🚨 Other algorithms MAY be supported too, but SHA-256 is the non-negotiable one.

4. Required COSE Key Parameters 💎

Only the required parameters of a key's representation get used when computing its COSE Key Thumbprint value. This section rounds up those required parameters, so pay attention 👀

The "kty" (label: 1) element MUST be present for all key types, and the integer value listed in the IANA "COSE Key Types" registry MUST be used. The tstr data type is not used with the "kty" element, so don't even try 🙅‍♀️

Lots of COSE Key parameters depend on the key type you picked. The subsections below list the required parameters for the key types people actually use a lot 💜

4.1. Octet Key Pair (OKP) 🌈

The required parameters for elliptic curve public keys that use the Octet Key Pair (OKP) key type, like X25519, are:

  • "kty" (label: 1, data type: int, value: 1)
  • "crv" (label: -1, value: int)
  • "x" (label: -2, value: bstr)

More details live in Section 7.1 of [RFC9053] ✨

4.2. Elliptic Curve Keys with X- and Y-Coordinates 🦋

The required parameters for elliptic curve public keys that use the EC2 key type, like NIST P-256, are:

  • "kty" (label: 1, data type: int, value: 2)
  • "crv" (label: -1, data type: int)
  • "x" (label: -2, data type: bstr)
  • "y" (label: -3, data type: bstr)

More details live in Section 7.1 of [RFC9053] ✨

Note, and this one's important: [RFC9052] supports both compressed and uncompressed point representations. For interoperability, implementations adhering to this specification MUST use the uncompressed point representation. That's why the y-coordinate is expressed as a bstr. If an implementation uses the compressed point representation, it MUST first convert it to the uncompressed form for the purpose of thumbprint calculation 🚨

4.3. RSA Public Keys 🔐

The required parameters for an RSA public key are:

  • "kty" (label: 1, data type: int, value: 3)
  • "n" (label: -1, data type: bstr)
  • "e" (label: -2, data type: bstr)

4.4. Symmetric Keys 🍓

The required parameters for a symmetric key are:

  • "kty" (label: 1, data type: int, value: 4)
  • "k" (label: -1, data type: bstr)

4.5. HSS-LMS Keys 🌸

The required parameters for HSS-LMS keys are:

  • "kty" (label: 1, data type: int, value: 5)
  • "pub" (label: -1, data type: bstr)

4.6. Others 🧚

As other key type values get defined, their defining specifications should be similarly consulted to figure out which parameters, on top of the "kty" element, are required. Future-proof energy 🔮

Part 1 of 3 is done 🎀 Part 2 is coming with Section 5 onward, so stay tuned, bestie 💖

5.6. Confirmation Method

okay so [RFC8747] is the one that brings in confirmation methods for CWTs, by adding the "cnf" claim 🫶. CWTs themselves are defined in [RFC8392]. This spec adds a brand new confirmation method based on COSE Key Thumbprints, and it's giving main character energy ✨

The proof-of-possession key gets identified with the "ckt" member of the CWT confirmation claim "cnf" 🎀. That member holds the COSE Key Thumbprint as a binary string. The big vibe here is that the actual COSE Key never gets sent. Only the thumbprint does 🦋 This works as long as the recipient can somehow fetch the COSE Key that matches the thumbprint in the "ckt" member. So the issuer of a CWT is basically saying "this presenter has this particular key," and the recipient can cryptographically check that the presenter really does have it, as long as there's a "ckt" CWT confirmation method member in the CWT 🔥

Here's an example of "ckt" in a CWT, sitting inside the confirmation method (line breaks added just for editorial reasons 💅):

{
 /iss/ 1 : "coaps://as.example.com",
 /aud/ 3 : "coaps://resource.example.org",
 /exp/ 4 : 1361398824,
 /cnf/ 8 : {
   /ckt/ 5 : h'496bd8afadf307e5b08c64b0421bf9dc
               01528a344a43bda88fadd1669da253ec'
  }
}

Section 8 is where the "ckt" CWT confirmation method member gets registered 📝 And the "ckt" member is used inside the "cnf" claim 💜

5.7. COSE Key Thumbprint URIs

This specification defines Uniform Resource Identifiers (URIs) that can represent a COSE Key Thumbprint value 🌸 The design is modeled on JSON Web Key (JWK) Thumbprint URIs, which are specified in [RFC9278]. Why does this matter? Because it means COSE Key Thumbprints can be used as key identifiers in places that need URIs 🙈 This spec also defines a URI prefix that tells you the stuff after the prefix is a COSE Key Thumbprint.

Here's that prefix:

urn:ietf:params:oauth:ckt

To make the hash algorithm super explicit in a URI, the prefix gets followed by a hash algorithm identifier and then the COSE Key Thumbprint value. Each piece is separated by a colon character, and together they make a URI that represents a COSE Key Thumbprint 🧚

Hash algorithm identifiers used in COSE Key Thumbprint URIs MUST be values from the "Hash Name String" column in the IANA "Named Information Hash Algorithm Registry" [IANA.Hash.Algorithms]. If a COSE Key Thumbprint URI uses a hash algorithm identifier that isn't in this registry, it is not considered valid, and applications MUST detect and handle that error, should it happen 🚨

Since the URN is encoded as a string, the output of the COSE Key Thumbprint computation described in Section 3 MUST be base64url encoded without padding 🍓

[RFC7515] spells out base64url encoding like this:

Base64 encoding using the URL- and filename-safe character set
defined in Section 5 of RFC 4648 [RFC4648], with all trailing '='
characters omitted (as permitted by Section 3.2 of [RFC7515]) and
without the inclusion of any line breaks, whitespace, or other
additional characters.  Note that the base64url encoding of the
empty octet sequence is the empty string.  (See Appendix C of
[RFC7515] for notes on implementing base64url encoding without
padding.)

The base64url encoding of the thumbprint from Section 6 is below (with a line break added for readability ✨):

SWvYr63zB-WwjGSwQhv53AFSijRKQ72oj63RZp2iU-w

And here's a full COSE Key Thumbprint URI (again, a line break added for readability 🌈):

urn:ietf:params:oauth:ckt:sha-256:

SWvYr63zB-WwjGSwQhv53AFSijRKQ72oj63RZp2iU-w

Quick heads-up on the namespace: the "oauth" part is there to line up with JWK Thumbprint URIs from [RFC9278] 💅 But these URIs are meant for applications and specs that aren't necessarily related to OAuth at all, so don't let the name fool you 🙈

6. Example

This section walks through the COSE Key Thumbprint computation for an example COSE Key holding an Elliptic Curve Cryptography (ECC) public key 🦋

For better readability, the example comes first in CBOR diagnostic format (with the long line broken up just for display purposes 👑):

  {
    / kty set to EC2 = Elliptic Curve Keys /
    1:2,
    / crv set to P-256 /
    -1:1,
    / public key: x-coordinate /
    -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0
8551d',
    / public key: y-coordinate /
    -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008
4d19c',
    / kid is bstr, not used in COSE Key Thumbprint /
    2:h'496bd8afadf307e5b08c64b0421bf9dc01528a344a43bda88fadd1669da2
53ec'
  }

That corresponds to the following CBOR encoding (with line breaks added for display purposes only 🫶):

A50102200121582065EDA5A12577C2BAE829437FE338701A10AAA375E1BB5B5DE108D
E439C08551D2258201E52ED75701163F7F9E40DDF9F341B3DC9BA860AF7E0CA7CA7E9
EECD0084D19C025820496BD8AFADF307E5B08C64B0421BF9DC01528A344A43BDA88FA
DD1669DA253EC

Not every parameter from that example gets used in the COSE Key Thumbprint computation 🤓 The reason is that the required parameters of an elliptic curve public key are (as listed in Section 4.2) "kty", "crv", "x", and "y". Everything else gets left out.

So the resulting COSE Key structure, in CBOR diagnostic format with line breaks added for readability, has the minimum parameters in the correct order:

{
   1:2,
  -1:1,
  -2:h'65eda5a12577c2bae829437fe338701a
       10aaa375e1bb5b5de108de439c08551d',
  -3:h'1e52ed75701163f7f9e40ddf9f341b3d
       c9ba860af7e0ca7ca7e9eecd0084d19c'
}

In CBOR encoding, that comes out to (with line breaks added for display purposes only 💖):

A40102200121582065EDA5A12577C2BAE829437FE338701A10AAA375E1BB5B5DE
108DE439C08551D2258201E52ED75701163F7F9E40DDF9F341B3DC9BA860AF7E0
CA7CA7E9EECD0084D19C

Using SHA-256, the resulting thumbprint is:

496bd8afadf307e5b08c64b0421bf9dc01528a344a43bda88fadd1669da253ec

7. Security Considerations

okay this section is serious, bestie, so listen up 🔥

A COSE Key Thumbprint only uniquely identifies a particular key if a single unambiguous COSE Key representation for that key is defined and used when the thumbprint gets computed 🔑 Key identifiers aren't part of the thumbprint calculation, same as the other optional parameters in the COSE_Key structure 🙈 If including specific optional parameters in the thumbprint calculation is important for your application, then this specification would not be suitable 💀

Thumbprint values are great for identifying legitimate keys, but comparing them is NOT a reliable way to exclude particular keys (or transformations of them) 😭 Why? An attacker can supply a key that's a transformation of a real key so it shows up looking like a different key. For example, say a legitimate RSA key uses a modulus value N, and an attacker supplies a key with modulus 3*N. That modified key would still work about 1/3 of the time, but it would look like a totally different key 👀

Producing thumbprints of symmetric keys needs extra care 🧁 Developers MUST ensure that the symmetric key has enough entropy to stop attackers from precomputing tables of symmetric keys with their matching hash values 🙅‍♀️ This can be prevented when the symmetric key is a randomly selected key of at least 128 bits in length. Thumbprints MUST NOT be used with passwords or other low-entropy secrets 🚫 If a developer can't determine whether all the symmetric keys used in an application have sufficient entropy, then thumbprints of symmetric keys MUST NOT be used. In general, thumbprints of symmetric keys should only be used in special applications. In most other deployment scenarios, it's more appropriate to use a different naming scheme for key identifiers 🌈

8. IANA Considerations

IANA has added the following entry to the "CWT Confirmation Methods" registry [IANA-CWT], which was established by [RFC8747] 🎀

Confirmation Method Name:  ckt
Confirmation Method Description:  COSE Key SHA-256 Thumbprint
JWT Confirmation Method Name:  (none)
Confirmation Key:  5
Confirmation Value Type(s):  binary string
Change Controller:  IETF
Specification Document(s):  RFC 9679

IANA also added a value to the "OAuth URI" registry [IANA-OAuth], which was established by [RFC6755] 🦋

URN:  urn:ietf:params:oauth:ckt
Common Name:  COSE Key Thumbprint URI
Change Controller:  IETF
Specification Document(s):  RFC 9679

9. References

9.1. Normative References

Here are the normative references, exactly as they're listed in the RFC 📚

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119,
           DOI 10.17487/RFC2119, March 1997,
           <https://www.rfc-editor.org/info/rfc2119>.

[RFC4648]  Josefsson, S., "The Base16, Base32, and Base64 Data
           Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
           <https://www.rfc-editor.org/info/rfc4648>.

[RFC6755]  Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace
           for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012,
           <https://www.rfc-editor.org/info/rfc6755>.

[RFC7515]  Jones, M., Bradley, J., and N. Sakimura, "JSON Web
           Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
           2015, <https://www.rfc-editor.org/info/rfc7515>.

[RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
           2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
           May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[RFC8392]  Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig,
           "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392,
           May 2018, <https://www.rfc-editor.org/info/rfc8392>.

[RFC8747]  Jones, M., Seitz, L., Selander, G., Erdtman, S., and H.
           Tschofenig, "Proof-of-Possession Key Semantics for CBOR
           Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March
           2020, <https://www.rfc-editor.org/info/rfc8747>.

[RFC8949]  Bormann, C. and P. Hoffman, "Concise Binary Object
           Representation (CBOR)", STD 94, RFC 8949,
           DOI 10.17487/RFC8949, December 2020,
           <https://www.rfc-editor.org/info/rfc8949>.

[RFC9052]  Schaad, J., "CBOR Object Signing and Encryption (COSE):
           Structures and Process", STD 96, RFC 9052,
           DOI 10.17487/RFC9052, August 2022,
           <https://www.rfc-editor.org/info/rfc9052>.

[RFC9053]  Schaad, J., "CBOR Object Signing and Encryption (COSE):
           Initial Algorithms", RFC 9053, DOI 10.17487/RFC9053,
           August 2022, <https://www.rfc-editor.org/info/rfc9053>.

9.2. Informative References ✨

bestie, these are the extra reads that aren't required but are worth a peek 📚💅

   [IANA-CWT] IANA, "CWT Confirmation Methods",
              <https://www.iana.org/assignments/cwt>.

   [IANA-OAuth]
              IANA, "OAuth URI",
              <https://www.iana.org/assignments/oauth-parameters>.

   [IANA.Hash.Algorithms]
              IANA, "Named Information Hash Algorithm Registry",
              <https://www.iana.org/assignments/named-information>.

   [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, DOI 10.17487/RFC5280, May 2008,
              <https://www.rfc-editor.org/info/rfc5280>.

   [RFC6234]  Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms
              (SHA and SHA-based HMAC and HKDF)", RFC 6234,
              DOI 10.17487/RFC6234, May 2011,
              <https://www.rfc-editor.org/info/rfc6234>.

   [RFC7517]  Jones, M., "JSON Web Key (JWK)", RFC 7517,
              DOI 10.17487/RFC7517, May 2015,
              <https://www.rfc-editor.org/info/rfc7517>.

   [RFC7638]  Jones, M. and N. Sakimura, "JSON Web Key (JWK)
              Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September
              2015, <https://www.rfc-editor.org/info/rfc7638>.

   [RFC7800]  Jones, M., Bradley, J., and H. Tschofenig, "Proof-of-
              Possession Key Semantics for JSON Web Tokens (JWTs)",
              RFC 7800, DOI 10.17487/RFC7800, April 2016,
              <https://www.rfc-editor.org/info/rfc7800>.

   [RFC9278]  Jones, M. and K. Yasuda, "JWK Thumbprint URI", RFC 9278,
              DOI 10.17487/RFC9278, August 2022,
              <https://www.rfc-editor.org/info/rfc9278>.

   [RFC9360]  Schaad, J., "CBOR Object Signing and Encryption (COSE):
              Header Parameters for Carrying and Referencing X.509
              Certificates", RFC 9360, DOI 10.17487/RFC9360, February
              2023, <https://www.rfc-editor.org/info/rfc9360>.

Acknowledgements 🫶

shoutout to the authors of [RFC7638] for the JWK Thumbprint spec 🙌 this whole doc takes JWK Thumbprints and applies them to COSE Key structures, so they basically made this possible 💖

Also a huge thank you to Carsten Bormann, Ilari Liusvaara, Laurence Lundblade, Daisuke Ajitomi, Michael Richardson, Michael B. Jones, Mallory Knodel, Joel Jaeggli, Derrell Piper, Patrik Fältström, Warren Kumari, Deb Cooley, and Brendan Moran for all their feedback 🌸✨ you all made this so much better 😭🫶

Authors' Addresses 💜

   Kohei Isobe
   SECOM CO., LTD.
   Japan
   Email: isobekohei@gmail.com


   Hannes Tschofenig
   University of Applied Sciences Bonn-Rhein-Sieg
   Germany
   Email: hannes.tschofenig@gmx.net


   Orie Steele
   Transmute
   United States of America
   Email: orie@transmute.industries

and that's the whole spec, bestie!! 🌈🦋👑

📦 where this page comes from