rfc9679.original   rfc9679.txt 
COSE K. Isobe Internet Engineering Task Force (IETF) K. Isobe
Internet-Draft SECOM CO., LTD. Request for Comments: 9679 SECOM CO., LTD.
Intended status: Standards Track H. Tschofenig Category: Standards Track H. Tschofenig
Expires: 10 March 2025 H-BRS ISSN: 2070-1721 H-BRS
O. Steele O. Steele
Transmute Transmute
6 September 2024 December 2024
CBOR Object Signing and Encryption (COSE) Key Thumbprint CBOR Object Signing and Encryption (COSE) Key Thumbprint
draft-ietf-cose-key-thumbprint-06
Abstract Abstract
This specification defines a method for computing a hash value over a This specification defines a method for computing a hash value over a
CBOR Object Signing and Encryption (COSE) Key. It specifies which CBOR Object Signing and Encryption (COSE) Key. It specifies which
fields within the COSE Key structure are included in the fields within the COSE Key structure are included in the
cryptographic hash computation, the process for creating a canonical cryptographic hash computation, the process for creating a canonical
representation of these fields, and how to hash the resulting byte representation of these fields, and how to hash the resulting byte
sequence. The resulting hash value, referred to as a "thumbprint," sequence. The resulting hash value, referred to as a "thumbprint",
can be used to identify or select the corresponding key. can be used to identify or select the corresponding key.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This is an Internet Standards Track document.
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
This Internet-Draft will expire on 10 March 2025. 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 Notice
Copyright (c) 2024 IETF Trust and the persons identified as the Copyright (c) 2024 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents
license-info) in effect on the date of publication of this document. (https://trustee.ietf.org/license-info) in effect on the date of
Please review these documents carefully, as they describe your rights publication of this document. Please review these documents
and restrictions with respect to this document. Code Components carefully, as they describe your rights and restrictions with respect
extracted from this document must include Revised BSD License text as to this document. Code Components extracted from this document must
described in Section 4.e of the Trust Legal Provisions and are include Revised BSD License text as described in Section 4.e of the
provided without warranty as described in the Revised BSD License. Trust Legal Provisions and are provided without warranty as described
in the Revised BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology
3. COSE Key Thumbprint . . . . . . . . . . . . . . . . . . . . . 3 3. COSE Key Thumbprint
4. Required COSE Key Parameters . . . . . . . . . . . . . . . . 3 4. Required COSE Key Parameters
4.1. Octet Key Pair (OKP) . . . . . . . . . . . . . . . . . . 4 4.1. Octet Key Pair (OKP)
4.2. Elliptic Curve Keys with X- and Y-Coordinate Pair . . . . 4 4.2. Elliptic Curve Keys with X- and Y-Coordinates
4.3. RSA Public Keys . . . . . . . . . . . . . . . . . . . . . 4 4.3. RSA Public Keys
4.4. Symmetric Keys . . . . . . . . . . . . . . . . . . . . . 5 4.4. Symmetric Keys
4.5. HSS-LMS . . . . . . . . . . . . . . . . . . . . . . . . . 5 4.5. HSS-LMS Keys
4.6. Others . . . . . . . . . . . . . . . . . . . . . . . . . 5 4.6. Others
5. Miscellaneous Considerations . . . . . . . . . . . . . . . . 5 5. Miscellaneous Considerations
5.1. Why Not Include Optional COSE Key Parameters? . . . . . . 5 5.1. Why Not Include Optional COSE Key Parameters?
5.2. Selection of Hash Function . . . . . . . . . . . . . . . 6 5.2. Selection of Hash Function
5.3. Thumbprints of Keys Not in COSE Key Format . . . . . . . 6 5.3. Thumbprints of Keys Not in COSE Key Format
5.4. Relationship to Digests of X.509 Values . . . . . . . . . 6 5.4. Relationship to Digests of X.509 Values
5.5. Confirmation Method . . . . . . . . . . . . . . . . . . . 7 5.5. Relationship to JSON Web Key Thumbprints
5.6. COSE Key Thumbprint URIs . . . . . . . . . . . . . . . . 7 5.6. Confirmation Method
6. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 5.7. COSE Key Thumbprint URIs
7. Security Considerations . . . . . . . . . . . . . . . . . . . 10 6. Example
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 7. Security Considerations
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 8. IANA Considerations
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 9. References
10.1. Normative References . . . . . . . . . . . . . . . . . . 11 9.1. Normative References
10.2. Informative References . . . . . . . . . . . . . . . . . 12 9.2. Informative References
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 Acknowledgements
Authors' Addresses
1. Introduction 1. Introduction
This specification defines a method for applying a cryptographic hash This specification defines a method for applying a cryptographic hash
function to a CBOR Object Signing and Encryption (COSE) Key structure function to a CBOR Object Signing and Encryption (COSE) Key structure
[RFC9052], resulting in a hash value known as a "thumbprint." To [RFC9052], resulting in a hash value known as a "thumbprint". To
achieve this, the document specifies which fields in the COSE Key achieve this, the document specifies which fields in the COSE Key
structure are included in the hash computation, the process for structure are included in the hash computation, the process for
creating a canonical form of these fields, and how to hash the creating a canonical form of these fields, and how to hash the
resulting byte sequence. One of the primary use cases for this resulting byte sequence. One of the primary use cases for this
thumbprint is as a naming scheme for identifying or selecting the 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 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 ID). Another key use case involves key derivation functions that use
the thumbprints of public keys from the endpoints, along with other the thumbprints of public keys from the endpoints, along with other
context, to derive a symmetric key. application context, to derive a symmetric key.
This specification outlines how thumbprints of COSE Keys are This specification outlines how thumbprints of COSE Keys are
generated for both asymmetric and symmetric keys (see Section 3 and generated for both asymmetric and symmetric keys (see Sections 3 and
Section 4). Additionally, it introduces a new CBOR Web Token (CWT) 4). Additionally, it introduces a new CBOR Web Token (CWT)
confirmation method, which is added to the IANA "CWT Confirmation confirmation method, which has been added to the IANA "CWT
Methods" registry established by [RFC8747]. For further details on Confirmation Methods" registry established by [RFC8747]. For further
the use of a confirmation claim in a CWT with a proof-of-possession details on the use of a confirmation claim in a CWT with a proof-of-
key, refer to Section 3.1 of [RFC8747]. possession key, refer to Section 3.1 of [RFC8747].
2. Terminology 2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in
14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
3. COSE Key Thumbprint 3. COSE Key Thumbprint
The thumbprint of a COSE Key MUST be computed as follows: The thumbprint of a COSE Key MUST be computed as follows:
1. Construct a COSE_Key structure (see Section 7 of [RFC9052]) 1. Construct a COSE_Key structure (see Section 7 of [RFC9052])
containing only the required parameters representing the key as containing only the required parameters representing the key as
described in Section 4 of this document. described in Section 4 of this document.
2. Apply the deterministic encoding described in Section 4.2.1 of 2. Apply the deterministic encoding described in Section 4.2.1 of
[RFC8949] to the representation constructed in step (1). [RFC8949] to the representation constructed in step 1.
3. Hash the bytes produced in step (2) with a cryptographic hash 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 H. For example, SHA-256 [RFC6234] may be used as a hash
function. function.
The details of this computation are further described in subsequent The details of this computation are further described in subsequent
sections. sections.
The SHA-256 hash algorithm MUST be supported, other algorithms MAY be The SHA-256 hash algorithm MUST be supported; other algorithms MAY be
supported. supported.
4. Required COSE Key Parameters 4. Required COSE Key Parameters
Only the required parameters of a key's representation are used when Only the required parameters of a key's representation are used when
computing its COSE Key Thumbprint value. This section summarizes the computing its COSE Key Thumbprint value. This section summarizes the
required parameters. required parameters.
The "kty" (label: 1) element MUST be present for all key types, and 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 the integer value specified in the IANA "COSE Key Types" registry
be used. The tstr data type is not used with the kty element. 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 Many COSE Key parameters are specific to the chosen key type. The
following subsections list the required parameters for commonly used following subsections list the required parameters for commonly used
key types. key types.
4.1. Octet Key Pair (OKP) 4.1. Octet Key Pair (OKP)
The required parameters for elliptic curve public keys that use the The required parameters for elliptic curve public keys that use the
OKP key type, such as X25519, are: Octet Key Pair (OKP) key type, such as X25519, are:
* "kty" (label: 1, data type: int, value: 1) * "kty" (label: 1, data type: int, value: 1)
* "crv" (label: -1, value: int) * "crv" (label: -1, value: int)
* "x" (label: -2, value: bstr) * "x" (label: -2, value: bstr)
Details can be found in Section 7.1 of [RFC9053]. Further details are described in Section 7.1 of [RFC9053].
4.2. Elliptic Curve Keys with X- and Y-Coordinate Pair 4.2. Elliptic Curve Keys with X- and Y-Coordinates
The required parameters for elliptic curve public keys that use the The required parameters for elliptic curve public keys that use the
EC2 key type, such as NIST P-256, are: EC2 key type, such as NIST P-256, are:
* "kty" (label: 1, data type: int, value: 2) * "kty" (label: 1, data type: int, value: 2)
* "crv" (label: -1, data type: int) * "crv" (label: -1, data type: int)
* "x" (label: -2, data type: bstr) * "x" (label: -2, data type: bstr)
* "y" (label: -3, data type: bstr) * "y" (label: -3, data type: bstr)
Details can be found in Section 7.1 of [RFC9053]. Further details are described in Section 7.1 of [RFC9053].
Note: [RFC9052] supports both compressed and uncompressed point Note: [RFC9052] supports both compressed and uncompressed point
representations. For interoperability, implementations adhering to representations. For interoperability, implementations adhering to
this specification MUST use the uncompressed point representation. this specification MUST use the uncompressed point representation.
Therefore, the y-coordinate is expressed as a bstr. If an Therefore, the y-coordinate is expressed as a bstr. If an
implementation uses the compressed point representation, it MUST implementation uses the compressed point representation, it MUST
first convert it to the uncompressed form for the purpose of first convert it to the uncompressed form for the purpose of
thumbprint calculation. thumbprint calculation.
4.3. RSA Public Keys 4.3. RSA Public Keys
skipping to change at page 5, line 4 skipping to change at line 189
first convert it to the uncompressed form for the purpose of first convert it to the uncompressed form for the purpose of
thumbprint calculation. thumbprint calculation.
4.3. RSA Public Keys 4.3. RSA Public Keys
The required parameters for an RSA public key are: The required parameters for an RSA public key are:
* "kty" (label: 1, data type: int, value: 3) * "kty" (label: 1, data type: int, value: 3)
* "n" (label: -1, data type: bstr) * "n" (label: -1, data type: bstr)
* "e" (label: -2, data type: bstr) * "e" (label: -2, data type: bstr)
4.4. Symmetric Keys 4.4. Symmetric Keys
The required parameters for a symmetric key are: The required parameters for a symmetric key are:
* "kty" (label: 1, data type: int, value: 4) * "kty" (label: 1, data type: int, value: 4)
* "k" (label: -1, data type: bstr) * "k" (label: -1, data type: bstr)
4.5. HSS-LMS 4.5. HSS-LMS Keys
The required parameters for HSS-LMS keys are: The required parameters for HSS-LMS keys are:
* "kty" (label: 1, data type: int, value: 5) * "kty" (label: 1, data type: int, value: 5)
* "pub" (label: -1, data type: bstr) * "pub" (label: -1, data type: bstr)
4.6. Others 4.6. Others
As other key type values are defined, the specifications defining As other key type values are defined, their defining specifications
them should be similarly consulted to determine which parameters, in should be similarly consulted to determine which parameters, in
addition to the "kty" element, are required. addition to the "kty" element, are required.
5. Miscellaneous Considerations 5. Miscellaneous Considerations
5.1. Why Not Include Optional COSE Key Parameters? 5.1. Why Not Include Optional COSE Key Parameters?
Optional parameters of COSE Keys are intentionally not included in Optional parameters of COSE Keys are intentionally not included in
the COSE Key Thumbprint computation so that their absence or presence the COSE Key Thumbprint computation so that their absence or presence
in the COSE Key does not alter the resulting value. The COSE Key in the COSE Key does not alter the resulting value. The COSE Key
Thumbprint is a digest of the essential parameters required to Thumbprint is a digest of the ordered essential parameters needed to
represent the key as a COSE Key, rather than any additional data that represent a COSE Key, with all other parameters excluded.
might accompany the key.
By excluding optional parameters, the COSE Key Thumbprint By excluding optional parameters, the COSE Key Thumbprint
consistently refers to the key itself, not to a key with additional consistently refers to the key itself, not to a key with additional
attributes. Different application contexts may include various attributes. Different application contexts may include various
optional attributes in the COSE Key structure. If these optional optional attributes in the COSE Key structure. If these optional
parameters were included in the thumbprint calculation, the resulting parameters were included in the thumbprint calculation, the resulting
values could differ for the same key depending on the attributes values could differ for the same key depending on the attributes
present. Including only the required parameters ensures that the present. Including only the required parameters ensures that the
COSE Key Thumbprint remains consistent for a given key, regardless of COSE Key Thumbprint remains consistent for a given key, regardless of
any additional attributes. any additional attributes.
skipping to change at page 6, line 30 skipping to change at line 259
use the thumbprint value as a "kid" (key ID). In such scenarios, the 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 consumer of the "kid" treats it as an opaque value solely for key
selection. selection.
However, when multiple parties are involved in reproducing and However, when multiple parties are involved in reproducing and
comparing the COSE Key Thumbprint, it is crucial that they know and comparing the COSE Key Thumbprint, it is crucial that they know and
use the same hash function to ensure consistent results. use the same hash function to ensure consistent results.
5.3. Thumbprints of Keys Not in COSE Key Format 5.3. Thumbprints of Keys Not in COSE Key Format
Keys that are in other formats can be represented as COSE Keys. Any Keys that are in other formats can be represented as COSE Keys. The
party in possession of a key that is represented as a COSE Key can only prerequisites are that the COSE_Key representation of the key be
use the COSE Key Thumbprint. defined and the party creating the COSE Key Thumbprint be in
possession of the necessary key material.
5.4. Relationship to Digests of X.509 Values 5.4. Relationship to Digests of X.509 Values
COSE Key Thumbprint values are computed on the COSE Key object COSE Key Thumbprint values are computed on the COSE Key object
required to represent a key, rather than all parameters of a COSE Key containing only essential parameters in a specific order. Thus, they
that the key is represented in. Thus, they are more analogous to are more analogous to applications that use digests of X.509 Subject
applications that use digests of X.509 Subject Public Key Info (SPKI) Public Key Info (SPKI) values, which are defined in Section 4.1.2.7
values, which are defined in Section 4.1.2.7 of [RFC5280], than to of [RFC5280], than to applications that use digests of complete
applications that use digests of complete certificate values, as the certificate values, as the "x5t" (X.509 certificate SHA-1 thumbprint)
"x5t" (X.509 certificate SHA-1 thumbprint) [RFC9360] value defined [RFC9360] value defined for X.509 certificate objects does. While
for X.509 certificate objects does. While logically equivalent to a logically equivalent to a digest of the SPKI representation of the
digest of the SPKI representation of the key, a COSE Key Thumbprint key, a COSE Key Thumbprint is computed over the CBOR representation
is computed over the CBOR representation of that key, rather than of that key rather than over an ASN.1 representation of it.
over an ASN.1 representation of it.
5.5. Confirmation Method 5.5. Relationship to JSON Web Key Thumbprints
[RFC8747] introduced confirmation methods for use with CBOR Web The ckt of a COSE Key, as described in Section 7 of [RFC9052], and
Tokens (CWTs) with the addition of the "cnf" claim. CWTs have been the jkt of a JSON Web Key, as described in Section 4 of [RFC7517],
defined in [RFC8392]. This specification adds a new confirmation are different even when the underlying cryptographic key material is
method based on COSE Key Thumbprints. the same.
The proof-of-possession key is identified using the "ckt" claim, the This document does not register a JWT confirmation method [RFC7800]
COSE Key Thumbprint claim. This claim contains the value of the COSE for using "ckt" as a confirmation method for a JWT or a CWT
Key Thumbprint encoded as a binary string. Instead of communicating confirmation method [RFC8747] for using "jkt" as a confirmation
the actual COSE Key only the thumbprint is conveyed. This approach method for a CWT.
assumes that the recipient is able to obtain the identified COSE Key
using the thumbprint contained in the "ckt" claim. 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"
claim in the CWT.
The following example demonstrates the use of the "ckt" claim in a 5.6. Confirmation Method
CWT as part of the confirmation method (with line-breaks inserted for
[RFC8747] introduces confirmation methods for use with CWTs with the
addition of the "cnf" claim. CWTs are defined in [RFC8392]. 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): editorial reasons):
{ {
/iss/ 1 : "coaps://as.example.com", /iss/ 1 : "coaps://as.example.com",
/aud/ 3 : "coaps://resource.example.org", /aud/ 3 : "coaps://resource.example.org",
/exp/ 4 : 1361398824, /exp/ 4 : 1361398824,
/cnf/ 8 : { /cnf/ 8 : {
/ckt/ [[TBD1]] : h'496bd8afadf307e5b08c64b0421bf9dc /ckt/ 5 : h'496bd8afadf307e5b08c64b0421bf9dc
01528a344a43bda88fadd1669da253ec' 01528a344a43bda88fadd1669da253ec'
} }
} }
Section 8 registers the "ckt" claim and the confirmation method. The Section 8 registers the "ckt" CWT confirmation method member. The
"ckt" claim is expected to be used in the "cnf" claim. "ckt" member is used in the "cnf" claim.
5.6. COSE Key Thumbprint URIs 5.7. COSE Key Thumbprint URIs
This specification defines Uniform Resource Identifiers (URIs) to This specification defines Uniform Resource Identifiers (URIs) to
represent a COSE Key Thumbprint value. The design follows the work represent a COSE Key Thumbprint value. The design follows the work
of the JSON Web Key (JWK) Thumbprint URIs, specified in [RFC9278]. of JSON Web Key (JWK) Thumbprint URIs, as specified in [RFC9278].
This enables COSE Key Thumbprints to be used, for example, as key This enables COSE Key Thumbprints to be used, for example, as key
identifiers in contexts requiring URIs. This specification defines a identifiers in contexts requiring URIs. This specification defines a
URI prefix indicating that the portion of the URI following the URI prefix indicating that the portion of the URI following the
prefix is a COSE Key Thumbprint. prefix is a COSE Key Thumbprint.
The following URI prefix is defined to indicate that the portion of The following URI prefix is defined to indicate that the portion of
the URI following the prefix is a COSE Key Thumbprint: the URI following the prefix is a COSE Key Thumbprint:
urn:ietf:params:oauth:ckt urn:ietf:params:oauth:ckt
To make the hash algorithm being used explicit in a URI, the prefix 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 is followed by a hash algorithm identifier and a COSE Key Thumbprint
value, each separated by a colon character to form a URI representing value, each separated by a colon character to form a URI representing
a COSE Key Thumbprint. a COSE Key Thumbprint.
Hash algorithm identifiers used in COSE Key Thumbprint URIs MUST be Hash algorithm identifiers used in COSE Key Thumbprint URIs MUST be
values from the "Hash Name String" column in the IANA "Named values from the "Hash Name String" column in the IANA "Named
Information Hash Algorithm Registry" [IANA.Hash.Algorithms]. COSE Information Hash Algorithm Registry" [IANA.Hash.Algorithms]. COSE
Key Thumbprint URIs with hash algorithm identifiers not found in this Key Thumbprint URIs with hash algorithm identifiers not found in this
registry are not considered valid and applications MUST detect and registry are not considered valid, and applications MUST detect and
handle this error, should it occur. handle this error, should it occur.
Since the URN is encoded as a string, the output of the COSE Key Since the URN is encoded as a string, the output of the COSE Key
Thumbprint computation described in Section 3 MUST be base64url Thumbprint computation described in Section 3 MUST be base64url
encoded without padding. encoded without padding.
[RFC7515] specifies Base64url encoding as follows: [RFC7515] specifies base64url encoding as follows:
"Base64 encoding using the URL- and filename-safe character set | Base64 encoding using the URL- and filename-safe character set
defined in Section 5 of RFC 4648 [RFC4648], with all trailing '=' | defined in Section 5 of RFC 4648 [RFC4648], with all trailing '='
characters omitted and without the inclusion of any line breaks, | characters omitted (as permitted by Section 3.2 of [RFC7515]) and
whitespace, or other additional characters. Note that the base64url | without the inclusion of any line breaks, whitespace, or other
encoding of the empty octet sequence is the empty string. (See | additional characters. Note that the base64url encoding of the
Appendix C of [RFC7515] for notes on implementing base64url encoding | empty octet sequence is the empty string. (See Appendix C of
without padding.)" | [RFC7515] for notes on implementing base64url encoding without
| padding.)
The base64url encoding of the thumbprint shown in Section 6 is shown The base64url encoding of the thumbprint shown in Section 6 is shown
below (with a line-break added for readability purposes). below (with a line break added for readability purposes).
SWvYr63zB-WwjGSwQhv53AFSijRKQ72oj63RZp2iU-w SWvYr63zB-WwjGSwQhv53AFSijRKQ72oj63RZp2iU-w
The full example of a COSE Key Thumbprint URI is shown below, again The full example of a COSE Key Thumbprint URI is shown below (with a
with a line-break added. line break added for readability).
urn:ietf:params:oauth:ckt:sha-256: urn:ietf:params:oauth:ckt:sha-256:
SWvYr63zB-WwjGSwQhv53AFSijRKQ72oj63RZp2iU-w
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.
6. Example 6. Example
This section demonstrates the COSE Key Thumbprint computation for the This section demonstrates the COSE Key Thumbprint computation for the
following example COSE Key containing an ECC public key. following example COSE Key containing an Elliptic Curve Cryptography
(ECC) public key.
For better readability, the example is first presented in CBOR For better readability, the example is first presented in CBOR
diagnostic format (with the long line broken for display purposes diagnostic format (with the long line broken for display purposes
only). only).
{ {
/ kty set to EC2 = Elliptic Curve Keys / / kty set to EC2 = Elliptic Curve Keys /
1:2, 1:2,
/ crv set to P-256 / / crv set to P-256 /
-1:1, -1:1,
/ public key: x-coordinate / / public key: x-coordinate /
-2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0 -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0
8551d', 8551d',
/ public key: y-coordinate / / public key: y-coordinate /
-3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008 -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008
4d19c', 4d19c',
/ kid is bstr, not used in COSE Key Thumbprint / / kid is bstr, not used in COSE Key Thumbprint /
2:h'1decade2facade3' 2:h'496bd8afadf307e5b08c64b0421bf9dc01528a344a43bda88fadd1669da2
53ec'
} }
The example above corresponds to the following CBOR encoding (with The example above corresponds to the following CBOR encoding (with
link breaks added for display purposes only): link breaks added for display purposes only):
A50102200121582065EDA5A12577C2BAE829437FE338701A10AAA375E1BB5B5DE108D A50102200121582065EDA5A12577C2BAE829437FE338701A10AAA375E1BB5B5DE108D
E439C08551D2258201E52ED75701163F7F9E40DDF9F341B3DC9BA860AF7E0CA7CA7E9 E439C08551D2258201E52ED75701163F7F9E40DDF9F341B3DC9BA860AF7E0CA7CA7E9
EECD0084D19C0258246D65726961646F632E6272616E64796275636B406275636B6C6 EECD0084D19C025820496BD8AFADF307E5B08C64B0421BF9DC01528A344A43BDA88FA
16E642E6578616D706C65 DD1669DA253EC
Not all of the parameters from the example above are used in the COSE Not all of the parameters from the example above are used in the COSE
Key Thumbprint computation since the required parameters of an Key Thumbprint computation because the required parameters of an
elliptic curve public key are (as listed in Section 4.2) "kty", elliptic curve public key are (as listed in Section 4.2) "kty",
"crv", "x", and "y". "crv", "x", and "y".
The resulting COSE Key structure, in CBOR diagnostic format with The resulting COSE Key structure, in CBOR diagnostic format with line
line-breaks added for better readability, with the minimum parameters breaks added for better readability, with the minimum parameters in
in the correct order are. the correct order are:
{ {
1:2, 1:2,
-1:1, -1:1,
-2:h'65eda5a12577c2bae829437fe338701a -2:h'65eda5a12577c2bae829437fe338701a
10aaa375e1bb5b5de108de439c08551d', 10aaa375e1bb5b5de108de439c08551d',
-3:h'1e52ed75701163f7f9e40ddf9f341b3d -3:h'1e52ed75701163f7f9e40ddf9f341b3d
c9ba860af7e0ca7ca7e9eecd0084d19c' c9ba860af7e0ca7ca7e9eecd0084d19c'
} }
In CBOR encoding the result is (with line-breaks added for display In CBOR encoding, the result is (with line breaks added for display
purposes only): purposes only):
A40102200121582065EDA5A12577C2BAE829437FE338701A10AAA375E1BB5B5DE A40102200121582065EDA5A12577C2BAE829437FE338701A10AAA375E1BB5B5DE
108DE439C08551D2258201E52ED75701163F7F9E40DDF9F341B3DC9BA860AF7E0 108DE439C08551D2258201E52ED75701163F7F9E40DDF9F341B3DC9BA860AF7E0
CA7CA7E9EECD0084D19C CA7CA7E9EECD0084D19C
Using SHA-256, the resulting thumbprint is: Using SHA-256, the resulting thumbprint is:
496bd8afadf307e5b08c64b0421bf9dc01528a344a43bda88fadd1669da253ec 496bd8afadf307e5b08c64b0421bf9dc01528a344a43bda88fadd1669da253ec
7. Security Considerations 7. Security Considerations
A COSE Key Thumbprint will only uniquely identify a particular key if A COSE Key Thumbprint will only uniquely identify a particular key if
a single unambiguous COSE Key representation for that key is defined a single unambiguous COSE Key representation for that key is defined
and used when computing the COSE Key Thumbprint.
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 and used when computing the COSE Key Thumbprint. Key identifiers are
not included in the thumbprint calculation (similarly to other not included in the thumbprint calculation (similarly to other
optional parameters in the COSE_Key structure). If the inclusion of optional parameters in the COSE_Key structure). If the inclusion of
specific optional parameters in the thumbprint calculation is specific optional parameters in the thumbprint calculation is
important for a particular application, this specification would not important for a particular application, this specification would not
be suitable. be suitable.
While thumbprint values are useful for identifying legitimate keys, While thumbprint values are useful for identifying legitimate keys,
comparing thumbprint values is not a reliable means of excluding the comparing thumbprint values is not a reliable means of excluding the
use of particular keys (or transformations thereof). The reason is use of particular keys (or transformations thereof). The reason is
that an attacker may supply a key that is a transformation of a key because an attacker may supply a key that is a transformation of a
in order to have it appear to be a different key. For instance, if 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 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 key with modulus 3*N, the modified key would still work about 1/3 of
the time, but would appear to be a different key. the time, but it would appear to be a different key.
Producing thumbprints of symmetric keys needs to be done with care. Producing thumbprints of symmetric keys needs to be done with care.
Developers MUST ensure that the symmetric key has sufficient entropy Developers MUST ensure that the symmetric key has sufficient entropy
to prevent attackers to precompute tables of symmetric keys with to prevent attackers from precomputing tables of symmetric keys with
their corresponding hash values. This can be prevented if the their corresponding hash values. This can be prevented if the
symmetric key is a randomly selected key of at least 128 bit length. symmetric key is a randomly selected key of at least a 128-bit
Thumbprints MUST NOT be used with passwords or other low-entropy length. Thumbprints MUST NOT be used with passwords or other low-
secrets. If a developer is unable to determine whether all symmetric entropy secrets. If a developer is unable to determine whether all
keys used in an application have sufficient entropy, then thumbprints symmetric keys used in an application have sufficient entropy, then
of symmetric keys MUST NOT be used. In general, using thumbprints of thumbprints of symmetric keys MUST NOT be used. In general, using
symmetric keys should only be used in special applications. In most thumbprints of symmetric keys should only be used in special
other deployment scenarios it is more appropriate to utilize a applications. In most other deployment scenarios, it is more
different naming scheme for key identifiers. appropriate to utilize a different naming scheme for key identifiers.
8. IANA Considerations 8. IANA Considerations
IANA is requested to add the following entry to the IANA "CWT IANA has added the following entry to the "CWT Confirmation Methods"
Confirmation Methods" registry established by [RFC8747]: 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: [[TBD1]]
* Confirmation Value Type(s): binary string
* Change Controller: IETF
* Specification Document(s): [[This document]]
Furthermore, IANA is requested to add a value to the IANA "OAuth URI"
registry established with [RFC6755]:
* URN: urn:ietf:params:oauth:ckt
* Common Name: COSE Key Thumbprint URI
* Change controller: IETF
* Specification Document: [[This document]]
9. Acknowledgements 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
We would like to thank the authors of [RFC7638] for their work on the Furthermore, IANA has added a value to the "OAuth URI" registry
JSON Web Key (JWK) Thumbprint specification. This document applies [IANA-OAuth] established by [RFC6755]:
JWK Thumbprints to COSE Key structures.
Additionally, we would like to thank Carsten Bormann, Ilari URN: urn:ietf:params:oauth:ckt
Liusvaara, Laurence Lundblade, Daisuke Ajitomi, Michael Richardson, Common Name: COSE Key Thumbprint URI
Michael B. Jones, Mallory Knodel, Joel Jaeggli, Derrell Piper, Change Controller: IETF
Patrik Fältström, Warren Kumari, Deb Cooley and Brendan Moran for Specification Document(s): RFC 9679
their feedback.
10. References 9. References
10.1. Normative References 9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<https://www.rfc-editor.org/rfc/rfc4648>. <https://www.rfc-editor.org/info/rfc4648>.
[RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace [RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace
for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012, for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012,
<https://www.rfc-editor.org/rfc/rfc6755>. <https://www.rfc-editor.org/info/rfc6755>.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
2015, <https://www.rfc-editor.org/rfc/rfc7515>. 2015, <https://www.rfc-editor.org/info/rfc7515>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig,
"CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392,
May 2018, <https://www.rfc-editor.org/rfc/rfc8392>. May 2018, <https://www.rfc-editor.org/info/rfc8392>.
[RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H. [RFC8747] Jones, M., Seitz, L., Selander, G., Erdtman, S., and H.
Tschofenig, "Proof-of-Possession Key Semantics for CBOR Tschofenig, "Proof-of-Possession Key Semantics for CBOR
Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March Web Tokens (CWTs)", RFC 8747, DOI 10.17487/RFC8747, March
2020, <https://www.rfc-editor.org/rfc/rfc8747>. 2020, <https://www.rfc-editor.org/info/rfc8747>.
[RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", STD 94, RFC 8949, Representation (CBOR)", STD 94, RFC 8949,
DOI 10.17487/RFC8949, December 2020, DOI 10.17487/RFC8949, December 2020,
<https://www.rfc-editor.org/rfc/rfc8949>. <https://www.rfc-editor.org/info/rfc8949>.
[RFC9052] Schaad, J., "CBOR Object Signing and Encryption (COSE): [RFC9052] Schaad, J., "CBOR Object Signing and Encryption (COSE):
Structures and Process", STD 96, RFC 9052, Structures and Process", STD 96, RFC 9052,
DOI 10.17487/RFC9052, August 2022, DOI 10.17487/RFC9052, August 2022,
<https://www.rfc-editor.org/rfc/rfc9052>. <https://www.rfc-editor.org/info/rfc9052>.
[RFC9053] Schaad, J., "CBOR Object Signing and Encryption (COSE): [RFC9053] Schaad, J., "CBOR Object Signing and Encryption (COSE):
Initial Algorithms", RFC 9053, DOI 10.17487/RFC9053, Initial Algorithms", RFC 9053, DOI 10.17487/RFC9053,
August 2022, <https://www.rfc-editor.org/rfc/rfc9053>. August 2022, <https://www.rfc-editor.org/info/rfc9053>.
10.2. Informative References 9.2. Informative References
[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.Hash.Algorithms]
"Named Information Hash Algorithm Registry", IANA, "Named Information Hash Algorithm Registry",
<https://www.iana.org/assignments/named-information>. <https://www.iana.org/assignments/named-information>.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
<https://www.rfc-editor.org/rfc/rfc5280>. <https://www.rfc-editor.org/info/rfc5280>.
[RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms
(SHA and SHA-based HMAC and HKDF)", RFC 6234, (SHA and SHA-based HMAC and HKDF)", RFC 6234,
DOI 10.17487/RFC6234, May 2011, DOI 10.17487/RFC6234, May 2011,
<https://www.rfc-editor.org/rfc/rfc6234>. <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) [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK)
Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September
2015, <https://www.rfc-editor.org/rfc/rfc7638>. 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, [RFC9278] Jones, M. and K. Yasuda, "JWK Thumbprint URI", RFC 9278,
DOI 10.17487/RFC9278, August 2022, DOI 10.17487/RFC9278, August 2022,
<https://www.rfc-editor.org/rfc/rfc9278>. <https://www.rfc-editor.org/info/rfc9278>.
[RFC9360] Schaad, J., "CBOR Object Signing and Encryption (COSE): [RFC9360] Schaad, J., "CBOR Object Signing and Encryption (COSE):
Header Parameters for Carrying and Referencing X.509 Header Parameters for Carrying and Referencing X.509
Certificates", RFC 9360, DOI 10.17487/RFC9360, February Certificates", RFC 9360, DOI 10.17487/RFC9360, February
2023, <https://www.rfc-editor.org/rfc/rfc9360>. 2023, <https://www.rfc-editor.org/info/rfc9360>.
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 Authors' Addresses
Kohei Isobe Kohei Isobe
SECOM CO., LTD. SECOM CO., LTD.
Japan
Email: isobekohei@gmail.com Email: isobekohei@gmail.com
Hannes Tschofenig Hannes Tschofenig
University of Applied Sciences Bonn-Rhein-Sieg University of Applied Sciences Bonn-Rhein-Sieg
Germany Germany
Email: hannes.tschofenig@gmx.net Email: hannes.tschofenig@gmx.net
Orie Steele Orie Steele
Transmute Transmute
United States United States of America
Email: orie@transmute.industries Email: orie@transmute.industries
 End of changes. 80 change blocks. 
207 lines changed or deleted 232 lines changed or added

This html diff was produced by rfcdiff 1.48.