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/rfc9679.¶

Copyright Notice

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, as 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 are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

This specification defines a method for applying a cryptographic hash function to a CBOR Object Signing and Encryption (COSE) Key structure [RFC9052], resulting in a hash value known as a "thumbprint". To achieve this, the document specifies which fields in the COSE Key structure are included in the hash computation, the process for creating a canonical form of these fields, and how to hash the resulting byte sequence. One of the primary use cases for this thumbprint is as a naming scheme for identifying or selecting the key, such as by using the COSE Key Thumbprint value as a "kid" (key ID). Another key use case involves key derivation functions that use the thumbprints of public keys from the endpoints, along with other application context, to derive a symmetric key.¶

This specification outlines how thumbprints of COSE Keys are generated for both asymmetric and symmetric keys (see Sections 3 and 4). Additionally, it introduces a new CBOR Web Token (CWT) confirmation method, which has been added to the IANA "CWT Confirmation Methods" registry established by [RFC8747]. For further details on the use of a confirmation claim in a CWT with a proof-of-possession key, refer to Section 3.1 of [RFC8747].¶

2. Terminology

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.¶

3. COSE Key Thumbprint

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 are further described in subsequent sections.¶

The SHA-256 hash algorithm MUST be supported; other algorithms MAY be supported.¶

4. Required COSE Key Parameters

Only the required parameters of a key's representation are used when computing its COSE Key Thumbprint value. This section summarizes the required parameters.¶

The "kty" (label: 1) element MUST be present for all key types, and the integer value specified in the IANA "COSE Key Types" registry MUST be used. The tstr data type is not used with the "kty" element.¶

Many COSE Key parameters are specific to the chosen key type. The following subsections list the required parameters for commonly used key types.¶

5. Miscellaneous Considerations

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

6. Example

This section demonstrates the COSE Key Thumbprint computation for the following example COSE Key containing an Elliptic Curve Cryptography (ECC) public key.¶

For better readability, the example is first presented in CBOR diagnostic format (with the long line broken for display purposes only).¶

  {
    / 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'
  }

The example above corresponds to the following CBOR encoding (with link breaks added for display purposes only):¶

A50102200121582065EDA5A12577C2BAE829437FE338701A10AAA375E1BB5B5DE108D
E439C08551D2258201E52ED75701163F7F9E40DDF9F341B3DC9BA860AF7E0CA7CA7E9
EECD0084D19C0258246D65726961646F632E6272616E64796275636B406275636B6C6
16E642E6578616D706C65

Not all of the parameters from the example above are used in the COSE Key Thumbprint computation because the required parameters of an elliptic curve public key are (as listed in Section 4.2) "kty", "crv", "x", and "y".¶

The resulting COSE Key structure, in CBOR diagnostic format with line breaks added for better readability, with the minimum parameters in the correct order are:¶

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

In CBOR encoding, the result is (with line breaks added for display purposes only):¶

A40102200121582065EDA5A12577C2BAE829437FE338701A10AAA375E1BB5B5DE
108DE439C08551D2258201E52ED75701163F7F9E40DDF9F341B3DC9BA860AF7E0
CA7CA7E9EECD0084D19C

Using SHA-256, the resulting thumbprint is:¶

496bd8afadf307e5b08c64b0421bf9dc01528a344a43bda88fadd1669da253ec

7. Security Considerations

A COSE Key Thumbprint will only uniquely identify a particular key if a single unambiguous COSE Key representation for that key is defined and used when computing the COSE Key Thumbprint. Key identifiers are not included in the thumbprint calculation (similarly to other optional parameters in the COSE_Key structure). If the inclusion of specific optional parameters in the thumbprint calculation is important for a particular application, this specification would not be suitable.¶

While thumbprint values are useful for identifying legitimate keys, comparing thumbprint values is not a reliable means of excluding the use of particular keys (or transformations thereof). The reason is because an attacker may supply a key that is a transformation of a key in order for it to appear as 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 it would appear to be a different key.¶

Producing thumbprints of symmetric keys needs to be done with care. Developers MUST ensure that the symmetric key has sufficient entropy to prevent attackers from precomputing tables of symmetric keys with their corresponding hash values. This can be prevented if the symmetric key is a randomly selected key of at least a 128-bit length. Thumbprints MUST NOT be used with passwords or other low-entropy secrets. If a developer is unable to determine whether all symmetric keys used in an application have sufficient entropy, then thumbprints of symmetric keys MUST NOT be used. In general, using thumbprints of symmetric keys should only be used in special applications. In most other deployment scenarios, it is more appropriate to utilize a different naming scheme for key identifiers.¶

8. IANA Considerations

IANA has added the following entry to the "CWT Confirmation Methods" registry [IANA-CWT] established by [RFC8747]:¶

Confirmation Method Name:

ckt¶

Confirmation Method Description:

COSE Key SHA-256 Thumbprint¶

JWT Confirmation Method Name:

jkt¶

Confirmation Key:

5¶

Confirmation Value Type(s):

binary string¶

Change Controller:

IETF¶

Specification Document(s):

RFC 9679¶

Furthermore, IANA has added a value to the "OAuth URI" registry [IANA-OAuth] established by [RFC6755]:¶

URN:

urn:ietf:params:oauth:ckt¶

Common Name:

COSE Key Thumbprint URI¶

Change Controller:

IETF¶

Specification Document(s):

RFC 9679¶

Acknowledgements

We would like to thank the authors of [RFC7638] for their work on the JWK Thumbprint specification. This document applies JWK Thumbprints to COSE Key structures.¶

Additionally, we would like to thank 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 their feedback.¶

Authors' Addresses