idnits 2.17.1 draft-ietf-cose-msg-24.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 756 has weird spacing: '...otected as de...' == Line 758 has weird spacing: '...otected as de...' == Line 760 has weird spacing: '...payload conta...' == Line 776 has weird spacing: '...natures is an...' == Line 791 has weird spacing: '...otected as de...' == (28 more instances...) -- The document date (November 22, 2016) is 2706 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' ** Downref: Normative reference to an Informational draft: draft-irtf-cfrg-eddsa (ref. 'I-D.irtf-cfrg-eddsa') -- 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) ** Obsolete normative reference: RFC 7539 (Obsoleted by RFC 8439) ** Downref: Normative reference to an Informational RFC: RFC 7748 -- Possible downref: Non-RFC (?) normative reference: ref. 'SEC1' == Outdated reference: A later version (-11) exists of draft-greevenbosch-appsawg-cbor-cddl-09 -- Obsolete informational reference (is this intentional?): RFC 2633 (Obsoleted by RFC 3851) -- Obsolete informational reference (is this intentional?): RFC 5751 (Obsoleted by RFC 8551) -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) Summary: 10 errors (**), 0 flaws (~~), 8 warnings (==), 8 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 Intended status: Standards Track November 22, 2016 5 Expires: May 26, 2017 7 CBOR Object Signing and Encryption (COSE) 8 draft-ietf-cose-msg-24 10 Abstract 12 Concise Binary Object Representation (CBOR) is data format designed 13 for small code size and small message size. There is a need for the 14 ability to have basic security services defined for this data format. 15 This document defines the CBOR Object Signing and Encryption (COSE) 16 specification. This specification describes how to create and 17 process signature, message authentication codes and encryption using 18 CBOR for serialization. This specification additionally specifies 19 how to represent cryptographic keys using CBOR. 21 Contributing to this document 23 The source for this draft is being maintained in GitHub. Suggested 24 changes should be submitted as pull requests at . Instructions are on that page as well. 26 Editorial changes can be managed in GitHub, but any substantial 27 issues need to be discussed on the COSE mailing list. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on May 26, 2017. 46 Copyright Notice 48 Copyright (c) 2016 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 64 1.1. Design changes from JOSE . . . . . . . . . . . . . . . . 5 65 1.2. Requirements Terminology . . . . . . . . . . . . . . . . 6 66 1.3. CBOR Grammar . . . . . . . . . . . . . . . . . . . . . . 6 67 1.4. CBOR Related Terminology . . . . . . . . . . . . . . . . 7 68 1.5. Document Terminology . . . . . . . . . . . . . . . . . . 8 69 2. Basic COSE Structure . . . . . . . . . . . . . . . . . . . . 8 70 3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 10 71 3.1. Common COSE Headers Parameters . . . . . . . . . . . . . 12 72 4. Signing Objects . . . . . . . . . . . . . . . . . . . . . . . 16 73 4.1. Signing with One or More Signers . . . . . . . . . . . . 16 74 4.2. Signing with One Signer . . . . . . . . . . . . . . . . . 18 75 4.3. Externally Supplied Data . . . . . . . . . . . . . . . . 19 76 4.4. Signing and Verification Process . . . . . . . . . . . . 20 77 4.5. Computing Counter Signatures . . . . . . . . . . . . . . 22 78 5. Encryption Objects . . . . . . . . . . . . . . . . . . . . . 22 79 5.1. Enveloped COSE Structure . . . . . . . . . . . . . . . . 22 80 5.1.1. Content Key Distribution Methods . . . . . . . . . . 24 81 5.2. Single Recipient Encrypted . . . . . . . . . . . . . . . 25 82 5.3. How to encrypt and decrypt for AEAD Algorithms . . . . . 25 83 5.4. How to encrypt and decrypt for AE Algorithms . . . . . . 28 84 6. MAC Objects . . . . . . . . . . . . . . . . . . . . . . . . . 29 85 6.1. MACed Message with Recipients . . . . . . . . . . . . . . 30 86 6.2. MACed Messages with Implicit Key . . . . . . . . . . . . 31 87 6.3. How to compute and verify a MAC . . . . . . . . . . . . . 31 88 7. Key Objects . . . . . . . . . . . . . . . . . . . . . . . . . 33 89 7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 33 90 8. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 36 91 8.1. ECDSA . . . . . . . . . . . . . . . . . . . . . . . . . . 37 92 8.1.1. Security Considerations . . . . . . . . . . . . . . . 39 93 8.2. Edwards-curve Digital Signature Algorithms (EdDSA) . . . 40 94 8.2.1. Security Considerations . . . . . . . . . . . . . . . 41 95 9. Message Authentication (MAC) Algorithms . . . . . . . . . . . 41 96 9.1. Hash-based Message Authentication Codes (HMAC) . . . . . 41 97 9.1.1. Security Considerations . . . . . . . . . . . . . . . 43 98 9.2. AES Message Authentication Code (AES-CBC-MAC) . . . . . . 43 99 9.2.1. Security Considerations . . . . . . . . . . . . . . . 44 100 10. Content Encryption Algorithms . . . . . . . . . . . . . . . . 45 101 10.1. AES GCM . . . . . . . . . . . . . . . . . . . . . . . . 45 102 10.1.1. Security Considerations . . . . . . . . . . . . . . 46 103 10.2. AES CCM . . . . . . . . . . . . . . . . . . . . . . . . 47 104 10.2.1. Security Considerations . . . . . . . . . . . . . . 50 105 10.3. ChaCha20 and Poly1305 . . . . . . . . . . . . . . . . . 50 106 10.3.1. Security Considerations . . . . . . . . . . . . . . 51 107 11. Key Derivation Functions (KDF) . . . . . . . . . . . . . . . 51 108 11.1. HMAC-based Extract-and-Expand Key Derivation Function 109 (HKDF) . . . . . . . . . . . . . . . . . . . . . . . . . 52 110 11.2. Context Information Structure . . . . . . . . . . . . . 54 111 12. Content Key Distribution Methods . . . . . . . . . . . . . . 59 112 12.1. Direct Encryption . . . . . . . . . . . . . . . . . . . 59 113 12.1.1. Direct Key . . . . . . . . . . . . . . . . . . . . . 60 114 12.1.2. Direct Key with KDF . . . . . . . . . . . . . . . . 60 115 12.2. Key Wrapping . . . . . . . . . . . . . . . . . . . . . . 62 116 12.2.1. AES Key Wrapping . . . . . . . . . . . . . . . . . . 63 117 12.3. Key Transport . . . . . . . . . . . . . . . . . . . . . 64 118 12.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 64 119 12.4.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 65 120 12.4.2. Security Considerations . . . . . . . . . . . . . . 69 121 12.5. Key Agreement with Key Wrap . . . . . . . . . . . . . . 69 122 12.5.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 69 123 13. Key Object Parameters . . . . . . . . . . . . . . . . . . . . 71 124 13.1. Elliptic Curve Keys . . . . . . . . . . . . . . . . . . 72 125 13.1.1. Double Coordinate Curves . . . . . . . . . . . . . . 72 126 13.2. Octet Key Pair . . . . . . . . . . . . . . . . . . . . . 73 127 13.3. Symmetric Keys . . . . . . . . . . . . . . . . . . . . . 74 128 14. CBOR Encoder Restrictions . . . . . . . . . . . . . . . . . . 75 129 15. Application Profiling Considerations . . . . . . . . . . . . 75 130 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 77 131 16.1. CBOR Tag assignment . . . . . . . . . . . . . . . . . . 77 132 16.2. COSE Header Parameters Registry . . . . . . . . . . . . 77 133 16.3. COSE Header Algorithm Parameters Registry . . . . . . . 78 134 16.4. COSE Algorithms Registry . . . . . . . . . . . . . . . . 78 135 16.5. COSE Key Common Parameters Registry . . . . . . . . . . 79 136 16.6. COSE Key Type Parameters Registry . . . . . . . . . . . 80 137 16.7. COSE Key Type Registry . . . . . . . . . . . . . . . . . 81 138 16.8. COSE Elliptic Curve Parameters Registry . . . . . . . . 81 139 16.9. Media Type Registrations . . . . . . . . . . . . . . . . 82 140 16.9.1. COSE Security Message . . . . . . . . . . . . . . . 82 141 16.9.2. COSE Key media type . . . . . . . . . . . . . . . . 83 143 16.10. CoAP Content-Format Registrations . . . . . . . . . . . 85 144 16.11. Expert Review Instructions . . . . . . . . . . . . . . . 86 145 17. Implementation Status . . . . . . . . . . . . . . . . . . . . 87 146 17.1. Author's Versions . . . . . . . . . . . . . . . . . . . 88 147 17.2. COSE Testing Library . . . . . . . . . . . . . . . . . . 88 148 18. Security Considerations . . . . . . . . . . . . . . . . . . . 89 149 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 91 150 19.1. Normative References . . . . . . . . . . . . . . . . . . 91 151 19.2. Informative References . . . . . . . . . . . . . . . . . 92 152 Appendix A. Guidelines for External Data Authentication of 153 Algorithms . . . . . . . . . . . . . . . . . . . . . 95 154 A.1. Algorithm Identification . . . . . . . . . . . . . . . . 95 155 A.2. Counter Signature Without Headers . . . . . . . . . . . . 98 156 Appendix B. Two Layers of Recipient Information . . . . . . . . 99 157 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 101 158 C.1. Examples of Signed Message . . . . . . . . . . . . . . . 102 159 C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 102 160 C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 103 161 C.1.3. Counter Signature . . . . . . . . . . . . . . . . . . 104 162 C.1.4. Signature w/ Criticality . . . . . . . . . . . . . . 105 163 C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 106 164 C.2.1. Single ECDSA signature . . . . . . . . . . . . . . . 106 165 C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 107 166 C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 107 167 C.3.2. Direct plus Key Derivation . . . . . . . . . . . . . 108 168 C.3.3. Counter Signature on Encrypted Content . . . . . . . 109 169 C.3.4. Encrypted Content with External Data . . . . . . . . 111 170 C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 111 171 C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 111 172 C.4.2. Encrypted Message w/ a Partial IV . . . . . . . . . . 112 173 C.5. Examples of MACed messages . . . . . . . . . . . . . . . 112 174 C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 112 175 C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 113 176 C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 114 177 C.5.4. Multi-recipient MACed message . . . . . . . . . . . . 115 178 C.6. Examples of MAC0 messages . . . . . . . . . . . . . . . . 116 179 C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 116 180 C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 117 181 C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 117 182 C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 118 183 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 120 184 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 121 186 1. Introduction 188 There has been an increased focus on small, constrained devices that 189 make up the Internet of Things (IoT). One of the standards that has 190 come out of this process is the Concise Binary Object Representation 191 (CBOR) [RFC7049]. CBOR extended the data model of the JavaScript 192 Object Notation (JSON) [RFC7159] by allowing for binary data, among 193 other changes. CBOR is being adopted by several of the IETF working 194 groups dealing with the IoT world as their encoding of data 195 structures. CBOR was designed specifically to be both small in terms 196 of messages transport and implementation size, as well having a 197 schema free decoder. A need exists to provide message security 198 services for IoT, and using CBOR as the message encoding format makes 199 sense. 201 The JOSE working group produced a set of documents 202 [RFC7515][RFC7516][RFC7517][RFC7518] using JSON that specified how to 203 process encryption, signatures and Message Authentication Code (MAC) 204 operations, and how to encode keys using JSON. This document defines 205 the CBOR Object Encryption and Signing (COSE) standard which does the 206 same thing for the CBOR encoding format. While there is a strong 207 attempt to keep the flavor of the original JOSE documents, two 208 considerations are taken into account: 210 o CBOR has capabilities that are not present in JSON and are 211 appropriate to use. One example of this is the fact that CBOR has 212 a method of encoding binary directly without first converting it 213 into a base64 encoded string. 215 o COSE is not a direct copy of the JOSE specification. In the 216 process of creating COSE, decisions that were made for JOSE were 217 re-examined. In many cases different results were decided on as 218 the criteria was not always the same. 220 1.1. Design changes from JOSE 222 o Define a single top message structure so that encrypted, signed 223 and MACed messages can easily be identified and still have a 224 consistent view. 226 o Signed messages distinguish between the protected and unprotected 227 parameters that relate to the content from those that relate to 228 the signature. 230 o MACed messages are separated from signed messages. 232 o MACed messages have the ability to use the same set of recipient 233 algorithms as enveloped messages for obtaining the MAC 234 authentication key. 236 o Use binary encodings for binary data rather than base64url 237 encodings. 239 o Combine the authentication tag for encryption algorithms with the 240 cipher text. 242 o The set of cryptographic algorithms has been expanded in some 243 directions, and trimmed in others. 245 1.2. Requirements Terminology 247 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 248 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 249 "OPTIONAL" in this document are to be interpreted as described in 250 [RFC2119]. 252 When the words appear in lower case, their natural language meaning 253 is used. 255 1.3. CBOR Grammar 257 There is currently no standard CBOR grammar available for use by 258 specifications. The CBOR structures are therefore described in 259 prose. 261 The document was developed by first working on the grammar and then 262 developing the prose to go with it. An artifact of this is that the 263 prose was written using the primitive type strings defined by CBOR 264 Data Definition Language (CDDL) [I-D.greevenbosch-appsawg-cbor-cddl]. 265 In this specification, the following primitive types are used: 267 any - non-specific value that permits all CBOR values to be placed 268 here. 270 bool - a boolean value (true: major type 7, value 21; false: major 271 type 7, value 20). 273 bstr - byte string (major type 2). 275 int - an unsigned integer or a negative integer. 277 nil - a null value (major type 7, value 22). 279 nint - a negative integer (major type 1). 281 tstr - a UTF-8 text string (major type 3). 283 uint - an unsigned integer (major type 0). 285 Two syntaxes from CDDL appear in this document as shorthand. These 286 are: 288 FOO / BAR - indicates that either FOO or BAR can appear here 290 [+ FOO] - indicates that the type FOO appears one or more times in 291 an array 293 As well as the prose description, a version of a CBOR grammar is 294 presented in CDDL. Since CDDL has not been published as an RFC, this 295 grammar may not work with the final version of CDDL. The CDDL 296 grammar is informational, the prose description is normative. 298 The collected CDDL can be extracted from the XML version of this 299 document via the following XPath expression below. (Depending on the 300 XPath evaluator one is using, it may be necessary to deal with > 301 as an entity.) 303 //artwork[@type='CDDL']/text() 305 CDDL expects the initial non-terminal symbol to be the first symbol 306 in the file. For this reason the first fragment of CDDL is presented 307 here. 309 start = COSE_Messages / COSE_Key / COSE_KeySet / Internal_Types 311 ; This is defined to make the tool quieter: 312 Internal_Types = Sig_structure / Enc_structure / MAC_structure / 313 COSE_KDF_Context 315 The non-terminal Internal_Types is defined for dealing with the 316 automated validation tools used during the writing of this document. 317 It references those non-terminals that are used for security 318 computations, but are not emitted for transport. 320 1.4. CBOR Related Terminology 322 In JSON, maps are called objects and only have one kind of map key: a 323 string. In COSE, we use strings, negative integers and unsigned 324 integers as map keys. The integers are used for compactness of 325 encoding and easy comparison. The inclusion of strings allows for an 326 additional range of short encoded values to be used as well. Since 327 the word "key" is mainly used in its other meaning, as a 328 cryptographic key, we use the term "label" for this usage as a map 329 key. 331 The presence of a label in a COSE map which is not a string or an 332 integer is an error. Applications can either fail processing or 333 process messages with incorrect labels, however they MUST NOT create 334 messages with incorrect labels. 336 A CDDL grammar fragment is defined that defines the non-terminals 337 'label', as in the previous paragraph and 'values', which permits any 338 value to be used. 340 label = int / tstr 341 values = any 343 1.5. Document Terminology 345 In this document, we use the following terminology: 347 Byte is a synonym for octet. 349 Constrained Application Protocol (CoAP) is a specialized web transfer 350 protocol for use in constrained systems. It is defined in [RFC7252]. 352 Authenticated Encryption (AE) [RFC5116] algorithms are those 353 encryption algorithms which provide an authentication check of the 354 contents algorithm with the encryption service. 356 Authenticated Encryption with Authenticated Data (AEAD) [RFC5116] 357 algorithms provide the same content authentication service as AE 358 algorithms, but additionally provide for authentication of non- 359 encrypted data as well. 361 2. Basic COSE Structure 363 The COSE object structure is designed so that there can be a large 364 amount of common code when parsing and processing the different types 365 of security messages. All of the message structures are built on the 366 CBOR array type. The first three elements of the array always 367 contain the same information: 369 1. The set of protected header parameters wrapped in a bstr. 371 2. The set of unprotected header parameters as a map. 373 3. The content of the message. The content is either the plain text 374 or the cipher text as appropriate. The content may be detached, 375 but the location is still used. The content is wrapped in a bstr 376 when present and is a nil value when detached. 378 Elements after this point are dependent on the specific message type. 380 COSE messages are also built using the concept of layers to separate 381 different types of cryptographic concepts. As an example of how this 382 works, consider the COSE_Encrypt message (Section 5.1). This message 383 type is broken into two layers: the content layer and the recipient 384 layer. In the content layer, the plain text is encrypted and 385 information about the encrypted message are placed. In the recipient 386 layer, the content encryption key (CEK) is encrypted and information 387 about how it is encrypted for each recipient is placed. A single 388 layer version of the encryption message COSE_Encrypt0 (Section 5.2) 389 is provided for cases where the CEK is pre-shared. 391 Identification of which type of message has been presented is done by 392 the following methods: 394 1. The specific message type is known from the context. This may be 395 defined by a marker in the containing structure or by 396 restrictions specified by the application protocol. 398 2. The message type is identified by a CBOR tag. Messages with a 399 CBOR tag are known in this specification as tagged messages, 400 while those without the CBOR tag are known as untagged messages. 401 This document defines a CBOR tag for each of the message 402 structures. These tags can be found in Table 1. 404 3. When a COSE object is carried in a media type of application/ 405 cose, the optional parameter 'cose-type' can be used to identify 406 the embedded object. The parameter is OPTIONAL if the tagged 407 version of the structure is used. The parameter is REQUIRED if 408 the untagged version of the structure is used. The value to use 409 with the parameter for each of the structures can be found in 410 Table 1. 412 4. When a COSE object is carried as a CoAP payload, the CoAP 413 Content-Format Option can be used to identify the message 414 content. The CoAP Content-Format values can be found in 415 Table 26. The CBOR tag for the message structure is not required 416 as each security message is uniquely identified. 418 +-------+---------------+---------------+---------------------------+ 419 | CBOR | cose-type | Data Item | Semantics | 420 | Tag | | | | 421 +-------+---------------+---------------+---------------------------+ 422 | 98 | cose-sign | COSE_Sign | COSE Signed Data Object | 423 | | | | | 424 | 18 | cose-sign1 | COSE_Sign1 | COSE Single Signer Data | 425 | | | | Object | 426 | | | | | 427 | 96 | cose-encrypt | COSE_Encrypt | COSE Encrypted Data | 428 | | | | Object | 429 | | | | | 430 | 16 | cose-encrypt0 | COSE_Encrypt0 | COSE Single Recipient | 431 | | | | Encrypted Data Object | 432 | | | | | 433 | 97 | cose-mac | COSE_Mac | COSE Mac-ed Data Object | 434 | | | | | 435 | 17 | cose-mac0 | COSE_Mac0 | COSE Mac w/o Recipients | 436 | | | | Object | 437 +-------+---------------+---------------+---------------------------+ 439 Table 1: COSE Message Identification 441 The following CDDL fragment identifies all of the top messages 442 defined in this document. Separate non-terminals are defined for the 443 tagged and the untagged versions of the messages. 445 COSE_Messages = COSE_Untagged_Message / COSE_Tagged_Message 447 COSE_Untagged_Message = COSE_Sign / COSE_Sign1 / 448 COSE_Encrypt / COSE_Encrypt0 / 449 COSE_Mac / COSE_Mac0 451 COSE_Tagged_Message = COSE_Sign_Tagged / COSE_Sign1_Tagged / 452 COSE_Encrypt_Tagged / COSE_Encrypt0_Tagged / 453 COSE_Mac_Tagged / COSE_Mac0_Tagged 455 3. Header Parameters 457 The structure of COSE has been designed to have two buckets of 458 information that are not considered to be part of the payload itself, 459 but are used for holding information about content, algorithms, keys, 460 or evaluation hints for the processing of the layer. These two 461 buckets are available for use in all of the structures except for 462 keys. While these buckets are present, they may not all be usable in 463 all instances. For example, while the protected bucket is defined as 464 part of the recipient structure, some of the algorithms used for 465 recipient structures do not provide for authenticated data. If this 466 is the case, the protected bucket is left empty. 468 Both buckets are implemented as CBOR maps. The map key is a 'label' 469 (Section 1.4). The value portion is dependent on the definition for 470 the label. Both maps use the same set of label/value pairs. The 471 integer and string values for labels have been divided into several 472 sections with a standard range, a private range, and a range that is 473 dependent on the algorithm selected. The defined labels can be found 474 in the "COSE Header Parameters" IANA registry (Section 16.2). 476 Two buckets are provided for each layer: 478 protected: Contains parameters about the current layer that are to 479 be cryptographically protected. This bucket MUST be empty if it 480 is not going to be included in a cryptographic computation. This 481 bucket is encoded in the message as a binary object. This value 482 is obtained by CBOR encoding the protected map and wrapping it in 483 a bstr object. Senders SHOULD encode a zero length map as a zero 484 length string rather than as a zero length map (encoded as h'a0'). 485 The zero length binary encoding is preferred because it is both 486 shorter and the version used in the serialization structures for 487 cryptographic computation. After encoding the map, the value is 488 wrapped in the binary object. Recipients MUST accept both a zero 489 length binary value and a zero length map encoded in the binary 490 value. The wrapping allows for the encoding of the protected map 491 to be transported with a greater chance that it will not be 492 altered in transit. (Badly behaved intermediates could decode and 493 re-encode, but this will result in a failure to verify unless the 494 re-encoded byte string is identical to the decoded byte string.) 495 This avoids the problem of all parties needing to be able to do a 496 common canonical encoding. 498 unprotected: Contains parameters about the current layer that are 499 not cryptographically protected. 501 Only parameters that deal with the current layer are to be placed at 502 that layer. As an example of this, the parameter 'content type' 503 describes the content of the message being carried in the message. 504 As such, this parameter is placed only in the content layer and is 505 not placed in the recipient or signature layers. In principle, one 506 should be able to process any given layer without reference to any 507 other layer. With the exception of the COSE_Sign structure, the only 508 data that needs to cross layers is the cryptographic key. 510 The buckets are present in all of the security objects defined in 511 this document. The fields in order are the 'protected' bucket (as a 512 CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map' 513 type). The presence of both buckets is required. The parameters 514 that go into the buckets come from the IANA "COSE Header Parameters" 515 registry (Section 16.2). Some common parameters are defined in the 516 next section, but a number of parameters are defined throughout this 517 document. 519 Labels in each of the maps MUST be unique. When processing messages, 520 if a label appears multiple times, the message MUST be rejected as 521 malformed. Applications SHOULD verify that the same label does not 522 occur in both the protected and unprotected headers. If the message 523 is not rejected as malformed, attributes MUST be obtained from the 524 protected bucket before they are obtained from the unprotected 525 bucket. 527 The following CDDL fragment represents the two header buckets. A 528 group Headers is defined in CDDL that represents the two buckets in 529 which attributes are placed. This group is used to provide these two 530 fields consistently in all locations. A type is also defined which 531 represents the map of common headers. 533 Headers = ( 534 protected : empty_or_serialized_map, 535 unprotected : header_map 536 ) 538 header_map = { 539 Generic_Headers, 540 * label => values 541 } 543 empty_or_serialized_map = bstr .cbor header_map / bstr .size 0 545 3.1. Common COSE Headers Parameters 547 This section defines a set of common header parameters. A summary of 548 these parameters can be found in Table 2. This table should be 549 consulted to determine the value of label, and the type of the value. 551 The set of header parameters defined in this section are: 553 alg: This parameter is used to indicate the algorithm used for the 554 security processing. This parameter MUST be authenticated where 555 the ability to do so exists. This support is provided by AEAD 556 algorithms or construction (COSE_Sign, COSE_Sign0, COSE_Mac and 557 COSE_Mac0). This authentication can be done either by placing the 558 header in the protected header bucket or as part of the externally 559 supplied data. The value is taken from the "COSE Algorithms" 560 Registry (see Section 16.4). 562 crit: The parameter is used to indicate which protected header 563 labels an application that is processing a message is required to 564 understand. Parameters defined in this document do not need to be 565 included as they should be understood by all implementations. 566 When present, this parameter MUST be placed in the protected 567 header bucket. The array MUST have at least one value in it. 568 Not all labels need to be included in the 'crit' parameter. The 569 rules for deciding which header labels are placed in the array 570 are: 572 * Integer labels in the range of 0 to 8 SHOULD be omitted. 574 * Integer labels in the range -1 to -128 can be omitted as they 575 are algorithm dependent. If an application can correctly 576 process an algorithm, it can be assumed that it will correctly 577 process all of the common parameters associated with that 578 algorithm. Integer labels in the range -129 to -65536 SHOULD 579 be included as these would be less common parameters that might 580 not be generally supported. 582 * Labels for parameters required for an application MAY be 583 omitted. Applications should have a statement if the label can 584 be omitted. 586 The header parameter values indicated by 'crit' can be processed 587 by either the security library code or by an application using a 588 security library; the only requirement is that the parameter is 589 processed. If the 'crit' value list includes a value for which 590 the parameter is not in the protected bucket, this is a fatal 591 error in processing the message. 593 content type: This parameter is used to indicate the content type of 594 the data in the payload or cipher text fields. Integers are from 595 the "CoAP Content-Formats" IANA registry table [COAP.Formats]. 596 Text values following the syntax of "/" 597 where and are defined in Section 4.2 of 598 [RFC6838]. Leading and trailing whitespace is also omitted. 599 Textual content values along with parameters and subparameters can 600 be located using the IANA "Media Types" registry. Applications 601 SHOULD provide this parameter if the content structure is 602 potentially ambiguous. 604 kid: This parameter identifies one piece of data that can be used as 605 input to find the needed cryptographic key. The value of this 606 parameter can be matched against the 'kid' member in a COSE_Key 607 structure. Other methods of key distribution can define an 608 equivalent field to be matched. Applications MUST NOT assume that 609 'kid' values are unique. There may be more than one key with the 610 same 'kid' value, so all of the keys associated with this 'kid' 611 may need to be checked. The internal structure of 'kid' values is 612 not defined and cannot be relied on by applications. Key 613 identifier values are hints about which key to use. This is not a 614 security critical field. For this reason, it can be placed in the 615 unprotected headers bucket. 617 IV: This parameter holds the Initialization Vector (IV) value. For 618 some symmetric encryption algorithms this may be referred to as a 619 nonce. The IV can be placed in the unprotected header as 620 modifying the IV will cause the decryption to yield plaintext that 621 is readily detectable as garbled. 623 Partial IV This parameter holds a part of the IV value. When using 624 the COSE_Encrypt0 structure, a portion of the IV can be part of 625 the context associated with the key. This field is used to carry 626 a value that causes the IV to be changed for each message. The IV 627 can be placed in the unprotected header as modifying the IV will 628 cause the decryption to yield plaintext that is readily detectable 629 as garbled. The 'Initialization Vector' and 'Partial 630 Initialization Vector' parameters MUST NOT both be present in the 631 same security layer. 632 The message IV is generated by the following steps: 634 1. Left pad the partial IV with zeros to the length of IV. 636 2. XOR the padded partial IV with the context IV. 638 counter signature: This parameter holds one or more counter 639 signature values. Counter signatures provide a method of having a 640 second party sign some data. The counter signature parameter can 641 occur as an unprotected attribute in any of the following 642 structures: COSE_Sign1, COSE_Signature, COSE_Encrypt, 643 COSE_recipient, COSE_Encrypt0, COSE_Mac and COSE_Mac0. These 644 structures all have the same beginning elements so that a 645 consistent calculation of the counter signature can be computed. 646 Details on computing counter signatures are found in Section 4.5. 648 +-----------+-------+----------------+-------------+----------------+ 649 | name | label | value type | value | description | 650 | | | | registry | | 651 +-----------+-------+----------------+-------------+----------------+ 652 | alg | 1 | int / tstr | COSE | Cryptographic | 653 | | | | Algorithms | algorithm to | 654 | | | | registry | use | 655 | | | | | | 656 | crit | 2 | [+ label] | COSE Header | Critical | 657 | | | | Labels | headers to be | 658 | | | | registry | understood | 659 | | | | | | 660 | content | 3 | tstr / uint | CoAP | Content type | 661 | type | | | Content- | of the payload | 662 | | | | Formats or | | 663 | | | | Media Types | | 664 | | | | registry | | 665 | | | | | | 666 | kid | 4 | bstr | | Key identifier | 667 | | | | | | 668 | IV | 5 | bstr | | Full | 669 | | | | | Initialization | 670 | | | | | Vector | 671 | | | | | | 672 | Partial | 6 | bstr | | Partial | 673 | IV | | | | Initialization | 674 | | | | | Vector | 675 | | | | | | 676 | counter | 7 | COSE_Signature | | CBOR encoded | 677 | signature | | / [+ | | signature | 678 | | | COSE_Signature | | structure | 679 | | | ] | | | 680 +-----------+-------+----------------+-------------+----------------+ 682 Table 2: Common Header Parameters 684 The CDDL fragment that represents the set of headers defined in this 685 section is given below. Each of the headers is tagged as optional 686 because they do not need to be in every map; headers required in 687 specific maps are discussed above. 689 Generic_Headers = ( 690 ? 1 => int / tstr, ; algorithm identifier 691 ? 2 => [+label], ; criticality 692 ? 3 => tstr / int, ; content type 693 ? 4 => bstr, ; key identifier 694 ? 5 => bstr, ; IV 695 ? 6 => bstr, ; Partial IV 696 ? 7 => COSE_Signature / [+COSE_Signature] ; Counter signature 697 ) 699 4. Signing Objects 701 COSE supports two different signature structures. COSE_Sign allows 702 for one or more signatures to be applied to the same content. 703 COSE_Sign1 is restricted to a single signer. The structures cannot 704 be converted between each other; as the signature computation 705 includes a parameter identifying which structure is being used, the 706 converted structure will fail signature validation. 708 4.1. Signing with One or More Signers 710 The COSE_Sign structure allows for one or more signatures to be 711 applied to a message payload. Parameters relating to the content and 712 parameters relating to the signature are carried along with the 713 signature itself. These parameters may be authenticated by the 714 signature, or just present. An example of a parameter about the 715 content is the content type. Examples of parameters about the 716 signature would be the algorithm and key used to create the signature 717 and counter signatures. 719 When more than one signature is present, the successful validation of 720 one signature associated with a given signer is usually treated as a 721 successful signature by that signer. However, there are some 722 application environments where other rules are needed. An 723 application that employs a rule other than one valid signature for 724 each signer must specify those rules. Also, where simple matching of 725 the signer identifier is not sufficient to determine whether the 726 signatures were generated by the same signer, the application 727 specification must describe how to determine which signatures were 728 generated by the same signer. Support for different communities of 729 recipients is the primary reason that signers choose to include more 730 than one signature. For example, the COSE_Sign structure might 731 include signatures generated with the Edwards Digital Signature 732 Algorithm (EdDSA) [I-D.irtf-cfrg-eddsa] signature algorithm and with 733 the Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] 734 signature algorithm. This allows recipients to verify the signature 735 associated with one algorithm or the other. (The original source of 736 this text is [RFC5652].) More detailed information on multiple 737 signature evaluation can be found in [RFC5752]. 739 The signature structure can be encoded either as tagged or untagged 740 depending on the context it will be used in. A tagged COSE_Sign 741 structure is identified by the CBOR tag TBD1. The CDDL fragment that 742 represents this is: 744 COSE_Sign_Tagged = #6.98(COSE_Sign) 746 A COSE Signed Message is defined in two parts. The CBOR object that 747 carries the body and information about the body is called the 748 COSE_Sign structure. The CBOR object that carries the signature and 749 information about the signature is called the COSE_Signature 750 structure. Examples of COSE Signed Messages can be found in 751 Appendix C.1. 753 The COSE_Sign structure is a CBOR array. The fields of the array in 754 order are: 756 protected as described in Section 3. 758 unprotected as described in Section 3. 760 payload contains the serialized content to be signed. If the 761 payload is not present in the message, the application is required 762 to supply the payload separately. The payload is wrapped in a 763 bstr to ensure that it is transported without changes. If the 764 payload is transported separately ("detached content"), then a nil 765 CBOR object is placed in this location and it is the 766 responsibility of the application to ensure that it will be 767 transported without changes. 769 Note: When a signature with message recovery algorithm is used 770 (Section 8), the maximum number of bytes that can be recovered is 771 the length of the payload. The size of the payload is reduced by 772 the number of bytes that will be recovered. If all of the bytes 773 of the payload are consumed, then the payload is encoded as a zero 774 length binary string rather than as being absent. 776 signatures is an array of signatures. Each signature is represented 777 as a COSE_Signature structure. 779 The CDDL fragment that represents the above text for COSE_Sign 780 follows. 782 COSE_Sign = [ 783 Headers, 784 payload : bstr / nil, 785 signatures : [+ COSE_Signature] 786 ] 788 The COSE_Signature structure is a CBOR array. The fields of the 789 array in order are: 791 protected as described in Section 3. 793 unprotected as described in Section 3. 795 signature contains the computed signature value. The type of the 796 field is a bstr. Algorithms MUST specify padding if the signature 797 value is not a multiple of 8 bits. 799 The CDDL fragment that represents the above text for COSE_Signature 800 follows. 802 COSE_Signature = [ 803 Headers, 804 signature : bstr 805 ] 806 ! 808 4.2. Signing with One Signer 810 The COSE_Sign1 signature structure is used when only one signature is 811 going to be placed on a message. The parameters dealing with the 812 content and the signature are placed in the same pair of buckets 813 rather than having the separation of COSE_Sign. 815 The structure can be encoded either tagged or untagged depending on 816 the context it will be used in. A tagged COSE_Sign1 structure is 817 identified by the CBOR tag TBD7. The CDDL fragment that represents 818 this is: 820 COSE_Sign1_Tagged = #6.18(COSE_Sign1) 822 The CBOR object that carries the body, the signature, and the 823 information about the body and signature is called the COSE_Sign1 824 structure. Examples of COSE_Sign1 messages can be found in 825 Appendix C.2. 827 The COSE_Sign1 structure is a CBOR array. The fields of the array in 828 order are: 830 protected as described in Section 3. 832 unprotected as described in Section 3. 834 payload as described in Section 4.1. 836 signature contains the computed signature value. The type of the 837 field is a bstr. 839 The CDDL fragment that represents the above text for COSE_Sign1 840 follows. 842 COSE_Sign1 = [ 843 Headers, 844 payload : bstr / nil, 845 signature : bstr 846 ] 848 4.3. Externally Supplied Data 850 One of the features offered in the COSE document is the ability for 851 applications to provide additional data to be authenticated, but that 852 is not carried as part of the COSE object. The primary reason for 853 supporting this can be seen by looking at the CoAP message structure 854 [RFC7252], where the facility exists for options to be carried before 855 the payload. Examples of data that can be placed in this location 856 would be the CoAP code or CoAP options. If the data is in the header 857 section, then it is available for proxies to help in performing its 858 operations. For example, the Accept Option can be used by a proxy to 859 determine if an appropriate value is in the Proxy's cache. But the 860 sender can prevent a proxy from changing the set of values that it 861 will accept by including that value in the resulting authentication 862 tag. However, it may also be desired to protect these values so that 863 if they are modified in transit, it can be detected. 865 This document describes the process for using a byte array of 866 externally supplied authenticated data; however, the method of 867 constructing the byte array is a function of the application. 868 Applications that use this feature need to define how the externally 869 supplied authenticated data is to be constructed. Such a 870 construction needs to take into account the following issues: 872 o If multiple items are included, applications need to ensure that 873 the same byte string is not produced if there are different 874 inputs. This could occur by appending the strings 'AB' and 'CDE' 875 or by appending the strings 'ABC' and 'DE'. This is usually 876 addressed by making fields a fixed width and/or encoding the 877 length of the field as part of the output. Using options from 878 CoAP [RFC7252] as an example, these fields use a TLV structure so 879 they can be concatenated without any problems. 881 o If multiple items are included, an order for the items needs to be 882 defined. Using options from CoAP as an example, an application 883 could state that the fields are to be ordered by the option 884 number. 886 o Applications need to ensure that the byte stream is going to be 887 the same on both sides. Using options from CoAP might give a 888 problem if the same relative numbering is kept. An intermediate 889 node could insert or remove an option, changing how the relative 890 number is done. An application would need to specify that the 891 relative number must be re-encoded to be relative only to the 892 options that are in the external data. 894 4.4. Signing and Verification Process 896 In order to create a signature, a well-defined byte stream is needed. 897 The Sig_struture is used to create the canonical form. This signing 898 and verification process takes in the body information (COSE_Sign or 899 COSE_Sign1), the signer information (COSE_Signature), and the 900 application data (external source). A Sig_structure is a CBOR array. 901 The fields of the Sig_struture in order are: 903 1. A text string identifying the context of the signature. The 904 context string is: 906 "Signature" for signatures using the COSE_Signature structure. 908 "Signature1" for signatures using the COSE_Sign1 structure. 910 "CounterSignature" for signatures used as counter signature 911 attributes. 913 2. The protected attributes from the body structure encoded in a 914 bstr type. If there are no protected attributes, a bstr of 915 length zero is used. 917 3. The protected attributes from the signer structure encoded in a 918 bstr type. If there are no protected attributes, a bstr of 919 length zero is used. This field is omitted for the COSE_Sign1 920 signature structure. 922 4. The protected attributes from the application encoded in a bstr 923 type. If this field is not supplied, it defaults to a zero 924 length binary string. (See Section 4.3 for application guidance 925 on constructing this field.) 927 5. The payload to be signed encoded in a bstr type. The payload is 928 placed here independent of how it is transported. 930 The CDDL fragment that describes the above text is. 932 Sig_structure = [ 933 context : "Signature" / "Signature1" / "CounterSignature", 934 body_protected : empty_or_serialized_map, 935 ? sign_protected : empty_or_serialized_map, 936 external_aad : bstr, 937 payload : bstr 938 ] 940 How to compute a signature: 942 1. Create a Sig_structure and populate it with the appropriate 943 fields. 945 2. Create the value ToBeSigned by encoding the Sig_structure to a 946 byte string, using the encoding described in Section 14. 948 3. Call the signature creation algorithm passing in K (the key to 949 sign with), alg (the algorithm to sign with), and ToBeSigned (the 950 value to sign). 952 4. Place the resulting signature value in the 'signature' field of 953 the array. 955 The steps for verifying a signature are: 957 1. Create a Sig_structure object and populate it with the 958 appropriate fields. 960 2. Create the value ToBeSigned by encoding the Sig_structure to a 961 byte string, using the encoding described in Section 14. 963 3. Call the signature verification algorithm passing in K (the key 964 to verify with), alg (the algorithm used sign with), ToBeSigned 965 (the value to sign), and sig (the signature to be verified). 967 In addition to performing the signature verification, the application 968 may also perform the appropriate checks to ensure that the key is 969 correctly paired with the signing identity and that the signing 970 identity is authorized before performing actions. 972 4.5. Computing Counter Signatures 974 Counter signatures provide a method of associating different 975 signature generated by different signers with some piece of content. 976 This is normally used to provide a signature on a signature allowing 977 for a proof that a signature existed at a given time (i.e., a 978 Timestamp). In this document, we allow for counter signatures to 979 exist in a greater number of environments. As an example, it is 980 possible to place a counter signature in the unprotected attributes 981 of a COSE_Encrypt object. This would allow for an intermediary to 982 either verify that the encrypted byte stream has not been modified, 983 without being able to decrypt it, or for the intermediary to assert 984 that an encrypted byte stream either existed at a given time or 985 passed through it in terms of routing (i.e., a proxy signature). 987 An example of a counter signature on a signature can be found in 988 Appendix C.1.3. An example of a counter signature in an encryption 989 object can be found in Appendix C.3.3. 991 The creation and validation of counter signatures over the different 992 items relies on the fact that the structure of the objects have the 993 same structure. The elements are a set of protected attributes, a 994 set of unprotected attributes, and a body, in that order. This means 995 that the Sig_structure can be used in a uniform manner to get the 996 byte stream for processing a signature. If the counter signature is 997 going to be computed over a COSE_Encrypt structure, the 998 body_protected and payload items can be mapped into the Sig_structure 999 in the same manner as from the COSE_Sign structure. 1001 It should be noted that only a signature algorithm with appendix (see 1002 Section 8) can be used for counter signatures. This is because the 1003 body should be able to be processed without having to evaluate the 1004 counter signature, and this is not possible for signature schemes 1005 with message recovery. 1007 5. Encryption Objects 1009 COSE supports two different encryption structures. COSE_Encrypt0 is 1010 used when a recipient structure is not needed because the key to be 1011 used is known implicitly. COSE_Encrypt is used the rest of the time. 1012 This includes cases where there are multiple recipients or a 1013 recipient algorithm other than direct is used. 1015 5.1. Enveloped COSE Structure 1017 The enveloped structure allows for one or more recipients of a 1018 message. There are provisions for parameters about the content and 1019 parameters about the recipient information to be carried in the 1020 message. The protected parameters associated with the content are 1021 authenticated by the content encryption algorithm. The protected 1022 parameters associated with the recipient are authenticated by the 1023 recipient algorithm (when the algorithm supports it). Examples of 1024 parameters about the content are the type of the content and the 1025 content encryption algorithm. Examples of parameters about the 1026 recipient are the recipient's key identifier and the recipient's 1027 encryption algorithm. 1029 The same techniques and structures are used for encrypting both the 1030 plain text and the keys. This is different from the approach used by 1031 both CMS [RFC5652] and JSON Web Encryption (JWE) [RFC7516] where 1032 different structures are used for the content layer and for the 1033 recipient layer. Two structures are defined: COSE_Encrypt to hold 1034 the encrypted content and COSE_recipient to hold the encrypted keys 1035 for recipients. Examples of encrypted messages can be found in 1036 Appendix C.3. 1038 The COSE_Encrypt structure can be encoded either tagged or untagged 1039 depending on the context it will be used in. A tagged COSE_Encrypt 1040 structure is identified by the CBOR tag TBD2. The CDDL fragment that 1041 represents this is: 1043 COSE_Encrypt_Tagged = #6.96(COSE_Encrypt) 1045 The COSE_Encrypt structure is a CBOR array. The fields of the array 1046 in order are: 1048 protected as described in Section 3. 1050 unprotected as described in Section 3. ' 1052 ciphertext contains the cipher text encoded as a bstr. If the 1053 cipher text is to be transported independently of the control 1054 information about the encryption process (i.e., detached content) 1055 then the field is encoded as a nil value. 1057 recipients contains an array of recipient information structures. 1058 The type for the recipient information structure is a 1059 COSE_recipient. 1061 The CDDL fragment that corresponds to the above text is: 1063 COSE_Encrypt = [ 1064 Headers, 1065 ciphertext : bstr / nil, 1066 recipients : [+COSE_recipient] 1067 ] 1068 The COSE_recipient structure is a CBOR array. The fields of the 1069 array in order are: 1071 protected as described in Section 3. 1073 unprotected as described in Section 3. 1075 ciphertext contains the encrypted key encoded as a bstr. All 1076 encoded keys are symetric keys, the binary value of the key is the 1077 content. If there is not an encrypted key, then this field is 1078 encoded as a nil value. 1080 recipients contains an array of recipient information structures. 1081 The type for the recipient information structure is a 1082 COSE_recipient. (An example of this can be found in Appendix B.) 1083 If there are no recipient information structures, this element is 1084 absent. 1086 The CDDL fragment that corresponds to the above text for 1087 COSE_recipient is: 1089 COSE_recipient = [ 1090 Headers, 1091 ciphertext : bstr / nil, 1092 ? recipients : [+COSE_recipient] 1093 ] 1095 5.1.1. Content Key Distribution Methods 1097 An encrypted message consists of an encrypted content and an 1098 encrypted CEK for one or more recipients. The CEK is encrypted for 1099 each recipient, using a key specific to that recipient. The details 1100 of this encryption depend on which class the recipient algorithm 1101 falls into. Specific details on each of the classes can be found in 1102 Section 12. A short summary of the five content key distribution 1103 methods is: 1105 direct: The CEK is the same as the identified previously distributed 1106 symmetric key or derived from a previously distributed secret. No 1107 CEK is transported in the message. 1109 symmetric key-encryption keys: The CEK is encrypted using a 1110 previously distributed symmetric KEK. 1112 key agreement: The recipient's public key and a sender's private key 1113 are used to generate a pairwise secret, a KDF is applied to derive 1114 a key, and then the CEK is either the derived key or encrypted by 1115 the derived key. 1117 key transport: The CEK is encrypted with the recipient's public key. 1118 No key transport algorithms are defined in this document. 1120 passwords: The CEK is encrypted in a KEK that is derived from a 1121 password. No password algorithms are defined in this document. 1123 5.2. Single Recipient Encrypted 1125 The COSE_Encrypt0 encrypted structure does not have the ability to 1126 specify recipients of the message. The structure assumes that the 1127 recipient of the object will already know the identity of the key to 1128 be used in order to decrypt the message. If a key needs to be 1129 identified to the recipient, the enveloped structure ought to be 1130 used. 1132 Examples of encrypted messages can be found in Appendix C.3. 1134 The COSE_Encrypt0 structure can be encoded either tagged or untagged 1135 depending on the context it will be used in. A tagged COSE_Encrypt0 1136 structure is identified by the CBOR tag TBD3. The CDDL fragment that 1137 represents this is: 1139 COSE_Encrypt0_Tagged = #6.16(COSE_Encrypt0) 1141 The COSE_Encrypt0 structure is a CBOR array. The fields of the array 1142 in order are: 1144 protected as described in Section 3. 1146 unprotected as described in Section 3. 1148 ciphertext as described in Section 5.1. 1150 The CDDL fragment for COSE_Encrypt0 that corresponds to the above 1151 text is: 1153 COSE_Encrypt0 = [ 1154 Headers, 1155 ciphertext : bstr / nil, 1156 ] 1158 5.3. How to encrypt and decrypt for AEAD Algorithms 1160 The encryption algorithm for AEAD algorithms is fairly simple. The 1161 first step is to create a consistent byte stream for the 1162 authenticated data structure. For this purpose, we use an 1163 Enc_structure. The Enc_structure is a CBOR array. The fields of the 1164 Enc_structure in order are: 1166 1. A text string identifying the context of the authenticated data 1167 structure. The context string is: 1169 "Encrypt0" for the content encryption of a COSE_Encrypt0 data 1170 structure. 1172 "Encrypt" for the first layer of a COSE_Encrypt data structure 1173 (i.e., for content encryption). 1175 "Enc_Recipient" for a recipient encoding to be placed in an 1176 COSE_Encrypt data structure. 1178 "Mac_Recipient" for a recipient encoding to be placed in a MACed 1179 message structure. 1181 "Rec_Recipient" for a recipient encoding to be placed in a 1182 recipient structure. 1184 2. The protected attributes from the body structure encoded in a 1185 bstr type. If there are no protected attributes, a bstr of 1186 length zero is used. 1188 3. The protected attributes from the application encoded in a bstr 1189 type. If this field is not supplied, it defaults to a zero 1190 length bstr. (See Section 4.3 for application guidance on 1191 constructing this field.) 1193 The CDDL fragment that describes the above text is: 1195 Enc_structure = [ 1196 context : "Encrypt" / "Encrypt0" / "Enc_Recipient" / 1197 "Mac_Recipient" / "Rec_Recipient", 1198 protected : empty_or_serialized_map, 1199 external_aad : bstr 1200 ] 1202 How to encrypt a message: 1204 1. Create an Enc_structure and populate it with the appropriate 1205 fields. 1207 2. Encode the Enc_structure to a byte stream (AAD), using the 1208 encoding described in Section 14. 1210 3. Determine the encryption key (K). This step is dependent on the 1211 class of recipient algorithm being used. For: 1213 No Recipients: The key to be used is determined by the algorithm 1214 and key at the current layer. Examples are key transport keys 1215 Section 12.3, key wrap keys Section 12.2.1 or pre-shared 1216 secrets. 1218 Direct Encryption and Direct Key Agreement: The key is 1219 determined by the key and algorithm in the recipient 1220 structure. The encryption algorithm and size of the key to be 1221 used are inputs into the KDF used for the recipient. (For 1222 direct, the KDF can be thought of as the identity operation.) 1223 Examples of these algorithms are found in Section 12.1.2 and 1224 Section 12.4.1. 1226 Other: The key is randomly or pseudo-randomly generated. 1228 4. Call the encryption algorithm with K (the encryption key), P (the 1229 plain text) and AAD. Place the returned cipher text into the 1230 'ciphertext' field of the structure. 1232 5. For recipients of the message, recursively perform the encryption 1233 algorithm for that recipient, using K (the encryption key) as the 1234 plain text. 1236 How to decrypt a message: 1238 1. Create a Enc_structure and populate it with the appropriate 1239 fields. 1241 2. Encode the Enc_structure to a byte stream (AAD), using the 1242 encoding described in Section 14. 1244 3. Determine the decryption key. This step is dependent on the 1245 class of recipient algorithm being used. For: 1247 No Recipients: The key to be used is determined by the algorithm 1248 and key at the current layer. Examples are key transport keys 1249 Section 12.3, key wrap keys Section 12.2.1 or pre-shared 1250 secrets. 1252 Direct Encryption and Direct Key Agreement: The key is 1253 determined by the key and algorithm in the recipient 1254 structure. The encryption algorithm and size of the key to be 1255 used are inputs into the KDF used for the recipient. (For 1256 direct, the KDF can be thought of as the identity operation.) 1257 Examples of these algorithms are found in Section 12.1.2 and 1258 Section 12.4.1. 1260 Other: The key is determined by decoding and decrypting one of 1261 the recipient structures. 1263 4. Call the decryption algorithm with K (the decryption key to use), 1264 C (the cipher text) and AAD. 1266 5.4. How to encrypt and decrypt for AE Algorithms 1268 How to encrypt a message: 1270 1. Verify that the 'protected' field is empty. 1272 2. Verify that there was no external additional authenticated data 1273 supplied for this operation. 1275 3. Determine the encryption key. This step is dependent on the 1276 class of recipient algorithm being used. For: 1278 No Recipients: The key to be used is determined by the algorithm 1279 and key at the current layer. Examples are key transport keys 1280 Section 12.3, key wrap keys Section 12.2.1 or pre-shared 1281 secrets. 1283 Direct Encryption and Direct Key Agreement: The key is 1284 determined by the key and algorithm in the recipient 1285 structure. The encryption algorithm and size of the key to be 1286 used are inputs into the KDF used for the recipient. (For 1287 direct, the KDF can be thought of as the identity operation.) 1288 Examples of these algorithms are found in Section 12.1.2 and 1289 Section 12.4.1. 1291 Other: The key is randomly generated. 1293 4. Call the encryption algorithm with K (the encryption key to use) 1294 and the P (the plain text). Place the returned cipher text into 1295 the 'ciphertext' field of the structure. 1297 5. For recipients of the message, recursively perform the encryption 1298 algorithm for that recipient, using K (the encryption key) as the 1299 plain text. 1301 How to decrypt a message: 1303 1. Verify that the 'protected' field is empty. 1305 2. Verify that there was no external additional authenticated data 1306 supplied for this operation. 1308 3. Determine the decryption key. This step is dependent on the 1309 class of recipient algorithm being used. For: 1311 No Recipients: The key to be used is determined by the algorithm 1312 and key at the current layer. Examples are key transport keys 1313 Section 12.3, key wrap keys Section 12.2.1 or pre-shared 1314 secrets. 1316 Direct Encryption and Direct Key Agreement: The key is 1317 determined by the key and algorithm in the recipient 1318 structure. The encryption algorithm and size of the key to be 1319 used are inputs into the KDF used for the recipient. (For 1320 direct, the KDF can be thought of as the identity operation.) 1321 Examples of these algorithms are found in Section 12.1.2 and 1322 Section 12.4.1. 1324 Other: The key is determined by decoding and decrypting one of 1325 the recipient structures. 1327 4. Call the decryption algorithm with K (the decryption key to use), 1328 and C (the cipher text). 1330 6. MAC Objects 1332 COSE supports two different MAC structures. COSE_MAC0 is used when a 1333 recipient structure is not needed because the key to be used is 1334 implicitly known. COSE_MAC is used for all other cases. These 1335 include a requirement for multiple recipients, the key being unknown, 1336 and a recipient algorithm of other than direct. 1338 In this section, we describe the structure and methods to be used 1339 when doing MAC authentication in COSE. This document allows for the 1340 use of all of the same classes of recipient algorithms as are allowed 1341 for encryption. 1343 When using MAC operations, there are two modes in which they can be 1344 used. The first is just a check that the content has not been 1345 changed since the MAC was computed. Any class of recipient algorithm 1346 can be used for this purpose. The second mode is to both check that 1347 the content has not been changed since the MAC was computed, and to 1348 use the recipient algorithm to verify who sent it. The classes of 1349 recipient algorithms that support this are those that use a pre- 1350 shared secret or do static-static key agreement (without the key wrap 1351 step). In both of these cases, the entity that created and sent the 1352 message MAC can be validated. (This knowledge of sender assumes that 1353 there are only two parties involved and you did not send the message 1354 to yourself.) The origination property can be obtained with both of 1355 the MAC message structures. 1357 6.1. MACed Message with Recipients 1359 The multiple recipient MACed message uses two structures, the 1360 COSE_Mac structure defined in this section for carrying the body and 1361 the COSE_recipient structure (Section 5.1) to hold the key used for 1362 the MAC computation. Examples of MACed messages can be found in 1363 Appendix C.5. 1365 The MAC structure can be encoded either tagged or untagged depending 1366 on the context it will be used in. A tagged COSE_Mac structure is 1367 identified by the CBOR tag TBD4. The CDDL fragment that represents 1368 this is: 1370 COSE_Mac_Tagged = #6.97(COSE_Mac) 1372 The COSE_Mac structure is a CBOR array. The fields of the array in 1373 order are: 1375 protected as described in Section 3. 1377 unprotected as described in Section 3. 1379 payload contains the serialized content to be MACed. If the payload 1380 is not present in the message, the application is required to 1381 supply the payload separately. The payload is wrapped in a bstr 1382 to ensure that it is transported without changes. If the payload 1383 is transported separately (i.e., detached content), then a nil 1384 CBOR value is placed in this location and it is the responsibility 1385 of the application to ensure that it will be transported without 1386 changes. 1388 tag contains the MAC value. 1390 recipients as described in Section 5.1. 1392 The CDDL fragment that represents the above text for COSE_Mac 1393 follows. 1395 COSE_Mac = [ 1396 Headers, 1397 payload : bstr / nil, 1398 tag : bstr, 1399 recipients :[+COSE_recipient] 1400 ] 1402 6.2. MACed Messages with Implicit Key 1404 In this section, we describe the structure and methods to be used 1405 when doing MAC authentication for those cases where the recipient is 1406 implicitly known. 1408 The MACed message uses the COSE_Mac0 structure defined in this 1409 section for carrying the body. Examples of MACed messages with an 1410 implicit key can be found in Appendix C.6. 1412 The MAC structure can be encoded either tagged or untagged depending 1413 on the context it will be used in. A tagged COSE_Mac0 structure is 1414 identified by the CBOR tag TBD6. The CDDL fragment that represents 1415 this is: 1417 COSE_Mac0_Tagged = #6.17(COSE_Mac0) 1419 The COSE_Mac0 structure is a CBOR array. The fields of the array in 1420 order are: 1422 protected as described in Section 3. 1424 unprotected as described in Section 3. 1426 payload as described in Section 6.1. 1428 tag contains the MAC value. 1430 The CDDL fragment that corresponds to the above text is: 1432 COSE_Mac0 = [ 1433 Headers, 1434 payload : bstr / nil, 1435 tag : bstr, 1436 ] 1438 6.3. How to compute and verify a MAC 1440 In order to get a consistent encoding of the data to be 1441 authenticated, the MAC_structure is used to have a canonical form. 1442 The MAC_structure is a CBOR array. The fields of the MAC_structure 1443 in order are: 1445 1. A text string that identifies the structure that is being 1446 encoded. This string is "MAC" for the COSE_Mac structure. This 1447 string is "MAC0" for the COSE_Mac0 structure. 1449 2. The protected attributes from the COSE_MAC structure. If there 1450 are no protected attributes, a zero length bstr is used. 1452 3. The protected attributes from the application encoded as a bstr 1453 type. If this field is not supplied, it defaults to a zero 1454 length binary string. (See Section 4.3 for application guidance 1455 on constructing this field.) 1457 4. The payload to be MAC-ed encoded in a bstr type. The payload is 1458 placed here independent of how it is transported. 1460 The CDDL fragment that corresponds to the above text is: 1462 MAC_structure = [ 1463 context : "MAC" / "MAC0", 1464 protected : empty_or_serialized_map, 1465 external_aad : bstr, 1466 payload : bstr 1467 ] 1469 The steps to compute a MAC are: 1471 1. Create a MAC_structure and populate it with the appropriate 1472 fields. 1474 2. Create the value ToBeMaced by encoding the MAC_structure to a 1475 byte stream, using the encoding described in Section 14. 1477 3. Call the MAC creation algorithm passing in K (the key to use), 1478 alg (the algorithm to MAC with) and ToBeMaced (the value to 1479 compute the MAC on). 1481 4. Place the resulting MAC in the 'tag' field of the COSE_Mac or 1482 COSE_Mac0 structure. 1484 5. Encrypt and encode the MAC key for each recipient of the message. 1486 The steps to verify a MAC are: 1488 1. Create a MAC_structure object and populate it with the 1489 appropriate fields. 1491 2. Create the value ToBeMaced by encoding the MAC_structure to a 1492 byte stream, using the encoding described in Section 14. 1494 3. Obtain the cryptographic key from one of the recipients of the 1495 message. 1497 4. Call the MAC creation algorithm passing in K (the key to use), 1498 alg (the algorithm to MAC with) and ToBeMaced (the value to 1499 compute the MAC on). 1501 5. Compare the MAC value to the 'tag' field of the COSE_Mac or 1502 COSE_Mac0 structure. 1504 7. Key Objects 1506 A COSE Key structure is built on a CBOR map object. The set of 1507 common parameters that can appear in a COSE Key can be found in the 1508 IANA "COSE Key Common Parameters" registry (Section 16.5). 1509 Additional parameters defined for specific key types can be found in 1510 the IANA "COSE Key Type Parameters" registry (Section 16.6). 1512 A COSE Key Set uses a CBOR array object as its underlying type. The 1513 values of the array elements are COSE Keys. A Key Set MUST have at 1514 least one element in the array. Examples of Key Sets can be found in 1515 Appendix C.7. 1517 Each element in a key set MUST be processed independently. If one 1518 element in a key set is either malformed or uses a key that is not 1519 understood by an application, that key is ignored and the other keys 1520 are processed normally. 1522 The element "kty" is a required element in a COSE_Key map. 1524 The CDDL grammar describing COSE_Key and COSE_KeySet is: 1526 COSE_Key = { 1527 1 => tstr / int, ; kty 1528 ? 2 => bstr, ; kid 1529 ? 3 => tstr / int, ; alg 1530 ? 4 => [+ (tstr / int) ], ; key_ops 1531 ? 5 => bstr, ; Base IV 1532 * label => values 1533 } 1535 COSE_KeySet = [+COSE_Key] 1537 7.1. COSE Key Common Parameters 1539 This document defines a set of common parameters for a COSE Key 1540 object. Table 3 provides a summary of the parameters defined in this 1541 section. There are also parameters that are defined for specific key 1542 types. Key type specific parameters can be found in Section 13. 1544 +---------+-------+----------------+------------+-------------------+ 1545 | name | label | CBOR type | registry | description | 1546 +---------+-------+----------------+------------+-------------------+ 1547 | kty | 1 | tstr / int | COSE Key | Identification of | 1548 | | | | Common | the key type | 1549 | | | | Parameters | | 1550 | | | | | | 1551 | alg | 3 | tstr / int | COSE | Key usage | 1552 | | | | Algorithm | restriction to | 1553 | | | | Values | this algorithm | 1554 | | | | | | 1555 | kid | 2 | bstr | | Key | 1556 | | | | | Identification | 1557 | | | | | value - match to | 1558 | | | | | kid in message | 1559 | | | | | | 1560 | key_ops | 4 | [+ (tstr/int)] | | Restrict set of | 1561 | | | | | permissible | 1562 | | | | | operations | 1563 | | | | | | 1564 | Base IV | 5 | bstr | | Base IV to be | 1565 | | | | | xor-ed with | 1566 | | | | | Partial IVs | 1567 +---------+-------+----------------+------------+-------------------+ 1569 Table 3: Key Map Labels 1571 kty: This parameter is used to identify the family of keys for this 1572 structure, and thus the set of key type specific parameters to be 1573 found. The set of values defined in this document can be found in 1574 Table 21. This parameter MUST be present in a key object. 1575 Implementations MUST verify that the key type is appropriate for 1576 the algorithm being processed. The key type MUST be included as 1577 part of the trust decision process. 1579 alg: This parameter is used to restrict the algorithm that is used 1580 with the key. If this parameter is present in the key structure, 1581 the application MUST verify that this algorithm matches the 1582 algorithm for which the key is being used. If the algorithms do 1583 not match, then this key object MUST NOT be used to perform the 1584 cryptographic operation. Note that the same key can be in a 1585 different key structure with a different or no algorithm 1586 specified, however this is considered to be a poor security 1587 practice. 1589 kid: This parameter is used to give an identifier for a key. The 1590 identifier is not structured and can be anything from a user 1591 provided string to a value computed on the public portion of the 1592 key. This field is intended for matching against a 'kid' 1593 parameter in a message in order to filter down the set of keys 1594 that need to be checked. 1596 key_ops: This parameter is defined to restrict the set of operations 1597 that a key is to be used for. The value of the field is an array 1598 of values from Table 4. Algorithms define the values of key ops 1599 that are permitted to appear and are required for specific 1600 operations. The set of values matches that in [RFC7517] and 1601 [W3C.WebCrypto]. 1603 Base IV: This parameter is defined to carry the base portion of an 1604 IV. It is designed to be used with the partial IV header 1605 parameter defined in Section 3.1. This field provides the ability 1606 to associate a partial IV with a key that is then modified on a 1607 per message basis with the partial IV. 1609 Extreme care needs to be taken when using a Base IV in an 1610 application. Many encryption algorithms lose security if the same 1611 IV is used twice. 1613 If different keys are derived for each sender, using the same base 1614 IV with partial IVs starting at zero is likely to ensure that the 1615 IV would not be used twice for a single key. If different keys 1616 are derived for each sender, starting at the same base IV is 1617 likely to satisfy this condition. If the same key is used for 1618 multiple senders, then the application needs to provide for a 1619 method of dividing the IV space up between the senders. This 1620 could be done by providing a different base point to start from or 1621 a different partial IV to start with and restricting the number of 1622 messages to be sent before re-keying. 1624 +---------+-------+-------------------------------------------------+ 1625 | name | value | description | 1626 +---------+-------+-------------------------------------------------+ 1627 | sign | 1 | The key is used to create signatures. Requires | 1628 | | | private key fields. | 1629 | | | | 1630 | verify | 2 | The key is used for verification of signatures. | 1631 | | | | 1632 | encrypt | 3 | The key is used for key transport encryption. | 1633 | | | | 1634 | decrypt | 4 | The key is used for key transport decryption. | 1635 | | | Requires private key fields. | 1636 | | | | 1637 | wrap | 5 | The key is used for key wrapping. | 1638 | key | | | 1639 | | | | 1640 | unwrap | 6 | The key is used for key unwrapping. Requires | 1641 | key | | private key fields. | 1642 | | | | 1643 | derive | 7 | The key is used for deriving keys. Requires | 1644 | key | | private key fields. | 1645 | | | | 1646 | derive | 8 | The key is used for deriving bits not to be | 1647 | bits | | used as a key. Requires private key fields. | 1648 | | | | 1649 | MAC | 9 | The key is used for creating MACs. | 1650 | create | | | 1651 | | | | 1652 | MAC | 10 | The key is used for validating MACs. | 1653 | verify | | | 1654 +---------+-------+-------------------------------------------------+ 1656 Table 4: Key Operation Values 1658 8. Signature Algorithms 1660 There are two signature algorithm schemes. The first is signature 1661 with appendix. In this scheme, the message content is processed and 1662 a signature is produced, the signature is called the appendix. This 1663 is the scheme used by algorithms such as ECDSA and RSASSA-PSS. (In 1664 fact the SSA in RSASSA-PSS stands for Signature Scheme with 1665 Appendix.) 1667 The signature functions for this scheme are: 1669 signature = Sign(message content, key) 1671 valid = Verification(message content, key, signature) 1672 The second scheme is signature with message recovery. (An example of 1673 such an algorithm is [PVSig].) In this scheme, the message content 1674 is processed, but part of it is included in the signature. Moving 1675 bytes of the message content into the signature allows for smaller 1676 signatures, the signature size is still potentially large, but the 1677 message content has shrunk. This has implications for systems 1678 implementing these algorithms and for applications that use them. 1679 The first is that the message content is not fully available until 1680 after a signature has been validated. Until that point the part of 1681 the message contained inside of the signature is unrecoverable. The 1682 second is that the security analysis of the strength of the signature 1683 is very much based on the structure of the message content. Messages 1684 that are highly predictable require additional randomness to be 1685 supplied as part of the signature process. In the worst case, it 1686 becomes the same as doing a signature with appendix. Finally, in the 1687 event that multiple signatures are applied to a message, all of the 1688 signature algorithms are going to be required to consume the same 1689 number of bytes of message content. This means that mixing of the 1690 different schemes in a single message is not supported, and if a 1691 recovery signature scheme is used, then the same amount of content 1692 needs to be consumed by all of the signatures. 1694 The signature functions for this scheme are: 1696 signature, message sent = Sign(message content, key) 1698 valid, message content = Verification(message sent, key, signature) 1700 Signature algorithms are used with the COSE_Signature and COSE_Sign1 1701 structures. At this time, only signatures with appendixes are 1702 defined for use with COSE, however considerable interest has been 1703 expressed in using a signature with message recovery algorithm due to 1704 the effective size reduction that is possible. Implementations will 1705 need to keep this in mind for later possible integration. 1707 8.1. ECDSA 1709 ECDSA [DSS] defines a signature algorithm using ECC. Implementations 1710 SHOULD use a deterministic version of ECDSA such as the one defined 1711 in [RFC6979]. The use of a deterministic signature algorithms allows 1712 for systems to avoid relying on random number generators in order to 1713 avoid generating the same value of 'k' (the per-message random 1714 value). Biased generation of the value be attacked and collisions 1715 will lead to leaked keys. It additionally allows for doing 1716 deterministic tests for the signature algorithm. The use of 1717 deterministic ECDSA does not lessen the need to to have good random 1718 number generation when creating the private key. 1720 The ECDSA signature algorithm is parameterized with a hash function 1721 (h). In the event that the length of the hash function output is 1722 greater than the group of the key, the left-most bytes of the hash 1723 output are used. 1725 The algorithms defined in this document can be found in Table 5. 1727 +-------+-------+---------+------------------+ 1728 | name | value | hash | description | 1729 +-------+-------+---------+------------------+ 1730 | ES256 | -7 | SHA-256 | ECDSA w/ SHA-256 | 1731 | | | | | 1732 | ES384 | -35 | SHA-384 | ECDSA w/ SHA-384 | 1733 | | | | | 1734 | ES512 | -36 | SHA-512 | ECDSA w/ SHA-512 | 1735 +-------+-------+---------+------------------+ 1737 Table 5: ECDSA Algorithm Values 1739 This document defines ECDSA to work only with the curves P-256, P-384 1740 and P-521. This document requires that the curves be encoded using 1741 the 'EC2' (2 coordinate Elliptic Curve) key type. Implementations 1742 need to check that the key type and curve are correct when creating 1743 and verifying a signature. Other documents can define it to work 1744 with other curves and points in the future. 1746 In order to promote interoperability, it is suggested that SHA-256 be 1747 used only with curve P-256, SHA-384 be used only with curve P-384 and 1748 SHA-512 be used with curve P-521. This is aligned with the 1749 recommendation in Section 4 of [RFC5480]. 1751 The signature algorithm results in a pair of integers (R, S). These 1752 integers will the same length as length of the key used for the 1753 signature process. The signature is encoded by converting the 1754 integers into byte strings of the same length as the key size. The 1755 length is rounded up to the nearest byte and is left padded with zero 1756 bits to get to the correct length. The two integers are then 1757 concatenated together to form a byte string that is the resulting 1758 signature. 1760 Using the function defined in [I-D.moriarty-pkcs1] the signature is: 1761 Signature = I2OSP(R, n) | I2OSP(S, n) 1762 where n = ceiling(key_length / 8) 1764 When using a COSE key for this algorithm, the following checks are 1765 made: 1767 o The 'kty' field MUST be present and it MUST be 'EC2'. 1769 o If the 'alg' field is present, it MUST match the ECDSA signature 1770 algorithm being used. 1772 o If the 'key_ops' field is present, it MUST include 'sign' when 1773 creating an ECDSA signature. 1775 o If the 'key_ops' field is present, it MUST include 'verify' when 1776 verifying an ECDSA signature. 1778 8.1.1. Security Considerations 1780 The security strength of the signature is no greater than the minimum 1781 of the security strength associated with the bit length of the key 1782 and the security strength of the hash function. 1784 Note: Use of this technique is a good idea even when good random 1785 number generation exists. Doing so both reduces the possibility of 1786 having the same value of 'k' in two signature operations and allows 1787 for reproducible signature values, which helps testing. 1789 There are two substitution attacks that can theoretically be mounted 1790 against the ECDSA signature algorithm. 1792 o Changing the curve used to validate the signature: If one changes 1793 the curve used to validate the signature, then potentially one 1794 could have a two messages with the same signature each computed 1795 under a different curve. The only requirement on the new curve is 1796 that its order be the same as the old one and it be acceptable to 1797 the client. An example would be to change from using the curve 1798 secp256r1 (aka P-256) to using secp256k1. (Both are 256 bit 1799 curves.) We current do not have any way to deal with this version 1800 of the attack except to restrict the overall set of curves that 1801 can be used. 1803 o Change the hash function used to validate the signature: If one 1804 has either two different hash functions of the same length, or one 1805 can truncate a hash function down, then one could potentially find 1806 collisions between the hash functions rather than within a single 1807 hash function. (For example, truncating SHA-512 to 256 bits might 1808 collide with a SHA-256 bit hash value.) As the hash algorithm is 1809 part of the signature algorithm identifier, this attack is 1810 mitigated by including signature algorithm identifier in the 1811 protected header. 1813 8.2. Edwards-curve Digital Signature Algorithms (EdDSA) 1815 [I-D.irtf-cfrg-eddsa] describes the elliptic curve signature scheme 1816 Edwards-curve Digital Signature Algorithm (EdDSA). In that document, 1817 the signature algorithm is instantiated using parameters for 1818 edwards25519 and edwards448 curves. The document additionally 1819 describes two variants of the EdDSA algorithm: Pure EdDSA, where no 1820 hash function is applied to the content before signing and, HashEdDSA 1821 where a hash function is applied to the content before signing and 1822 the result of that hash function is signed. For the EdDSA, the 1823 content to be signed (either the message or the pre-hash value) is 1824 processed twice inside of the signature algorithm. For use with 1825 COSE, only the pure EdDSA version is used. This is because it is not 1826 expected that extremely large contents are going to be needed and, 1827 based on the arrangement of the message structure, the entire message 1828 is going to need to be held in memory in order to create or verify a 1829 signature. This means that there does not appear to be a need to be 1830 able to do block updates of the hash, followed by eliminating the 1831 message from memory. Applications can provide the same features by 1832 defining the content of the message as a hash value and transporting 1833 the COSE object (with the hash value) and the content as separate 1834 items. 1836 The algorithms defined in this document can be found in Table 6. A 1837 single signature algorithm is defined, which can be used for multiple 1838 curves. 1840 +-------+-------+-------------+ 1841 | name | value | description | 1842 +-------+-------+-------------+ 1843 | EdDSA | -8 | EdDSA | 1844 +-------+-------+-------------+ 1846 Table 6: EdDSA Algorithm Values 1848 [I-D.irtf-cfrg-eddsa] describes the method of encoding the signature 1849 value. 1851 When using a COSE key for this algorithm the following checks are 1852 made: 1854 o The 'kty' field MUST be present and it MUST be 'OKP' (Octet Key 1855 Pair). 1857 o The 'crv' field MUST be present, and it MUST be a curve defined 1858 for this signature algorithm. 1860 o If the 'alg' field is present, it MUST match 'EdDSA'. 1862 o If the 'key_ops' field is present, it MUST include 'sign' when 1863 creating an EdDSA signature. 1865 o If the 'key_ops' field is present, it MUST include 'verify' when 1866 verifying an EdDSA signature. 1868 8.2.1. Security Considerations 1870 How public values are computed is not the same when looking at EdDSA 1871 and ECDH, for this reason they should not be used with the other 1872 algorithm. 1874 If batch signature verification is performed, a well-seeded 1875 cryptographic random number generator is REQUIRED. Signing and non- 1876 batch signature verification are deterministic operations and do not 1877 need random numbers of any kind. 1879 9. Message Authentication (MAC) Algorithms 1881 Message Authentication Codes (MACs) provide data authentication and 1882 integrity protection. They provide either no or very limited data 1883 origination. A MAC, for example, be used to prove the identity of 1884 the sender to a third party. 1886 MACs use the same scheme as signature with appendix algorithms. The 1887 message content is processed and an authentication code is produced. 1888 The authentication code is frequently called a tag. 1890 The MAC functions are: 1892 tag = MAC_Create(message content, key) 1894 valid = MAC_Verify(message content, key, tag) 1896 MAC algorithms can be based on either a block cipher algorithm (i.e., 1897 AES-MAC) or a hash algorithm (i.e., HMAC). This document defines a 1898 MAC algorithm using each of these constructions. 1900 MAC algorithms are used in the COSE_Mac and COSE_Mac0 structures. 1902 9.1. Hash-based Message Authentication Codes (HMAC) 1904 The Hash-based Message Authentication Code algorithm (HMAC) 1905 [RFC2104][RFC4231] was designed to deal with length extension 1906 attacks. The algorithm was also designed to allow for new hash 1907 algorithms to be directly plugged in without changes to the hash 1908 function. The HMAC design process has been shown as solid since, 1909 while the security of hash algorithms such as MD5 has decreased over 1910 time, the security of HMAC combined with MD5 has not yet been shown 1911 to be compromised [RFC6151]. 1913 The HMAC algorithm is parameterized by an inner and outer padding, a 1914 hash function (h), and an authentication tag value length. For this 1915 specification, the inner and outer padding are fixed to the values 1916 set in [RFC2104]. The length of the authentication tag corresponds 1917 to the difficulty of producing a forgery. For use in constrained 1918 environments, we define a set of HMAC algorithms that are truncated. 1919 There are currently no known issues with truncation, however the 1920 security strength of the message tag is correspondingly reduced in 1921 strength. When truncating, the left-most tag length bits are kept 1922 and transmitted. 1924 The algorithms defined in this document can be found in Table 7. 1926 +-----------+-------+---------+----------+--------------------------+ 1927 | name | value | Hash | Tag | description | 1928 | | | | Length | | 1929 +-----------+-------+---------+----------+--------------------------+ 1930 | HMAC | 4 | SHA-256 | 64 | HMAC w/ SHA-256 | 1931 | 256/64 | | | | truncated to 64 bits | 1932 | | | | | | 1933 | HMAC | 5 | SHA-256 | 256 | HMAC w/ SHA-256 | 1934 | 256/256 | | | | | 1935 | | | | | | 1936 | HMAC | 6 | SHA-384 | 384 | HMAC w/ SHA-384 | 1937 | 384/384 | | | | | 1938 | | | | | | 1939 | HMAC | 7 | SHA-512 | 512 | HMAC w/ SHA-512 | 1940 | 512/512 | | | | | 1941 +-----------+-------+---------+----------+--------------------------+ 1943 Table 7: HMAC Algorithm Values 1945 Some recipient algorithms carry the key while others derive a key 1946 from secret data. For those algorithms that carry the key (such as 1947 AES-KeyWrap), the size of the HMAC key SHOULD be the same size as the 1948 underlying hash function. For those algorithms that derive the key 1949 (such as ECDH), the derived key MUST be the same size as the 1950 underlying hash function. 1952 When using a COSE key for this algorithm, the following checks are 1953 made: 1955 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 1957 o If the 'alg' field is present, it MUST match the HMAC algorithm 1958 being used. 1960 o If the 'key_ops' field is present, it MUST include 'MAC create' 1961 when creating an HMAC authentication tag. 1963 o If the 'key_ops' field is present, it MUST include 'MAC verify' 1964 when verifying an HMAC authentication tag. 1966 Implementations creating and validating MAC values MUST validate that 1967 the key type, key length, and algorithm are correct and appropriate 1968 for the entities involved. 1970 9.1.1. Security Considerations 1972 HMAC has proved to be resistant to attack even when used with 1973 weakened hash algorithms. The current best known attack appears is 1974 to brute force the key. This means that key size is going to be 1975 directly related to the security of an HMAC operation. 1977 9.2. AES Message Authentication Code (AES-CBC-MAC) 1979 AES-CBC-MAC is defined in [MAC]. (Note this is not the same 1980 algorithm as AES-CMAC [RFC4493]). 1982 AES-CBC-MAC is parameterized by the key length, the authentication 1983 tag length and the IV used. For all of these algorithms, the IV is 1984 fixed to all zeros. We provide an array of algorithms for various 1985 key lengths and tag lengths. The algorithms defined in this document 1986 are found in Table 8. 1988 +-------------+-------+----------+----------+-----------------------+ 1989 | name | value | key | tag | description | 1990 | | | length | length | | 1991 +-------------+-------+----------+----------+-----------------------+ 1992 | AES-MAC | 14 | 128 | 64 | AES-MAC 128 bit key, | 1993 | 128/64 | | | | 64-bit tag | 1994 | | | | | | 1995 | AES-MAC | 15 | 256 | 64 | AES-MAC 256 bit key, | 1996 | 256/64 | | | | 64-bit tag | 1997 | | | | | | 1998 | AES-MAC | 25 | 128 | 128 | AES-MAC 128 bit key, | 1999 | 128/128 | | | | 128-bit tag | 2000 | | | | | | 2001 | AES-MAC | 26 | 256 | 128 | AES-MAC 256 bit key, | 2002 | 256/128 | | | | 128-bit tag | 2003 +-------------+-------+----------+----------+-----------------------+ 2005 Table 8: AES-MAC Algorithm Values 2007 Keys may be obtained either from a key structure or from a recipient 2008 structure. Implementations creating and validating MAC values MUST 2009 validate that the key type, key length and algorithm are correct and 2010 appropriate for the entities involved. 2012 When using a COSE key for this algorithm, the following checks are 2013 made: 2015 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2017 o If the 'alg' field is present, it MUST match the AES-MAC algorithm 2018 being used. 2020 o If the 'key_ops' field is present, it MUST include 'MAC create' 2021 when creating an AES-MAC authentication tag. 2023 o If the 'key_ops' field is present, it MUST include 'MAC verify' 2024 when verifying an AES-MAC authentication tag. 2026 9.2.1. Security Considerations 2028 A number of attacks exist against CBC-MAC that need to be considered. 2029 - 2031 o A single key must only be used for messages of a fixed and known 2032 length. If this is not the case, an attacker will be able to 2033 generate a message with a valid tag given two message and tag 2034 pairs. This can be addressed by using different keys for 2035 different length messages. The current structure mitigates this 2036 problem, as a specific encoding structure that includes lengths is 2037 built and signed. (CMAC also addresses this issue.) 2039 o When using CBC mode, if the same key is used for both encryption 2040 and authentication operations, an attacker can produce messages 2041 with a valid authentication code. 2043 o If the IV can be modified, then messages can be forged. This is 2044 addressed by fixing the IV to all zeros. 2046 10. Content Encryption Algorithms 2048 Content Encryption Algorithms provide data confidentiality for 2049 potentially large blocks of data using a symmetric key. They provide 2050 integrity on the data that was encrypted, however they provide either 2051 no or very limited data origination. (One cannot, for example, be 2052 used to prove the identity of the sender to a third party.) The 2053 ability to provide data origination is linked to how the CEK is 2054 obtained. 2056 COSE restricts the set of legal content encryption algorithms to 2057 those that support authentication both of the content and additional 2058 data. The encryption process will generate some type of 2059 authentication value, but that value may be either explicit or 2060 implicit in terms of the algorithm definition. For simplicity sake, 2061 the authentication code will normally be defined as being appended to 2062 the cipher text stream. The encryption functions are: 2064 ciphertext = Encrypt(message content, key, additional data) 2066 valid, message content = Decrypt(cipher text, key, additional data) 2068 Most AEAD algorithms are logically defined as returning the message 2069 content only if the decryption is valid. Many but not all 2070 implementations will follow this convention. The message content 2071 MUST NOT be used if the decryption does not validate. 2073 These algorithms are used in COSE_Encrypt and COSE_Encrypt0. 2075 10.1. AES GCM 2077 The GCM mode is a generic authenticated encryption block cipher mode 2078 defined in [AES-GCM]. The GCM mode is combined with the AES block 2079 encryption algorithm to define an AEAD cipher. 2081 The GCM mode is parameterized by the size of the authentication tag 2082 and the size of the nonce. This document fixes the size of the nonce 2083 at 96 bits. The size of the authentication tag is limited to a small 2084 set of values. For this document however, the size of the 2085 authentication tag is fixed at 128 bits. 2087 The set of algorithms defined in this document are in Table 9. 2089 +---------+-------+------------------------------------------+ 2090 | name | value | description | 2091 +---------+-------+------------------------------------------+ 2092 | A128GCM | 1 | AES-GCM mode w/ 128-bit key, 128-bit tag | 2093 | | | | 2094 | A192GCM | 2 | AES-GCM mode w/ 192-bit key, 128-bit tag | 2095 | | | | 2096 | A256GCM | 3 | AES-GCM mode w/ 256-bit key, 128-bit tag | 2097 +---------+-------+------------------------------------------+ 2099 Table 9: Algorithm Value for AES-GCM 2101 Keys may be obtained either from a key structure or from a recipient 2102 structure. Implementations encrypting and decrypting MUST validate 2103 that the key type, key length and algorithm are correct and 2104 appropriate for the entities involved. 2106 When using a COSE key for this algorithm, the following checks are 2107 made: 2109 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2111 o If the 'alg' field is present, it MUST match the AES-GCM algorithm 2112 being used. 2114 o If the 'key_ops' field is present, it MUST include 'encrypt' or 2115 'wrap key' when encrypting. 2117 o If the 'key_ops' field is present, it MUST include 'decrypt' or 2118 'unwrap key' when decrypting. 2120 10.1.1. Security Considerations 2122 When using AES-GCM, the following restrictions MUST be enforced: 2124 o The key and nonce pair MUST be unique for every message encrypted. 2126 o The total amount of data encrypted for a single key MUST NOT 2127 exceed 2^39 - 256 bits. An explicit check is required only in 2128 environments where it is expected that it might be exceeded. 2130 Consideration was given to supporting smaller tag values; the 2131 constrained community would desire tag sizes in the 64-bit range. 2133 Doing so drastically changes both the maximum messages size 2134 (generally not an issue) and the number of times that a key can be 2135 used. Given that CCM is the usual mode for constrained environments, 2136 restricted modes are not supported. 2138 10.2. AES CCM 2140 Counter with CBC-MAC (CCM) is a generic authentication encryption 2141 block cipher mode defined in [RFC3610]. The CCM mode is combined 2142 with the AES block encryption algorithm to define a commonly used 2143 content encryption algorithm used in constrained devices. 2145 The CCM mode has two parameter choices. The first choice is M, the 2146 size of the authentication field. The choice of the value for M 2147 involves a trade-off between message growth (from the tag) and the 2148 probably that an attacker can undetectably modify a message. The 2149 second choice is L, the size of the length field. This value 2150 requires a trade-off between the maximum message size and the size of 2151 the Nonce. 2153 It is unfortunate that the specification for CCM specified L and M as 2154 a count of bytes rather than a count of bits. This leads to possible 2155 misunderstandings where AES-CCM-8 is frequently used to refer to a 2156 version of CCM mode where the size of the authentication is 64 bits 2157 and not 8 bits. These values have traditionally been specified as 2158 bit counts rather than byte counts. This document will follow the 2159 convention of using bit counts so that it is easier to compare the 2160 different algorithms presented in this document. 2162 We define a matrix of algorithms in this document over the values of 2163 L and M. Constrained devices are usually operating in situations 2164 where they use short messages and want to avoid doing recipient 2165 specific cryptographic operations. This favors smaller values of 2166 both L and M. Less constrained devices will want to be able to use 2167 larger messages and are more willing to generate new keys for every 2168 operation. This favors larger values of L and M. 2170 The following values are used for L: 2172 16 bits (2) limits messages to 2^16 bytes (64 KiB) in length. This 2173 is sufficiently long for messages in the constrained world. The 2174 nonce length is 13 bytes allowing for 2^(13*8) possible values of 2175 the nonce without repeating. 2177 64 bits (8) limits messages to 2^64 bytes in length. The nonce 2178 length is 7 bytes allowing for 2^56 possible values of the nonce 2179 without repeating. 2181 The following values are used for M: 2183 64 bits (8) produces a 64-bit authentication tag. This implies that 2184 there is a 1 in 2^64 chance that a modified message will 2185 authenticate. 2187 128 bits (16) produces a 128-bit authentication tag. This implies 2188 that there is a 1 in 2^128 chance that a modified message will 2189 authenticate. 2191 +--------------------+-------+----+-----+-----+---------------------+ 2192 | name | value | L | M | k | description | 2193 +--------------------+-------+----+-----+-----+---------------------+ 2194 | AES-CCM-16-64-128 | 10 | 16 | 64 | 128 | AES-CCM mode | 2195 | | | | | | 128-bit key, 64-bit | 2196 | | | | | | tag, 13-byte nonce | 2197 | | | | | | | 2198 | AES-CCM-16-64-256 | 11 | 16 | 64 | 256 | AES-CCM mode | 2199 | | | | | | 256-bit key, 64-bit | 2200 | | | | | | tag, 13-byte nonce | 2201 | | | | | | | 2202 | AES-CCM-64-64-128 | 12 | 64 | 64 | 128 | AES-CCM mode | 2203 | | | | | | 128-bit key, 64-bit | 2204 | | | | | | tag, 7-byte nonce | 2205 | | | | | | | 2206 | AES-CCM-64-64-256 | 13 | 64 | 64 | 256 | AES-CCM mode | 2207 | | | | | | 256-bit key, 64-bit | 2208 | | | | | | tag, 7-byte nonce | 2209 | | | | | | | 2210 | AES-CCM-16-128-128 | 30 | 16 | 128 | 128 | AES-CCM mode | 2211 | | | | | | 128-bit key, | 2212 | | | | | | 128-bit tag, | 2213 | | | | | | 13-byte nonce | 2214 | | | | | | | 2215 | AES-CCM-16-128-256 | 31 | 16 | 128 | 256 | AES-CCM mode | 2216 | | | | | | 256-bit key, | 2217 | | | | | | 128-bit tag, | 2218 | | | | | | 13-byte nonce | 2219 | | | | | | | 2220 | AES-CCM-64-128-128 | 32 | 64 | 128 | 128 | AES-CCM mode | 2221 | | | | | | 128-bit key, | 2222 | | | | | | 128-bit tag, 7-byte | 2223 | | | | | | nonce | 2224 | | | | | | | 2225 | AES-CCM-64-128-256 | 33 | 64 | 128 | 256 | AES-CCM mode | 2226 | | | | | | 256-bit key, | 2227 | | | | | | 128-bit tag, 7-byte | 2228 | | | | | | nonce | 2229 +--------------------+-------+----+-----+-----+---------------------+ 2231 Table 10: Algorithm Values for AES-CCM 2233 Keys may be obtained either from a key structure or from a recipient 2234 structure. Implementations encrypting and decrypting MUST validate 2235 that the key type, key length and algorithm are correct and 2236 appropriate for the entities involved. 2238 When using a COSE key for this algorithm, the following checks are 2239 made: 2241 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2243 o If the 'alg' field is present, it MUST match the AES-CCM algorithm 2244 being used. 2246 o If the 'key_ops' field is present, it MUST include 'encrypt' or 2247 'wrap key' when encrypting. 2249 o If the 'key_ops' field is present, it MUST include 'decrypt' or 2250 'unwrap key' when decrypting. 2252 10.2.1. Security Considerations 2254 When using AES-CCM, the following restrictions MUST be enforced: 2256 o The key and nonce pair MUST be unique for every message encrypted. 2257 Note that the value of L influences the number of unique nonces. 2259 o The total number of times the AES block cipher is used MUST NOT 2260 exceed 2^61 operations. This limitation is the sum of times the 2261 block cipher is used in computing the MAC value and in performing 2262 stream encryption operations. An explicit check is required only 2263 in environments where it is expected that it might be exceeded. 2265 [RFC3610] additionally calls out one other consideration of note. It 2266 is possible to do a pre-computation attack against the algorithm in 2267 cases where portions of the plaintext are highly predictable. This 2268 reduces the security of the key size by half. Ways to deal with this 2269 attack include adding a random portion to the nonce value and/or 2270 increasing the key size used. Using a portion of the nonce for a 2271 random value will decrease the number of messages that a single key 2272 can be used for. Increasing the key size may require more resources 2273 in the constrained device. See sections 5 and 10 of [RFC3610] for 2274 more information. 2276 10.3. ChaCha20 and Poly1305 2278 ChaCha20 and Poly1305 combined together is an AEAD mode that is 2279 defined in [RFC7539]. This is an algorithm defined to be a cipher 2280 that is not AES and thus would not suffer from any future weaknesses 2281 found in AES. These cryptographic functions are designed to be fast 2282 in software-only implementations. 2284 The ChaCha20/Poly1305 AEAD construction defined in [RFC7539] has no 2285 parameterization. It takes a 256-bit key and a 96-bit nonce, as well 2286 as the plain text and additional data as inputs and produces the 2287 cipher text as an option. We define one algorithm identifier for 2288 this algorithm in Table 11. 2290 +-------------------+-------+---------------------------------------+ 2291 | name | value | description | 2292 +-------------------+-------+---------------------------------------+ 2293 | ChaCha20/Poly1305 | 24 | ChaCha20/Poly1305 w/ 256-bit key, | 2294 | | | 128-bit tag | 2295 +-------------------+-------+---------------------------------------+ 2297 Table 11: Algorithm Value for AES-GCM 2299 Keys may be obtained either from a key structure or from a recipient 2300 structure. Implementations encrypting and decrypting MUST validate 2301 that the key type, key length and algorithm are correct and 2302 appropriate for the entities involved. 2304 When using a COSE key for this algorithm, the following checks are 2305 made: 2307 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2309 o If the 'alg' field is present, it MUST match the ChaCha20/Poly1305 2310 algorithm being used. 2312 o If the 'key_ops' field is present, it MUST include 'encrypt' or 2313 'wrap key' when encrypting. 2315 o If the 'key_ops' field is present, it MUST include 'decrypt' or 2316 'unwrap key' when decrypting. 2318 10.3.1. Security Considerations 2320 The pair of key, nonce MUST be unique for every invocation of the 2321 algorithm. Nonce counters are considered to be an acceptable way of 2322 ensuring that they are unique. 2324 11. Key Derivation Functions (KDF) 2326 Key Derivation Functions (KDFs) are used to take some secret value 2327 and generate a different one. The secret value comes in three 2328 flavors: 2330 o Secrets that are uniformly random: This is the type of secret that 2331 is created by a good random number generator. 2333 o Secrets that are not uniformly random: This is type of secret that 2334 is created by operations like key agreement. 2336 o Secrets that are not random: This is the type of secret that 2337 people generate for things like passwords. 2339 General KDF functions work well with the first type of secret, can do 2340 reasonably well with the second type of secret, and generally do 2341 poorly with the last type of secret. None of the KDF functions in 2342 this section are designed to deal with the type of secrets that are 2343 used for passwords. Functions like PBES2 [I-D.moriarty-pkcs5-v2dot1] 2344 need to be used for that type of secret. 2346 The same KDF function can be setup to deal with the first two types 2347 of secrets in a different way. The KDF function defined in 2348 Section 11.1 is such a function. This is reflected in the set of 2349 algorithms defined for HKDF. 2351 When using KDF functions, one component that is included is context 2352 information. Context information is used to allow for different 2353 keying information to be derived from the same secret. The use of 2354 context based keying material is considered to be a good security 2355 practice. 2357 This document defines a single context structure and a single KDF 2358 function. These elements are used for all of the recipient 2359 algorithms defined in this document that require a KDF process. 2360 These algorithms are defined in Section 12.1.2, Section 12.4.1, and 2361 Section 12.5.1. 2363 11.1. HMAC-based Extract-and-Expand Key Derivation Function (HKDF) 2365 The HKDF key derivation algorithm is defined in [RFC5869]. 2367 The HKDF algorithm takes these inputs: 2369 secret - a shared value that is secret. Secrets may be either 2370 previously shared or derived from operations like a DH key 2371 agreement. 2373 salt - an optional value that is used to change the generation 2374 process. The salt value can be either public or private. If the 2375 salt is public and carried in the message, then the 'salt' 2376 algorithm header parameter defined in Table 13 is used. While 2377 [RFC5869] suggests that the length of the salt be the same as the 2378 length of the underlying hash value, any amount of salt will 2379 improve the security as different key values will be generated. 2380 This parameter is protected by being included in the key 2381 computation and does not need to be separately authenticated. The 2382 salt value does not need to be unique for every message sent. 2384 length - the number of bytes of output that need to be generated. 2386 context information - Information that describes the context in 2387 which the resulting value will be used. Making this information 2388 specific to the context in which the material is going to be used 2389 ensures that the resulting material will always be tied to that 2390 usage. The context structure defined in Section 11.2 is used by 2391 the KDF functions in this document. 2393 PRF - The underlying pseudo-random function to be used in the HKDF 2394 algorithm. The PRF is encoded into the HKDF algorithm selection. 2396 HKDF is defined to use HMAC as the underlying PRF. However, it is 2397 possible to use other functions in the same construct to provide a 2398 different KDF function that is more appropriate in the constrained 2399 world. Specifically, one can use AES-CBC-MAC as the PRF for the 2400 expand step, but not for the extract step. When using a good random 2401 shared secret of the correct length, the extract step can be skipped. 2402 For the AES algorithm versions, the extract step is always skipped. 2404 The extract step cannot be skipped if the secret is not uniformly 2405 random, for example, if it is the result of an ECDH key agreement 2406 step. (This implies that the AES HKDF version cannot be used with 2407 ECDH.) If the extract step is skipped, the 'salt' value is not used 2408 as part of the HKDF functionality. 2410 The algorithms defined in this document are found in Table 12. 2412 +---------------+-----------------+---------------------------------+ 2413 | name | PRF | description | 2414 +---------------+-----------------+---------------------------------+ 2415 | HKDF SHA-256 | HMAC with | HKDF using HMAC SHA-256 as the | 2416 | | SHA-256 | PRF | 2417 | | | | 2418 | HKDF SHA-512 | HMAC with | HKDF using HMAC SHA-512 as the | 2419 | | SHA-512 | PRF | 2420 | | | | 2421 | HKDF AES- | AES-CBC-MAC-128 | HKDF using AES-MAC as the PRF | 2422 | MAC-128 | | w/ 128-bit key | 2423 | | | | 2424 | HKDF AES- | AES-CBC-MAC-256 | HKDF using AES-MAC as the PRF | 2425 | MAC-256 | | w/ 256-bit key | 2426 +---------------+-----------------+---------------------------------+ 2428 Table 12: HKDF algorithms 2430 +------+-------+------+-------------------------------+-------------+ 2431 | name | label | type | algorithm | description | 2432 +------+-------+------+-------------------------------+-------------+ 2433 | salt | -20 | bstr | direct+HKDF-SHA-256, direct | Random salt | 2434 | | | | +HKDF-SHA-512, direct+HKDF- | | 2435 | | | | AES-128, direct+HKDF-AES-256, | | 2436 | | | | ECDH-ES+HKDF-256, ECDH- | | 2437 | | | | ES+HKDF-512, ECDH- | | 2438 | | | | SS+HKDF-256, ECDH- | | 2439 | | | | SS+HKDF-512, ECDH-ES+A128KW, | | 2440 | | | | ECDH-ES+A192KW, ECDH- | | 2441 | | | | ES+A256KW, ECDH-SS+A128KW, | | 2442 | | | | ECDH-SS+A192KW, ECDH- | | 2443 | | | | SS+A256KW | | 2444 +------+-------+------+-------------------------------+-------------+ 2446 Table 13: HKDF Algorithm Parameters 2448 11.2. Context Information Structure 2450 The context information structure is used to ensure that the derived 2451 keying material is "bound" to the context of the transaction. The 2452 context information structure used here is based on that defined in 2453 [SP800-56A]. By using CBOR for the encoding of the context 2454 information structure, we automatically get the same type and length 2455 separation of fields that is obtained by the use of ASN.1. This 2456 means that there is no need to encode the lengths for the base 2457 elements as it is done by the encoding used in JOSE (Section 4.6.2 of 2458 [RFC7518]). 2460 The context information structure refers to PartyU and PartyV as the 2461 two parties that are doing the key derivation. Unless the 2462 application protocol defines differently, we assign PartyU to the 2463 entity that is creating the message and PartyV to the entity that is 2464 receiving the message. By doing this association, different keys 2465 will be derived for each direction as the context information is 2466 different in each direction. 2468 The context structure is built from information that is known to both 2469 entities. This information can be obtained from a variety of 2470 sources: 2472 o Fields can be defined by the application. This is commonly used 2473 to assign fixed names to parties, but can be used for other items 2474 such as nonces. 2476 o Fields can be defined by usage of the output. Examples of this 2477 are the algorithm and key size that are being generated. 2479 o Fields can be defined by parameters from the message. We define a 2480 set of parameters in Table 14 that can be used to carry the values 2481 associated with the context structure. Examples of this are 2482 identities and nonce values. These parameters are designed to be 2483 placed in the unprotected bucket of the recipient structure. 2484 (They do not need to be in the protected bucket since they already 2485 are included in the cryptographic computation by virtue of being 2486 included in the context structure.) 2488 +----------+-------+------+---------------------------+-------------+ 2489 | name | label | type | algorithm | description | 2490 +----------+-------+------+---------------------------+-------------+ 2491 | PartyU | -21 | bstr | direct+HKDF-SHA-256, | Party U | 2492 | identity | | | direct+HKDF-SHA-512, | identity | 2493 | | | | direct+HKDF-AES-128, | Information | 2494 | | | | direct+HKDF-AES-256, | | 2495 | | | | ECDH-ES+HKDF-256, ECDH- | | 2496 | | | | ES+HKDF-512, ECDH- | | 2497 | | | | SS+HKDF-256, ECDH- | | 2498 | | | | SS+HKDF-512, ECDH- | | 2499 | | | | ES+A128KW, ECDH- | | 2500 | | | | ES+A192KW, ECDH- | | 2501 | | | | ES+A256KW, ECDH- | | 2502 | | | | SS+A128KW, ECDH- | | 2503 | | | | SS+A192KW, ECDH-SS+A256KW | | 2504 | | | | | | 2505 | PartyU | -22 | bstr | direct+HKDF-SHA-256, | Party U | 2506 | nonce | | / | direct+HKDF-SHA-512, | provided | 2507 | | | int | direct+HKDF-AES-128, | nonce | 2508 | | | | direct+HKDF-AES-256, | | 2509 | | | | ECDH-ES+HKDF-256, ECDH- | | 2510 | | | | ES+HKDF-512, ECDH- | | 2511 | | | | SS+HKDF-256, ECDH- | | 2512 | | | | SS+HKDF-512, ECDH- | | 2513 | | | | ES+A128KW, ECDH- | | 2514 | | | | ES+A192KW, ECDH- | | 2515 | | | | ES+A256KW, ECDH- | | 2516 | | | | SS+A128KW, ECDH- | | 2517 | | | | SS+A192KW, ECDH-SS+A256KW | | 2518 | | | | | | 2519 | PartyU | -23 | bstr | direct+HKDF-SHA-256, | Party U | 2520 | other | | | direct+HKDF-SHA-512, | other | 2521 | | | | direct+HKDF-AES-128, | provided | 2522 | | | | direct+HKDF-AES-256, | information | 2523 | | | | ECDH-ES+HKDF-256, ECDH- | | 2524 | | | | ES+HKDF-512, ECDH- | | 2525 | | | | SS+HKDF-256, ECDH- | | 2526 | | | | SS+HKDF-512, ECDH- | | 2527 | | | | ES+A128KW, ECDH- | | 2528 | | | | ES+A192KW, ECDH- | | 2529 | | | | ES+A256KW, ECDH- | | 2530 | | | | SS+A128KW, ECDH- | | 2531 | | | | SS+A192KW, ECDH-SS+A256KW | | 2532 | | | | | | 2533 | PartyV | -24 | bstr | direct+HKDF-SHA-256, | Party V | 2534 | identity | | | direct+HKDF-SHA-512, | identity | 2535 | | | | direct+HKDF-AES-128, | Information | 2536 | | | | direct+HKDF-AES-256, | | 2537 | | | | ECDH-ES+HKDF-256, ECDH- | | 2538 | | | | ES+HKDF-512, ECDH- | | 2539 | | | | SS+HKDF-256, ECDH- | | 2540 | | | | SS+HKDF-512, ECDH- | | 2541 | | | | ES+A128KW, ECDH- | | 2542 | | | | ES+A192KW, ECDH- | | 2543 | | | | ES+A256KW, ECDH- | | 2544 | | | | SS+A128KW, ECDH- | | 2545 | | | | SS+A192KW, ECDH-SS+A256KW | | 2546 | | | | | | 2547 | PartyV | -25 | bstr | direct+HKDF-SHA-256, | Party V | 2548 | nonce | | / | direct+HKDF-SHA-512, | provided | 2549 | | | int | direct+HKDF-AES-128, | nonce | 2550 | | | | direct+HKDF-AES-256, | | 2551 | | | | ECDH-ES+HKDF-256, ECDH- | | 2552 | | | | ES+HKDF-512, ECDH- | | 2553 | | | | SS+HKDF-256, ECDH- | | 2554 | | | | SS+HKDF-512, ECDH- | | 2555 | | | | ES+A128KW, ECDH- | | 2556 | | | | ES+A192KW, ECDH- | | 2557 | | | | ES+A256KW, ECDH- | | 2558 | | | | SS+A128KW, ECDH- | | 2559 | | | | SS+A192KW, ECDH-SS+A256KW | | 2560 | | | | | | 2561 | PartyV | -26 | bstr | direct+HKDF-SHA-256, | Party V | 2562 | other | | | direct+HKDF-SHA-512, | other | 2563 | | | | direct+HKDF-AES-128, | provided | 2564 | | | | direct+HKDF-AES-256, | information | 2565 | | | | ECDH-ES+HKDF-256, ECDH- | | 2566 | | | | ES+HKDF-512, ECDH- | | 2567 | | | | SS+HKDF-256, ECDH- | | 2568 | | | | SS+HKDF-512, ECDH- | | 2569 | | | | ES+A128KW, ECDH- | | 2570 | | | | ES+A192KW, ECDH- | | 2571 | | | | ES+A256KW, ECDH- | | 2572 | | | | SS+A128KW, ECDH- | | 2573 | | | | SS+A192KW, ECDH-SS+A256KW | | 2574 +----------+-------+------+---------------------------+-------------+ 2575 Table 14: Context Algorithm Parameters 2577 We define a CBOR object to hold the context information. This object 2578 is referred to as COSE_KDF_Context. The object is based on a CBOR 2579 array type. The fields in the array are: 2581 AlgorithmID This field indicates the algorithm for which the key 2582 material will be used. This normally is either a Key Wrap 2583 algorithm identifier or a Content Encryption algorithm identifier. 2584 The values are from the "COSE Algorithm Value" registry. This 2585 field is required to be present. The field exists in the context 2586 information so that if the same environment is used for different 2587 algorithms, then completely different keys will be generated for 2588 each of those algorithms. (This practice means if algorithm A is 2589 broken and thus is easier to find, the key derived for algorithm B 2590 will not be the same as the key derived for algorithm A.) 2592 PartyUInfo This field holds information about party U. The 2593 PartyUInfo is encoded as a CBOR array. The elements of PartyUInfo 2594 are encoded in the order presented, however if the element does 2595 not exist no element is placed in the array. The elements of the 2596 PartyUInfo array are: 2598 identity This contains the identity information for party U. The 2599 identities can be assigned in one of two manners. Firstly, a 2600 protocol can assign identities based on roles. For example, 2601 the roles of "client" and "server" may be assigned to different 2602 entities in the protocol. Each entity would then use the 2603 correct label for the data they send or receive. The second 2604 way for a protocol to assign identities is to use a name based 2605 on a naming system (i.e., DNS, X.509 names). 2606 We define an algorithm parameter 'PartyU identity' that can be 2607 used to carry identity information in the message. However, 2608 identity information is often known as part of the protocol and 2609 can thus be inferred rather than made explicit. If identity 2610 information is carried in the message, applications SHOULD have 2611 a way of validating the supplied identity information. The 2612 identity information does not need to be specified and is set 2613 to nil in that case. 2615 nonce This contains a nonce value. The nonce can either be 2616 implicit from the protocol or carried as a value in the 2617 unprotected headers. 2618 We define an algorithm parameter 'PartyU nonce' that can be 2619 used to carry this value in the message However, the nonce 2620 value could be determined by the application and the value 2621 determined from elsewhere. 2623 This option does not need to be specified and is set to nil in 2624 that case 2626 other This contains other information that is defined by the 2627 protocol. 2628 This option does not need to be specified and is set to nil in 2629 that case 2631 PartyVInfo This field holds information about party V. The content 2632 of the structure are the same as for the PartyUInfo but for party 2633 V. 2635 SuppPubInfo This field contains public information that is mutually 2636 known to both parties. 2638 keyDataLength This is set to the number of bits of the desired 2639 output value. (This practice means if algorithm A can use two 2640 different key lengths, the key derived for longer key size will 2641 not contain the key for shorter key size as a prefix.) 2643 protected This field contains the protected parameter field. If 2644 there are no elements in the protected field, then use a zero 2645 length bstr. 2647 other This field is for free form data defined by the 2648 application. An example is that an application could define 2649 two different strings to be placed here to generate different 2650 keys for a data stream vs a control stream. This field is 2651 optional and will only be present if the application defines a 2652 structure for this information. Applications that define this 2653 SHOULD use CBOR to encode the data so that types and lengths 2654 are correctly included. 2656 SuppPrivInfo This field contains private information that is 2657 mutually known private information. An example of this 2658 information would be a pre-existing shared secret. (This could, 2659 for example, be used in combination with an ECDH key agreement to 2660 provide a secondary proof of identity.) The field is optional and 2661 will only be present if the application defines a structure for 2662 this information. Applications that define this SHOULD use CBOR 2663 to encode the data so that types and lengths are correctly 2664 included. 2666 The following CDDL fragment corresponds to the text above. 2668 PartyInfo = ( 2669 identity : bstr / nil, 2670 nonce : bstr / int / nil, 2671 other : bstr / nil, 2672 ) 2674 COSE_KDF_Context = [ 2675 AlgorithmID : int / tstr, 2676 PartyUInfo : [ PartyInfo ], 2677 PartyVInfo : [ PartyInfo ], 2678 SuppPubInfo : [ 2679 keyDataLength : uint, 2680 protected : empty_or_serialized_map, 2681 ? other : bstr 2682 ], 2683 ? SuppPrivInfo : bstr 2684 ] 2686 12. Content Key Distribution Methods 2688 Content key distribution methods (recipient algorithms) can be 2689 defined into a number of different classes. COSE has the ability to 2690 support many classes of recipient algorithms. In this section, a 2691 number of classes are listed and then a set of algorithms are 2692 specified for each of the classes. The names of the recipient 2693 algorithm classes used here are the same as are defined in [RFC7516]. 2694 Other specifications use different terms for the recipient algorithm 2695 classes or do not support some of the recipient algorithm classes. 2697 12.1. Direct Encryption 2699 The direct encryption class algorithms share a secret between the 2700 sender and the recipient that is used either directly or after 2701 manipulation as the CEK. When direct encryption mode is used, it 2702 MUST be the only mode used on the message. 2704 The COSE_Encrypt structure for the recipient is organized as follows: 2706 o The 'protected' field MUST be a zero length item unless it is used 2707 in the computation of the content key. 2709 o The 'alg' parameter MUST be present. 2711 o A parameter identifying the shared secret SHOULD be present. 2713 o The 'ciphertext' field MUST be a zero length item. 2715 o The 'recipients' field MUST be absent. 2717 12.1.1. Direct Key 2719 This recipient algorithm is the simplest; the identified key is 2720 directly used as the key for the next layer down in the message. 2721 There are no algorithm parameters defined for this algorithm. The 2722 algorithm identifier value is assigned in Table 15. 2724 When this algorithm is used, the protected field MUST be zero length. 2725 The key type MUST be 'Symmetric'. 2727 +--------+-------+-------------------+ 2728 | name | value | description | 2729 +--------+-------+-------------------+ 2730 | direct | -6 | Direct use of CEK | 2731 +--------+-------+-------------------+ 2733 Table 15: Direct Key 2735 12.1.1.1. Security Considerations 2737 This recipient algorithm has several potential problems that need to 2738 be considered: 2740 o These keys need to have some method to be regularly updated over 2741 time. All of the content encryption algorithms specified in this 2742 document have limits on how many times a key can be used without 2743 significant loss of security. 2745 o These keys need to be dedicated to a single algorithm. There have 2746 been a number of attacks developed over time when a single key is 2747 used for multiple different algorithms. One example of this is 2748 the use of a single key both for CBC encryption mode and CBC-MAC 2749 authentication mode. 2751 o Breaking one message means all messages are broken. If an 2752 adversary succeeds in determining the key for a single message, 2753 then the key for all messages is also determined. 2755 12.1.2. Direct Key with KDF 2757 These recipient algorithms take a common shared secret between the 2758 two parties and applies the HKDF function (Section 11.1), using the 2759 context structure defined in Section 11.2 to transform the shared 2760 secret into the CEK. The 'protected' field can be of non-zero 2761 length. Either the 'salt' parameter of HKDF or the partyU 'nonce' 2762 parameter of the context structure MUST be present. The salt/nonce 2763 parameter can be generated either randomly or deterministically. The 2764 requirement is that it be a unique value for the shared secret in 2765 question. 2767 If the salt/nonce value is generated randomly, then it is suggested 2768 that the length of the random value be the same length as the hash 2769 function underlying HKDF. While there is no way to guarantee that it 2770 will be unique, there is a high probability that it will be unique. 2771 If the salt/nonce value is generated deterministically, it can be 2772 guaranteed to be unique and thus there is no length requirement. 2774 A new IV must be used for each message if the same key is used. The 2775 IV can be modified in a predictable manner, a random manner or an 2776 unpredictable manner (i.e., encrypting a counter). 2778 The IV used for a key can also be generated from the same HKDF 2779 functionality as the key is generated. If HKDF is used for 2780 generating the IV, the algorithm identifier is set to "IV- 2781 GENERATION". 2783 When these algorithms are used, the key type MUST be 'symmetric'. 2785 The set of algorithms defined in this document can be found in 2786 Table 16. 2788 +---------------------+-------+-------------+-----------------------+ 2789 | name | value | KDF | description | 2790 +---------------------+-------+-------------+-----------------------+ 2791 | direct+HKDF-SHA-256 | -10 | HKDF | Shared secret w/ HKDF | 2792 | | | SHA-256 | and SHA-256 | 2793 | | | | | 2794 | direct+HKDF-SHA-512 | -11 | HKDF | Shared secret w/ HKDF | 2795 | | | SHA-512 | and SHA-512 | 2796 | | | | | 2797 | direct+HKDF-AES-128 | -12 | HKDF AES- | Shared secret w/ AES- | 2798 | | | MAC-128 | MAC 128-bit key | 2799 | | | | | 2800 | direct+HKDF-AES-256 | -13 | HKDF AES- | Shared secret w/ AES- | 2801 | | | MAC-256 | MAC 256-bit key | 2802 +---------------------+-------+-------------+-----------------------+ 2804 Table 16: Direct Key with KDF 2806 When using a COSE key for this algorithm, the following checks are 2807 made: 2809 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2811 o If the 'alg' field is present, it MUST match the algorithm being 2812 used. 2814 o If the 'key_ops' field is present, it MUST include 'deriveKey' or 2815 'deriveBits'. 2817 12.1.2.1. Security Considerations 2819 The shared secret needs to have some method to be regularly updated 2820 over time. The shared secret forms the basis of trust. Although not 2821 used directly, it should still be subject to scheduled rotation. 2823 While these methods do not provide for perfect forward secrecy, as 2824 the same shared secret is used for all of the keys generated, if the 2825 key for any single message is discovered only the message (or series 2826 of messages) using that derived key are compromised. A new key 2827 derivation step will generate a new key which requires the same 2828 amount of work to get the key. 2830 12.2. Key Wrapping 2832 In key wrapping mode, the CEK is randomly generated and that key is 2833 then encrypted by a shared secret between the sender and the 2834 recipient. All of the currently defined key wrapping algorithms for 2835 COSE are AE algorithms. Key wrapping mode is considered to be 2836 superior to direct encryption if the system has any capability for 2837 doing random key generation. This is because the shared key is used 2838 to wrap random data rather than data that has some degree of 2839 organization and may in fact be repeating the same content. The use 2840 of Key Wrapping loses the weak data origination that is provided by 2841 the direct encryption algorithms. 2843 The COSE_Encrypt structure for the recipient is organized as follows: 2845 o The 'protected' field MUST be absent if the key wrap algorithm is 2846 an AE algorithm. 2848 o The 'recipients' field is normally absent, but can be used. 2849 Applications MUST deal with a recipient field being present, not 2850 being able to decrypt that recipient is an acceptable way of 2851 dealing with it. Failing to process the message is not an 2852 acceptable way of dealing with it. 2854 o The plain text to be encrypted is the key from next layer down 2855 (usually the content layer). 2857 o At a minimum, the 'unprotected' field MUST contain the 'alg' 2858 parameter and SHOULD contain a parameter identifying the shared 2859 secret. 2861 12.2.1. AES Key Wrapping 2863 The AES Key Wrapping algorithm is defined in [RFC3394]. This 2864 algorithm uses an AES key to wrap a value that is a multiple of 64 2865 bits. As such, it can be used to wrap a key for any of the content 2866 encryption algorithms defined in this document. The algorithm 2867 requires a single fixed parameter, the initial value. This is fixed 2868 to the value specified in Section 2.2.3.1 of [RFC3394]. There are no 2869 public parameters that vary on a per invocation basis. The protected 2870 header field MUST be empty. 2872 Keys may be obtained either from a key structure or from a recipient 2873 structure. Implementations encrypting and decrypting MUST validate 2874 that the key type, key length and algorithm are correct and 2875 appropriate for the entities involved. 2877 When using a COSE key for this algorithm, the following checks are 2878 made: 2880 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2882 o If the 'alg' field is present, it MUST match the AES Key Wrap 2883 algorithm being used. 2885 o If the 'key_ops' field is present, it MUST include 'encrypt' or 2886 'wrap key' when encrypting. 2888 o If the 'key_ops' field is present, it MUST include 'decrypt' or 2889 'unwrap key' when decrypting. 2891 +--------+-------+----------+-----------------------------+ 2892 | name | value | key size | description | 2893 +--------+-------+----------+-----------------------------+ 2894 | A128KW | -3 | 128 | AES Key Wrap w/ 128-bit key | 2895 | | | | | 2896 | A192KW | -4 | 192 | AES Key Wrap w/ 192-bit key | 2897 | | | | | 2898 | A256KW | -5 | 256 | AES Key Wrap w/ 256-bit key | 2899 +--------+-------+----------+-----------------------------+ 2901 Table 17: AES Key Wrap Algorithm Values 2903 12.2.1.1. Security Considerations for AES-KW 2905 The shared secret needs to have some method to be regularly updated 2906 over time. The shared secret is the basis of trust. 2908 12.3. Key Transport 2910 Key transport mode is also called key encryption mode in some 2911 standards. Key transport mode differs from key wrap mode in that it 2912 uses an asymmetric encryption algorithm rather than a symmetric 2913 encryption algorithm to protect the key. This document does not 2914 define any key transport mode algorithms. 2916 When using a key transport algorithm, the COSE_Encrypt structure for 2917 the recipient is organized as follows: 2919 o The 'protected' field MUST be absent. 2921 o The plain text to be encrypted is the key from next layer down 2922 (usually the content layer). 2924 o At a minimum, the 'unprotected' field MUST contain the 'alg' 2925 parameter and SHOULD contain a parameter identifying the 2926 asymmetric key. 2928 12.4. Direct Key Agreement 2930 The 'direct key agreement' class of recipient algorithms uses a key 2931 agreement method to create a shared secret. A KDF is then applied to 2932 the shared secret to derive a key to be used in protecting the data. 2933 This key is normally used as a CEK or MAC key, but could be used for 2934 other purposes if more than two layers are in use (see Appendix B). 2936 The most commonly used key agreement algorithm is Diffie-Hellman, but 2937 other variants exist. Since COSE is designed for a store and forward 2938 environment rather than an on-line environment, many of the DH 2939 variants cannot be used as the receiver of the message cannot provide 2940 any dynamic key material. One side-effect of this is that perfect 2941 forward secrecy (see [RFC4949]) is not achievable. A static key will 2942 always be used for the receiver of the COSE object. 2944 Two variants of DH that are supported are: 2946 Ephemeral-Static DH: where the sender of the message creates a 2947 one-time DH key and uses a static key for the recipient. The use 2948 of the ephemeral sender key means that no additional random input 2949 is needed as this is randomly generated for each message. 2951 Static-Static DH: where a static key is used for both the sender 2952 and the recipient. The use of static keys allows for recipient to 2953 get a weak version of data origination for the message. When 2954 static-static key agreement is used, then some piece of unique 2955 data for the KDF is required to ensure that a different key is 2956 created for each message. 2958 When direct key agreement mode is used, there MUST be only one 2959 recipient in the message. This method creates the key directly and 2960 that makes it difficult to mix with additional recipients. If 2961 multiple recipients are needed, then the version with key wrap needs 2962 to be used. 2964 The COSE_Encrypt structure for the recipient is organized as follows: 2966 o At a minimum, headers MUST contain the 'alg' parameter and SHOULD 2967 contain a parameter identifying the recipient's asymmetric key. 2969 o The headers SHOULD identify the sender's key for the static-static 2970 versions and MUST contain the sender's ephemeral key for the 2971 ephemeral-static versions. 2973 12.4.1. ECDH 2975 The mathematics for Elliptic Curve Diffie-Hellman can be found in 2976 [RFC6090]. In this document, the algorithm is extended to be used 2977 with the two curves defined in [RFC7748]. 2979 ECDH is parameterized by the following: 2981 o Curve Type/Curve: The curve selected controls not only the size of 2982 the shared secret, but the mathematics for computing the shared 2983 secret. The curve selected also controls how a point in the curve 2984 is represented and what happens for the identity points on the 2985 curve. In this specification, we allow for a number of different 2986 curves to be used. A set of curves are defined in Table 22. 2987 The math used to obtain the computed secret is based on the curve 2988 selected and not on the ECDH algorithm. For this reason, a new 2989 algorithm does not need to be defined for each of the curves. 2991 o Computed Secret to Shared Secret: Once the computed secret is 2992 known, the resulting value needs to be converted to a byte string 2993 to run the KDF function. The X coordinate is used for all of the 2994 curves defined in this document. For curves X25519 and X448, the 2995 resulting value is used directly as it is a byte string of a known 2996 length. For the P-256, P-384 and P-521 curves, the X coordinate 2997 is run through the I2OSP function defined in [I-D.moriarty-pkcs1], 2998 using the same computation for n as is defined in Section 8.1. 3000 o Ephemeral-static or static-static: The key agreement process may 3001 be done using either a static or an ephemeral key for the sender's 3002 side. When using ephemeral keys, the sender MUST generate a new 3003 ephemeral key for every key agreement operation. The ephemeral 3004 key is placed in the 'ephemeral key' parameter and MUST be present 3005 for all algorithm identifiers that use ephemeral keys. When using 3006 static keys, the sender MUST either generate a new random value or 3007 otherwise create a unique value. For the KDF functions used, this 3008 means either in the 'salt' parameter for HKDF (Table 13) or in the 3009 'PartyU nonce' parameter for the context structure (Table 14) MUST 3010 be present. (Both may be present if desired.) The value in the 3011 parameter MUST be unique for the pair of keys being used. It is 3012 acceptable to use a global counter that is incremented for every 3013 static-static operation and use the resulting value. When using 3014 static keys, the static key should be identified to the recipient. 3015 The static key can be identified either by providing the key 3016 ('static key') or by providing a key identifier for the static key 3017 ('static key id'). Both of these parameters are defined in 3018 Table 19. 3020 o Key derivation algorithm: The result of an ECDH key agreement 3021 process does not provide a uniformly random secret. As such, it 3022 needs to be run through a KDF in order to produce a usable key. 3023 Processing the secret through a KDF also allows for the 3024 introduction of context material: how the key is going to be used, 3025 and one-time material for static-static key agreement. All of the 3026 algorithms defined in this document use one of the HKDF algorithms 3027 defined in Section 11.1 with the context structure defined in 3028 Section 11.2. 3030 o Key Wrap algorithm: No key wrap algorithm is used. This is 3031 represented in Table 18 as 'none'. The key size for the context 3032 structure is the content layer encryption algorithm size. 3034 The set of direct ECDH algorithms defined in this document are found 3035 in Table 18. 3037 +-----------+-------+---------+------------+--------+---------------+ 3038 | name | value | KDF | Ephemeral- | Key | description | 3039 | | | | Static | Wrap | | 3040 +-----------+-------+---------+------------+--------+---------------+ 3041 | ECDH-ES + | -25 | HKDF - | yes | none | ECDH ES w/ | 3042 | HKDF-256 | | SHA-256 | | | HKDF - | 3043 | | | | | | generate key | 3044 | | | | | | directly | 3045 | | | | | | | 3046 | ECDH-ES + | -26 | HKDF - | yes | none | ECDH ES w/ | 3047 | HKDF-512 | | SHA-512 | | | HKDF - | 3048 | | | | | | generate key | 3049 | | | | | | directly | 3050 | | | | | | | 3051 | ECDH-SS + | -27 | HKDF - | no | none | ECDH SS w/ | 3052 | HKDF-256 | | SHA-256 | | | HKDF - | 3053 | | | | | | generate key | 3054 | | | | | | directly | 3055 | | | | | | | 3056 | ECDH-SS + | -28 | HKDF - | no | none | ECDH SS w/ | 3057 | HKDF-512 | | SHA-512 | | | HKDF - | 3058 | | | | | | generate key | 3059 | | | | | | directly | 3060 +-----------+-------+---------+------------+--------+---------------+ 3062 Table 18: ECDH Algorithm Values 3064 +-----------+-------+----------+---------------------+--------------+ 3065 | name | label | type | algorithm | description | 3066 +-----------+-------+----------+---------------------+--------------+ 3067 | ephemeral | -1 | COSE_Key | ECDH-ES+HKDF-256, | Ephemeral | 3068 | key | | | ECDH-ES+HKDF-512, | Public key | 3069 | | | | ECDH-ES+A128KW, | for the | 3070 | | | | ECDH-ES+A192KW, | sender | 3071 | | | | ECDH-ES+A256KW | | 3072 | | | | | | 3073 | static | -2 | COSE_Key | ECDH-SS+HKDF-256, | Static | 3074 | key | | | ECDH-SS+HKDF-512, | Public key | 3075 | | | | ECDH-SS+A128KW, | for the | 3076 | | | | ECDH-SS+A192KW, | sender | 3077 | | | | ECDH-SS+A256KW | | 3078 | | | | | | 3079 | static | -3 | bstr | ECDH-SS+HKDF-256, | Static | 3080 | key id | | | ECDH-SS+HKDF-512, | Public key | 3081 | | | | ECDH-SS+A128KW, | identifier | 3082 | | | | ECDH-SS+A192KW, | for the | 3083 | | | | ECDH-SS+A256KW | sender | 3084 +-----------+-------+----------+---------------------+--------------+ 3086 Table 19: ECDH Algorithm Parameters 3088 This document defines these algorithms to be used with the curves 3089 P-256, P-384, P-521, X25519, and X448. Implementations MUST verify 3090 that the key type and curve are correct. Different curves are 3091 restricted to different key types. Implementations MUST verify that 3092 the curve and algorithm are appropriate for the entities involved. 3094 When using a COSE key for this algorithm, the following checks are 3095 made: 3097 o The 'kty' field MUST be present and it MUST be 'EC2' or 'OKP'. 3099 o If the 'alg' field is present, it MUST match the Key Agreement 3100 algorithm being used. 3102 o If the 'key_ops' field is present, it MUST include 'derive key' or 3103 'derive bits' for the private key. 3105 o If the 'key_ops' field is present, it MUST be empty for the public 3106 key. 3108 12.4.2. Security Considerations 3110 Some method of checking that points provided from external entities 3111 are valid. For the 'EC2' key format, this can be done by checking 3112 that the x and y values form a point on the curve. For the 'OKP' 3113 format, there is no simple way to do point validation. 3115 Consideration was given to requiring that the public keys of both 3116 entities be provided as part of the key derivation process. (As 3117 recommended in section 6.1 of [RFC7748].) This was not done as COSE 3118 is used in a store and forward format rather than in on line key 3119 exchange. In order for this to be a problem, either the receiver 3120 public key has to be chosen maliciously or the sender has to be 3121 malicious. In either case, all security evaporates anyway. 3123 A proof of possession of the private key associated with the public 3124 key is recommended when a key is moved from untrusted to trusted. 3125 (Either by the end user or by the entity that is responsible for 3126 making trust statements on keys.) 3128 12.5. Key Agreement with Key Wrap 3130 Key Agreement with Key Wrapping uses a randomly generated CEK. The 3131 CEK is then encrypted using a Key Wrapping algorithm and a key 3132 derived from the shared secret computed by the key agreement 3133 algorithm. The function for this would be: 3135 encryptedKey = KeyWrap(KDF(DH-Shared, context), CEK) 3137 The COSE_Encrypt structure for the recipient is organized as follows: 3139 o The 'protected' field is fed into the KDF context structure. 3141 o The plain text to be encrypted is the key from next layer down 3142 (usually the content layer). 3144 o The 'alg' parameter MUST be present in the layer. 3146 o A parameter identifying the recipient's key SHOULD be present. A 3147 parameter identifying the sender's key SHOULD be present. 3149 12.5.1. ECDH 3151 These algorithms are defined in Table 20. 3153 ECDH with Key Agreement is parameterized by the same parameters as 3154 for ECDH Section 12.4.1 with the following modifications: 3156 o Key Wrap Algorithm: Any of the key wrap algorithms defined in 3157 Section 12.2.1 are supported. The size of the key used for the 3158 key wrap algorithm is fed into the KDF function. The set of 3159 identifiers are found in Table 20. 3161 +-----------+-------+---------+------------+--------+---------------+ 3162 | name | value | KDF | Ephemeral- | Key | description | 3163 | | | | Static | Wrap | | 3164 +-----------+-------+---------+------------+--------+---------------+ 3165 | ECDH-ES + | -29 | HKDF - | yes | A128KW | ECDH ES w/ | 3166 | A128KW | | SHA-256 | | | Concat KDF | 3167 | | | | | | and AES Key | 3168 | | | | | | wrap w/ 128 | 3169 | | | | | | bit key | 3170 | | | | | | | 3171 | ECDH-ES + | -30 | HKDF - | yes | A192KW | ECDH ES w/ | 3172 | A192KW | | SHA-256 | | | Concat KDF | 3173 | | | | | | and AES Key | 3174 | | | | | | wrap w/ 192 | 3175 | | | | | | bit key | 3176 | | | | | | | 3177 | ECDH-ES + | -31 | HKDF - | yes | A256KW | ECDH ES w/ | 3178 | A256KW | | SHA-256 | | | Concat KDF | 3179 | | | | | | and AES Key | 3180 | | | | | | wrap w/ 256 | 3181 | | | | | | bit key | 3182 | | | | | | | 3183 | ECDH-SS + | -32 | HKDF - | no | A128KW | ECDH SS w/ | 3184 | A128KW | | SHA-256 | | | Concat KDF | 3185 | | | | | | and AES Key | 3186 | | | | | | wrap w/ 128 | 3187 | | | | | | bit key | 3188 | | | | | | | 3189 | ECDH-SS + | -33 | HKDF - | no | A192KW | ECDH SS w/ | 3190 | A192KW | | SHA-256 | | | Concat KDF | 3191 | | | | | | and AES Key | 3192 | | | | | | wrap w/ 192 | 3193 | | | | | | bit key | 3194 | | | | | | | 3195 | ECDH-SS + | -34 | HKDF - | no | A256KW | ECDH SS w/ | 3196 | A256KW | | SHA-256 | | | Concat KDF | 3197 | | | | | | and AES Key | 3198 | | | | | | wrap w/ 256 | 3199 | | | | | | bit key | 3200 +-----------+-------+---------+------------+--------+---------------+ 3202 Table 20: ECDH Algorithm Values with Key Wrap 3204 When using a COSE key for this algorithm, the following checks are 3205 made: 3207 o The 'kty' field MUST be present and it MUST be 'EC2' or 'OKP'. 3209 o If the 'alg' field is present, it MUST match the Key Agreement 3210 algorithm being used. 3212 o If the 'key_ops' field is present, it MUST include 'derive key' or 3213 'derive bits' for the private key. 3215 o If the 'key_ops' field is present, it MUST be empty for the public 3216 key. 3218 13. Key Object Parameters 3220 The COSE_Key object defines a way to hold a single key object. It is 3221 still required that the members of individual key types be defined. 3222 This section of the document is where we define an initial set of 3223 members for specific key types. 3225 For each of the key types, we define both public and private members. 3226 The public members are what is transmitted to others for their usage. 3227 Private members allow for the archival of keys by individuals. 3228 However, there are some circumstances in which private keys may be 3229 distributed to entities in a protocol. Examples include: entities 3230 that have poor random number generation, centralized key creation for 3231 multi-cast type operations, and protocols in which a shared secret is 3232 used as a bearer token for authorization purposes. 3234 Key types are identified by the 'kty' member of the COSE_Key object. 3235 In this document, we define four values for the member: 3237 +-----------+-------+--------------------------------------------+ 3238 | name | value | description | 3239 +-----------+-------+--------------------------------------------+ 3240 | OKP | 1 | Octet Key Pair | 3241 | | | | 3242 | EC2 | 2 | Elliptic Curve Keys w/ X,Y Coordinate pair | 3243 | | | | 3244 | Symmetric | 4 | Symmetric Keys | 3245 | | | | 3246 | Reserved | 0 | This value is reserved | 3247 +-----------+-------+--------------------------------------------+ 3249 Table 21: Key Type Values 3251 13.1. Elliptic Curve Keys 3253 Two different key structures could be defined for Elliptic Curve 3254 keys. One version uses both an x and a y coordinate, potentially 3255 with point compression ('EC2'). This is the traditional EC point 3256 representation that is used in [RFC5480]. The other version uses 3257 only the x coordinate as the y coordinate is either to be recomputed 3258 or not needed for the key agreement operation ('OKP'). 3260 Applications MUST check that the curve and the key type are 3261 consistent and reject a key if they are not. 3263 +---------+----------+-------+------------------------------------+ 3264 | name | key type | value | description | 3265 +---------+----------+-------+------------------------------------+ 3266 | P-256 | EC2 | 1 | NIST P-256 also known as secp256r1 | 3267 | | | | | 3268 | P-384 | EC2 | 2 | NIST P-384 also known as secp384r1 | 3269 | | | | | 3270 | P-521 | EC2 | 3 | NIST P-521 also known as secp521r1 | 3271 | | | | | 3272 | X25519 | OKP | 4 | X25519 for use w/ ECDH only | 3273 | | | | | 3274 | X448 | OKP | 5 | X448 for use w/ ECDH only | 3275 | | | | | 3276 | Ed25519 | OKP | 6 | Ed25519 for use w/ EdDSA only | 3277 | | | | | 3278 | Ed448 | OKP | 7 | Ed448 for use w/ EdDSA only | 3279 +---------+----------+-------+------------------------------------+ 3281 Table 22: EC Curves 3283 13.1.1. Double Coordinate Curves 3285 The traditional way of sending EC curves has been to send either both 3286 the x and y coordinates, or the x coordinate and a sign bit for the y 3287 coordinate. The latter encoding has not been recommended in the IETF 3288 due to potential IPR issues. However, for operations in constrained 3289 environments, the ability to shrink a message by not sending the y 3290 coordinate is potentially useful. 3292 For EC keys with both coordinates, the 'kty' member is set to 2 3293 (EC2). The key parameters defined in this section are summarized in 3294 Table 23. The members that are defined for this key type are: 3296 crv contains an identifier of the curve to be used with the key. 3297 The curves defined in this document for this key type can be found 3298 in Table 22. Other curves may be registered in the future and 3299 private curves can be used as well. 3301 x contains the x coordinate for the EC point. The integer is 3302 converted to an octet string as defined in [SEC1]. Leading zero 3303 octets MUST be preserved. 3305 y contains either the sign bit or the value of y coordinate for the 3306 EC point. When encoding the value y, the integer is converted to 3307 an octet string (as defined in [SEC1]) and encoded as a CBOR bstr. 3308 Leading zero octets MUST be preserved. The compressed point 3309 encoding is also supported. Compute the sign bit as laid out in 3310 the Elliptic-Curve-Point-to-Octet-String Conversion function of 3311 [SEC1]. If the sign bit is zero, then encode y as a CBOR false 3312 value, otherwise encode y as a CBOR true value. The encoding of 3313 the infinity point is not supported. 3315 d contains the private key. 3317 For public keys, it is REQUIRED that 'crv', 'x' and 'y' be present in 3318 the structure. For private keys, it is REQUIRED that 'crv' and 'd' 3319 be present in the structure. For private keys, it is RECOMMENDED 3320 that 'x' and 'y' also be present, but they can be recomputed from the 3321 required elements and omitting them saves on space. 3323 +------+-------+-------+---------+----------------------------------+ 3324 | name | key | label | type | description | 3325 | | type | | | | 3326 +------+-------+-------+---------+----------------------------------+ 3327 | crv | 2 | -1 | int / | EC Curve identifier - Taken from | 3328 | | | | tstr | the COSE Curves registry | 3329 | | | | | | 3330 | x | 2 | -2 | bstr | X Coordinate | 3331 | | | | | | 3332 | y | 2 | -3 | bstr / | Y Coordinate | 3333 | | | | bool | | 3334 | | | | | | 3335 | d | 2 | -4 | bstr | Private key | 3336 +------+-------+-------+---------+----------------------------------+ 3338 Table 23: EC Key Parameters 3340 13.2. Octet Key Pair 3342 A new key type is defined for Octet Key Pairs (OKP). Do not assume 3343 that keys using this type are elliptic curves. This key type could 3344 be used for other curve types (for example, mathematics based on 3345 hyper-elliptic surfaces). 3347 The key parameters defined in this section are summarized in 3348 Table 24. The members that are defined for this key type are: 3350 crv contains an identifier of the curve to be used with the key. 3351 The curves defined in this document for this key type can be found 3352 in Table 22. Other curves may be registered in the future and 3353 private curves can be used as well. 3355 x contains the x coordinate for the EC point. The octet string 3356 represents a little-endian encoding of x. 3358 d contains the private key. 3360 For public keys, it is REQUIRED that 'crv' and 'x' be present in the 3361 structure. For private keys, it is REQUIRED that 'crv' and 'd' be 3362 present in the structure. For private keys, it is RECOMMENDED that 3363 'x' also be present, but it can be recomputed from the required 3364 elements and omitting it saves on space. 3366 +------+------+-------+-------+-------------------------------------+ 3367 | name | key | label | type | description | 3368 | | type | | | | 3369 +------+------+-------+-------+-------------------------------------+ 3370 | crv | 1 | -1 | int / | EC Curve identifier - Taken from | 3371 | | | | tstr | the COSE Key Common Parameters | 3372 | | | | | registry | 3373 | | | | | | 3374 | x | 1 | -2 | bstr | X Coordinate | 3375 | | | | | | 3376 | d | 1 | -4 | bstr | Private key | 3377 +------+------+-------+-------+-------------------------------------+ 3379 Table 24: Octet Key Pair Parameters 3381 13.3. Symmetric Keys 3383 Occasionally it is required that a symmetric key be transported 3384 between entities. This key structure allows for that to happen. 3386 For symmetric keys, the 'kty' member is set to 3 (Symmetric). The 3387 member that is defined for this key type is: 3389 k contains the value of the key. 3391 This key structure does not have a form that contains only public 3392 members. As it is expected that this key structure is going to be 3393 transmitted, care must be taking that it is never transmitted 3394 accidentally or insecurely. For symmetric keys, it is REQUIRED that 3395 'k' be present in the structure. 3397 +------+----------+-------+------+-------------+ 3398 | name | key type | label | type | description | 3399 +------+----------+-------+------+-------------+ 3400 | k | 4 | -1 | bstr | Key Value | 3401 +------+----------+-------+------+-------------+ 3403 Table 25: Symmetric Key Parameters 3405 14. CBOR Encoder Restrictions 3407 There has been an attempt to limit the number of places where the 3408 document needs to impose restrictions on how the CBOR Encoder needs 3409 to work. We have managed to narrow it down to the following 3410 restrictions: 3412 o The restriction applies to the encoding the Sig_structure, the 3413 Enc_structure, and the MAC_structure. 3415 o The rules for Canonical CBOR (Section 3.9 of RFC 7049) MUST be 3416 used in these locations. The main rule that needs to be enforced 3417 is that all lengths in these structures MUST be encoded such that 3418 they are encoded using definite lengths and the minimum length 3419 encoding is used. 3421 o Applications MUST NOT generate messages with the same label used 3422 twice as a key in a single map. Applications MUST NOT parse and 3423 process messages with the same label used twice as a key in a 3424 single map. Applications can enforce the parse and process 3425 requirement by using parsers that will fail the parse step or by 3426 using parsers that will pass all keys to the application and the 3427 application can perform the check for duplicate keys. 3429 15. Application Profiling Considerations 3431 This document is designed to provide a set of security services, but 3432 not to provide implementation requirements for specific usage. The 3433 interoperability requirements are provided for how each of the 3434 individual services are used and how the algorithms are to be used 3435 for interoperability. The requirements about which algorithms and 3436 which services are needed are deferred to each application. 3438 An example of a profile can be found in 3439 [I-D.selander-ace-object-security] where two profiles are being 3440 developed. One is for carrying content by itself, and the other is 3441 for carrying content in combination with CoAP headers. 3443 It is intended that a profile of this document be created that 3444 defines the interoperability requirements for that specific 3445 application. This section provides a set of guidelines and topics 3446 that need to be considered when profiling this document. 3448 o Applications need to determine the set of messages defined in this 3449 document that they will be using. The set of messages corresponds 3450 fairly directly to the set of security services that are needed 3451 and to the security levels needed. 3453 o Applications may define new header parameters for a specific 3454 purpose. Applications will often times select specific header 3455 parameters to use or not to use. For example, an application 3456 would normally state a preference for using either the IV or the 3457 partial IV parameter. If the partial IV parameter is specified, 3458 then the application would also need to define how the fixed 3459 portion of the IV would be determined. 3461 o When applications use externally defined authenticated data, they 3462 need to define how that data is encoded. This document assumes 3463 that the data will be provided as a byte stream. More information 3464 can be found in Section 4.3. 3466 o Applications need to determine the set of security algorithms that 3467 are to be used. When selecting the algorithms to be used as the 3468 mandatory to implement set, consideration should be given to 3469 choosing different types of algorithms when two are chosen for a 3470 specific purpose. An example of this would be choosing HMAC- 3471 SHA512 and AES-CMAC as different MAC algorithms; the construction 3472 is vastly different between these two algorithms. This means that 3473 a weakening of one algorithm would be unlikely to lead to a 3474 weakening of the other algorithms. Of course, these algorithms do 3475 not provide the same level of security and thus may not be 3476 comparable for the desired security functionality. 3478 o Applications may need to provide some type of negotiation or 3479 discovery method if multiple algorithms or message structures are 3480 permitted. The method can be as simple as requiring 3481 preconfiguration of the set of algorithms to providing a discovery 3482 method built into the protocol. S/MIME provided a number of 3483 different ways to approach the problem that applications could 3484 follow: 3486 * Advertising in the message (S/MIME capabilities) [RFC5751]. 3488 * Advertising in the certificate (capabilities extension) 3489 [RFC4262]. 3491 * Minimum requirements for the S/MIME, which have been updated 3492 over time [RFC2633][RFC5751]. 3494 16. IANA Considerations 3496 16.1. CBOR Tag assignment 3498 It is requested that IANA assign the following tags from the "CBOR 3499 Tags" registry. It is requested that the tags for COSE_Sign1, 3500 COSE_Encrypt0, and COSE_Mac0 be assigned in the 1 to 23 value range 3501 (one byte long when encoded). It is requested that the tags for 3502 COSE_Sign, COSE_Encrypt and COSE_MAC be assigned in the 24 to 255 3503 value range (two bytes long when encoded). 3505 The tags to be assigned are in Table 1. 3507 16.2. COSE Header Parameters Registry 3509 It is requested that IANA create a new registry entitled "COSE Header 3510 Parameters". The registry should be created as Expert Review 3511 Required. Guidelines for the experts is provided Section 16.11. It 3512 should be noted that in additional to the expert review, some 3513 portions of the registry require a specification, potentially on 3514 standards track, be supplied as well. 3516 The columns of the registry are: 3518 name The name is present to make it easier to refer to and discuss 3519 the registration entry. The value is not used in the protocol. 3520 Names are to be unique in the table. 3522 label This is the value used for the label. The label can be either 3523 an integer or a string. Registration in the table is based on the 3524 value of the label requested. Integer values between 1 and 255 3525 and strings of length 1 are designated as Standards Track Document 3526 required. Integer values from 256 to 65535 and strings of length 3527 2 are designated as Specification Required. Integer values of 3528 greater than 65535 and strings of length greater than 2 are 3529 designated as expert review. Integer values in the range -1 to 3530 -65536 are delegated to the "COSE Header Algorithm Parameters" 3531 registry. Integer values less than -65536 are marked as private 3532 use. 3534 value This contains the CBOR type for the value portion of the 3535 label. 3537 value registry This contains a pointer to the registry used to 3538 contain values where the set is limited. 3540 description This contains a brief description of the header field. 3542 specification This contains a pointer to the specification defining 3543 the header field (where public). 3545 The initial contents of the registry can be found in Table 2 and 3546 Table 27. The specification column for all rows in that table should 3547 be this document. 3549 Additionally, the label of 0 is to be marked as 'Reserved'. 3551 16.3. COSE Header Algorithm Parameters Registry 3553 It is requested that IANA create a new registry entitled "COSE Header 3554 Algorithm Parameters". The registry is to be created as Expert 3555 Review Required. Expert review guidelines are provided in 3556 Section 16.11. 3558 The columns of the registry are: 3560 name The name is present to make it easier to refer to and discuss 3561 the registration entry. The value is not used in the protocol. 3563 algorithm The algorithm(s) that this registry entry is used for. 3564 This value is taken from the "COSE Algorithm Values" registry. 3565 Multiple algorithms can be specified in this entry. For the 3566 table, the algorithm, label pair MUST be unique. 3568 label This is the value used for the label. The label is an integer 3569 in the range of -1 to -65536. 3571 value This contains the CBOR type for the value portion of the 3572 label. 3574 description This contains a brief description of the header field. 3576 specification This contains a pointer to the specification defining 3577 the header field (where public). 3579 The initial contents of the registry can be found in Table 13, 3580 Table 14, and Table 19. The specification column for all rows in 3581 that table should be this document. 3583 16.4. COSE Algorithms Registry 3585 It is requested that IANA create a new registry entitled "COSE 3586 Algorithms Registry". The registry is to be created as Expert Review 3587 Required. Guidelines for the experts is provided Section 16.11. It 3588 should be noted that in additional to the expert review, some 3589 portions of the registry require a specification, potentially on 3590 standards track, be supplied as well. 3592 The columns of the registry are: 3594 value: The value to be used to identify this algorithm. Algorithm 3595 values MUST be unique. The value can be a positive integer, a 3596 negative integer or a string. Integer values between -256 and 255 3597 and strings of length 1 are designated as Standards Track Document 3598 required. Integer values from -65536 to 65535 and strings of 3599 length 2 are designated as Specification Required. Integer values 3600 of greater than 65535 and strings of length greater than 2 are 3601 designated as expert review. Integer values less than -65536 are 3602 marked as private use. 3604 description: A short description of the algorithm. 3606 specification: A document where the algorithm is defined (if 3607 publicly available). 3609 recommended: Does the IETF have a concensus recommendation to use 3610 the algorithm. The legal values are 'yes', 'no' and 'deprecated'. 3612 The initial contents of the registry can be found in Table 10, 3613 Table 9, Table 11, Table 5, Table 7, Table 8, Table 15, Table 16, 3614 Table 17, Table 6, Table 20 and Table 18. The specification column 3615 for all rows in the table should be this document. The recommneded 3616 column for all rows in the table are set to 'yes'. 3618 Additionally, the label of 0 is to be marked as 'Reserved'. 3620 NOTE: The assignment of algorithm identifiers in this document was 3621 done so that positive numbers were used for the first layer objects 3622 (COSE_Sign, COSE_Sign1, COSE_Encrypt, COSE_Encrypt0, COSE_Mac, and 3623 COSE_Mac0). Negative numbers were used for second layer objects 3624 (COSE_Signature and COSE_recipient). Expert reviewers should 3625 consider this practice, but are not expected to be restricted by this 3626 precedent. 3628 16.5. COSE Key Common Parameters Registry 3630 It is requested that IANA create a new registry entitled "COSE Key 3631 Common Parameters" registry. The registry is to be created as Expert 3632 Review Required. Guidelines for the experts is provided 3633 Section 16.11. It should be noted that in additional to the expert 3634 review, some portions of the registry require a specification, 3635 potentially on standards track, be supplied as well. 3637 The columns of the registry are: 3639 name This is a descriptive name that enables easier reference to the 3640 item. It is not used in the encoding. 3642 label The value to be used to identify this algorithm. Key map 3643 labels MUST be unique. The label can be a positive integer, a 3644 negative integer or a string. Integer values between 0 and 255 3645 and strings of length 1 are designated as Standards Track Document 3646 required. Integer values from 256 to 65535 and strings of length 3647 2 are designated as Specification Required. Integer values of 3648 greater than 65535 and strings of length greater than 2 are 3649 designated as expert review. Integer values in the range -1 to 3650 -65536 are used for key parameters specific to a single algorithm 3651 delegated to the "COSE Key Type Parameter Labels" registry. 3652 Integer values less than -65536 are marked as private use. 3654 CBOR Type This field contains the CBOR type for the field. 3656 registry This field denotes the registry that values come from, if 3657 one exists. 3659 description This field contains a brief description for the field. 3661 specification This contains a pointer to the public specification 3662 for the field if one exists 3664 This registry will be initially populated by the values in Table 3. 3665 The specification column for all of these entries will be this 3666 document. 3668 16.6. COSE Key Type Parameters Registry 3670 It is requested that IANA create a new registry "COSE Key Type 3671 Parameters". The registry is to be created as Expert Review 3672 Required. Expert review guidelines are provided in Section 16.11. 3674 The columns of the table are: 3676 key type This field contains a descriptive string of a key type. 3677 This should be a value that is in the COSE Key Common Parameters 3678 table and is placed in the 'kty' field of a COSE Key structure. 3680 name This is a descriptive name that enables easier reference to the 3681 item. It is not used in the encoding. 3683 label The label is to be unique for every value of key type. The 3684 range of values is from -256 to -1. Labels are expected to be 3685 reused for different keys. 3687 CBOR type This field contains the CBOR type for the field. 3689 description This field contains a brief description for the field. 3691 specification This contains a pointer to the public specification 3692 for the field if one exists. 3694 This registry will be initially populated by the values in Table 23, 3695 Table 24, and Table 25. The specification column for all of these 3696 entries will be this document. 3698 16.7. COSE Key Type Registry 3700 It is requested that IANA create a new registry "COSE Key Type 3701 Registry". The registry is to be created as Expert Review Required. 3702 Expert review guidelines are provided in Section 16.11. 3704 The columns of this table are: 3706 name This is a descriptive name that enables easier reference to the 3707 item. The name MUST be unique. It is not used in the encoding. 3709 value This is the value used to identify the curve. These values 3710 MUST be unique. The value can be a positive integer, a negative 3711 integer or a string. 3713 description This field contains a brief description of the curve. 3715 specification This contains a pointer to the public specification 3716 for the curve if one exists. 3718 This registry will be initially populated by the values in Table 21. 3719 The specification column for all of these entries will be this 3720 document. 3722 16.8. COSE Elliptic Curve Parameters Registry 3724 It is requested that IANA create a new registry "COSE Elliptic Curve 3725 Parameters". The registry is to be created as Expert Review 3726 Required. Guidelines for the experts is provided Section 16.11. It 3727 should be noted that in additional to the expert review, some 3728 portions of the registry require a specification, potentially on 3729 standards track, be supplied as well. 3731 The columns of the table are: 3733 name This is a descriptive name that enables easier reference to the 3734 item. It is not used in the encoding. 3736 value This is the value used to identify the curve. These values 3737 MUST be unique. The integer values from -256 to 255 are 3738 designated as Standards Track Document Required. The integer 3739 values from 256 to 65535 and -65536 to -257 are designated as 3740 Specification Required. Integer values over 65535 are designated 3741 as expert review. Integer values less than -65536 are marked as 3742 private use. 3744 key type This designates the key type(s) that can be used with this 3745 curve. 3747 description This field contains a brief description of the curve. 3749 specification This contains a pointer to the public specification 3750 for the curve if one exists. 3752 recommended: Does the IETF have a concensus recommendation to use 3753 the algorithm. The legal values are 'yes', 'no' and 'deprecated'. 3755 This registry will be initially populated by the values in Table 22. 3756 The specification column for all of these entries will be this 3757 document. The recommended column for all of the inital entries will 3758 be 'yes'. 3760 16.9. Media Type Registrations 3762 16.9.1. COSE Security Message 3764 This section registers the "application/cose" media type in the 3765 "Media Types" registry. These media types are used to indicate that 3766 the content is a COSE message. 3768 Type name: application 3770 Subtype name: cose 3772 Required parameters: N/A 3774 Optional parameters: cose-type 3776 Encoding considerations: binary 3777 Security considerations: See the Security Considerations section 3778 of RFC TBD. 3780 Interoperability considerations: N/A 3782 Published specification: RFC TBD 3784 Applications that use this media type: IoT applications sending 3785 security content over HTTP(S) transports. 3787 Fragment identifier considerations: N/A 3789 Additional information: 3791 * Magic number(s): N/A 3793 * File extension(s): cbor 3795 * Macintosh file type code(s): N/A 3797 Person & email address to contact for further information: 3798 iesg@ietf.org 3800 Intended usage: COMMON 3802 Restrictions on usage: N/A 3804 Author: Jim Schaad, ietf@augustcellars.com 3806 Change Controller: IESG 3808 Provisional registration? No 3810 16.9.2. COSE Key media type 3812 This section registers the "application/cose-key" and "application/ 3813 cose-key-set" media types in the "Media Types" registry. These media 3814 types are used to indicate, respectively, that content is a COSE_Key 3815 or COSE_KeySet object. 3817 The template for registering "application/cose-key" is: 3819 Type name: application 3821 Subtype name: cose-key 3823 Required parameters: N/A 3824 Optional parameters: N/A 3826 Encoding considerations: binary 3828 Security considerations: See the Security Considerations section 3829 of RFC TBD. 3831 Interoperability considerations: N/A 3833 Published specification: RFC TBD 3835 Applications that use this media type: Distribution of COSE based 3836 keys for IoT applications. 3838 Fragment identifier considerations: N/A 3840 Additional information: 3842 * Magic number(s): N/A 3844 * File extension(s): cbor 3846 * Macintosh file type code(s): N/A 3848 Person & email address to contact for further information: 3849 iesg@ietf.org 3851 Intended usage: COMMON 3853 Restrictions on usage: N/A 3855 Author: Jim Schaad, ietf@augustcellars.com 3857 Change Controller: IESG 3859 Provisional registration? No 3861 The template for registering "application/cose-key-set" is: 3863 Type name: application 3865 Subtype name: cose-key-set 3867 Required parameters: N/A 3869 Optional parameters: N/A 3871 Encoding considerations: binary 3872 Security considerations: See the Security Considerations section 3873 of RFC TBD. 3875 Interoperability considerations: N/A 3877 Published specification: RFC TBD 3879 Applications that use this media type: Distribution of COSE based 3880 keys for IoT applications. 3882 Fragment identifier considerations: N/A 3884 Additional information: 3886 * Magic number(s): N/A 3888 * File extension(s): cbor 3890 * Macintosh file type code(s): N/A 3892 Person & email address to contact for further information: 3893 iesg@ietf.org 3895 Intended usage: COMMON 3897 Restrictions on usage: N/A 3899 Author: Jim Schaad, ietf@augustcellars.com 3901 Change Controller: IESG 3903 Provisional registration? No 3905 16.10. CoAP Content-Format Registrations 3907 IANA is requested to add the following entries to the "CoAP Content- 3908 Format" registry. ID assignment in the 24-255 range is requested. 3910 +---------------------------------+----------+-------+--------------+ 3911 | Media Type | Encoding | ID | Reference | 3912 +---------------------------------+----------+-------+--------------+ 3913 | application/cose; cose-type | | TBD10 | [This | 3914 | ="cose-sign" | | | Document] | 3915 | | | | | 3916 | application/cose; cose-type | | TBD11 | [This | 3917 | ="cose-sign1" | | | Document] | 3918 | | | | | 3919 | application/cose; cose-type | | TBD12 | [This | 3920 | ="cose-encrypt" | | | Document] | 3921 | | | | | 3922 | application/cose; cose-type | | TBD13 | [This | 3923 | ="cose-encrypt0" | | | Document] | 3924 | | | | | 3925 | application/cose; cose-type | | TBD14 | [This | 3926 | ="cose-mac" | | | Document] | 3927 | | | | | 3928 | application/cose; cose-type | | TBD15 | [This | 3929 | ="cose-mac0" | | | Document] | 3930 | | | | | 3931 | application/cose-key | | TBD16 | [This | 3932 | | | | Document] | 3933 | | | | | 3934 | application/cose-key-set | | TBD17 | [This | 3935 | | | | Document | 3936 +---------------------------------+----------+-------+--------------+ 3938 Table 26 3940 16.11. Expert Review Instructions 3942 All of the IANA registries established in this document are defined 3943 as expert review. This section gives some general guidelines for 3944 what the experts should be looking for, but they are being designated 3945 as experts for a reason so they should be given substantial latitude. 3947 Expert reviewers should take into consideration the following points: 3949 o Point squatting should be discouraged. Reviewers are encouraged 3950 to get sufficient information for registration requests to ensure 3951 that the usage is not going to duplicate one that is already 3952 registered and that the point is likely to be used in deployments. 3953 The zones tagged as private use are intended for testing purposes 3954 and closed environments, code points in other ranges should not be 3955 assigned for testing. 3957 o Specifications are required for the standards track range of point 3958 assignment. Specifications should exist for specification 3959 required ranges, but early assignment before a specification is 3960 available is considered to be permissible. Specifications are 3961 needed for the first-come, first-serve range if they are expected 3962 to be used outside of closed environments in an interoperable way. 3963 When specifications are not provided, the description provided 3964 needs to have sufficient information to identify what the point is 3965 being used for. 3967 o Experts should take into account the expected usage of fields when 3968 approving point assignment. The fact that there is a range for 3969 standards track documents does not mean that a standards track 3970 document cannot have points assigned outside of that range. The 3971 length of the encoded value should be weighed against how many 3972 code points of that length are left, the size of device it will be 3973 used on, and the number of code points left that encode to that 3974 size. 3976 o When algorithms are registered, vanity registrations should be 3977 discouraged. One way to do this is to require registrations to 3978 provide additional documentation on security analysis of the 3979 algorithm. Another thing that should be considered is to request 3980 for an opinion on the algorithm from the Crypto Forum Research 3981 Group (CFRG). Algorithms that do not meet the security 3982 requirements of the community and the messages structures should 3983 not be registered. 3985 17. Implementation Status 3987 This section records the status of known implementations of the 3988 protocol defined by this specification at the time of posting of this 3989 Internet-Draft, and is based on a proposal described in [RFC7942]. 3990 The description of implementations in this section is intended to 3991 assist the IETF in its decision processes in progressing drafts to 3992 RFCs. Please note that the listing of any individual implementation 3993 here does not imply endorsement by the IETF. Furthermore, no effort 3994 has been spent to verify the information presented here that was 3995 supplied by IETF contributors. This is not intended as, and must not 3996 be construed to be, a catalog of available implementations or their 3997 features. Readers are advised to note that other implementations may 3998 exist. 4000 According to [RFC7942], "this will allow reviewers and working groups 4001 to assign due consideration to documents that have the benefit of 4002 running code, which may serve as evidence of valuable experimentation 4003 and feedback that have made the implemented protocols more mature. 4005 It is up to the individual working groups to use this information as 4006 they see fit". 4008 17.1. Author's Versions 4010 There are three different implementations that have been created by 4011 the author of the document both to create the examples that are 4012 included in the document and to validate the structures and 4013 methodology used in the design of COSE. 4015 Implementation Location: https://github.com/cose-wg 4017 Primary Maintainer: Jim Schaad 4019 Languages: There are three different languages that are currently 4020 supported: Java, C# and C. 4022 Cryptography: The Java and C# libraries use Bouncy Castle to 4023 provide the required cryptography. The C version uses OPENSSL 4024 Version 1.0 for the cryptography. 4026 Coverage: The libraries currently do not have full support for 4027 counter signatures of either variety. They do have support to 4028 allow for implicit algorithm support as they allow for the 4029 application to set attributes that are not to be sent in the 4030 message. 4032 Testing: All of the examples in the example library are generated 4033 by the C# library and then validated using the Java and C 4034 libraries. All three libraries have tests to allow for the 4035 creating of the same messages that are in the example library 4036 followed by validating them. These are not compared against the 4037 example library. The Java and C# libraries have unit testing 4038 included. Not all of the MUST statements in the document have 4039 been implemented as part of the libraries. One such statement is 4040 the requirement that unique labels be present. 4042 Licensing: Revised BSD License 4044 17.2. COSE Testing Library 4046 Implementation Location: https://github.com/cose-wg/Examples 4048 Primary Maintainer: Jim Schaad 4050 Description: A set of tests for the COSE library is provided as 4051 part of the implementation effort. Both success and fail tests 4052 have been provided. All of the examples in this document are part 4053 of this example set. 4055 Coverage: An attempt has been made to have test cases for every 4056 message type and algorithm in the document. Currently examples 4057 dealing with counter signatures, EdDSA, and ECDH with Curve24459 4058 and Goldilocks are missing. 4060 Licensing: Public Domain 4062 18. Security Considerations 4064 There are a number of security considerations that need to be taken 4065 into account by implementers of this specification. The security 4066 considerations that are specific to an individual algorithm are 4067 placed next to the description of the algorithm. While some 4068 considerations have been highlighted here, additional considerations 4069 may be found in the documents listed in the references. 4071 Implementations need to protect the private key material for any 4072 individuals. There are some cases in this document that need to be 4073 highlighted on this issue. 4075 o Using the same key for two different algorithms can leak 4076 information about the key. It is therefore recommended that keys 4077 be restricted to a single algorithm. 4079 o Use of 'direct' as a recipient algorithm combined with a second 4080 recipient algorithm, exposes the direct key to the second 4081 recipient. 4083 o Several of the algorithms in this document have limits on the 4084 number of times that a key can be used without leaking information 4085 about the key. 4087 The use of ECDH and direct plus KDF (with no key wrap) will not 4088 directly lead to the private key being leaked; the one way function 4089 of the KDF will prevent that. There is however, a different issue 4090 that needs to be addressed. Having two recipients requires that the 4091 CEK be shared between two recipients. The second recipient therefore 4092 has a CEK that was derived from material that can be used for the 4093 weak proof of origin. The second recipient could create a message 4094 using the same CEK and send it to the first recipient, the first 4095 recipient would, for either static-static ECDH or direct plus KDF, 4096 make an assumption that the CEK could be used for proof of origin 4097 even though it is from the wrong entity. If the key wrap step is 4098 added, then no proof of origin is implied and this is not an issue. 4100 Although it has been mentioned before, the use of a single key for 4101 multiple algorithms has been demonstrated in some cases to leak 4102 information about a key, provide for attackers to forge integrity 4103 tags, or gain information about encrypted content. Binding a key to 4104 a single algorithm prevents these problems. Key creators and key 4105 consumers are strongly encouraged not only to create new keys for 4106 each different algorithm, but to include that selection of algorithm 4107 in any distribution of key material and strictly enforce the matching 4108 of algorithms in the key structure to algorithms in the message 4109 structure. In addition to checking that algorithms are correct, the 4110 key form needs to be checked as well. Do not use an 'EC2' key where 4111 an 'OKP' key is expected. 4113 Before using a key for transmission, or before acting on information 4114 received, a trust decision on a key needs to be made. Is the data or 4115 action something that the entity associated with the key has a right 4116 to see or a right to request? A number of factors are associated 4117 with this trust decision. Some of the ones that are highlighted here 4118 are: 4120 o What are the permissions associated with the key owner? 4122 o Is the cryptographic algorithm acceptable in the current context? 4124 o Have the restrictions associated with the key, such as algorithm 4125 or freshness, been checked and are correct? 4127 o Is the request something that is reasonable, given the current 4128 state of the application? 4130 o Have any security considerations that are part of the message been 4131 enforced (as specified by the application or 'crit' parameter)? 4133 There are a large number of algorithms presented in this document 4134 that use nonce values. For all of the nonces defined in this 4135 document, there is some type of restriction on the nonce being a 4136 unique value either for a key or for some other conditions. In all 4137 of these cases, there is no known requirement on the nonce being both 4138 unique and unpredictable, under these circumstances it reasonable to 4139 use a counter for creation of the nonce. In cases where one wants 4140 the pattern of the nonce to be unpredictable as well as unique, one 4141 can use a key created for that purpose and encrypt the counter to 4142 produce the nonce value. 4144 One area that has been starting to get exposure is doing traffic 4145 analysis of encrypted messages based on the length of the message. 4146 This specification does not provide for a uniform method of providing 4147 padding as part of the message structure. An observer can 4148 distinguish between two different strings (for example, 'YES' and 4149 'NO') based on length for all of the content encryption algorithms 4150 that are defined in this document. This means that it is up to 4151 applications to document how content padding is to be done in order 4152 to prevent or discourage such analysis. (For example, the strings 4153 could be defined as 'YES' and 'NO '.) 4155 19. References 4157 19.1. Normative References 4159 [AES-GCM] Dworkin, M., "NIST Special Publication 800-38D: 4160 Recommendation for Block Cipher Modes of Operation: 4161 Galois/Counter Mode (GCM) and GMAC.", Nov 2007. 4163 [COAP.Formats] 4164 IANA, , "CoAP Content-Formats". 4166 [DSS] U.S. National Institute of Standards and Technology, 4167 "Digital Signature Standard (DSS)", July 2013. 4169 [I-D.irtf-cfrg-eddsa] 4170 Josefsson, S. and I. Liusvaara, "Edwards-curve Digital 4171 Signature Algorithm (EdDSA)", draft-irtf-cfrg-eddsa-08 4172 (work in progress), August 2016. 4174 [MAC] NiST, N., "FIPS PUB 113: Computer Data Authentication", 4175 May 1985. 4177 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 4178 Hashing for Message Authentication", RFC 2104, 4179 DOI 10.17487/RFC2104, February 1997, 4180 . 4182 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4183 Requirement Levels", BCP 14, RFC 2119, 4184 DOI 10.17487/RFC2119, March 1997, 4185 . 4187 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 4188 (AES) Key Wrap Algorithm", RFC 3394, DOI 10.17487/RFC3394, 4189 September 2002, . 4191 [RFC3610] Whiting, D., Housley, R., and N. Ferguson, "Counter with 4192 CBC-MAC (CCM)", RFC 3610, DOI 10.17487/RFC3610, September 4193 2003, . 4195 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 4196 Key Derivation Function (HKDF)", RFC 5869, 4197 DOI 10.17487/RFC5869, May 2010, 4198 . 4200 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 4201 Curve Cryptography Algorithms", RFC 6090, 4202 DOI 10.17487/RFC6090, February 2011, 4203 . 4205 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 4206 Algorithm (DSA) and Elliptic Curve Digital Signature 4207 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 4208 2013, . 4210 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 4211 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 4212 October 2013, . 4214 [RFC7539] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF 4215 Protocols", RFC 7539, DOI 10.17487/RFC7539, May 2015, 4216 . 4218 [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 4219 for Security", RFC 7748, DOI 10.17487/RFC7748, January 4220 2016, . 4222 [SEC1] Standards for Efficient Cryptography Group, "SEC 1: 4223 Elliptic Curve Cryptography", May 2009. 4225 19.2. Informative References 4227 [I-D.greevenbosch-appsawg-cbor-cddl] 4228 Vigano, C. and H. Birkholz, "CBOR data definition language 4229 (CDDL): a notational convention to express CBOR data 4230 structures", draft-greevenbosch-appsawg-cbor-cddl-09 (work 4231 in progress), September 2016. 4233 [I-D.moriarty-pkcs1] 4234 Moriarty, K., Kaliski, B., Jonsson, J., and A. Rusch, 4235 "PKCS #1 Version 2.2: RSA Cryptography Specifications", 4236 draft-moriarty-pkcs1-03 (work in progress), September 4237 2016. 4239 [I-D.moriarty-pkcs5-v2dot1] 4240 Moriarty, K., Kaliski, B., and A. Rusch, "PKCS #5: 4241 Password-Based Cryptography Specification Version 2.1", 4242 draft-moriarty-pkcs5-v2dot1-04 (work in progress), 4243 September 2016. 4245 [I-D.selander-ace-object-security] 4246 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 4247 "Object Security of CoAP (OSCOAP)", draft-selander-ace- 4248 object-security-06 (work in progress), October 2016. 4250 [PVSig] Brown, D. and D. Johnson, "Formal Security Proofs for a 4251 Signature Scheme with Partial Message Recover", February 4252 2000. 4254 [RFC2633] Ramsdell, B., Ed., "S/MIME Version 3 Message 4255 Specification", RFC 2633, DOI 10.17487/RFC2633, June 1999, 4256 . 4258 [RFC4231] Nystrom, M., "Identifiers and Test Vectors for HMAC-SHA- 4259 224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512", 4260 RFC 4231, DOI 10.17487/RFC4231, December 2005, 4261 . 4263 [RFC4262] Santesson, S., "X.509 Certificate Extension for Secure/ 4264 Multipurpose Internet Mail Extensions (S/MIME) 4265 Capabilities", RFC 4262, DOI 10.17487/RFC4262, December 4266 2005, . 4268 [RFC4493] Song, JH., Poovendran, R., Lee, J., and T. Iwata, "The 4269 AES-CMAC Algorithm", RFC 4493, DOI 10.17487/RFC4493, June 4270 2006, . 4272 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 4273 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 4274 . 4276 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 4277 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 4278 . 4280 [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, 4281 "Elliptic Curve Cryptography Subject Public Key 4282 Information", RFC 5480, DOI 10.17487/RFC5480, March 2009, 4283 . 4285 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 4286 RFC 5652, DOI 10.17487/RFC5652, September 2009, 4287 . 4289 [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet 4290 Mail Extensions (S/MIME) Version 3.2 Message 4291 Specification", RFC 5751, DOI 10.17487/RFC5751, January 4292 2010, . 4294 [RFC5752] Turner, S. and J. Schaad, "Multiple Signatures in 4295 Cryptographic Message Syntax (CMS)", RFC 5752, 4296 DOI 10.17487/RFC5752, January 2010, 4297 . 4299 [RFC5990] Randall, J., Kaliski, B., Brainard, J., and S. Turner, 4300 "Use of the RSA-KEM Key Transport Algorithm in the 4301 Cryptographic Message Syntax (CMS)", RFC 5990, 4302 DOI 10.17487/RFC5990, September 2010, 4303 . 4305 [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations 4306 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 4307 RFC 6151, DOI 10.17487/RFC6151, March 2011, 4308 . 4310 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 4311 Specifications and Registration Procedures", BCP 13, 4312 RFC 6838, DOI 10.17487/RFC6838, January 2013, 4313 . 4315 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 4316 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 4317 2014, . 4319 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 4320 Application Protocol (CoAP)", RFC 7252, 4321 DOI 10.17487/RFC7252, June 2014, 4322 . 4324 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 4325 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 4326 2015, . 4328 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 4329 RFC 7516, DOI 10.17487/RFC7516, May 2015, 4330 . 4332 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 4333 DOI 10.17487/RFC7517, May 2015, 4334 . 4336 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 4337 DOI 10.17487/RFC7518, May 2015, 4338 . 4340 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 4341 Code: The Implementation Status Section", BCP 205, 4342 RFC 7942, DOI 10.17487/RFC7942, July 2016, 4343 . 4345 [SP800-56A] 4346 Barker, E., Chen, L., Roginsky, A., and M. Smid, "NIST 4347 Special Publication 800-56A: Recommendation for Pair-Wise 4348 Key Establishment Schemes Using Discrete Logarithm 4349 Cryptography", May 2013. 4351 [W3C.WebCrypto] 4352 Watson, M., "Web Cryptography API", July 2016. 4354 Appendix A. Guidelines for External Data Authentication of Algorithms 4356 There has been a portion of the working group who have expressed a 4357 strong desire to relax the rule that the algorithm identifier be 4358 required to appear in each level of a COSE object. There are two 4359 basic reasons that have been advanced to support this position. 4360 First, the resulting message will be smaller if the algorithm 4361 identifier is omitted from the most common messages in a CoAP 4362 environment. Second, there is a potential bug that will arise if 4363 full checking is not done correctly between the different places that 4364 an algorithm identifier could be placed (the message itself, an 4365 application statement, the key structure that the sender possesses 4366 and the key structure the recipient possesses). 4368 This appendix lays out how such a change can be made and the details 4369 that an application needs to specify in order to use this option. 4370 Two different sets of details are specified: Those needed to omit an 4371 algorithm identifier and those needed to use a variant on the counter 4372 signature attribute that contains no attributes about itself. 4374 A.1. Algorithm Identification 4376 In this section are laid out three sets of recommendations. The 4377 first set of recommendations apply to having an implicit algorithm 4378 identified for a single layer of a COSE object. The second set of 4379 recommendations apply to having multiple implicit algorithms 4380 identified for multiple layers of a COSE object. The third set of 4381 recommendations apply to having implicit algorithms for multiple COSE 4382 object constructs. 4384 RFC 2119 language is deliberately not used here. This specification 4385 can provide recommendations, but it cannot enforce them. 4387 This set of recommendations applies to the case where an application 4388 is distributing a fixed algorithm along with the key information for 4389 use in a single COSE object. This normally applies to the smallest 4390 of the COSE objects, specifically COSE_Sign1, COSE_Mac0, and 4391 COSE_Encrypt0, but could apply to the other structures as well. 4393 The following items should be taken into account: 4395 o Applications need to list the set of COSE structures that implicit 4396 algorithms are to be used in. Applications need to require that 4397 the receipt of an explicit algorithm identifier in one of these 4398 structures will lead to the message being rejected. This 4399 requirement is stated so that there will never be a case where 4400 there is any ambiguity about the question of which algorithm 4401 should be used, the implicit or the explicit one. This applies 4402 even if the transported algorithm identifier is a protected 4403 attribute. This applies even if the transported algorithm is the 4404 same as the implicit algorithm. 4406 o Applications need to define the set of information that is to be 4407 considered to be part of a context when omitting algorithm 4408 identifiers. At a minimum, this would be the key identifier (if 4409 needed), the key, the algorithm, and the COSE structure it is used 4410 with. Applications should restrict the use of a single key to a 4411 single algorithm. As noted for some of the algorithms in this 4412 document, the use of the same key in different related algorithms 4413 can lead to leakage of information about the key, leakage about 4414 the data or the ability to perform forgeries. 4416 o In many cases, applications that make the algorithm identifier 4417 implicit will also want to make the context identifier implicit 4418 for the same reason. That is, omitting the context identifier 4419 will decrease the message size (potentially significantly 4420 depending on the length of the identifier). Applications that do 4421 this will need to describe the circumstances where the context 4422 identifier is to be omitted and how the context identifier is to 4423 be inferred in these cases. (Exhaustive search over all of the 4424 keys would normally not be considered to be acceptable.) An 4425 example of how this can be done is to tie the context to a 4426 transaction identifier. Both would be sent on the original 4427 message, but only the transaction identifier would need to be sent 4428 after that point as the context is tied into the transaction 4429 identifier. Another way would be to associate a context with a 4430 network address. All messages coming from a single network 4431 address can be assumed to be associated with a specific context. 4432 (In this case the address would normally be distributed as part of 4433 the context.) 4435 o Applications cannot rely on key identifiers being unique unless 4436 they take significant efforts to ensure that they are computed in 4437 such a way as to create this guarantee. Even when an application 4438 does this, the uniqueness might be violated if the application is 4439 run in different contexts (i.e., with a different context 4440 provider) or if the system combines the security contexts from 4441 different applications together into a single store. 4443 o Applications should continue the practice of protecting the 4444 algorithm identifier. Since this is not done by placing it in the 4445 protected attributes field, applications should define an 4446 application specific external data structure that includes this 4447 value. This external data field can be used as such for content 4448 encryption, MAC, and signature algorithms. It can be used in the 4449 SuppPrivInfo field for those algorithms which use a KDF function 4450 to derive a key value. Applications may also want to protect 4451 other information that is part of the context structure as well. 4452 It should be noted that those fields, such as the key or a base 4453 IV, are protected by virtue of being used in the cryptographic 4454 computation and do not need to be included in the external data 4455 field. 4457 The second case is having multiple implicit algorithm identifiers 4458 specified for a multiple layer COSE object. An example of how this 4459 would work is the encryption context that an application specifies 4460 contains a content encryption algorithm, a key wrap algorithm, a key 4461 identifier, and a shared secret. The sender omits sending the 4462 algorithm identifier for both the content layer and the recipient 4463 layer leaving only the key identifier. The receiver then uses the 4464 key identifier to get the implicit algorithm identifiers. 4466 The following additional items need to be taken into consideration: 4468 o Applications that want to support this will need to define a 4469 structure that allows for, and clearly identifies, both the COSE 4470 structure to be used with a given key and the structure and 4471 algorithm to be used for the secondary layer. The key for the 4472 secondary layer is computed per normal from the recipient layer. 4474 The third case is having multiple implicit algorithm identifiers, but 4475 targeted at potentially unrelated layers or different COSE objects. 4477 There are a number of different scenarios where this might be 4478 applicable. Some of these scenarios are: 4480 o Two contexts are distributed as a pair. Each of the contexts is 4481 for use with a COSE_Encrypt message. Each context will consist of 4482 distinct secret keys and IVs and potentially even different 4483 algorithms. One context is for sending messages from party A to 4484 party B, the second context is for sending messages from party B 4485 to party A. This means that there is no chance for a reflection 4486 attack to occur as each party uses different secret keys to send 4487 its messages, a message that is reflected back to it would fail to 4488 decrypt. 4490 o Two contexts are distributed as a pair. The first context is used 4491 for encryption of the message; the second context is used to place 4492 a counter signature on the message. The intention is that the 4493 second context can be distributed to other entities independently 4494 of the first context. This allows these entities to validate that 4495 the message came from an individual without being able to decrypt 4496 the message and see the content. 4498 o Two contexts are distributed as a pair. The first context 4499 contains a key for dealing with MACed messages, the second context 4500 contains a key for dealing with encrypted messages. This allows 4501 for a unified distribution of keys to participants for different 4502 types of messages that have different keys, but where the keys may 4503 be used in coordinated manner. 4505 For these cases, the following additional items need to be 4506 considered: 4508 o Applications need to ensure that the multiple contexts stay 4509 associated. If one of the contexts is invalidated for any reason, 4510 all of the contexts associated with it should also be invalidated. 4512 A.2. Counter Signature Without Headers 4514 There is a group of people who want to have a counter signature 4515 parameter that is directly tied to the value being signed and thus 4516 the authenticated and unauthenticated buckets can be removed from the 4517 message being sent. The focus on this is an even smaller size, as 4518 all of the information on the process of creating the counter 4519 signature is implicit rather than being explicitly carried in the 4520 message. This includes not only the algorithm identifier as 4521 presented above, but also items such as the key identification is 4522 always external to the signature structure. This means that the 4523 entities that are doing the validation of the counter signature are 4524 required to infer which key is to be used from context rather than 4525 being explicit. One way of doing this would be to presume that all 4526 data coming from a specific port (or to a specific URL) is to be 4527 validated by a specific key. (Note that this does not require that 4528 the key identifier be part of the value signed as it does not serve a 4529 cryptographic purpose. If the key validates the counter signature, 4530 then it should be presumed that the entity associated with that key 4531 produced the signature.) 4533 When computing the signature for the bare counter signature header, 4534 the same Sig_structure defined in Section 4.4 is used. The 4535 sign_protected field is omitted, as there is no protected header 4536 field in in this counter signature header. The value of 4537 "CounterSignature0" is placed in the context field of the 4538 Sig_stucture. 4540 +-------------------+-------+-------+-------+-----------------------+ 4541 | name | label | value | value | description | 4542 | | | type | | | 4543 +-------------------+-------+-------+-------+-----------------------+ 4544 | CounterSignature0 | 9 | bstr | | Counter signature | 4545 | | | | | with implied signer | 4546 | | | | | and headers | 4547 +-------------------+-------+-------+-------+-----------------------+ 4549 Table 27 4551 Appendix B. Two Layers of Recipient Information 4553 All of the currently defined recipient algorithms classes only use 4554 two layers of the COSE_Encrypt structure. The first layer is the 4555 message content and the second layer is the content key encryption. 4556 However, if one uses a recipient algorithm such as RSA-KEM (see 4557 Appendix A of RSA-KEM [RFC5990]), then it makes sense to have three 4558 layers of the COSE_Encrypt structure. 4560 These layers would be: 4562 o Layer 0: The content encryption layer. This layer contains the 4563 payload of the message. 4565 o Layer 1: The encryption of the CEK by a KEK. 4567 o Layer 2: The encryption of a long random secret using an RSA key 4568 and a key derivation function to convert that secret into the KEK. 4570 This is an example of what a triple layer message would look like. 4571 The message has the following layers: 4573 o Layer 0: Has a content encrypted with AES-GCM using a 128-bit key. 4575 o Layer 1: Uses the AES Key wrap algorithm with a 128-bit key. 4577 o Layer 2: Uses ECDH Ephemeral-Static direct to generate the layer 1 4578 key. 4580 In effect, this example is a decomposed version of using the ECDH- 4581 ES+A128KW algorithm. 4583 Size of binary file is 183 bytes 4584 96( 4585 [ 4586 / protected / h'a10101' / { 4587 \ alg \ 1:1 \ AES-GCM 128 \ 4588 } / , 4589 / unprotected / { 4590 / iv / 5:h'02d1f7e6f26c43d4868d87ce' 4591 }, 4592 / ciphertext / h'64f84d913ba60a76070a9a48f26e97e863e2852948658f0 4593 811139868826e89218a75715b', 4594 / recipients / [ 4595 [ 4596 / protected / h'', 4597 / unprotected / { 4598 / alg / 1:-3 / A128KW / 4599 }, 4600 / ciphertext / h'dbd43c4e9d719c27c6275c67d628d493f090593db82 4601 18f11', 4602 / recipients / [ 4603 [ 4604 / protected / h'a1013818' / { 4605 \ alg \ 1:-25 \ ECDH-ES + HKDF-256 \ 4606 } / , 4607 / unprotected / { 4608 / ephemeral / -1:{ 4609 / kty / 1:2, 4610 / crv / -1:1, 4611 / x / -2:h'b2add44368ea6d641f9ca9af308b4079aeb519f11 4612 e9b8a55a600b21233e86e68', 4613 / y / -3:false 4614 }, 4615 / kid / 4:'meriadoc.brandybuck@buckland.example' 4616 }, 4617 / ciphertext / h'' 4618 ] 4619 ] 4620 ] 4621 ] 4622 ] 4623 ) 4625 Appendix C. Examples 4627 This appendix includes a set of examples that show the different 4628 features and message types that have been defined in this document. 4629 To make the examples easier to read, they are presented using the 4630 extended CBOR diagnostic notation (defined in 4631 [I-D.greevenbosch-appsawg-cbor-cddl]) rather than as a binary dump. 4633 A GitHub project has been created at https://github.com/cose-wg/ 4634 Examples that contains not only the examples presented in this 4635 document, but a more complete set of testing examples as well. Each 4636 example is found in a JSON file that contains the inputs used to 4637 create the example, some of the intermediate values that can be used 4638 in debugging the example and the output of the example presented in 4639 both a hex and a CBOR diagnostic notation format. Some of the 4640 examples at the site are designed failure testing cases; these are 4641 clearly marked as such in the JSON file. If errors in the examples 4642 in this document are found, the examples on github will be updated 4643 and a note to that effect will be placed in the JSON file. 4645 As noted, the examples are presented using the CBOR's diagnostic 4646 notation. A Ruby based tool exists that can convert between the 4647 diagnostic notation and binary. This tool can be installed with the 4648 command line: 4650 gem install cbor-diag 4652 The diagnostic notation can be converted into binary files using the 4653 following command line: 4655 diag2cbor.rb < inputfile > outputfile 4657 The examples can be extracted from the XML version of this document 4658 via an XPath expression as all of the artwork is tagged with the 4659 attribute type='CBORdiag'. (Depending on the XPath evaluator one is 4660 using, it may be necessary to deal with > as an entity.) 4662 //artwork[@type='CDDL']/text() 4664 C.1. Examples of Signed Message 4666 C.1.1. Single Signature 4668 This example uses the following: 4670 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 4672 Size of binary file is 103 bytes 4673 98( 4674 [ 4675 / protected / h'', 4676 / unprotected / {}, 4677 / payload / 'This is the content.', 4678 / signatures / [ 4679 [ 4680 / protected / h'a10126' / { 4681 \ alg \ 1:-7 \ ECDSA 256 \ 4682 } / , 4683 / unprotected / { 4684 / kid / 4:'11' 4685 }, 4686 / signature / h'e2aeafd40d69d19dfe6e52077c5d7ff4e408282cbefb 4687 5d06cbf414af2e19d982ac45ac98b8544c908b4507de1e90b717c3d34816fe926a2b 4688 98f53afd2fa0f30a' 4689 ] 4690 ] 4691 ] 4692 ) 4694 C.1.2. Multiple Signers 4696 This example uses the following: 4698 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 4700 o Signature Algorithm: ECDSA w/ SHA-512, Curve P-521 4702 Size of binary file is 277 bytes 4703 98( 4704 [ 4705 / protected / h'', 4706 / unprotected / {}, 4707 / payload / 'This is the content.', 4708 / signatures / [ 4709 [ 4710 / protected / h'a10126' / { 4711 \ alg \ 1:-7 \ ECDSA 256 \ 4712 } / , 4713 / unprotected / { 4714 / kid / 4:'11' 4715 }, 4716 / signature / h'e2aeafd40d69d19dfe6e52077c5d7ff4e408282cbefb 4717 5d06cbf414af2e19d982ac45ac98b8544c908b4507de1e90b717c3d34816fe926a2b 4718 98f53afd2fa0f30a' 4719 ], 4720 [ 4721 / protected / h'a1013823' / { 4722 \ alg \ 1:-36 4723 } / , 4724 / unprotected / { 4725 / kid / 4:'bilbo.baggins@hobbiton.example' 4726 }, 4727 / signature / h'00a2d28a7c2bdb1587877420f65adf7d0b9a06635dd1 4728 de64bb62974c863f0b160dd2163734034e6ac003b01e8705524c5c4ca479a952f024 4729 7ee8cb0b4fb7397ba08d009e0c8bf482270cc5771aa143966e5a469a09f613488030 4730 c5b07ec6d722e3835adb5b2d8c44e95ffb13877dd2582866883535de3bb03d01753f 4731 83ab87bb4f7a0297' 4732 ] 4733 ] 4734 ] 4735 ) 4737 C.1.3. Counter Signature 4739 This example uses the following: 4741 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 4743 o The same parameters are used for both the signature and the 4744 counter signature. 4746 Size of binary file is 180 bytes 4747 98( 4748 [ 4749 / protected / h'', 4750 / unprotected / { 4751 / countersign / 7:[ 4752 / protected / h'a10126' / { 4753 \ alg \ 1:-7 \ ECDSA 256 \ 4754 } / , 4755 / unprotected / { 4756 / kid / 4:'11' 4757 }, 4758 / signature / h'5ac05e289d5d0e1b0a7f048a5d2b643813ded50bc9e4 4759 9220f4f7278f85f19d4a77d655c9d3b51e805a74b099e1e085aacd97fc29d72f887e 4760 8802bb6650cceb2c' 4761 ] 4762 }, 4763 / payload / 'This is the content.', 4764 / signatures / [ 4765 [ 4766 / protected / h'a10126' / { 4767 \ alg \ 1:-7 \ ECDSA 256 \ 4768 } / , 4769 / unprotected / { 4770 / kid / 4:'11' 4771 }, 4772 / signature / h'e2aeafd40d69d19dfe6e52077c5d7ff4e408282cbefb 4773 5d06cbf414af2e19d982ac45ac98b8544c908b4507de1e90b717c3d34816fe926a2b 4774 98f53afd2fa0f30a' 4775 ] 4776 ] 4777 ] 4778 ) 4780 C.1.4. Signature w/ Criticality 4782 This example uses the following: 4784 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 4786 o There is a criticality marker on the "reserved" header parameter 4788 Size of binary file is 125 bytes 4789 98( 4790 [ 4791 / protected / h'a2687265736572766564f40281687265736572766564' / 4792 { 4793 "reserved":false, 4794 \ crit \ 2:[ 4795 "reserved" 4796 ] 4797 } / , 4798 / unprotected / {}, 4799 / payload / 'This is the content.', 4800 / signatures / [ 4801 [ 4802 / protected / h'a10126' / { 4803 \ alg \ 1:-7 \ ECDSA 256 \ 4804 } / , 4805 / unprotected / { 4806 / kid / 4:'11' 4807 }, 4808 / signature / h'3fc54702aa56e1b2cb20284294c9106a63f91bac658d 4809 69351210a031d8fc7c5ff3e4be39445b1a3e83e1510d1aca2f2e8a7c081c7645042b 4810 18aba9d1fad1bd9c' 4811 ] 4812 ] 4813 ] 4814 ) 4816 C.2. Single Signer Examples 4818 C.2.1. Single ECDSA signature 4820 This example uses the following: 4822 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 4824 Size of binary file is 98 bytes 4825 18( 4826 [ 4827 / protected / h'a10126' / { 4828 \ alg \ 1:-7 \ ECDSA 256 \ 4829 } / , 4830 / unprotected / { 4831 / kid / 4:'11' 4832 }, 4833 / payload / 'This is the content.', 4834 / signature / h'eae868ecc176883766c5dc5ba5b8dca25dab3c2e56a551ce 4835 5705b793914348e19f43d6c6ba654472da301b645b293c9ba939295b97c4bdb84778 4836 2bff384c5794' 4837 ] 4838 ) 4840 C.3. Examples of Enveloped Messages 4842 C.3.1. Direct ECDH 4844 This example uses the following: 4846 o CEK: AES-GCM w/ 128-bit key 4848 o Recipient class: ECDH Ephemeral-Static, Curve P-256 4850 Size of binary file is 151 bytes 4851 96( 4852 [ 4853 / protected / h'a10101' / { 4854 \ alg \ 1:1 \ AES-GCM 128 \ 4855 } / , 4856 / unprotected / { 4857 / iv / 5:h'c9cf4df2fe6c632bf7886413' 4858 }, 4859 / ciphertext / h'7adbe2709ca818fb415f1e5df66f4e1a51053ba6d65a1a0 4860 c52a357da7a644b8070a151b0', 4861 / recipients / [ 4862 [ 4863 / protected / h'a1013818' / { 4864 \ alg \ 1:-25 \ ECDH-ES + HKDF-256 \ 4865 } / , 4866 / unprotected / { 4867 / ephemeral / -1:{ 4868 / kty / 1:2, 4869 / crv / -1:1, 4870 / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf 4871 bf054e1c7b4d91d6280', 4872 / y / -3:true 4873 }, 4874 / kid / 4:'meriadoc.brandybuck@buckland.example' 4875 }, 4876 / ciphertext / h'' 4877 ] 4878 ] 4879 ] 4880 ) 4882 C.3.2. Direct plus Key Derivation 4884 This example uses the following: 4886 o CEK: AES-CCM w/128-bit key, truncate the tag to 64 bits 4888 o Recipient class: Use HKDF on a shared secret with the following 4889 implicit fields as part of the context. 4891 * salt: "aabbccddeeffgghh" 4893 * APU identity: "lighting-client" 4895 * APV identity: "lighting-server" 4897 * Supplementary Public Other: "Encryption Example 02" 4899 Size of binary file is 91 bytes 4901 96( 4902 [ 4903 / protected / h'a1010a' / { 4904 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 4905 } / , 4906 / unprotected / { 4907 / iv / 5:h'89f52f65a1c580933b5261a76c' 4908 }, 4909 / ciphertext / h'753548a19b1307084ca7b2056924ed95f2e3b17006dfe93 4910 1b687b847', 4911 / recipients / [ 4912 [ 4913 / protected / h'a10129' / { 4914 \ alg \ 1:-10 4915 } / , 4916 / unprotected / { 4917 / salt / -20:'aabbccddeeffgghh', 4918 / kid / 4:'our-secret' 4919 }, 4920 / ciphertext / h'' 4921 ] 4922 ] 4923 ] 4924 ) 4926 C.3.3. Counter Signature on Encrypted Content 4928 This example uses the following: 4930 o CEK: AES-GCM w/ 128-bit key 4932 o Recipient class: ECDH Ephemeral-Static, Curve P-256 4934 Size of binary file is 326 bytes 4935 96( 4936 [ 4937 / protected / h'a10101' / { 4938 \ alg \ 1:1 \ AES-GCM 128 \ 4939 } / , 4940 / unprotected / { 4941 / iv / 5:h'c9cf4df2fe6c632bf7886413', 4942 / countersign / 7:[ 4943 / protected / h'a1013823' / { 4944 \ alg \ 1:-36 4945 } / , 4946 / unprotected / { 4947 / kid / 4:'bilbo.baggins@hobbiton.example' 4948 }, 4949 / signature / h'00929663c8789bb28177ae28467e66377da12302d7f9 4950 594d2999afa5dfa531294f8896f2b6cdf1740014f4c7f1a358e3a6cf57f4ed6fb02f 4951 cf8f7aa989f5dfd07f0700a3a7d8f3c604ba70fa9411bd10c2591b483e1d2c31de00 4952 3183e434d8fba18f17a4c7e3dfa003ac1cf3d30d44d2533c4989d3ac38c38b71481c 4953 c3430c9d65e7ddff' 4954 ] 4955 }, 4956 / ciphertext / h'7adbe2709ca818fb415f1e5df66f4e1a51053ba6d65a1a0 4957 c52a357da7a644b8070a151b0', 4958 / recipients / [ 4959 [ 4960 / protected / h'a1013818' / { 4961 \ alg \ 1:-25 \ ECDH-ES + HKDF-256 \ 4962 } / , 4963 / unprotected / { 4964 / ephemeral / -1:{ 4965 / kty / 1:2, 4966 / crv / -1:1, 4967 / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf 4968 bf054e1c7b4d91d6280', 4969 / y / -3:true 4970 }, 4971 / kid / 4:'meriadoc.brandybuck@buckland.example' 4972 }, 4973 / ciphertext / h'' 4974 ] 4975 ] 4976 ] 4977 ) 4979 C.3.4. Encrypted Content with External Data 4981 This example uses the following: 4983 o CEK: AES-GCM w/ 128-bit key 4985 o Recipient class: ECDH static-Static, Curve P-256 with AES Key Wrap 4987 o Externally Supplied AAD: h'0011bbcc22dd44ee55ff660077' 4989 Size of binary file is 173 bytes 4991 96( 4992 [ 4993 / protected / h'a10101' / { 4994 \ alg \ 1:1 \ AES-GCM 128 \ 4995 } / , 4996 / unprotected / { 4997 / iv / 5:h'02d1f7e6f26c43d4868d87ce' 4998 }, 4999 / ciphertext / h'64f84d913ba60a76070a9a48f26e97e863e28529d8f5335 5000 e5f0165eee976b4a5f6c6f09d', 5001 / recipients / [ 5002 [ 5003 / protected / h'a101381f' / { 5004 \ alg \ 1:-32 \ ECHD-SS+A128KW \ 5005 } / , 5006 / unprotected / { 5007 / static kid / -3:'peregrin.took@tuckborough.example', 5008 / kid / 4:'meriadoc.brandybuck@buckland.example', 5009 / U nonce / -22:h'0101' 5010 }, 5011 / ciphertext / h'41e0d76f579dbd0d936a662d54d8582037de2e366fd 5012 e1c62' 5013 ] 5014 ] 5015 ] 5016 ) 5018 C.4. Examples of Encrypted Messages 5020 C.4.1. Simple Encrypted Message 5022 This example uses the following: 5024 o CEK: AES-CCM w/ 128-bit key and a 64-bit tag 5026 Size of binary file is 52 bytes 5027 16( 5028 [ 5029 / protected / h'a1010a' / { 5030 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 5031 } / , 5032 / unprotected / { 5033 / iv / 5:h'89f52f65a1c580933b5261a78c' 5034 }, 5035 / ciphertext / h'5974e1b99a3a4cc09a659aa2e9e7fff161d38ce7edd5617 5036 388e77baf' 5037 ] 5038 ) 5040 C.4.2. Encrypted Message w/ a Partial IV 5042 This example uses the following: 5044 o CEK: AES-CCM w/ 128-bit key and a 64-bit tag 5046 o Prefix for IV is 89F52F65A1C580933B52 5048 Size of binary file is 41 bytes 5050 16( 5051 [ 5052 / protected / h'a1010a' / { 5053 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 5054 } / , 5055 / unprotected / { 5056 / partial iv / 6:h'61a7' 5057 }, 5058 / ciphertext / h'252a8911d465c125b6764739700f0141ed09192da5c69e5 5059 33abf852b' 5060 ] 5061 ) 5063 C.5. Examples of MACed messages 5065 C.5.1. Shared Secret Direct MAC 5067 This example uses the following: 5069 o MAC: AES-CMAC, 256-bit key, truncated to 64 bits 5071 o Recipient class: direct shared secret 5073 Size of binary file is 57 bytes 5074 97( 5075 [ 5076 / protected / h'a1010f' / { 5077 \ alg \ 1:15 \ AES-CBC-MAC-256//64 \ 5078 } / , 5079 / unprotected / {}, 5080 / payload / 'This is the content.', 5081 / tag / h'9e1226ba1f81b848', 5082 / recipients / [ 5083 [ 5084 / protected / h'', 5085 / unprotected / { 5086 / alg / 1:-6 / direct /, 5087 / kid / 4:'our-secret' 5088 }, 5089 / ciphertext / h'' 5090 ] 5091 ] 5092 ] 5093 ) 5095 C.5.2. ECDH Direct MAC 5097 This example uses the following: 5099 o MAC: HMAC w/SHA-256, 256-bit key 5101 o Recipient class: ECDH key agreement, two static keys, HKDF w/ 5102 context structure 5104 Size of binary file is 214 bytes 5105 97( 5106 [ 5107 / protected / h'a10105' / { 5108 \ alg \ 1:5 \ HMAC 256//256 \ 5109 } / , 5110 / unprotected / {}, 5111 / payload / 'This is the content.', 5112 / tag / h'81a03448acd3d305376eaa11fb3fe416a955be2cbe7ec96f012c99 5113 4bc3f16a41', 5114 / recipients / [ 5115 [ 5116 / protected / h'a101381a' / { 5117 \ alg \ 1:-27 \ ECDH-SS + HKDF-256 \ 5118 } / , 5119 / unprotected / { 5120 / static kid / -3:'peregrin.took@tuckborough.example', 5121 / kid / 4:'meriadoc.brandybuck@buckland.example', 5122 / U nonce / -22:h'4d8553e7e74f3c6a3a9dd3ef286a8195cbf8a23d 5123 19558ccfec7d34b824f42d92bd06bd2c7f0271f0214e141fb779ae2856abf585a583 5124 68b017e7f2a9e5ce4db5' 5125 }, 5126 / ciphertext / h'' 5127 ] 5128 ] 5129 ] 5130 ) 5132 C.5.3. Wrapped MAC 5134 This example uses the following: 5136 o MAC: AES-MAC, 128-bit key, truncated to 64 bits 5138 o Recipient class: AES keywrap w/ a pre-shared 256-bit key 5140 Size of binary file is 109 bytes 5141 97( 5142 [ 5143 / protected / h'a1010e' / { 5144 \ alg \ 1:14 \ AES-CBC-MAC-128//64 \ 5145 } / , 5146 / unprotected / {}, 5147 / payload / 'This is the content.', 5148 / tag / h'36f5afaf0bab5d43', 5149 / recipients / [ 5150 [ 5151 / protected / h'', 5152 / unprotected / { 5153 / alg / 1:-5 / A256KW /, 5154 / kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037' 5155 }, 5156 / ciphertext / h'711ab0dc2fc4585dce27effa6781c8093eba906f227 5157 b6eb0' 5158 ] 5159 ] 5160 ] 5161 ) 5163 C.5.4. Multi-recipient MACed message 5165 This example uses the following: 5167 o MAC: HMAC w/ SHA-256, 128-bit key 5169 o Recipient class: Uses three different methods 5171 1. ECDH Ephemeral-Static, Curve P-521, AES-Key Wrap w/ 128-bit 5172 key 5174 2. AES-Key Wrap w/ 256-bit key 5176 Size of binary file is 309 bytes 5177 97( 5178 [ 5179 / protected / h'a10105' / { 5180 \ alg \ 1:5 \ HMAC 256//256 \ 5181 } / , 5182 / unprotected / {}, 5183 / payload / 'This is the content.', 5184 / tag / h'bf48235e809b5c42e995f2b7d5fa13620e7ed834e337f6aa43df16 5185 1e49e9323e', 5186 / recipients / [ 5187 [ 5188 / protected / h'a101381c' / { 5189 \ alg \ 1:-29 \ ECHD-ES+A128KW \ 5190 } / , 5191 / unprotected / { 5192 / ephemeral / -1:{ 5193 / kty / 1:2, 5194 / crv / -1:3, 5195 / x / -2:h'0043b12669acac3fd27898ffba0bcd2e6c366d53bc4db 5196 71f909a759304acfb5e18cdc7ba0b13ff8c7636271a6924b1ac63c02688075b55ef2 5197 d613574e7dc242f79c3', 5198 / y / -3:true 5199 }, 5200 / kid / 4:'bilbo.baggins@hobbiton.example' 5201 }, 5202 / ciphertext / h'339bc4f79984cdc6b3e6ce5f315a4c7d2b0ac466fce 5203 a69e8c07dfbca5bb1f661bc5f8e0df9e3eff5' 5204 ], 5205 [ 5206 / protected / h'', 5207 / unprotected / { 5208 / alg / 1:-5 / A256KW /, 5209 / kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037' 5210 }, 5211 / ciphertext / h'0b2c7cfce04e98276342d6476a7723c090dfdd15f9a 5212 518e7736549e998370695e6d6a83b4ae507bb' 5213 ] 5214 ] 5215 ] 5216 ) 5218 C.6. Examples of MAC0 messages 5220 C.6.1. Shared Secret Direct MAC 5222 This example uses the following: 5224 o MAC: AES-CMAC, 256-bit key, truncated to 64 bits 5225 o Recipient class: direct shared secret 5227 Size of binary file is 37 bytes 5229 17( 5230 [ 5231 / protected / h'a1010f' / { 5232 \ alg \ 1:15 \ AES-CBC-MAC-256//64 \ 5233 } / , 5234 / unprotected / {}, 5235 / payload / 'This is the content.', 5236 / tag / h'726043745027214f' 5237 ] 5238 ) 5240 Note that this example uses the same inputs as Appendix C.5.1. 5242 C.7. COSE Keys 5244 C.7.1. Public Keys 5246 This is an example of a COSE Key set. This example includes the 5247 public keys for all of the previous examples. 5249 In order the keys are: 5251 o An EC key with a kid of "meriadoc.brandybuck@buckland.example" 5253 o An EC key with a kid of "peregrin.took@tuckborough.example" 5255 o An EC key with a kid of "bilbo.baggins@hobbiton.example" 5257 o An EC key with a kid of "11" 5259 Size of binary file is 481 bytes 5261 [ 5262 { 5263 -1:1, 5264 -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0 5265 8551d', 5266 -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008 5267 4d19c', 5268 1:2, 5269 2:'meriadoc.brandybuck@buckland.example' 5270 }, 5271 { 5272 -1:1, 5273 -2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a 5274 09eff', 5275 -3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbf 5276 c117e', 5277 1:2, 5278 2:'11' 5279 }, 5280 { 5281 -1:3, 5282 -2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737bf5de 5283 7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620085e5c8 5284 f42ad', 5285 -3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e247e 5286 60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3fe1ea1 5287 d9475', 5288 1:2, 5289 2:'bilbo.baggins@hobbiton.example' 5290 }, 5291 { 5292 -1:1, 5293 -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b4d91 5294 d6280', 5295 -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e03bf 5296 822bb', 5297 1:2, 5298 2:'peregrin.took@tuckborough.example' 5299 } 5300 ] 5302 C.7.2. Private Keys 5304 This is an example of a COSE Key set. This example includes the 5305 private keys for all of the previous examples. 5307 In order the keys are: 5309 o An EC key with a kid of "meriadoc.brandybuck@buckland.example" 5311 o A shared-secret key with a kid of "our-secret" 5313 o An EC key with a kid of "peregrin.took@tuckborough.example" 5315 o A shared-secret key with a kid of "018c0ae5-4d9b-471b- 5316 bfd6-eef314bc7037" 5318 o An EC key with a kid of "bilbo.baggins@hobbiton.example" 5320 o An EC key with a kid of "11" 5322 Size of binary file is 816 bytes 5324 [ 5325 { 5326 1:2, 5327 2:'meriadoc.brandybuck@buckland.example', 5328 -1:1, 5329 -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0 5330 8551d', 5331 -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008 5332 4d19c', 5333 -4:h'aff907c99f9ad3aae6c4cdf21122bce2bd68b5283e6907154ad911840fa 5334 208cf' 5335 }, 5336 { 5337 1:2, 5338 2:'11', 5339 -1:1, 5340 -2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a 5341 09eff', 5342 -3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbf 5343 c117e', 5344 -4:h'57c92077664146e876760c9520d054aa93c3afb04e306705db609030850 5345 7b4d3' 5346 }, 5347 { 5348 1:2, 5349 2:'bilbo.baggins@hobbiton.example', 5350 -1:3, 5351 -2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737bf5de 5352 7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620085e5c8 5353 f42ad', 5354 -3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e247e 5355 60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3fe1ea1 5356 d9475', 5357 -4:h'00085138ddabf5ca975f5860f91a08e91d6d5f9a76ad4018766a476680b 5358 55cd339e8ab6c72b5facdb2a2a50ac25bd086647dd3e2e6e99e84ca2c3609fdf177f 5359 eb26d' 5360 }, 5361 { 5362 1:4, 5363 2:'our-secret', 5364 -1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dcea6c4 5365 27188' 5366 }, 5367 { 5368 1:2, 5369 -1:1, 5370 2:'peregrin.took@tuckborough.example', 5371 -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b4d91 5372 d6280', 5373 -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e03bf 5374 822bb', 5375 -4:h'02d1f7e6f26c43d4868d87ceb2353161740aacf1f7163647984b522a848 5376 df1c3' 5377 }, 5378 { 5379 1:4, 5380 2:'our-secret2', 5381 -1:h'849b5786457c1491be3a76dcea6c4271' 5382 }, 5383 { 5384 1:4, 5385 2:'018c0ae5-4d9b-471b-bfd6-eef314bc7037', 5386 -1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dcea6c4 5387 27188' 5388 } 5389 ] 5391 Acknowledgments 5393 This document is a product of the COSE working group of the IETF. 5395 The following individuals are to blame for getting me started on this 5396 project in the first place: Richard Barnes, Matt Miller, and Martin 5397 Thomson. 5399 The initial version of the draft was based to some degree on the 5400 outputs of the JOSE and S/MIME working groups. 5402 The following individuals provided input into the final form of the 5403 document: Carsten Bormann, John Bradley, Brain Campbell, Michael B. 5405 Jones, Ilari Liusvaara, Francesca Palombini, Goran Selander, and 5406 Ludwig Seitz. 5408 Author's Address 5410 Jim Schaad 5411 August Cellars 5413 Email: ietf@augustcellars.com