idnits 2.17.1 draft-ietf-cose-rfc8152bis-algs-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([I-D.schaad-cose-RFC8152bis-struct]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 14, 2019) is 1897 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'AES-GCM' -- Possible downref: Non-RFC (?) normative reference: ref. 'DSS' -- Possible downref: Normative reference to a draft: ref. 'I-D.schaad-cose-rfc8152bis-struct' -- Possible downref: Non-RFC (?) normative reference: ref. 'MAC' ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Downref: Normative reference to an Informational RFC: RFC 3394 ** Downref: Normative reference to an Informational RFC: RFC 3610 ** Downref: Normative reference to an Informational RFC: RFC 5869 ** Downref: Normative reference to an Informational RFC: RFC 6090 ** Downref: Normative reference to an Informational RFC: RFC 6979 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Downref: Normative reference to an Informational RFC: RFC 7748 ** Downref: Normative reference to an Informational RFC: RFC 8032 ** Downref: Normative reference to an Informational RFC: RFC 8439 -- Possible downref: Non-RFC (?) normative reference: ref. 'SEC1' == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-07 -- Obsolete informational reference (is this intentional?): RFC 8152 (Obsoleted by RFC 9052, RFC 9053) Summary: 11 errors (**), 0 flaws (~~), 2 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 COSE Working Group J. Schaad 3 Internet-Draft August Cellars 4 Obsoletes: 8152 (if approved) February 14, 2019 5 Intended status: Standards Track 6 Expires: August 18, 2019 8 CBOR Algorithms for Object Signing and Encryption (COSE) 9 draft-ietf-cose-rfc8152bis-algs-01 11 Abstract 13 Concise Binary Object Representation (CBOR) is a data format designed 14 for small code size and small message size. There is a need for the 15 ability to have basic security services defined for this data format. 16 This document defines the CBOR Object Signing and Encryption (COSE) 17 protocol. This specification describes how to create and process 18 signatures, message authentication codes, and encryption using CBOR 19 for serialization. COSE additionally describes how to represent 20 cryptographic keys using CBOR. 22 In this specification the conventions for the use of a number of 23 cryptographic algorithms with COSE. The details of the structure of 24 COSE are defined in [I-D.schaad-cose-rfc8152bis-struct]. 26 This document along with [I-D.schaad-cose-rfc8152bis-struct] 27 obsoletes RFC8152. 29 Contributing to this document 31 The source for this draft is being maintained in GitHub. Suggested 32 changes should be submitted as pull requests at . Instructions are on that page as well. 34 Editorial changes can be managed in GitHub, but any substantial 35 issues need to be discussed on the COSE mailing list. 37 Status of This Memo 39 This Internet-Draft is submitted in full conformance with the 40 provisions of BCP 78 and BCP 79. 42 Internet-Drafts are working documents of the Internet Engineering 43 Task Force (IETF). Note that other groups may also distribute 44 working documents as Internet-Drafts. The list of current Internet- 45 Drafts is at https://datatracker.ietf.org/drafts/current/. 47 Internet-Drafts are draft documents valid for a maximum of six months 48 and may be updated, replaced, or obsoleted by other documents at any 49 time. It is inappropriate to use Internet-Drafts as reference 50 material or to cite them other than as "work in progress." 52 This Internet-Draft will expire on August 18, 2019. 54 Copyright Notice 56 Copyright (c) 2019 IETF Trust and the persons identified as the 57 document authors. All rights reserved. 59 This document is subject to BCP 78 and the IETF Trust's Legal 60 Provisions Relating to IETF Documents 61 (https://trustee.ietf.org/license-info) in effect on the date of 62 publication of this document. Please review these documents 63 carefully, as they describe your rights and restrictions with respect 64 to this document. Code Components extracted from this document must 65 include Simplified BSD License text as described in Section 4.e of 66 the Trust Legal Provisions and are provided without warranty as 67 described in the Simplified BSD License. 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 72 1.1. Requirements Terminology . . . . . . . . . . . . . . . . 4 73 1.2. Changes from RFC8152 . . . . . . . . . . . . . . . . . . 4 74 1.3. Document Terminology . . . . . . . . . . . . . . . . . . 4 75 1.4. CBOR Grammar . . . . . . . . . . . . . . . . . . . . . . 4 76 2. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 4 77 2.1. ECDSA . . . . . . . . . . . . . . . . . . . . . . . . . . 5 78 2.1.1. Security Considerations . . . . . . . . . . . . . . . 6 79 2.2. Edwards-Curve Digital Signature Algorithms (EdDSAs) . . . 7 80 2.2.1. Security Considerations . . . . . . . . . . . . . . . 8 81 3. Message Authentication Code (MAC) Algorithms . . . . . . . . 8 82 3.1. Hash-Based Message Authentication Codes (HMACs) . . . . . 8 83 3.1.1. Security Considerations . . . . . . . . . . . . . . . 10 84 3.2. AES Message Authentication Code (AES-CBC-MAC) . . . . . . 10 85 3.2.1. Security Considerations . . . . . . . . . . . . . . . 11 86 4. Content Encryption Algorithms . . . . . . . . . . . . . . . . 11 87 4.1. AES GCM . . . . . . . . . . . . . . . . . . . . . . . . . 11 88 4.1.1. Security Considerations . . . . . . . . . . . . . . . 12 89 4.2. AES CCM . . . . . . . . . . . . . . . . . . . . . . . . . 13 90 4.2.1. Security Considerations . . . . . . . . . . . . . . . 15 91 4.3. ChaCha20 and Poly1305 . . . . . . . . . . . . . . . . . . 15 92 4.3.1. Security Considerations . . . . . . . . . . . . . . . 16 93 5. Key Derivation Functions (KDFs) . . . . . . . . . . . . . . . 16 94 5.1. HMAC-Based Extract-and-Expand Key Derivation Function 95 (HKDF) . . . . . . . . . . . . . . . . . . . . . . . . . 16 96 5.2. Context Information Structure . . . . . . . . . . . . . . 18 98 6. Content Key Distribution Methods . . . . . . . . . . . . . . 23 99 6.1. Direct Key . . . . . . . . . . . . . . . . . . . . . . . 23 100 6.1.1. Security Considerations . . . . . . . . . . . . . . . 24 101 6.2. Direct Key with KDF . . . . . . . . . . . . . . . . . . . 24 102 6.2.1. Security Considerations . . . . . . . . . . . . . . . 25 103 6.3. AES Key Wrap . . . . . . . . . . . . . . . . . . . . . . 26 104 6.3.1. Security Considerations for AES-KW . . . . . . . . . 27 105 6.4. Direct ECDH . . . . . . . . . . . . . . . . . . . . . . . 27 106 6.4.1. Security Considerations . . . . . . . . . . . . . . . 29 107 6.5. ECDH with Key Wrap . . . . . . . . . . . . . . . . . . . 30 108 7. Key Object Parameters . . . . . . . . . . . . . . . . . . . . 32 109 7.1. Elliptic Curve Keys . . . . . . . . . . . . . . . . . . . 32 110 7.1.1. Double Coordinate Curves . . . . . . . . . . . . . . 33 111 7.2. Octet Key Pair . . . . . . . . . . . . . . . . . . . . . 34 112 7.3. Symmetric Keys . . . . . . . . . . . . . . . . . . . . . 35 113 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 114 8.1. COSE Algorithms Registry . . . . . . . . . . . . . . . . 35 115 8.2. COSE Key Type Parameters Registry . . . . . . . . . . . . 36 116 8.3. COSE Key Types Registry . . . . . . . . . . . . . . . . . 36 117 8.4. COSE Elliptic Curves Registry . . . . . . . . . . . . . . 37 118 8.5. Expert Review Instructions . . . . . . . . . . . . . . . 37 119 9. Security Considerations . . . . . . . . . . . . . . . . . . . 38 120 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 40 121 10.1. Normative References . . . . . . . . . . . . . . . . . . 40 122 10.2. Informative References . . . . . . . . . . . . . . . . . 42 123 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 43 124 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 43 125 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 44 127 1. Introduction 129 There has been an increased focus on small, constrained devices that 130 make up the Internet of Things (IoT). One of the standards that has 131 come out of this process is "Concise Binary Object Representation 132 (CBOR)" [RFC7049]. CBOR extended the data model of the JavaScript 133 Object Notation (JSON) [RFC8259] by allowing for binary data, among 134 other changes. CBOR is being adopted by several of the IETF working 135 groups dealing with the IoT world as their encoding of data 136 structures. CBOR was designed specifically to be both small in terms 137 of messages transport and implementation size and be a schema-free 138 decoder. A need exists to provide message security services for IoT, 139 and using CBOR as the message-encoding format makes sense. 141 The core COSE specification consists of two documents. 142 [I-D.schaad-cose-rfc8152bis-struct] contains the serialization 143 structures and the procedures for using the different cryptographic 144 algorithms. This document provides for an initial set of algorithms 145 that are then use with those structures. Additional algorithms 146 beyond what are in this document are defined elsewhere. 148 1.1. Requirements Terminology 150 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 151 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 152 "OPTIONAL" in this document are to be interpreted as described in BCP 153 14 [RFC2119] [RFC8174] when, and only when, they appear in all 154 capitals, as shown here. 156 1.2. Changes from RFC8152 158 TBD 160 1.3. Document Terminology 162 In this document, we use the following terminology: 164 Byte is a synonym for octet. 166 Constrained Application Protocol (CoAP) is a specialized web transfer 167 protocol for use in constrained systems. It is defined in [RFC7252]. 169 Authenticated Encryption (AE) [RFC5116] algorithms are those 170 encryption algorithms that provide an authentication check of the 171 plain text contents as part of the encryption service. 173 Authenticated Encryption with Authenticated Data (AEAD) [RFC5116] 174 algorithms provide the same content authentication service as AE 175 algorithms, but they additionally provide for authentication of non- 176 encrypted data as well. 178 1.4. CBOR Grammar 180 At the time that [RFC8152] was initially published, the CBOR Data 181 Definition Language (CDDL) [I-D.ietf-cbor-cddl] had not yet been 182 published. This document uses a variant of CDDL which is described 183 in [I-D.schaad-cose-rfc8152bis-struct] 185 2. Signature Algorithms 187 The document defines signature algorithm identifiers for two 188 signature algorithms. 190 2.1. ECDSA 192 ECDSA [DSS] defines a signature algorithm using ECC. Implementations 193 SHOULD use a deterministic version of ECDSA such as the one defined 194 in [RFC6979]. The use of a deterministic signature algorithm allows 195 for systems to avoid relying on random number generators in order to 196 avoid generating the same value of 'k' (the per-message random 197 value). Biased generation of the value 'k' can be attacked, and 198 collisions of this value leads to leaked keys. It additionally 199 allows for doing deterministic tests for the signature algorithm. 200 The use of deterministic ECDSA does not lessen the need to have good 201 random number generation when creating the private key. 203 The ECDSA signature algorithm is parameterized with a hash function 204 (h). In the event that the length of the hash function output is 205 greater than the group of the key, the leftmost bytes of the hash 206 output are used. 208 The algorithms defined in this document can be found in Table 1. 210 +-------+-------+---------+------------------+ 211 | Name | Value | Hash | Description | 212 +-------+-------+---------+------------------+ 213 | ES256 | -7 | SHA-256 | ECDSA w/ SHA-256 | 214 | ES384 | -35 | SHA-384 | ECDSA w/ SHA-384 | 215 | ES512 | -36 | SHA-512 | ECDSA w/ SHA-512 | 216 +-------+-------+---------+------------------+ 218 Table 1: ECDSA Algorithm Values 220 This document defines ECDSA to work only with the curves P-256, 221 P-384, and P-521. This document requires that the curves be encoded 222 using the 'EC2' (2 coordinate elliptic curve) key type. 223 Implementations need to check that the key type and curve are correct 224 when creating and verifying a signature. Other documents can define 225 it to work with other curves and points in the future. 227 In order to promote interoperability, it is suggested that SHA-256 be 228 used only with curve P-256, SHA-384 be used only with curve P-384, 229 and SHA-512 be used with curve P-521. This is aligned with the 230 recommendation in Section 4 of [RFC5480]. 232 The signature algorithm results in a pair of integers (R, S). These 233 integers will be the same length as the length of the key used for 234 the signature process. The signature is encoded by converting the 235 integers into byte strings of the same length as the key size. The 236 length is rounded up to the nearest byte and is left padded with zero 237 bits to get to the correct length. The two integers are then 238 concatenated together to form a byte string that is the resulting 239 signature. 241 Using the function defined in [RFC8017], the signature is: 243 Signature = I2OSP(R, n) | I2OSP(S, n) 244 where n = ceiling(key_length / 8) 246 When using a COSE key for this algorithm, the following checks are 247 made: 249 o The 'kty' field MUST be present, and it MUST be 'EC2'. 251 o If the 'alg' field is present, it MUST match the ECDSA signature 252 algorithm being used. 254 o If the 'key_ops' field is present, it MUST include 'sign' when 255 creating an ECDSA signature. 257 o If the 'key_ops' field is present, it MUST include 'verify' when 258 verifying an ECDSA signature. 260 2.1.1. Security Considerations 262 The security strength of the signature is no greater than the minimum 263 of the security strength associated with the bit length of the key 264 and the security strength of the hash function. 266 Note: Use of a deterministic signature technique is a good idea even 267 when good random number generation exists. Doing so both reduces the 268 possibility of having the same value of 'k' in two signature 269 operations and allows for reproducible signature values, which helps 270 testing. 272 There are two substitution attacks that can theoretically be mounted 273 against the ECDSA signature algorithm. 275 o Changing the curve used to validate the signature: If one changes 276 the curve used to validate the signature, then potentially one 277 could have two messages with the same signature, each computed 278 under a different curve. The only requirement on the new curve is 279 that its order be the same as the old one and it be acceptable to 280 the client. An example would be to change from using the curve 281 secp256r1 (aka P-256) to using secp256k1. (Both are 256-bit 282 curves.) We currently do not have any way to deal with this 283 version of the attack except to restrict the overall set of curves 284 that can be used. 286 o Change the hash function used to validate the signature: If one 287 either has two different hash functions of the same length or can 288 truncate a hash function down, then one could potentially find 289 collisions between the hash functions rather than within a single 290 hash function (for example, truncating SHA-512 to 256 bits might 291 collide with a SHA-256 bit hash value). As the hash algorithm is 292 part of the signature algorithm identifier, this attack is 293 mitigated by including a signature algorithm identifier in the 294 protected header. 296 2.2. Edwards-Curve Digital Signature Algorithms (EdDSAs) 298 [RFC8032] describes the elliptic curve signature scheme Edwards-curve 299 Digital Signature Algorithm (EdDSA). In that document, the signature 300 algorithm is instantiated using parameters for edwards25519 and 301 edwards448 curves. The document additionally describes two variants 302 of the EdDSA algorithm: Pure EdDSA, where no hash function is applied 303 to the content before signing, and HashEdDSA, where a hash function 304 is applied to the content before signing and the result of that hash 305 function is signed. For EdDSA, the content to be signed (either the 306 message or the pre-hash value) is processed twice inside of the 307 signature algorithm. For use with COSE, only the pure EdDSA version 308 is used. This is because it is not expected that extremely large 309 contents are going to be needed and, based on the arrangement of the 310 message structure, the entire message is going to need to be held in 311 memory in order to create or verify a signature. This means that 312 there does not appear to be a need to be able to do block updates of 313 the hash, followed by eliminating the message from memory. 314 Applications can provide the same features by defining the content of 315 the message as a hash value and transporting the COSE object (with 316 the hash value) and the content as separate items. 318 The algorithms defined in this document can be found in Table 2. A 319 single signature algorithm is defined, which can be used for multiple 320 curves. 322 +-------+-------+-------------+ 323 | Name | Value | Description | 324 +-------+-------+-------------+ 325 | EdDSA | -8 | EdDSA | 326 +-------+-------+-------------+ 328 Table 2: EdDSA Algorithm Values 330 [RFC8032] describes the method of encoding the signature value. 332 When using a COSE key for this algorithm, the following checks are 333 made: 335 o The 'kty' field MUST be present, and it MUST be 'OKP' (Octet Key 336 Pair). 338 o The 'crv' field MUST be present, and it MUST be a curve defined 339 for this signature algorithm. 341 o If the 'alg' field is present, it MUST match 'EdDSA'. 343 o If the 'key_ops' field is present, it MUST include 'sign' when 344 creating an EdDSA signature. 346 o If the 'key_ops' field is present, it MUST include 'verify' when 347 verifying an EdDSA signature. 349 2.2.1. Security Considerations 351 How public values are computed is not the same when looking at EdDSA 352 and Elliptic Curve Diffie-Hellman (ECDH); for this reason, they 353 should not be used with the other algorithm. 355 If batch signature verification is performed, a well-seeded 356 cryptographic random number generator is REQUIRED. Signing and non- 357 batch signature verification are deterministic operations and do not 358 need random numbers of any kind. 360 3. Message Authentication Code (MAC) Algorithms 362 This section defines the usages for two MAC algorithms. 364 3.1. Hash-Based Message Authentication Codes (HMACs) 366 HMAC [RFC2104] [RFC4231] was designed to deal with length extension 367 attacks. The algorithm was also designed to allow for new hash 368 algorithms to be directly plugged in without changes to the hash 369 function. The HMAC design process has been shown as solid since, 370 while the security of hash algorithms such as MD5 has decreased over 371 time; the security of HMAC combined with MD5 has not yet been shown 372 to be compromised [RFC6151]. 374 The HMAC algorithm is parameterized by an inner and outer padding, a 375 hash function (h), and an authentication tag value length. For this 376 specification, the inner and outer padding are fixed to the values 377 set in [RFC2104]. The length of the authentication tag corresponds 378 to the difficulty of producing a forgery. For use in constrained 379 environments, we define one HMAC algorithms that is truncated. There 380 are currently no known issues with truncation; however, the security 381 strength of the message tag is correspondingly reduced in strength. 383 When truncating, the leftmost tag length bits are kept and 384 transmitted. 386 The algorithms defined in this document can be found in Table 3. 388 +-----------+-------+---------+----------+--------------------------+ 389 | Name | Value | Hash | Tag | Description | 390 | | | | Length | | 391 +-----------+-------+---------+----------+--------------------------+ 392 | HMAC | 4 | SHA-256 | 64 | HMAC w/ SHA-256 | 393 | 256/64 | | | | truncated to 64 bits | 394 | HMAC | 5 | SHA-256 | 256 | HMAC w/ SHA-256 | 395 | 256/256 | | | | | 396 | HMAC | 6 | SHA-384 | 384 | HMAC w/ SHA-384 | 397 | 384/384 | | | | | 398 | HMAC | 7 | SHA-512 | 512 | HMAC w/ SHA-512 | 399 | 512/512 | | | | | 400 +-----------+-------+---------+----------+--------------------------+ 402 Table 3: HMAC Algorithm Values 404 Some recipient algorithms carry the key while others derive a key 405 from secret data. For those algorithms that carry the key (such as 406 AES Key Wrap), the size of the HMAC key SHOULD be the same size as 407 the underlying hash function. For those algorithms that derive the 408 key (such as ECDH), the derived key MUST be the same size as the 409 underlying hash function. 411 When using a COSE key for this algorithm, the following checks are 412 made: 414 o The 'kty' field MUST be present, and it MUST be 'Symmetric'. 416 o If the 'alg' field is present, it MUST match the HMAC algorithm 417 being used. 419 o If the 'key_ops' field is present, it MUST include 'MAC create' 420 when creating an HMAC authentication tag. 422 o If the 'key_ops' field is present, it MUST include 'MAC verify' 423 when verifying an HMAC authentication tag. 425 Implementations creating and validating MAC values MUST validate that 426 the key type, key length, and algorithm are correct and appropriate 427 for the entities involved. 429 3.1.1. Security Considerations 431 HMAC has proved to be resistant to attack even when used with 432 weakened hash algorithms. The current best known attack is to brute 433 force the key. This means that key size is going to be directly 434 related to the security of an HMAC operation. 436 3.2. AES Message Authentication Code (AES-CBC-MAC) 438 AES-CBC-MAC is defined in [MAC]. (Note that this is not the same 439 algorithm as AES Cipher-Based Message Authentication Code (AES-CMAC) 440 [RFC4493].) 442 AES-CBC-MAC is parameterized by the key length, the authentication 443 tag length, and the IV used. For all of these algorithms, the IV is 444 fixed to all zeros. We provide an array of algorithms for various 445 key lengths and tag lengths. The algorithms defined in this document 446 are found in Table 4. 448 +-------------+-------+----------+----------+-----------------------+ 449 | Name | Value | Key | Tag | Description | 450 | | | Length | Length | | 451 +-------------+-------+----------+----------+-----------------------+ 452 | AES-MAC | 14 | 128 | 64 | AES-MAC 128-bit key, | 453 | 128/64 | | | | 64-bit tag | 454 | AES-MAC | 15 | 256 | 64 | AES-MAC 256-bit key, | 455 | 256/64 | | | | 64-bit tag | 456 | AES-MAC | 25 | 128 | 128 | AES-MAC 128-bit key, | 457 | 128/128 | | | | 128-bit tag | 458 | AES-MAC | 26 | 256 | 128 | AES-MAC 256-bit key, | 459 | 256/128 | | | | 128-bit tag | 460 +-------------+-------+----------+----------+-----------------------+ 462 Table 4: AES-MAC Algorithm Values 464 Keys may be obtained either from a key structure or from a recipient 465 structure. Implementations creating and validating MAC values MUST 466 validate that the key type, key length, and algorithm are correct and 467 appropriate for the entities involved. 469 When using a COSE key for this algorithm, the following checks are 470 made: 472 o The 'kty' field MUST be present, and it MUST be 'Symmetric'. 474 o If the 'alg' field is present, it MUST match the AES-MAC algorithm 475 being used. 477 o If the 'key_ops' field is present, it MUST include 'MAC create' 478 when creating an AES-MAC authentication tag. 480 o If the 'key_ops' field is present, it MUST include 'MAC verify' 481 when verifying an AES-MAC authentication tag. 483 3.2.1. Security Considerations 485 A number of attacks exist against Cipher Block Chaining Message 486 Authentication Code (CBC-MAC) that need to be considered. 488 o A single key must only be used for messages of a fixed or known 489 length. If this is not the case, an attacker will be able to 490 generate a message with a valid tag given two message and tag 491 pairs. This can be addressed by using different keys for messages 492 of different lengths. The current structure mitigates this 493 problem, as a specific encoding structure that includes lengths is 494 built and signed. (CMAC also addresses this issue.) 496 o Cipher Block Chaining (CBC) mode, if the same key is used for both 497 encryption and authentication operations, an attacker can produce 498 messages with a valid authentication code. 500 o If the IV can be modified, then messages can be forged. This is 501 addressed by fixing the IV to all zeros. 503 4. Content Encryption Algorithms 505 This document defines the identifier and usages for three content 506 encryption algorithms. 508 4.1. AES GCM 510 The Galois/Counter Mode (GCM) mode is a generic authenticated 511 encryption block cipher mode defined in [AES-GCM]. The GCM mode is 512 combined with the AES block encryption algorithm to define an AEAD 513 cipher. 515 The GCM mode is parameterized by the size of the authentication tag 516 and the size of the nonce. This document fixes the size of the nonce 517 at 96 bits. The size of the authentication tag is limited to a small 518 set of values. For this document however, the size of the 519 authentication tag is fixed at 128 bits. 521 The set of algorithms defined in this document are in Table 5. 523 +---------+-------+------------------------------------------+ 524 | Name | Value | Description | 525 +---------+-------+------------------------------------------+ 526 | A128GCM | 1 | AES-GCM mode w/ 128-bit key, 128-bit tag | 527 | A192GCM | 2 | AES-GCM mode w/ 192-bit key, 128-bit tag | 528 | A256GCM | 3 | AES-GCM mode w/ 256-bit key, 128-bit tag | 529 +---------+-------+------------------------------------------+ 531 Table 5: Algorithm Value for AES-GCM 533 Keys may be obtained either from a key structure or from a recipient 534 structure. Implementations encrypting and decrypting MUST validate 535 that the key type, key length, and algorithm are correct and 536 appropriate for the entities involved. 538 When using a COSE key for this algorithm, the following checks are 539 made: 541 o The 'kty' field MUST be present, and it MUST be 'Symmetric'. 543 o If the 'alg' field is present, it MUST match the AES-GCM algorithm 544 being used. 546 o If the 'key_ops' field is present, it MUST include 'encrypt' or 547 'wrap key' when encrypting. 549 o If the 'key_ops' field is present, it MUST include 'decrypt' or 550 'unwrap key' when decrypting. 552 4.1.1. Security Considerations 554 When using AES-GCM, the following restrictions MUST be enforced: 556 o The key and nonce pair MUST be unique for every message encrypted. 558 o The total amount of data encrypted for a single key MUST NOT 559 exceed 2^39 - 256 bits. An explicit check is required only in 560 environments where it is expected that it might be exceeded. 562 Consideration was given to supporting smaller tag values; the 563 constrained community would desire tag sizes in the 64-bit range. 564 Doing so drastically changes both the maximum messages size 565 (generally not an issue) and the number of times that a key can be 566 used. Given that Counter with CBC-MAC (CCM) is the usual mode for 567 constrained environments, restricted modes are not supported. 569 4.2. AES CCM 571 CCM is a generic authentication encryption block cipher mode defined 572 in [RFC3610]. The CCM mode is combined with the AES block encryption 573 algorithm to define a commonly used content encryption algorithm used 574 in constrained devices. 576 The CCM mode has two parameter choices. The first choice is M, the 577 size of the authentication field. The choice of the value for M 578 involves a trade-off between message growth (from the tag) and the 579 probability that an attacker can undetectably modify a message. The 580 second choice is L, the size of the length field. This value 581 requires a trade-off between the maximum message size and the size of 582 the Nonce. 584 It is unfortunate that the specification for CCM specified L and M as 585 a count of bytes rather than a count of bits. This leads to possible 586 misunderstandings where AES-CCM-8 is frequently used to refer to a 587 version of CCM mode where the size of the authentication is 64 bits 588 and not 8 bits. These values have traditionally been specified as 589 bit counts rather than byte counts. This document will follow the 590 convention of using bit counts so that it is easier to compare the 591 different algorithms presented in this document. 593 We define a matrix of algorithms in this document over the values of 594 L and M. Constrained devices are usually operating in situations 595 where they use short messages and want to avoid doing recipient- 596 specific cryptographic operations. This favors smaller values of 597 both L and M. Less-constrained devices will want to be able to use 598 larger messages and are more willing to generate new keys for every 599 operation. This favors larger values of L and M. 601 The following values are used for L: 603 16 bits (2): This limits messages to 2^16 bytes (64 KiB) in length. 604 This is sufficiently long for messages in the constrained world. 605 The nonce length is 13 bytes allowing for 2^(13*8) possible values 606 of the nonce without repeating. 608 64 bits (8): This limits messages to 2^64 bytes in length. The 609 nonce length is 7 bytes allowing for 2^56 possible values of the 610 nonce without repeating. 612 The following values are used for M: 614 64 bits (8): This produces a 64-bit authentication tag. This 615 implies that there is a 1 in 2^64 chance that a modified message 616 will authenticate. 618 128 bits (16): This produces a 128-bit authentication tag. This 619 implies that there is a 1 in 2^128 chance that a modified message 620 will authenticate. 622 +--------------------+-------+----+-----+-----+---------------------+ 623 | Name | Value | L | M | k | Description | 624 +--------------------+-------+----+-----+-----+---------------------+ 625 | AES-CCM-16-64-128 | 10 | 16 | 64 | 128 | AES-CCM mode | 626 | | | | | | 128-bit key, 64-bit | 627 | | | | | | tag, 13-byte nonce | 628 | AES-CCM-16-64-256 | 11 | 16 | 64 | 256 | AES-CCM mode | 629 | | | | | | 256-bit key, 64-bit | 630 | | | | | | tag, 13-byte nonce | 631 | AES-CCM-64-64-128 | 12 | 64 | 64 | 128 | AES-CCM mode | 632 | | | | | | 128-bit key, 64-bit | 633 | | | | | | tag, 7-byte nonce | 634 | AES-CCM-64-64-256 | 13 | 64 | 64 | 256 | AES-CCM mode | 635 | | | | | | 256-bit key, 64-bit | 636 | | | | | | tag, 7-byte nonce | 637 | AES-CCM-16-128-128 | 30 | 16 | 128 | 128 | AES-CCM mode | 638 | | | | | | 128-bit key, | 639 | | | | | | 128-bit tag, | 640 | | | | | | 13-byte nonce | 641 | AES-CCM-16-128-256 | 31 | 16 | 128 | 256 | AES-CCM mode | 642 | | | | | | 256-bit key, | 643 | | | | | | 128-bit tag, | 644 | | | | | | 13-byte nonce | 645 | AES-CCM-64-128-128 | 32 | 64 | 128 | 128 | AES-CCM mode | 646 | | | | | | 128-bit key, | 647 | | | | | | 128-bit tag, 7-byte | 648 | | | | | | nonce | 649 | AES-CCM-64-128-256 | 33 | 64 | 128 | 256 | AES-CCM mode | 650 | | | | | | 256-bit key, | 651 | | | | | | 128-bit tag, 7-byte | 652 | | | | | | nonce | 653 +--------------------+-------+----+-----+-----+---------------------+ 655 Table 6: Algorithm Values for AES-CCM 657 Keys may be obtained either from a key structure or from a recipient 658 structure. Implementations encrypting and decrypting MUST validate 659 that the key type, key length, and algorithm are correct and 660 appropriate for the entities involved. 662 When using a COSE key for this algorithm, the following checks are 663 made: 665 o The 'kty' field MUST be present, and it MUST be 'Symmetric'. 667 o If the 'alg' field is present, it MUST match the AES-CCM algorithm 668 being used. 670 o If the 'key_ops' field is present, it MUST include 'encrypt' or 671 'wrap key' when encrypting. 673 o If the 'key_ops' field is present, it MUST include 'decrypt' or 674 'unwrap key' when decrypting. 676 4.2.1. Security Considerations 678 When using AES-CCM, the following restrictions MUST be enforced: 680 o The key and nonce pair MUST be unique for every message encrypted. 681 Note that the value of L influences the number of unique nonces. 683 o The total number of times the AES block cipher is used MUST NOT 684 exceed 2^61 operations. This limitation is the sum of times the 685 block cipher is used in computing the MAC value and in performing 686 stream encryption operations. An explicit check is required only 687 in environments where it is expected that it might be exceeded. 689 [RFC3610] additionally calls out one other consideration of note. It 690 is possible to do a pre-computation attack against the algorithm in 691 cases where portions of the plaintext are highly predictable. This 692 reduces the security of the key size by half. Ways to deal with this 693 attack include adding a random portion to the nonce value and/or 694 increasing the key size used. Using a portion of the nonce for a 695 random value will decrease the number of messages that a single key 696 can be used for. Increasing the key size may require more resources 697 in the constrained device. See Sections 5 and 10 of [RFC3610] for 698 more information. 700 4.3. ChaCha20 and Poly1305 702 ChaCha20 and Poly1305 combined together is an AEAD mode that is 703 defined in [RFC8439]. This is an algorithm defined to be a cipher 704 that is not AES and thus would not suffer from any future weaknesses 705 found in AES. These cryptographic functions are designed to be fast 706 in software-only implementations. 708 The ChaCha20/Poly1305 AEAD construction defined in [RFC8439] has no 709 parameterization. It takes a 256-bit key and a 96-bit nonce, as well 710 as the plaintext and additional data as inputs and produces the 711 ciphertext as an option. We define one algorithm identifier for this 712 algorithm in Table 7. 714 +-------------------+-------+---------------------------------------+ 715 | Name | Value | Description | 716 +-------------------+-------+---------------------------------------+ 717 | ChaCha20/Poly1305 | 24 | ChaCha20/Poly1305 w/ 256-bit key, | 718 | | | 128-bit tag | 719 +-------------------+-------+---------------------------------------+ 721 Table 7: Algorithm Value for AES-GCM 723 Keys may be obtained either from a key structure or from a recipient 724 structure. Implementations encrypting and decrypting MUST validate 725 that the key type, key length, and algorithm are correct and 726 appropriate for the entities involved. 728 When using a COSE key for this algorithm, the following checks are 729 made: 731 o The 'kty' field MUST be present, and it MUST be 'Symmetric'. 733 o If the 'alg' field is present, it MUST match the ChaCha20/Poly1305 734 algorithm being used. 736 o If the 'key_ops' field is present, it MUST include 'encrypt' or 737 'wrap key' when encrypting. 739 o If the 'key_ops' field is present, it MUST include 'decrypt' or 740 'unwrap key' when decrypting. 742 4.3.1. Security Considerations 744 The key and nounce values MUST be a unique pair for every invocation 745 of the algorithm. Nonce counters are considered to be an acceptable 746 way of ensuring that they are unique. 748 5. Key Derivation Functions (KDFs) 750 This document defines a single context structure and a single KDF. 751 These elements are used for all of the recipient algorithms defined 752 in this document that require a KDF process. These algorithms are 753 defined in Sections 6.2, 6.4, and 6.5. 755 5.1. HMAC-Based Extract-and-Expand Key Derivation Function (HKDF) 757 The HKDF key derivation algorithm is defined in [RFC5869]. 759 The HKDF algorithm takes these inputs: 761 secret -- a shared value that is secret. Secrets may be either 762 previously shared or derived from operations like a Diffie-Hellman 763 (DH) key agreement. 765 salt -- an optional value that is used to change the generation 766 process. The salt value can be either public or private. If the 767 salt is public and carried in the message, then the 'salt' 768 algorithm header parameter defined in Table 9 is used. While 769 [RFC5869] suggests that the length of the salt be the same as the 770 length of the underlying hash value, any amount of salt will 771 improve the security as different key values will be generated. 772 This parameter is protected by being included in the key 773 computation and does not need to be separately authenticated. The 774 salt value does not need to be unique for every message sent. 776 length -- the number of bytes of output that need to be generated. 778 context information -- Information that describes the context in 779 which the resulting value will be used. Making this information 780 specific to the context in which the material is going to be used 781 ensures that the resulting material will always be tied to that 782 usage. The context structure defined in Section 5.2 is used by 783 the KDFs in this document. 785 PRF -- The underlying pseudorandom function to be used in the HKDF 786 algorithm. The PRF is encoded into the HKDF algorithm selection. 788 HKDF is defined to use HMAC as the underlying PRF. However, it is 789 possible to use other functions in the same construct to provide a 790 different KDF that is more appropriate in the constrained world. 791 Specifically, one can use AES-CBC-MAC as the PRF for the expand step, 792 but not for the extract step. When using a good random shared secret 793 of the correct length, the extract step can be skipped. For the AES 794 algorithm versions, the extract step is always skipped. 796 The extract step cannot be skipped if the secret is not uniformly 797 random, for example, if it is the result of an ECDH key agreement 798 step. This implies that the AES HKDF version cannot be used with 799 ECDH. If the extract step is skipped, the 'salt' value is not used 800 as part of the HKDF functionality. 802 The algorithms defined in this document are found in Table 8. 804 +---------------+-----------------+---------------------------------+ 805 | Name | PRF | Description | 806 +---------------+-----------------+---------------------------------+ 807 | HKDF SHA-256 | HMAC with | HKDF using HMAC SHA-256 as the | 808 | | SHA-256 | PRF | 809 | HKDF SHA-512 | HMAC with | HKDF using HMAC SHA-512 as the | 810 | | SHA-512 | PRF | 811 | HKDF AES- | AES-CBC-MAC-128 | HKDF using AES-MAC as the PRF | 812 | MAC-128 | | w/ 128-bit key | 813 | HKDF AES- | AES-CBC-MAC-256 | HKDF using AES-MAC as the PRF | 814 | MAC-256 | | w/ 256-bit key | 815 +---------------+-----------------+---------------------------------+ 817 Table 8: HKDF Algorithms 819 +------+-------+------+-------------------------------+-------------+ 820 | Name | Label | Type | Algorithm | Description | 821 +------+-------+------+-------------------------------+-------------+ 822 | salt | -20 | bstr | direct+HKDF-SHA-256, direct | Random salt | 823 | | | | +HKDF-SHA-512, direct+HKDF- | | 824 | | | | AES-128, direct+HKDF-AES-256, | | 825 | | | | ECDH-ES+HKDF-256, ECDH- | | 826 | | | | ES+HKDF-512, ECDH- | | 827 | | | | SS+HKDF-256, ECDH- | | 828 | | | | SS+HKDF-512, ECDH-ES+A128KW, | | 829 | | | | ECDH-ES+A192KW, ECDH- | | 830 | | | | ES+A256KW, ECDH-SS+A128KW, | | 831 | | | | ECDH-SS+A192KW, ECDH- | | 832 | | | | SS+A256KW | | 833 +------+-------+------+-------------------------------+-------------+ 835 Table 9: HKDF Algorithm Parameters 837 5.2. Context Information Structure 839 The context information structure is used to ensure that the derived 840 keying material is "bound" to the context of the transaction. The 841 context information structure used here is based on that defined in 842 [SP800-56A]. By using CBOR for the encoding of the context 843 information structure, we automatically get the same type and length 844 separation of fields that is obtained by the use of ASN.1. This 845 means that there is no need to encode the lengths for the base 846 elements, as it is done by the encoding used in JOSE (Section 4.6.2 847 of [RFC7518]). 849 The context information structure refers to PartyU and PartyV as the 850 two parties that are doing the key derivation. Unless the 851 application protocol defines differently, we assign PartyU to the 852 entity that is creating the message and PartyV to the entity that is 853 receiving the message. By doing this association, different keys 854 will be derived for each direction as the context information is 855 different in each direction. 857 The context structure is built from information that is known to both 858 entities. This information can be obtained from a variety of 859 sources: 861 o Fields can be defined by the application. This is commonly used 862 to assign fixed names to parties, but it can be used for other 863 items such as nonces. 865 o Fields can be defined by usage of the output. Examples of this 866 are the algorithm and key size that are being generated. 868 o Fields can be defined by parameters from the message. We define a 869 set of parameters in Table 10 that can be used to carry the values 870 associated with the context structure. Examples of this are 871 identities and nonce values. These parameters are designed to be 872 placed in the unprotected bucket of the recipient structure; they 873 do not need to be in the protected bucket since they already are 874 included in the cryptographic computation by virtue of being 875 included in the context structure. 877 +----------+-------+------+---------------------------+-------------+ 878 | Name | Label | Type | Algorithm | Description | 879 +----------+-------+------+---------------------------+-------------+ 880 | PartyU | -21 | bstr | direct+HKDF-SHA-256, | Party U | 881 | identity | | | direct+HKDF-SHA-512, | identity | 882 | | | | direct+HKDF-AES-128, | information | 883 | | | | direct+HKDF-AES-256, | | 884 | | | | ECDH-ES+HKDF-256, ECDH- | | 885 | | | | ES+HKDF-512, ECDH- | | 886 | | | | SS+HKDF-256, ECDH- | | 887 | | | | SS+HKDF-512, ECDH- | | 888 | | | | ES+A128KW, ECDH- | | 889 | | | | ES+A192KW, ECDH- | | 890 | | | | ES+A256KW, ECDH- | | 891 | | | | SS+A128KW, ECDH- | | 892 | | | | SS+A192KW, ECDH-SS+A256KW | | 893 | PartyU | -22 | bstr | direct+HKDF-SHA-256, | Party U | 894 | nonce | | / | direct+HKDF-SHA-512, | provided | 895 | | | int | direct+HKDF-AES-128, | nonce | 896 | | | | direct+HKDF-AES-256, | | 897 | | | | ECDH-ES+HKDF-256, ECDH- | | 898 | | | | ES+HKDF-512, ECDH- | | 899 | | | | SS+HKDF-256, ECDH- | | 900 | | | | SS+HKDF-512, ECDH- | | 901 | | | | ES+A128KW, ECDH- | | 902 | | | | ES+A192KW, ECDH- | | 903 | | | | ES+A256KW, ECDH- | | 904 | | | | SS+A128KW, ECDH- | | 905 | | | | SS+A192KW, ECDH-SS+A256KW | | 906 | PartyU | -23 | bstr | direct+HKDF-SHA-256, | Party U | 907 | other | | | direct+HKDF-SHA-512, | other | 908 | | | | direct+HKDF-AES-128, | provided | 909 | | | | direct+HKDF-AES-256, | information | 910 | | | | ECDH-ES+HKDF-256, ECDH- | | 911 | | | | ES+HKDF-512, ECDH- | | 912 | | | | SS+HKDF-256, ECDH- | | 913 | | | | SS+HKDF-512, ECDH- | | 914 | | | | ES+A128KW, ECDH- | | 915 | | | | ES+A192KW, ECDH- | | 916 | | | | ES+A256KW, ECDH- | | 917 | | | | SS+A128KW, ECDH- | | 918 | | | | SS+A192KW, ECDH-SS+A256KW | | 919 | PartyV | -24 | bstr | direct+HKDF-SHA-256, | Party V | 920 | identity | | | direct+HKDF-SHA-512, | identity | 921 | | | | direct+HKDF-AES-128, | information | 922 | | | | direct+HKDF-AES-256, | | 923 | | | | ECDH-ES+HKDF-256, ECDH- | | 924 | | | | ES+HKDF-512, ECDH- | | 925 | | | | SS+HKDF-256, ECDH- | | 926 | | | | SS+HKDF-512, ECDH- | | 927 | | | | ES+A128KW, ECDH- | | 928 | | | | ES+A192KW, ECDH- | | 929 | | | | ES+A256KW, ECDH- | | 930 | | | | SS+A128KW, ECDH- | | 931 | | | | SS+A192KW, ECDH-SS+A256KW | | 932 | PartyV | -25 | bstr | direct+HKDF-SHA-256, | Party V | 933 | nonce | | / | direct+HKDF-SHA-512, | provided | 934 | | | int | direct+HKDF-AES-128, | nonce | 935 | | | | direct+HKDF-AES-256, | | 936 | | | | ECDH-ES+HKDF-256, ECDH- | | 937 | | | | ES+HKDF-512, ECDH- | | 938 | | | | SS+HKDF-256, ECDH- | | 939 | | | | SS+HKDF-512, ECDH- | | 940 | | | | ES+A128KW, ECDH- | | 941 | | | | ES+A192KW, ECDH- | | 942 | | | | ES+A256KW, ECDH- | | 943 | | | | SS+A128KW, ECDH- | | 944 | | | | SS+A192KW, ECDH-SS+A256KW | | 945 | PartyV | -26 | bstr | direct+HKDF-SHA-256, | Party V | 946 | other | | | direct+HKDF-SHA-512, | other | 947 | | | | direct+HKDF-AES-128, | provided | 948 | | | | direct+HKDF-AES-256, | information | 949 | | | | ECDH-ES+HKDF-256, ECDH- | | 950 | | | | ES+HKDF-512, ECDH- | | 951 | | | | SS+HKDF-256, ECDH- | | 952 | | | | SS+HKDF-512, ECDH- | | 953 | | | | ES+A128KW, ECDH- | | 954 | | | | ES+A192KW, ECDH- | | 955 | | | | ES+A256KW, ECDH- | | 956 | | | | SS+A128KW, ECDH- | | 957 | | | | SS+A192KW, ECDH-SS+A256KW | | 958 +----------+-------+------+---------------------------+-------------+ 960 Table 10: Context Algorithm Parameters 962 We define a CBOR object to hold the context information. This object 963 is referred to as COSE_KDF_Context. The object is based on a CBOR 964 array type. The fields in the array are: 966 AlgorithmID: This field indicates the algorithm for which the key 967 material will be used. This normally is either a key wrap 968 algorithm identifier or a content encryption algorithm identifier. 969 The values are from the "COSE Algorithms" registry. This field is 970 required to be present. The field exists in the context 971 information so that if the same environment is used for different 972 algorithms, then completely different keys will be generated for 973 each of those algorithms. This practice means if algorithm A is 974 broken and thus is easier to find, the key derived for algorithm B 975 will not be the same as the key derived for algorithm A. 977 PartyUInfo: This field holds information about party U. The 978 PartyUInfo is encoded as a CBOR array. The elements of PartyUInfo 979 are encoded in the order presented. The elements of the 980 PartyUInfo array are: 982 identity: This contains the identity information for party U. 983 The identities can be assigned in one of two manners. First, a 984 protocol can assign identities based on roles. For example, 985 the roles of "client" and "server" may be assigned to different 986 entities in the protocol. Each entity would then use the 987 correct label for the data they send or receive. The second 988 way for a protocol to assign identities is to use a name based 989 on a naming system (i.e., DNS, X.509 names). 991 We define an algorithm parameter 'PartyU identity' that can be 992 used to carry identity information in the message. However, 993 identity information is often known as part of the protocol and 994 can thus be inferred rather than made explicit. If identity 995 information is carried in the message, applications SHOULD have 996 a way of validating the supplied identity information. The 997 identity information does not need to be specified and is set 998 to nil in that case. 1000 nonce: This contains a nonce value. The nonce can either be 1001 implicit from the protocol or be carried as a value in the 1002 unprotected headers. 1004 We define an algorithm parameter 'PartyU nonce' that can be 1005 used to carry this value in the message; however, the nonce 1006 value could be determined by the application and the value 1007 determined from elsewhere. 1009 This option does not need to be specified and is set to nil in 1010 that case. 1012 other: This contains other information that is defined by the 1013 protocol. This option does not need to be specified and is set 1014 to nil in that case. 1016 PartyVInfo: This field holds information about party V. The content 1017 of the structure is the same as for the PartyUInfo but for party 1018 V. 1020 SuppPubInfo: This field contains public information that is mutually 1021 known to both parties. 1023 keyDataLength: This is set to the number of bits of the desired 1024 output value. This practice means if algorithm A can use two 1025 different key lengths, the key derived for longer key size will 1026 not contain the key for shorter key size as a prefix. 1028 protected: This field contains the protected parameter field. If 1029 there are no elements in the protected field, then use a zero- 1030 length bstr. 1032 other: This field is for free form data defined by the 1033 application. An example is that an application could define 1034 two different strings to be placed here to generate different 1035 keys for a data stream versus a control stream. This field is 1036 optional and will only be present if the application defines a 1037 structure for this information. Applications that define this 1038 SHOULD use CBOR to encode the data so that types and lengths 1039 are correctly included. 1041 SuppPrivInfo: This field contains private information that is 1042 mutually known private information. An example of this 1043 information would be a preexisting shared secret. (This could, 1044 for example, be used in combination with an ECDH key agreement to 1045 provide a secondary proof of identity.) The field is optional and 1046 will only be present if the application defines a structure for 1047 this information. Applications that define this SHOULD use CBOR 1048 to encode the data so that types and lengths are correctly 1049 included. 1051 The following CDDL fragment corresponds to the text above. 1053 PartyInfo = ( 1054 identity : bstr / nil, 1055 nonce : bstr / int / nil, 1056 other : bstr / nil 1057 ) 1059 COSE_KDF_Context = [ 1060 AlgorithmID : int / tstr, 1061 PartyUInfo : [ PartyInfo ], 1062 PartyVInfo : [ PartyInfo ], 1063 SuppPubInfo : [ 1064 keyDataLength : uint, 1065 protected : empty_or_serialized_map, 1066 ? other : bstr 1067 ], 1068 ? SuppPrivInfo : bstr 1069 ] 1071 6. Content Key Distribution Methods 1073 This document defines the identifiers and usage for a number of 1074 content key distribution methods. 1076 6.1. Direct Key 1078 This recipient algorithm is the simplest; the identified key is 1079 directly used as the key for the next layer down in the message. 1080 There are no algorithm parameters defined for this algorithm. The 1081 algorithm identifier value is assigned in Table 11. 1083 When this algorithm is used, the protected field MUST be zero length. 1084 The key type MUST be 'Symmetric'. 1086 +--------+-------+-------------------+ 1087 | Name | Value | Description | 1088 +--------+-------+-------------------+ 1089 | direct | -6 | Direct use of CEK | 1090 +--------+-------+-------------------+ 1092 Table 11: Direct Key 1094 6.1.1. Security Considerations 1096 This recipient algorithm has several potential problems that need to 1097 be considered: 1099 o These keys need to have some method to be regularly updated over 1100 time. All of the content encryption algorithms specified in this 1101 document have limits on how many times a key can be used without 1102 significant loss of security. 1104 o These keys need to be dedicated to a single algorithm. There have 1105 been a number of attacks developed over time when a single key is 1106 used for multiple different algorithms. One example of this is 1107 the use of a single key for both the CBC encryption mode and the 1108 CBC-MAC authentication mode. 1110 o Breaking one message means all messages are broken. If an 1111 adversary succeeds in determining the key for a single message, 1112 then the key for all messages is also determined. 1114 6.2. Direct Key with KDF 1116 These recipient algorithms take a common shared secret between the 1117 two parties and applies the HKDF function (Section 5.1), using the 1118 context structure defined in Section 5.2 to transform the shared 1119 secret into the CEK. The 'protected' field can be of non-zero 1120 length. Either the 'salt' parameter of HKDF or the 'PartyU nonce' 1121 parameter of the context structure MUST be present. The salt/nonce 1122 parameter can be generated either randomly or deterministically. The 1123 requirement is that it be a unique value for the shared secret in 1124 question. 1126 If the salt/nonce value is generated randomly, then it is suggested 1127 that the length of the random value be the same length as the hash 1128 function underlying HKDF. While there is no way to guarantee that it 1129 will be unique, there is a high probability that it will be unique. 1130 If the salt/nonce value is generated deterministically, it can be 1131 guaranteed to be unique, and thus there is no length requirement. 1133 A new IV must be used for each message if the same key is used. The 1134 IV can be modified in a predictable manner, a random manner, or an 1135 unpredictable manner (i.e., encrypting a counter). 1137 The IV used for a key can also be generated from the same HKDF 1138 functionality as the key is generated. If HKDF is used for 1139 generating the IV, the algorithm identifier is set to "IV- 1140 GENERATION". 1142 When these algorithms are used, the key type MUST be 'symmetric'. 1144 The set of algorithms defined in this document can be found in 1145 Table 12. 1147 +---------------------+-------+-------------+-----------------------+ 1148 | Name | Value | KDF | Description | 1149 +---------------------+-------+-------------+-----------------------+ 1150 | direct+HKDF-SHA-256 | -10 | HKDF | Shared secret w/ HKDF | 1151 | | | SHA-256 | and SHA-256 | 1152 | direct+HKDF-SHA-512 | -11 | HKDF | Shared secret w/ HKDF | 1153 | | | SHA-512 | and SHA-512 | 1154 | direct+HKDF-AES-128 | -12 | HKDF AES- | Shared secret w/ AES- | 1155 | | | MAC-128 | MAC 128-bit key | 1156 | direct+HKDF-AES-256 | -13 | HKDF AES- | Shared secret w/ AES- | 1157 | | | MAC-256 | MAC 256-bit key | 1158 +---------------------+-------+-------------+-----------------------+ 1160 Table 12: Direct Key with KDF 1162 When using a COSE key for this algorithm, the following checks are 1163 made: 1165 o The 'kty' field MUST be present, and it MUST be 'Symmetric'. 1167 o If the 'alg' field is present, it MUST match the algorithm being 1168 used. 1170 o If the 'key_ops' field is present, it MUST include 'deriveKey' or 1171 'deriveBits'. 1173 6.2.1. Security Considerations 1175 The shared secret needs to have some method to be regularly updated 1176 over time. The shared secret forms the basis of trust. Although not 1177 used directly, it should still be subject to scheduled rotation. 1179 While these methods do not provide for perfect forward secrecy, as 1180 the same shared secret is used for all of the keys generated, if the 1181 key for any single message is discovered, only the message (or series 1182 of messages) using that derived key are compromised. A new key 1183 derivation step will generate a new key that requires the same amount 1184 of work to get the key. 1186 6.3. AES Key Wrap 1188 The AES Key Wrap algorithm is defined in [RFC3394]. This algorithm 1189 uses an AES key to wrap a value that is a multiple of 64 bits. As 1190 such, it can be used to wrap a key for any of the content encryption 1191 algorithms defined in this document. The algorithm requires a single 1192 fixed parameter, the initial value. This is fixed to the value 1193 specified in Section 2.2.3.1 of [RFC3394]. There are no public 1194 parameters that vary on a per-invocation basis. The protected header 1195 field MUST be empty. 1197 Keys may be obtained either from a key structure or from a recipient 1198 structure. Implementations encrypting and decrypting MUST validate 1199 that the key type, key length, and algorithm are correct and 1200 appropriate for the entities involved. 1202 When using a COSE key for this algorithm, the following checks are 1203 made: 1205 o The 'kty' field MUST be present, and it MUST be 'Symmetric'. 1207 o If the 'alg' field is present, it MUST match the AES Key Wrap 1208 algorithm being used. 1210 o If the 'key_ops' field is present, it MUST include 'encrypt' or 1211 'wrap key' when encrypting. 1213 o If the 'key_ops' field is present, it MUST include 'decrypt' or 1214 'unwrap key' when decrypting. 1216 +--------+-------+----------+-----------------------------+ 1217 | Name | Value | Key Size | Description | 1218 +--------+-------+----------+-----------------------------+ 1219 | A128KW | -3 | 128 | AES Key Wrap w/ 128-bit key | 1220 | A192KW | -4 | 192 | AES Key Wrap w/ 192-bit key | 1221 | A256KW | -5 | 256 | AES Key Wrap w/ 256-bit key | 1222 +--------+-------+----------+-----------------------------+ 1224 Table 13: AES Key Wrap Algorithm Values 1226 6.3.1. Security Considerations for AES-KW 1228 The shared secret needs to have some method to be regularly updated 1229 over time. The shared secret is the basis of trust. 1231 6.4. Direct ECDH 1233 The mathematics for ECDH can be found in [RFC6090]. In this 1234 document, the algorithm is extended to be used with the two curves 1235 defined in [RFC7748]. 1237 ECDH is parameterized by the following: 1239 o Curve Type/Curve: The curve selected controls not only the size of 1240 the shared secret, but the mathematics for computing the shared 1241 secret. The curve selected also controls how a point in the curve 1242 is represented and what happens for the identity points on the 1243 curve. In this specification, we allow for a number of different 1244 curves to be used. A set of curves are defined in Table 18. 1245 The math used to obtain the computed secret is based on the curve 1246 selected and not on the ECDH algorithm. For this reason, a new 1247 algorithm does not need to be defined for each of the curves. 1249 o Computed Secret to Shared Secret: Once the computed secret is 1250 known, the resulting value needs to be converted to a byte string 1251 to run the KDF. The x-coordinate is used for all of the curves 1252 defined in this document. For curves X25519 and X448, the 1253 resulting value is used directly as it is a byte string of a known 1254 length. For the P-256, P-384, and P-521 curves, the x-coordinate 1255 is run through the I2OSP function defined in [RFC8017], using the 1256 same computation for n as is defined in Section 2.1. 1258 o Ephemeral-Static or Static-Static: The key agreement process may 1259 be done using either a static or an ephemeral key for the sender's 1260 side. When using ephemeral keys, the sender MUST generate a new 1261 ephemeral key for every key agreement operation. The ephemeral 1262 key is placed in the 'ephemeral key' parameter and MUST be present 1263 for all algorithm identifiers that use ephemeral keys. When using 1264 static keys, the sender MUST either generate a new random value or 1265 create a unique value. For the KDFs used, this means either the 1266 'salt' parameter for HKDF (Table 9) or the 'PartyU nonce' 1267 parameter for the context structure (Table 10) MUST be present 1268 (both can be present if desired). The value in the parameter MUST 1269 be unique for the pair of keys being used. It is acceptable to 1270 use a global counter that is incremented for every static-static 1271 operation and use the resulting value. When using static keys, 1272 the static key should be identified to the recipient. The static 1273 key can be identified either by providing the key ('static key') 1274 or by providing a key identifier for the static key ('static key 1275 id'). Both of these parameters are defined in Table 15. 1277 o Key Derivation Algorithm: The result of an ECDH key agreement 1278 process does not provide a uniformly random secret. As such, it 1279 needs to be run through a KDF in order to produce a usable key. 1280 Processing the secret through a KDF also allows for the 1281 introduction of context material: how the key is going to be used 1282 and one-time material for static-static key agreement. All of the 1283 algorithms defined in this document use one of the HKDF algorithms 1284 defined in Section 5.1 with the context structure defined in 1285 Section 5.2. 1287 o Key Wrap Algorithm: No key wrap algorithm is used. This is 1288 represented in Table 14 as 'none'. The key size for the context 1289 structure is the content layer encryption algorithm size. 1291 The set of direct ECDH algorithms defined in this document are found 1292 in Table 14. 1294 +-----------+-------+---------+------------+--------+---------------+ 1295 | Name | Value | KDF | Ephemeral- | Key | Description | 1296 | | | | Static | Wrap | | 1297 +-----------+-------+---------+------------+--------+---------------+ 1298 | ECDH-ES + | -25 | HKDF - | yes | none | ECDH ES w/ | 1299 | HKDF-256 | | SHA-256 | | | HKDF - | 1300 | | | | | | generate key | 1301 | | | | | | directly | 1302 | ECDH-ES + | -26 | HKDF - | yes | none | ECDH ES w/ | 1303 | HKDF-512 | | SHA-512 | | | HKDF - | 1304 | | | | | | generate key | 1305 | | | | | | directly | 1306 | ECDH-SS + | -27 | HKDF - | no | none | ECDH SS w/ | 1307 | HKDF-256 | | SHA-256 | | | HKDF - | 1308 | | | | | | generate key | 1309 | | | | | | directly | 1310 | ECDH-SS + | -28 | HKDF - | no | none | ECDH SS w/ | 1311 | HKDF-512 | | SHA-512 | | | HKDF - | 1312 | | | | | | generate key | 1313 | | | | | | directly | 1314 +-----------+-------+---------+------------+--------+---------------+ 1316 Table 14: ECDH Algorithm Values 1318 +-----------+-------+----------+---------------------+--------------+ 1319 | Name | Label | Type | Algorithm | Description | 1320 +-----------+-------+----------+---------------------+--------------+ 1321 | ephemeral | -1 | COSE_Key | ECDH-ES+HKDF-256, | Ephemeral | 1322 | key | | | ECDH-ES+HKDF-512, | public key | 1323 | | | | ECDH-ES+A128KW, | for the | 1324 | | | | ECDH-ES+A192KW, | sender | 1325 | | | | ECDH-ES+A256KW | | 1326 | static | -2 | COSE_Key | ECDH-SS+HKDF-256, | Static | 1327 | key | | | ECDH-SS+HKDF-512, | public key | 1328 | | | | ECDH-SS+A128KW, | for the | 1329 | | | | ECDH-SS+A192KW, | sender | 1330 | | | | ECDH-SS+A256KW | | 1331 | static | -3 | bstr | ECDH-SS+HKDF-256, | Static | 1332 | key id | | | ECDH-SS+HKDF-512, | public key | 1333 | | | | ECDH-SS+A128KW, | identifier | 1334 | | | | ECDH-SS+A192KW, | for the | 1335 | | | | ECDH-SS+A256KW | sender | 1336 +-----------+-------+----------+---------------------+--------------+ 1338 Table 15: ECDH Algorithm Parameters 1340 This document defines these algorithms to be used with the curves 1341 P-256, P-384, P-521, X25519, and X448. Implementations MUST verify 1342 that the key type and curve are correct. Different curves are 1343 restricted to different key types. Implementations MUST verify that 1344 the curve and algorithm are appropriate for the entities involved. 1346 When using a COSE key for this algorithm, the following checks are 1347 made: 1349 o The 'kty' field MUST be present, and it MUST be 'EC2' or 'OKP'. 1351 o If the 'alg' field is present, it MUST match the key agreement 1352 algorithm being used. 1354 o If the 'key_ops' field is present, it MUST include 'derive key' or 1355 'derive bits' for the private key. 1357 o If the 'key_ops' field is present, it MUST be empty for the public 1358 key. 1360 6.4.1. Security Considerations 1362 There is a method of checking that points provided from external 1363 entities are valid. For the 'EC2' key format, this can be done by 1364 checking that the x and y values form a point on the curve. For the 1365 'OKP' format, there is no simple way to do point validation. 1367 Consideration was given to requiring that the public keys of both 1368 entities be provided as part of the key derivation process (as 1369 recommended in Section 6.1 of [RFC7748]). This was not done as COSE 1370 is used in a store and forward format rather than in online key 1371 exchange. In order for this to be a problem, either the receiver 1372 public key has to be chosen maliciously or the sender has to be 1373 malicious. In either case, all security evaporates anyway. 1375 A proof of possession of the private key associated with the public 1376 key is recommended when a key is moved from untrusted to trusted 1377 (either by the end user or by the entity that is responsible for 1378 making trust statements on keys). 1380 6.5. ECDH with Key Wrap 1382 These algorithms are defined in Table 16. 1384 ECDH with Key Agreement is parameterized by the same parameters as 1385 for ECDH; see Section 6.4, with the following modifications: 1387 o Key Wrap Algorithm: Any of the key wrap algorithms defined in 1388 Section 6.3 are supported. The size of the key used for the key 1389 wrap algorithm is fed into the KDF. The set of identifiers are 1390 found in Table 16. 1392 +-----------+-------+---------+------------+--------+---------------+ 1393 | Name | Value | KDF | Ephemeral- | Key | Description | 1394 | | | | Static | Wrap | | 1395 +-----------+-------+---------+------------+--------+---------------+ 1396 | ECDH-ES + | -29 | HKDF - | yes | A128KW | ECDH ES w/ | 1397 | A128KW | | SHA-256 | | | Concat KDF | 1398 | | | | | | and AES Key | 1399 | | | | | | Wrap w/ | 1400 | | | | | | 128-bit key | 1401 | | | | | | | 1402 | ECDH-ES + | -30 | HKDF - | yes | A192KW | ECDH ES w/ | 1403 | A192KW | | SHA-256 | | | Concat KDF | 1404 | | | | | | and AES Key | 1405 | | | | | | Wrap w/ | 1406 | | | | | | 192-bit key | 1407 | | | | | | | 1408 | ECDH-ES + | -31 | HKDF - | yes | A256KW | ECDH ES w/ | 1409 | A256KW | | SHA-256 | | | Concat KDF | 1410 | | | | | | and AES Key | 1411 | | | | | | Wrap w/ | 1412 | | | | | | 256-bit key | 1413 | | | | | | | 1414 | ECDH-SS + | -32 | HKDF - | no | A128KW | ECDH SS w/ | 1415 | A128KW | | SHA-256 | | | Concat KDF | 1416 | | | | | | and AES Key | 1417 | | | | | | Wrap w/ | 1418 | | | | | | 128-bit key | 1419 | | | | | | | 1420 | ECDH-SS + | -33 | HKDF - | no | A192KW | ECDH SS w/ | 1421 | A192KW | | SHA-256 | | | Concat KDF | 1422 | | | | | | and AES Key | 1423 | | | | | | Wrap w/ | 1424 | | | | | | 192-bit key | 1425 | | | | | | | 1426 | ECDH-SS + | -34 | HKDF - | no | A256KW | ECDH SS w/ | 1427 | A256KW | | SHA-256 | | | Concat KDF | 1428 | | | | | | and AES Key | 1429 | | | | | | Wrap w/ | 1430 | | | | | | 256-bit key | 1431 +-----------+-------+---------+------------+--------+---------------+ 1433 Table 16: ECDH Algorithm Values with Key Wrap 1435 When using a COSE key for this algorithm, the following checks are 1436 made: 1438 o The 'kty' field MUST be present, and it MUST be 'EC2' or 'OKP'. 1440 o If the 'alg' field is present, it MUST match the key agreement 1441 algorithm being used. 1443 o If the 'key_ops' field is present, it MUST include 'derive key' or 1444 'derive bits' for the private key. 1446 o If the 'key_ops' field is present, it MUST be empty for the public 1447 key. 1449 7. Key Object Parameters 1451 The COSE_Key object defines a way to hold a single key object. It is 1452 still required that the members of individual key types be defined. 1453 This section of the document is where we define an initial set of 1454 members for specific key types. 1456 For each of the key types, we define both public and private members. 1457 The public members are what is transmitted to others for their usage. 1458 Private members allow for the archival of keys by individuals. 1459 However, there are some circumstances in which private keys may be 1460 distributed to entities in a protocol. Examples include: entities 1461 that have poor random number generation, centralized key creation for 1462 multi-cast type operations, and protocols in which a shared secret is 1463 used as a bearer token for authorization purposes. 1465 Key types are identified by the 'kty' member of the COSE_Key object. 1466 In this document, we define four values for the member: 1468 +-----------+-------+-----------------------------------------------+ 1469 | Name | Value | Description | 1470 +-----------+-------+-----------------------------------------------+ 1471 | OKP | 1 | Octet Key Pair | 1472 | EC2 | 2 | Elliptic Curve Keys w/ x- and y-coordinate | 1473 | | | pair | 1474 | Symmetric | 4 | Symmetric Keys | 1475 | Reserved | 0 | This value is reserved | 1476 +-----------+-------+-----------------------------------------------+ 1478 Table 17: Key Type Values 1480 7.1. Elliptic Curve Keys 1482 Two different key structures are defined for elliptic curve keys. 1483 One version uses both an x-coordinate and a y-coordinate, potentially 1484 with point compression ('EC2'). This is the traditional EC point 1485 representation that is used in [RFC5480]. The other version uses 1486 only the x-coordinate as the y-coordinate is either to be recomputed 1487 or not needed for the key agreement operation ('OKP'). 1489 Applications MUST check that the curve and the key type are 1490 consistent and reject a key if they are not. 1492 +---------+-------+----------+------------------------------------+ 1493 | Name | Value | Key Type | Description | 1494 +---------+-------+----------+------------------------------------+ 1495 | P-256 | 1 | EC2 | NIST P-256 also known as secp256r1 | 1496 | P-384 | 2 | EC2 | NIST P-384 also known as secp384r1 | 1497 | P-521 | 3 | EC2 | NIST P-521 also known as secp521r1 | 1498 | X25519 | 4 | OKP | X25519 for use w/ ECDH only | 1499 | X448 | 5 | OKP | X448 for use w/ ECDH only | 1500 | Ed25519 | 6 | OKP | Ed25519 for use w/ EdDSA only | 1501 | Ed448 | 7 | OKP | Ed448 for use w/ EdDSA only | 1502 +---------+-------+----------+------------------------------------+ 1504 Table 18: Elliptic Curves 1506 7.1.1. Double Coordinate Curves 1508 The traditional way of sending ECs has been to send either both the 1509 x-coordinate and y-coordinate or the x-coordinate and a sign bit for 1510 the y-coordinate. The latter encoding has not been recommended in 1511 the IETF due to potential IPR issues. However, for operations in 1512 constrained environments, the ability to shrink a message by not 1513 sending the y-coordinate is potentially useful. 1515 For EC keys with both coordinates, the 'kty' member is set to 2 1516 (EC2). The key parameters defined in this section are summarized in 1517 Table 19. The members that are defined for this key type are: 1519 crv: This contains an identifier of the curve to be used with the 1520 key. The curves defined in this document for this key type can 1521 be found in Table 18. Other curves may be registered in the 1522 future, and private curves can be used as well. 1524 x: This contains the x-coordinate for the EC point. The integer is 1525 converted to an octet string as defined in [SEC1]. Leading zero 1526 octets MUST be preserved. 1528 y: This contains either the sign bit or the value of the 1529 y-coordinate for the EC point. When encoding the value y, the 1530 integer is converted to an octet string (as defined in [SEC1]) 1531 and encoded as a CBOR bstr. Leading zero octets MUST be 1532 preserved. The compressed point encoding is also supported. 1533 Compute the sign bit as laid out in the Elliptic-Curve-Point-to- 1534 Octet-String Conversion function of [SEC1]. If the sign bit is 1535 zero, then encode y as a CBOR false value; otherwise, encode y 1536 as a CBOR true value. The encoding of the infinity point is not 1537 supported. 1539 d: This contains the private key. 1541 For public keys, it is REQUIRED that 'crv', 'x', and 'y' be present 1542 in the structure. For private keys, it is REQUIRED that 'crv' and 1543 'd' be present in the structure. For private keys, it is RECOMMENDED 1544 that 'x' and 'y' also be present, but they can be recomputed from the 1545 required elements and omitting them saves on space. 1547 +-------+------+-------+--------+-----------------------------------+ 1548 | Key | Name | Label | CBOR | Description | 1549 | Type | | | Type | | 1550 +-------+------+-------+--------+-----------------------------------+ 1551 | 2 | crv | -1 | int / | EC identifier - Taken from the | 1552 | | | | tstr | "COSE Elliptic Curves" registry | 1553 | 2 | x | -2 | bstr | x-coordinate | 1554 | 2 | y | -3 | bstr / | y-coordinate | 1555 | | | | bool | | 1556 | 2 | d | -4 | bstr | Private key | 1557 +-------+------+-------+--------+-----------------------------------+ 1559 Table 19: EC Key Parameters 1561 7.2. Octet Key Pair 1563 A new key type is defined for Octet Key Pairs (OKP). Do not assume 1564 that keys using this type are elliptic curves. This key type could 1565 be used for other curve types (for example, mathematics based on 1566 hyper-elliptic surfaces). 1568 The key parameters defined in this section are summarized in 1569 Table 20. The members that are defined for this key type are: 1571 crv: This contains an identifier of the curve to be used with the 1572 key. The curves defined in this document for this key type can 1573 be found in Table 18. Other curves may be registered in the 1574 future and private curves can be used as well. 1576 x: This contains the x-coordinate for the EC point. The octet 1577 string represents a little-endian encoding of x. 1579 d: This contains the private key. 1581 For public keys, it is REQUIRED that 'crv' and 'x' be present in the 1582 structure. For private keys, it is REQUIRED that 'crv' and 'd' be 1583 present in the structure. For private keys, it is RECOMMENDED that 1584 'x' also be present, but it can be recomputed from the required 1585 elements and omitting it saves on space. 1587 +------+-------+-------+--------+-----------------------------------+ 1588 | Name | Key | Label | Type | Description | 1589 | | Type | | | | 1590 +------+-------+-------+--------+-----------------------------------+ 1591 | crv | 1 | -1 | int / | EC identifier - Taken from the | 1592 | | | | tstr | "COSE Key Common Parameters" | 1593 | | | | | registry | 1594 | x | 1 | -2 | bstr | x-coordinate | 1595 | d | 1 | -4 | bstr | Private key | 1596 +------+-------+-------+--------+-----------------------------------+ 1598 Table 20: Octet Key Pair Parameters 1600 7.3. Symmetric Keys 1602 Occasionally it is required that a symmetric key be transported 1603 between entities. This key structure allows for that to happen. 1605 For symmetric keys, the 'kty' member is set to 4 ('Symmetric'). The 1606 member that is defined for this key type is: 1608 k: This contains the value of the key. 1610 This key structure does not have a form that contains only public 1611 members. As it is expected that this key structure is going to be 1612 transmitted, care must be taken that it is never transmitted 1613 accidentally or insecurely. For symmetric keys, it is REQUIRED that 1614 'k' be present in the structure. 1616 +------+----------+-------+------+-------------+ 1617 | Name | Key Type | Label | Type | Description | 1618 +------+----------+-------+------+-------------+ 1619 | k | 4 | -1 | bstr | Key Value | 1620 +------+----------+-------+------+-------------+ 1622 Table 21: Symmetric Key Parameters 1624 8. IANA Considerations 1626 8.1. COSE Algorithms Registry 1628 IANA created and populated the "COSE Algorithms" registry as part of 1629 processing processing [RFC8152]. IANA is requested to update the for 1630 individual algorithms from [RFC8152] to this document. 1632 This document does not modify the guidance for designated experts. 1634 8.2. COSE Key Type Parameters Registry 1636 IANA has created a new registry titled "COSE Key Type Parameters". 1637 The registry has been created to use the "Expert Review Required" 1638 registration procedure. Expert review guidelines are provided in 1639 Section 8.5. 1641 The columns of the table are: 1643 Key Type: This field contains a descriptive string of a key type. 1644 This should be a value that is in the "COSE Key Common Parameters" 1645 registry and is placed in the 'kty' field of a COSE Key structure. 1647 Name: This is a descriptive name that enables easier reference to 1648 the item. It is not used in the encoding. 1650 Label: The label is to be unique for every value of key type. The 1651 range of values is from -65536 to -1. Labels are expected to be 1652 reused for different keys. 1654 CBOR Type: This field contains the CBOR type for the field. 1656 Description: This field contains a brief description for the field. 1658 Reference: This contains a pointer to the public specification for 1659 the field if one exists. 1661 This registry has been initially populated by the values in Tables 1662 19, 20, and 21. All of the entries in the "References" column of 1663 this registry point to this document. 1665 8.3. COSE Key Types Registry 1667 IANA has created a new registry titled "COSE Key Types". The 1668 registry has been created to use the "Expert Review Required" 1669 registration procedure. Expert review guidelines are provided in 1670 Section 8.5. 1672 The columns of this table are: 1674 Name: This is a descriptive name that enables easier reference to 1675 the item. The name MUST be unique. It is not used in the 1676 encoding. 1678 Value: This is the value used to identify the curve. These values 1679 MUST be unique. The value can be a positive integer, a negative 1680 integer, or a string. 1682 Description: This field contains a brief description of the curve. 1684 References: This contains a pointer to the public specification for 1685 the curve if one exists. 1687 This registry has been initially populated by the values in Table 17. 1688 The specification column for all of these entries will be this 1689 document. 1691 8.4. COSE Elliptic Curves Registry 1693 IANA created and populated the "COSE Elliptic Curves" registry as 1694 part of processing [RFC8152]. IANA is requested to change the 1695 reference from [RFC8152] to this document for all values in the 1696 registry. 1698 This document does not change the guidance for Designated Experts. 1700 8.5. Expert Review Instructions 1702 All of the IANA registries established in this document are defined 1703 as expert review. This section gives some general guidelines for 1704 what the experts should be looking for, but they are being designated 1705 as experts for a reason, so they should be given substantial 1706 latitude. 1708 Expert reviewers should take into consideration the following points: 1710 o Point squatting should be discouraged. Reviewers are encouraged 1711 to get sufficient information for registration requests to ensure 1712 that the usage is not going to duplicate one that is already 1713 registered, and that the point is likely to be used in 1714 deployments. The zones tagged as private use are intended for 1715 testing purposes and closed environments; code points in other 1716 ranges should not be assigned for testing. 1718 o Specifications are required for the standards track range of point 1719 assignment. Specifications should exist for specification 1720 required ranges, but early assignment before a specification is 1721 available is considered to be permissible. Specifications are 1722 needed for the first-come, first-serve range if they are expected 1723 to be used outside of closed environments in an interoperable way. 1724 When specifications are not provided, the description provided 1725 needs to have sufficient information to identify what the point is 1726 being used for. 1728 o Experts should take into account the expected usage of fields when 1729 approving point assignment. The fact that there is a range for 1730 standards track documents does not mean that a standards track 1731 document cannot have points assigned outside of that range. The 1732 length of the encoded value should be weighed against how many 1733 code points of that length are left, the size of device it will be 1734 used on, and the number of code points left that encode to that 1735 size. 1737 o When algorithms are registered, vanity registrations should be 1738 discouraged. One way to do this is to require registrations to 1739 provide additional documentation on security analysis of the 1740 algorithm. Another thing that should be considered is requesting 1741 an opinion on the algorithm from the Crypto Forum Research Group 1742 (CFRG). Algorithms that do not meet the security requirements of 1743 the community and the messages structures should not be 1744 registered. 1746 9. Security Considerations 1748 There are a number of security considerations that need to be taken 1749 into account by implementers of this specification. The security 1750 considerations that are specific to an individual algorithm are 1751 placed next to the description of the algorithm. While some 1752 considerations have been highlighted here, additional considerations 1753 may be found in the documents listed in the references. 1755 Implementations need to protect the private key material for any 1756 individuals. There are some cases in this document that need to be 1757 highlighted on this issue. 1759 o Using the same key for two different algorithms can leak 1760 information about the key. It is therefore recommended that keys 1761 be restricted to a single algorithm. 1763 o Use of 'direct' as a recipient algorithm combined with a second 1764 recipient algorithm exposes the direct key to the second 1765 recipient. 1767 o Several of the algorithms in this document have limits on the 1768 number of times that a key can be used without leaking information 1769 about the key. 1771 The use of ECDH and direct plus KDF (with no key wrap) will not 1772 directly lead to the private key being leaked; the one way function 1773 of the KDF will prevent that. There is, however, a different issue 1774 that needs to be addressed. Having two recipients requires that the 1775 CEK be shared between two recipients. The second recipient therefore 1776 has a CEK that was derived from material that can be used for the 1777 weak proof of origin. The second recipient could create a message 1778 using the same CEK and send it to the first recipient; the first 1779 recipient would, for either static-static ECDH or direct plus KDF, 1780 make an assumption that the CEK could be used for proof of origin 1781 even though it is from the wrong entity. If the key wrap step is 1782 added, then no proof of origin is implied and this is not an issue. 1784 Although it has been mentioned before, the use of a single key for 1785 multiple algorithms has been demonstrated in some cases to leak 1786 information about a key, provide the opportunity for attackers to 1787 forge integrity tags, or gain information about encrypted content. 1788 Binding a key to a single algorithm prevents these problems. Key 1789 creators and key consumers are strongly encouraged not only to create 1790 new keys for each different algorithm, but to include that selection 1791 of algorithm in any distribution of key material and strictly enforce 1792 the matching of algorithms in the key structure to algorithms in the 1793 message structure. In addition to checking that algorithms are 1794 correct, the key form needs to be checked as well. Do not use an 1795 'EC2' key where an 'OKP' key is expected. 1797 Before using a key for transmission, or before acting on information 1798 received, a trust decision on a key needs to be made. Is the data or 1799 action something that the entity associated with the key has a right 1800 to see or a right to request? A number of factors are associated 1801 with this trust decision. Some of the ones that are highlighted here 1802 are: 1804 o What are the permissions associated with the key owner? 1806 o Is the cryptographic algorithm acceptable in the current context? 1808 o Have the restrictions associated with the key, such as algorithm 1809 or freshness, been checked and are they correct? 1811 o Is the request something that is reasonable, given the current 1812 state of the application? 1814 o Have any security considerations that are part of the message been 1815 enforced (as specified by the application or 'crit' parameter)? 1817 There are a large number of algorithms presented in this document 1818 that use nonce values. For all of the nonces defined in this 1819 document, there is some type of restriction on the nonce being a 1820 unique value either for a key or for some other conditions. In all 1821 of these cases, there is no known requirement on the nonce being both 1822 unique and unpredictable; under these circumstances, it's reasonable 1823 to use a counter for creation of the nonce. In cases where one wants 1824 the pattern of the nonce to be unpredictable as well as unique, one 1825 can use a key created for that purpose and encrypt the counter to 1826 produce the nonce value. 1828 One area that has been starting to get exposure is doing traffic 1829 analysis of encrypted messages based on the length of the message. 1830 This specification does not provide for a uniform method of providing 1831 padding as part of the message structure. An observer can 1832 distinguish between two different strings (for example, 'YES' and 1833 'NO') based on the length for all of the content encryption 1834 algorithms that are defined in this document. This means that it is 1835 up to the applications to document how content padding is to be done 1836 in order to prevent or discourage such analysis. (For example, the 1837 strings could be defined as 'YES' and 'NO '.) 1839 10. References 1841 10.1. Normative References 1843 [AES-GCM] National Institute of Standards and Technology, 1844 "Recommendation for Block Cipher Modes of Operation: 1845 Galois/Counter Mode (GCM) and GMAC", NIST Special 1846 Publication 800-38D, DOI 10.6028/NIST.SP.800-38D, November 1847 2007, . 1850 [DSS] National Institute of Standards and Technology, "Digital 1851 Signature Standard (DSS)", FIPS PUB 186-4, 1852 DOI 10.6028/NIST.FIPS.186-4, July 2013, 1853 . 1856 [I-D.schaad-cose-rfc8152bis-struct] 1857 Schaad, J., "CBOR Object Signing and Encryption (COSE) - 1858 Structures and Process", draft-schaad-cose-rfc8152bis- 1859 struct-01 (work in progress), December 2018. 1861 [MAC] National Institute of Standards and Technology, "Computer 1862 Data Authentication", FIPS PUB 113, May 1985, 1863 . 1866 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1867 Hashing for Message Authentication", RFC 2104, 1868 DOI 10.17487/RFC2104, February 1997, 1869 . 1871 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1872 Requirement Levels", BCP 14, RFC 2119, 1873 DOI 10.17487/RFC2119, March 1997, 1874 . 1876 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 1877 (AES) Key Wrap Algorithm", RFC 3394, DOI 10.17487/RFC3394, 1878 September 2002, . 1880 [RFC3610] Whiting, D., Housley, R., and N. Ferguson, "Counter with 1881 CBC-MAC (CCM)", RFC 3610, DOI 10.17487/RFC3610, September 1882 2003, . 1884 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 1885 Key Derivation Function (HKDF)", RFC 5869, 1886 DOI 10.17487/RFC5869, May 2010, 1887 . 1889 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 1890 Curve Cryptography Algorithms", RFC 6090, 1891 DOI 10.17487/RFC6090, February 2011, 1892 . 1894 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 1895 Algorithm (DSA) and Elliptic Curve Digital Signature 1896 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 1897 2013, . 1899 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1900 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1901 October 2013, . 1903 [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 1904 for Security", RFC 7748, DOI 10.17487/RFC7748, January 1905 2016, . 1907 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital 1908 Signature Algorithm (EdDSA)", RFC 8032, 1909 DOI 10.17487/RFC8032, January 2017, 1910 . 1912 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1913 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1914 May 2017, . 1916 [RFC8439] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF 1917 Protocols", RFC 8439, DOI 10.17487/RFC8439, June 2018, 1918 . 1920 [SEC1] Certicom Research, "SEC 1: Elliptic Curve Cryptography", 1921 Standards for Efficient Cryptography, Version 2.0, May 1922 2009, . 1924 10.2. Informative References 1926 [I-D.ietf-cbor-cddl] 1927 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 1928 definition language (CDDL): a notational convention to 1929 express CBOR and JSON data structures", draft-ietf-cbor- 1930 cddl-07 (work in progress), February 2019. 1932 [RFC4231] Nystrom, M., "Identifiers and Test Vectors for HMAC-SHA- 1933 224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512", 1934 RFC 4231, DOI 10.17487/RFC4231, December 2005, 1935 . 1937 [RFC4493] Song, JH., Poovendran, R., Lee, J., and T. Iwata, "The 1938 AES-CMAC Algorithm", RFC 4493, DOI 10.17487/RFC4493, June 1939 2006, . 1941 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 1942 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 1943 . 1945 [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, 1946 "Elliptic Curve Cryptography Subject Public Key 1947 Information", RFC 5480, DOI 10.17487/RFC5480, March 2009, 1948 . 1950 [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations 1951 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 1952 RFC 6151, DOI 10.17487/RFC6151, March 2011, 1953 . 1955 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1956 Application Protocol (CoAP)", RFC 7252, 1957 DOI 10.17487/RFC7252, June 2014, 1958 . 1960 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 1961 DOI 10.17487/RFC7518, May 2015, 1962 . 1964 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, 1965 "PKCS #1: RSA Cryptography Specifications Version 2.2", 1966 RFC 8017, DOI 10.17487/RFC8017, November 2016, 1967 . 1969 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1970 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1971 . 1973 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1974 Interchange Format", STD 90, RFC 8259, 1975 DOI 10.17487/RFC8259, December 2017, 1976 . 1978 [SP800-56A] 1979 Barker, E., Chen, L., Roginsky, A., and M. Smid, 1980 "Recommendation for Pair-Wise Key Establishment Schemes 1981 Using Discrete Logarithm Cryptography", NIST Special 1982 Publication 800-56A, Revision 2, 1983 DOI 10.6028/NIST.SP.800-56Ar2, May 2013, 1984 . 1987 Appendix A. Examples 1989 A GitHub project has been created at that contains not only the examples presented in this 1991 document, but a more complete set of testing examples as well. Each 1992 example is found in a JSON file that contains the inputs used to 1993 create the example, some of the intermediate values that can be used 1994 in debugging the example and the output of the example presented in 1995 both a hex and a CBOR diagnostic notation format. Some of the 1996 examples at the site are designed failure testing cases; these are 1997 clearly marked as such in the JSON file. If errors in the examples 1998 in this document are found, the examples on GitHub will be updated, 1999 and a note to that effect will be placed in the JSON file. 2001 Acknowledgments 2003 This document is a product of the COSE working group of the IETF. 2005 The following individuals are to blame for getting me started on this 2006 project in the first place: Richard Barnes, Matt Miller, and Martin 2007 Thomson. 2009 The initial version of the specification was based to some degree on 2010 the outputs of the JOSE and S/MIME working groups. 2012 The following individuals provided input into the final form of the 2013 document: Carsten Bormann, John Bradley, Brain Campbell, Michael B. 2014 Jones, Ilari Liusvaara, Francesca Palombini, Ludwig Seitz, and Goran 2015 Selander. 2017 Author's Address 2019 Jim Schaad 2020 August Cellars 2022 Email: ietf@augustcellars.com