idnits 2.17.1 draft-ietf-cose-msg-19.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 746 has weird spacing: '...otected as de...' == Line 748 has weird spacing: '...otected as de...' == Line 750 has weird spacing: '...payload conta...' == Line 766 has weird spacing: '...natures is an...' == Line 781 has weird spacing: '...otected as de...' == (28 more instances...) -- The document date (September 27, 2016) is 2768 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'AES-GCM' -- Possible downref: Non-RFC (?) normative reference: ref. 'DSS' -- Possible downref: 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 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 7539 (Obsoleted by RFC 8439) -- 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 2898 (Obsoleted by RFC 8018) -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) -- 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: 7 errors (**), 0 flaws (~~), 8 warnings (==), 10 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 September 27, 2016 5 Expires: March 31, 2017 7 CBOR Object Signing and Encryption (COSE) 8 draft-ietf-cose-msg-19 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 March 31, 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 . . . . . . . . . . . . . . 21 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 . . . . . . . . . . . . . . 57 112 12.1. Direct Encryption . . . . . . . . . . . . . . . . . . . 58 113 12.1.1. Direct Key . . . . . . . . . . . . . . . . . . . . . 58 114 12.1.2. Direct Key with KDF . . . . . . . . . . . . . . . . 59 115 12.2. Key Wrapping . . . . . . . . . . . . . . . . . . . . . . 60 116 12.2.1. AES Key Wrapping . . . . . . . . . . . . . . . . . . 61 117 12.3. Key Transport . . . . . . . . . . . . . . . . . . . . . 62 118 12.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 62 119 12.4.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 63 120 12.4.2. Security Considerations . . . . . . . . . . . . . . 66 121 12.5. Key Agreement with Key Wrap . . . . . . . . . . . . . . 67 122 12.5.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 67 123 13. Key Object Parameters . . . . . . . . . . . . . . . . . . . . 69 124 13.1. Elliptic Curve Keys . . . . . . . . . . . . . . . . . . 69 125 13.1.1. Double Coordinate Curves . . . . . . . . . . . . . . 70 126 13.2. Octet Key Pair . . . . . . . . . . . . . . . . . . . . . 71 127 13.3. Symmetric Keys . . . . . . . . . . . . . . . . . . . . . 72 128 14. CBOR Encoder Restrictions . . . . . . . . . . . . . . . . . . 73 129 15. Application Profiling Considerations . . . . . . . . . . . . 73 130 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 75 131 16.1. CBOR Tag assignment . . . . . . . . . . . . . . . . . . 75 132 16.2. COSE Header Parameters Registry . . . . . . . . . . . . 75 133 16.3. COSE Header Algorithm Parameters Registry . . . . . . . 76 134 16.4. COSE Algorithms Registry . . . . . . . . . . . . . . . . 77 135 16.5. COSE Key Common Parameters Registry . . . . . . . . . . 77 136 16.6. COSE Key Type Parameters Registry . . . . . . . . . . . 78 137 16.7. COSE Key Type Registry . . . . . . . . . . . . . . . . . 79 138 16.8. COSE Elliptic Curve Parameters Registry . . . . . . . . 79 139 16.9. Media Type Registrations . . . . . . . . . . . . . . . . 80 140 16.9.1. COSE Security Message . . . . . . . . . . . . . . . 80 141 16.9.2. COSE Key media type . . . . . . . . . . . . . . . . 81 143 16.10. CoAP Content-Format Registrations . . . . . . . . . . . 83 144 16.11. Expert Review Instructions . . . . . . . . . . . . . . . 84 145 17. Implementation Status . . . . . . . . . . . . . . . . . . . . 85 146 17.1. Author's Versions . . . . . . . . . . . . . . . . . . . 86 147 17.2. COSE Testing Library . . . . . . . . . . . . . . . . . . 86 148 18. Security Considerations . . . . . . . . . . . . . . . . . . . 87 149 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 89 150 19.1. Normative References . . . . . . . . . . . . . . . . . . 89 151 19.2. Informative References . . . . . . . . . . . . . . . . . 90 152 Appendix A. Making Mandatory Algorithm Header Optional . . . . . 93 153 A.1. Algorithm Identification . . . . . . . . . . . . . . . . 93 154 A.2. Counter Signature Without Headers . . . . . . . . . . . . 96 155 Appendix B. Two Layers of Recipient Information . . . . . . . . 97 156 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 98 157 C.1. Examples of Signed Message . . . . . . . . . . . . . . . 99 158 C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 99 159 C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 100 160 C.1.3. Counter Signature . . . . . . . . . . . . . . . . . . 101 161 C.1.4. Signature w/ Criticality . . . . . . . . . . . . . . 102 162 C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 103 163 C.2.1. Single ECDSA signature . . . . . . . . . . . . . . . 103 164 C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 104 165 C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 104 166 C.3.2. Direct plus Key Derivation . . . . . . . . . . . . . 105 167 C.3.3. Counter Signature on Encrypted Content . . . . . . . 106 168 C.3.4. Encrypted Content with External Data . . . . . . . . 108 169 C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 108 170 C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 108 171 C.4.2. Encrypted Message w/ a Partial IV . . . . . . . . . . 109 172 C.5. Examples of MACed messages . . . . . . . . . . . . . . . 109 173 C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 109 174 C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 110 175 C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 111 176 C.5.4. Multi-recipient MACed message . . . . . . . . . . . . 112 177 C.6. Examples of MAC0 messages . . . . . . . . . . . . . . . . 113 178 C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 113 179 C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 114 180 C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 114 181 C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 115 182 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 117 183 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 118 185 1. Introduction 187 There has been an increased focus on small, constrained devices that 188 make up the Internet of Things (IoT). One of the standards that has 189 come out of this process is the Concise Binary Object Representation 190 (CBOR) [RFC7049]. CBOR extended the data model of the JavaScript 191 Object Notation (JSON) [RFC7159] by allowing for binary data, among 192 other changes. CBOR is being adopted by several of the IETF working 193 groups dealing with the IoT world as their encoding of data 194 structures. CBOR was designed specifically to be both small in terms 195 of messages transport and implementation size, as well having a 196 schema free decoder. A need exists to provide message security 197 services for IoT, using CBOR as the message encoding format makes 198 sense. 200 The JOSE working group produced a set of documents 201 [RFC7515][RFC7516][RFC7517][RFC7518] using JSON that specified how to 202 process encryption, signatures and message authentication (MAC) 203 operations, and how to encode keys using JSON. This document defines 204 the CBOR Object Encryption and Signing (COSE) standard which does the 205 same thing for the CBOR encoding format. While there is a strong 206 attempt to keep the flavor of the original JOSE documents, two 207 considerations are taken into account: 209 o CBOR has capabilities that are not present in JSON and are 210 appropriate to use. One example of this is the fact that CBOR has 211 a method of encoding binary directly without first converting it 212 into a base64 encoded string. 214 o COSE is not a direct copy of the JOSE specification. In the 215 process of creating COSE, decisions that were made for JOSE were 216 re-examined. In many cases different results were decided on as 217 the criteria was not always the same. 219 1.1. Design changes from JOSE 221 o Define a single top message structure so that encrypted, signed 222 and MACed messages can easily be identified and still have a 223 consistent view. 225 o Signed messages distinguish between the protected and unprotected 226 parameters that relate to the content from those that relate to 227 the signature. 229 o MACed messages are separated from signed messages. 231 o MACed messages have the ability to use the same set of recipient 232 algorithms as enveloped messages for obtaining the MAC 233 authentication key. 235 o Use binary encodings for binary data rather than base64url 236 encodings. 238 o Combine the authentication tag for encryption algorithms with the 239 cipher text. 241 o The set of cryptographic algorithms has been expanded in some 242 directions, and trimmed in others. 244 1.2. Requirements Terminology 246 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 247 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 248 "OPTIONAL" in this document are to be interpreted as described in 249 [RFC2119]. 251 When the words appear in lower case, their natural language meaning 252 is used. 254 1.3. CBOR Grammar 256 There currently is no standard CBOR grammar available for use by 257 specifications. The CBOR structures are therefore described in 258 prose. 260 The document was developed by first working on the grammar and then 261 developing the prose to go with it. An artifact of this is that the 262 prose was written using the primitive type strings defined by CBOR 263 Data Definition Language (CDDL) [I-D.greevenbosch-appsawg-cbor-cddl]. 264 In this specification, the following primitive types are used: 266 any - non-specific value that permits all CBOR values to be placed 267 here. 269 bool - a boolean value (true: major type 7, value 21; false: major 270 type 7, value 20). 272 bstr - byte string (major type 2). 274 int - an unsigned integer or a negative integer. 276 nil - a null value (major type 7, value 22). 278 nint - a negative integer (major type 1). 280 tstr - a UTF-8 text string (major type 3). 282 uint - an unsigned integer (major type 0). 284 As well as the prose description, a version of a CBOR grammar is 285 presented in CDDL. Since CDDL has not been published as an RFC, this 286 grammar may not work with the final version of CDDL. The CDDL 287 grammar is informational, the prose description is normative. 289 The collected CDDL can be extracted from the XML version of this 290 document via the following XPath expression below. (Depending on the 291 XPath evaluator one is using, it may be necessary to deal with > 292 as an entity.) 294 //artwork[@type='CDDL']/text() 296 CDDL expects the initial non-terminal symbol to be the first symbol 297 in the file. For this, reason the first fragment of CDDL is 298 presented here. 300 start = COSE_Messages / COSE_Key / COSE_KeySet / Internal_Types 302 ; This is defined to make the tool quieter: 303 Internal_Types = Sig_structure / Enc_structure / MAC_structure / 304 COSE_KDF_Context 306 The non-terminal Internal_Types is defined for dealing with the 307 automated validation tools used during the writing of this document. 308 It references those non-terminals that are used for security 309 computations, but are not emitted for transport. 311 1.4. CBOR Related Terminology 313 In JSON, maps are called objects and only have one kind of map key: a 314 string. In COSE, we use strings, negative integers and unsigned 315 integers as map keys. The integers are used for compactness of 316 encoding and easy comparison. The inclusion of strings allows for an 317 additional range of short encoded values to be used as well. Since 318 the word "key" is mainly used in its other meaning, as a 319 cryptographic key, we use the term "label" for this usage as a map 320 key. 322 The presence of a label in a COSE map which is not a string or an 323 integer is an error. Applications can either fail processing or 324 process messages with incorrect labels, however they MUST NOT create 325 messages with incorrect labels. 327 A CDDL grammar fragment is defined that defines the non-terminals 328 'label', as in the previous paragraph and 'values', which permits any 329 value to be used. 331 label = int / tstr 332 values = any 334 1.5. Document Terminology 336 In this document, we use the following terminology: 338 Byte is a synonym for octet. 340 Constrained Application Protocol (CoAP) is a specialized web transfer 341 protocol for use in constrained systems. It is defined in [RFC7252]. 343 Authenticated Encryption (AE) algorithms are those encryption 344 algorithms which provide an authentication check of the contents 345 algorithm with the encryption service. 347 Authenticated Encryption with Authenticated Data (AEAD) algorithms 348 provide the same content authentication service as AE algorithms, but 349 additionally provide for authentication of non-encrypted data as 350 well. 352 2. Basic COSE Structure 354 The COSE object structure is designed so that there can be a large 355 amount of common code when parsing and processing the different types 356 of security messages. All of the message structures are built on the 357 CBOR array type. The first three elements of the array always 358 contain the same information: 360 1. The set of protected header parameters wrapped in a bstr. 362 2. The set of unprotected header parameters as a map. 364 3. The content of the message. The content is either the plain text 365 or the cipher text as appropriate. The content may be detached, 366 but the location is still used. The content is wrapped in a bstr 367 when present and is a nil value when detached. 369 Elements after this point are dependent on the specific message type. 371 COSE messages are also built using the concept of layers to separate 372 different types of cryptographic concepts. As an example of how this 373 works consider the COSE_Encrypt message (Section 5.1). This message 374 type is broken into two layers: the content layer and the recipient 375 layer. In the content layer, the plain text is encrypted and 376 information about the encrypted message are placed. In the recipient 377 layer, the content encryption key (CEK) is encrypted and information 378 about how it is encrypted for each recipient is placed. A single 379 layer version of the encryption message COSE_Encrypt0 (Section 5.2) 380 is provided for cases where the CEK is pre-shared. 382 Identification of which type of message has been presented is done by 383 the following method: 385 1. The specific message type is known from the context. This may be 386 defined by a marker in the containing structure or by 387 restrictions specified by the application protocol. 389 2. The message type is identified by a CBOR tag. Messages with a 390 CBOR tag are known in this specification as tagged messages, 391 while those without the CBOR tag are known as untagged messages. 392 This document defines a CBOR tag for each of the message 393 structures. These tags can be found in Table 1. 395 3. When a COSE object is carried in a media type of application/ 396 cose, the optional parameter 'cose-type' can be used to identify 397 the embedded object. The parameter is OPTIONAL if the tagged 398 version of the structure is used. The parameter is REQUIRED if 399 the untagged version of the structure is used. The value to use 400 with the parameter for each of the structures can be found in 401 Table 1. 403 4. When a COSE object is carried as a CoAP payload, the CoAP 404 Content-Format Option can be used to identify the message 405 content. The CoAP Content-Format values can be found in 406 Table 26. The CBOR tag for the message structure is not required 407 as each security message is uniquely identified. 409 +-------+---------------+---------------+---------------------------+ 410 | CBOR | cose-type | Data Item | Semantics | 411 | Tag | | | | 412 +-------+---------------+---------------+---------------------------+ 413 | TBD1 | cose-sign | COSE_Sign | COSE Signed Data Object | 414 | | | | | 415 | TBD7 | cose-sign1 | COSE_Sign1 | COSE Single Signer Data | 416 | | | | Object | 417 | | | | | 418 | TBD2 | cose-encrypt | COSE_Encrypt | COSE Encrypted Data | 419 | | | | Object | 420 | | | | | 421 | TBD3 | cose-encrypt0 | COSE_Encrypt0 | COSE Single Recipient | 422 | | | | Encrypted Data Object | 423 | | | | | 424 | TBD4 | cose-mac | COSE_Mac | COSE Mac-ed Data Object | 425 | | | | | 426 | TBD6 | cose-mac0 | COSE_Mac0 | COSE Mac w/o Recipients | 427 | | | | Object | 428 +-------+---------------+---------------+---------------------------+ 430 Table 1: COSE Message Identification 432 The following CDDL fragment identifies all of the top messages 433 defined in this document. Separate non-terminals are defined for the 434 tagged and the untagged versions of the messages. 436 COSE_Messages = COSE_Untagged_Message / COSE_Tagged_Message 438 COSE_Untagged_Message = COSE_Sign / COSE_Sign1 / 439 COSE_Encrypt / COSE_Encrypt0 / 440 COSE_Mac / COSE_Mac0 442 COSE_Tagged_Message = COSE_Sign_Tagged / COSE_Sign1_Tagged / 443 COSE_Encrypt_Tagged / COSE_Encrypt0_Tagged / 444 COSE_Mac_Tagged / COSE_Mac0_Tagged 446 3. Header Parameters 448 The structure of COSE has been designed to have two buckets of 449 information that are not considered to be part of the payload itself, 450 but are used for holding information about content, algorithms, keys, 451 or evaluation hints for the processing of the layer. These two 452 buckets are available for use in all of the structures except for 453 keys. While these buckets are present, they may not all be usable in 454 all instances. For example, while the protected bucket is defined as 455 part of the recipient structure, some of the algorithms used for 456 recipient structures do not provide for authenticated data. If this 457 is the case, the protected bucket is left empty. 459 Both buckets are implemented as CBOR maps. The map key is a 'label' 460 (Section 1.4). The value portion is dependent on the definition for 461 the label. Both maps use the same set of label/value pairs. The 462 integer and string values for labels have been divided into several 463 sections with a standard range, a private range, and a range that is 464 dependent on the algorithm selected. The defined labels can be found 465 in the "COSE Header Parameters" IANA registry (Section 16.2). 467 Two buckets are provided for each layer: 469 protected: Contains parameters about the current layer that are to 470 be cryptographically protected. This bucket MUST be empty if it 471 is not going to be included in a cryptographic computation. This 472 bucket is encoded in the message as a binary object. This value 473 is obtained by CBOR encoding the protected map and wrapping it in 474 a bstr object. Senders SHOULD encode a zero length map as a zero 475 length string rather than as a zero length map (encoded as h'a0'). 476 The zero length binary encoding is preferred because it is both 477 shorter and the version used in the serialization structures for 478 cryptographic computation. After encoding the map, the value is 479 wrapped in the binary object. Recipients MUST accept both a zero 480 length binary value and a zero length map encoded in the binary 481 value. The wrapping allows for the encoding of the protected map 482 to be transported with a greater chance that it will not be 483 altered in transit. (Badly behaved intermediates could decode and 484 re-encode, but this will result in a failure to verify unless the 485 re-encoded byte string is identical to the decoded byte string.) 486 This avoids the problem of all parties needing to be able to do a 487 common canonical encoding. 489 unprotected: Contains parameters about the current layer that are 490 not cryptographically protected. 492 Only parameters that deal with the current layer are to be placed at 493 that layer. As an example of this, the parameter 'content type' 494 describes the content of the message being carried in the message. 495 As such, this parameter is placed only in the content layer and is 496 not placed in the recipient or signature layers. In principle, one 497 should be able to process any given layer without reference to any 498 other layer. With the exception of the COSE_Sign structure, the only 499 data that needs to cross layers is the cryptographic key. 501 The buckets are present in all of the security objects defined in 502 this document. The fields in order are the 'protected' bucket (as a 503 CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map' 504 type). The presence of both buckets is required. The parameters 505 that go into the buckets come from the IANA "COSE Header Parameters" 506 registry (Section 16.2). Some common parameters are defined in the 507 next section, but a number of parameters are defined throughout this 508 document. 510 Labels in each of the maps MUST be unique. When processing messages, 511 if a label appears multiple times, the message MUST be rejected as 512 malformed. Applications SHOULD verify that the same label does not 513 occur in both the protected and unprotected headers. If the message 514 is not rejected as malformed, attributes MUST be obtained from the 515 protected bucket before they are obtained from the unprotected 516 bucket. 518 The following CDDL fragment represents the two header buckets. A 519 group Headers is defined in CDDL that represents the two buckets in 520 which attributes are placed. This group is used to provide these two 521 fields consistently in all locations. A type is also defined which 522 represents the map of common headers. 524 Headers = ( 525 protected : empty_or_serialized_map, 526 unprotected : header_map 527 ) 529 header_map = { 530 Generic_Headers, 531 * label => values 532 } 534 empty_or_serialized_map = bstr .cbor header_map / bstr .size 0 536 3.1. Common COSE Headers Parameters 538 This section defines a set of common header parameters. A summary of 539 these parameters can be found in Table 2. This table should be 540 consulted to determine the value of label, and the type of the value. 542 The set of header parameters defined in this section are: 544 alg This parameter is used to indicate the algorithm used for the 545 security processing. This parameter MUST be present in the 546 COSE_Signature, COSE_Sign1, COSE_Encrypt, COSE_Encrypt0, COSE_Mac, 547 and COSE_Mac0 structures. When the algorithm supports 548 authenticating associated data, this parameter MUST be in the 549 protected header bucket. The value is taken from the "COSE 550 Algorithms" Registry (see Section 16.4). 552 crit The parameter is used to indicate which protected header labels 553 an application that is processing a message is required to 554 understand. Parameters defined in this document do not need to be 555 included as they should be understood by all implementations. 556 When present, this parameter MUST be placed in the protected 557 header bucket. The array MUST have at least one value in it. 558 Not all labels need to be included in the 'crit' parameter. The 559 rules for deciding which header labels are placed in the array 560 are: 562 * Integer labels in the range of 0 to 8 SHOULD be omitted. 564 * Integer labels in the range -1 to -128 can be omitted as they 565 are algorithm dependent. If an application can correctly 566 process an algorithm, it can be assumed that it will correctly 567 process all of the common parameters associated with that 568 algorithm. Integer labels in the range -129 to -65536 SHOULD 569 be included as these would be less common parameters that might 570 not be generally supported. 572 * Labels for parameters required for an application MAY be 573 omitted. Applications should have a statement if the label can 574 be omitted. 576 The header parameter values indicated by 'crit' can be processed 577 by either the security library code or by an application using a 578 security library; the only requirement is that the parameter is 579 processed. If the 'crit' value list includes a value for which 580 the parameter is not in the protected bucket, this is a fatal 581 error in processing the message. 583 content type This parameter is used to indicate the content type of 584 the data in the payload or cipher text fields. Integers are from 585 the "CoAP Content-Formats" IANA registry table [COAP.Formats]. 586 Text values following the syntax of Content-Type defined in 587 Section 5.1 of [RFC2045] omitting the prefix string "Content- 588 Type:". Leading and trailing whitespace is also omitted. Textual 589 content values along with parameters and subparameters can be 590 located using the IANA "Media Types" registry. Applications 591 SHOULD provide this parameter if the content structure is 592 potentially ambiguous. 594 kid This parameter identifies one piece of data that can be used as 595 input to find the needed cryptographic key. The value of this 596 parameter can be matched against the 'kid' member in a COSE_Key 597 structure. Other methods of key distribution can define an 598 equivalent field to be matched. Applications MUST NOT assume that 599 'kid' values are unique. There may be more than one key with the 600 same 'kid' value, so all of the keys may need to be checked to 601 find the correct one. The internal structure of 'kid' values is 602 not defined and cannot be relied on by applications. Key 603 identifier values are hints about which key to use. This is not a 604 security critical field. For this reason, it can be placed in the 605 unprotected headers bucket. 607 IV This parameter holds the Initialization Vector (IV) value. For 608 some symmetric encryption algorithms this may be referred to as a 609 nonce. The IV can be placed in the unprotected header as 610 modifying the IV will cause the decryption to yield plaintext that 611 is readily detectable as garbled. 613 Partial IV This parameter holds a part of the IV value. When using 614 the COSE_Encrypt0 structure, a portion of the IV can be part of 615 the context associated with the key. This field is used to carry 616 a value that causes the IV to be changed for each message. The IV 617 can be placed in the unprotected header as modifying the IV will 618 cause the decryption to yield plaintext that is readily detectable 619 as garbled. The 'Initialization Vector' and 'Partial 620 Initialization Vector' parameters MUST NOT both be present in the 621 same security layer. 622 The message IV is generated by the following steps: 624 1. Left pad the partial IV with zeros to the length of IV. 626 2. XOR the padded partial IV with the context IV. 628 counter signature This parameter holds one or more counter signature 629 values. Counter signatures provide a method of having a second 630 party sign some data. The counter signature parameter can occur 631 as an unprotected attribute in any of the following structures: 632 COSE_Sign1, COSE_Signature, COSE_Encrypt, COSE_recipient, 633 COSE_Encrypt0, COSE_Mac and COSE_Mac0. These structures all have 634 the same beginning elements so that a consistent calculation of 635 the counter signature can be computed. Details on computing 636 counter signatures are found in Section 4.5. 638 +-----------+-------+----------------+-------------+----------------+ 639 | name | label | value type | value | description | 640 | | | | registry | | 641 +-----------+-------+----------------+-------------+----------------+ 642 | alg | 1 | int / tstr | COSE | Cryptographic | 643 | | | | Algorithms | algorithm to | 644 | | | | registry | use | 645 | | | | | | 646 | crit | 2 | [+ label] | COSE Header | Critical | 647 | | | | Labels | headers to be | 648 | | | | registry | understood | 649 | | | | | | 650 | content | 3 | tstr / uint | CoAP | Content type | 651 | type | | | Content- | of the payload | 652 | | | | Formats or | | 653 | | | | Media Types | | 654 | | | | registry | | 655 | | | | | | 656 | kid | 4 | bstr | | Key identifier | 657 | | | | | | 658 | IV | 5 | bstr | | Full | 659 | | | | | Initialization | 660 | | | | | Vector | 661 | | | | | | 662 | Partial | 6 | bstr | | Partial | 663 | IV | | | | Initialization | 664 | | | | | Vector | 665 | | | | | | 666 | counter | 7 | COSE_Signature | | CBOR encoded | 667 | signature | | / [+ | | signature | 668 | | | COSE_Signature | | structure | 669 | | | ] | | | 670 +-----------+-------+----------------+-------------+----------------+ 672 Table 2: Common Header Parameters 674 The CDDL fragment that represents the set of headers defined in this 675 section is given below. Each of the headers is tagged as optional 676 because they do not need to be in every map; headers required in 677 specific maps are discussed above. 679 Generic_Headers = ( 680 ? 1 => int / tstr, ; algorithm identifier 681 ? 2 => [+label], ; criticality 682 ? 3 => tstr / int, ; content type 683 ? 4 => bstr, ; key identifier 684 ? 5 => bstr, ; IV 685 ? 6 => bstr, ; Partial IV 686 ? 7 => COSE_Signature / [+COSE_Signature] ; Counter signature 687 ) 689 4. Signing Objects 691 COSE supports two different signature structures. COSE_Sign allows 692 for one or more signatures to be applied to the same content. 693 COSE_Sign1 is restricted to a single signer. The structures cannot 694 be converted between each other; as the signature computation 695 includes a parameter identifying which structure is being used, the 696 converted structure will fail signature validation. 698 4.1. Signing with One or More Signers 700 The COSE_Sign structure allows for one or more signatures to be 701 applied to a message payload. Parameters relating to the content and 702 parameters relating to the signature are carried along with the 703 signature itself. These parameters may be authenticated by the 704 signature, or just present. An example of a parameter about the 705 content is the content type. Examples of parameters about the 706 signature would be the algorithm and key used to create the signature 707 and counter signatures. 709 When more than one signature is present, the successful validation of 710 one signature associated with a given signer is usually treated as a 711 successful signature by that signer. However, there are some 712 application environments where other rules are needed. An 713 application that employs a rule other than one valid signature for 714 each signer must specify those rules. Also, where simple matching of 715 the signer identifier is not sufficient to determine whether the 716 signatures were generated by the same signer, the application 717 specification must describe how to determine which signatures were 718 generated by the same signer. Support for different communities of 719 recipients is the primary reason that signers choose to include more 720 than one signature. For example, the COSE_Sign structure might 721 include signatures generated with the Edwards Digital Signature 722 Algorithm (EdDSA) [I-D.irtf-cfrg-eddsa] signature algorithm and with 723 the Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] 724 signature algorithm. This allows recipients to verify the signature 725 associated with one algorithm or the other. (The original source of 726 this text is [RFC5652].) More detailed information on multiple 727 signature evaluation can be found in [RFC5752]. 729 The signature structure can be encoded either as tagged or untagged 730 depending on the context it will be used in. A tagged COSE_Sign 731 structure is identified by the CBOR tag TBD1. The CDDL fragment that 732 represents this is: 734 COSE_Sign_Tagged = #6.991(COSE_Sign) ; Replace 991 with TBD1 736 A COSE Signed Message is defined in two parts. The CBOR object that 737 carries the body and information about the body is called the 738 COSE_Sign structure. The CBOR object that carries the signature and 739 information about the signature is called the COSE_Signature 740 structure. Examples of COSE Signed Messages can be found in 741 Appendix C.1. 743 The COSE_Sign structure is a CBOR array. The fields of the array in 744 order are: 746 protected as described in Section 3. 748 unprotected as described in Section 3. 750 payload contains the serialized content to be signed. If the 751 payload is not present in the message, the application is required 752 to supply the payload separately. The payload is wrapped in a 753 bstr to ensure that it is transported without changes. If the 754 payload is transported separately ("detached content"), then a nil 755 CBOR object is placed in this location and it is the 756 responsibility of the application to ensure that it will be 757 transported without changes. 759 Note: When a signature with message recovery algorithm is used 760 (Section 8), the maximum number of bytes that can be recovered is 761 the length of the payload. The size of the payload is reduced by 762 the number of bytes that will be recovered. If all of the bytes 763 of the payload are consumed, then the payload is encoded as a zero 764 length binary string rather than as being absent. 766 signatures is an array of signatures. Each signature is represented 767 as a COSE_Signature structure. 769 The CDDL fragment that represents the above text for COSE_Sign 770 follows. 772 COSE_Sign = [ 773 Headers, 774 payload : bstr / nil, 775 signatures : [+ COSE_Signature] 776 ] 778 The COSE_Signature structure is a CBOR array. The fields of the 779 array in order are: 781 protected as described in Section 3. 783 unprotected as described in Section 3. 785 signature contains the computed signature value. The type of the 786 field is a bstr. 788 The CDDL fragment that represents the above text for COSE_Signature 789 follows. 791 COSE_Signature = [ 792 Headers, 793 signature : bstr 794 ] 796 4.2. Signing with One Signer 798 The COSE_Sign1 signature structure is used when only one signature is 799 going to be placed on a message. The parameters dealing with the 800 content and the signature are placed in the same pair of buckets 801 rather than having the separation of COSE_Sign. 803 The structure can be encoded either tagged or untagged depending on 804 the context it will be used in. A tagged COSE_Sign1 structure is 805 identified by the CBOR tag TBD7. The CDDL fragment that represents 806 this is: 808 COSE_Sign1_Tagged = #6.997(COSE_Sign1) ; Replace 997 with TBD7 810 The CBOR object that carries the body, the signature, and the 811 information about the body and signature is called the COSE_Sign1 812 structure. Examples of COSE_Sign1 messages can be found in 813 Appendix C.2. 815 The COSE_Sign1 structure is a CBOR array. The fields of the array in 816 order are: 818 protected as described in Section 3. 820 unprotected as described in Section 3. 822 payload as described in Section 4.1. 824 signature contains the computed signature value. The type of the 825 field is a bstr. 827 The CDDL fragment that represents the above text for COSE_Sign1 828 follows. 830 COSE_Sign1 = [ 831 Headers, 832 payload : bstr / nil, 833 signature : bstr 834 ] 836 4.3. Externally Supplied Data 838 One of the features offered in the COSE document is the ability for 839 applications to provide additional data to be authenticated, but that 840 is not carried as part of the COSE object. The primary reason for 841 supporting this can be seen by looking at the CoAP message structure 842 [RFC7252], where the facility exists for options to be carried before 843 the payload. Examples of data that can be placed in this location 844 would be the CoAP code or CoAP options. If the data is in the header 845 section, then it is available for proxies to help in performing its 846 operations. For example, the Accept Option can be used by a proxy to 847 determine if an appropriate value is in the Proxy's cache. But the 848 sender can prevent a proxy from changing the set of values that it 849 will accept by including that value in the resulting authentication 850 tag. However, it may also be desired to protect these values so that 851 if they are modified in transit, it can be detected. 853 This document describes the process for using a byte array of 854 externally supplied authenticated data; however, the method of 855 constructing the byte array is a function of the application. 856 Applications that use this feature need to define how the externally 857 supplied authenticated data is to be constructed. Such a 858 construction needs to take into account the following issues: 860 o If multiple items are included, care needs to be taken that data 861 cannot bleed between the items. This is usually addressed by 862 making fields fixed width and/or encoding the length of the field. 863 Using options from CoAP [RFC7252] as an example, these fields use 864 a TLV structure so they can be concatenated without any problems. 866 o If multiple items are included, an order for the items needs to be 867 defined. Using options from CoAP as an example, an application 868 could state that the fields are to be ordered by the option 869 number. 871 o Applications need to ensure that the byte stream is going to be 872 the same on both sides. Using options from CoAP might give a 873 problem if the same relative numbering is kept. An intermediate 874 node could insert or remove an option, changing how the relative 875 number is done. An application would need to specify that the 876 relative number must be re-encoded to be relative only to the 877 options that are in the external data. 879 4.4. Signing and Verification Process 881 In order to create a signature, a well-defined byte stream is needed. 882 This signing and verification process takes in the body information 883 (COSE_Sign or COSE_Sign1), the signer information (COSE_Signature), 884 and the application data (external source). A CBOR array is used to 885 construct the byte stream. The fields of the array in order are: 887 1. A text string identifying the context of the signature. The 888 context string is: 890 "Signature" for signatures using the COSE_Signature structure. 892 "Signature1" for signatures using the COSE_Sign1 structure. 894 "CounterSignature" for signatures used as counter signature 895 attributes. 897 2. The protected attributes from the body structure encoded in a 898 bstr type. If there are no protected attributes, a bstr of 899 length zero is used. 901 3. The protected attributes from the signer structure encoded in a 902 bstr type. If there are no protected attributes, a bstr of 903 length zero is used. This field is omitted for the COSE_Sign1 904 signature structure. 906 4. The protected attributes from the application encoded in a bstr 907 type. If this field is not supplied, it defaults to a zero 908 length binary string. (See Section 4.3 for application guidance 909 on constructing this field.) 911 5. The payload to be signed encoded in a bstr type. The payload is 912 placed here independent of how it is transported. 914 The CDDL fragment that describes the above text is. 916 Sig_structure = [ 917 context : "Signature" / "Signature1" / "CounterSignature", 918 body_protected : empty_or_serialized_map, 919 ? sign_protected : empty_or_serialized_map, 920 external_aad : bstr, 921 payload : bstr 922 ] 924 How to compute a signature: 926 1. Create a Sig_structure and populate it with the appropriate 927 fields. 929 2. Create the value ToBeSigned by encoding the Sig_structure to a 930 byte string, using the encoding described in Section 14. 932 3. Call the signature creation algorithm passing in K (the key to 933 sign with), alg (the algorithm to sign with), and ToBeSigned (the 934 value to sign). 936 4. Place the resulting signature value in the 'signature' field of 937 the array. 939 The steps for verifying a signature are: 941 1. Create a Sig_structure object and populate it with the 942 appropriate fields. 944 2. Create the value ToBeSigned by encoding the Sig_structure to a 945 byte string, using the encoding described in Section 14. 947 3. Call the signature verification algorithm passing in K (the key 948 to verify with), alg (the algorithm used sign with), ToBeSigned 949 (the value to sign), and sig (the signature to be verified). 951 In addition to performing the signature verification, one must also 952 perform the appropriate checks to ensure that the key is correctly 953 paired with the signing identity and that the signing identity is 954 authorized before performing actions. 956 4.5. Computing Counter Signatures 958 Counter signatures provide a method of associating different 959 signature generated by different signers with some piece of content. 960 This is normally used to provide a signature on a signature allowing 961 for a proof that a signature existed at a given time (i.e., a 962 Timestamp). In this document, we allow for counter signatures to 963 exist in a greater number of environments. As an example, it is 964 possible to place a counter signature in the unprotected attributes 965 of a COSE_Encrypt object. This would allow for an intermediary to 966 either verify that the encrypted byte stream has not been modified, 967 without being able to decrypt it, or for the intermediary to assert 968 that an encrypted byte stream either existed at a given time or 969 passed through it in terms of routing (i.e., a proxy signature). 971 An example of a counter signature on a signature can be found in 972 Appendix C.1.3. An example of a counter signature in an encryption 973 object can be found in Appendix C.3.3. 975 The creation and validation of counter signatures over the different 976 items relies on the fact that the structure of the objects have the 977 same structure. The elements are a set of protected attributes, a 978 set of unprotected attributes, and a body, in that order. This means 979 that the Sig_structure can be used in a uniform manner to get the 980 byte stream for processing a signature. If the counter signature is 981 going to be computed over a COSE_Encrypt structure, the 982 body_protected and payload items can be mapped into the Sig_structure 983 in the same manner as from the COSE_Sign structure. 985 It should be noted that only a signature algorithm with appendix (see 986 Section 8) can be used for counter signatures. This is because the 987 body should be able to be processed without having to evaluate the 988 counter signature, and this is not possible for signature schemes 989 with message recovery. 991 5. Encryption Objects 993 COSE supports two different encryption structures. COSE_Encrypt0 is 994 used when a recipient structure is not needed because the key to be 995 used is known implicitly. COSE_Encrypt is used the rest of the time. 996 This includes cases where there are multiple recipients or a 997 recipient algorithm other than direct is used. 999 5.1. Enveloped COSE Structure 1001 The enveloped structure allows for one or more recipients of a 1002 message. There are provisions for parameters about the content and 1003 parameters about the recipient information to be carried in the 1004 message. The protected parameters associated with the content are 1005 authenticated by the content encryption algorithm. The protected 1006 parameters associated with the recipient are authenticated by the 1007 recipient algorithm (when the algorithm supports it). Examples of 1008 parameters about the content are the type of the content and the 1009 content encryption algorithm. Examples of parameters about the 1010 recipient are the recipient's key identifier and the recipient's 1011 encryption algorithm. 1013 The same techniques and structures are used for encrypting both the 1014 plain text and the keys. This is different from the approach used by 1015 both CMS [RFC5652] and JSON Web Encryption (JWE) [RFC7516] where 1016 different structures are used for the content layer and for the 1017 recipient layer. Two structures are defined: COSE_Encrypt to hold 1018 the encrypted content and COSE_recipient to hold the encrypted keys 1019 for recipients. Examples of encrypted messages can be found in 1020 Appendix C.3. 1022 The COSE_Encrypt structure can be encoded either tagged or untagged 1023 depending on the context it will be used in. A tagged COSE_Encrypt 1024 structure is identified by the CBOR tag TBD2. The CDDL fragment that 1025 represents this is: 1027 COSE_Encrypt_Tagged = #6.992(COSE_Encrypt) ; Replace 992 with TBD2 1029 The COSE_Encrypt structure is a CBOR array. The fields of the array 1030 in order are: 1032 protected as described in Section 3. 1034 unprotected as described in Section 3. ' 1036 ciphertext contains the cipher text encoded as a bstr. If the 1037 cipher text is to be transported independently of the control 1038 information about the encryption process (i.e., detached content) 1039 then the field is encoded as a nil value. 1041 recipients contains an array of recipient information structures. 1042 The type for the recipient information structure is a 1043 COSE_recipient. 1045 The CDDL fragment that corresponds to the above text is: 1047 COSE_Encrypt = [ 1048 Headers, 1049 ciphertext : bstr / nil, 1050 recipients : [+COSE_recipient] 1051 ] 1053 The COSE_recipient structure is a CBOR array. The fields of the 1054 array in order are: 1056 protected as described in Section 3. 1058 unprotected as described in Section 3. 1060 ciphertext contains the encrypted key encoded as a bstr. All 1061 encoded keys are symetric keys, the binary value of the key is the 1062 content. If there is not an encrypted key, then this field is 1063 encoded as a nil value. 1065 recipients contains an array of recipient information structures. 1066 The type for the recipient information structure is a 1067 COSE_recipient. (An example of this can be found in Appendix B.) 1068 If there are no recipient information structures, this element is 1069 absent. 1071 The CDDL fragment that corresponds to the above text for 1072 COSE_recipient is: 1074 COSE_recipient = [ 1075 Headers, 1076 ciphertext : bstr / nil, 1077 ? recipients : [+COSE_recipient] 1078 ] 1080 5.1.1. Content Key Distribution Methods 1082 An encrypted message consists of an encrypted content and an 1083 encrypted CEK for one or more recipients. The CEK is encrypted for 1084 each recipient, using a key specific to that recipient. The details 1085 of this encryption depend on which class the recipient algorithm 1086 falls into. Specific details on each of the classes can be found in 1087 Section 12. A short summary of the five content key distribution 1088 methods is: 1090 direct: The CEK is the same as the identified previously distributed 1091 symmetric key or derived from a previously distributed secret. No 1092 CEK is transported in the message. 1094 symmetric key-encryption keys: The CEK is encrypted using a 1095 previously distributed symmetric KEK. 1097 key agreement: The recipient's public key and a sender's private key 1098 are used to generate a pairwise secret, a KDF is applied to derive 1099 a key, and then the CEK is either the derived key or encrypted by 1100 the derived key. 1102 key transport: The CEK is encrypted with the recipient's public key. 1103 No key transport algorithms are defined in this document. 1105 passwords: The CEK is encrypted in a KEK that is derived from a 1106 password. No password algorithms are defined in this document. 1108 5.2. Single Recipient Encrypted 1110 The COSE_Encrypt0 encrypted structure does not have the ability to 1111 specify recipients of the message. The structure assumes that the 1112 recipient of the object will already know the identity of the key to 1113 be used in order to decrypt the message. If a key needs to be 1114 identified to the recipient, the enveloped structure ought to be 1115 used. 1117 Examples of encrypted messages can be found in Appendix C.3. 1119 The COSE_Encrypt0 structure can be encoded either tagged or untagged 1120 depending on the context it will be used in. A tagged COSE_Encrypt0 1121 structure is identified by the CBOR tag TBD3. The CDDL fragment that 1122 represents this is: 1124 COSE_Encrypt0_Tagged = #6.993(COSE_Encrypt0) ; Replace 993 with TBD3 1126 The COSE_Encrypt structure is a CBOR array. The fields of the array 1127 in order are: 1129 protected as described in Section 3. 1131 unprotected as described in Section 3. 1133 ciphertext as described in Section 5.1. 1135 The CDDL fragment for COSE_Encrypt0 that corresponds to the above 1136 text is: 1138 COSE_Encrypt0 = [ 1139 Headers, 1140 ciphertext : bstr / nil, 1141 ] 1143 5.3. How to encrypt and decrypt for AEAD Algorithms 1145 The encryption algorithm for AEAD algorithms is fairly simple. The 1146 first step is to create a consistent byte stream for the 1147 authenticated data structure. For this purpose, we use a CBOR array. 1148 The fields of the array in order are: 1150 1. A text string identifying the context of the authenticated data 1151 structure. The context string is: 1153 "Encrypt0" for the content encryption of a COSE_Encrypt0 data 1154 structure. 1156 "Encrypt" for the first layer of a COSE_Encrypt data structure 1157 (i.e., for content encryption). 1159 "Enc_Recipient" for a recipient encoding to be placed in an 1160 COSE_Encrypt data structure. 1162 "Mac_Recipient" for a recipient encoding to be placed in a MACed 1163 message structure. 1165 "Rec_Recipient" for a recipient encoding to be placed in a 1166 recipient structure. 1168 2. The protected attributes from the body structure encoded in a 1169 bstr type. If there are no protected attributes, a bstr of 1170 length zero is used. 1172 3. The protected attributes from the application encoded in a bstr 1173 type. If this field is not supplied, it defaults to a zero 1174 length bstr. (See Section 4.3 for application guidance on 1175 constructing this field.) 1177 The CDDL fragment that describes the above text is: 1179 Enc_structure = [ 1180 context : "Encrypt" / "Encrypt0" / "Enc_Recipient" / 1181 "Mac_Recipient" / "Rec_Recipient", 1182 protected : empty_or_serialized_map, 1183 external_aad : bstr 1184 ] 1186 How to encrypt a message: 1188 1. Create an Enc_structure and populate it with the appropriate 1189 fields. 1191 2. Encode the Enc_structure to a byte stream (AAD), using the 1192 encoding described in Section 14. 1194 3. Determine the encryption key (K). This step is dependent on the 1195 class of recipient algorithm being used. For: 1197 No Recipients: The key to be used is determined by the algorithm 1198 and key at the current layer. Examples are key transport keys 1199 Section 12.3, key wrap keys Section 12.2.1 or pre-shared 1200 secrets. 1202 Direct Encryption and Direct Key Agreement: The key is 1203 determined by the key and algorithm in the recipient 1204 structure. The encryption algorithm and size of the key to be 1205 used are inputs into the KDF used for the recipient. (For 1206 direct, the KDF can be thought of as the identity operation.) 1207 Examples of these algorithms are found in Section 12.1.2 and 1208 Section 12.4.1. 1210 Other: The key is randomly or pseudo-randomly generated. 1212 4. Call the encryption algorithm with K (the encryption key), P (the 1213 plain text) and AAD. Place the returned cipher text into the 1214 'ciphertext' field of the structure. 1216 5. For recipients of the message, recursively perform the encryption 1217 algorithm for that recipient, using K (the encryption key) as the 1218 plain text. 1220 How to decrypt a message: 1222 1. Create a Enc_structure and populate it with the appropriate 1223 fields. 1225 2. Encode the Enc_structure to a byte stream (AAD), using the 1226 encoding described in Section 14. 1228 3. Determine the decryption key. This step is dependent on the 1229 class of recipient algorithm being used. For: 1231 No Recipients: The key to be used is determined by the algorithm 1232 and key at the current layer. Examples are key transport keys 1233 Section 12.3, key wrap keys Section 12.2.1 or pre-shared 1234 secrets. 1236 Direct Encryption and Direct Key Agreement: The key is 1237 determined by the key and algorithm in the recipient 1238 structure. The encryption algorithm and size of the key to be 1239 used are inputs into the KDF used for the recipient. (For 1240 direct, the KDF can be thought of as the identity operation.) 1241 Examples of these algorithms are found in Section 12.1.2 and 1242 Section 12.4.1. 1244 Other: The key is determined by decoding and decrypting one of 1245 the recipient structures. 1247 4. Call the decryption algorithm with K (the decryption key to use), 1248 C (the cipher text) and AAD. 1250 5.4. How to encrypt and decrypt for AE Algorithms 1252 How to encrypt a message: 1254 1. Verify that the 'protected' field is empty. 1256 2. Verify that there was no external additional authenticated data 1257 supplied for this operation. 1259 3. Determine the encryption key. This step is dependent on the 1260 class of recipient algorithm being used. For: 1262 No Recipients: The key to be used is determined by the algorithm 1263 and key at the current layer. Examples are key transport keys 1264 Section 12.3, key wrap keys Section 12.2.1 or pre-shared 1265 secrets. 1267 Direct Encryption and Direct Key Agreement: The key is 1268 determined by the key and algorithm in the recipient 1269 structure. The encryption algorithm and size of the key to be 1270 used are inputs into the KDF used for the recipient. (For 1271 direct, the KDF can be thought of as the identity operation.) 1272 Examples of these algorithms are found in Section 12.1.2 and 1273 Section 12.4.1. 1275 Other: The key is randomly generated. 1277 4. Call the encryption algorithm with K (the encryption key to use) 1278 and the P (the plain text). Place the returned cipher text into 1279 the 'ciphertext' field of the structure. 1281 5. For recipients of the message, recursively perform the encryption 1282 algorithm for that recipient, using K (the encryption key) as the 1283 plain text. 1285 How to decrypt a message: 1287 1. Verify that the 'protected' field is empty. 1289 2. Verify that there was no external additional authenticated data 1290 supplied for this operation. 1292 3. Determine the decryption key. This step is dependent on the 1293 class of recipient algorithm being used. For: 1295 No Recipients: The key to be used is determined by the algorithm 1296 and key at the current layer. Examples are key transport keys 1297 Section 12.3, key wrap keys Section 12.2.1 or pre-shared 1298 secrets. 1300 Direct Encryption and Direct Key Agreement: The key is 1301 determined by the key and algorithm in the recipient 1302 structure. The encryption algorithm and size of the key to be 1303 used are inputs into the KDF used for the recipient. (For 1304 direct, the KDF can be thought of as the identity operation.) 1305 Examples of these algorithms are found in Section 12.1.2 and 1306 Section 12.4.1. 1308 Other: The key is determined by decoding and decrypting one of 1309 the recipient structures. 1311 4. Call the decryption algorithm with K (the decryption key to use), 1312 and C (the cipher text). 1314 6. MAC Objects 1316 COSE supports two different MAC structures. COSE_MAC0 is used when a 1317 recipient structure is not needed because the key to be used is 1318 implicitly known. COSE_MAC is used for all other cases. These 1319 include a requirement for multiple recipients, the key being unknown, 1320 and a recipient algorithm of other than direct. 1322 In this section, we describe the structure and methods to be used 1323 when doing MAC authentication in COSE. This document allows for the 1324 use of all of the same classes of recipient algorithms as are allowed 1325 for encryption. 1327 When using MAC operations, there are two modes in which they can be 1328 used. The first is just a check that the content has not been 1329 changed since the MAC was computed. Any class of recipient algorithm 1330 can be used for this purpose. The second mode is to both check that 1331 the content has not been changed since the MAC was computed, and to 1332 use the recipient algorithm to verify who sent it. The classes of 1333 recipient algorithms that support this are those that use a pre- 1334 shared secret or do static-static key agreement (without the key wrap 1335 step). In both of these cases, the entity that created and sent the 1336 message MAC can be validated. (This knowledge of sender assumes that 1337 there are only two parties involved and you did not send the message 1338 to yourself.) The origination property can be obtained with both of 1339 the MAC message structures. 1341 6.1. MACed Message with Recipients 1343 The multiple recipient MACed message uses two structures, the 1344 COSE_Mac structure defined in this section for carrying the body and 1345 the COSE_recipient structure (Section 5.1) to hold the key used for 1346 the MAC computation. Examples of MACed messages can be found in 1347 Appendix C.5. 1349 The MAC structure can be encoded either tagged or untagged depending 1350 on the context it will be used in. A tagged COSE_Mac structure is 1351 identified by the CBOR tag TBD4. The CDDL fragment that represents 1352 this is: 1354 COSE_Mac_Tagged = #6.994(COSE_Mac) ; Replace 994 with TBD4 1356 The COSE_Mac structure is a CBOR array. The fields of the array in 1357 order are: 1359 protected as described in Section 3. 1361 unprotected as described in Section 3. 1363 payload contains the serialized content to be MACed. If the payload 1364 is not present in the message, the application is required to 1365 supply the payload separately. The payload is wrapped in a bstr 1366 to ensure that it is transported without changes. If the payload 1367 is transported separately (i.e., detached content), then a nil 1368 CBOR value is placed in this location and it is the responsibility 1369 of the application to ensure that it will be transported without 1370 changes. 1372 tag contains the MAC value. 1374 recipients as described in Section 5.1. 1376 The CDDL fragment that represents the above text for COSE_Mac 1377 follows. 1379 COSE_Mac = [ 1380 Headers, 1381 payload : bstr / nil, 1382 tag : bstr, 1383 recipients :[+COSE_recipient] 1384 ] 1386 6.2. MACed Messages with Implicit Key 1388 In this section, we describe the structure and methods to be used 1389 when doing MAC authentication for those cases where the recipient is 1390 implicitly known. 1392 The MACed message uses the COSE_Mac0 structure defined in this 1393 section for carrying the body. Examples of MACed messages with an 1394 implicit key can be found in Appendix C.6. 1396 The MAC structure can be encoded either tagged or untagged depending 1397 on the context it will be used in. A tagged COSE_Mac0 structure is 1398 identified by the CBOR tag TBD6. The CDDL fragment that represents 1399 this is: 1401 COSE_Mac0_Tagged = #6.996(COSE_Mac0) ; Replace 996 with TBD6 1403 The COSE_Mac0 structure is a CBOR array. The fields of the array in 1404 order are: 1406 protected as described in Section 3. 1408 unprotected as described in Section 3. 1410 payload as described in Section 6.1. 1412 tag contains the MAC value. 1414 The CDDL fragment that corresponds to the above text is: 1416 COSE_Mac0 = [ 1417 Headers, 1418 payload : bstr / nil, 1419 tag : bstr, 1420 ] 1422 6.3. How to compute and verify a MAC 1424 In order to get a consistent encoding of the data to be 1425 authenticated, the MAC_structure is used to have a canonical form. 1426 The MAC_structure is a CBOR array. The fields of the MAC_structure 1427 in order are: 1429 1. A text string that identifies the structure that is being 1430 encoded. This string is "MAC" for the COSE_Mac structure. This 1431 string is "MAC0" for the COSE_Mac0 structure. 1433 2. The protected attributes from the COSE_MAC structure. If there 1434 are no protected attributes, a zero length bstr is used. 1436 3. The protected attributes from the application encoded as a bstr 1437 type. If this field is not supplied, it defaults to a zero 1438 length binary string. (See Section 4.3 for application guidance 1439 on constructing this field.) 1441 4. The payload to be MAC-ed encoded in a bstr type. The payload is 1442 placed here independent of how it is transported. 1444 The CDDL fragment that corresponds to the above text is: 1446 MAC_structure = [ 1447 context : "MAC" / "MAC0", 1448 protected : empty_or_serialized_map, 1449 external_aad : bstr, 1450 payload : bstr 1451 ] 1453 The steps to compute a MAC are: 1455 1. Create a MAC_structure and populate it with the appropriate 1456 fields. 1458 2. Create the value ToBeMaced by encoding the MAC_structure to a 1459 byte stream, using the encoding described in Section 14. 1461 3. Call the MAC creation algorithm passing in K (the key to use), 1462 alg (the algorithm to MAC with) and ToBeMaced (the value to 1463 compute the MAC on). 1465 4. Place the resulting MAC in the 'tag' field of the COSE_Mac or 1466 COSE_Mac0 structure. 1468 5. Encrypt and encode the MAC key for each recipient of the message. 1470 The steps to verify a MAC are: 1472 1. Create a MAC_structure object and populate it with the 1473 appropriate fields. 1475 2. Create the value ToBeMaced by encoding the MAC_structure to a 1476 byte stream, using the encoding described in Section 14. 1478 3. Obtain the cryptographic key from one of the recipients of the 1479 message. 1481 4. Call the MAC creation algorithm passing in K (the key to use), 1482 alg (the algorithm to MAC with) and ToBeMaced (the value to 1483 compute the MAC on). 1485 5. Compare the MAC value to the 'tag' field of the COSE_Mac or 1486 COSE_Mac0 structure. 1488 7. Key Objects 1490 A COSE Key structure is built on a CBOR map object. The set of 1491 common parameters that can appear in a COSE Key can be found in the 1492 IANA "COSE Key Common Parameters" registry (Section 16.5). 1493 Additional parameters defined for specific key types can be found in 1494 the IANA "COSE Key Type Parameters" registry (Section 16.6). 1496 A COSE Key Set uses a CBOR array object as its underlying type. The 1497 values of the array elements are COSE Keys. A Key Set MUST have at 1498 least one element in the array. Examples of Key Sets can be found in 1499 Appendix C.7. 1501 Each element in a key set MUST be processed independently. If one 1502 element in a key set is either malformed or uses a key that is not 1503 understood by an application, that key is ignored and the other keys 1504 are processed normally. 1506 The element "kty" is a required element in a COSE_Key map. 1508 The CDDL grammar describing COSE_Key and COSE_KeySet is: 1510 COSE_Key = { 1511 1 => tstr / int, ; kty 1512 ? 2 => bstr, ; kid 1513 ? 3 => tstr / int, ; alg 1514 ? 4 => [+ (tstr / int) ], ; key_ops 1515 ? 5 => bstr, ; Base IV 1516 * label => values 1517 } 1519 COSE_KeySet = [+COSE_Key] 1521 7.1. COSE Key Common Parameters 1523 This document defines a set of common parameters for a COSE Key 1524 object. Table 3 provides a summary of the parameters defined in this 1525 section. There are also parameters that are defined for specific key 1526 types. Key type specific parameters can be found in Section 13. 1528 +---------+-------+----------------+------------+-------------------+ 1529 | name | label | CBOR type | registry | description | 1530 +---------+-------+----------------+------------+-------------------+ 1531 | kty | 1 | tstr / int | COSE Key | Identification of | 1532 | | | | Common | the key type | 1533 | | | | Parameters | | 1534 | | | | | | 1535 | alg | 3 | tstr / int | COSE | Key usage | 1536 | | | | Algorithm | restriction to | 1537 | | | | Values | this algorithm | 1538 | | | | | | 1539 | kid | 2 | bstr | | Key | 1540 | | | | | Identification | 1541 | | | | | value - match to | 1542 | | | | | kid in message | 1543 | | | | | | 1544 | key_ops | 4 | [+ (tstr/int)] | | Restrict set of | 1545 | | | | | permissible | 1546 | | | | | operations | 1547 | | | | | | 1548 | Base IV | 5 | bstr | | Base IV to be | 1549 | | | | | xor-ed with | 1550 | | | | | Partial IVs | 1551 +---------+-------+----------------+------------+-------------------+ 1553 Table 3: Key Map Labels 1555 kty: This parameter is used to identify the family of keys for this 1556 structure, and thus the set of key type specific parameters to be 1557 found. The set of values defined in this document can be found in 1558 Table 21. This parameter MUST be present in a key object. 1559 Implementations MUST verify that the key type is appropriate for 1560 the algorithm being processed. The key type MUST be included as 1561 part of the trust decision process. 1563 alg: This parameter is used to restrict the algorithm that is used 1564 with the key. If this parameter is present in the key structure, 1565 the application MUST verify that this algorithm matches the 1566 algorithm for which the key is being used. If the algorithms do 1567 not match, then this key object MUST NOT be used to perform the 1568 cryptographic operation. Note that the same key can be in a 1569 different key structure with a different or no algorithm 1570 specified, however this is considered to be a poor security 1571 practice. 1573 kid: This parameter is used to give an identifier for a key. The 1574 identifier is not structured and can be anything from a user 1575 provided string to a value computed on the public portion of the 1576 key. This field is intended for matching against a 'kid' 1577 parameter in a message in order to filter down the set of keys 1578 that need to be checked. 1580 key_ops: This parameter is defined to restrict the set of operations 1581 that a key is to be used for. The value of the field is an array 1582 of values from Table 4. Algorithms define the values of key ops 1583 that are permitted to appear and are required for specific 1584 operations. 1586 Base IV: This parameter is defined to carry the base portion of an 1587 IV. It is designed to be used with the partial IV header 1588 parameter defined in Section 3.1. This field provides the ability 1589 to associate a partial IV with a key that is then modified on a 1590 per message basis with the partial IV. 1592 Extreme care needs to be taken when using a Base IV in an 1593 application. Many encryption algorithms lose security if the same 1594 IV is used twice. 1596 If different keys are derived for each sender, starting at the 1597 same base IV is likely to satisfy this condition. If the same key 1598 is used for multiple senders, then the application needs to 1599 provide for a method of dividing the IV space up between the 1600 senders. This could be done by providing a different base point 1601 to start from or a different partial IV to start with and 1602 restricting the number of messages to be sent before re-keying. 1604 +---------+-------+-------------------------------------------------+ 1605 | name | value | description | 1606 +---------+-------+-------------------------------------------------+ 1607 | sign | 1 | The key is used to create signatures. Requires | 1608 | | | private key fields. | 1609 | | | | 1610 | verify | 2 | The key is used for verification of signatures. | 1611 | | | | 1612 | encrypt | 3 | The key is used for key transport encryption. | 1613 | | | | 1614 | decrypt | 4 | The key is used for key transport decryption. | 1615 | | | Requires private key fields. | 1616 | | | | 1617 | wrap | 5 | The key is used for key wrapping. | 1618 | key | | | 1619 | | | | 1620 | unwrap | 6 | The key is used for key unwrapping. Requires | 1621 | key | | private key fields. | 1622 | | | | 1623 | derive | 7 | The key is used for deriving keys. Requires | 1624 | key | | private key fields. | 1625 | | | | 1626 | derive | 8 | The key is used for deriving bits. Requires | 1627 | bits | | private key fields. | 1628 | | | | 1629 | MAC | 9 | The key is used for creating MACs. | 1630 | create | | | 1631 | | | | 1632 | MAC | 10 | The key is used for validating MACs. | 1633 | verify | | | 1634 +---------+-------+-------------------------------------------------+ 1636 Table 4: Key Operation Values 1638 8. Signature Algorithms 1640 There are two signature algorithm schemes. The first is signature 1641 with appendix. In this scheme, the message content is processed and 1642 a signature is produced, the signature is called the appendix. This 1643 is the scheme used by algorithms such as ECDSA and RSASSA-PSS. (In 1644 fact the SSA in RSASSA-PSS stands for Signature Scheme with 1645 Appendix.) 1647 The signature functions for this scheme are: 1649 signature = Sign(message content, key) 1651 valid = Verification(message content, key, signature) 1652 The second scheme is signature with message recovery. (An example of 1653 such an algorithm is [PVSig].) In this scheme, the message content 1654 is processed, but part of it is included in the signature. Moving 1655 bytes of the message content into the signature allows for smaller 1656 signatures, the signature size is still potentially large, but the 1657 message content has shrunk. This has implications for systems 1658 implementing these algorithms and for applications that use them. 1659 The first is that the message content is not fully available until 1660 after a signature has been validated. Until that point the part of 1661 the message contained inside of the signature is unrecoverable. The 1662 second is that the security analysis of the strength of the signature 1663 is very much based on the structure of the message content. Messages 1664 that are highly predictable require additional randomness to be 1665 supplied as part of the signature process. In the worst case, it 1666 becomes the same as doing a signature with appendix. Finally, in the 1667 event that multiple signatures are applied to a message, all of the 1668 signature algorithms are going to be required to consume the same 1669 number of bytes of message content. This means that mixing of the 1670 different schemes in a single message is not supported, and if a 1671 recovery signature scheme is used, then the same amount of content 1672 needs to be consumed by all of the signatures. 1674 The signature functions for this scheme are: 1676 signature, message sent = Sign(message content, key) 1678 valid, message content = Verification(message sent, key, signature) 1680 Signature algorithms are used with the COSE_Signature and COSE_Sign1 1681 structures. At this time, only signatures with appendixes are 1682 defined for use with COSE, however considerable interest has been 1683 expressed in using a signature with message recovery algorithm due to 1684 the effective size reduction that is possible. Implementations will 1685 need to keep this in mind for later possible integration. 1687 8.1. ECDSA 1689 ECDSA [DSS] defines a signature algorithm using ECC. 1691 The ECDSA signature algorithm is parameterized with a hash function 1692 (h). In the event that the length of the hash function output is 1693 greater than the group of the key, the left-most bytes of the hash 1694 output are used. 1696 The algorithms defined in this document can be found in Table 5. 1698 +-------+-------+---------+------------------+ 1699 | name | value | hash | description | 1700 +-------+-------+---------+------------------+ 1701 | ES256 | -7 | SHA-256 | ECDSA w/ SHA-256 | 1702 | | | | | 1703 | ES384 | -35 | SHA-384 | ECDSA w/ SHA-384 | 1704 | | | | | 1705 | ES512 | -36 | SHA-512 | ECDSA w/ SHA-512 | 1706 +-------+-------+---------+------------------+ 1708 Table 5: ECDSA Algorithm Values 1710 This document defines ECDSA to work only with the curves P-256, P-384 1711 and P-521. This document requires that the curves be encoded using 1712 the 'EC2' key type. Implementations need to check that the key type 1713 and curve are correct when creating and verifying a signature. Other 1714 documents can define it to work with other curves and points in the 1715 future. 1717 In order to promote interoperability, it is suggested that SHA-256 be 1718 used only with curve P-256, SHA-384 be used only with curve P-384 and 1719 SHA-512 be used with curve P-521. This is aligned with the 1720 recommendation in Section 4 of [RFC5480]. 1722 The signature algorithm results in a pair of integers (R, S). These 1723 integers will the same length as length of the key used for the 1724 signature process. The signature is encoded by converting the 1725 integers into byte strings of the same length as the key size. The 1726 length is rounded up to the nearest byte and is left padded with zero 1727 bits to get to the correct length. The two integers are then 1728 concatenated together to form a byte string that is the resulting 1729 signature. 1731 Using the function defined in [RFC3447] the signature is: 1732 Signature = I2OSP(R, n) | I2OSP(S, n) 1733 where n = ceiling(key_length / 8) 1735 When using a COSE key for this algorithm, the following checks are 1736 made: 1738 o The 'kty' field MUST be present and it MUST be 'EC2'. 1740 o If the 'alg' field is present, it MUST match the ECDSA signature 1741 algorithm being used. 1743 o If the 'key_ops' field is present, it MUST include 'sign' when 1744 creating an ECDSA signature. 1746 o If the 'key_ops' field is present, it MUST include 'verify' when 1747 verifying an ECDSA signature. 1749 8.1.1. Security Considerations 1751 The security strength of the signature is no greater than the minimum 1752 of the security strength associated with the bit length of the key 1753 and the security strength of the hash function. 1755 Systems that have poor random number generation can leak their keys 1756 by signing two different messages with the same value 'k' (the per- 1757 message random value). [RFC6979] provides a method to deal with this 1758 problem by making 'k' be deterministic based on the message content 1759 rather than randomly generated. Applications that specify ECDSA 1760 should evaluate the ability to get good random number generation and 1761 require deterministic signatures where poor random number generation 1762 exists. 1764 Note: Use of this technique is a good idea even when good random 1765 number generation exists. Doing so both reduces the possibility of 1766 having the same value of 'k' in two signature operations and allows 1767 for reproducible signature values, which helps testing. 1769 There are two substitution attacks that can theoretically be mounted 1770 against the ECDSA signature algorithm. 1772 o Changing the curve used to validate the signature: If one changes 1773 the curve used to validate the signature, then potentially one 1774 could have a two messages with the same signature each computed 1775 under a different curve. The only requirement on the new curve is 1776 that its order be the same as the old one and it be acceptable to 1777 the client. An example would be to change from using the curve 1778 secp256r1 (aka P-256) to using secp256k1. (Both are 256 bit 1779 curves.) We current do not have any way to deal with this version 1780 of the attack except to restrict the overall set of curves that 1781 can be used. 1783 o Change the hash function used to validate the signature: If one 1784 has either two different hash functions of the same length, or one 1785 can truncate a hash function down, then one could potentially find 1786 collisions between the hash functions rather than within a single 1787 hash function. (For example, truncating SHA-512 to 256 bits might 1788 collide with a SHA-256 bit hash value.) As the hash algorithm is 1789 part of the signature algorithm identifier, this attack is 1790 mitigated by including signature algorithm identifier in the 1791 protected header. 1793 8.2. Edwards-curve Digital Signature Algorithms (EdDSA) 1795 [I-D.irtf-cfrg-eddsa] describes the elliptic curve signature scheme 1796 Edwards-curve Digital Signature Algorithm (EdDSA). In that document, 1797 the signature algorithm is instantiated using parameters for 1798 edwards25519 and edwards448 curves. The document additionally 1799 describes two variants of the EdDSA algorithm: Pure EdDSA, where no 1800 hash function is applied to the content before signing and, HashEdDSA 1801 where a hash function is applied to the content before signing and 1802 the result of that hash function is signed. For the EdDSA, the 1803 content to be signed (either the message or the pre-hash value) is 1804 processed twice inside of the signature algorithm. For use with 1805 COSE, only the pure EdDSA version is used. This is because it is not 1806 expected that extremely large contents are going to be needed and, 1807 based on the arrangement of the message structure, the entire message 1808 is going to need to be held in memory in order to create or verify a 1809 signature. This means that there does not appear to be a need to be 1810 able to do block updates of the hash, followed by eliminating the 1811 message from memory. Applications can provide the same features by 1812 defining the content of the message as a hash value and transporting 1813 the COSE object (with the hash value) and the content as separate 1814 items. 1816 The algorithms defined in this document can be found in Table 6. A 1817 single signature algorithm is defined, which can be used for multiple 1818 curves. 1820 +-------+-------+-------------+ 1821 | name | value | description | 1822 +-------+-------+-------------+ 1823 | EdDSA | -8 | EdDSA | 1824 +-------+-------+-------------+ 1826 Table 6: EdDSA Algorithm Values 1828 [I-D.irtf-cfrg-eddsa] describes the method of encoding the signature 1829 value. 1831 When using a COSE key for this algorithm the following checks are 1832 made: 1834 o The 'kty' field MUST be present and it MUST be 'OKP'. 1836 o The 'crv' field MUST be present, and it MUST be a curve defined 1837 for this signature algorithm. 1839 o If the 'alg' field is present, it MUST match 'EdDSA'. 1841 o If the 'key_ops' field is present, it MUST include 'sign' when 1842 creating an EdDSA signature. 1844 o If the 'key_ops' field is present, it MUST include 'verify' when 1845 verifying an EdDSA signature. 1847 8.2.1. Security Considerations 1849 The Edwards curves for EdDSA and ECDH are distinct and should not be 1850 used for the other algorithm. 1852 If batch signature verification is performed, a well-seeded 1853 cryptographic random number generator is REQUIRED. Signing and non- 1854 batch signature verification are deterministic operations and do not 1855 need random numbers of any kind. 1857 9. Message Authentication (MAC) Algorithms 1859 Message Authentication Codes (MACs) provide data authentication and 1860 integrity protection. They provide either no or very limited data 1861 origination. A MAC, for example, be used to prove the identity of 1862 the sender to a third party. 1864 MACs use the same scheme as signature with appendix algorithms. The 1865 message content is processed and an authentication code is produced. 1866 The authentication code is frequently called a tag. 1868 The MAC functions are: 1870 tag = MAC_Create(message content, key) 1872 valid = MAC_Verify(message content, key, tag) 1874 MAC algorithms can be based on either a block cipher algorithm (i.e., 1875 AES-MAC) or a hash algorithm (i.e., HMAC). This document defines a 1876 MAC algorithm using each of these constructions. 1878 MAC algorithms are used in the COSE_Mac and COSE_Mac0 structures. 1880 9.1. Hash-based Message Authentication Codes (HMAC) 1882 The Hash-based Message Authentication Code algorithm (HMAC) 1883 [RFC2104][RFC4231] was designed to deal with length extension 1884 attacks. The algorithm was also designed to allow for new hash 1885 algorithms to be directly plugged in without changes to the hash 1886 function. The HMAC design process has been shown as solid since, 1887 while the security of hash algorithms such as MD5 has decreased over 1888 time, the security of HMAC combined with MD5 has not yet been shown 1889 to be compromised [RFC6151]. 1891 The HMAC algorithm is parameterized by an inner and outer padding, a 1892 hash function (h), and an authentication tag value length. For this 1893 specification, the inner and outer padding are fixed to the values 1894 set in [RFC2104]. The length of the authentication tag corresponds 1895 to the difficulty of producing a forgery. For use in constrained 1896 environments, we define a set of HMAC algorithms that are truncated. 1897 There are currently no known issues with truncation, however the 1898 security strength of the message tag is correspondingly reduced in 1899 strength. When truncating, the left-most tag length bits are kept 1900 and transmitted. 1902 The algorithms defined in this document can be found in Table 7. 1904 +-----------+-------+---------+----------+--------------------------+ 1905 | name | value | Hash | Tag | description | 1906 | | | | Length | | 1907 +-----------+-------+---------+----------+--------------------------+ 1908 | HMAC | 4 | SHA-256 | 64 | HMAC w/ SHA-256 | 1909 | 256/64 | | | | truncated to 64 bits | 1910 | | | | | | 1911 | HMAC | 5 | SHA-256 | 256 | HMAC w/ SHA-256 | 1912 | 256/256 | | | | | 1913 | | | | | | 1914 | HMAC | 6 | SHA-384 | 384 | HMAC w/ SHA-384 | 1915 | 384/384 | | | | | 1916 | | | | | | 1917 | HMAC | 7 | SHA-512 | 512 | HMAC w/ SHA-512 | 1918 | 512/512 | | | | | 1919 +-----------+-------+---------+----------+--------------------------+ 1921 Table 7: HMAC Algorithm Values 1923 Some recipient algorithms carry the key while others derive a key 1924 from secret data. For those algorithms that carry the key (such as 1925 AES-KeyWrap), the size of the HMAC key SHOULD be the same size as the 1926 underlying hash function. For those algorithms that derive the key 1927 (such as ECDH), the derived key MUST be the same size as the 1928 underlying hash function. 1930 When using a COSE key for this algorithm, the following checks are 1931 made: 1933 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 1935 o If the 'alg' field is present, it MUST match the HMAC algorithm 1936 being used. 1938 o If the 'key_ops' field is present, it MUST include 'MAC create' 1939 when creating an HMAC authentication tag. 1941 o If the 'key_ops' field is present, it MUST include 'MAC verify' 1942 when verifying an HMAC authentication tag. 1944 Implementations creating and validating MAC values MUST validate that 1945 the key type, key length, and algorithm are correct and appropriate 1946 for the entities involved. 1948 9.1.1. Security Considerations 1950 HMAC has proved to be resistant to attack even when used with 1951 weakened hash algorithms. The current best known attack appears is 1952 to brute force the key. This means that key size is going to be 1953 directly related to the security of an HMAC operation. 1955 9.2. AES Message Authentication Code (AES-CBC-MAC) 1957 AES-CBC-MAC is defined in [MAC]. (Note this is not the same 1958 algorithm as AES-CMAC [RFC4493]). 1960 AES-CBC-MAC is parameterized by the key length, the authentication 1961 tag length and the IV used. For all of these algorithms, the IV is 1962 fixed to all zeros. We provide an array of algorithms for various 1963 key lengths and tag lengths. The algorithms defined in this document 1964 are found in Table 8. 1966 +-------------+-------+----------+----------+-----------------------+ 1967 | name | value | key | tag | description | 1968 | | | length | length | | 1969 +-------------+-------+----------+----------+-----------------------+ 1970 | AES-MAC | 14 | 128 | 64 | AES-MAC 128 bit key, | 1971 | 128/64 | | | | 64-bit tag | 1972 | | | | | | 1973 | AES-MAC | 15 | 256 | 64 | AES-MAC 256 bit key, | 1974 | 256/64 | | | | 64-bit tag | 1975 | | | | | | 1976 | AES-MAC | 25 | 128 | 128 | AES-MAC 128 bit key, | 1977 | 128/128 | | | | 128-bit tag | 1978 | | | | | | 1979 | AES-MAC | 26 | 256 | 128 | AES-MAC 256 bit key, | 1980 | 256/128 | | | | 128-bit tag | 1981 +-------------+-------+----------+----------+-----------------------+ 1983 Table 8: AES-MAC Algorithm Values 1985 Keys may be obtained either from a key structure or from a recipient 1986 structure. Implementations creating and validating MAC values MUST 1987 validate that the key type, key length and algorithm are correct and 1988 appropriate for the entities involved. 1990 When using a COSE key for this algorithm, the following checks are 1991 made: 1993 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 1995 o If the 'alg' field is present, it MUST match the AES-MAC algorithm 1996 being used. 1998 o If the 'key_ops' field is present, it MUST include 'MAC create' 1999 when creating an AES-MAC authentication tag. 2001 o If the 'key_ops' field is present, it MUST include 'MAC verify' 2002 when verifying an AES-MAC authentication tag. 2004 9.2.1. Security Considerations 2006 A number of attacks exist against CBC-MAC that need to be considered. 2007 - 2009 o A single key must only be used for messages of a fixed and known 2010 length. If this is not the case, an attacker will be able to 2011 generate a message with a valid tag given two message and tag 2012 pairs. This can be addressed by using different keys for 2013 different length messages. The current structure mitigates this 2014 problem, as a specific encoding structure that includes lengths is 2015 built and signed. (CMAC also addresses this issue.) 2017 o When using CBC mode, if the same key is used for both encryption 2018 and authentication operations, an attacker can produce messages 2019 with a valid authentication code. 2021 o If the IV can be modified, then messages can be forged. This is 2022 addressed by fixing the IV to all zeros. 2024 10. Content Encryption Algorithms 2026 Content Encryption Algorithms provide data confidentiality for 2027 potentially large blocks of data using a symmetric key. They provide 2028 integrity on the data that was encrypted, however they provide either 2029 no or very limited data origination. (One cannot, for example, be 2030 used to prove the identity of the sender to a third party.) The 2031 ability to provide data origination is linked to how the CEK is 2032 obtained. 2034 COSE restricts the set of legal content encryption algorithms to 2035 those that support authentication both of the content and additional 2036 data. The encryption process will generate some type of 2037 authentication value, but that value may be either explicit or 2038 implicit in terms of the algorithm definition. For simplicity sake, 2039 the authentication code will normally be defined as being appended to 2040 the cipher text stream. The encryption functions are: 2042 ciphertext = Encrypt(message content, key, additional data) 2044 valid, message content = Decrypt(cipher text, key, additional data) 2046 Most AEAD algorithms are logically defined as returning the message 2047 content only if the decryption is valid. Many but not all 2048 implementations will follow this convention. The message content 2049 MUST NOT be used if the decryption does not validate. 2051 These algorithms are used in COSE_Encrypt and COSE_Encrypt0. 2053 10.1. AES GCM 2055 The GCM mode is a generic authenticated encryption block cipher mode 2056 defined in [AES-GCM]. The GCM mode is combined with the AES block 2057 encryption algorithm to define an AEAD cipher. 2059 The GCM mode is parameterized by the size of the authentication tag 2060 and the size of the nonce. This document fixes the size of the nonce 2061 at 96 bits. The size of the authentication tag is limited to a small 2062 set of values. For this document however, the size of the 2063 authentication tag is fixed at 128 bits. 2065 The set of algorithms defined in this document are in Table 9. 2067 +---------+-------+------------------------------------------+ 2068 | name | value | description | 2069 +---------+-------+------------------------------------------+ 2070 | A128GCM | 1 | AES-GCM mode w/ 128-bit key, 128-bit tag | 2071 | | | | 2072 | A192GCM | 2 | AES-GCM mode w/ 192-bit key, 128-bit tag | 2073 | | | | 2074 | A256GCM | 3 | AES-GCM mode w/ 256-bit key, 128-bit tag | 2075 +---------+-------+------------------------------------------+ 2077 Table 9: Algorithm Value for AES-GCM 2079 Keys may be obtained either from a key structure or from a recipient 2080 structure. Implementations encrypting and decrypting MUST validate 2081 that the key type, key length and algorithm are correct and 2082 appropriate for the entities involved. 2084 When using a COSE key for this algorithm, the following checks are 2085 made: 2087 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2089 o If the 'alg' field is present, it MUST match the AES-GCM algorithm 2090 being used. 2092 o If the 'key_ops' field is present, it MUST include 'encrypt' or 2093 'wrap key' when encrypting. 2095 o If the 'key_ops' field is present, it MUST include 'decrypt' or 2096 'unwrap key' when decrypting. 2098 10.1.1. Security Considerations 2100 When using AES-GCM, the following restrictions MUST be enforced: 2102 o The key and nonce pair MUST be unique for every message encrypted. 2104 o The total amount of data encrypted for a single key MUST NOT 2105 exceed 2^39 - 256 bits. An explicit check is required only in 2106 environments where it is expected that it might be exceeded. 2108 Consideration was given to supporting smaller tag values; the 2109 constrained community would desire tag sizes in the 64-bit range. 2111 Doing so drastically changes both the maximum messages size 2112 (generally not an issue) and the number of times that a key can be 2113 used. Given that CCM is the usual mode for constrained environments, 2114 restricted modes are not supported. 2116 10.2. AES CCM 2118 Counter with CBC-MAC (CCM) is a generic authentication encryption 2119 block cipher mode defined in [RFC3610]. The CCM mode is combined 2120 with the AES block encryption algorithm to define a commonly used 2121 content encryption algorithm used in constrained devices. 2123 The CCM mode has two parameter choices. The first choice is M, the 2124 size of the authentication field. The choice of the value for M 2125 involves a trade-off between message growth (from the tag) and the 2126 probably that an attacker can undetectably modify a message. The 2127 second choice is L, the size of the length field. This value 2128 requires a trade-off between the maximum message size and the size of 2129 the Nonce. 2131 It is unfortunate that the specification for CCM specified L and M as 2132 a count of bytes rather than a count of bits. This leads to possible 2133 misunderstandings where AES-CCM-8 is frequently used to refer to a 2134 version of CCM mode where the size of the authentication is 64 bits 2135 and not 8 bits. These values have traditionally been specified as 2136 bit counts rather than byte counts. This document will follow the 2137 convention of using bit counts so that it is easier to compare the 2138 different algorithms presented in this document. 2140 We define a matrix of algorithms in this document over the values of 2141 L and M. Constrained devices are usually operating in situations 2142 where they use short messages and want to avoid doing recipient 2143 specific cryptographic operations. This favors smaller values of 2144 both L and M. Less constrained devices will want to be able to use 2145 larger messages and are more willing to generate new keys for every 2146 operation. This favors larger values of L and M. 2148 The following values are used for L: 2150 16 bits (2) limits messages to 2^16 bytes (64 KiB) in length. This 2151 is sufficiently long for messages in the constrained world. The 2152 nonce length is 13 bytes allowing for 2^(13*8) possible values of 2153 the nonce without repeating. 2155 64 bits (8) limits messages to 2^64 bytes in length. The nonce 2156 length is 7 bytes allowing for 2^56 possible values of the nonce 2157 without repeating. 2159 The following values are used for M: 2161 64 bits (8) produces a 64-bit authentication tag. This implies that 2162 there is a 1 in 2^64 chance that a modified message will 2163 authenticate. 2165 128 bits (16) produces a 128-bit authentication tag. This implies 2166 that there is a 1 in 2^128 chance that a modified message will 2167 authenticate. 2169 +--------------------+-------+----+-----+-----+---------------------+ 2170 | name | value | L | M | k | description | 2171 +--------------------+-------+----+-----+-----+---------------------+ 2172 | AES-CCM-16-64-128 | 10 | 16 | 64 | 128 | AES-CCM mode | 2173 | | | | | | 128-bit key, 64-bit | 2174 | | | | | | tag, 13-byte nonce | 2175 | | | | | | | 2176 | AES-CCM-16-64-256 | 11 | 16 | 64 | 256 | AES-CCM mode | 2177 | | | | | | 256-bit key, 64-bit | 2178 | | | | | | tag, 13-byte nonce | 2179 | | | | | | | 2180 | AES-CCM-64-64-128 | 12 | 64 | 64 | 128 | AES-CCM mode | 2181 | | | | | | 128-bit key, 64-bit | 2182 | | | | | | tag, 7-byte nonce | 2183 | | | | | | | 2184 | AES-CCM-64-64-256 | 13 | 64 | 64 | 256 | AES-CCM mode | 2185 | | | | | | 256-bit key, 64-bit | 2186 | | | | | | tag, 7-byte nonce | 2187 | | | | | | | 2188 | AES-CCM-16-128-128 | 30 | 16 | 128 | 128 | AES-CCM mode | 2189 | | | | | | 128-bit key, | 2190 | | | | | | 128-bit tag, | 2191 | | | | | | 13-byte nonce | 2192 | | | | | | | 2193 | AES-CCM-16-128-256 | 31 | 16 | 128 | 256 | AES-CCM mode | 2194 | | | | | | 256-bit key, | 2195 | | | | | | 128-bit tag, | 2196 | | | | | | 13-byte nonce | 2197 | | | | | | | 2198 | AES-CCM-64-128-128 | 32 | 64 | 128 | 128 | AES-CCM mode | 2199 | | | | | | 128-bit key, | 2200 | | | | | | 128-bit tag, 7-byte | 2201 | | | | | | nonce | 2202 | | | | | | | 2203 | AES-CCM-64-128-256 | 33 | 64 | 128 | 256 | AES-CCM mode | 2204 | | | | | | 256-bit key, | 2205 | | | | | | 128-bit tag, 7-byte | 2206 | | | | | | nonce | 2207 +--------------------+-------+----+-----+-----+---------------------+ 2209 Table 10: Algorithm Values for AES-CCM 2211 Keys may be obtained either from a key structure or from a recipient 2212 structure. Implementations encrypting and decrypting MUST validate 2213 that the key type, key length and algorithm are correct and 2214 appropriate for the entities involved. 2216 When using a COSE key for this algorithm, the following checks are 2217 made: 2219 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2221 o If the 'alg' field is present, it MUST match the AES-CCM algorithm 2222 being used. 2224 o If the 'key_ops' field is present, it MUST include 'encrypt' or 2225 'wrap key' when encrypting. 2227 o If the 'key_ops' field is present, it MUST include 'decrypt' or 2228 'unwrap key' when decrypting. 2230 10.2.1. Security Considerations 2232 When using AES-CCM, the following restrictions MUST be enforced: 2234 o The key and nonce pair MUST be unique for every message encrypted. 2235 Note that the value of L influences the number of unique nonces. 2237 o The total number of times the AES block cipher is used MUST NOT 2238 exceed 2^61 operations. This limitation is the sum of times the 2239 block cipher is used in computing the MAC value and in performing 2240 stream encryption operations. An explicit check is required only 2241 in environments where it is expected that it might be exceeded. 2243 [RFC3610] additionally calls out one other consideration of note. It 2244 is possible to do a pre-computation attack against the algorithm in 2245 cases where portions of the plaintext are highly predictable. This 2246 reduces the security of the key size by half. Ways to deal with this 2247 attack include adding a random portion to the nonce value and/or 2248 increasing the key size used. Using a portion of the nonce for a 2249 random value will decrease the number of messages that a single key 2250 can be used for. Increasing the key size may require more resources 2251 in the constrained device. See sections 5 and 10 of [RFC3610] for 2252 more information. 2254 10.3. ChaCha20 and Poly1305 2256 ChaCha20 and Poly1305 combined together is an AEAD mode that is 2257 defined in [RFC7539]. This is an algorithm defined to be a cipher 2258 that is not AES and thus would not suffer from any future weaknesses 2259 found in AES. These cryptographic functions are designed to be fast 2260 in software-only implementations. 2262 The ChaCha20/Poly1305 AEAD construction defined in [RFC7539] has no 2263 parameterization. It takes a 256-bit key and a 96-bit nonce, as well 2264 as the plain text and additional data as inputs and produces the 2265 cipher text as an option. We define one algorithm identifier for 2266 this algorithm in Table 11. 2268 +-------------------+-------+---------------------------------------+ 2269 | name | value | description | 2270 +-------------------+-------+---------------------------------------+ 2271 | ChaCha20/Poly1305 | 24 | ChaCha20/Poly1305 w/ 256-bit key, | 2272 | | | 128-bit tag | 2273 +-------------------+-------+---------------------------------------+ 2275 Table 11: Algorithm Value for AES-GCM 2277 Keys may be obtained either from a key structure or from a recipient 2278 structure. Implementations encrypting and decrypting MUST validate 2279 that the key type, key length and algorithm are correct and 2280 appropriate for the entities involved. 2282 When using a COSE key for this algorithm, the following checks are 2283 made: 2285 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2287 o If the 'alg' field is present, it MUST match the ChaCha20/Poly1305 2288 algorithm being used. 2290 o If the 'key_ops' field is present, it MUST include 'encrypt' or 2291 'wrap key' when encrypting. 2293 o If the 'key_ops' field is present, it MUST include 'decrypt' or 2294 'unwrap key' when decrypting. 2296 10.3.1. Security Considerations 2298 The pair of key, nonce MUST be unique for every invocation of the 2299 algorithm. Nonce counters are considered to be an acceptable way of 2300 ensuring that they are unique. 2302 11. Key Derivation Functions (KDF) 2304 Key Derivation Functions (KDFs) are used to take some secret value 2305 and generate a different one. The secret value comes in three 2306 flavors: 2308 o Secrets that are uniformly random: This is the type of secret that 2309 is created by a good random number generator. 2311 o Secrets that are not uniformly random: This is type of secret that 2312 is created by operations like key agreement. 2314 o Secrets that are not random: This is the type of secret that 2315 people generate for things like passwords. 2317 General KDF functions work well with the first type of secret, can do 2318 reasonably well with the second type of secret, and generally do 2319 poorly with the last type of secret. None of the KDF functions in 2320 this section are designed to deal with the type of secrets that are 2321 used for passwords. Functions like PBES2 [RFC2898] need to be used 2322 for that type of secret. 2324 The same KDF function can be setup to deal with the first two types 2325 of secrets in a different way. The KDF function defined in 2326 Section 11.1 is such a function. This is reflected in the set of 2327 algorithms defined for HKDF. 2329 When using KDF functions, one component that is included is context 2330 information. Context information is used to allow for different 2331 keying information to be derived from the same secret. The use of 2332 context based keying material is considered to be a good security 2333 practice. 2335 This document defines a single context structure and a single KDF 2336 function. These elements are used for all of the recipient 2337 algorithms defined in this document that require a KDF process. 2338 These algorithms are defined in Section 12.1.2, Section 12.4.1, and 2339 Section 12.5.1. 2341 11.1. HMAC-based Extract-and-Expand Key Derivation Function (HKDF) 2343 The HKDF key derivation algorithm is defined in [RFC5869]. 2345 The HKDF algorithm takes these inputs: 2347 secret - a shared value that is secret. Secrets may be either 2348 previously shared or derived from operations like a DH key 2349 agreement. 2351 salt - an optional value that is used to change the generation 2352 process. The salt value can be either public or private. If the 2353 salt is public and carried in the message, then the 'salt' 2354 algorithm header parameter defined in Table 13 is used. While 2355 [RFC5869] suggests that the length of the salt be the same as the 2356 length of the underlying hash value, any amount of salt will 2357 improve the security as different key values will be generated. 2358 This parameter is protected by being included in the key 2359 computation and does not need to be separately authenticated. The 2360 salt value does not need to be unique for every message sent. 2362 length - the number of bytes of output that need to be generated. 2364 context information - Information that describes the context in 2365 which the resulting value will be used. Making this information 2366 specific to the context in which the material is going to be used 2367 ensures that the resulting material will always be tied to that 2368 usage. The context structure defined in Section 11.2 is used by 2369 the KDF functions in this document. 2371 PRF - The underlying pseudo-random function to be used in the HKDF 2372 algorithm. The PRF is encoded into the HKDF algorithm selection. 2374 HKDF is defined to use HMAC as the underlying PRF. However, it is 2375 possible to use other functions in the same construct to provide a 2376 different KDF function that is more appropriate in the constrained 2377 world. Specifically, one can use AES-CBC-MAC as the PRF for the 2378 expand step, but not for the extract step. When using a good random 2379 shared secret of the correct length, the extract step can be skipped. 2380 For the AES algorithm versions, the extract step is always skipped. 2382 The extract step cannot be skipped if the secret is not uniformly 2383 random, for example, if it is the result of an ECDH key agreement 2384 step. (This implies that the AES HKDF version cannot be used with 2385 ECDH.) If the extract step is skipped, the 'salt' value is not used 2386 as part of the HKDF functionality. 2388 The algorithms defined in this document are found in Table 12. 2390 +---------------+-----------------+---------------------------------+ 2391 | name | PRF | description | 2392 +---------------+-----------------+---------------------------------+ 2393 | HKDF SHA-256 | HMAC with | HKDF using HMAC SHA-256 as the | 2394 | | SHA-256 | PRF | 2395 | | | | 2396 | HKDF SHA-512 | HMAC with | HKDF using HMAC SHA-512 as the | 2397 | | SHA-512 | PRF | 2398 | | | | 2399 | HKDF AES- | AES-CBC-MAC-128 | HKDF using AES-MAC as the PRF | 2400 | MAC-128 | | w/ 128-bit key | 2401 | | | | 2402 | HKDF AES- | AES-CBC-MAC-256 | HKDF using AES-MAC as the PRF | 2403 | MAC-256 | | w/ 256-bit key | 2404 +---------------+-----------------+---------------------------------+ 2406 Table 12: HKDF algorithms 2408 +------+-------+------+-------------+ 2409 | name | label | type | description | 2410 +------+-------+------+-------------+ 2411 | salt | -20 | bstr | Random salt | 2412 +------+-------+------+-------------+ 2414 Table 13: HKDF Algorithm Parameters 2416 11.2. Context Information Structure 2418 The context information structure is used to ensure that the derived 2419 keying material is "bound" to the context of the transaction. The 2420 context information structure used here is based on that defined in 2421 [SP800-56A]. By using CBOR for the encoding of the context 2422 information structure, we automatically get the same type and length 2423 separation of fields that is obtained by the use of ASN.1. This 2424 means that there is no need to encode the lengths for the base 2425 elements as it is done by the encoding used in JOSE (Section 4.6.2 of 2426 [RFC7518]). 2428 The context information structure refers to PartyU and PartyV as the 2429 two parties that are doing the key derivation. Unless the 2430 application protocol defines differently, we assign PartyU to the 2431 entity that is creating the message and PartyV to the entity that is 2432 receiving the message. By doing this association, different keys 2433 will be derived for each direction as the context information is 2434 different in each direction. 2436 The context structure is built from information that is known to both 2437 entities. This information can be obtained from a variety of 2438 sources: 2440 o Fields can be defined by the application. This is commonly used 2441 to assign fixed names to parties, but can be used for other items 2442 such as nonces. 2444 o Fields can be defined by usage of the output. Examples of this 2445 are the algorithm and key size that are being generated. 2447 o Fields can be defined by parameters from the message. We define a 2448 set of parameters in Table 14 that can be used to carry the values 2449 associated with the context structure. Examples of this are 2450 identities and nonce values. These parameters are designed to be 2451 placed in the unprotected bucket of the recipient structure. 2452 (They do not need to be in the protected bucket since they already 2453 are included in the cryptographic computation by virtue of being 2454 included in the context structure.) 2456 +---------------+-------+-----------+-------------------------------+ 2457 | name | label | type | description | 2458 +---------------+-------+-----------+-------------------------------+ 2459 | PartyU | -21 | bstr | Party U identity Information | 2460 | identity | | | | 2461 | | | | | 2462 | PartyU nonce | -22 | bstr / | Party U provided nonce | 2463 | | | int | | 2464 | | | | | 2465 | PartyU other | -23 | bstr | Party U other provided | 2466 | | | | information | 2467 | | | | | 2468 | PartyV | -24 | bstr | Party V identity Information | 2469 | identity | | | | 2470 | | | | | 2471 | PartyV nonce | -25 | bstr / | Party V provided nonce | 2472 | | | int | | 2473 | | | | | 2474 | PartyV other | -26 | bstr | Party V other provided | 2475 | | | | information | 2476 +---------------+-------+-----------+-------------------------------+ 2478 Table 14: Context Algorithm Parameters 2480 We define a CBOR object to hold the context information. This object 2481 is referred to as CBOR_KDF_Context. The object is based on a CBOR 2482 array type. The fields in the array are: 2484 AlgorithmID This field indicates the algorithm for which the key 2485 material will be used. This normally is either a Key Wrap 2486 algorithm identifier or a Content Encryption algorithm identifier. 2487 The values are from the "COSE Algorithm Value" registry. This 2488 field is required to be present. The field exists in the context 2489 information so that if the same environment is used for different 2490 algorithms, then completely different keys will be generated for 2491 each of those algorithms. (This practice means if algorithm A is 2492 broken and thus is easier to find, the key derived for algorithm B 2493 will not be the same as the key derived for algorithm A.) 2495 PartyUInfo This field holds information about party U. The 2496 PartyUInfo is encoded as a CBOR array. The elements of PartyUInfo 2497 are encoded in the order presented, however if the element does 2498 not exist no element is placed in the array. The elements of the 2499 PartyUInfo array are: 2501 identity This contains the identity information for party U. The 2502 identities can be assigned in one of two manners. Firstly, a 2503 protocol can assign identities based on roles. For example, 2504 the roles of "client" and "server" may be assigned to different 2505 entities in the protocol. Each entity would then use the 2506 correct label for the data they send or receive. The second 2507 way for a protocol to assign identities is to use a name based 2508 on a naming system (i.e., DNS, X.509 names). 2509 We define an algorithm parameter 'PartyU identity' that can be 2510 used to carry identity information in the message. However, 2511 identity information is often known as part of the protocol and 2512 can thus be inferred rather than made explicit. If identity 2513 information is carried in the message, applications SHOULD have 2514 a way of validating the supplied identity information. The 2515 identity information does not need to be specified and is set 2516 to nil in that case. 2518 nonce This contains a nonce value. The nonce can either be 2519 implicit from the protocol or carried as a value in the 2520 unprotected headers. 2521 We define an algorithm parameter 'PartyU nonce' that can be 2522 used to carry this value in the message However, the nonce 2523 value could be determined by the application and the value 2524 determined from elsewhere. 2525 This option does not need to be specified and is set to nil in 2526 that case 2528 other This contains other information that is defined by the 2529 protocol. 2530 This option does not need to be specified and is set to nil in 2531 that case 2533 PartyVInfo This field holds information about party V. The content 2534 of the structure are the same as for the PartyUInfo but for party 2535 V. 2537 SuppPubInfo This field contains public information that is mutually 2538 known to both parties. 2540 keyDataLength This is set to the number of bits of the desired 2541 output value. (This practice means if algorithm A can use two 2542 different key lengths, the key derived for longer key size will 2543 not contain the key for shorter key size as a prefix.) 2545 protected This field contains the protected parameter field. If 2546 there are no elements in the protected field, then use a zero 2547 length bstr. 2549 other This field is for free form data defined by the 2550 application. An example is that an application could define 2551 two different strings to be placed here to generate different 2552 keys for a data stream vs a control stream. This field is 2553 optional and will only be present if the application defines a 2554 structure for this information. Applications that define this 2555 SHOULD use CBOR to encode the data so that types and lengths 2556 are correctly included. 2558 SuppPrivInfo This field contains private information that is 2559 mutually known private information. An example of this 2560 information would be a pre-existing shared secret. (This could, 2561 for example, be used in combination with an ECDH key agreement to 2562 provide a secondary proof of identity.) The field is optional and 2563 will only be present if the application defines a structure for 2564 this information. Applications that define this SHOULD use CBOR 2565 to encode the data so that types and lengths are correctly 2566 included. 2568 The following CDDL fragment corresponds to the text above. 2570 PartyInfo = ( 2571 identity : bstr / nil, 2572 nonce : bstr / int / nil, 2573 other : bstr / nil, 2574 ) 2576 COSE_KDF_Context = [ 2577 AlgorithmID : int / tstr, 2578 PartyUInfo : [ PartyInfo ], 2579 PartyVInfo : [ PartyInfo ], 2580 SuppPubInfo : [ 2581 keyDataLength : uint, 2582 protected : empty_or_serialized_map, 2583 ? other : bstr 2584 ], 2585 ? SuppPrivInfo : bstr 2586 ] 2588 12. Content Key Distribution Methods 2590 Content key distribution methods (recipient algorithms) can be 2591 defined into a number of different classes. COSE has the ability to 2592 support many classes of recipient algorithms. In this section, a 2593 number of classes are listed and then a set of algorithms are 2594 specified for each of the classes. The names of the recipient 2595 algorithm classes used here are the same as are defined in [RFC7516]. 2596 Other specifications use different terms for the recipient algorithm 2597 classes or do not support some of the recipient algorithm classes. 2599 12.1. Direct Encryption 2601 The direct encryption class algorithms share a secret between the 2602 sender and the recipient that is used either directly or after 2603 manipulation as the CEK. When direct encryption mode is used, it 2604 MUST be the only mode used on the message. 2606 The COSE_Encrypt structure for the recipient is organized as follows: 2608 o The 'protected' field MUST be a zero length item unless it is used 2609 in the computation of the content key. 2611 o The 'alg' parameter MUST be present. 2613 o A parameter identifying the shared secret SHOULD be present. 2615 o The 'ciphertext' field MUST be a zero length item. 2617 o The 'recipients' field MUST be absent. 2619 12.1.1. Direct Key 2621 This recipient algorithm is the simplest; the identified key is 2622 directly used as the key for the next layer down in the message. 2623 There are no algorithm parameters defined for this algorithm. The 2624 algorithm identifier value is assigned in Table 15. 2626 When this algorithm is used, the protected field MUST be zero length. 2627 The key type MUST be 'Symmetric'. 2629 +--------+-------+-------------------+ 2630 | name | value | description | 2631 +--------+-------+-------------------+ 2632 | direct | -6 | Direct use of CEK | 2633 +--------+-------+-------------------+ 2635 Table 15: Direct Key 2637 12.1.1.1. Security Considerations 2639 This recipient algorithm has several potential problems that need to 2640 be considered: 2642 o These keys need to have some method to be regularly updated over 2643 time. All of the content encryption algorithms specified in this 2644 document have limits on how many times a key can be used without 2645 significant loss of security. 2647 o These keys need to be dedicated to a single algorithm. There have 2648 been a number of attacks developed over time when a single key is 2649 used for multiple different algorithms. One example of this is 2650 the use of a single key both for CBC encryption mode and CBC-MAC 2651 authentication mode. 2653 o Breaking one message means all messages are broken. If an 2654 adversary succeeds in determining the key for a single message, 2655 then the key for all messages is also determined. 2657 12.1.2. Direct Key with KDF 2659 These recipient algorithms take a common shared secret between the 2660 two parties and applies the HKDF function (Section 11.1), using the 2661 context structure defined in Section 11.2 to transform the shared 2662 secret into the CEK. The 'protected' field can be of non-zero 2663 length. Either the 'salt' parameter of HKDF or the partyU 'nonce' 2664 parameter of the context structure MUST be present. The salt/nonce 2665 parameter can be generated either randomly or deterministically. The 2666 requirement is that it be a unique value for the shared secret in 2667 question. 2669 If the salt/nonce value is generated randomly, then it is suggested 2670 that the length of the random value be the same length as the hash 2671 function underlying HKDF. While there is no way to guarantee that it 2672 will be unique, there is a high probability that it will be unique. 2673 If the salt/nonce value is generated deterministically, it can be 2674 guaranteed to be unique and thus there is no length requirement. 2676 A new IV must be used for each message if the same key is used. The 2677 IV can be modified in a predictable manner, a random manner or an 2678 unpredictable manner (i.e., encrypting a counter). 2680 The IV used for a key can also be generated from the same HKDF 2681 functionality as the key is generated. If HKDF is used for 2682 generating the IV, the algorithm identifier is set to "IV- 2683 GENERATION". 2685 When these algorithms are used, the key type MUST be 'symmetric'. 2687 The set of algorithms defined in this document can be found in 2688 Table 16. 2690 +---------------------+-------+-------------+-----------------------+ 2691 | name | value | KDF | description | 2692 +---------------------+-------+-------------+-----------------------+ 2693 | direct+HKDF-SHA-256 | -10 | HKDF | Shared secret w/ HKDF | 2694 | | | SHA-256 | and SHA-256 | 2695 | | | | | 2696 | direct+HKDF-SHA-512 | -11 | HKDF | Shared secret w/ HKDF | 2697 | | | SHA-512 | and SHA-512 | 2698 | | | | | 2699 | direct+HKDF-AES-128 | -12 | HKDF AES- | Shared secret w/ AES- | 2700 | | | MAC-128 | MAC 128-bit key | 2701 | | | | | 2702 | direct+HKDF-AES-256 | -13 | HKDF AES- | Shared secret w/ AES- | 2703 | | | MAC-256 | MAC 256-bit key | 2704 +---------------------+-------+-------------+-----------------------+ 2706 Table 16: Direct Key with KDF 2708 When using a COSE key for this algorithm, the following checks are 2709 made: 2711 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2713 o If the 'alg' field is present, it MUST match the algorithm being 2714 used. 2716 o If the 'key_ops' field is present, it MUST include 'deriveKey' or 2717 'deriveBits'. 2719 12.1.2.1. Security Considerations 2721 The shared secret needs to have some method to be regularly updated 2722 over time. The shared secret forms the basis of trust. Although not 2723 used directly, it should still be subject to scheduled rotation. 2725 While these methods do not provide for perfect forward secrecy, as 2726 the same shared secret is used for all of the keys generated, if the 2727 key for any single message is discovered only the message (or series 2728 of messages) using that derived key are compromised. A new key 2729 derivation step will generate a new key which requires the same 2730 amount of work to get the key. 2732 12.2. Key Wrapping 2734 In key wrapping mode, the CEK is randomly generated and that key is 2735 then encrypted by a shared secret between the sender and the 2736 recipient. All of the currently defined key wrapping algorithms for 2737 COSE are AE algorithms. Key wrapping mode is considered to be 2738 superior to direct encryption if the system has any capability for 2739 doing random key generation. This is because the shared key is used 2740 to wrap random data rather than data that has some degree of 2741 organization and may in fact be repeating the same content. The use 2742 of Key Wrapping loses the weak data origination that is provided by 2743 the direct encryption algorithms. 2745 The COSE_Encrypt structure for the recipient is organized as follows: 2747 o The 'protected' field MUST be absent if the key wrap algorithm is 2748 an AE algorithm. 2750 o The 'recipients' field is normally absent, but can be used. 2751 Applications MUST deal with a recipient field being present, not 2752 being able to decrypt that recipient is an acceptable way of 2753 dealing with it. Failing to process the message is not an 2754 acceptable way of dealing with it. 2756 o The plain text to be encrypted is the key from next layer down 2757 (usually the content layer). 2759 o At a minimum, the 'unprotected' field MUST contain the 'alg' 2760 parameter and SHOULD contain a parameter identifying the shared 2761 secret. 2763 12.2.1. AES Key Wrapping 2765 The AES Key Wrapping algorithm is defined in [RFC3394]. This 2766 algorithm uses an AES key to wrap a value that is a multiple of 64 2767 bits. As such, it can be used to wrap a key for any of the content 2768 encryption algorithms defined in this document. The algorithm 2769 requires a single fixed parameter, the initial value. This is fixed 2770 to the value specified in Section 2.2.3.1 of [RFC3394]. There are no 2771 public parameters that vary on a per invocation basis. The protected 2772 header field MUST be empty. 2774 Keys may be obtained either from a key structure or from a recipient 2775 structure. Implementations encrypting and decrypting MUST validate 2776 that the key type, key length and algorithm are correct and 2777 appropriate for the entities involved. 2779 When using a COSE key for this algorithm, the following checks are 2780 made: 2782 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2784 o If the 'alg' field is present, it MUST match the AES Key Wrap 2785 algorithm being used. 2787 o If the 'key_ops' field is present, it MUST include 'encrypt' or 2788 'wrap key' when encrypting. 2790 o If the 'key_ops' field is present, it MUST include 'decrypt' or 2791 'unwrap key' when decrypting. 2793 +--------+-------+----------+-----------------------------+ 2794 | name | value | key size | description | 2795 +--------+-------+----------+-----------------------------+ 2796 | A128KW | -3 | 128 | AES Key Wrap w/ 128-bit key | 2797 | | | | | 2798 | A192KW | -4 | 192 | AES Key Wrap w/ 192-bit key | 2799 | | | | | 2800 | A256KW | -5 | 256 | AES Key Wrap w/ 256-bit key | 2801 +--------+-------+----------+-----------------------------+ 2803 Table 17: AES Key Wrap Algorithm Values 2805 12.2.1.1. Security Considerations for AES-KW 2807 The shared secret needs to have some method to be regularly updated 2808 over time. The shared secret is the basis of trust. 2810 12.3. Key Transport 2812 Key transport mode is also called key encryption mode in some 2813 standards. Key transport mode differs from key wrap mode in that it 2814 uses an asymmetric encryption algorithm rather than a symmetric 2815 encryption algorithm to protect the key. This document does not 2816 define any key transport mode algorithms. 2818 When using a key transport algorithm, the COSE_Encrypt structure for 2819 the recipient is organized as follows: 2821 o The 'protected' field MUST be absent. 2823 o The plain text to be encrypted is the key from next layer down 2824 (usually the content layer). 2826 o At a minimum, the 'unprotected' field MUST contain the 'alg' 2827 parameter and SHOULD contain a parameter identifying the 2828 asymmetric key. 2830 12.4. Direct Key Agreement 2832 The 'direct key agreement' class of recipient algorithms uses a key 2833 agreement method to create a shared secret. A KDF is then applied to 2834 the shared secret to derive a key to be used in protecting the data. 2836 This key is normally used as a CEK or MAC key, but could be used for 2837 other purposes if more than two layers are in use (see Appendix B). 2839 The most commonly used key agreement algorithm is Diffie-Hellman, but 2840 other variants exist. Since COSE is designed for a store and forward 2841 environment rather than an on-line environment, many of the DH 2842 variants cannot be used as the receiver of the message cannot provide 2843 any dynamic key material. One side-effect of this is that perfect 2844 forward secrecy (see [RFC4949]) is not achievable. A static key will 2845 always be used for the receiver of the COSE object. 2847 Two variants of DH that are supported are: 2849 Ephemeral-Static DH: where the sender of the message creates a 2850 one-time DH key and uses a static key for the recipient. The use 2851 of the ephemeral sender key means that no additional random input 2852 is needed as this is randomly generated for each message. 2854 Static-Static DH: where a static key is used for both the sender 2855 and the recipient. The use of static keys allows for recipient to 2856 get a weak version of data origination for the message. When 2857 static-static key agreement is used, then some piece of unique 2858 data for the KDF is required to ensure that a different key is 2859 created for each message. 2861 When direct key agreement mode is used, there MUST be only one 2862 recipient in the message. This method creates the key directly and 2863 that makes it difficult to mix with additional recipients. If 2864 multiple recipients are needed, then the version with key wrap needs 2865 to be used. 2867 The COSE_Encrypt structure for the recipient is organized as follows: 2869 o At a minimum, headers MUST contain the 'alg' parameter and SHOULD 2870 contain a parameter identifying the recipient's asymmetric key. 2872 o The headers SHOULD identify the sender's key for the static-static 2873 versions and MUST contain the sender's ephemeral key for the 2874 ephemeral-static versions. 2876 12.4.1. ECDH 2878 The mathematics for Elliptic Curve Diffie-Hellman can be found in 2879 [RFC6090]. In this document, the algorithm is extended to be used 2880 with the two curves defined in [RFC7748]. 2882 ECDH is parameterized by the following: 2884 o Curve Type/Curve: The curve selected controls not only the size of 2885 the shared secret, but the mathematics for computing the shared 2886 secret. The curve selected also controls how a point in the curve 2887 is represented and what happens for the identity points on the 2888 curve. In this specification, we allow for a number of different 2889 curves to be used. A set of curves are defined in Table 22. 2890 The math used to obtain the computed secret is based on the curve 2891 selected and not on the ECDH algorithm. For this reason, a new 2892 algorithm does not need to be defined for each of the curves. 2894 o Computed Secret to Shared Secret: Once the computed secret is 2895 known, the resulting value needs to be converted to a byte string 2896 to run the KDF function. The X coordinate is used for all of the 2897 curves defined in this document. For curves X25519 and X448, the 2898 resulting value is used directly as it is a byte string of a known 2899 length. For the P-256, P-384 and P-521 curves, the X coordinate 2900 is run through the I2OSP function defined in [RFC3447], using the 2901 same computation for n as is defined in Section 8.1. 2903 o Ephemeral-static or static-static: The key agreement process may 2904 be done using either a static or an ephemeral key for the sender's 2905 side. When using ephemeral keys, the sender MUST generate a new 2906 ephemeral key for every key agreement operation. The ephemeral 2907 key is placed in the 'ephemeral key' parameter and MUST be present 2908 for all algorithm identifiers that use ephemeral keys. When using 2909 static keys, the sender MUST either generate a new random value or 2910 otherwise create a unique value. For the KDF functions used, this 2911 means either in the 'salt' parameter for HKDF (Table 13) or in the 2912 'PartyU nonce' parameter for the context structure (Table 14) MUST 2913 be present. (Both may be present if desired.) The value in the 2914 parameter MUST be unique for the pair of keys being used. It is 2915 acceptable to use a global counter that is incremented for every 2916 static-static operation and use the resulting value. When using 2917 static keys, the static key should be identified to the recipient. 2918 The static key can be identified either by providing the key 2919 ('static key') or by providing a key identifier for the static key 2920 ('static key id'). Both of these parameters are defined in 2921 Table 19. 2923 o Key derivation algorithm: The result of an ECDH key agreement 2924 process does not provide a uniformly random secret. As such, it 2925 needs to be run through a KDF in order to produce a usable key. 2926 Processing the secret through a KDF also allows for the 2927 introduction of context material: how the key is going to be used, 2928 and one-time material for static-static key agreement. All of the 2929 algorithms defined in this document use one of the HKDF algorithms 2930 defined in Section 11.1 with the context structure defined in 2931 Section 11.2. 2933 o Key Wrap algorithm: No key wrap algorithm is used. This is 2934 represented in Table 18 as 'none'. The key size for the context 2935 structure is the content layer encryption algorithm size. 2937 The set of direct ECDH algorithms defined in this document are found 2938 in Table 18. 2940 +-----------+-------+---------+------------+--------+---------------+ 2941 | name | value | KDF | Ephemeral- | Key | description | 2942 | | | | Static | Wrap | | 2943 +-----------+-------+---------+------------+--------+---------------+ 2944 | ECDH-ES + | -25 | HKDF - | yes | none | ECDH ES w/ | 2945 | HKDF-256 | | SHA-256 | | | HKDF - | 2946 | | | | | | generate key | 2947 | | | | | | directly | 2948 | | | | | | | 2949 | ECDH-ES + | -26 | HKDF - | yes | none | ECDH ES w/ | 2950 | HKDF-512 | | SHA-512 | | | HKDF - | 2951 | | | | | | generate key | 2952 | | | | | | directly | 2953 | | | | | | | 2954 | ECDH-SS + | -27 | HKDF - | no | none | ECDH SS w/ | 2955 | HKDF-256 | | SHA-256 | | | HKDF - | 2956 | | | | | | generate key | 2957 | | | | | | directly | 2958 | | | | | | | 2959 | ECDH-SS + | -28 | HKDF - | no | none | ECDH SS w/ | 2960 | HKDF-512 | | SHA-512 | | | HKDF - | 2961 | | | | | | generate key | 2962 | | | | | | directly | 2963 +-----------+-------+---------+------------+--------+---------------+ 2965 Table 18: ECDH Algorithm Values 2967 +-----------+-------+----------+-----------+------------------------+ 2968 | name | label | type | algorithm | description | 2969 +-----------+-------+----------+-----------+------------------------+ 2970 | ephemeral | -1 | COSE_Key | ECDH-ES | Ephemeral Public key | 2971 | key | | | | for the sender | 2972 | | | | | | 2973 | static | -2 | COSE_Key | ECDH-SS | Static Public key for | 2974 | key | | | | the sender | 2975 | | | | | | 2976 | static | -3 | bstr | ECDH-SS | Static Public key | 2977 | key id | | | | identifier for the | 2978 | | | | | sender | 2979 +-----------+-------+----------+-----------+------------------------+ 2981 Table 19: ECDH Algorithm Parameters 2983 This document defines these algorithms to be used with the curves 2984 P-256, P-384, P-521, X25519, and X448. Implementations MUST verify 2985 that the key type and curve are correct. Different curves are 2986 restricted to different key types. Implementations MUST verify that 2987 the curve and algorithm are appropriate for the entities involved. 2989 When using a COSE key for this algorithm, the following checks are 2990 made: 2992 o The 'kty' field MUST be present and it MUST be 'EC2' or 'OKP'. 2994 o If the 'alg' field is present, it MUST match the Key Agreement 2995 algorithm being used. 2997 o If the 'key_ops' field is present, it MUST include 'derive key' or 2998 'derive bits' for the private key. 3000 o If the 'key_ops' field is present, it MUST be empty for the public 3001 key. 3003 12.4.2. Security Considerations 3005 Some method of checking that points provided from external entities 3006 are valid. For the 'EC2' key format, this can be done by checking 3007 that the x and y values form a point on the curve. For the 'OKP' 3008 format, there is no simple way to do point validation. 3010 Consideration was given to requiring that the public keys of both 3011 entities be provided as part of the key derivation process. (As 3012 recommended in section 6.1 of [RFC7748].) This was not done as COSE 3013 is used in a store and forward format rather than in on line key 3014 exchange. In order for this to be a problem, either the receiver 3015 public key has to be chosen maliciously or the sender has to be 3016 malicious. In either case, all security evaporates anyway. 3018 A proof of possession of the private key associated with the public 3019 key is recommended when a key is moved from untrusted to trusted. 3020 (Either by the end user or by the entity that is responsible for 3021 making trust statements on keys.) 3023 12.5. Key Agreement with Key Wrap 3025 Key Agreement with Key Wrapping uses a randomly generated CEK. The 3026 CEK is then encrypted using a Key Wrapping algorithm and a key 3027 derived from the shared secret computed by the key agreement 3028 algorithm. 3030 The COSE_Encrypt structure for the recipient is organized as follows: 3032 o The 'protected' field is fed into the KDF context structure. 3034 o The plain text to be encrypted is the key from next layer down 3035 (usually the content layer). 3037 o The 'alg' parameter MUST be present in the layer. 3039 o A parameter identifying the recipient's key SHOULD be present. A 3040 parameter identifying the sender's key SHOULD be present. 3042 12.5.1. ECDH 3044 These algorithms are defined in Table 20. 3046 ECDH with Key Agreement is parameterized by the same parameters as 3047 for ECDH Section 12.4.1 with the following modifications: 3049 o Key Wrap Algorithm: Any of the key wrap algorithms defined in 3050 Section 12.2.1 are supported. The size of the key used for the 3051 key wrap algorithm is fed into the KDF function. The set of 3052 identifiers are found in Table 20. 3054 +-----------+-------+---------+------------+--------+---------------+ 3055 | name | value | KDF | Ephemeral- | Key | description | 3056 | | | | Static | Wrap | | 3057 +-----------+-------+---------+------------+--------+---------------+ 3058 | ECDH-ES + | -29 | HKDF - | yes | A128KW | ECDH ES w/ | 3059 | A128KW | | SHA-256 | | | Concat KDF | 3060 | | | | | | and AES Key | 3061 | | | | | | wrap w/ 128 | 3062 | | | | | | bit key | 3063 | | | | | | | 3064 | ECDH-ES + | -30 | HKDF - | yes | A192KW | ECDH ES w/ | 3065 | A192KW | | SHA-256 | | | Concat KDF | 3066 | | | | | | and AES Key | 3067 | | | | | | wrap w/ 192 | 3068 | | | | | | bit key | 3069 | | | | | | | 3070 | ECDH-ES + | -31 | HKDF - | yes | A256KW | ECDH ES w/ | 3071 | A256KW | | SHA-256 | | | Concat KDF | 3072 | | | | | | and AES Key | 3073 | | | | | | wrap w/ 256 | 3074 | | | | | | bit key | 3075 | | | | | | | 3076 | ECDH-SS + | -32 | HKDF - | no | A128KW | ECDH SS w/ | 3077 | A128KW | | SHA-256 | | | Concat KDF | 3078 | | | | | | and AES Key | 3079 | | | | | | wrap w/ 128 | 3080 | | | | | | bit key | 3081 | | | | | | | 3082 | ECDH-SS + | -33 | HKDF - | no | A192KW | ECDH SS w/ | 3083 | A192KW | | SHA-256 | | | Concat KDF | 3084 | | | | | | and AES Key | 3085 | | | | | | wrap w/ 192 | 3086 | | | | | | bit key | 3087 | | | | | | | 3088 | ECDH-SS + | -34 | HKDF - | no | A256KW | ECDH SS w/ | 3089 | A256KW | | SHA-256 | | | Concat KDF | 3090 | | | | | | and AES Key | 3091 | | | | | | wrap w/ 256 | 3092 | | | | | | bit key | 3093 +-----------+-------+---------+------------+--------+---------------+ 3095 Table 20: ECDH Algorithm Values with Key Wrap 3097 When using a COSE key for this algorithm, the following checks are 3098 made: 3100 o The 'kty' field MUST be present and it MUST be 'EC2' or 'OKP'. 3102 o If the 'alg' field is present, it MUST match the Key Agreement 3103 algorithm being used. 3105 o If the 'key_ops' field is present, it MUST include 'derive key' or 3106 'derive bits' for the private key. 3108 o If the 'key_ops' field is present, it MUST be empty for the public 3109 key. 3111 13. Key Object Parameters 3113 The COSE_Key object defines a way to hold a single key object. It is 3114 still required that the members of individual key types be defined. 3115 This section of the document is where we define an initial set of 3116 members for specific key types. 3118 For each of the key types, we define both public and private members. 3119 The public members are what is transmitted to others for their usage. 3120 Private members allow for the archival of keys by individuals. 3121 However, there are some circumstances in which private keys may be 3122 distributed to entities in a protocol. Examples include: entities 3123 that have poor random number generation, centralized key creation for 3124 multi-cast type operations, and protocols in which a shared secret is 3125 used as a bearer token for authorization purposes. 3127 Key types are identified by the 'kty' member of the COSE_Key object. 3128 In this document, we define four values for the member: 3130 +-----------+-------+--------------------------------------------+ 3131 | name | value | description | 3132 +-----------+-------+--------------------------------------------+ 3133 | OKP | 1 | Octet Key Pair | 3134 | | | | 3135 | EC2 | 2 | Elliptic Curve Keys w/ X,Y Coordinate pair | 3136 | | | | 3137 | Symmetric | 4 | Symmetric Keys | 3138 | | | | 3139 | Reserved | 0 | This value is reserved | 3140 +-----------+-------+--------------------------------------------+ 3142 Table 21: Key Type Values 3144 13.1. Elliptic Curve Keys 3146 Two different key structures could be defined for Elliptic Curve 3147 keys. One version uses both an x and a y coordinate, potentially 3148 with point compression ('EC2'). This is the traditional EC point 3149 representation that is used in [RFC5480]. The other version uses 3150 only the x coordinate as the y coordinate is either to be recomputed 3151 or not needed for the key agreement operation ('OKP'). 3153 Applications MUST check that the curve and the key type are 3154 consistent and reject a key if they are not. 3156 +---------+----------+-------+------------------------------------+ 3157 | name | key type | value | description | 3158 +---------+----------+-------+------------------------------------+ 3159 | P-256 | EC2 | 1 | NIST P-256 also known as secp256r1 | 3160 | | | | | 3161 | P-384 | EC2 | 2 | NIST P-384 also known as secp384r1 | 3162 | | | | | 3163 | P-521 | EC2 | 3 | NIST P-521 also known as secp521r1 | 3164 | | | | | 3165 | X25519 | OKP | 4 | X25519 for use w/ ECDH only | 3166 | | | | | 3167 | X448 | OKP | 5 | X448 for use w/ ECDH only | 3168 | | | | | 3169 | Ed25519 | OKP | 6 | Ed25519 for use w/ EdDSA only | 3170 | | | | | 3171 | Ed448 | OKP | 7 | Ed448 for use w/ EdDSA only | 3172 +---------+----------+-------+------------------------------------+ 3174 Table 22: EC Curves 3176 13.1.1. Double Coordinate Curves 3178 The traditional way of sending EC curves has been to send either both 3179 the x and y coordinates, or the x coordinate and a sign bit for the y 3180 coordinate. The latter encoding has not been recommended in the IETF 3181 due to potential IPR issues. However, for operations in constrained 3182 environments, the ability to shrink a message by not sending the y 3183 coordinate is potentially useful. 3185 For EC keys with both coordinates, the 'kty' member is set to 2 3186 (EC2). The key parameters defined in this section are summarized in 3187 Table 23. The members that are defined for this key type are: 3189 crv contains an identifier of the curve to be used with the key. 3190 The curves defined in this document for this key type can be found 3191 in Table 22. Other curves may be registered in the future and 3192 private curves can be used as well. 3194 x contains the x coordinate for the EC point. The integer is 3195 converted to an octet string as defined in [SEC1]. Leading zero 3196 octets MUST be preserved. 3198 y contains either the sign bit or the value of y coordinate for the 3199 EC point. When encoding the value y, the integer is converted to 3200 an octet string (as defined in [SEC1]) and encoded as a CBOR bstr. 3201 Leading zero octets MUST be preserved. The compressed point 3202 encoding is also supported. Compute the sign bit as laid out in 3203 the Elliptic-Curve-Point-to-Octet-String Conversion function of 3204 [SEC1]. If the sign bit is zero, then encode y as a CBOR false 3205 value, otherwise encode y as a CBOR true value. The encoding of 3206 the infinity point is not supported. 3208 d contains the private key. 3210 For public keys, it is REQUIRED that 'crv', 'x' and 'y' be present in 3211 the structure. For private keys, it is REQUIRED that 'crv' and 'd' 3212 be present in the structure. For private keys, it is RECOMMENDED 3213 that 'x' and 'y' also be present, but they can be recomputed from the 3214 required elements and omitting them saves on space. 3216 +------+-------+-------+---------+----------------------------------+ 3217 | name | key | value | type | description | 3218 | | type | | | | 3219 +------+-------+-------+---------+----------------------------------+ 3220 | crv | 2 | -1 | int / | EC Curve identifier - Taken from | 3221 | | | | tstr | the COSE Curves registry | 3222 | | | | | | 3223 | x | 2 | -2 | bstr | X Coordinate | 3224 | | | | | | 3225 | y | 2 | -3 | bstr / | Y Coordinate | 3226 | | | | bool | | 3227 | | | | | | 3228 | d | 2 | -4 | bstr | Private key | 3229 +------+-------+-------+---------+----------------------------------+ 3231 Table 23: EC Key Parameters 3233 13.2. Octet Key Pair 3235 A new key type is defined for Octet Key Pairs (OKP). Do not assume 3236 that keys using this type are elliptic curves. This key type could 3237 be used for other curve types (for example, mathematics based on 3238 hyper-elliptic surfaces). 3240 The key parameters defined in this section are summarized in 3241 Table 24. The members that are defined for this key type are: 3243 crv contains an identifier of the curve to be used with the key. 3244 The curves defined in this document for this key type can be found 3245 in Table 22. Other curves may be registered in the future and 3246 private curves can be used as well. 3248 x contains the x coordinate for the EC point. The octet string 3249 represents a little-endian encoding of x. 3251 d contains the private key. 3253 For public keys, it is REQUIRED that 'crv' and 'x' be present in the 3254 structure. For private keys, it is REQUIRED that 'crv' and 'd' be 3255 present in the structure. For private keys, it is RECOMMENDED that 3256 'x' also be present, but it can be recomputed from the required 3257 elements and omitting it saves on space. 3259 +------+------+-------+-------+-------------------------------------+ 3260 | name | key | value | type | description | 3261 | | type | | | | 3262 +------+------+-------+-------+-------------------------------------+ 3263 | crv | 1 | -1 | int / | EC Curve identifier - Taken from | 3264 | | | | tstr | the COSE Key Common Parameters | 3265 | | | | | registry | 3266 | | | | | | 3267 | x | 1 | -2 | bstr | X Coordinate | 3268 | | | | | | 3269 | d | 1 | -4 | bstr | Private key | 3270 +------+------+-------+-------+-------------------------------------+ 3272 Table 24: Octet Key Pair Parameters 3274 13.3. Symmetric Keys 3276 Occasionally it is required that a symmetric key be transported 3277 between entities. This key structure allows for that to happen. 3279 For symmetric keys, the 'kty' member is set to 3 (Symmetric). The 3280 member that is defined for this key type is: 3282 k contains the value of the key. 3284 This key structure does not have a form that contains only public 3285 members. As it is expected that this key structure is going to be 3286 transmitted, care must be taking that it is never transmitted 3287 accidentally or insecurely. For symmetric keys, it is REQUIRED that 3288 'k' be present in the structure. 3290 +------+----------+-------+------+-------------+ 3291 | name | key type | value | type | description | 3292 +------+----------+-------+------+-------------+ 3293 | k | 4 | -1 | bstr | Key Value | 3294 +------+----------+-------+------+-------------+ 3296 Table 25: Symmetric Key Parameters 3298 14. CBOR Encoder Restrictions 3300 There has been an attempt to limit the number of places where the 3301 document needs to impose restrictions on how the CBOR Encoder needs 3302 to work. We have managed to narrow it down to the following 3303 restrictions: 3305 o The restriction applies to the encoding the Sig_structure, the 3306 Enc_structure, and the MAC_structure. 3308 o The rules for Canonical CBOR (Section 3.9 of RFC 7049) MUST be 3309 used in these locations. The main rule that needs to be enforced 3310 is that all lengths in these structures MUST be encoded such that 3311 they are encoded using definite lengths and the minimum length 3312 encoding is used. 3314 o Applications MUST NOT generate messages with the same label used 3315 twice as a key in a single map. Applications MUST NOT parse and 3316 process messages with the same label used twice as a key in a 3317 single map. Applications can enforce the parse and process 3318 requirement by using parsers that will fail the parse step or by 3319 using parsers that will pass all keys to the application and the 3320 application can perform the check for duplicate keys. 3322 15. Application Profiling Considerations 3324 This document is designed to provide a set of security services, but 3325 not to provide implementation requirements for specific usage. The 3326 interoperability requirements are provided for how each of the 3327 individual services are used and how the algorithms are to be used 3328 for interoperability. The requirements about which algorithms and 3329 which services are needed are deferred to each application. 3331 It is intended that a profile of this document be created that 3332 defines the interoperability requirements for that specific 3333 application. This section provides a set of guidelines and topics 3334 that need to be considered when profiling this document. 3336 o Applications need to determine the set of messages defined in this 3337 document that they will be using. The set of messages corresponds 3338 fairly directly to the set of security services that are needed 3339 and to the security levels needed. 3341 o Applications may define new header parameters for a specific 3342 purpose. Applications will often times select specific header 3343 parameters to use or not to use. For example, an application 3344 would normally state a preference for using either the IV or the 3345 partial IV parameter. If the partial IV parameter is specified, 3346 then the application would also need to define how the fixed 3347 portion of the IV would be determined. 3349 o When applications use externally defined authenticated data, they 3350 need to define how that data is encoded. This document assumes 3351 that the data will be provided as a byte stream. More information 3352 can be found in Section 4.3. 3354 o Applications need to determine the set of security algorithms that 3355 are to be used. When selecting the algorithms to be used as the 3356 mandatory to implement set, consideration should be given to 3357 choosing different types of algorithms when two are chosen for a 3358 specific purpose. An example of this would be choosing HMAC- 3359 SHA512 and AES-CMAC as different MAC algorithms; the construction 3360 is vastly different between these two algorithms. This means that 3361 a weakening of one algorithm would be unlikely to lead to a 3362 weakening of the other algorithms. Of course, these algorithms do 3363 not provide the same level of security and thus may not be 3364 comparable for the desired security functionality. 3366 o Applications may need to provide some type of negotiation or 3367 discovery method if multiple algorithms or message structures are 3368 permitted. The method can be as simple as requiring 3369 preconfiguration of the set of algorithms to providing a discovery 3370 method built into the protocol. S/MIME provided a number of 3371 different ways to approach the problem that applications could 3372 follow: 3374 * Advertising in the message (S/MIME capabilities) [RFC5751]. 3376 * Advertising in the certificate (capabilities extension) 3377 [RFC4262]. 3379 * Minimum requirements for the S/MIME, which have been updated 3380 over time [RFC2633][RFC5751]. 3382 16. IANA Considerations 3384 16.1. CBOR Tag assignment 3386 It is requested that IANA assign the following tags from the "CBOR 3387 Tags" registry. It is requested that the tags for COSE_Sign1, 3388 COSE_Encrypt0, and COSE_Mac0 be assigned in the 1 to 23 value range 3389 (one byte long when encoded). It is requested that the tags for 3390 COSE_Sign, COSE_Encrypt and COSE_MAC be assigned in the 24 to 255 3391 value range (two bytes long when encoded). 3393 The tags to be assigned are in Table 1. 3395 16.2. COSE Header Parameters Registry 3397 It is requested that IANA create a new registry entitled "COSE Header 3398 Parameters". The registry should be created as Expert Review 3399 Required. Guidelines for the experts is provided Section 16.11. It 3400 should be noted that in additional to the expert review, some 3401 portions of the registry require a specification, potentially on 3402 standards track, be supplied as well. 3404 The columns of the registry are: 3406 name The name is present to make it easier to refer to and discuss 3407 the registration entry. The value is not used in the protocol. 3408 Names are to be unique in the table. 3410 label This is the value used for the label. The label can be either 3411 an integer or a string. Registration in the table is based on the 3412 value of the label requested. Integer values between 1 and 255 3413 and strings of length 1 are designated as Standards Track Document 3414 required. Integer values from 256 to 65535 and strings of length 3415 2 are designated as Specification Required. Integer values of 3416 greater than 65535 and strings of length greater than 2 are 3417 designated as expert review. Integer values in the range -1 to 3418 -65536 are delegated to the "COSE Header Algorithm Parameters" 3419 registry. Integer values less than -65536 are marked as private 3420 use. 3422 value This contains the CBOR type for the value portion of the 3423 label. 3425 value registry This contains a pointer to the registry used to 3426 contain values where the set is limited. 3428 description This contains a brief description of the header field. 3430 specification This contains a pointer to the specification defining 3431 the header field (where public). 3433 The initial contents of the registry can be found in Table 2 and 3434 Table 27. The specification column for all rows in that table should 3435 be this document. 3437 Additionally, the label of 0 is to be marked as 'Reserved'. 3439 16.3. COSE Header Algorithm Parameters Registry 3441 It is requested that IANA create a new registry entitled "COSE Header 3442 Algorithm Parameters". The registry is to be created as Expert 3443 Review Required. Expert review guidelines are provided in 3444 Section 16.11. 3446 The columns of the registry are: 3448 name The name is present to make it easier to refer to and discuss 3449 the registration entry. The value is not used in the protocol. 3451 algorithm The algorithm(s) that this registry entry is used for. 3452 This value is taken from the "COSE Algorithm Values" registry. 3453 Multiple algorithms can be specified in this entry. For the 3454 table, the algorithm, label pair MUST be unique. 3456 label This is the value used for the label. The label is an integer 3457 in the range of -1 to -65536. 3459 value This contains the CBOR type for the value portion of the 3460 label. 3462 value registry This contains a pointer to the registry used to 3463 contain values where the set is limited. 3465 description This contains a brief description of the header field. 3467 specification This contains a pointer to the specification defining 3468 the header field (where public). 3470 The initial contents of the registry can be found in Table 13, 3471 Table 14, and Table 19. The specification column for all rows in 3472 that table should be this document. 3474 16.4. COSE Algorithms Registry 3476 It is requested that IANA create a new registry entitled "COSE 3477 Algorithms Registry". The registry is to be created as Expert Review 3478 Required. Guidelines for the experts is provided Section 16.11. It 3479 should be noted that in additional to the expert review, some 3480 portions of the registry require a specification, potentially on 3481 standards track, be supplied as well. 3483 The columns of the registry are: 3485 value The value to be used to identify this algorithm. Algorithm 3486 values MUST be unique. The value can be a positive integer, a 3487 negative integer or a string. Integer values between -256 and 255 3488 and strings of length 1 are designated as Standards Track Document 3489 required. Integer values from -65536 to 65535 and strings of 3490 length 2 are designated as Specification Required. Integer values 3491 of greater than 65535 and strings of length greater than 2 are 3492 designated as expert review. Integer values less than -65536 are 3493 marked as private use. 3495 description A short description of the algorithm. 3497 specification A document where the algorithm is defined (if publicly 3498 available). 3500 The initial contents of the registry can be found in Table 10, 3501 Table 9, Table 11, Table 5, Table 7, Table 8, Table 15, Table 16, 3502 Table 17, Table 6, Table 20 and Table 18. The specification column 3503 for all rows in that table should be this document. 3505 NOTE: The assignment of algorithm identifiers in this document was 3506 done so that positive numbers were used for the first layer objects 3507 (COSE_Sign, COSE_Sign1, COSE_Encrypt, COSE_Encrypt0, COSE_Mac, and 3508 COSE_Mac0). Negative numbers were used for second layer objects 3509 (COSE_Signature and COSE_recipient). Expert reviewers should 3510 consider this practice, but are not expected to be restricted by this 3511 precedent. 3513 16.5. COSE Key Common Parameters Registry 3515 It is requested that IANA create a new registry entitled "COSE Key 3516 Common Parameters" registry. The registry is to be created as Expert 3517 Review Required. Guidelines for the experts is provided 3518 Section 16.11. It should be noted that in additional to the expert 3519 review, some portions of the registry require a specification, 3520 potentially on standards track, be supplied as well. 3522 The columns of the registry are: 3524 name This is a descriptive name that enables easier reference to the 3525 item. It is not used in the encoding. 3527 label The value to be used to identify this algorithm. Key map 3528 labels MUST be unique. The label can be a positive integer, a 3529 negative integer or a string. Integer values between 0 and 255 3530 and strings of length 1 are designated as Standards Track Document 3531 required. Integer values from 256 to 65535 and strings of length 3532 2 are designated as Specification Required. Integer values of 3533 greater than 65535 and strings of length greater than 2 are 3534 designated as expert review. Integer values in the range -1 to 3535 -65536 are used for key parameters specific to a single algorithm 3536 delegated to the "COSE Key Type Parameter Labels" registry. 3537 Integer values less than -65536 are marked as private use. 3539 CBOR Type This field contains the CBOR type for the field. 3541 registry This field denotes the registry that values come from, if 3542 one exists. 3544 description This field contains a brief description for the field. 3546 specification This contains a pointer to the public specification 3547 for the field if one exists 3549 This registry will be initially populated by the values in Table 3. 3550 The specification column for all of these entries will be this 3551 document. 3553 16.6. COSE Key Type Parameters Registry 3555 It is requested that IANA create a new registry "COSE Key Type 3556 Parameters". The registry is to be created as Expert Review 3557 Required. Expert review guidelines are provided in Section 16.11. 3559 The columns of the table are: 3561 key type This field contains a descriptive string of a key type. 3562 This should be a value that is in the COSE Key Common Parameters 3563 table and is placed in the 'kty' field of a COSE Key structure. 3565 name This is a descriptive name that enables easier reference to the 3566 item. It is not used in the encoding. 3568 label The label is to be unique for every value of key type. The 3569 range of values is from -256 to -1. Labels are expected to be 3570 reused for different keys. 3572 CBOR type This field contains the CBOR type for the field. 3574 description This field contains a brief description for the field. 3576 specification This contains a pointer to the public specification 3577 for the field if one exists. 3579 This registry will be initially populated by the values in Table 23, 3580 Table 24, and Table 25. The specification column for all of these 3581 entries will be this document. 3583 16.7. COSE Key Type Registry 3585 It is requested that IANA create a new registry "COSE Key Type 3586 Registry". The registry is to be created as Expert Review Required. 3587 Expert review guidelines are provided in Section 16.11. 3589 The columns of this table are: 3591 name This is a descriptive name that enables easier reference to the 3592 item. The name MUST be unique. It is not used in the encoding. 3594 value This is the value used to identify the curve. These values 3595 MUST be unique. The value can be a positive integer, a negative 3596 integer or a string. 3598 description This field contains a brief description of the curve. 3600 specification This contains a pointer to the public specification 3601 for the curve if one exists. 3603 This registry will be initially populated by the values in Table 21. 3604 The specification column for all of these entries will be this 3605 document. 3607 16.8. COSE Elliptic Curve Parameters Registry 3609 It is requested that IANA create a new registry "COSE Elliptic Curve 3610 Parameters". The registry is to be created as Expert Review 3611 Required. Guidelines for the experts is provided Section 16.11. It 3612 should be noted that in additional to the expert review, some 3613 portions of the registry require a specification, potentially on 3614 standards track, be supplied as well. 3616 The columns of the table are: 3618 name This is a descriptive name that enables easier reference to the 3619 item. It is not used in the encoding. 3621 value This is the value used to identify the curve. These values 3622 MUST be unique. The integer values from -256 to 255 are 3623 designated as Standards Track Document Required. The integer 3624 values from 256 to 65535 and -65536 to -257 are designated as 3625 Specification Required. Integer values over 65535 are designated 3626 as expert review. Integer values less than -65536 are marked as 3627 private use. 3629 key type This designates the key type(s) that can be used with this 3630 curve. 3632 description This field contains a brief description of the curve. 3634 specification This contains a pointer to the public specification 3635 for the curve if one exists. 3637 This registry will be initially populated by the values in Table 22. 3638 The specification column for all of these entries will be this 3639 document. 3641 16.9. Media Type Registrations 3643 16.9.1. COSE Security Message 3645 This section registers the "application/cose" media type in the 3646 "Media Types" registry. These media types are used to indicate that 3647 the content is a COSE message. 3649 Type name: application 3651 Subtype name: cose 3653 Required parameters: N/A 3655 Optional parameters: cose-type 3657 Encoding considerations: binary 3659 Security considerations: See the Security Considerations section 3660 of RFC TBD. 3662 Interoperability considerations: N/A 3663 Published specification: RFC TBD 3665 Applications that use this media type: To be identified 3667 Fragment identifier considerations: N/A 3669 Additional information: 3671 * Magic number(s): N/A 3673 * File extension(s): cbor 3675 * Macintosh file type code(s): N/A 3677 Person & email address to contact for further information: 3678 iesg@ietf.org 3680 Intended usage: COMMON 3682 Restrictions on usage: N/A 3684 Author: Jim Schaad, ietf@augustcellars.com 3686 Change Controller: IESG 3688 Provisional registration? No 3690 16.9.2. COSE Key media type 3692 This section registers the "application/cose-key" and "application/ 3693 cose-key-set" media types in the "Media Types" registry. These media 3694 types are used to indicate, respectively, that content is a COSE_Key 3695 or COSE_KeySet object. 3697 The template for registering "application/cose-key" is: 3699 Type name: application 3701 Subtype name: cose-key 3703 Required parameters: N/A 3705 Optional parameters: N/A 3707 Encoding considerations: binary 3709 Security considerations: See the Security Considerations section 3710 of RFC TBD. 3712 Interoperability considerations: N/A 3714 Published specification: RFC TBD 3716 Applications that use this media type: To be identified 3718 Fragment identifier considerations: N/A 3720 Additional information: 3722 * Magic number(s): N/A 3724 * File extension(s): cbor 3726 * Macintosh file type code(s): N/A 3728 Person & email address to contact for further information: 3729 iesg@ietf.org 3731 Intended usage: COMMON 3733 Restrictions on usage: N/A 3735 Author: Jim Schaad, ietf@augustcellars.com 3737 Change Controller: IESG 3739 Provisional registration? No 3741 The template for registering "application/cose-key-set" is: 3743 Type name: application 3745 Subtype name: cose-key-set 3747 Required parameters: N/A 3749 Optional parameters: N/A 3751 Encoding considerations: binary 3753 Security considerations: See the Security Considerations section 3754 of RFC TBD. 3756 Interoperability considerations: N/A 3758 Published specification: RFC TBD 3759 Applications that use this media type: To be identified 3761 Fragment identifier considerations: N/A 3763 Additional information: 3765 * Magic number(s): N/A 3767 * File extension(s): cbor 3769 * Macintosh file type code(s): N/A 3771 Person & email address to contact for further information: 3772 iesg@ietf.org 3774 Intended usage: COMMON 3776 Restrictions on usage: N/A 3778 Author: Jim Schaad, ietf@augustcellars.com 3780 Change Controller: IESG 3782 Provisional registration? No 3784 16.10. CoAP Content-Format Registrations 3786 IANA is requested to add the following entries to the "CoAP Content- 3787 Format" registry. ID assignment in the 24-255 range is requested. 3789 +---------------------------------+----------+-------+--------------+ 3790 | Media Type | Encoding | ID | Reference | 3791 +---------------------------------+----------+-------+--------------+ 3792 | application/cose; cose-type | | TBD10 | [This | 3793 | ="cose-sign" | | | Document] | 3794 | | | | | 3795 | application/cose; cose-type | | TBD11 | [This | 3796 | ="cose-sign1" | | | Document] | 3797 | | | | | 3798 | application/cose; cose-type | | TBD12 | [This | 3799 | ="cose-encrypt" | | | Document] | 3800 | | | | | 3801 | application/cose; cose-type | | TBD13 | [This | 3802 | ="cose-encrypt0" | | | Document] | 3803 | | | | | 3804 | application/cose; cose-type | | TBD14 | [This | 3805 | ="cose-mac" | | | Document] | 3806 | | | | | 3807 | application/cose; cose-type | | TBD15 | [This | 3808 | ="cose-mac0" | | | Document] | 3809 | | | | | 3810 | application/cose-key | | TBD16 | [This | 3811 | | | | Document] | 3812 | | | | | 3813 | application/cose-key-set | | TBD17 | [This | 3814 | | | | Document | 3815 +---------------------------------+----------+-------+--------------+ 3817 Table 26 3819 16.11. Expert Review Instructions 3821 All of the IANA registries established in this document are defined 3822 as expert review. This section gives some general guidelines for 3823 what the experts should be looking for, but they are being designated 3824 as experts for a reason so they should be given substantial latitude. 3826 Expert reviewers should take into consideration the following points: 3828 o Point squatting should be discouraged. Reviewers are encouraged 3829 to get sufficient information for registration requests to ensure 3830 that the usage is not going to duplicate one that is already 3831 registered and that the point is likely to be used in deployments. 3832 The zones tagged as private use are intended for testing purposes 3833 and closed environments, code points in other ranges should not be 3834 assigned for testing. 3836 o Specifications are required for the standards track range of point 3837 assignment. Specifications should exist for specification 3838 required ranges, but early assignment before a specification is 3839 available is considered to be permissible. Specifications are 3840 needed for the first-come, first-serve range if they are expected 3841 to be used outside of closed environments in an interoperable way. 3842 When specifications are not provided, the description provided 3843 needs to have sufficient information to identify what the point is 3844 being used for. 3846 o Experts should take into account the expected usage of fields when 3847 approving point assignment. The fact that there is a range for 3848 standards track documents does not mean that a standards track 3849 document cannot have points assigned outside of that range. The 3850 length of the encoded value should be weighed against how many 3851 code points of that length are left, the size of device it will be 3852 used on, and the number of code points left that encode to that 3853 size. 3855 o When algorithms are registered, vanity registrations should be 3856 discouraged. One way to do this is to require registrations to 3857 provide additional documentation on security analysis of the 3858 algorithm. Another thing that should be considered is to request 3859 for an opinion on the algorithm from the Crypto Forum Research 3860 Group (CFRG). Algorithms that do not meet the security 3861 requirements of the community and the messages structures should 3862 not be registered. 3864 17. Implementation Status 3866 This section records the status of known implementations of the 3867 protocol defined by this specification at the time of posting of this 3868 Internet-Draft, and is based on a proposal described in [RFC7942]. 3869 The description of implementations in this section is intended to 3870 assist the IETF in its decision processes in progressing drafts to 3871 RFCs. Please note that the listing of any individual implementation 3872 here does not imply endorsement by the IETF. Furthermore, no effort 3873 has been spent to verify the information presented here that was 3874 supplied by IETF contributors. This is not intended as, and must not 3875 be construed to be, a catalog of available implementations or their 3876 features. Readers are advised to note that other implementations may 3877 exist. 3879 According to [RFC7942], "this will allow reviewers and working groups 3880 to assign due consideration to documents that have the benefit of 3881 running code, which may serve as evidence of valuable experimentation 3882 and feedback that have made the implemented protocols more mature. 3884 It is up to the individual working groups to use this information as 3885 they see fit". 3887 17.1. Author's Versions 3889 There are three different implementations that have been created by 3890 the author of the document both to create the examples that are 3891 included in the document and to validate the structures and 3892 methodology used in the design of COSE. 3894 Implementation Location: https://github.com/cose-wg 3896 Primary Maintainer: Jim Schaad 3898 Languages: There are three different languages that are currently 3899 supported: Java, C# and C. 3901 Cryptography: The Java and C# libraries use Bouncy Castle to 3902 provide the required cryptography. The C version uses OPENSSL 3903 Version 1.0 for the cryptography. 3905 Coverage: The libraries currently do not have full support for 3906 counter signatures of either variety. They do have support to 3907 allow for implicit algorithm support as they allow for the 3908 application to set attributes that are not to be sent in the 3909 message. 3911 Testing: All of the examples in the example library are generated 3912 by the C# library and then validated using the Java and C 3913 libraries. All three libraries have tests to allow for the 3914 creating of the same messages that are in the example library 3915 followed by validating them. These are not compared against the 3916 example library. The Java and C# libraries have unit testing 3917 included. Not all of the MUST statements in the document have 3918 been implemented as part of the libraries. One such statement is 3919 the requirement that unique labels be present. 3921 Licensing: Revised BSD License 3923 17.2. COSE Testing Library 3925 Implementation Location: https://github.com/cose-wg/Examples 3927 Primary Maintainer: Jim Schaad 3929 Description: A set of tests for the COSE library is provided as 3930 part of the implementation effort. Both success and fail tests 3931 have been provided. All of the examples in this document are part 3932 of this example set. 3934 Coverage: An attempt has been made to have test cases for every 3935 message type and algorithm in the document. Currently examples 3936 dealing with counter signatures, EdDSA, and ECDH with Curve24459 3937 and Goldilocks are missing. 3939 Licensing: Public Domain 3941 18. Security Considerations 3943 There are a number of security considerations that need to be taken 3944 into account by implementers of this specification. The security 3945 considerations that are specific to an individual algorithm are 3946 placed next to the description of the algorithm. While some 3947 considerations have been highlighted here, additional considerations 3948 may be found in the documents listed in the references. 3950 Implementations need to protect the private key material for any 3951 individuals. There are some cases in this document that need to be 3952 highlighted on this issue. 3954 o Using the same key for two different algorithms can leak 3955 information about the key. It is therefore recommended that keys 3956 be restricted to a single algorithm. 3958 o Use of 'direct' as a recipient algorithm combined with a second 3959 recipient algorithm, exposes the direct key to the second 3960 recipient. 3962 o Several of the algorithms in this document have limits on the 3963 number of times that a key can be used without leaking information 3964 about the key. 3966 The use of ECDH and direct plus KDF (with no key wrap) will not 3967 directly lead to the private key being leaked; the one way function 3968 of the KDF will prevent that. There is however, a different issue 3969 that needs to be addressed. Having two recipients requires that the 3970 CEK be shared between two recipients. The second recipient therefore 3971 has a CEK that was derived from material that can be used for the 3972 weak proof of origin. The second recipient could create a message 3973 using the same CEK and send it to the first recipient, the first 3974 recipient would, for either static-static ECDH or direct plus KDF, 3975 make an assumption that the CEK could be used for proof of origin 3976 even though it is from the wrong entity. If the key wrap step is 3977 added, then no proof of origin is implied and this is not an issue. 3979 Although it has been mentioned before, the use of a single key for 3980 multiple algorithms has been demonstrated in some cases to leak 3981 information about a key, provide for attackers to forge integrity 3982 tags, or gain information about encrypted content. Binding a key to 3983 a single algorithm prevents these problems. Key creators and key 3984 consumers are strongly encouraged not only to create new keys for 3985 each different algorithm, but to include that selection of algorithm 3986 in any distribution of key material and strictly enforce the matching 3987 of algorithms in the key structure to algorithms in the message 3988 structure. In addition to checking that algorithms are correct, the 3989 key form needs to be checked as well. Do not use an 'EC2' key where 3990 an 'OKP' key is expected. 3992 Before using a key for transmission, or before acting on information 3993 received, a trust decision on a key needs to be made. Is the data or 3994 action something that the entity associated with the key has a right 3995 to see or a right to request? A number of factors are associated 3996 with this trust decision. Some of the ones that are highlighted here 3997 are: 3999 o What are the permissions associated with the key owner? 4001 o Is the cryptographic algorithm acceptable in the current context? 4003 o Have the restrictions associated with the key, such as algorithm 4004 or freshness, been checked and are correct? 4006 o Is the request something that is reasonable, given the current 4007 state of the application? 4009 o Have any security considerations that are part of the message been 4010 enforced (as specified by the application or 'crit' parameter)? 4012 There are a large number of algorithms presented in this document 4013 that use nonce values. For all of the nonces defined in this 4014 document, there is some type of restriction on the nonce being a 4015 unique value either for a key or for some other conditions. In all 4016 of these cases, there is no known requirement on the nonce being both 4017 unique and unpredictable, under these circumstances it reasonable to 4018 use a counter for creation of the nonce. In cases where one wants 4019 the pattern of the nonce to be unpredictable as well as unique, one 4020 can use a key created for that purpose and encrypt the counter to 4021 produce the nonce value. 4023 One area that has been starting to get exposure is doing traffic 4024 analysis of encrypted messages based on the length of the message. 4025 This specification does not provide for a uniform method of providing 4026 padding as part of the message structure. An observer can 4027 distinguish between two different strings (for example, 'YES' and 4028 'NO') based on length for all of the content encryption algorithms 4029 that are defined in this document. This means that it is up to 4030 applications to document how content padding is to be done in order 4031 to prevent or discourage such analysis. (For example, the strings 4032 could be defined as 'YES' and 'NO '.) 4034 19. References 4036 19.1. Normative References 4038 [AES-GCM] Dworkin, M., "NIST Special Publication 800-38D: 4039 Recommendation for Block Cipher Modes of Operation: 4040 Galois/Counter Mode (GCM) and GMAC.", Nov 2007. 4042 [COAP.Formats] 4043 IANA, , "CoAP Content-Formats". 4045 [DSS] U.S. National Institute of Standards and Technology, 4046 "Digital Signature Standard (DSS)", July 2013. 4048 [MAC] NiST, N., "FIPS PUB 113: Computer Data Authentication", 4049 May 1985. 4051 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 4052 Hashing for Message Authentication", RFC 2104, 4053 DOI 10.17487/RFC2104, February 1997, 4054 . 4056 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4057 Requirement Levels", BCP 14, RFC 2119, 4058 DOI 10.17487/RFC2119, March 1997, 4059 . 4061 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 4062 (AES) Key Wrap Algorithm", RFC 3394, DOI 10.17487/RFC3394, 4063 September 2002, . 4065 [RFC3610] Whiting, D., Housley, R., and N. Ferguson, "Counter with 4066 CBC-MAC (CCM)", RFC 3610, DOI 10.17487/RFC3610, September 4067 2003, . 4069 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 4070 Key Derivation Function (HKDF)", RFC 5869, 4071 DOI 10.17487/RFC5869, May 2010, 4072 . 4074 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 4075 Curve Cryptography Algorithms", RFC 6090, 4076 DOI 10.17487/RFC6090, February 2011, 4077 . 4079 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 4080 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 4081 October 2013, . 4083 [RFC7539] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF 4084 Protocols", RFC 7539, DOI 10.17487/RFC7539, May 2015, 4085 . 4087 [SEC1] Standards for Efficient Cryptography Group, "SEC 1: 4088 Elliptic Curve Cryptography", May 2009. 4090 19.2. Informative References 4092 [I-D.greevenbosch-appsawg-cbor-cddl] 4093 Vigano, C. and H. Birkholz, "CBOR data definition language 4094 (CDDL): a notational convention to express CBOR data 4095 structures", draft-greevenbosch-appsawg-cbor-cddl-09 (work 4096 in progress), September 2016. 4098 [I-D.irtf-cfrg-eddsa] 4099 Josefsson, S. and I. Liusvaara, "Edwards-curve Digital 4100 Signature Algorithm (EdDSA)", draft-irtf-cfrg-eddsa-08 4101 (work in progress), August 2016. 4103 [PVSig] Brown, D. and D. Johnson, "Formal Security Proofs for a 4104 Signature Scheme with Partial Message Recover", February 4105 2000. 4107 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 4108 Extensions (MIME) Part One: Format of Internet Message 4109 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, 4110 . 4112 [RFC2633] Ramsdell, B., Ed., "S/MIME Version 3 Message 4113 Specification", RFC 2633, DOI 10.17487/RFC2633, June 1999, 4114 . 4116 [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography 4117 Specification Version 2.0", RFC 2898, 4118 DOI 10.17487/RFC2898, September 2000, 4119 . 4121 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 4122 Standards (PKCS) #1: RSA Cryptography Specifications 4123 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 4124 2003, . 4126 [RFC4231] Nystrom, M., "Identifiers and Test Vectors for HMAC-SHA- 4127 224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512", 4128 RFC 4231, DOI 10.17487/RFC4231, December 2005, 4129 . 4131 [RFC4262] Santesson, S., "X.509 Certificate Extension for Secure/ 4132 Multipurpose Internet Mail Extensions (S/MIME) 4133 Capabilities", RFC 4262, DOI 10.17487/RFC4262, December 4134 2005, . 4136 [RFC4493] Song, JH., Poovendran, R., Lee, J., and T. Iwata, "The 4137 AES-CMAC Algorithm", RFC 4493, DOI 10.17487/RFC4493, June 4138 2006, . 4140 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 4141 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 4142 . 4144 [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, 4145 "Elliptic Curve Cryptography Subject Public Key 4146 Information", RFC 5480, DOI 10.17487/RFC5480, March 2009, 4147 . 4149 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 4150 RFC 5652, DOI 10.17487/RFC5652, September 2009, 4151 . 4153 [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet 4154 Mail Extensions (S/MIME) Version 3.2 Message 4155 Specification", RFC 5751, DOI 10.17487/RFC5751, January 4156 2010, . 4158 [RFC5752] Turner, S. and J. Schaad, "Multiple Signatures in 4159 Cryptographic Message Syntax (CMS)", RFC 5752, 4160 DOI 10.17487/RFC5752, January 2010, 4161 . 4163 [RFC5990] Randall, J., Kaliski, B., Brainard, J., and S. Turner, 4164 "Use of the RSA-KEM Key Transport Algorithm in the 4165 Cryptographic Message Syntax (CMS)", RFC 5990, 4166 DOI 10.17487/RFC5990, September 2010, 4167 . 4169 [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations 4170 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 4171 RFC 6151, DOI 10.17487/RFC6151, March 2011, 4172 . 4174 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 4175 Algorithm (DSA) and Elliptic Curve Digital Signature 4176 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 4177 2013, . 4179 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 4180 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 4181 2014, . 4183 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 4184 Application Protocol (CoAP)", RFC 7252, 4185 DOI 10.17487/RFC7252, June 2014, 4186 . 4188 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 4189 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 4190 2015, . 4192 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 4193 RFC 7516, DOI 10.17487/RFC7516, May 2015, 4194 . 4196 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 4197 DOI 10.17487/RFC7517, May 2015, 4198 . 4200 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 4201 DOI 10.17487/RFC7518, May 2015, 4202 . 4204 [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 4205 for Security", RFC 7748, DOI 10.17487/RFC7748, January 4206 2016, . 4208 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 4209 Code: The Implementation Status Section", BCP 205, 4210 RFC 7942, DOI 10.17487/RFC7942, July 2016, 4211 . 4213 [SP800-56A] 4214 Barker, E., Chen, L., Roginsky, A., and M. Smid, "NIST 4215 Special Publication 800-56A: Recommendation for Pair-Wise 4216 Key Establishment Schemes Using Discrete Logarithm 4217 Cryptography", May 2013. 4219 Appendix A. Making Mandatory Algorithm Header Optional 4221 There has been a portion of the working group who have expressed a 4222 strong desire to relax the rule that the algorithm identifier be 4223 required to appear in each level of a COSE object. There are two 4224 basic reasons that have been advanced to support this position. 4225 First, the resulting message will be smaller if the algorithm 4226 identifier is omitted from the most common messages in a CoAP 4227 environment. Second, there is a potential bug that will arise if 4228 full checking is not done correctly between the different places that 4229 an algorithm identifier could be placed (the message itself, an 4230 application statement, the key structure that the sender possesses 4231 and the key structure the recipient possesses). 4233 This appendix lays out how such a change can be made and the details 4234 that an application needs to specify in order to use this option. 4235 Two different sets of details are specified: Those needed to omit an 4236 algorithm identifier and those needed to use a variant on the counter 4237 signature attribute that contains no attributes about itself. 4239 A.1. Algorithm Identification 4241 In this section are laid out three sets of recommendations. The 4242 first set of recommendations apply to having an implicit algorithm 4243 identified for a single layer of a COSE object. The second set of 4244 recommendations apply to having multiple implicit algorithms 4245 identified for multiple layers of a COSE object. The third set of 4246 recommendations apply to having implicit algorithms for multiple COSE 4247 object constructs. 4249 RFC 2119 language is deliberately not used here. This specification 4250 can provide recommendations, but it cannot enforce them. 4252 This set of recommendations applies to the case where an application 4253 is distributing a fixed algorithm along with the key information for 4254 use in a single COSE object. This normally applies to the smallest 4255 of the COSE objects, specifically COSE_Sign1, COSE_Mac0, and 4256 COSE_Encrypt0, but could apply to the other structures as well. 4258 The following items should be taken into account: 4260 o Applications need to list the set of COSE structures that implicit 4261 algorithms are to be used in. Applications need to require that 4262 the receipt of an explicit algorithm identifier in one of these 4263 structures will lead to the message being rejected. This 4264 requirement is stated so that there will never be a case where 4265 there is any ambiguity about the question of which algorithm 4266 should be used, the implicit or the explicit one. This applies 4267 even if the transported algorithm identifier is a protected 4268 attribute. This applies even if the transported algorithm is the 4269 same as the implicit algorithm. 4271 o Applications need to define the set of information that is to be 4272 considered to be part of a context when omitting algorithm 4273 identifiers. At a minimum, this would be the key identifier (if 4274 needed), the key, the algorithm, and the COSE structure it is used 4275 with. Applications should restrict the use of a single key to a 4276 single algorithm. As noted for some of the algorithms in this 4277 document, the use of the same key in different related algorithms 4278 can lead to leakage of information about the key, leakage about 4279 the data or the ability to perform forgeries. 4281 o In many cases, applications that make the algorithm identifier 4282 implicit will also want to make the context identifier implicit 4283 for the same reason. That is, omitting the context identifier 4284 will decrease the message size (potentially significantly 4285 depending on the length of the identifier). Applications that do 4286 this will need to describe the circumstances where the context 4287 identifier is to be omitted and how the context identifier is to 4288 be inferred in these cases. (Exhaustive search over all of the 4289 keys would normally not be considered to be acceptable.) An 4290 example of how this can be done is to tie the context to a 4291 transaction identifier. Both would be sent on the original 4292 message, but only the transaction identifier would need to be sent 4293 after that point as the context is tied into the transaction 4294 identifier. Another way would be to associate a context with a 4295 network address. All messages coming from a single network 4296 address can be assumed to be associated with a specific context. 4297 (In this case the address would normally be distributed as part of 4298 the context.) 4300 o Applications cannot rely on key identifiers being unique unless 4301 they take significant efforts to ensure that they are computed in 4302 such a way as to create this guarantee. Even when an application 4303 does this, the uniqueness might be violated if the application is 4304 run in different contexts (i.e., with a different context 4305 provider) or if the system combines the security contexts from 4306 different applications together into a single store. 4308 o Applications should continue the practice of protecting the 4309 algorithm identifier. Since this is not done by placing it in the 4310 protected attributes field, applications should define an 4311 application specific external data structure that includes this 4312 value. This external data field can be used as such for content 4313 encryption, MAC, and signature algorithms. It can be used in the 4314 SuppPrivInfo field for those algorithms which use a KDF function 4315 to derive a key value. Applications may also want to protect 4316 other information that is part of the context structure as well. 4317 It should be noted that those fields, such as the key or a base 4318 IV, are protected by virtue of being used in the cryptographic 4319 computation and do not need to be included in the external data 4320 field. 4322 The second case is having multiple implicit algorithm identifiers 4323 specified for a multiple layer COSE object. An example of how this 4324 would work is the encryption context that an application specifies 4325 contains a content encryption algorithm, a key wrap algorithm, a key 4326 identifier, and a shared secret. The sender omits sending the 4327 algorithm identifier for both the content layer and the recipient 4328 layer leaving only the key identifier. The receiver then uses the 4329 key identifier to get the implicit algorithm identifiers. 4331 The following additional items need to be taken into consideration: 4333 o Applications that want to support this will need to define a 4334 structure that allows for, and clearly identifies, both the COSE 4335 structure to be used with a given key and the structure and 4336 algorithm to be used for the secondary layer. The key for the 4337 secondary layer is computed per normal from the recipient layer. 4339 The third case is having multiple implicit algorithm identifiers, but 4340 targeted at potentially unrelated layers or different COSE objects. 4341 There are a number of different scenarios where this might be 4342 applicable. Some of these scenarios are: 4344 o Two contexts are distributed as a pair. Each of the contexts is 4345 for use with a COSE_Encrypt message. Each context will consist of 4346 distinct secret keys and IVs and potentially even different 4347 algorithms. One context is for sending messages from party A to 4348 party B, the second context is for sending messages from party B 4349 to party A. This means that there is no chance for a reflection 4350 attack to occur as each party uses different secret keys to send 4351 its messages, a message that is reflected back to it would fail to 4352 decrypt. 4354 o Two contexts are distributed as a pair. The first context is used 4355 for encryption of the message; the second context is used to place 4356 a counter signature on the message. The intention is that the 4357 second context can be distributed to other entities independently 4358 of the first context. This allows these entities to validate that 4359 the message came from an individual without being able to decrypt 4360 the message and see the content. 4362 o Two contexts are distributed as a pair. The first context 4363 contains a key for dealing with MACed messages, the second context 4364 contains a key for dealing with encrypted messages. This allows 4365 for a unified distribution of keys to participants for different 4366 types of messages that have different keys, but where the keys may 4367 be used in coordinated manner. 4369 For these cases, the following additional items need to be 4370 considered: 4372 o Applications need to ensure that the multiple contexts stay 4373 associated. If one of the contexts is invalidated for any reason, 4374 all of the contexts associated with it should also be invalidated. 4376 A.2. Counter Signature Without Headers 4378 There is a group of people who want to have a counter signature 4379 parameter that is directly tied to the value being signed and thus 4380 the authenticated and unauthenticated buckets can be removed from the 4381 message being sent. The focus on this is an even smaller size, as 4382 all of the information on the process of creating the counter 4383 signature is implicit rather than being explicitly carried in the 4384 message. This includes not only the algorithm identifier as 4385 presented above, but also items such as the key identification is 4386 always external to the signature structure. This means that the 4387 entities that are doing the validation of the counter signature are 4388 required to infer which key is to be used from context rather than 4389 being explicit. One way of doing this would be to presume that all 4390 data coming from a specific port (or to a specific URL) is to be 4391 validated by a specific key. (Note that this does not require that 4392 the key identifier be part of the value signed as it does not serve a 4393 cryptographic purpose. If the key validates the counter signature, 4394 then it should be presumed that the entity associated with that key 4395 produced the signature.) 4397 When computing the signature for the bare counter signature header, 4398 the same Sig_structure defined in Section 4.4 is used. The 4399 sign_protected field is omitted, as there is no protected header 4400 field in in this counter signature header. The value of 4401 "CounterSignature0" is placed in the context field of the 4402 Sig_stucture. 4404 +-------------------+-------+--------+------------------------------+ 4405 | name | label | value | description | 4406 | | | type | | 4407 +-------------------+-------+--------+------------------------------+ 4408 | CounterSignature0 | 9 | bstr | Counter signature with | 4409 | | | | implied signer and headers | 4410 +-------------------+-------+--------+------------------------------+ 4412 Table 27 4414 Appendix B. Two Layers of Recipient Information 4416 All of the currently defined recipient algorithms classes only use 4417 two layers of the COSE_Encrypt structure. The first layer is the 4418 message content and the second layer is the content key encryption. 4419 However, if one uses a recipient algorithm such as RSA-KEM (see 4420 Appendix A of RSA-KEM [RFC5990]), then it makes sense to have three 4421 layers of the COSE_Encrypt structure. 4423 These layers would be: 4425 o Layer 0: The content encryption layer. This layer contains the 4426 payload of the message. 4428 o Layer 1: The encryption of the CEK by a KEK. 4430 o Layer 2: The encryption of a long random secret using an RSA key 4431 and a key derivation function to convert that secret into the KEK. 4433 This is an example of what a triple layer message would look like. 4434 The message has the following layers: 4436 o Layer 0: Has a content encrypted with AES-GCM using a 128-bit key. 4438 o Layer 1: Uses the AES Key wrap algorithm with a 128-bit key. 4440 o Layer 2: Uses ECDH Ephemeral-Static direct to generate the layer 1 4441 key. 4443 In effect, this example is a decomposed version of using the ECDH- 4444 ES+A128KW algorithm. 4446 Size of binary file is 184 bytes 4447 992( 4448 [ 4449 / protected / h'a10101' / { 4450 \ alg \ 1:1 \ AES-GCM 128 \ 4451 } / , 4452 / unprotected / { 4453 / iv / 5:h'02d1f7e6f26c43d4868d87ce' 4454 }, 4455 / ciphertext / h'64f84d913ba60a76070a9a48f26e97e863e2852948658f0 4456 811139868826e89218a75715b', 4457 / recipients / [ 4458 [ 4459 / protected / h'', 4460 / unprotected / { 4461 / alg / 1:-3 / A128KW / 4462 }, 4463 / ciphertext / h'dbd43c4e9d719c27c6275c67d628d493f090593db82 4464 18f11', 4465 / recipients / [ 4466 [ 4467 / protected / h'a1013818' / { 4468 \ alg \ 1:-25 \ ECDH-ES + HKDF-256 \ 4469 } / , 4470 / unprotected / { 4471 / ephemeral / -1:{ 4472 / kty / 1:2, 4473 / crv / -1:1, 4474 / x / -2:h'b2add44368ea6d641f9ca9af308b4079aeb519f11 4475 e9b8a55a600b21233e86e68', 4476 / y / -3:false 4477 }, 4478 / kid / 4:'meriadoc.brandybuck@buckland.example' 4479 }, 4480 / ciphertext / h'' 4481 ] 4482 ] 4483 ] 4484 ] 4485 ] 4486 ) 4488 Appendix C. Examples 4490 This appendix includes a set of examples that show the different 4491 features and message types that have been defined in this document. 4492 To make the examples easier to read, they are presented using the 4493 extended CBOR diagnostic notation (defined in 4494 [I-D.greevenbosch-appsawg-cbor-cddl]) rather than as a binary dump. 4496 A GitHub project has been created at https://github.com/cose-wg/ 4497 Examples that contains not only the examples presented in this 4498 document, but a more complete set of testing examples as well. Each 4499 example is found in a JSON file that contains the inputs used to 4500 create the example, some of the intermediate values that can be used 4501 in debugging the example and the output of the example presented in 4502 both a hex and a CBOR diagnostic notation format. Some of the 4503 examples at the site are designed failure testing cases; these are 4504 clearly marked as such in the JSON file. If errors in the examples 4505 in this document are found, the examples on github will be updated 4506 and a note to that effect will be placed in the JSON file. 4508 As noted, the examples are presented using the CBOR's diagnostic 4509 notation. A Ruby based tool exists that can convert between the 4510 diagnostic notation and binary. This tool can be installed with the 4511 command line: 4513 gem install cbor-diag 4515 The diagnostic notation can be converted into binary files using the 4516 following command line: 4518 diag2cbor.rb < inputfile > outputfile 4520 The examples can be extracted from the XML version of this document 4521 via an XPath expression as all of the artwork is tagged with the 4522 attribute type='CBORdiag'. (Depending on the XPath evaluator one is 4523 using, it may be necessary to deal with > as an entity.) 4525 //artwork[@type='CDDL']/text() 4527 C.1. Examples of Signed Message 4529 C.1.1. Single Signature 4531 This example uses the following: 4533 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 4535 Size of binary file is 104 bytes 4536 991( 4537 [ 4538 / protected / h'', 4539 / unprotected / {}, 4540 / payload / 'This is the content.', 4541 / signatures / [ 4542 [ 4543 / protected / h'a10126' / { 4544 \ alg \ 1:-7 \ ECDSA 256 \ 4545 } / , 4546 / unprotected / { 4547 / kid / 4:'11' 4548 }, 4549 / signature / h'eae868ecc176883766c5dc5ba5b8dca25dab3c2e56a5 4550 51ce5705b793914348e14eea4aee6e0c9f09db4ef3ddeca8f3506cd1a98a8fb64327 4551 be470355c9657ce0' 4552 ] 4553 ] 4554 ] 4555 ) 4557 C.1.2. Multiple Signers 4559 This example uses the following: 4561 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 4563 o Signature Algorithm: ECDSA w/ SHA-512, Curve P-521 4565 Size of binary file is 278 bytes 4566 991( 4567 [ 4568 / protected / h'', 4569 / unprotected / {}, 4570 / payload / 'This is the content.', 4571 / signatures / [ 4572 [ 4573 / protected / h'a10126' / { 4574 \ alg \ 1:-7 \ ECDSA 256 \ 4575 } / , 4576 / unprotected / { 4577 / kid / 4:'11' 4578 }, 4579 / signature / h'0dc1c5e62719d8f3cce1468b7c881eee6a8088b46bf8 4580 36ae956dd38fe93199199951a6a5e02a24aed5edde3509748366b1c539aaef7dea34 4581 f2cd618fe19fe55d' 4582 ], 4583 [ 4584 / protected / h'a1013823' / { 4585 \ alg \ 1:-36 4586 } / , 4587 / unprotected / { 4588 / kid / 4:'bilbo.baggins@hobbiton.example' 4589 }, 4590 / signature / h'012ce5b1dfe8b5aa6eaa09a54c58a84ad0900e4fdf27 4591 59ec22d1c861cccd75c7e1c4025a2da35e512fc2874d6ac8fd862d09ad07ed2deac2 4592 97b897561e04a8d42476017c11a4a34e26c570c9eff22c1dc84d56cdf6e03ed34bc9 4593 e934c5fdf676c7948d79e97dfe161730217c57748aadb364a0207cee811e9dde65ae 4594 37942e8a8348cc91' 4595 ] 4596 ] 4597 ] 4598 ) 4600 C.1.3. Counter Signature 4602 This example uses the following: 4604 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 4606 o The same parameters are used for both the signature and the 4607 counter signature. 4609 Size of binary file is 181 bytes 4610 991( 4611 [ 4612 / protected / h'', 4613 / unprotected / { 4614 / countersign / 7:[ 4615 / protected / h'a10126' / { 4616 \ alg \ 1:-7 \ ECDSA 256 \ 4617 } / , 4618 / unprotected / { 4619 / kid / 4:'11' 4620 }, 4621 / signature / h'c9d3402485aa585cee3efc69b14496c0b00714584b26 4622 0f8e05764b7dbc70ae2b23b89812f5895b805f07a792f7ce77ef6d63875dc37d6a78 4623 ef4d175da45c9a51' 4624 ] 4625 }, 4626 / payload / 'This is the content.', 4627 / signatures / [ 4628 [ 4629 / protected / h'a10126' / { 4630 \ alg \ 1:-7 \ ECDSA 256 \ 4631 } / , 4632 / unprotected / { 4633 / kid / 4:'11' 4634 }, 4635 / signature / h'eae868ecc176883766c5dc5ba5b8dca25dab3c2e56a5 4636 51ce5705b793914348e14eea4aee6e0c9f09db4ef3ddeca8f3506cd1a98a8fb64327 4637 be470355c9657ce0' 4638 ] 4639 ] 4640 ] 4641 ) 4643 C.1.4. Signature w/ Criticality 4645 This example uses the following: 4647 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 4649 o There is a criticality marker on the "reserved" header parameter 4651 Size of binary file is 126 bytes 4652 991( 4653 [ 4654 / protected / h'a2687265736572766564f40281687265736572766564' / 4655 { 4656 "reserved":false, 4657 \ crit \ 2:[ 4658 "reserved" 4659 ] 4660 } / , 4661 / unprotected / {}, 4662 / payload / 'This is the content.', 4663 / signatures / [ 4664 [ 4665 / protected / h'a10126' / { 4666 \ alg \ 1:-7 \ ECDSA 256 \ 4667 } / , 4668 / unprotected / { 4669 / kid / 4:'11' 4670 }, 4671 / signature / h'eae868ecc176883766c5dc5ba5b8dca25dab3c2e56a5 4672 51ce5705b793914348e1ff259ead2c38d8a7d8a9c87c2ce534d762dab059773115a6 4673 176fa780e85b6b25' 4674 ] 4675 ] 4676 ] 4677 ) 4679 C.2. Single Signer Examples 4681 C.2.1. Single ECDSA signature 4683 This example uses the following: 4685 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 4687 Size of binary file is 100 bytes 4688 997( 4689 [ 4690 / protected / h'a10126' / { 4691 \ alg \ 1:-7 \ ECDSA 256 \ 4692 } / , 4693 / unprotected / { 4694 / kid / 4:'11' 4695 }, 4696 / payload / 'This is the content.', 4697 / signature / h'eae868ecc176883766c5dc5ba5b8dca25dab3c2e56a551ce 4698 5705b793914348e19f43d6c6ba654472da301b645b293c9ba939295b97c4bdb84778 4699 2bff384c5794' 4700 ] 4701 ) 4703 C.3. Examples of Enveloped Messages 4705 C.3.1. Direct ECDH 4707 This example uses the following: 4709 o CEK: AES-GCM w/ 128-bit key 4711 o Recipient class: ECDH Ephemeral-Static, Curve P-256 4713 Size of binary file is 152 bytes 4714 992( 4715 [ 4716 / protected / h'a10101' / { 4717 \ alg \ 1:1 \ AES-GCM 128 \ 4718 } / , 4719 / unprotected / { 4720 / iv / 5:h'c9cf4df2fe6c632bf7886413' 4721 }, 4722 / ciphertext / h'7adbe2709ca818fb415f1e5df66f4e1a51053ba6d65a1a0 4723 c52a357da7a644b8070a151b0', 4724 / recipients / [ 4725 [ 4726 / protected / h'a1013818' / { 4727 \ alg \ 1:-25 \ ECDH-ES + HKDF-256 \ 4728 } / , 4729 / unprotected / { 4730 / ephemeral / -1:{ 4731 / kty / 1:2, 4732 / crv / -1:1, 4733 / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf 4734 bf054e1c7b4d91d6280', 4735 / y / -3:true 4736 }, 4737 / kid / 4:'meriadoc.brandybuck@buckland.example' 4738 }, 4739 / ciphertext / h'' 4740 ] 4741 ] 4742 ] 4743 ) 4745 C.3.2. Direct plus Key Derivation 4747 This example uses the following: 4749 o CEK: AES-CCM w/128-bit key, truncate the tag to 64 bits 4751 o Recipient class: Use HKDF on a shared secret with the following 4752 implicit fields as part of the context. 4754 * salt: "aabbccddeeffgghh" 4756 * APU identity: "lighting-client" 4758 * APV identity: "lighting-server" 4760 * Supplementary Public Other: "Encryption Example 02" 4762 Size of binary file is 92 bytes 4764 992( 4765 [ 4766 / protected / h'a1010a' / { 4767 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 4768 } / , 4769 / unprotected / { 4770 / iv / 5:h'89f52f65a1c580933b5261a76c' 4771 }, 4772 / ciphertext / h'753548a19b1307084ca7b2056924ed95f2e3b17006dfe93 4773 1b687b847', 4774 / recipients / [ 4775 [ 4776 / protected / h'a10129' / { 4777 \ alg \ 1:-10 4778 } / , 4779 / unprotected / { 4780 / salt / -20:'aabbccddeeffgghh', 4781 / kid / 4:'our-secret' 4782 }, 4783 / ciphertext / h'' 4784 ] 4785 ] 4786 ] 4787 ) 4789 C.3.3. Counter Signature on Encrypted Content 4791 This example uses the following: 4793 o CEK: AES-GCM w/ 128-bit key 4795 o Recipient class: ECDH Ephemeral-Static, Curve P-256 4797 Size of binary file is 327 bytes 4798 992( 4799 [ 4800 / protected / h'a10101' / { 4801 \ alg \ 1:1 \ AES-GCM 128 \ 4802 } / , 4803 / unprotected / { 4804 / iv / 5:h'c9cf4df2fe6c632bf7886413', 4805 / countersign / 7:[ 4806 / protected / h'a1013823' / { 4807 \ alg \ 1:-36 4808 } / , 4809 / unprotected / { 4810 / kid / 4:'bilbo.baggins@hobbiton.example' 4811 }, 4812 / signature / h'00aa98cbfd382610a375d046a275f30266e8d0faacb9 4813 069fde06e37825ae7825419c474f416ded0c8e3e7b55bff68f2a704135bdf99186f6 4814 6659461c8cf929cc7fb300f5e2b33c3b433655042ff719804ff73b0be3e988ecebc0 4815 c70ef6616996809c6eb59a918dbe0a5edb0d15137ece0aba2a0b0f68ad2631cb62f2 4816 ea4d7099804218b0' 4817 ] 4818 }, 4819 / ciphertext / h'7adbe2709ca818fb415f1e5df66f4e1a51053ba6d65a1a0 4820 c52a357da7a644b8070a151b0', 4821 / recipients / [ 4822 [ 4823 / protected / h'a1013818' / { 4824 \ alg \ 1:-25 \ ECDH-ES + HKDF-256 \ 4825 } / , 4826 / unprotected / { 4827 / ephemeral / -1:{ 4828 / kty / 1:2, 4829 / crv / -1:1, 4830 / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf 4831 bf054e1c7b4d91d6280', 4832 / y / -3:true 4833 }, 4834 / kid / 4:'meriadoc.brandybuck@buckland.example' 4835 }, 4836 / ciphertext / h'' 4837 ] 4838 ] 4839 ] 4840 ) 4842 C.3.4. Encrypted Content with External Data 4844 This example uses the following: 4846 o CEK: AES-GCM w/ 128-bit key 4848 o Recipient class: ECDH static-Static, Curve P-256 with AES Key Wrap 4850 o Externally Supplied AAD: h'0011bbcc22dd44ee55ff660077' 4852 Size of binary file is 174 bytes 4854 992( 4855 [ 4856 / protected / h'a10101' / { 4857 \ alg \ 1:1 \ AES-GCM 128 \ 4858 } / , 4859 / unprotected / { 4860 / iv / 5:h'02d1f7e6f26c43d4868d87ce' 4861 }, 4862 / ciphertext / h'64f84d913ba60a76070a9a48f26e97e863e28529d8f5335 4863 e5f0165eee976b4a5f6c6f09d', 4864 / recipients / [ 4865 [ 4866 / protected / h'a101381f' / { 4867 \ alg \ 1:-32 \ ECHD-SS+A128KW \ 4868 } / , 4869 / unprotected / { 4870 / static kid / -3:'peregrin.took@tuckborough.example', 4871 / kid / 4:'meriadoc.brandybuck@buckland.example', 4872 / U nonce / -22:h'0101' 4873 }, 4874 / ciphertext / h'41e0d76f579dbd0d936a662d54d8582037de2e366fd 4875 e1c62' 4876 ] 4877 ] 4878 ] 4879 ) 4881 C.4. Examples of Encrypted Messages 4883 C.4.1. Simple Encrypted Message 4885 This example uses the following: 4887 o CEK: AES-CCM w/ 128-bit key and a 64-bit tag 4889 Size of binary file is 54 bytes 4890 993( 4891 [ 4892 / protected / h'a1010a' / { 4893 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 4894 } / , 4895 / unprotected / { 4896 / iv / 5:h'89f52f65a1c580933b5261a78c' 4897 }, 4898 / ciphertext / h'5974e1b99a3a4cc09a659aa2e9e7fff161d38ce7edd5617 4899 388e77baf' 4900 ] 4901 ) 4903 C.4.2. Encrypted Message w/ a Partial IV 4905 This example uses the following: 4907 o CEK: AES-CCM w/ 128-bit key and a 64-bit tag 4909 o Prefix for IV is 89F52F65A1C580933B52 4911 Size of binary file is 43 bytes 4913 993( 4914 [ 4915 / protected / h'a1010a' / { 4916 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 4917 } / , 4918 / unprotected / { 4919 / partial iv / 6:h'61a7' 4920 }, 4921 / ciphertext / h'252a8911d465c125b6764739700f0141ed09192da5c69e5 4922 33abf852b' 4923 ] 4924 ) 4926 C.5. Examples of MACed messages 4928 C.5.1. Shared Secret Direct MAC 4930 This example uses the following: 4932 o MAC: AES-CMAC, 256-bit key, truncated to 64 bits 4934 o Recipient class: direct shared secret 4936 Size of binary file is 58 bytes 4937 994( 4938 [ 4939 / protected / h'a1010f' / { 4940 \ alg \ 1:15 \ AES-CBC-MAC-256//64 \ 4941 } / , 4942 / unprotected / {}, 4943 / payload / 'This is the content.', 4944 / tag / h'9e1226ba1f81b848', 4945 / recipients / [ 4946 [ 4947 / protected / h'', 4948 / unprotected / { 4949 / alg / 1:-6 / direct /, 4950 / kid / 4:'our-secret' 4951 }, 4952 / ciphertext / h'' 4953 ] 4954 ] 4955 ] 4956 ) 4958 C.5.2. ECDH Direct MAC 4960 This example uses the following: 4962 o MAC: HMAC w/SHA-256, 256-bit key 4964 o Recipient class: ECDH key agreement, two static keys, HKDF w/ 4965 context structure 4967 Size of binary file is 215 bytes 4968 994( 4969 [ 4970 / protected / h'a10105' / { 4971 \ alg \ 1:5 \ HMAC 256//256 \ 4972 } / , 4973 / unprotected / {}, 4974 / payload / 'This is the content.', 4975 / tag / h'81a03448acd3d305376eaa11fb3fe416a955be2cbe7ec96f012c99 4976 4bc3f16a41', 4977 / recipients / [ 4978 [ 4979 / protected / h'a101381a' / { 4980 \ alg \ 1:-27 \ ECDH-SS + HKDF-256 \ 4981 } / , 4982 / unprotected / { 4983 / static kid / -3:'peregrin.took@tuckborough.example', 4984 / kid / 4:'meriadoc.brandybuck@buckland.example', 4985 / U nonce / -22:h'4d8553e7e74f3c6a3a9dd3ef286a8195cbf8a23d 4986 19558ccfec7d34b824f42d92bd06bd2c7f0271f0214e141fb779ae2856abf585a583 4987 68b017e7f2a9e5ce4db5' 4988 }, 4989 / ciphertext / h'' 4990 ] 4991 ] 4992 ] 4993 ) 4995 C.5.3. Wrapped MAC 4997 This example uses the following: 4999 o MAC: AES-MAC, 128-bit key, truncated to 64 bits 5001 o Recipient class: AES keywrap w/ a pre-shared 256-bit key 5003 Size of binary file is 110 bytes 5004 994( 5005 [ 5006 / protected / h'a1010e' / { 5007 \ alg \ 1:14 \ AES-CBC-MAC-128//64 \ 5008 } / , 5009 / unprotected / {}, 5010 / payload / 'This is the content.', 5011 / tag / h'36f5afaf0bab5d43', 5012 / recipients / [ 5013 [ 5014 / protected / h'', 5015 / unprotected / { 5016 / alg / 1:-5 / A256KW /, 5017 / kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037' 5018 }, 5019 / ciphertext / h'711ab0dc2fc4585dce27effa6781c8093eba906f227 5020 b6eb0' 5021 ] 5022 ] 5023 ] 5024 ) 5026 C.5.4. Multi-recipient MACed message 5028 This example uses the following: 5030 o MAC: HMAC w/ SHA-256, 128-bit key 5032 o Recipient class: Uses three different methods 5034 1. ECDH Ephemeral-Static, Curve P-521, AES-Key Wrap w/ 128-bit 5035 key 5037 2. AES-Key Wrap w/ 256-bit key 5039 Size of binary file is 310 bytes 5040 994( 5041 [ 5042 / protected / h'a10105' / { 5043 \ alg \ 1:5 \ HMAC 256//256 \ 5044 } / , 5045 / unprotected / {}, 5046 / payload / 'This is the content.', 5047 / tag / h'bf48235e809b5c42e995f2b7d5fa13620e7ed834e337f6aa43df16 5048 1e49e9323e', 5049 / recipients / [ 5050 [ 5051 / protected / h'a101381c' / { 5052 \ alg \ 1:-29 \ ECHD-ES+A128KW \ 5053 } / , 5054 / unprotected / { 5055 / ephemeral / -1:{ 5056 / kty / 1:2, 5057 / crv / -1:3, 5058 / x / -2:h'0043b12669acac3fd27898ffba0bcd2e6c366d53bc4db 5059 71f909a759304acfb5e18cdc7ba0b13ff8c7636271a6924b1ac63c02688075b55ef2 5060 d613574e7dc242f79c3', 5061 / y / -3:true 5062 }, 5063 / kid / 4:'bilbo.baggins@hobbiton.example' 5064 }, 5065 / ciphertext / h'339bc4f79984cdc6b3e6ce5f315a4c7d2b0ac466fce 5066 a69e8c07dfbca5bb1f661bc5f8e0df9e3eff5' 5067 ], 5068 [ 5069 / protected / h'', 5070 / unprotected / { 5071 / alg / 1:-5 / A256KW /, 5072 / kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037' 5073 }, 5074 / ciphertext / h'0b2c7cfce04e98276342d6476a7723c090dfdd15f9a 5075 518e7736549e998370695e6d6a83b4ae507bb' 5076 ] 5077 ] 5078 ] 5079 ) 5081 C.6. Examples of MAC0 messages 5083 C.6.1. Shared Secret Direct MAC 5085 This example uses the following: 5087 o MAC: AES-CMAC, 256-bit key, truncated to 64 bits 5088 o Recipient class: direct shared secret 5090 Size of binary file is 39 bytes 5092 996( 5093 [ 5094 / protected / h'a1010f' / { 5095 \ alg \ 1:15 \ AES-CBC-MAC-256//64 \ 5096 } / , 5097 / unprotected / {}, 5098 / payload / 'This is the content.', 5099 / tag / h'726043745027214f' 5100 ] 5101 ) 5103 Note that this example uses the same inputs as Appendix C.5.1. 5105 C.7. COSE Keys 5107 C.7.1. Public Keys 5109 This is an example of a COSE Key set. This example includes the 5110 public keys for all of the previous examples. 5112 In order the keys are: 5114 o An EC key with a kid of "meriadoc.brandybuck@buckland.example" 5116 o An EC key with a kid of "peregrin.took@tuckborough.example" 5118 o An EC key with a kid of "bilbo.baggins@hobbiton.example" 5120 o An EC key with a kid of "11" 5122 Size of binary file is 481 bytes 5124 [ 5125 { 5126 -1:1, 5127 -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0 5128 8551d', 5129 -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008 5130 4d19c', 5131 1:2, 5132 2:'meriadoc.brandybuck@buckland.example' 5133 }, 5134 { 5135 -1:1, 5136 -2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a 5137 09eff', 5138 -3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbf 5139 c117e', 5140 1:2, 5141 2:'11' 5142 }, 5143 { 5144 -1:3, 5145 -2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737bf5de 5146 7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620085e5c8 5147 f42ad', 5148 -3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e247e 5149 60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3fe1ea1 5150 d9475', 5151 1:2, 5152 2:'bilbo.baggins@hobbiton.example' 5153 }, 5154 { 5155 -1:1, 5156 -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b4d91 5157 d6280', 5158 -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e03bf 5159 822bb', 5160 1:2, 5161 2:'peregrin.took@tuckborough.example' 5162 } 5163 ] 5165 C.7.2. Private Keys 5167 This is an example of a COSE Key set. This example includes the 5168 private keys for all of the previous examples. 5170 In order the keys are: 5172 o An EC key with a kid of "meriadoc.brandybuck@buckland.example" 5174 o A shared-secret key with a kid of "our-secret" 5176 o An EC key with a kid of "peregrin.took@tuckborough.example" 5178 o A shared-secret key with a kid of "018c0ae5-4d9b-471b- 5179 bfd6-eef314bc7037" 5181 o An EC key with a kid of "bilbo.baggins@hobbiton.example" 5183 o An EC key with a kid of "11" 5185 Size of binary file is 816 bytes 5187 [ 5188 { 5189 1:2, 5190 2:'meriadoc.brandybuck@buckland.example', 5191 -1:1, 5192 -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0 5193 8551d', 5194 -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008 5195 4d19c', 5196 -4:h'aff907c99f9ad3aae6c4cdf21122bce2bd68b5283e6907154ad911840fa 5197 208cf' 5198 }, 5199 { 5200 1:2, 5201 2:'11', 5202 -1:1, 5203 -2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a 5204 09eff', 5205 -3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbf 5206 c117e', 5207 -4:h'57c92077664146e876760c9520d054aa93c3afb04e306705db609030850 5208 7b4d3' 5209 }, 5210 { 5211 1:2, 5212 2:'bilbo.baggins@hobbiton.example', 5213 -1:3, 5214 -2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737bf5de 5215 7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620085e5c8 5216 f42ad', 5217 -3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e247e 5218 60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3fe1ea1 5219 d9475', 5220 -4:h'00085138ddabf5ca975f5860f91a08e91d6d5f9a76ad4018766a476680b 5221 55cd339e8ab6c72b5facdb2a2a50ac25bd086647dd3e2e6e99e84ca2c3609fdf177f 5222 eb26d' 5223 }, 5224 { 5225 1:4, 5226 2:'our-secret', 5227 -1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dcea6c4 5228 27188' 5229 }, 5230 { 5231 1:2, 5232 -1:1, 5233 2:'peregrin.took@tuckborough.example', 5234 -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b4d91 5235 d6280', 5236 -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e03bf 5237 822bb', 5238 -4:h'02d1f7e6f26c43d4868d87ceb2353161740aacf1f7163647984b522a848 5239 df1c3' 5240 }, 5241 { 5242 1:4, 5243 2:'our-secret2', 5244 -1:h'849b5786457c1491be3a76dcea6c4271' 5245 }, 5246 { 5247 1:4, 5248 2:'018c0ae5-4d9b-471b-bfd6-eef314bc7037', 5249 -1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dcea6c4 5250 27188' 5251 } 5252 ] 5254 Acknowledgments 5256 This document is a product of the COSE working group of the IETF. 5258 The following individuals are to blame for getting me started on this 5259 project in the first place: Richard Barnes, Matt Miller, and Martin 5260 Thomson. 5262 The initial version of the draft was based to some degree on the 5263 outputs of the JOSE and S/MIME working groups. 5265 The following individuals provided input into the final form of the 5266 document: Carsten Bormann, John Bradley, Brain Campbell, Michael B. 5268 Jones, Ilari Liusvaara, Francesca Palombini, Goran Selander, and 5269 Ludwig Seitz. 5271 Author's Address 5273 Jim Schaad 5274 August Cellars 5276 Email: ietf@augustcellars.com