| RFC 9679 | COSE Key Thumbprint | December 2024 |
| Isobe, et al. | Standards Track | [Page] |
This specification defines a method for computing a hash value over a CBORObject Signing and Encryption (COSE) Key. It specifies which fields withinthe COSE Key structure are included in the cryptographic hash computation,the process for creating a canonical representation of these fields, and howto hash the resulting byte sequence. The resulting hash value, referred toas a "thumbprint", can be used to identify or select the corresponding key.¶
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 athttps://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, 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.¶
This specification defines a method for applying a cryptographichash function to a CBOR Object Signing and Encryption (COSE) Keystructure[RFC9052], resulting in a hash value known as a"thumbprint". To achieve this, the document specifies which fieldsin the COSE Key structure are included in the hash computation, theprocess for creating a canonical form of these fields, and how tohash the resulting byte sequence. One of the primary use cases forthis thumbprint is as a naming scheme for identifying or selectingthe key, such as by using the COSE Key Thumbprint value as a "kid"(key ID). Another key use case involves key derivation functionsthat use the thumbprints of public keys from the endpoints, alongwith other application context, to derive a symmetric key.¶
This specification outlines how thumbprints of COSE Keys are generatedfor both asymmetric and symmetric keys (see Sections3 and4). 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 CWTwith a proof-of-possession key, refer toSection 3.1 of [RFC8747].¶
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.¶
The thumbprint of a COSE KeyMUST be computed as follows:¶
Construct a COSE_Key structure (seeSection 7 of [RFC9052]) containing only the required parameters representing the key as described inSection 4 of this document.¶
Apply the deterministic encoding described inSection 4.2.1 of [RFC8949] to the representation constructed in step 1.¶
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 subsequentsections.¶
The SHA-256 hash algorithmMUST be supported; other algorithmsMAY be supported.¶
Only the required parameters of a key's representation are used whencomputing its COSE Key Thumbprint value. This section summarizes therequired parameters.¶
The "kty" (label: 1) elementMUST be present for all key types, and the integervalue specified in the IANA "COSE Key Types" registryMUST be used. The tstr datatype is not used with the "kty" element.¶
Many COSE Key parameters are specific to the chosen key type. The followingsubsections list the required parameters for commonly used key types.¶
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 inSection 7.1 of [RFC9053].¶
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 inSection 7.1 of [RFC9053].¶
Note:[RFC9052] supports both compressed and uncompressed pointrepresentations. For interoperability, implementations adhering tothis specificationMUST use the uncompressed point representation.Therefore, the y-coordinate is expressed as a bstr. If animplementation uses the compressed point representation, itMUST first convert it to the uncompressed form for the purposeof thumbprint calculation.¶
The required parameters for an RSA public key are:¶
The required parameters for a symmetric key are:¶
The required parameters for HSS-LMS keys are:¶
Optional parameters of COSE Keys are intentionally not included in theCOSE Key Thumbprint computation so that their absence or presencein 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 consistentlyrefers to the key itself, not to a key with additional attributes.Different application contexts may include various optional attributesin the COSE Key structure. If these optional parameters were includedin the thumbprint calculation, the resulting values could differ forthe same key depending on the attributes present. Including only therequired parameters ensures that the COSE Key Thumbprint remainsconsistent for a given key, regardless of any additional attributes.¶
Different kinds of thumbprints could be defined by other specificationsthat might include some or all additional COSE Key parameters, if usecases arise where such different kinds of thumbprints would be useful.¶
A specific hash function must be chosen by an application to computethe hash value of the hash input. For instance, SHA-256[RFC6234]may be used as the hash function. While SHA-256 is a good defaultchoice at the time of writing, the preferred hash function may evolveas the cryptographic landscape develops.¶
In many cases, only the party that generates the key needs to beaware of the hash function used. For example, the key producer mightuse the thumbprint value as a "kid" (key ID). In such scenarios, theconsumer of the "kid" treats it as an opaque value solely for keyselection.¶
However, when multiple parties are involved in reproducing andcomparing the COSE Key Thumbprint, it is crucial that they knowand use the same hash function to ensure consistent results.¶
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.¶
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 thatuse digests of X.509 Subject Public Key Info (SPKI) values, which aredefined inSection 4.1.2.7 of [RFC5280], than to applications thatuse digests of complete certificate values, as the "x5t" (X.509certificate SHA-1 thumbprint)[RFC9360] value defined for X.509certificate objects does. While logically equivalent to a digest ofthe SPKI representation of the key, a COSE Key Thumbprint is computed overthe CBOR representation of that key rather than over an ASN.1representation of it.¶
The ckt of a COSE Key, as described inSection 7 of [RFC9052], and the jkt of a JSON Web Key, as described inSection 4 of [RFC7517], are different even when the underlying cryptographic key material is the same.¶
This document does not register a JWT confirmation method[RFC7800] for using "ckt" as a confirmation method for a JWT or a CWT confirmation method[RFC8747] for using "jkt" as a confirmation method for a CWT.¶
[RFC8747] introduces confirmation methods for use with CWTs with the addition of the "cnf" claim. CWTs are defined in[RFC8392]. This specification adds a newconfirmation method based on COSE Key Thumbprints.¶
The proof-of-possession key is identified using the "ckt" member ofthe CWT confirmation claim "cnf". This member contains the value ofthe COSE Key Thumbprint encoded as a binary string. Instead ofcommunicating the actual COSE Key, only the thumbprint is conveyed.This approach assumes that the recipient is able to obtain theidentified COSE Key using the thumbprint contained in the "ckt"member. In this approach, the issuer of a CWT declares that thepresenter possesses a particular key and that the recipientcan cryptographically confirm the presenter's proof of possessionof the key by including a "ckt" CWT confirmation method member in the CWT.¶
The following example demonstrates the use of the "ckt" memberin 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' } }¶Section 8 registers the "ckt" CWT confirmation method member.The "ckt" member is used in the "cnf" claim.¶
This specification defines Uniform Resource Identifiers (URIs)to represent a COSE Key Thumbprint value. The design followsthe work of JSON Web Key (JWK) Thumbprint URIs, as specifiedin[RFC9278]. 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 theportion of the URI following the prefix is a COSE Key Thumbprint.¶
The following URI prefix is defined to indicate that the portionof 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 prefixis followed by a hash algorithm identifier and a COSE Key Thumbprintvalue, each separated by a colon character to form a URI representinga COSE Key Thumbprint.¶
Hash algorithm identifiers used in COSE Key Thumbprint URIsMUST be values from the "Hash Name String" column in the IANA "Named Information Hash Algorithm Registry"[IANA.Hash.Algorithms]. COSE Key Thumbprint URIs with hash algorithm identifiers not found in this registry are notconsidered valid, and applicationsMUST detect and handle thiserror, should it occur.¶
Since the URN is encoded as a string, the output of the COSE KeyThumbprint computation described inSection 3MUST be base64url encoded without padding.¶
[RFC7515] specifies base64url encoding as follows:¶
Base64 encoding using the URL- and filename-safe character set defined in Section5 of RFC 4648[RFC4648], with all trailing '='characters omitted (as permitted bySection 3.2 of [RFC7515]) and without the inclusion of any line breaks,whitespace, or other additional characters. Note that the base64urlencoding of the empty octet sequence is the empty string.(SeeAppendix C of [RFC7515] for notes on implementing base64urlencoding without padding.)¶
The base64url encoding of the thumbprint shown inSection 6 isshown 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[RFC9278]; however, these URIs are intended for use with applications and specifications not necessarily related to OAuth.¶
This section demonstrates the COSE Key Thumbprint computation for thefollowing example COSE Key containing an Elliptic Curve Cryptography (ECC) public key.¶
For better readability, the example is first presented in CBOR diagnostic format (withthe 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'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c08551d', / public key: y-coordinate / -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd0084d19c', / kid is bstr, not used in COSE Key Thumbprint / 2:h'496bd8afadf307e5b08c64b0421bf9dc01528a344a43bda88fadd1669da253ec' }¶The example above corresponds to the following CBOR encoding(with link breaks added for display purposes only):¶
A50102200121582065EDA5A12577C2BAE829437FE338701A10AAA375E1BB5B5DE108DE439C08551D2258201E52ED75701163F7F9E40DDF9F341B3DC9BA860AF7E0CA7CA7E9EECD0084D19C025820496BD8AFADF307E5B08C64B0421BF9DC01528A344A43BDA88FADD1669DA253EC¶
Not all of the parameters from the example above are used in the COSE KeyThumbprint computation because the required parameters of an elliptic curvepublic key are (as listed inSection 4.2) "kty", "crv", "x", and "y".¶
The resulting COSE Key structure, in CBOR diagnostic format withline breaks added for better readability, with the minimum parametersin 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 displaypurposes only):¶
A40102200121582065EDA5A12577C2BAE829437FE338701A10AAA375E1BB5B5DE108DE439C08551D2258201E52ED75701163F7F9E40DDF9F341B3DC9BA860AF7E0CA7CA7E9EECD0084D19C¶
Using SHA-256, the resulting thumbprint is:¶
496bd8afadf307e5b08c64b0421bf9dc01528a344a43bda88fadd1669da253ec¶
A COSE Key Thumbprint will only uniquely identify a particular key if asingle unambiguous COSE Key representation for that key is defined andused when computing the COSE Key Thumbprint. Key identifiers are notincluded in the thumbprint calculation (similarly to other optionalparameters in the COSE_Key structure). If the inclusionof specific optional parameters in the thumbprint calculation is importantfor 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 theuse of particular keys (or transformations thereof). The reason isbecause an attacker may supply a key that is a transformation of a keyin order for it to appear as a different key. For instance, ifa legitimate RSA key uses a modulus value N and an attacker suppliesa key with modulus 3*N, the modified key would still work about 1/3of the time, but it would appear to be a different key.¶
Producing thumbprints of symmetric keys needs to be done with care. DevelopersMUST ensure that the symmetric key has sufficient entropy to preventattackers from precomputing tables of symmetric keys with their correspondinghash values. This can be prevented if the symmetric key is a randomlyselected key of at least a 128-bit length. ThumbprintsMUST NOT be used with passwords or other low-entropy secrets. If adeveloper is unable to determine whether all symmetric keys used in anapplication have sufficient entropy, then thumbprints of symmetric keysMUST NOT be used. In general, using thumbprints of symmetric keys shouldonly be used in special applications. In most other deployment scenarios,it is more appropriate to utilize a different naming scheme for keyidentifiers.¶
IANA has added the following entry to the "CWT ConfirmationMethods" registry[IANA-CWT] established by[RFC8747]:¶
Furthermore, IANA has added a value to the "OAuth URI" registry[IANA-OAuth]established by[RFC6755]:¶
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 thankCarsten 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, andBrendan Moran for their feedback.¶