CBOR Object Signing and Encryption (COSE) Key Thumbprint
draft-ietf-cose-key-thumbprint-02

COSE                                                            K. Isobe
Internet-Draft                                           SECOM CO., LTD.
Intended status: Standards Track                           H. Tschofenig
Expires: 7 April 2024                                     5 October 2023

        CBOR Object Signing and Encryption (COSE) Key Thumbprint
                   draft-ietf-cose-key-thumbprint-02

Abstract

   This specification defines a method for computing a hash value over a
   COSE Key. It defines which fields in a COSE Key structure are used in
   the hash computation, the method of creating a canonical form of the
   fields, and how to hash the byte sequence.  The resulting hash value
   can be used for identifying or selecting a key that is the subject of
   the thumbprint.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   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
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 7 April 2024.

Copyright Notice

   Copyright (c) 2023 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.

Isobe & Tschofenig        Expires 7 April 2024                  [Page 1]
Internet-Draft             COSE Key Thumbprint              October 2023

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
   3.  COSE Key Thumbprint . . . . . . . . . . . . . . . . . . . . .   3
   4.  Required COSE Key Parameters  . . . . . . . . . . . . . . . .   3
     4.1.  Octet Key Pair (OKP)  . . . . . . . . . . . . . . . . . .   3
     4.2.  Elliptic Curve Keys w/ x- and y-coordinate pair . . . . .   4
     4.3.  RSA Public Keys . . . . . . . . . . . . . . . . . . . . .   4
     4.4.  Symmetric Keys  . . . . . . . . . . . . . . . . . . . . .   4
     4.5.  HSS-LMS . . . . . . . . . . . . . . . . . . . . . . . . .   5
     4.6.  Others  . . . . . . . . . . . . . . . . . . . . . . . . .   5
   5.  Miscellaneous Considerations  . . . . . . . . . . . . . . . .   5
     5.1.  Why Not Include Optional COSE Key Parameters? . . . . . .   5
     5.2.  Selection of Hash Function  . . . . . . . . . . . . . . .   6
     5.3.  Thumbprints of Keys Not in COSE Key Format  . . . . . . .   6
     5.4.  Relationship to Digests of X.509 Values . . . . . . . . .   6
     5.5.  Confirmation Methods  . . . . . . . . . . . . . . . . . .   6
   6.  Example . . . . . . . . . . . . . . . . . . . . . . . . . . .   7
   7.  Security Considerations . . . . . . . . . . . . . . . . . . .   9
   8.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  10
   9.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  11
   10. References  . . . . . . . . . . . . . . . . . . . . . . . . .  11
     10.1.  Normative References . . . . . . . . . . . . . . . . . .  11
     10.2.  Informative References . . . . . . . . . . . . . . . . .  11
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  12

1.  Introduction

   This specification defines a method for computing a hash value
   (a.k.a. digest) over a COSE Key structure [RFC9052].  It defines
   which fields in a COSE Key structure are used in the hash
   computation, the method of creating a canonical form for those
   fields, and how to hash the byte sequence.  The resulting hash value
   can be used for identifying or selecting the key that is the subject
   of the thumbprint, for instance, by using the COSE Key Thumbprint
   value as a "kid" (key ID) value.

   This specification defines how thumbprints of COSE keys are created.
   Additionally, a new CWT confirmation method is registered in the
   registry created by [RFC8747].  See Section 3.1 of [RFC8747] for
   details about the use of a confirmation claim in a CWT with a proof-
   of-possession key.

Isobe & Tschofenig        Expires 7 April 2024                  [Page 2]
Internet-Draft             COSE Key Thumbprint              October 2023

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.
       This specification describes what those required parameters are
       and what, if necessary, what the unique encoding is.

   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 resulting value is the COSE Key Thumbprint with H of the COSE
   Key. The details of this computation are further described in
   subsequent sections.

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 found 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 depend on the chosen key type.  The
   subsection below list the required parameters for commonly used key
   types.

4.1.  Octet Key Pair (OKP)

   The required parameters for elliptic curve public keys that use the
   OKP key type, such as X25519, are:

   *  "kty" (label: 1, data type: int, value: 1)

Isobe & Tschofenig        Expires 7 April 2024                  [Page 3]
Internet-Draft             COSE Key Thumbprint              October 2023

   *  "crv" (label: -1, value: int)

   *  "x" (label: -2, value: bstr)

   Details can be found in Section 7.1 of [RFC9053].

4.2.  Elliptic Curve Keys w/ x- and y-coordinate pair

   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)

   Details can be found in Section 7.1 of [RFC9053].

   Note: [RFC9052] offers both compressed as well as uncompressed point
   representations.  For interoperability, implementations following
   this specification MUST use the uncompressed point representation.
   Hence, the y-coordinate is expressed as a bstr.  An implementation
   that uses the compressed point representation MUST compute the
   uncompressed representation for the purpose of the thumbprint
   calculation.

4.3.  RSA Public Keys

   The required parameters for an RSA public key are:

   *  "kty" (label: 1, data type: int, value: 3)

   *  "n" (label: -1, data type: bstr)

   *  "e" (label: -2, data type: bstr)

4.4.  Symmetric Keys

   The required parameters for a symmetric key are:

   *  "kty" (label: 1, data type: int, value: 4)

   *  "k" (label: -1, data type: bstr)

Isobe & Tschofenig        Expires 7 April 2024                  [Page 4]
Internet-Draft             COSE Key Thumbprint              October 2023

4.5.  HSS-LMS

   The required parameters for HSS-LMS keys are:

   *  "kty" (label: 1, data type: int, value: 5)

   *  "pub" (label: -1, data type: bstr)

4.6.  Others

   As other key type values are defined, the specifications defining
   them should be similarly consulted to determine which parameters, in
   addition to the "kty" element, are required.

5.  Miscellaneous Considerations

5.1.  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 value is a digest of the parameters required to represent
   the key as a COSE Key -- not of additional data that may also
   accompany the key.

   Optional parameters are not included so that the COSE Key Thumbprint
   refers to a key -- not a key with an associated set of key
   attributes.  Different application contexts might or might not
   include different subsets of optional attributes about the key in the
   COSE Key structure.  If these were included in the calculation of the
   COSE Key Thumbprint, the values would be different for those COSE
   Keys, even though the keys are the same.  The benefit of including
   only the required parameters is that the COSE Key Thumbprint of any
   COSE Key representing the key remains the same, regardless of any
   other attributes that are present.

   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.

Isobe & Tschofenig        Expires 7 April 2024                  [Page 5]
Internet-Draft             COSE Key Thumbprint              October 2023

5.2.  Selection of Hash Function

   A specific hash function must be chosen by an application to compute
   the hash value of the hash input.  For example, SHA-256 [RFC6234]
   might be used as the hash function by the application.  While SHA-256
   is a good default choice at the time of writing, the hash function of
   choice can be expected to change over time as the cryptographic
   landscape evolves.

   Note that in many cases, only the party that creates a key will need
   to know the hash function used.  A typical usage is for the producer
   of the key to use the thumbprint value as a "kid" (key ID) value.  In
   this case, the consumer of the "kid" treats it as an opaque value
   that it uses to select the key.

   However, in some cases, multiple parties will be reproducing the COSE
   Key Thumbprint calculation and comparing the results.  In these
   cases, the parties will need to know which hash function was used and
   use the same one.

5.3.  Thumbprints of Keys Not in COSE Key Format

   A key need not be in COSE Key format to create a COSE Key Thumbprint
   of it.  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.

5.4.  Relationship to Digests of X.509 Values

   COSE Key Thumbprint values are computed on the COSE Key element
   required to represent a key, rather than all members of a COSE Key
   that the key is represented in.  Thus, they are more analogous to
   applications that use digests of X.509 Subject Public Key Info (SPKI)
   values, which are defined in Section 4.1.2.7 of [RFC5280], than to
   applications that use digests of complete certificate values, as the
   "x5t" (X.509 certificate SHA-1 thumbprint) [RFC9360] 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.

5.5.  Confirmation Methods

   [RFC8747] introduced confirmation methods for use with CBOR Web
   Tokens (CWTs).  CWTs have been defined in [RFC8392].  This
   specification adds a new confirmation method based on COSE Key
   Thumbprints.

Isobe & Tschofenig        Expires 7 April 2024                  [Page 6]
Internet-Draft             COSE Key Thumbprint              October 2023

   The proof-of-possession key is identified using the "ckt" claim, the
   COSE Key Thumbprint claim.  This claim 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" claim.  In this case, 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
   CWT (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/ [[TBD2]] : h'496bd8afadf307e5b08c64b0421bf9dc
                     01528a344a43bda88fadd1669da253ec'
        }
      }

   Section 8 registers the "ckt" claim and the confirmation method.  The
   "ckt" claim is expected to be used in the "cnf" claim.

6.  Example

   This section demonstrates the COSE Key Thumbprint computation for the
   following example COSE Key containing an ECC public key.

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

Isobe & Tschofenig        Expires 7 April 2024                  [Page 7]
Internet-Draft             COSE Key Thumbprint              October 2023

     {
       / 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 /
       2:'meriadoc.brandybuck@buckland.example'
     }

   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 since the required parameters of an elliptic curve
   public key are:

   *  "kty"

   *  "crv"

   *  "x"

   *  "y"

   The required order based on Section 4.2.1 of [RFC8949] is:

   *  "y" (label: -3, data type: bstr)

   *  "x" (label: -2, data type: bstr)

   *  "crv" (label: -1, data type: int)

   *  "kty" (label: 1, data type: int)

   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.

Isobe & Tschofenig        Expires 7 April 2024                  [Page 8]
Internet-Draft             COSE Key Thumbprint              October 2023

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

   If two asymmetric keys are used by different parties with different
   key identifiers then the COSE Key Thumbprints will still be equal
   since the key identifier itself is not included in the thumbprint
   calculation (similarly to other optional parameters in the COSE_Key
   structure).  When the inclusion of certain optional parameters in the
   thumbprint calcuation is important for a given application, this
   specification is not the appropriate choice.

   To promote interoperability among implementations, the SHA-256 hash
   algorithm is mandatory to implement.

   While thumbprint values are valuable 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
   that an attacker may supply a key that is a transformation of a key
   in order to have it appear to be 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 would appear to be a different key.

Isobe & Tschofenig        Expires 7 April 2024                  [Page 9]
Internet-Draft             COSE Key Thumbprint              October 2023

   Producing thumbprints of symmetric keys needs to be done with care.
   Developers MUST ensure that the symmetric key has sufficient entropy
   to prevent attackers to precompute 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 128 bit length.
   Using thumbprints with passwords (i.e. low-entropy secrets) is
   dangerous and MUST be avoided.  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 is requested to add the following entry to the "CWT Confirmation
   Methods" registry established by [RFC8747]:

   *  Confirmation Method Name: ckt

   *  Confirmation Method Description: COSE Key Thumbprint

   *  JWT Confirmation Method Name: ckt

   *  Confirmation Key: [[TBD1]]

   *  Confirmation Value Type(s): binary string

   *  Change Controller: IESG

   *  Specification Document(s): [[This document]]

   IANA is furthermore asked to register the "ckt" claim to the "CBOR
   Web Token (CWT) Claims" registry created by [RFC8392]:

   *  Claim Name: ckt

   *  Claim Description: COSE Key Thumbprint

   *  JWT Claim Name: ckt

   *  Claim Key: TBD1

   *  Claim Value Type(s): byte string

   *  Change Controller: IESG

   *  Specification Document(s): [[This specification]]

Isobe & Tschofenig        Expires 7 April 2024                 [Page 10]
Internet-Draft             COSE Key Thumbprint              October 2023

9.  Acknowledgements

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

   Additionally, we would like to thank Carsten Bormann, Orie Steele,
   Ilari Liusvaara, Laurence Lundblade, Daisuke Ajitomi, Michael
   Richardson, Mike Jones, and Brendan Moran for their feedback.

10.  References

10.1.  Normative References

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

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

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

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

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

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

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

10.2.  Informative References

Isobe & Tschofenig        Expires 7 April 2024                 [Page 11]
Internet-Draft             COSE Key Thumbprint              October 2023

   [RFC5280]  Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
              Housley, R., and W. Polk, "Internet X.509 Public Key
              Infrastructure Certificate and Certificate Revocation List
              (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
              <https://www.rfc-editor.org/rfc/rfc5280>.

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

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

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

Authors' Addresses

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

   Hannes Tschofenig
   Email: hannes.tschofenig@gmx.net

Isobe & Tschofenig        Expires 7 April 2024                 [Page 12]