idnits 2.17.1 draft-ietf-cose-rfc8152bis-algs-03.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.ietf-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 (June 10, 2019) is 1774 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' == Outdated reference: A later version (-15) exists of draft-ietf-cose-rfc8152bis-struct-02 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-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' -- 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) June 10, 2019 5 Intended status: Standards Track 6 Expires: December 12, 2019 8 CBOR Object Signing and Encryption (COSE): Initial Algorithms 9 draft-ietf-cose-rfc8152bis-algs-03 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.ietf-cose-rfc8152bis-struct]. 26 This document along with [I-D.ietf-cose-rfc8152bis-struct] obsoletes 27 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 December 12, 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 1.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . 4 77 2. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 5 78 2.1. ECDSA . . . . . . . . . . . . . . . . . . . . . . . . . . 5 79 2.1.1. Security Considerations . . . . . . . . . . . . . . . 6 80 2.2. Edwards-Curve Digital Signature Algorithms (EdDSAs) . . . 7 81 2.2.1. Security Considerations . . . . . . . . . . . . . . . 8 82 3. Message Authentication Code (MAC) Algorithms . . . . . . . . 8 83 3.1. Hash-Based Message Authentication Codes (HMACs) . . . . . 9 84 3.1.1. Security Considerations . . . . . . . . . . . . . . . 10 85 3.2. AES Message Authentication Code (AES-CBC-MAC) . . . . . . 10 86 3.2.1. Security Considerations . . . . . . . . . . . . . . . 11 87 4. Content Encryption Algorithms . . . . . . . . . . . . . . . . 12 88 4.1. AES GCM . . . . . . . . . . . . . . . . . . . . . . . . . 12 89 4.1.1. Security Considerations . . . . . . . . . . . . . . . 13 90 4.2. AES CCM . . . . . . . . . . . . . . . . . . . . . . . . . 13 91 4.2.1. Security Considerations . . . . . . . . . . . . . . . 16 92 4.3. ChaCha20 and Poly1305 . . . . . . . . . . . . . . . . . . 16 93 4.3.1. Security Considerations . . . . . . . . . . . . . . . 17 94 5. Key Derivation Functions (KDFs) . . . . . . . . . . . . . . . 17 95 5.1. HMAC-Based Extract-and-Expand Key Derivation Function 96 (HKDF) . . . . . . . . . . . . . . . . . . . . . . . . . 18 98 5.2. Context Information Structure . . . . . . . . . . . . . . 19 99 6. Content Key Distribution Methods . . . . . . . . . . . . . . 24 100 6.1. Direct Encryption . . . . . . . . . . . . . . . . . . . . 24 101 6.1.1. Direct Key . . . . . . . . . . . . . . . . . . . . . 24 102 6.1.2. Direct Key with KDF . . . . . . . . . . . . . . . . . 25 103 6.2. AES Key Wrap . . . . . . . . . . . . . . . . . . . . . . 27 104 6.2.1. Security Considerations for AES-KW . . . . . . . . . 28 105 6.3. Direct ECDH . . . . . . . . . . . . . . . . . . . . . . . 28 106 6.3.1. Security Considerations . . . . . . . . . . . . . . . 31 107 6.4. ECDH with Key Wrap . . . . . . . . . . . . . . . . . . . 31 108 7. Key Object Parameters . . . . . . . . . . . . . . . . . . . . 33 109 7.1. Elliptic Curve Keys . . . . . . . . . . . . . . . . . . . 33 110 7.1.1. Double Coordinate Curves . . . . . . . . . . . . . . 34 111 7.2. Octet Key Pair . . . . . . . . . . . . . . . . . . . . . 35 112 7.3. Symmetric Keys . . . . . . . . . . . . . . . . . . . . . 36 113 8. CBOR Encoding Restrictions . . . . . . . . . . . . . . . . . 36 114 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 115 10. Security Considerations . . . . . . . . . . . . . . . . . . . 37 116 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 117 11.1. Normative References . . . . . . . . . . . . . . . . . . 39 118 11.2. Informative References . . . . . . . . . . . . . . . . . 41 119 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 42 120 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 42 122 1. Introduction 124 There has been an increased focus on small, constrained devices that 125 make up the Internet of Things (IoT). One of the standards that has 126 come out of this process is "Concise Binary Object Representation 127 (CBOR)" [RFC7049]. CBOR extended the data model of the JavaScript 128 Object Notation (JSON) [RFC8259] by allowing for binary data, among 129 other changes. CBOR is being adopted by several of the IETF working 130 groups dealing with the IoT world as their encoding of data 131 structures. CBOR was designed specifically to be both small in terms 132 of messages transport and implementation size and be a schema-free 133 decoder. A need exists to provide message security services for IoT, 134 and using CBOR as the message-encoding format makes sense. 136 The core COSE specification consists of two documents. 137 [I-D.ietf-cose-rfc8152bis-struct] contains the serialization 138 structures and the procedures for using the different cryptographic 139 algorithms. This document provides for an initial set of algorithms 140 that are then use with those structures. Additional algorithms 141 beyond what are in this document are defined elsewhere. 143 1.1. Requirements Terminology 145 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 146 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 147 "OPTIONAL" in this document are to be interpreted as described in BCP 148 14 [RFC2119] [RFC8174] when, and only when, they appear in all 149 capitals, as shown here. 151 1.2. Changes from RFC8152 153 o Extract the sections dealing with specific algorithms into this 154 document. The sections dealing with structure and general 155 processing rules are placed in [I-D.ietf-cose-rfc8152bis-struct]. 157 1.3. Document Terminology 159 In this document, we use the following terminology: 161 Byte is a synonym for octet. 163 Constrained Application Protocol (CoAP) is a specialized web transfer 164 protocol for use in constrained systems. It is defined in [RFC7252]. 166 Authenticated Encryption (AE) [RFC5116] algorithms are those 167 encryption algorithms that provide an authentication check of the 168 plain text contents as part of the encryption service. 170 Authenticated Encryption with Authenticated Data (AEAD) [RFC5116] 171 algorithms provide the same content authentication service as AE 172 algorithms, but they additionally provide for authentication of non- 173 encrypted data as well. 175 1.4. CBOR Grammar 177 At the time that [RFC8152] was initially published, the CBOR Data 178 Definition Language (CDDL) [I-D.ietf-cbor-cddl] had not yet been 179 published. This document uses a variant of CDDL which is described 180 in [I-D.ietf-cose-rfc8152bis-struct] 182 1.5. Examples 184 A GitHub project has been created at that contains a set of testing examples as well. Each 186 example is found in a JSON file that contains the inputs used to 187 create the example, some of the intermediate values that can be used 188 in debugging the example and the output of the example presented in 189 both a hex and a CBOR diagnostic notation format. Some of the 190 examples at the site are designed failure testing cases; these are 191 clearly marked as such in the JSON file. If errors in the examples 192 in this document are found, the examples on GitHub will be updated, 193 and a note to that effect will be placed in the JSON file. 195 2. Signature Algorithms 197 Section 9 of [I-D.ietf-cose-rfc8152bis-struct] 198 [I-D.ietf-cose-rfc8152bis-struct] contains a generic description of 199 signature algorithms. The document defines signature algorithm 200 identifiers for two signature algorithms. 202 2.1. ECDSA 204 ECDSA [DSS] defines a signature algorithm using ECC. Implementations 205 SHOULD use a deterministic version of ECDSA such as the one defined 206 in [RFC6979]. The use of a deterministic signature algorithm allows 207 for systems to avoid relying on random number generators in order to 208 avoid generating the same value of 'k' (the per-message random 209 value). Biased generation of the value 'k' can be attacked, and 210 collisions of this value leads to leaked keys. It additionally 211 allows for doing deterministic tests for the signature algorithm. 212 The use of deterministic ECDSA does not lessen the need to have good 213 random number generation when creating the private key. 215 The ECDSA signature algorithm is parameterized with a hash function 216 (h). In the event that the length of the hash function output is 217 greater than the group of the key, the leftmost bytes of the hash 218 output are used. 220 The algorithms defined in this document can be found in Table 1. 222 +-------+-------+---------+------------------+ 223 | Name | Value | Hash | Description | 224 +-------+-------+---------+------------------+ 225 | ES256 | -7 | SHA-256 | ECDSA w/ SHA-256 | 226 | ES384 | -35 | SHA-384 | ECDSA w/ SHA-384 | 227 | ES512 | -36 | SHA-512 | ECDSA w/ SHA-512 | 228 +-------+-------+---------+------------------+ 230 Table 1: ECDSA Algorithm Values 232 This document defines ECDSA to work only with the curves P-256, 233 P-384, and P-521. This document requires that the curves be encoded 234 using the 'EC2' (2 coordinate elliptic curve) key type. 235 Implementations need to check that the key type and curve are correct 236 when creating and verifying a signature. Other documents can define 237 it to work with other curves and points in the future. 239 In order to promote interoperability, it is suggested that SHA-256 be 240 used only with curve P-256, SHA-384 be used only with curve P-384, 241 and SHA-512 be used with curve P-521. This is aligned with the 242 recommendation in Section 4 of [RFC5480]. 244 The signature algorithm results in a pair of integers (R, S). These 245 integers will be the same length as the length of the key used for 246 the signature process. The signature is encoded by converting the 247 integers into bit strings of the same length as the key size. The 248 length is rounded up to the nearest byte and is left padded with zero 249 bits to get to the correct length. The two integers are then 250 concatenated together to form a byte string that is the resulting 251 signature. 253 Using the function defined in [RFC8017], the signature is: 255 Signature = I2OSP(R, n) | I2OSP(S, n) 256 where n = ceiling(key_length / 8) 258 When using a COSE key for this algorithm, the following checks are 259 made: 261 o The 'kty' field MUST be present, and it MUST be 'EC2'. 263 o If the 'alg' field is present, it MUST match the ECDSA signature 264 algorithm being used. 266 o If the 'key_ops' field is present, it MUST include 'sign' when 267 creating an ECDSA signature. 269 o If the 'key_ops' field is present, it MUST include 'verify' when 270 verifying an ECDSA signature. 272 2.1.1. Security Considerations 274 The security strength of the signature is no greater than the minimum 275 of the security strength associated with the bit length of the key 276 and the security strength of the hash function. 278 Note: Use of a deterministic signature technique is a good idea even 279 when good random number generation exists. Doing so both reduces the 280 possibility of having the same value of 'k' in two signature 281 operations and allows for reproducible signature values, which helps 282 testing. 284 There are two substitution attacks that can theoretically be mounted 285 against the ECDSA signature algorithm. 287 o Changing the curve used to validate the signature: If one changes 288 the curve used to validate the signature, then potentially one 289 could have two messages with the same signature, each computed 290 under a different curve. The only requirement on the new curve is 291 that its order be the same as the old one and it be acceptable to 292 the client. An example would be to change from using the curve 293 secp256r1 (aka P-256) to using secp256k1. (Both are 256-bit 294 curves.) We currently do not have any way to deal with this 295 version of the attack except to restrict the overall set of curves 296 that can be used. 298 o Change the hash function used to validate the signature: If one 299 either has two different hash functions of the same length or can 300 truncate a hash function down, then one could potentially find 301 collisions between the hash functions rather than within a single 302 hash function (for example, truncating SHA-512 to 256 bits might 303 collide with a SHA-256 bit hash value). As the hash algorithm is 304 part of the signature algorithm identifier, this attack is 305 mitigated by including a signature algorithm identifier in the 306 protected header. 308 2.2. Edwards-Curve Digital Signature Algorithms (EdDSAs) 310 [RFC8032] describes the elliptic curve signature scheme Edwards-curve 311 Digital Signature Algorithm (EdDSA). In that document, the signature 312 algorithm is instantiated using parameters for edwards25519 and 313 edwards448 curves. The document additionally describes two variants 314 of the EdDSA algorithm: Pure EdDSA, where no hash function is applied 315 to the content before signing, and HashEdDSA, where a hash function 316 is applied to the content before signing and the result of that hash 317 function is signed. For EdDSA, the content to be signed (either the 318 message or the pre-hash value) is processed twice inside of the 319 signature algorithm. For use with COSE, only the pure EdDSA version 320 is used. This is because it is not expected that extremely large 321 contents are going to be needed and, based on the arrangement of the 322 message structure, the entire message is going to need to be held in 323 memory in order to create or verify a signature. This means that 324 there does not appear to be a need to be able to do block updates of 325 the hash, followed by eliminating the message from memory. 326 Applications can provide the same features by defining the content of 327 the message as a hash value and transporting the COSE object (with 328 the hash value) and the content as separate items. 330 The algorithms defined in this document can be found in Table 2. A 331 single signature algorithm is defined, which can be used for multiple 332 curves. 334 +-------+-------+-------------+ 335 | Name | Value | Description | 336 +-------+-------+-------------+ 337 | EdDSA | -8 | EdDSA | 338 +-------+-------+-------------+ 340 Table 2: EdDSA Algorithm Values 342 [RFC8032] describes the method of encoding the signature value. 344 When using a COSE key for this algorithm, the following checks are 345 made: 347 o The 'kty' field MUST be present, and it MUST be 'OKP' (Octet Key 348 Pair). 350 o The 'crv' field MUST be present, and it MUST be a curve defined 351 for this signature algorithm. 353 o If the 'alg' field is present, it MUST match 'EdDSA'. 355 o If the 'key_ops' field is present, it MUST include 'sign' when 356 creating an EdDSA signature. 358 o If the 'key_ops' field is present, it MUST include 'verify' when 359 verifying an EdDSA signature. 361 2.2.1. Security Considerations 363 How public values are computed is not the same when looking at EdDSA 364 and Elliptic Curve Diffie-Hellman (ECDH); for this reason, they 365 should not be used with the other algorithm. 367 If batch signature verification is performed, a well-seeded 368 cryptographic random number generator is REQUIRED. Signing and non- 369 batch signature verification are deterministic operations and do not 370 need random numbers of any kind. 372 3. Message Authentication Code (MAC) Algorithms 374 Section 10 of [I-D.ietf-cose-rfc8152bis-struct] 375 [I-D.ietf-cose-rfc8152bis-struct] contains a generic description of 376 MAC algorithms. This section defines the conventions for two MAC 377 algorithms. 379 3.1. Hash-Based Message Authentication Codes (HMACs) 381 HMAC [RFC2104] [RFC4231] was designed to deal with length extension 382 attacks. The algorithm was also designed to allow for new hash 383 algorithms to be directly plugged in without changes to the hash 384 function. The HMAC design process has been shown as solid since, 385 while the security of hash algorithms such as MD5 has decreased over 386 time; the security of HMAC combined with MD5 has not yet been shown 387 to be compromised [RFC6151]. 389 The HMAC algorithm is parameterized by an inner and outer padding, a 390 hash function (h), and an authentication tag value length. For this 391 specification, the inner and outer padding are fixed to the values 392 set in [RFC2104]. The length of the authentication tag corresponds 393 to the difficulty of producing a forgery. For use in constrained 394 environments, we define one HMAC algorithms that is truncated. There 395 are currently no known issues with truncation; however, the security 396 strength of the message tag is correspondingly reduced in strength. 397 When truncating, the leftmost tag length bits are kept and 398 transmitted. 400 The algorithms defined in this document can be found in Table 3. 402 +-----------+-------+---------+----------+--------------------------+ 403 | Name | Value | Hash | Tag | Description | 404 | | | | Length | | 405 +-----------+-------+---------+----------+--------------------------+ 406 | HMAC | 4 | SHA-256 | 64 | HMAC w/ SHA-256 | 407 | 256/64 | | | | truncated to 64 bits | 408 | HMAC | 5 | SHA-256 | 256 | HMAC w/ SHA-256 | 409 | 256/256 | | | | | 410 | HMAC | 6 | SHA-384 | 384 | HMAC w/ SHA-384 | 411 | 384/384 | | | | | 412 | HMAC | 7 | SHA-512 | 512 | HMAC w/ SHA-512 | 413 | 512/512 | | | | | 414 +-----------+-------+---------+----------+--------------------------+ 416 Table 3: HMAC Algorithm Values 418 Some recipient algorithms carry the key while others derive a key 419 from secret data. For those algorithms that carry the key (such as 420 AES Key Wrap), the size of the HMAC key SHOULD be the same size as 421 the underlying hash function. For those algorithms that derive the 422 key (such as ECDH), the derived key MUST be the same size as the 423 underlying hash function. 425 When using a COSE key for this algorithm, the following checks are 426 made: 428 o The 'kty' field MUST be present, and it MUST be 'Symmetric'. 430 o If the 'alg' field is present, it MUST match the HMAC algorithm 431 being used. 433 o If the 'key_ops' field is present, it MUST include 'MAC create' 434 when creating an HMAC authentication tag. 436 o If the 'key_ops' field is present, it MUST include 'MAC verify' 437 when verifying an HMAC authentication tag. 439 Implementations creating and validating MAC values MUST validate that 440 the key type, key length, and algorithm are correct and appropriate 441 for the entities involved. 443 3.1.1. Security Considerations 445 HMAC has proved to be resistant to attack even when used with 446 weakened hash algorithms. The current best known attack is to brute 447 force the key. This means that key size is going to be directly 448 related to the security of an HMAC operation. 450 3.2. AES Message Authentication Code (AES-CBC-MAC) 452 AES-CBC-MAC is defined in [MAC]. (Note that this is not the same 453 algorithm as AES Cipher-Based Message Authentication Code (AES-CMAC) 454 [RFC4493].) 456 AES-CBC-MAC is parameterized by the key length, the authentication 457 tag length, and the IV used. For all of these algorithms, the IV is 458 fixed to all zeros. We provide an array of algorithms for various 459 key lengths and tag lengths. The algorithms defined in this document 460 are found in Table 4. 462 +-------------+-------+----------+----------+-----------------------+ 463 | Name | Value | Key | Tag | Description | 464 | | | Length | Length | | 465 +-------------+-------+----------+----------+-----------------------+ 466 | AES-MAC | 14 | 128 | 64 | AES-MAC 128-bit key, | 467 | 128/64 | | | | 64-bit tag | 468 | AES-MAC | 15 | 256 | 64 | AES-MAC 256-bit key, | 469 | 256/64 | | | | 64-bit tag | 470 | AES-MAC | 25 | 128 | 128 | AES-MAC 128-bit key, | 471 | 128/128 | | | | 128-bit tag | 472 | AES-MAC | 26 | 256 | 128 | AES-MAC 256-bit key, | 473 | 256/128 | | | | 128-bit tag | 474 +-------------+-------+----------+----------+-----------------------+ 476 Table 4: AES-MAC Algorithm Values 478 Keys may be obtained either from a key structure or from a recipient 479 structure. Implementations creating and validating MAC values MUST 480 validate that the key type, key length, and algorithm are correct and 481 appropriate for the entities involved. 483 When using a COSE key for this algorithm, the following checks are 484 made: 486 o The 'kty' field MUST be present, and it MUST be 'Symmetric'. 488 o If the 'alg' field is present, it MUST match the AES-MAC algorithm 489 being used. 491 o If the 'key_ops' field is present, it MUST include 'MAC create' 492 when creating an AES-MAC authentication tag. 494 o If the 'key_ops' field is present, it MUST include 'MAC verify' 495 when verifying an AES-MAC authentication tag. 497 3.2.1. Security Considerations 499 A number of attacks exist against Cipher Block Chaining Message 500 Authentication Code (CBC-MAC) that need to be considered. 502 o A single key must only be used for messages of a fixed or known 503 length. If this is not the case, an attacker will be able to 504 generate a message with a valid tag given two message and tag 505 pairs. This can be addressed by using different keys for messages 506 of different lengths. The current structure mitigates this 507 problem, as a specific encoding structure that includes lengths is 508 built and signed. (CMAC also addresses this issue.) 510 o Cipher Block Chaining (CBC) mode, if the same key is used for both 511 encryption and authentication operations, an attacker can produce 512 messages with a valid authentication code. 514 o If the IV can be modified, then messages can be forged. This is 515 addressed by fixing the IV to all zeros. 517 4. Content Encryption Algorithms 519 Section 11 of [I-D.ietf-cose-rfc8152bis-struct] 520 [I-D.ietf-cose-rfc8152bis-struct] contains a generic description of 521 Content Encryption algorithms. This document defines the identifier 522 and usages for three content encryption algorithms. 524 4.1. AES GCM 526 The Galois/Counter Mode (GCM) mode is a generic authenticated 527 encryption block cipher mode defined in [AES-GCM]. The GCM mode is 528 combined with the AES block encryption algorithm to define an AEAD 529 cipher. 531 The GCM mode is parameterized by the size of the authentication tag 532 and the size of the nonce. This document fixes the size of the nonce 533 at 96 bits. The size of the authentication tag is limited to a small 534 set of values. For this document however, the size of the 535 authentication tag is fixed at 128 bits. 537 The set of algorithms defined in this document are in Table 5. 539 +---------+-------+------------------------------------------+ 540 | Name | Value | Description | 541 +---------+-------+------------------------------------------+ 542 | A128GCM | 1 | AES-GCM mode w/ 128-bit key, 128-bit tag | 543 | A192GCM | 2 | AES-GCM mode w/ 192-bit key, 128-bit tag | 544 | A256GCM | 3 | AES-GCM mode w/ 256-bit key, 128-bit tag | 545 +---------+-------+------------------------------------------+ 547 Table 5: Algorithm Value for AES-GCM 549 Keys may be obtained either from a key structure or from a recipient 550 structure. Implementations encrypting and decrypting MUST validate 551 that the key type, key length, and algorithm are correct and 552 appropriate for the entities involved. 554 When using a COSE key for this algorithm, the following checks are 555 made: 557 o The 'kty' field MUST be present, and it MUST be 'Symmetric'. 559 o If the 'alg' field is present, it MUST match the AES-GCM algorithm 560 being used. 562 o If the 'key_ops' field is present, it MUST include 'encrypt' or 563 'wrap key' when encrypting. 565 o If the 'key_ops' field is present, it MUST include 'decrypt' or 566 'unwrap key' when decrypting. 568 4.1.1. Security Considerations 570 When using AES-GCM, the following restrictions MUST be enforced: 572 o The key and nonce pair MUST be unique for every message encrypted. 574 o The total amount of data encrypted for a single key MUST NOT 575 exceed 2^39 - 256 bits. An explicit check is required only in 576 environments where it is expected that it might be exceeded. 578 Consideration was given to supporting smaller tag values; the 579 constrained community would desire tag sizes in the 64-bit range. 580 Doing so drastically changes both the maximum messages size 581 (generally not an issue) and the number of times that a key can be 582 used. Given that Counter with CBC-MAC (CCM) is the usual mode for 583 constrained environments, restricted modes are not supported. 585 4.2. AES CCM 587 CCM is a generic authentication encryption block cipher mode defined 588 in [RFC3610]. The CCM mode is combined with the AES block encryption 589 algorithm to define a commonly used content encryption algorithm used 590 in constrained devices. 592 The CCM mode has two parameter choices. The first choice is M, the 593 size of the authentication field. The choice of the value for M 594 involves a trade-off between message growth (from the tag) and the 595 probability that an attacker can undetectably modify a message. The 596 second choice is L, the size of the length field. This value 597 requires a trade-off between the maximum message size and the size of 598 the Nonce. 600 It is unfortunate that the specification for CCM specified L and M as 601 a count of bytes rather than a count of bits. This leads to possible 602 misunderstandings where AES-CCM-8 is frequently used to refer to a 603 version of CCM mode where the size of the authentication is 64 bits 604 and not 8 bits. These values have traditionally been specified as 605 bit counts rather than byte counts. This document will follow the 606 convention of using bit counts so that it is easier to compare the 607 different algorithms presented in this document. 609 We define a matrix of algorithms in this document over the values of 610 L and M. Constrained devices are usually operating in situations 611 where they use short messages and want to avoid doing recipient- 612 specific cryptographic operations. This favors smaller values of 613 both L and M. Less-constrained devices will want to be able to use 614 larger messages and are more willing to generate new keys for every 615 operation. This favors larger values of L and M. 617 The following values are used for L: 619 16 bits (2): This limits messages to 2^16 bytes (64 KiB) in length. 620 This is sufficiently long for messages in the constrained world. 621 The nonce length is 13 bytes allowing for 2^104 possible values of 622 the nonce without repeating. 624 64 bits (8): This limits messages to 2^64 bytes in length. The 625 nonce length is 7 bytes allowing for 2^56 possible values of the 626 nonce without repeating. 628 The following values are used for M: 630 64 bits (8): This produces a 64-bit authentication tag. This 631 implies that there is a 1 in 2^64 chance that a modified message 632 will authenticate. 634 128 bits (16): This produces a 128-bit authentication tag. This 635 implies that there is a 1 in 2^128 chance that a modified message 636 will authenticate. 638 +--------------------+-------+----+-----+-----+---------------------+ 639 | Name | Value | L | M | k | Description | 640 +--------------------+-------+----+-----+-----+---------------------+ 641 | AES-CCM-16-64-128 | 10 | 16 | 64 | 128 | AES-CCM mode | 642 | | | | | | 128-bit key, 64-bit | 643 | | | | | | tag, 13-byte nonce | 644 | AES-CCM-16-64-256 | 11 | 16 | 64 | 256 | AES-CCM mode | 645 | | | | | | 256-bit key, 64-bit | 646 | | | | | | tag, 13-byte nonce | 647 | AES-CCM-64-64-128 | 12 | 64 | 64 | 128 | AES-CCM mode | 648 | | | | | | 128-bit key, 64-bit | 649 | | | | | | tag, 7-byte nonce | 650 | AES-CCM-64-64-256 | 13 | 64 | 64 | 256 | AES-CCM mode | 651 | | | | | | 256-bit key, 64-bit | 652 | | | | | | tag, 7-byte nonce | 653 | AES-CCM-16-128-128 | 30 | 16 | 128 | 128 | AES-CCM mode | 654 | | | | | | 128-bit key, | 655 | | | | | | 128-bit tag, | 656 | | | | | | 13-byte nonce | 657 | AES-CCM-16-128-256 | 31 | 16 | 128 | 256 | AES-CCM mode | 658 | | | | | | 256-bit key, | 659 | | | | | | 128-bit tag, | 660 | | | | | | 13-byte nonce | 661 | AES-CCM-64-128-128 | 32 | 64 | 128 | 128 | AES-CCM mode | 662 | | | | | | 128-bit key, | 663 | | | | | | 128-bit tag, 7-byte | 664 | | | | | | nonce | 665 | AES-CCM-64-128-256 | 33 | 64 | 128 | 256 | AES-CCM mode | 666 | | | | | | 256-bit key, | 667 | | | | | | 128-bit tag, 7-byte | 668 | | | | | | nonce | 669 +--------------------+-------+----+-----+-----+---------------------+ 671 Table 6: Algorithm Values for AES-CCM 673 Keys may be obtained either from a key structure or from a recipient 674 structure. Implementations encrypting and decrypting MUST validate 675 that the key type, key length, and algorithm are correct and 676 appropriate for the entities involved. 678 When using a COSE key for this algorithm, the following checks are 679 made: 681 o The 'kty' field MUST be present, and it MUST be 'Symmetric'. 683 o If the 'alg' field is present, it MUST match the AES-CCM algorithm 684 being used. 686 o If the 'key_ops' field is present, it MUST include 'encrypt' or 687 'wrap key' when encrypting. 689 o If the 'key_ops' field is present, it MUST include 'decrypt' or 690 'unwrap key' when decrypting. 692 4.2.1. Security Considerations 694 When using AES-CCM, the following restrictions MUST be enforced: 696 o The key and nonce pair MUST be unique for every message encrypted. 697 Note that the value of L influences the number of unique nonces. 699 o The total number of times the AES block cipher is used MUST NOT 700 exceed 2^61 operations. This limitation is the sum of times the 701 block cipher is used in computing the MAC value and in performing 702 stream encryption operations. An explicit check is required only 703 in environments where it is expected that it might be exceeded. 705 [RFC3610] additionally calls out one other consideration of note. It 706 is possible to do a pre-computation attack against the algorithm in 707 cases where portions of the plaintext are highly predictable. This 708 reduces the security of the key size by half. Ways to deal with this 709 attack include adding a random portion to the nonce value and/or 710 increasing the key size used. Using a portion of the nonce for a 711 random value will decrease the number of messages that a single key 712 can be used for. Increasing the key size may require more resources 713 in the constrained device. See Sections 5 and 10 of [RFC3610] for 714 more information. 716 4.3. ChaCha20 and Poly1305 718 ChaCha20 and Poly1305 combined together is an AEAD mode that is 719 defined in [RFC8439]. This is an algorithm defined to be a cipher 720 that is not AES and thus would not suffer from any future weaknesses 721 found in AES. These cryptographic functions are designed to be fast 722 in software-only implementations. 724 The ChaCha20/Poly1305 AEAD construction defined in [RFC8439] has no 725 parameterization. It takes a 256-bit key and a 96-bit nonce, as well 726 as the plaintext and additional data as inputs and produces the 727 ciphertext as an option. We define one algorithm identifier for this 728 algorithm in Table 7. 730 +-------------------+-------+---------------------------------------+ 731 | Name | Value | Description | 732 +-------------------+-------+---------------------------------------+ 733 | ChaCha20/Poly1305 | 24 | ChaCha20/Poly1305 w/ 256-bit key, | 734 | | | 128-bit tag | 735 +-------------------+-------+---------------------------------------+ 737 Table 7: Algorithm Value for AES-GCM 739 Keys may be obtained either from a key structure or from a recipient 740 structure. Implementations encrypting and decrypting MUST validate 741 that the key type, key length, and algorithm are correct and 742 appropriate for the entities involved. 744 When using a COSE key for this algorithm, the following checks are 745 made: 747 o The 'kty' field MUST be present, and it MUST be 'Symmetric'. 749 o If the 'alg' field is present, it MUST match the ChaCha20/Poly1305 750 algorithm being used. 752 o If the 'key_ops' field is present, it MUST include 'encrypt' or 753 'wrap key' when encrypting. 755 o If the 'key_ops' field is present, it MUST include 'decrypt' or 756 'unwrap key' when decrypting. 758 4.3.1. Security Considerations 760 The key and nounce values MUST be a unique pair for every invocation 761 of the algorithm. Nonce counters are considered to be an acceptable 762 way of ensuring that they are unique. 764 5. Key Derivation Functions (KDFs) 766 Section 12 of [I-D.ietf-cose-rfc8152bis-struct] 767 [I-D.ietf-cose-rfc8152bis-struct] contains a generic description of 768 Key Derivation Functions. This document defines a single context 769 structure and a single KDF. These elements are used for all of the 770 recipient algorithms defined in this document that require a KDF 771 process. These algorithms are defined in Sections 6.1.2, 6.3, and 772 6.4. 774 5.1. HMAC-Based Extract-and-Expand Key Derivation Function (HKDF) 776 The HKDF key derivation algorithm is defined in [RFC5869]. 778 The HKDF algorithm takes these inputs: 780 secret -- a shared value that is secret. Secrets may be either 781 previously shared or derived from operations like a Diffie-Hellman 782 (DH) key agreement. 784 salt -- an optional value that is used to change the generation 785 process. The salt value can be either public or private. If the 786 salt is public and carried in the message, then the 'salt' 787 algorithm header parameter defined in Table 9 is used. While 788 [RFC5869] suggests that the length of the salt be the same as the 789 length of the underlying hash value, any amount of salt will 790 improve the security as different key values will be generated. 791 This parameter is protected by being included in the key 792 computation and does not need to be separately authenticated. The 793 salt value does not need to be unique for every message sent. 795 length -- the number of bytes of output that need to be generated. 797 context information -- Information that describes the context in 798 which the resulting value will be used. Making this information 799 specific to the context in which the material is going to be used 800 ensures that the resulting material will always be tied to that 801 usage. The context structure defined in Section 5.2 is used by 802 the KDFs in this document. 804 PRF -- The underlying pseudorandom function to be used in the HKDF 805 algorithm. The PRF is encoded into the HKDF algorithm selection. 807 HKDF is defined to use HMAC as the underlying PRF. However, it is 808 possible to use other functions in the same construct to provide a 809 different KDF that is more appropriate in the constrained world. 810 Specifically, one can use AES-CBC-MAC as the PRF for the expand step, 811 but not for the extract step. When using a good random shared secret 812 of the correct length, the extract step can be skipped. For the AES 813 algorithm versions, the extract step is always skipped. 815 The extract step cannot be skipped if the secret is not uniformly 816 random, for example, if it is the result of an ECDH key agreement 817 step. This implies that the AES HKDF version cannot be used with 818 ECDH. If the extract step is skipped, the 'salt' value is not used 819 as part of the HKDF functionality. 821 The algorithms defined in this document are found in Table 8. 823 +---------------+-----------------+---------------------------------+ 824 | Name | PRF | Description | 825 +---------------+-----------------+---------------------------------+ 826 | HKDF SHA-256 | HMAC with | HKDF using HMAC SHA-256 as the | 827 | | SHA-256 | PRF | 828 | HKDF SHA-512 | HMAC with | HKDF using HMAC SHA-512 as the | 829 | | SHA-512 | PRF | 830 | HKDF AES- | AES-CBC-MAC-128 | HKDF using AES-MAC as the PRF | 831 | MAC-128 | | w/ 128-bit key | 832 | HKDF AES- | AES-CBC-MAC-256 | HKDF using AES-MAC as the PRF | 833 | MAC-256 | | w/ 256-bit key | 834 +---------------+-----------------+---------------------------------+ 836 Table 8: HKDF Algorithms 838 +------+-------+------+-------------------------------+-------------+ 839 | Name | Label | Type | Algorithm | Description | 840 +------+-------+------+-------------------------------+-------------+ 841 | salt | -20 | bstr | direct+HKDF-SHA-256, direct | Random salt | 842 | | | | +HKDF-SHA-512, direct+HKDF- | | 843 | | | | AES-128, direct+HKDF-AES-256, | | 844 | | | | ECDH-ES+HKDF-256, ECDH- | | 845 | | | | ES+HKDF-512, ECDH- | | 846 | | | | SS+HKDF-256, ECDH- | | 847 | | | | SS+HKDF-512, ECDH-ES+A128KW, | | 848 | | | | ECDH-ES+A192KW, ECDH- | | 849 | | | | ES+A256KW, ECDH-SS+A128KW, | | 850 | | | | ECDH-SS+A192KW, ECDH- | | 851 | | | | SS+A256KW | | 852 +------+-------+------+-------------------------------+-------------+ 854 Table 9: HKDF Algorithm Parameters 856 5.2. Context Information Structure 858 The context information structure is used to ensure that the derived 859 keying material is "bound" to the context of the transaction. The 860 context information structure used here is based on that defined in 861 [SP800-56A]. By using CBOR for the encoding of the context 862 information structure, we automatically get the same type and length 863 separation of fields that is obtained by the use of ASN.1. This 864 means that there is no need to encode the lengths for the base 865 elements, as it is done by the encoding used in JOSE (Section 4.6.2 866 of [RFC7518]). 868 The context information structure refers to PartyU and PartyV as the 869 two parties that are doing the key derivation. Unless the 870 application protocol defines differently, we assign PartyU to the 871 entity that is creating the message and PartyV to the entity that is 872 receiving the message. By doing this association, different keys 873 will be derived for each direction as the context information is 874 different in each direction. 876 The context structure is built from information that is known to both 877 entities. This information can be obtained from a variety of 878 sources: 880 o Fields can be defined by the application. This is commonly used 881 to assign fixed names to parties, but it can be used for other 882 items such as nonces. 884 o Fields can be defined by usage of the output. Examples of this 885 are the algorithm and key size that are being generated. 887 o Fields can be defined by parameters from the message. We define a 888 set of parameters in Table 10 that can be used to carry the values 889 associated with the context structure. Examples of this are 890 identities and nonce values. These parameters are designed to be 891 placed in the unprotected bucket of the recipient structure; they 892 do not need to be in the protected bucket since they already are 893 included in the cryptographic computation by virtue of being 894 included in the context structure. 896 +----------+-------+------+---------------------------+-------------+ 897 | Name | Label | Type | Algorithm | Description | 898 +----------+-------+------+---------------------------+-------------+ 899 | PartyU | -21 | bstr | direct+HKDF-SHA-256, | Party U | 900 | identity | | | direct+HKDF-SHA-512, | identity | 901 | | | | direct+HKDF-AES-128, | information | 902 | | | | direct+HKDF-AES-256, | | 903 | | | | ECDH-ES+HKDF-256, ECDH- | | 904 | | | | ES+HKDF-512, ECDH- | | 905 | | | | SS+HKDF-256, ECDH- | | 906 | | | | SS+HKDF-512, ECDH- | | 907 | | | | ES+A128KW, ECDH- | | 908 | | | | ES+A192KW, ECDH- | | 909 | | | | ES+A256KW, ECDH- | | 910 | | | | SS+A128KW, ECDH- | | 911 | | | | SS+A192KW, ECDH-SS+A256KW | | 912 | PartyU | -22 | bstr | direct+HKDF-SHA-256, | Party U | 913 | nonce | | / | direct+HKDF-SHA-512, | provided | 914 | | | int | direct+HKDF-AES-128, | nonce | 915 | | | | direct+HKDF-AES-256, | | 916 | | | | ECDH-ES+HKDF-256, ECDH- | | 917 | | | | ES+HKDF-512, ECDH- | | 918 | | | | SS+HKDF-256, ECDH- | | 919 | | | | SS+HKDF-512, ECDH- | | 920 | | | | ES+A128KW, ECDH- | | 921 | | | | ES+A192KW, ECDH- | | 922 | | | | ES+A256KW, ECDH- | | 923 | | | | SS+A128KW, ECDH- | | 924 | | | | SS+A192KW, ECDH-SS+A256KW | | 925 | PartyU | -23 | bstr | direct+HKDF-SHA-256, | Party U | 926 | other | | | direct+HKDF-SHA-512, | other | 927 | | | | direct+HKDF-AES-128, | provided | 928 | | | | direct+HKDF-AES-256, | information | 929 | | | | ECDH-ES+HKDF-256, ECDH- | | 930 | | | | ES+HKDF-512, ECDH- | | 931 | | | | SS+HKDF-256, ECDH- | | 932 | | | | SS+HKDF-512, ECDH- | | 933 | | | | ES+A128KW, ECDH- | | 934 | | | | ES+A192KW, ECDH- | | 935 | | | | ES+A256KW, ECDH- | | 936 | | | | SS+A128KW, ECDH- | | 937 | | | | SS+A192KW, ECDH-SS+A256KW | | 938 | PartyV | -24 | bstr | direct+HKDF-SHA-256, | Party V | 939 | identity | | | direct+HKDF-SHA-512, | identity | 940 | | | | direct+HKDF-AES-128, | information | 941 | | | | direct+HKDF-AES-256, | | 942 | | | | ECDH-ES+HKDF-256, ECDH- | | 943 | | | | ES+HKDF-512, ECDH- | | 944 | | | | SS+HKDF-256, ECDH- | | 945 | | | | SS+HKDF-512, ECDH- | | 946 | | | | ES+A128KW, ECDH- | | 947 | | | | ES+A192KW, ECDH- | | 948 | | | | ES+A256KW, ECDH- | | 949 | | | | SS+A128KW, ECDH- | | 950 | | | | SS+A192KW, ECDH-SS+A256KW | | 951 | PartyV | -25 | bstr | direct+HKDF-SHA-256, | Party V | 952 | nonce | | / | direct+HKDF-SHA-512, | provided | 953 | | | int | direct+HKDF-AES-128, | nonce | 954 | | | | direct+HKDF-AES-256, | | 955 | | | | ECDH-ES+HKDF-256, ECDH- | | 956 | | | | ES+HKDF-512, ECDH- | | 957 | | | | SS+HKDF-256, ECDH- | | 958 | | | | SS+HKDF-512, ECDH- | | 959 | | | | ES+A128KW, ECDH- | | 960 | | | | ES+A192KW, ECDH- | | 961 | | | | ES+A256KW, ECDH- | | 962 | | | | SS+A128KW, ECDH- | | 963 | | | | SS+A192KW, ECDH-SS+A256KW | | 964 | PartyV | -26 | bstr | direct+HKDF-SHA-256, | Party V | 965 | other | | | direct+HKDF-SHA-512, | other | 966 | | | | direct+HKDF-AES-128, | provided | 967 | | | | direct+HKDF-AES-256, | information | 968 | | | | ECDH-ES+HKDF-256, ECDH- | | 969 | | | | ES+HKDF-512, ECDH- | | 970 | | | | SS+HKDF-256, ECDH- | | 971 | | | | SS+HKDF-512, ECDH- | | 972 | | | | ES+A128KW, ECDH- | | 973 | | | | ES+A192KW, ECDH- | | 974 | | | | ES+A256KW, ECDH- | | 975 | | | | SS+A128KW, ECDH- | | 976 | | | | SS+A192KW, ECDH-SS+A256KW | | 977 +----------+-------+------+---------------------------+-------------+ 979 Table 10: Context Algorithm Parameters 981 We define a CBOR object to hold the context information. This object 982 is referred to as COSE_KDF_Context. The object is based on a CBOR 983 array type. The fields in the array are: 985 AlgorithmID: This field indicates the algorithm for which the key 986 material will be used. This normally is either a key wrap 987 algorithm identifier or a content encryption algorithm identifier. 988 The values are from the "COSE Algorithms" registry. This field is 989 required to be present. The field exists in the context 990 information so that if the same environment is used for different 991 algorithms, then completely different keys will be generated for 992 each of those algorithms. This practice means if algorithm A is 993 broken and thus is easier to find, the key derived for algorithm B 994 will not be the same as the key derived for algorithm A. 996 PartyUInfo: This field holds information about party U. The 997 PartyUInfo is encoded as a CBOR array. The elements of PartyUInfo 998 are encoded in the order presented. The elements of the 999 PartyUInfo array are: 1001 identity: This contains the identity information for party U. 1002 The identities can be assigned in one of two manners. First, a 1003 protocol can assign identities based on roles. For example, 1004 the roles of "client" and "server" may be assigned to different 1005 entities in the protocol. Each entity would then use the 1006 correct label for the data they send or receive. The second 1007 way for a protocol to assign identities is to use a name based 1008 on a naming system (i.e., DNS, X.509 names). 1010 We define an algorithm parameter 'PartyU identity' that can be 1011 used to carry identity information in the message. However, 1012 identity information is often known as part of the protocol and 1013 can thus be inferred rather than made explicit. If identity 1014 information is carried in the message, applications SHOULD have 1015 a way of validating the supplied identity information. The 1016 identity information does not need to be specified and is set 1017 to nil in that case. 1019 nonce: This contains a nonce value. The nonce can either be 1020 implicit from the protocol or be carried as a value in the 1021 unprotected headers. 1023 We define an algorithm parameter 'PartyU nonce' that can be 1024 used to carry this value in the message; however, the nonce 1025 value could be determined by the application and the value 1026 determined from elsewhere. 1028 This option does not need to be specified and is set to nil in 1029 that case. 1031 other: This contains other information that is defined by the 1032 protocol. This option does not need to be specified and is set 1033 to nil in that case. 1035 PartyVInfo: This field holds information about party V. The content 1036 of the structure is the same as for the PartyUInfo but for party 1037 V. 1039 SuppPubInfo: This field contains public information that is mutually 1040 known to both parties. 1042 keyDataLength: This is set to the number of bits of the desired 1043 output value. This practice means if algorithm A can use two 1044 different key lengths, the key derived for longer key size will 1045 not contain the key for shorter key size as a prefix. 1047 protected: This field contains the protected parameter field. If 1048 there are no elements in the protected field, then use a zero- 1049 length bstr. 1051 other: This field is for free form data defined by the 1052 application. An example is that an application could define 1053 two different strings to be placed here to generate different 1054 keys for a data stream versus a control stream. This field is 1055 optional and will only be present if the application defines a 1056 structure for this information. Applications that define this 1057 SHOULD use CBOR to encode the data so that types and lengths 1058 are correctly included. 1060 SuppPrivInfo: This field contains private information that is 1061 mutually known private information. An example of this 1062 information would be a preexisting shared secret. (This could, 1063 for example, be used in combination with an ECDH key agreement to 1064 provide a secondary proof of identity.) The field is optional and 1065 will only be present if the application defines a structure for 1066 this information. Applications that define this SHOULD use CBOR 1067 to encode the data so that types and lengths are correctly 1068 included. 1070 The following CDDL fragment corresponds to the text above. 1072 PartyInfo = ( 1073 identity : bstr / nil, 1074 nonce : bstr / int / nil, 1075 other : bstr / nil 1076 ) 1078 COSE_KDF_Context = [ 1079 AlgorithmID : int / tstr, 1080 PartyUInfo : [ PartyInfo ], 1081 PartyVInfo : [ PartyInfo ], 1082 SuppPubInfo : [ 1083 keyDataLength : uint, 1084 protected : empty_or_serialized_map, 1085 ? other : bstr 1086 ], 1087 ? SuppPrivInfo : bstr 1088 ] 1090 6. Content Key Distribution Methods 1092 Section 13 of [I-D.ietf-cose-rfc8152bis-struct] 1093 [I-D.ietf-cose-rfc8152bis-struct] contains a generic description of 1094 content key distribution methods. This document defines the 1095 identifiers and usage for a number of content key distribution 1096 methods. 1098 6.1. Direct Encryption 1100 Direct encryption algorithm is defined in Section 13.1 of [I-D.ietf- 1101 cose-rfc8152bis-struct] [I-D.ietf-cose-rfc8152bis-struct]. 1102 Information about how to fill in the COSE_Recipient structure are 1103 detailed there. 1105 6.1.1. Direct Key 1107 This recipient algorithm is the simplest; the identified key is 1108 directly used as the key for the next layer down in the message. 1109 There are no algorithm parameters defined for this algorithm. The 1110 algorithm identifier value is assigned in Table 11. 1112 When this algorithm is used, the protected field MUST be zero length. 1113 The key type MUST be 'Symmetric'. 1115 +--------+-------+-------------------+ 1116 | Name | Value | Description | 1117 +--------+-------+-------------------+ 1118 | direct | -6 | Direct use of CEK | 1119 +--------+-------+-------------------+ 1121 Table 11: Direct Key 1123 6.1.1.1. Security Considerations 1125 This recipient algorithm has several potential problems that need to 1126 be considered: 1128 o These keys need to have some method to be regularly updated over 1129 time. All of the content encryption algorithms specified in this 1130 document have limits on how many times a key can be used without 1131 significant loss of security. 1133 o These keys need to be dedicated to a single algorithm. There have 1134 been a number of attacks developed over time when a single key is 1135 used for multiple different algorithms. One example of this is 1136 the use of a single key for both the CBC encryption mode and the 1137 CBC-MAC authentication mode. 1139 o Breaking one message means all messages are broken. If an 1140 adversary succeeds in determining the key for a single message, 1141 then the key for all messages is also determined. 1143 6.1.2. Direct Key with KDF 1145 These recipient algorithms take a common shared secret between the 1146 two parties and applies the HKDF function (Section 5.1), using the 1147 context structure defined in Section 5.2 to transform the shared 1148 secret into the CEK. The 'protected' field can be of non-zero 1149 length. Either the 'salt' parameter of HKDF or the 'PartyU nonce' 1150 parameter of the context structure MUST be present. The salt/nonce 1151 parameter can be generated either randomly or deterministically. The 1152 requirement is that it be a unique value for the shared secret in 1153 question. 1155 If the salt/nonce value is generated randomly, then it is suggested 1156 that the length of the random value be the same length as the hash 1157 function underlying HKDF. While there is no way to guarantee that it 1158 will be unique, there is a high probability that it will be unique. 1160 If the salt/nonce value is generated deterministically, it can be 1161 guaranteed to be unique, and thus there is no length requirement. 1163 A new IV must be used for each message if the same key is used. The 1164 IV can be modified in a predictable manner, a random manner, or an 1165 unpredictable manner (i.e., encrypting a counter). 1167 The IV used for a key can also be generated from the same HKDF 1168 functionality as the key is generated. If HKDF is used for 1169 generating the IV, the algorithm identifier is set to "IV- 1170 GENERATION". 1172 When these algorithms are used, the key type MUST be 'symmetric'. 1174 The set of algorithms defined in this document can be found in 1175 Table 12. 1177 +---------------------+-------+-------------+-----------------------+ 1178 | Name | Value | KDF | Description | 1179 +---------------------+-------+-------------+-----------------------+ 1180 | direct+HKDF-SHA-256 | -10 | HKDF | Shared secret w/ HKDF | 1181 | | | SHA-256 | and SHA-256 | 1182 | direct+HKDF-SHA-512 | -11 | HKDF | Shared secret w/ HKDF | 1183 | | | SHA-512 | and SHA-512 | 1184 | direct+HKDF-AES-128 | -12 | HKDF AES- | Shared secret w/ AES- | 1185 | | | MAC-128 | MAC 128-bit key | 1186 | direct+HKDF-AES-256 | -13 | HKDF AES- | Shared secret w/ AES- | 1187 | | | MAC-256 | MAC 256-bit key | 1188 +---------------------+-------+-------------+-----------------------+ 1190 Table 12: Direct Key with KDF 1192 When using a COSE key for this algorithm, the following checks are 1193 made: 1195 o The 'kty' field MUST be present, and it MUST be 'Symmetric'. 1197 o If the 'alg' field is present, it MUST match the algorithm being 1198 used. 1200 o If the 'key_ops' field is present, it MUST include 'deriveKey' or 1201 'deriveBits'. 1203 6.1.2.1. Security Considerations 1205 The shared secret needs to have some method to be regularly updated 1206 over time. The shared secret forms the basis of trust. Although not 1207 used directly, it should still be subject to scheduled rotation. 1209 While these methods do not provide for perfect forward secrecy, as 1210 the same shared secret is used for all of the keys generated, if the 1211 key for any single message is discovered, only the message (or series 1212 of messages) using that derived key are compromised. A new key 1213 derivation step will generate a new key that requires the same amount 1214 of work to get the key. 1216 6.2. AES Key Wrap 1218 The AES Key Wrap algorithm is defined in [RFC3394]. This algorithm 1219 uses an AES key to wrap a value that is a multiple of 64 bits. As 1220 such, it can be used to wrap a key for any of the content encryption 1221 algorithms defined in this document. The algorithm requires a single 1222 fixed parameter, the initial value. This is fixed to the value 1223 specified in Section 2.2.3.1 of [RFC3394]. There are no public 1224 parameters that vary on a per-invocation basis. The protected header 1225 field MUST be empty. 1227 Keys may be obtained either from a key structure or from a recipient 1228 structure. Implementations encrypting and decrypting MUST validate 1229 that the key type, key length, and algorithm are correct and 1230 appropriate for the entities involved. 1232 When using a COSE key for this algorithm, the following checks are 1233 made: 1235 o The 'kty' field MUST be present, and it MUST be 'Symmetric'. 1237 o If the 'alg' field is present, it MUST match the AES Key Wrap 1238 algorithm being used. 1240 o If the 'key_ops' field is present, it MUST include 'encrypt' or 1241 'wrap key' when encrypting. 1243 o If the 'key_ops' field is present, it MUST include 'decrypt' or 1244 'unwrap key' when decrypting. 1246 +--------+-------+----------+-----------------------------+ 1247 | Name | Value | Key Size | Description | 1248 +--------+-------+----------+-----------------------------+ 1249 | A128KW | -3 | 128 | AES Key Wrap w/ 128-bit key | 1250 | A192KW | -4 | 192 | AES Key Wrap w/ 192-bit key | 1251 | A256KW | -5 | 256 | AES Key Wrap w/ 256-bit key | 1252 +--------+-------+----------+-----------------------------+ 1254 Table 13: AES Key Wrap Algorithm Values 1256 6.2.1. Security Considerations for AES-KW 1258 The shared secret needs to have some method to be regularly updated 1259 over time. The shared secret is the basis of trust. 1261 6.3. Direct ECDH 1263 The mathematics for ECDH can be found in [RFC6090]. In this 1264 document, the algorithm is extended to be used with the two curves 1265 defined in [RFC7748]. 1267 ECDH is parameterized by the following: 1269 o Curve Type/Curve: The curve selected controls not only the size of 1270 the shared secret, but the mathematics for computing the shared 1271 secret. The curve selected also controls how a point in the curve 1272 is represented and what happens for the identity points on the 1273 curve. In this specification, we allow for a number of different 1274 curves to be used. A set of curves are defined in Table 18. 1275 The math used to obtain the computed secret is based on the curve 1276 selected and not on the ECDH algorithm. For this reason, a new 1277 algorithm does not need to be defined for each of the curves. 1279 o Computed Secret to Shared Secret: Once the computed secret is 1280 known, the resulting value needs to be converted to a byte string 1281 to run the KDF. The x-coordinate is used for all of the curves 1282 defined in this document. For curves X25519 and X448, the 1283 resulting value is used directly as it is a byte string of a known 1284 length. For the P-256, P-384, and P-521 curves, the x-coordinate 1285 is run through the I2OSP function defined in [RFC8017], using the 1286 same computation for n as is defined in Section 2.1. 1288 o Ephemeral-Static or Static-Static: The key agreement process may 1289 be done using either a static or an ephemeral key for the sender's 1290 side. When using ephemeral keys, the sender MUST generate a new 1291 ephemeral key for every key agreement operation. The ephemeral 1292 key is placed in the 'ephemeral key' parameter and MUST be present 1293 for all algorithm identifiers that use ephemeral keys. When using 1294 static keys, the sender MUST either generate a new random value or 1295 create a unique value. For the KDFs used, this means either the 1296 'salt' parameter for HKDF (Table 9) or the 'PartyU nonce' 1297 parameter for the context structure (Table 10) MUST be present 1298 (both can be present if desired). The value in the parameter MUST 1299 be unique for the pair of keys being used. It is acceptable to 1300 use a global counter that is incremented for every static-static 1301 operation and use the resulting value. When using static keys, 1302 the static key should be identified to the recipient. The static 1303 key can be identified either by providing the key ('static key') 1304 or by providing a key identifier for the static key ('static key 1305 id'). Both of these parameters are defined in Table 15. 1307 o Key Derivation Algorithm: The result of an ECDH key agreement 1308 process does not provide a uniformly random secret. As such, it 1309 needs to be run through a KDF in order to produce a usable key. 1310 Processing the secret through a KDF also allows for the 1311 introduction of context material: how the key is going to be used 1312 and one-time material for static-static key agreement. All of the 1313 algorithms defined in this document use one of the HKDF algorithms 1314 defined in Section 5.1 with the context structure defined in 1315 Section 5.2. 1317 o Key Wrap Algorithm: No key wrap algorithm is used. This is 1318 represented in Table 14 as 'none'. The key size for the context 1319 structure is the content layer encryption algorithm size. 1321 COSE does not have an Ephemeral-Ephemeral version defined. The 1322 reason for this is that COSE is not an an online protocol by itself 1323 and thus does not have a method to establish ephemeral secrets on 1324 both sides. The expectation is that a protocol would establish the 1325 secrets for both sides, and then they would be used as static-static 1326 for the purposes of COSE, or that the protocol would generate a 1327 shared secret and a direct encryption would be used. 1329 The set of direct ECDH algorithms defined in this document are found 1330 in Table 14. 1332 +-----------+-------+---------+------------+--------+---------------+ 1333 | Name | Value | KDF | Ephemeral- | Key | Description | 1334 | | | | Static | Wrap | | 1335 +-----------+-------+---------+------------+--------+---------------+ 1336 | ECDH-ES + | -25 | HKDF - | yes | none | ECDH ES w/ | 1337 | HKDF-256 | | SHA-256 | | | HKDF - | 1338 | | | | | | generate key | 1339 | | | | | | directly | 1340 | ECDH-ES + | -26 | HKDF - | yes | none | ECDH ES w/ | 1341 | HKDF-512 | | SHA-512 | | | HKDF - | 1342 | | | | | | generate key | 1343 | | | | | | directly | 1344 | ECDH-SS + | -27 | HKDF - | no | none | ECDH SS w/ | 1345 | HKDF-256 | | SHA-256 | | | HKDF - | 1346 | | | | | | generate key | 1347 | | | | | | directly | 1348 | ECDH-SS + | -28 | HKDF - | no | none | ECDH SS w/ | 1349 | HKDF-512 | | SHA-512 | | | HKDF - | 1350 | | | | | | generate key | 1351 | | | | | | directly | 1352 +-----------+-------+---------+------------+--------+---------------+ 1354 Table 14: ECDH Algorithm Values 1356 +-----------+-------+----------+---------------------+--------------+ 1357 | Name | Label | Type | Algorithm | Description | 1358 +-----------+-------+----------+---------------------+--------------+ 1359 | ephemeral | -1 | COSE_Key | ECDH-ES+HKDF-256, | Ephemeral | 1360 | key | | | ECDH-ES+HKDF-512, | public key | 1361 | | | | ECDH-ES+A128KW, | for the | 1362 | | | | ECDH-ES+A192KW, | sender | 1363 | | | | ECDH-ES+A256KW | | 1364 | static | -2 | COSE_Key | ECDH-SS+HKDF-256, | Static | 1365 | key | | | ECDH-SS+HKDF-512, | public key | 1366 | | | | ECDH-SS+A128KW, | for the | 1367 | | | | ECDH-SS+A192KW, | sender | 1368 | | | | ECDH-SS+A256KW | | 1369 | static | -3 | bstr | ECDH-SS+HKDF-256, | Static | 1370 | key id | | | ECDH-SS+HKDF-512, | public key | 1371 | | | | ECDH-SS+A128KW, | identifier | 1372 | | | | ECDH-SS+A192KW, | for the | 1373 | | | | ECDH-SS+A256KW | sender | 1374 +-----------+-------+----------+---------------------+--------------+ 1376 Table 15: ECDH Algorithm Parameters 1378 This document defines these algorithms to be used with the curves 1379 P-256, P-384, P-521, X25519, and X448. Implementations MUST verify 1380 that the key type and curve are correct. Different curves are 1381 restricted to different key types. Implementations MUST verify that 1382 the curve and algorithm are appropriate for the entities involved. 1384 When using a COSE key for this algorithm, the following checks are 1385 made: 1387 o The 'kty' field MUST be present, and it MUST be 'EC2' or 'OKP'. 1389 o If the 'alg' field is present, it MUST match the key agreement 1390 algorithm being used. 1392 o If the 'key_ops' field is present, it MUST include 'derive key' or 1393 'derive bits' for the private key. 1395 o If the 'key_ops' field is present, it MUST be empty for the public 1396 key. 1398 6.3.1. Security Considerations 1400 There is a method of checking that points provided from external 1401 entities are valid. For the 'EC2' key format, this can be done by 1402 checking that the x and y values form a point on the curve. For the 1403 'OKP' format, there is no simple way to do point validation. 1405 Consideration was given to requiring that the public keys of both 1406 entities be provided as part of the key derivation process (as 1407 recommended in Section 6.1 of [RFC7748]). This was not done as COSE 1408 is used in a store and forward format rather than in online key 1409 exchange. In order for this to be a problem, either the receiver 1410 public key has to be chosen maliciously or the sender has to be 1411 malicious. In either case, all security evaporates anyway. 1413 A proof of possession of the private key associated with the public 1414 key is recommended when a key is moved from untrusted to trusted 1415 (either by the end user or by the entity that is responsible for 1416 making trust statements on keys). 1418 6.4. ECDH with Key Wrap 1420 These algorithms are defined in Table 16. 1422 ECDH with Key Agreement is parameterized by the same parameters as 1423 for ECDH; see Section 6.3, with the following modifications: 1425 o Key Wrap Algorithm: Any of the key wrap algorithms defined in 1426 Section 6.2 are supported. The size of the key used for the key 1427 wrap algorithm is fed into the KDF. The set of identifiers are 1428 found in Table 16. 1430 +-----------+-------+---------+------------+--------+---------------+ 1431 | Name | Value | KDF | Ephemeral- | Key | Description | 1432 | | | | Static | Wrap | | 1433 +-----------+-------+---------+------------+--------+---------------+ 1434 | ECDH-ES + | -29 | HKDF - | yes | A128KW | ECDH ES w/ | 1435 | A128KW | | SHA-256 | | | Concat KDF | 1436 | | | | | | and AES Key | 1437 | | | | | | Wrap w/ | 1438 | | | | | | 128-bit key | 1439 | | | | | | | 1440 | ECDH-ES + | -30 | HKDF - | yes | A192KW | ECDH ES w/ | 1441 | A192KW | | SHA-256 | | | Concat KDF | 1442 | | | | | | and AES Key | 1443 | | | | | | Wrap w/ | 1444 | | | | | | 192-bit key | 1445 | | | | | | | 1446 | ECDH-ES + | -31 | HKDF - | yes | A256KW | ECDH ES w/ | 1447 | A256KW | | SHA-256 | | | Concat KDF | 1448 | | | | | | and AES Key | 1449 | | | | | | Wrap w/ | 1450 | | | | | | 256-bit key | 1451 | | | | | | | 1452 | ECDH-SS + | -32 | HKDF - | no | A128KW | ECDH SS w/ | 1453 | A128KW | | SHA-256 | | | Concat KDF | 1454 | | | | | | and AES Key | 1455 | | | | | | Wrap w/ | 1456 | | | | | | 128-bit key | 1457 | | | | | | | 1458 | ECDH-SS + | -33 | HKDF - | no | A192KW | ECDH SS w/ | 1459 | A192KW | | SHA-256 | | | Concat KDF | 1460 | | | | | | and AES Key | 1461 | | | | | | Wrap w/ | 1462 | | | | | | 192-bit key | 1463 | | | | | | | 1464 | ECDH-SS + | -34 | HKDF - | no | A256KW | ECDH SS w/ | 1465 | A256KW | | SHA-256 | | | Concat KDF | 1466 | | | | | | and AES Key | 1467 | | | | | | Wrap w/ | 1468 | | | | | | 256-bit key | 1469 +-----------+-------+---------+------------+--------+---------------+ 1471 Table 16: ECDH Algorithm Values with Key Wrap 1473 When using a COSE key for this algorithm, the following checks are 1474 made: 1476 o The 'kty' field MUST be present, and it MUST be 'EC2' or 'OKP'. 1478 o If the 'alg' field is present, it MUST match the key agreement 1479 algorithm being used. 1481 o If the 'key_ops' field is present, it MUST include 'derive key' or 1482 'derive bits' for the private key. 1484 o If the 'key_ops' field is present, it MUST be empty for the public 1485 key. 1487 7. Key Object Parameters 1489 The COSE_Key object defines a way to hold a single key object. It is 1490 still required that the members of individual key types be defined. 1491 This section of the document is where we define an initial set of 1492 members for specific key types. 1494 For each of the key types, we define both public and private members. 1495 The public members are what is transmitted to others for their usage. 1496 Private members allow for the archival of keys by individuals. 1497 However, there are some circumstances in which private keys may be 1498 distributed to entities in a protocol. Examples include: entities 1499 that have poor random number generation, centralized key creation for 1500 multi-cast type operations, and protocols in which a shared secret is 1501 used as a bearer token for authorization purposes. 1503 Key types are identified by the 'kty' member of the COSE_Key object. 1504 In this document, we define four values for the member: 1506 +-----------+-------+-----------------------------------------------+ 1507 | Name | Value | Description | 1508 +-----------+-------+-----------------------------------------------+ 1509 | OKP | 1 | Octet Key Pair | 1510 | EC2 | 2 | Elliptic Curve Keys w/ x- and y-coordinate | 1511 | | | pair | 1512 | Symmetric | 4 | Symmetric Keys | 1513 | Reserved | 0 | This value is reserved | 1514 +-----------+-------+-----------------------------------------------+ 1516 Table 17: Key Type Values 1518 7.1. Elliptic Curve Keys 1520 Two different key structures are defined for elliptic curve keys. 1521 One version uses both an x-coordinate and a y-coordinate, potentially 1522 with point compression ('EC2'). This is the traditional EC point 1523 representation that is used in [RFC5480]. The other version uses 1524 only the x-coordinate as the y-coordinate is either to be recomputed 1525 or not needed for the key agreement operation ('OKP'). 1527 Applications MUST check that the curve and the key type are 1528 consistent and reject a key if they are not. 1530 +---------+-------+----------+------------------------------------+ 1531 | Name | Value | Key Type | Description | 1532 +---------+-------+----------+------------------------------------+ 1533 | P-256 | 1 | EC2 | NIST P-256 also known as secp256r1 | 1534 | P-384 | 2 | EC2 | NIST P-384 also known as secp384r1 | 1535 | P-521 | 3 | EC2 | NIST P-521 also known as secp521r1 | 1536 | X25519 | 4 | OKP | X25519 for use w/ ECDH only | 1537 | X448 | 5 | OKP | X448 for use w/ ECDH only | 1538 | Ed25519 | 6 | OKP | Ed25519 for use w/ EdDSA only | 1539 | Ed448 | 7 | OKP | Ed448 for use w/ EdDSA only | 1540 +---------+-------+----------+------------------------------------+ 1542 Table 18: Elliptic Curves 1544 7.1.1. Double Coordinate Curves 1546 The traditional way of sending ECs has been to send either both the 1547 x-coordinate and y-coordinate or the x-coordinate and a sign bit for 1548 the y-coordinate. The latter encoding has not been recommended in 1549 the IETF due to potential IPR issues. However, for operations in 1550 constrained environments, the ability to shrink a message by not 1551 sending the y-coordinate is potentially useful. 1553 For EC keys with both coordinates, the 'kty' member is set to 2 1554 (EC2). The key parameters defined in this section are summarized in 1555 Table 19. The members that are defined for this key type are: 1557 crv: This contains an identifier of the curve to be used with the 1558 key. The curves defined in this document for this key type can 1559 be found in Table 18. Other curves may be registered in the 1560 future, and private curves can be used as well. 1562 x: This contains the x-coordinate for the EC point. The integer is 1563 converted to an octet string as defined in [SEC1]. Leading zero 1564 octets MUST be preserved. 1566 y: This contains either the sign bit or the value of the 1567 y-coordinate for the EC point. When encoding the value y, the 1568 integer is converted to an octet string (as defined in [SEC1]) 1569 and encoded as a CBOR bstr. Leading zero octets MUST be 1570 preserved. The compressed point encoding is also supported. 1571 Compute the sign bit as laid out in the Elliptic-Curve-Point-to- 1572 Octet-String Conversion function of [SEC1]. If the sign bit is 1573 zero, then encode y as a CBOR false value; otherwise, encode y 1574 as a CBOR true value. The encoding of the infinity point is not 1575 supported. 1577 d: This contains the private key. 1579 For public keys, it is REQUIRED that 'crv', 'x', and 'y' be present 1580 in the structure. For private keys, it is REQUIRED that 'crv' and 1581 'd' be present in the structure. For private keys, it is RECOMMENDED 1582 that 'x' and 'y' also be present, but they can be recomputed from the 1583 required elements and omitting them saves on space. 1585 +-------+------+-------+--------+-----------------------------------+ 1586 | Key | Name | Label | CBOR | Description | 1587 | Type | | | Type | | 1588 +-------+------+-------+--------+-----------------------------------+ 1589 | 2 | crv | -1 | int / | EC identifier - Taken from the | 1590 | | | | tstr | "COSE Elliptic Curves" registry | 1591 | 2 | x | -2 | bstr | x-coordinate | 1592 | 2 | y | -3 | bstr / | y-coordinate | 1593 | | | | bool | | 1594 | 2 | d | -4 | bstr | Private key | 1595 +-------+------+-------+--------+-----------------------------------+ 1597 Table 19: EC Key Parameters 1599 7.2. Octet Key Pair 1601 A new key type is defined for Octet Key Pairs (OKP). Do not assume 1602 that keys using this type are elliptic curves. This key type could 1603 be used for other curve types (for example, mathematics based on 1604 hyper-elliptic surfaces). 1606 The key parameters defined in this section are summarized in 1607 Table 20. The members that are defined for this key type are: 1609 crv: This contains an identifier of the curve to be used with the 1610 key. The curves defined in this document for this key type can 1611 be found in Table 18. Other curves may be registered in the 1612 future and private curves can be used as well. 1614 x: This contains the x-coordinate for the EC point. The octet 1615 string represents a little-endian encoding of x. 1617 d: This contains the private key. 1619 For public keys, it is REQUIRED that 'crv' and 'x' be present in the 1620 structure. For private keys, it is REQUIRED that 'crv' and 'd' be 1621 present in the structure. For private keys, it is RECOMMENDED that 1622 'x' also be present, but it can be recomputed from the required 1623 elements and omitting it saves on space. 1625 +------+-------+-------+--------+-----------------------------------+ 1626 | Name | Key | Label | Type | Description | 1627 | | Type | | | | 1628 +------+-------+-------+--------+-----------------------------------+ 1629 | crv | 1 | -1 | int / | EC identifier - Taken from the | 1630 | | | | tstr | "COSE Elliptic Curves" registry | 1631 | x | 1 | -2 | bstr | x-coordinate | 1632 | d | 1 | -4 | bstr | Private key | 1633 +------+-------+-------+--------+-----------------------------------+ 1635 Table 20: Octet Key Pair Parameters 1637 7.3. Symmetric Keys 1639 Occasionally it is required that a symmetric key be transported 1640 between entities. This key structure allows for that to happen. 1642 For symmetric keys, the 'kty' member is set to 4 ('Symmetric'). The 1643 member that is defined for this key type is: 1645 k: This contains the value of the key. 1647 This key structure does not have a form that contains only public 1648 members. As it is expected that this key structure is going to be 1649 transmitted, care must be taken that it is never transmitted 1650 accidentally or insecurely. For symmetric keys, it is REQUIRED that 1651 'k' be present in the structure. 1653 +------+----------+-------+------+-------------+ 1654 | Name | Key Type | Label | Type | Description | 1655 +------+----------+-------+------+-------------+ 1656 | k | 4 | -1 | bstr | Key Value | 1657 +------+----------+-------+------+-------------+ 1659 Table 21: Symmetric Key Parameters 1661 8. CBOR Encoding Restrictions 1663 There has been an attempt to limit the number of places where the 1664 document needs to impose restrictions on how the CBOR Encoder needs 1665 to work. We have managed to narrow it down to the following 1666 restrictions: 1668 o The restriction applies to the encoding of the COSE_KDF_Context. 1670 o Encoding MUST be done using definite lengths and the length of the 1671 MUST be the minimum possible length. This means that the integer 1672 1 is encoded as "0x01" and not "0x1801". 1674 o Applications MUST NOT generate messages with the same label used 1675 twice as a key in a single map. Applications MUST NOT parse and 1676 process messages with the same label used twice as a key in a 1677 single map. Applications can enforce the parse and process 1678 requirement by using parsers that will fail the parse step or by 1679 using parsers that will pass all keys to the application, and the 1680 application can perform the check for duplicate keys. 1682 9. IANA Considerations 1684 There are no IANA actions. The required actions are in 1685 [I-D.ietf-cose-rfc8152bis-struct]. 1687 10. Security Considerations 1689 There are a number of security considerations that need to be taken 1690 into account by implementers of this specification. The security 1691 considerations that are specific to an individual algorithm are 1692 placed next to the description of the algorithm. While some 1693 considerations have been highlighted here, additional considerations 1694 may be found in the documents listed in the references. 1696 Implementations need to protect the private key material for any 1697 individuals. There are some cases in this document that need to be 1698 highlighted on this issue. 1700 o Using the same key for two different algorithms can leak 1701 information about the key. It is therefore recommended that keys 1702 be restricted to a single algorithm. 1704 o Use of 'direct' as a recipient algorithm combined with a second 1705 recipient algorithm exposes the direct key to the second 1706 recipient. 1708 o Several of the algorithms in this document have limits on the 1709 number of times that a key can be used without leaking information 1710 about the key. 1712 The use of ECDH and direct plus KDF (with no key wrap) will not 1713 directly lead to the private key being leaked; the one way function 1714 of the KDF will prevent that. There is, however, a different issue 1715 that needs to be addressed. Having two recipients requires that the 1716 CEK be shared between two recipients. The second recipient therefore 1717 has a CEK that was derived from material that can be used for the 1718 weak proof of origin. The second recipient could create a message 1719 using the same CEK and send it to the first recipient; the first 1720 recipient would, for either static-static ECDH or direct plus KDF, 1721 make an assumption that the CEK could be used for proof of origin 1722 even though it is from the wrong entity. If the key wrap step is 1723 added, then no proof of origin is implied and this is not an issue. 1725 Although it has been mentioned before, the use of a single key for 1726 multiple algorithms has been demonstrated in some cases to leak 1727 information about a key, provide the opportunity for attackers to 1728 forge integrity tags, or gain information about encrypted content. 1729 Binding a key to a single algorithm prevents these problems. Key 1730 creators and key consumers are strongly encouraged not only to create 1731 new keys for each different algorithm, but to include that selection 1732 of algorithm in any distribution of key material and strictly enforce 1733 the matching of algorithms in the key structure to algorithms in the 1734 message structure. In addition to checking that algorithms are 1735 correct, the key form needs to be checked as well. Do not use an 1736 'EC2' key where an 'OKP' key is expected. 1738 Before using a key for transmission, or before acting on information 1739 received, a trust decision on a key needs to be made. Is the data or 1740 action something that the entity associated with the key has a right 1741 to see or a right to request? A number of factors are associated 1742 with this trust decision. Some of the ones that are highlighted here 1743 are: 1745 o What are the permissions associated with the key owner? 1747 o Is the cryptographic algorithm acceptable in the current context? 1749 o Have the restrictions associated with the key, such as algorithm 1750 or freshness, been checked and are they correct? 1752 o Is the request something that is reasonable, given the current 1753 state of the application? 1755 o Have any security considerations that are part of the message been 1756 enforced (as specified by the application or 'crit' parameter)? 1758 There are a large number of algorithms presented in this document 1759 that use nonce values. For all of the nonces defined in this 1760 document, there is some type of restriction on the nonce being a 1761 unique value either for a key or for some other conditions. In all 1762 of these cases, there is no known requirement on the nonce being both 1763 unique and unpredictable; under these circumstances, it's reasonable 1764 to use a counter for creation of the nonce. In cases where one wants 1765 the pattern of the nonce to be unpredictable as well as unique, one 1766 can use a key created for that purpose and encrypt the counter to 1767 produce the nonce value. 1769 One area that has been starting to get exposure is doing traffic 1770 analysis of encrypted messages based on the length of the message. 1771 This specification does not provide for a uniform method of providing 1772 padding as part of the message structure. An observer can 1773 distinguish between two different strings (for example, 'YES' and 1774 'NO') based on the length for all of the content encryption 1775 algorithms that are defined in this document. This means that it is 1776 up to the applications to document how content padding is to be done 1777 in order to prevent or discourage such analysis. (For example, the 1778 strings could be defined as 'YES' and 'NO '.) 1780 11. References 1782 11.1. Normative References 1784 [AES-GCM] National Institute of Standards and Technology, 1785 "Recommendation for Block Cipher Modes of Operation: 1786 Galois/Counter Mode (GCM) and GMAC", NIST Special 1787 Publication 800-38D, DOI 10.6028/NIST.SP.800-38D, November 1788 2007, . 1791 [DSS] National Institute of Standards and Technology, "Digital 1792 Signature Standard (DSS)", FIPS PUB 186-4, 1793 DOI 10.6028/NIST.FIPS.186-4, July 2013, 1794 . 1797 [I-D.ietf-cose-rfc8152bis-struct] 1798 Schaad, J., "CBOR CBOR Object Signing and Encryption 1799 (COSE): Structures and Process", draft-ietf-cose- 1800 rfc8152bis-struct-02 (work in progress), March 2019. 1802 [MAC] National Institute of Standards and Technology, "Computer 1803 Data Authentication", FIPS PUB 113, May 1985, 1804 . 1807 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1808 Hashing for Message Authentication", RFC 2104, 1809 DOI 10.17487/RFC2104, February 1997, 1810 . 1812 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1813 Requirement Levels", BCP 14, RFC 2119, 1814 DOI 10.17487/RFC2119, March 1997, 1815 . 1817 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 1818 (AES) Key Wrap Algorithm", RFC 3394, DOI 10.17487/RFC3394, 1819 September 2002, . 1821 [RFC3610] Whiting, D., Housley, R., and N. Ferguson, "Counter with 1822 CBC-MAC (CCM)", RFC 3610, DOI 10.17487/RFC3610, September 1823 2003, . 1825 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 1826 Key Derivation Function (HKDF)", RFC 5869, 1827 DOI 10.17487/RFC5869, May 2010, 1828 . 1830 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 1831 Curve Cryptography Algorithms", RFC 6090, 1832 DOI 10.17487/RFC6090, February 2011, 1833 . 1835 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 1836 Algorithm (DSA) and Elliptic Curve Digital Signature 1837 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 1838 2013, . 1840 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1841 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1842 October 2013, . 1844 [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 1845 for Security", RFC 7748, DOI 10.17487/RFC7748, January 1846 2016, . 1848 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital 1849 Signature Algorithm (EdDSA)", RFC 8032, 1850 DOI 10.17487/RFC8032, January 2017, 1851 . 1853 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1854 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1855 May 2017, . 1857 [RFC8439] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF 1858 Protocols", RFC 8439, DOI 10.17487/RFC8439, June 2018, 1859 . 1861 [SEC1] Certicom Research, "SEC 1: Elliptic Curve Cryptography", 1862 Standards for Efficient Cryptography, Version 2.0, May 1863 2009, . 1865 11.2. Informative References 1867 [I-D.ietf-cbor-cddl] 1868 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 1869 definition language (CDDL): a notational convention to 1870 express CBOR and JSON data structures", draft-ietf-cbor- 1871 cddl-08 (work in progress), March 2019. 1873 [RFC4231] Nystrom, M., "Identifiers and Test Vectors for HMAC-SHA- 1874 224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512", 1875 RFC 4231, DOI 10.17487/RFC4231, December 2005, 1876 . 1878 [RFC4493] Song, JH., Poovendran, R., Lee, J., and T. Iwata, "The 1879 AES-CMAC Algorithm", RFC 4493, DOI 10.17487/RFC4493, June 1880 2006, . 1882 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 1883 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 1884 . 1886 [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, 1887 "Elliptic Curve Cryptography Subject Public Key 1888 Information", RFC 5480, DOI 10.17487/RFC5480, March 2009, 1889 . 1891 [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations 1892 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 1893 RFC 6151, DOI 10.17487/RFC6151, March 2011, 1894 . 1896 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1897 Application Protocol (CoAP)", RFC 7252, 1898 DOI 10.17487/RFC7252, June 2014, 1899 . 1901 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 1902 DOI 10.17487/RFC7518, May 2015, 1903 . 1905 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, 1906 "PKCS #1: RSA Cryptography Specifications Version 2.2", 1907 RFC 8017, DOI 10.17487/RFC8017, November 2016, 1908 . 1910 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 1911 RFC 8152, DOI 10.17487/RFC8152, July 2017, 1912 . 1914 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1915 Interchange Format", STD 90, RFC 8259, 1916 DOI 10.17487/RFC8259, December 2017, 1917 . 1919 [SP800-56A] 1920 Barker, E., Chen, L., Roginsky, A., and M. Smid, 1921 "Recommendation for Pair-Wise Key Establishment Schemes 1922 Using Discrete Logarithm Cryptography", NIST Special 1923 Publication 800-56A, Revision 2, 1924 DOI 10.6028/NIST.SP.800-56Ar2, May 2013, 1925 . 1928 Acknowledgments 1930 This document is a product of the COSE working group of the IETF. 1932 The following individuals are to blame for getting me started on this 1933 project in the first place: Richard Barnes, Matt Miller, and Martin 1934 Thomson. 1936 The initial version of the specification was based to some degree on 1937 the outputs of the JOSE and S/MIME working groups. 1939 The following individuals provided input into the final form of the 1940 document: Carsten Bormann, John Bradley, Brain Campbell, Michael B. 1941 Jones, Ilari Liusvaara, Francesca Palombini, Ludwig Seitz, and Goran 1942 Selander. 1944 Author's Address 1946 Jim Schaad 1947 August Cellars 1949 Email: ietf@augustcellars.com