CBOR Object Signing and Encryption (COSE) Key Thumbprint SECOM CO., LTD.
Japan isobekohei@gmail.com
University of Applied Sciences Bonn-Rhein-Sieg
Germany hannes.tschofenig@gmx.net
Transmute
United States of America orie@transmute.industries
SEC cose This specification defines a method for computing a hash value over a CBOR Object Signing and Encryption (COSE) Key. It specifies which fields within the COSE Key structure are included in the cryptographic hash computation, the process for creating a canonical representation of these fields, and how to hash the resulting byte sequence. The resulting hash value, referred to as a "thumbprint", can be used to identify or select the corresponding 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. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at .
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 () 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
  • .  Introduction
  • .  Terminology
  • .  COSE Key Thumbprint
  • .  Required COSE Key Parameters
    • .  Octet Key Pair (OKP)
    • .  Elliptic Curve Keys with X- and Y-Coordinates
    • .  RSA Public Keys
    • .  Symmetric Keys
    • .  HSS-LMS Keys
    • .  Others
  • .  Miscellaneous Considerations
    • .  Why Not Include Optional COSE Key Parameters?
    • .  Selection of Hash Function
    • .  Thumbprints of Keys Not in COSE Key Format
    • .  Relationship to Digests of X.509 Values
    • .  Relationship to JSON Web Key Thumbprints
    • .  Confirmation Method
    • .  COSE Key Thumbprint URIs
  • .  Example
  • .  Security Considerations
  • .  IANA Considerations
  • .  References
    • .  Normative References
    • .  Informative References
  • Acknowledgements
  • Authors' Addresses
Introduction This specification defines a method for applying a cryptographic hash function to a CBOR Object Signing and Encryption (COSE) Key structure , 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 and ). Additionally, it introduces a new CBOR Web Token (CWT) confirmation method, which has been added to the IANA "CWT Confirmation Methods" registry established by . For further details on the use of a confirmation claim in a CWT with a proof-of-possession key, refer to .
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 when, and only when, they appear in all capitals, as shown here.
COSE Key Thumbprint The thumbprint of a COSE Key MUST be computed as follows:
  1. Construct a COSE_Key structure (see ) containing only the required parameters representing the key as described in of this document.
  2. Apply the deterministic encoding described in 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 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.
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.
Octet Key Pair (OKP) The required parameters for elliptic curve public keys that use the Octet Key Pair (OKP) key type, such as X25519, are:
  • "kty" (label: 1, data type: int, value: 1)
  • "crv" (label: -1, value: int)
  • "x" (label: -2, value: bstr)
Further details are described in .
Elliptic Curve Keys with X- and Y-Coordinates The required parameters for elliptic curve public keys that use the EC2 key type, such as 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)
Further details are described in . Note: supports both compressed and uncompressed point representations. For interoperability, implementations adhering to this specification MUST use the uncompressed point representation. Therefore, 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.
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)
Symmetric Keys The required parameters for a symmetric key are:
  • "kty" (label: 1, data type: int, value: 4)
  • "k" (label: -1, data type: bstr)
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)
Others As other key type values are defined, their defining specifications should be similarly consulted to determine which parameters, in addition to the "kty" element, are required.
Miscellaneous Considerations
Why Not Include Optional COSE Key Parameters? Optional parameters of COSE Keys are intentionally not included in the COSE Key Thumbprint computation so that their absence or presence in the COSE Key does not alter the resulting value. The COSE Key Thumbprint is a digest of the ordered essential parameters needed to represent a COSE Key, with all other parameters excluded. By excluding optional parameters, the COSE Key Thumbprint consistently refers to the key itself, not to a key with additional attributes. Different application contexts may include various optional attributes in the COSE Key structure. If these optional parameters were included in the thumbprint calculation, the resulting values could differ for the same key depending on the attributes present. Including only the required parameters ensures that the COSE Key Thumbprint remains consistent for a given key, regardless of any additional attributes. Different kinds of thumbprints could be defined by other specifications that might include some or all additional COSE Key parameters, if use cases arise where such different kinds of thumbprints would be useful.
Selection of Hash Function A specific hash function must be chosen by an application to compute the hash value of the hash input. For instance, SHA-256 may be used as the hash function. While SHA-256 is a good default choice at the time of writing, the preferred hash function may evolve as the cryptographic landscape develops. In many cases, only the party that generates the key needs to be aware of the hash function used. For example, the key producer might use the thumbprint value as a "kid" (key ID). In such scenarios, the consumer of the "kid" treats it as an opaque value solely for key selection. However, when multiple parties are involved in reproducing and comparing the COSE Key Thumbprint, it is crucial that they know and use the same hash function to ensure consistent results.
Thumbprints of Keys Not in COSE Key Format Keys that are in other formats can be represented as COSE Keys. The only prerequisites are that the COSE_Key representation of the key be defined and the party creating the COSE Key Thumbprint be in possession of the necessary key material.
Relationship to Digests of X.509 Values COSE Key Thumbprint values are computed on the COSE Key object containing only essential parameters in a specific order. Thus, they are more analogous to applications that use digests of X.509 Subject Public Key Info (SPKI) values, which are defined in , than to applications that use digests of complete certificate values, as the "x5t" (X.509 certificate SHA-1 thumbprint) value defined for X.509 certificate objects does. While logically equivalent to a digest of the SPKI representation of the key, a COSE Key Thumbprint is computed over the CBOR representation of that key rather than over an ASN.1 representation of it.
Relationship to JSON Web Key Thumbprints The ckt of a COSE Key, as described in , and the jkt of a JSON Web Key, as described in , are different even when the underlying cryptographic key material is the same. This document does not register a JWT confirmation method for using "ckt" as a confirmation method for a JWT or a CWT confirmation method for using "jkt" as a confirmation method for a CWT.
Confirmation Method introduces confirmation methods for use with CWTs with the addition of the "cnf" claim. CWTs are defined in . This specification adds a new confirmation method based on COSE Key Thumbprints. The proof-of-possession key is identified using the "ckt" member of the CWT confirmation claim "cnf". This member contains the value of the COSE Key Thumbprint encoded as a binary string. Instead of communicating the actual COSE Key, only the thumbprint is conveyed. This approach assumes that the recipient is able to obtain the identified COSE Key using the thumbprint contained in the "ckt" member. In this approach, the issuer of a CWT declares that the presenter possesses a particular key and that the recipient can cryptographically confirm the presenter's proof of possession of the key by including a "ckt" CWT confirmation method member in the CWT. The following example demonstrates the use of the "ckt" member in a CWT as part of the confirmation method (with line breaks inserted 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' } } registers the "ckt" CWT confirmation method member. The "ckt" member is used in the "cnf" claim.
COSE Key Thumbprint URIs This specification defines Uniform Resource Identifiers (URIs) to represent a COSE Key Thumbprint value. The design follows the work of JSON Web Key (JWK) Thumbprint URIs, as specified in . This enables COSE Key Thumbprints to be used, for example, as key identifiers in contexts requiring URIs. This specification defines a URI prefix indicating that the portion of the URI following the prefix is a COSE Key Thumbprint. The following URI prefix is defined to indicate that the portion of the URI following the prefix is a COSE Key Thumbprint: urn:ietf:params:oauth:ckt To make the hash algorithm being used explicit in a URI, the prefix is followed by a hash algorithm identifier and a COSE Key Thumbprint value, each separated by a colon character to form a URI representing 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" . COSE Key Thumbprint URIs with hash algorithm identifiers not found in this registry are not considered valid, and applications MUST detect and handle this error, should it occur. Since the URN is encoded as a string, the output of the COSE Key Thumbprint computation described in MUST be base64url encoded without padding. specifies base64url encoding as follows:
Base64 encoding using the URL- and filename-safe character set defined in Section of RFC 4648 , with all trailing '=' characters omitted (as permitted by ) 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 for notes on implementing base64url encoding without padding.)
The base64url encoding of the thumbprint shown in is shown below (with a line break added for readability purposes). SWvYr63zB-WwjGSwQhv53AFSijRKQ72oj63RZp2iU-w The full example of a COSE Key Thumbprint URI is shown below (with a line break added for readability). urn:ietf:params:oauth:ckt:sha-256: SWvYr63zB-WwjGSwQhv53AFSijRKQ72oj63RZp2iU-w Note that the use of oauth in the namespace is to align with JWK Thumbprint URIs as described in ; however, these URIs are intended for use with applications and specifications not necessarily related to OAuth.
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 EECD0084D19C025820496BD8AFADF307E5B08C64B0421BF9DC01528A344A43BDA88FA DD1669DA253EC 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 ) "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
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.
IANA Considerations IANA has added the following entry to the "CWT Confirmation Methods" registry established by :
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
Furthermore, IANA has added a value to the "OAuth URI" registry established by :
URN:
urn:ietf:params:oauth:ckt
Common Name:
COSE Key Thumbprint URI
Change Controller:
IETF
Specification Document(s):
RFC 9679
 References Normative References Key words for use in RFCs to Indicate Requirement Levels In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. The Base16, Base32, and Base64 Data Encodings This document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK] An IETF URN Sub-Namespace for OAuth This document establishes an IETF URN Sub-namespace for use with OAuth-related specifications. This document is not an Internet Standards Track specification; it is published for informational purposes. JSON Web Signature (JWS) JSON Web Signature (JWS) represents content secured with digital signatures or Message Authentication Codes (MACs) using JSON-based data structures. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and an IANA registry defined by that specification. Related encryption capabilities are described in the separate JSON Web Encryption (JWE) specification. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. CBOR Web Token (CWT) CBOR Web Token (CWT) is a compact means of representing claims to be transferred between two parties. The claims in a CWT are encoded in the Concise Binary Object Representation (CBOR), and CBOR Object Signing and Encryption (COSE) is used for added application-layer security protection. A claim is a piece of information asserted about a subject and is represented as a name/value pair consisting of a claim name and a claim value. CWT is derived from JSON Web Token (JWT) but uses CBOR rather than JSON. Proof-of-Possession Key Semantics for CBOR Web Tokens (CWTs) This specification describes how to declare in a CBOR Web Token (CWT) (which is defined by RFC 8392) that the presenter of the CWT possesses a particular proof-of-possession key. Being able to prove possession of a key is also sometimes described as being the holder-of-key. This specification provides equivalent functionality to "Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs)" (RFC 7800) but using Concise Binary Object Representation (CBOR) and CWTs rather than JavaScript Object Notation (JSON) and JSON Web Tokens (JWTs). Concise Binary Object Representation (CBOR) The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack. This document obsoletes RFC 7049, providing editorial improvements, new details, and errata fixes while keeping full compatibility with the interchange format of RFC 7049. It does not create a new version of the format. CBOR Object Signing and Encryption (COSE): Structures and Process Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. There is a need to be able to define basic security services for this data format. This document defines the CBOR Object Signing and Encryption (COSE) protocol. This specification describes how to create and process signatures, message authentication codes, and encryption using CBOR for serialization. This specification additionally describes how to represent cryptographic keys using CBOR. This document, along with RFC 9053, obsoletes RFC 8152. CBOR Object Signing and Encryption (COSE): Initial Algorithms Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. There is a need to be able to define basic security services for this data format. This document defines a set of algorithms that can be used with the CBOR Object Signing and Encryption (COSE) protocol (RFC 9052). This document, along with RFC 9052, obsoletes RFC 8152. Informative References CWT Confirmation Methods IANA OAuth URI IANA Named Information Hash Algorithm Registry IANA Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile This memo profiles the X.509 v3 certificate and X.509 v2 certificate revocation list (CRL) for use in the Internet. An overview of this approach and model is provided as an introduction. The X.509 v3 certificate format is described in detail, with additional information regarding the format and semantics of Internet name forms. Standard certificate extensions are described and two Internet-specific extensions are defined. A set of required certificate extensions is specified. The X.509 v2 CRL format is described in detail along with standard and Internet-specific extensions. An algorithm for X.509 certification path validation is described. An ASN.1 module and examples are provided in the appendices. [STANDARDS-TRACK] US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF) Federal Information Processing Standard, FIPS JSON Web Key (JWK) A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. This specification also defines a JWK Set JSON data structure that represents a set of JWKs. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and IANA registries established by that specification. JSON Web Key (JWK) Thumbprint This specification defines a method for computing a hash value over a JSON Web Key (JWK). It defines which fields in a JWK are used in the hash computation, the method of creating a canonical form for those fields, and how to convert the resulting Unicode string into a byte sequence to be hashed. The resulting hash value can be used for identifying or selecting the key represented by the JWK that is the subject of the thumbprint. Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs) This specification describes how to declare in a JSON Web Token (JWT) that the presenter of the JWT possesses a particular proof-of- possession key and how the recipient can cryptographically confirm proof of possession of the key by the presenter. Being able to prove possession of a key is also sometimes described as the presenter being a holder-of-key. JWK Thumbprint URI This specification registers a kind of URI that represents a JSON Web Key (JWK) Thumbprint value. JWK Thumbprints are defined in RFC 7638. This enables JWK Thumbprints to be used, for instance, as key identifiers in contexts requiring URIs. CBOR Object Signing and Encryption (COSE): Header Parameters for Carrying and Referencing X.509 Certificates The CBOR Object Signing and Encryption (COSE) message structure uses references to keys in general. For some algorithms, additional properties are defined that carry parameters relating to keys as needed. The COSE Key structure is used for transporting keys outside of COSE messages. This document extends the way that keys can be identified and transported by providing attributes that refer to or contain X.509 certificates.
Acknowledgements We would like to thank the authors of for their work on the JWK Thumbprint specification. This document applies JWK Thumbprints to COSE Key structures. Additionally, we would like to thank , , , , , , , , , , , , and for their feedback.
Authors' Addresses SECOM CO., LTD.
Japan isobekohei@gmail.com
University of Applied Sciences Bonn-Rhein-Sieg
Germany hannes.tschofenig@gmx.net
Transmute
United States of America orie@transmute.industries