idnits 2.17.1 draft-ietf-cose-msg-14.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 724 has weird spacing: '...otected as de...' == Line 726 has weird spacing: '...otected as de...' == Line 728 has weird spacing: '...payload conta...' == Line 744 has weird spacing: '...natures is an...' == Line 759 has weird spacing: '...otected as de...' == (28 more instances...) -- The document date (June 23, 2016) is 2857 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-08 == Outdated reference: A later version (-08) exists of draft-irtf-cfrg-eddsa-05 -- 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 6982 (Obsoleted by RFC 7942) -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) Summary: 7 errors (**), 0 flaws (~~), 9 warnings (==), 11 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 June 23, 2016 5 Expires: December 25, 2016 7 CBOR Object Signing and Encryption (COSE) 8 draft-ietf-cose-msg-14 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 the basic security services defined for this data 15 format. This document defines the CBOR Object Signing and Encyption 16 (COSE) specification. This specification describes how to create and 17 process signature, message authentication codes and encryption using 18 CBOR for serialization. This specifiction additionally specifies how 19 to representat 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 December 25, 2016. 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 . . . . . . . . . . . . . . . . . . 7 69 2. Basic COSE Structure . . . . . . . . . . . . . . . . . . . . 8 70 3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 10 71 3.1. Common COSE Headers Parameters . . . . . . . . . . . . . 11 72 4. Signing Objects . . . . . . . . . . . . . . . . . . . . . . . 15 73 4.1. Signing with One or More Signers . . . . . . . . . . . . 15 74 4.2. Signing with One Signer . . . . . . . . . . . . . . . . . 17 75 4.3. Externally Supplied Data . . . . . . . . . . . . . . . . 18 76 4.4. Signing and Verification Process . . . . . . . . . . . . 19 77 4.5. Computing Counter Signatures . . . . . . . . . . . . . . 20 78 5. Encryption Objects . . . . . . . . . . . . . . . . . . . . . 21 79 5.1. Enveloped COSE Structure . . . . . . . . . . . . . . . . 21 80 5.1.1. Recipient Algorithm Classes . . . . . . . . . . . . . 23 81 5.2. Single Recipient Encrypted . . . . . . . . . . . . . . . 24 82 5.3. Encryption Algorithm for AEAD algorithms . . . . . . . . 24 83 5.4. Encryption algorithm for AE algorithms . . . . . . . . . 26 84 6. MAC Objects . . . . . . . . . . . . . . . . . . . . . . . . . 28 85 6.1. MACed Message with Recipients . . . . . . . . . . . . . . 28 86 6.2. MACed Messages with Implicit Key . . . . . . . . . . . . 29 87 6.3. How to compute and verify a MAC . . . . . . . . . . . . . 30 88 7. Key Objects . . . . . . . . . . . . . . . . . . . . . . . . . 31 89 7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 32 90 8. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 35 91 8.1. ECDSA . . . . . . . . . . . . . . . . . . . . . . . . . . 36 92 8.1.1. Security Considerations . . . . . . . . . . . . . . . 37 93 8.2. Edwards-curve Digital Signature Algorithms (EdDSA) . . . 38 94 8.2.1. Security Considerations . . . . . . . . . . . . . . . 39 95 9. Message Authentication (MAC) Algorithms . . . . . . . . . . . 39 96 9.1. Hash-based Message Authentication Codes (HMAC) . . . . . 40 97 9.1.1. Security Considerations . . . . . . . . . . . . . . . 41 98 9.2. AES Message Authentication Code (AES-CBC-MAC) . . . . . . 41 99 9.2.1. Security Considerations . . . . . . . . . . . . . . . 42 100 10. Content Encryption Algorithms . . . . . . . . . . . . . . . . 43 101 10.1. AES GCM . . . . . . . . . . . . . . . . . . . . . . . . 43 102 10.1.1. Security Considerations . . . . . . . . . . . . . . 44 103 10.2. AES CCM . . . . . . . . . . . . . . . . . . . . . . . . 45 104 10.2.1. Security Considerations . . . . . . . . . . . . . . 48 105 10.3. ChaCha20 and Poly1305 . . . . . . . . . . . . . . . . . 48 106 10.3.1. Security Considerations . . . . . . . . . . . . . . 49 107 11. Key Derivation Functions (KDF) . . . . . . . . . . . . . . . 49 108 11.1. HMAC-based Extract-and-Expand Key Derivation Function 109 (HKDF) . . . . . . . . . . . . . . . . . . . . . . . . . 50 110 11.2. Context Information Structure . . . . . . . . . . . . . 52 111 12. Recipient Algorithm Classes . . . . . . . . . . . . . . . . . 55 112 12.1. Direct Encryption . . . . . . . . . . . . . . . . . . . 56 113 12.1.1. Direct Key . . . . . . . . . . . . . . . . . . . . . 56 114 12.1.2. Direct Key with KDF . . . . . . . . . . . . . . . . 57 115 12.2. Key Wrapping . . . . . . . . . . . . . . . . . . . . . . 58 116 12.2.1. AES Key Wrapping . . . . . . . . . . . . . . . . . . 59 117 12.3. Key Encryption . . . . . . . . . . . . . . . . . . . . . 60 118 12.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 60 119 12.4.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 61 120 12.4.2. Security Considerations . . . . . . . . . . . . . . 64 121 12.5. Key Agreement with KDF . . . . . . . . . . . . . . . . . 65 122 12.5.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 65 123 13. Key Object Parameters . . . . . . . . . . . . . . . . . . . . 67 124 13.1. Elliptic Curve Keys . . . . . . . . . . . . . . . . . . 67 125 13.1.1. Double Coordinate Curves . . . . . . . . . . . . . . 68 126 13.2. Octet Key Pair . . . . . . . . . . . . . . . . . . . . . 69 127 13.3. Symmetric Keys . . . . . . . . . . . . . . . . . . . . . 70 128 14. CBOR Encoder Restrictions . . . . . . . . . . . . . . . . . . 71 129 15. Application Profiling Considerations . . . . . . . . . . . . 71 130 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 73 131 16.1. CBOR Tag assignment . . . . . . . . . . . . . . . . . . 73 132 16.2. COSE Header Parameters Registry . . . . . . . . . . . . 73 133 16.3. COSE Header Algorithm Labels Registry . . . . . . . . . 74 134 16.4. COSE Algorithms Registry . . . . . . . . . . . . . . . . 74 135 16.5. COSE Key Common Parameters Registry . . . . . . . . . . 75 136 16.6. COSE Key Type Parameters Registry . . . . . . . . . . . 76 137 16.7. COSE Elliptic Curve Parameters Registry . . . . . . . . 77 138 16.8. Media Type Registrations . . . . . . . . . . . . . . . . 77 139 16.8.1. COSE Security Message . . . . . . . . . . . . . . . 77 140 16.8.2. COSE Key media type . . . . . . . . . . . . . . . . 78 141 16.9. CoAP Content Format Registrations . . . . . . . . . . . 80 142 16.10. Expert Review Instructions . . . . . . . . . . . . . . . 81 143 17. Implementation Status . . . . . . . . . . . . . . . . . . . . 82 144 17.1. Author's Versions . . . . . . . . . . . . . . . . . . . 83 145 17.2. COSE Testing Library . . . . . . . . . . . . . . . . . . 83 146 18. Security Considerations . . . . . . . . . . . . . . . . . . . 84 147 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 86 148 19.1. Normative References . . . . . . . . . . . . . . . . . . 86 149 19.2. Informative References . . . . . . . . . . . . . . . . . 87 150 Appendix A. Making Mandatory Algorithm Header Optional . . . . . 89 151 A.1. Algorithm Identification . . . . . . . . . . . . . . . . 90 152 A.2. Counter Signature Without Headers . . . . . . . . . . . . 93 153 Appendix B. Two Layers of Recipient Information . . . . . . . . 93 154 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 95 155 C.1. Examples of Signed Message . . . . . . . . . . . . . . . 96 156 C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 96 157 C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 97 158 C.1.3. Counter Signature . . . . . . . . . . . . . . . . . . 98 159 C.1.4. Signature w/ Criticality . . . . . . . . . . . . . . 99 160 C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 100 161 C.2.1. Single ECDSA signature . . . . . . . . . . . . . . . 100 162 C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 101 163 C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 101 164 C.3.2. Direct plus Key Derivation . . . . . . . . . . . . . 102 165 C.3.3. Counter Signature on Encrypted Content . . . . . . . 103 166 C.3.4. Encrypted Content with External Data . . . . . . . . 105 167 C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 105 168 C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 105 169 C.4.2. Encrypted Message w/ a Partial IV . . . . . . . . . . 106 170 C.5. Examples of MACed messages . . . . . . . . . . . . . . . 106 171 C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 106 172 C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 107 173 C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 108 174 C.5.4. Multi-recipient MACed message . . . . . . . . . . . . 109 175 C.6. Examples of MAC0 messages . . . . . . . . . . . . . . . . 110 176 C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 110 177 C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 111 178 C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 111 179 C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 112 180 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 114 181 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 115 183 1. Introduction 185 There has been an increased focus on the small, constrained devices 186 that make up the Internet of Things (IoT). One of the standards that 187 has come out of this process is the Concise Binary Object 188 Representation (CBOR) [RFC7049]. CBOR extended the data model of the 189 JavaScript Object Notation (JSON) [RFC7159] by allowing for binary 190 data, among other changes. CBOR is being adopted by several of the 191 IETF working groups dealing with the IoT world as their encoding of 192 data structures. CBOR was designed specifically to be both small in 193 terms of messages transport and implementation size, as well having a 194 schema free decoder. A need exists to provide message security 195 services for IoT and using CBOR as the message encoding format makes 196 sense. 198 The JOSE working group produced a set of documents 199 [RFC7515][RFC7516][RFC7517][RFC7518] using JSON that specified how to 200 process encryption, signatures and message authentication (MAC) 201 operations, and how to encode keys using JSON. This document defines 202 the CBOR Object Encryption and Signing (COSE) standard which does the 203 same thing for the CBOR encoding format. While there is a strong 204 attempt to keep the flavor of the original JOSE documents, two 205 considerations are taken into account: 207 o CBOR has capabilities that are not present in JSON and are 208 appropriate to use. One example of this is the fact that CBOR has 209 a method of encoding binary directly without first converting it 210 into a base64 encoded string. 212 o COSE is not a direct copy of the JOSE specification. In the 213 process of creating COSE, decisions that were made for JOSE were 214 re-examined. In many cases different results were decided on as 215 the criteria was not always the same. 217 1.1. Design changes from JOSE 219 o Define a single top message structure so that encrypted, signed 220 and MACed messages can easily identified and still have a 221 consistent view. 223 o Signed messages separate the concept of protected and unprotected 224 parameters that are for the content and the signature. 226 o MACed messages are separated from signed messages. 228 o MACed messages have the ability to use the same set of recipient 229 algorithms as enveloped messages for obtaining the MAC 230 authentication key. 232 o Use binary encodings for binary data rather than base64url 233 encodings. 235 o Combine the authentication tag for encryption algorithms with the 236 cipher text. 238 o The set of cryptographic algorithms has been expanded in some 239 directions, and trimmed in others. 241 1.2. Requirements Terminology 243 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 244 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 245 "OPTIONAL" in this document are to be interpreted as described in 246 [RFC2119]. 248 When the words appear in lower case, their natural language meaning 249 is used. 251 1.3. CBOR Grammar 253 There currently is no standard CBOR grammar available for use by 254 specifications. We therefore describe the CBOR structures in prose. 256 The document was developed by first working on the grammar and then 257 developing the prose to go with it. An artifact of this is that the 258 prose was written using the primitive type strings defined by CBOR 259 Data Definition Language (CDDL) [I-D.greevenbosch-appsawg-cbor-cddl]. 260 In this specification, the following primitive types are used: 262 any - non-specific value that permits all CBOR values to be placed 263 here. 265 bool - a boolean value (true: major type 7, value 21; false: major 266 type 7, value 20). 268 bstr - byte string (major type 2). 270 int - an unsigned integer or a negative integer. 272 nil - a null value (major type 7, value 22). 274 nint - a negative integer (major type 1). 276 tstr - a UTF-8 text string (major type 3). 278 uint - an unsigned integer (major type 0). 280 As well as the prose description, a version of a CBOR grammar is 281 presented in CDDL. Since CDDL has not been published as an RFC, this 282 grammar may not work with the final version of CDDL. The CDDL 283 grammar is informational, the prose description is normative. 285 The collected CDDL can be extracted from the XML version of this 286 document via the following XPath expression below. (Depending on the 287 XPath evaluator one is using, it may be necessary to deal with > 288 as an entity.) 290 //artwork[@type='CDDL']/text() 292 CDDL expects the initial non-terminal symbol to be the first symbol 293 in the file. For this, reason the first fragment of CDDL is 294 presented here. 296 start = COSE_Messages / COSE_Key / COSE_KeySet / Internal_Types 298 ; This is defined to make the tool quieter: 299 Internal_Types = Sig_structure / Enc_structure / MAC_structure / 300 COSE_KDF_Context 302 The non-terminal Internal_Types is defined for dealing with the 303 automated validation tools used during the writing of this document. 304 It references those non-terminals that are used for security 305 computations, but are not emitted for transport. 307 1.4. CBOR Related Terminology 309 In JSON, maps are called objects and only have one kind of map key: a 310 string. In COSE, we use strings, negative integers and unsigned 311 integers as map keys. The integers are used for compactness of 312 encoding and easy comparison. Since the word "key" is mainly used in 313 its other meaning, as a cryptographic key, we use the term "label" 314 for this usage as a map key. 316 The presence of a label in a COSE map which is not a string or an 317 integer is an error. Applications can either fail processing or 318 process messages with incorrect labels, however they MUST NOT create 319 messages with incorrect labels. 321 A CDDL grammar fragment is defined that defines the non-terminals 322 'label', as in the previous paragraph and 'values', which permits any 323 value to be used. 325 label = int / tstr 326 values = any 328 1.5. Document Terminology 330 In this document, we use the following terminology: 332 Byte is a synonym for octet. 334 Constrained Application Protocol (CoAP) is a specialized web transfer 335 protocol for use in constrained systems. It is defined in [RFC7252]. 337 Authenticated Encryption (AE) algorithms are those encryption 338 algorithms which provide an authentication check of the contents 339 algorithm with the encryption service. 341 Authenticated Encryption with Authenticated Data (AEAD) algorithms 342 provide the same content authentication service as AE algorithms, but 343 additionally provide for authentication of non-encrypted data as 344 well. 346 2. Basic COSE Structure 348 The COSE object structure is designed so that there can be a large 349 amount of common code when parsing and processing the different 350 security messages. All of the message structures are built on the 351 CBOR array type. The first three elements of the array always 352 contain the same information: 354 1. The set of protected header parameters wrapped in a bstr. 356 2. The set of unprotected header parameters as a map. 358 3. The content of the message. The content is either the plain text 359 or the cipher text as appropriate. The content may be detached, 360 but the location is still used. The content is wrapped in a bstr 361 when present and is a nil value when detached. 363 Elements after this point are dependent on the specific message type. 365 Identification of which type of message has been presented is done by 366 the following method: 368 1. The specific message type is known from the context. This may be 369 defined by a marker in the containing structure or by 370 restrictions specified by the application protocol. 372 2. The message type is identified by a CBOR tag. Messages with a 373 CBOR tag are known in this specification as tagged messages, 374 while those without the CBOR tag are known as untagged messages. 375 This document defines a CBOR tag for each of the message 376 structures. These tags can be found in Table 1. 378 3. When a COSE object is carried in a media type of application/ 379 cose, the optional parameter 'cose-type' can be used to identify 380 the embedded object. The parameter is OPTIONAL if the tagged 381 version of the structure is used. The parameter is REQUIRED if 382 the untagged version of the structure is used. The value to use 383 with the parameter for each of the structures can be found in 384 Table 1. 386 4. When a COSE object is carried as a CoAP payload, the CoAP 387 Content-Format Option can be used to identify the message 388 content. The CoAP Content-Format values can be found in 389 Table 26. The CBOR tag for the message structure is not required 390 as each security message is uniquely identified. 392 +-------+---------------+---------------+---------------------------+ 393 | CBOR | cose-type | Data Item | Semantics | 394 | Tag | | | | 395 +-------+---------------+---------------+---------------------------+ 396 | TBD1 | cose-sign | COSE_Sign | COSE Signed Data Object | 397 | | | | | 398 | TBD7 | cose-sign1 | COSE_Sign1 | COSE Single Signer Data | 399 | | | | Object | 400 | | | | | 401 | TBD2 | cose-encrypt | COSE_Encrypt | COSE Encrypted Data | 402 | | | | Object | 403 | | | | | 404 | TBD3 | cose-encrypt1 | COSE_Encrypt0 | COSE Single Recipient | 405 | | | | Encrypted Data Object | 406 | | | | | 407 | TBD4 | cose-mac | COSE_Mac | COSE Mac-ed Data Object | 408 | | | | | 409 | TBD6 | cose-mac0 | COSE_Mac0 | COSE Mac w/o Recipients | 410 | | | | Object | 411 +-------+---------------+---------------+---------------------------+ 413 Table 1: COSE Message Identification 415 The following CDDL fragment identifies all of the top messages 416 defined in this document. Separate non-terminals are defined for the 417 tagged and the untagged versions of the messages. 419 COSE_Messages = COSE_Untagged_Message / COSE_Tagged_Message 421 COSE_Untagged_Message = COSE_Sign / COSE_Sign1 / 422 COSE_Encrypt / COSE_Encrypt0 / 423 COSE_Mac / COSE_Mac0 425 COSE_Tagged_Message = COSE_Sign_Tagged / COSE_Sign1_Tagged / 426 COSE_Encrypt_Tagged / COSE_Encrypt0_Tagged / 427 COSE_Mac_Tagged / COSE_Mac0_Tagged 429 3. Header Parameters 431 The structure of COSE has been designed to have two buckets of 432 information that are not considered to be part of the payload itself, 433 but are used for holding information about content, algorithms, keys, 434 or evaluation hints for the processing of the layer. These two 435 buckets are available for use in all of the structures except for 436 keys. While these buckets are present, they may not all be usable in 437 all instances. For example, while the protected bucket is defined as 438 part of the recipient structure, some of the algorithms used for 439 recipient structures do not provide for authenticated data. If this 440 is the case, the protected bucket is left empty. 442 Both buckets are implemented as CBOR maps. The map key is a 'label' 443 (Section 1.4). The value portion is dependent on the definition for 444 the label. Both maps use the same set of label/value pairs. The 445 integer and string values for labels has been divided into several 446 sections with a standard range, a private range, and a range that is 447 dependent on the algorithm selected. The defined labels can be found 448 in the "COSE Header Parameters" IANA registry (Section 16.2). 450 Two buckets are provided for each layer: 452 protected: Contains parameters about the current layer that are to 453 be cryptographically protected. This bucket MUST be empty if it 454 is not going to be included in a cryptographic computation. This 455 bucket is encoded in the message as a binary object. This value 456 is obtained by CBOR encoding the protected map and wrapping it in 457 a bstr object. Senders SHOULD encode an empty protected map as a 458 zero length binary object (i.e., the byte string h'a0'). This 459 encoding is used because it is both shorter and the version used 460 in the serialization structures for cryptographic computation. 461 Recipients MUST accept both a zero length binary value and a zero 462 length map encoded in the binary value. The wrapping allows for 463 the encoding of the protected map to be transported with a greater 464 chance that it will not be altered in transit. (Badly behaved 465 intermediates could decode and re-encode, but this will result in 466 a failure to verify unless the re-encoded byte string is identical 467 to the decoded byte string.) This avoids the problem of all 468 parties needing to be able to do a common canonical encoding. 470 unprotected: Contains parameters about the current layer that are 471 not cryptographically protected. 473 Only parameters that deal with the current layer are to be placed at 474 that layer. As an example of this, the parameter 'content type' 475 describes the content of the message being carried in the message. 476 As such, this parameter is placed only in the content layer and is 477 not placed in the recipient or signature layers. In principle, one 478 should be able to process any given layer without reference to any 479 other layer. (With the exception of the COSE_Sign structure, the 480 only data that needs to cross layers is the cryptographic key.) 482 The buckets are present in all of the security objects defined in 483 this document. The fields in order are the 'protected' bucket (as a 484 CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map' 485 type). The presence of both buckets is required. The parameters 486 that go into the buckets come from the IANA "COSE Header Parameters" 487 registry (Section 16.2). Some common parameters are defined in the 488 next section, but a number of parameters are defined throughout this 489 document. 491 Labels in each of the maps MUST be unique. When processing messages, 492 if a label appears multiple times, the message MUST be rejected as 493 malformed. Applications SHOULD perform the same checks that the same 494 label does not occur in both the protected and unprotected headers. 495 If the message is not rejected as malformed, attributes MUST be 496 obtained from the protected bucket before they are obtained from the 497 unprotected bucket. 499 The following CDDL fragment represents the two header buckets. A 500 group Headers is defined in CDDL that represents the two buckets in 501 which attributes are placed. This group is used to provide these two 502 fields consistently in all locations. A type is also defined which 503 represents the map of common headers. 505 Headers = ( 506 protected : empty_or_serialized_map, 507 unprotected : header_map 508 ) 510 header_map = { 511 Generic_Headers, 512 * label => values 513 } 515 empty_or_serialized_map = bstr .cbor header_map / bstr .size 0 517 3.1. Common COSE Headers Parameters 519 This section defines a set of common header parameters. A summary of 520 these parameters can be found in Table 2. This table should be 521 consulted to determine the value of label, and the type of the value. 523 The set of header parameters defined in this section are: 525 alg This parameter is used to indicate the algorithm used for the 526 security processing. This parameter MUST be present at each layer 527 of a signed, encrypted or authenticated message except the 528 COSE_Sign structure. When the algorithm supports authenticating 529 associated data, this parameter MUST be in the protected header 530 bucket. The value is taken from the "COSE Algorithms" Registry 531 (see Section 16.4). 533 crit The parameter is used to indicate which protected header labels 534 an application that is processing a message is required to 535 understand. Parameters defined in this document do not need to be 536 included as they should be understood by all implementations. 537 When present, this parameter MUST be placed in the protected 538 header bucket. The array MUST have at least one value in it. 539 Not all labels need to be included in the 'crit' parameter. The 540 rules for deciding which header labels are placed in the array 541 are: 543 * Integer labels in the range of 0 to 8 SHOULD be omitted. 545 * Integer labels in the range -1 to -255 can be omitted as they 546 are algorithm dependent. If an application can correctly 547 process an algorithm, it can be assumed that it will correctly 548 process all of the common parameters associated with that 549 algorithm. (The algorithm range is -1 to -65536; the higher 550 end is for more optional algorithm specific items.) 552 * Labels for parameters required for an application MAY be 553 omitted. Applications should have a statement if the label can 554 be omitted. 556 The header parameter values indicated by 'crit' can be processed 557 by either the security library code or by an application using a 558 security library; the only requirement is that the parameter is 559 processed. If the 'crit' value list includes a value for which 560 the parameter is not in the protected bucket, this is a fatal 561 error in processing the message. 563 content type This parameter is used to indicate the content type of 564 the data in the payload or cipher text fields. Integers are from 565 the "CoAP Content-Formats" IANA registry table. Text values 566 following the syntax of Content-Type defined in Section 5.1 of 567 [RFC2045] omitting the prefix string "Content-Type:". Leading and 568 trailing whitespace is also omitted. Textual content values along 569 with parameters and subparameters can be located using the IANA 570 "Media Types" registry. Applications SHOULD provide this 571 parameter if the content structure is potentially ambiguous. 573 kid This parameter identifies one piece of data that can be used as 574 input to find the needed cryptographic key. The value of this 575 parameter can be matched against the 'kid' member in a COSE_Key 576 structure. Other methods of key distribution can define an 577 equivalent field to be matched. Applications MUST NOT assume that 578 'kid' values are unique. There may be more than one key with the 579 same 'kid' value, so all of the keys may need to be checked to 580 find the correct one. The internal structure of 'kid' values is 581 not defined and cannot be relied on by applications. Key 582 identifier values are hints about which key to use. They are not 583 directly a security critical field. For this reason, they can be 584 placed in the unprotected headers bucket. 586 Initialization Vector This parameter holds the Initialization Vector 587 (IV) value. For some symmetric encryption algorithms this may be 588 referred to as a nonce. As the IV is authenticated by the 589 encryption process, it can be placed in the unprotected header 590 bucket. 592 Partial Initialization Vector This parameter holds a part of the IV 593 value. When using the COSE_Encrypt0 structure, a portion of the 594 IV can be part of the context associated with the key. This field 595 is used to carry a value that causes the IV to be changed for each 596 message. As the IV is authenticated by the encryption process, 597 this value can be placed in the unprotected header bucket. The 598 'Initialization Vector' and 'Partial Initialization Vector' 599 parameters MUST NOT both be present in the same security layer. 600 The message IV is generated by the following steps: 602 1. Left pad the partial IV with zeros to the length of IV. 604 2. XOR the padded partial IV with the context IV. 606 counter signature This parameter holds one or more counter signature 607 values. Counter signatures provide a method of having a second 608 party sign some data. The counter signature can occur as an 609 unprotected attribute in any of the following structures: 610 COSE_Sign, COSE_Sign1, COSE_Signature, COSE_Encrypt, 611 COSE_recipient, COSE_Encrypt0, COSE_Mac and COSE_Mac0. These 612 structures all have the same beginning elements so that a 613 consistent calculation of the counter signature can be computed. 614 Details on computing counter signatures are found in Section 4.5. 616 +-----------+-------+----------------+-------------+----------------+ 617 | name | label | value type | value | description | 618 | | | | registry | | 619 +-----------+-------+----------------+-------------+----------------+ 620 | alg | 1 | int / tstr | COSE | Cryptographic | 621 | | | | Algorithms | algorithm to | 622 | | | | registry | use | 623 | | | | | | 624 | crit | 2 | [+ label] | COSE Header | Critical | 625 | | | | Labels | headers to be | 626 | | | | registry | understood | 627 | | | | | | 628 | content | 3 | tstr / uint | CoAP | Content type | 629 | type | | | Content - | of the payload | 630 | | | | Formats or | | 631 | | | | Media Types | | 632 | | | | registry | | 633 | | | | | | 634 | kid | 4 | bstr | | key identifier | 635 | | | | | | 636 | IV | 5 | bstr | | Full | 637 | | | | | Initialization | 638 | | | | | Vector | 639 | | | | | | 640 | Partial | 6 | bstr | | Partial | 641 | IV | | | | Initialization | 642 | | | | | Vector | 643 | | | | | | 644 | counter | 7 | COSE_Signature | | CBOR encoded | 645 | signature | | / [+ | | signature | 646 | | | COSE_Signature | | structure | 647 | | | ] | | | 648 +-----------+-------+----------------+-------------+----------------+ 650 Table 2: Common Header Parameters 652 The CDDL fragment that represents the set of headers defined in this 653 section is given below. Each of the headers is tagged as optional 654 because they do not need to be in every map; headers required in 655 specific maps are discussed above. 657 Generic_Headers = ( 658 ? 1 => int / tstr, ; algorithm identifier 659 ? 2 => [+label], ; criticality 660 ? 3 => tstr / int, ; content type 661 ? 4 => bstr, ; key identifier 662 ? 5 => bstr, ; IV 663 ? 6 => bstr, ; Partial IV 664 ? 7 => COSE_Signature / [+COSE_Signature] ; Counter signature 665 ) 667 4. Signing Objects 669 COSE supports two different signature structures. COSE_Sign allows 670 for one or more signers to be applied to a single content. 671 COSE_Sign1 is restricted to a single signer. The structures cannot 672 be converted between each other; as the signature computation 673 includes a parameter identifying which structure is being used, the 674 converted structure will fail signature validation. 676 4.1. Signing with One or More Signers 678 The COSE_Sign structure allows for one or more signatures to be 679 applied to a message payload. There are provisions for parameters 680 about the content and parameters about the signature to be carried 681 along with the signature itself. These parameters may be 682 authenticated by the signature, or just present. An example of a 683 parameter about the content is the content type. Examples of 684 parameters about the signature would be the algorithm and key used to 685 create the signature and counter signatures. 687 When more than one signature is present, the successful validation of 688 one signature associated with a given signer is usually treated as a 689 successful signature by that signer. However, there are some 690 application environments where other rules are needed. An 691 application that employs a rule other than one valid signature for 692 each signer must specify those rules. Also, where simple matching of 693 the signer identifier is not sufficient to determine whether the 694 signatures were generated by the same signer, the application 695 specification must describe how to determine which signatures were 696 generated by the same signer. Support of different communities of 697 recipients is the primary reason that signers choose to include more 698 than one signature. For example, the COSE_Sign structure might 699 include signatures generated with the Edwards Digital Signature 700 Algorithm (EdDSA) signature algorithm and with the Elliptic Curve 701 Digital Signature Algorithm (ECDSA) signature algorithm. This allows 702 recipients to verify the signature associated with one algorithm or 703 the other. (The original source of this text is [RFC5652].) More 704 detailed information on multiple signature evaluation can be found in 705 [RFC5752]. 707 The signature structure can be encoded either as tagged or untagged 708 depending on the context it will be used in. A tagged COSE_Sign 709 structure is identified by the CBOR tag TBD1. The CDDL fragment that 710 represents this is: 712 COSE_Sign_Tagged = #6.991(COSE_Sign) ; Replace 991 with TBD1 714 A COSE Signed Message is defined in two parts. The CBOR object that 715 carries the body and information about the body is called the 716 COSE_Sign structure. The CBOR object that carries the signature and 717 information about the signature is called the COSE_Signature 718 structure. Examples of COSE Signed Messages can be found in 719 Appendix C.1. 721 The COSE_Sign structure is a CBOR array. The fields of the array in 722 order are: 724 protected as described in Section 3. 726 unprotected as described in Section 3. 728 payload contains the serialized content to be signed. If the 729 payload is not present in the message, the application is required 730 to supply the payload separately. The payload is wrapped in a 731 bstr to ensure that it is transported without changes. If the 732 payload is transported separately ("detached content"), then a nil 733 CBOR object is placed in this location and it is the 734 responsibility of the application to ensure that it will be 735 transported without changes. 737 Note: When a signature with message recovery algorithm is used 738 (Section 8), the maximum number of bytes that can be recovered is 739 the length of the payload. The size of the payload is reduced by 740 the number of bytes that will be recovered. If all of the bytes 741 of the payload are consumed, then the payload is encoded as a zero 742 length binary string rather than as being absent. 744 signatures is an array of signatures. Each signature is represented 745 as a COSE_Signature structure. 747 The CDDL fragment that represents the above text for COSE_Sign 748 follows. 750 COSE_Sign = [ 751 Headers, 752 payload : bstr / nil, 753 signatures : [+ COSE_Signature] 754 ] 756 The COSE_Signature structure is a CBOR array. The fields of the 757 array in order are: 759 protected as described in Section 3. 761 unprotected as described in Section 3. 763 signature contains the computed signature value. The type of the 764 field is a bstr. 766 The CDDL fragment that represents the above text for COSE_Signature 767 follows. 769 COSE_Signature = [ 770 Headers, 771 signature : bstr 772 ] 774 4.2. Signing with One Signer 776 The COSE_Sign1 signature structure is used when only one signer is 777 going to be placed on a message. The parameters dealing with the 778 content and the signature are placed in the same pair of buckets 779 rather than having the separation of COSE_Sign. 781 The structure can be encoded either tagged or untagged depending on 782 the context it will be used in. A tagged COSE_Sign1 structure is 783 identified by the CBOR tag TBD7. The CDDL fragment that represents 784 this is: 786 COSE_Sign1_Tagged = #6.997(COSE_Sign1) ; Replace 997 with TBD7 788 The CBOR object that carries the body, the signature, and the 789 information about the body and signature is called the COSE_Sign1 790 structure. Examples of COSE_Sign1 messages can be found in 791 Appendix C.2. 793 The COSE_Sign1 structure is a CBOR array. The fields of the array in 794 order are: 796 protected as described in Section 3. 798 unprotected as described in Section 3. 800 payload as described in Section 4.1. 802 signature contains the computed signature value. The type of the 803 field is a bstr. 805 The CDDL fragment that represents the above text for COSE_Sign1 806 follows. 808 COSE_Sign1 = [ 809 Headers, 810 payload : bstr / nil, 811 signature : bstr 812 ] 814 4.3. Externally Supplied Data 816 One of the features supplied in the COSE document is the ability for 817 applications to provide additional data to be authenticated as part 818 of the security, but that is not carried as part of the COSE object. 819 The primary reason for supporting this can be seen by looking at the 820 CoAP message structure [RFC7252], where the facility exists for 821 options to be carried before the payload. Examples of data that can 822 be placed in this location would be the CoAP code, CoAP token, or 823 CoAP options. If the data is in the header section, then it is 824 available for routers to help in performing the replay detection and 825 prevention. However, it may also be desired to protect these values 826 so that if they are modified in transit, it can be detected. 828 This document describes the process for using a byte array of 829 externally supplied authenticated data; however, the method of 830 constructing the byte array is a function of the application. 831 Applications that use this feature need to define how the externally 832 supplied authenticated data is to be constructed. Such a 833 construction needs to take into account the following issues: 835 o If multiple items are included, care needs to be taken that data 836 cannot bleed between the items. This is usually addressed by 837 making fields fixed width and/or encoding the length of the field. 838 Using options from CoAP [RFC7252] as an example, these fields use 839 a TLV structure so they can be concatenated without any problems. 841 o If multiple items are included, an order for the items needs to be 842 defined. Using options from CoAP as an example, an application 843 could state that the fields are to be ordered by the option 844 number. 846 o Applications need to ensure that the byte stream is going to be 847 the same on both sides. Using options from CoAP might give a 848 problem if the same relative numbering is kept. An intermediate 849 node could insert or remove an option, changing how the relative 850 number is done. An application would need to specify that the 851 relative number must be re-encoded to be relative only to the 852 options that are in the external data. 854 4.4. Signing and Verification Process 856 In order to create a signature, a well-defined byte stream is needed. 857 This algorithm takes in the body information (COSE_Sign or 858 COSE_Sign1), the signer information (COSE_Signature), and the 859 application data (External). A CBOR array is used to construct the 860 byte stream. The fields of the array in order are: 862 1. A text string identifying the context of the signature. The 863 context string is: 865 "Signature" for signatures using the COSE_Signature structure. 867 "Signature1" for signatures using the COSE_Sign1 structure. 869 "CounterSignature" for signatures used as counter signature 870 attributes. 872 2. The protected attributes from the body structure encoded in a 873 bstr type. If there are no protected attributes, a bstr of 874 length zero is used. 876 3. The protected attributes from the signer structure encoded in a 877 bstr type. If there are no protected attributes, a bstr of 878 length zero is used. This field is omitted for the COSE_Sign1 879 signature structure. 881 4. The protected attributes from the application encoded in a bstr 882 type. If this field is not supplied, it defaults to a zero 883 length binary string. (See Section 4.3 for application guidance 884 on constructing this field.) 886 5. The payload to be signed encoded in a bstr type. The payload is 887 placed here independent of how it is transported. 889 The CDDL fragment that describes the above text is. 891 Sig_structure = [ 892 context : "Signature" / "Signature1" / "CounterSignature", 893 body_protected : empty_or_serialized_map, 894 ? sign_protected : empty_or_serialized_map, 895 external_aad : bstr, 896 payload : bstr 897 ] 899 How to compute a signature: 901 1. Create a Sig_structure and populate it with the appropriate 902 fields. 904 2. Create the value ToBeSigned by encoding the Sig_structure to a 905 byte string, using the encoding described in Section 14. 907 3. Call the signature creation algorithm passing in K (the key to 908 sign with), alg (the algorithm to sign with), and ToBeSigned (the 909 value to sign). 911 4. Place the resulting signature value in the 'signature' field of 912 the array. 914 How to verify a signature: 916 1. Create a Sig_structure object and populate it with the 917 appropriate fields. 919 2. Create the value ToBeSigned by encoding the Sig_structure to a 920 byte string, using the encoding described in Section 14. 922 3. Call the signature verification algorithm passing in K (the key 923 to verify with), alg (the algorithm used sign with), ToBeSigned 924 (the value to sign), and sig (the signature to be verified). 926 In addition to performing the signature verification, one must also 927 perform the appropriate checks to ensure that the key is correctly 928 paired with the signing identity and that the signing identity is 929 authorized before performing actions. 931 4.5. Computing Counter Signatures 933 Counter signatures provide a method of having a different signature 934 occur on some piece of content. This is normally used to provide a 935 signature on a signature allowing for a proof that a signature 936 existed at a given time (i.e., a Timestamp). In this document, we 937 allow for counter signatures to exist in a greater number of 938 environments. As an example, it is possible to place a counter 939 signature in the unprotected attributes of a COSE_Encrypt object. 940 This would allow for an intermediary to either verify that the 941 encrypted byte stream has not been modified, without being able to 942 decrypt it, or for the intermediary to assert that an encrypted byte 943 stream either existed at a given time or passed through it in terms 944 of routing (i.e., a proxy signature). 946 An example of a counter signature on a signature can be found in 947 Appendix C.1.3. An example of a counter signature in an encryption 948 object can be found in Appendix C.3.3. 950 The creation and validation of counter signatures over the different 951 items relies on the fact that the structure of the objects have the 952 same structure. The elements are a set of protected attributes, a 953 set of unprotected attributes, and a body, in that order. This means 954 that the Sig_structure can be used in a uniform manner to get the 955 byte stream for processing a signature. If the counter signature is 956 going to be computed over a COSE_Encrypt structure, the 957 body_protected and payload items can be mapped into the Sig_structure 958 in the same manner as from the COSE_Sign structure. 960 It should be noted that only a signature algorithm with appendix (see 961 Section 8) can be used for counter signatures. This is because the 962 body should be able to be processed without having to evaluate the 963 counter signature, and this is not possible for signature schemes 964 with message recovery. 966 5. Encryption Objects 968 COSE supports two different encryption structures. COSE_Encrypt0 is 969 used when a recipient structure is not needed because the key to be 970 used is known implicitly. COSE_Encrypt is used the rest of the time. 971 This includes cases where there are multiple recipients or a 972 recipient algorithm other than direct is used. 974 5.1. Enveloped COSE Structure 976 The enveloped structure allows for one or more recipients of a 977 message. There are provisions for parameters about the content and 978 parameters about the recipient information to be carried in the 979 message. The protected parameters associated with the content are 980 authenticated by the content encryption algorithm. The protected 981 parameters associated with the recipient are authenticated by the 982 recipient algorithm (when the algorithm supports it). Examples of 983 parameters about the content are the type of the content and the 984 content encryption algorithm. Examples of parameters about the 985 recipient are the recipient's key identifier and the recipient's 986 encryption algorithm. 988 The same techniques and structures are used for encrypting both the 989 plain text and the keys used to protect the text. This is different 990 from the approach used by both CMS [RFC5652] and JSON Web Encryption 991 (JWE) [RFC7516] where different structures are used for the content 992 layer and for the recipient layer. Two structures are defined: 993 COSE_Encrypt to hold the encrypted content and COSE_recipient to hold 994 the encrypted keys for recipients. Examples of encrypted messages 995 can be found in Appendix C.3. 997 The COSE_Encrypt structure can be encoded either tagged or untagged 998 depending on the context it will be used in. A tagged COSE_Encrypt 999 structure is identified by the CBOR tag TBD2. The CDDL fragment that 1000 represents this is: 1002 COSE_Encrypt_Tagged = #6.992(COSE_Encrypt) ; Replace 992 with TBD2 1004 The COSE_Encrypt structure is a CBOR array. The fields of the array 1005 in order are: 1007 protected as described in Section 3. 1009 unprotected as described in Section 3. ' 1011 ciphertext contains the cipher text encoded as a bstr. If the 1012 cipher text is to be transported independently of the control 1013 information about the encryption process (i.e., detached content) 1014 then the field is encoded as a nil value. 1016 recipients contains an array of recipient information structures. 1017 The type for the recipient information structure is a 1018 COSE_recipient. 1020 The CDDL fragment that corresponds to the above text is: 1022 COSE_Encrypt = [ 1023 Headers, 1024 ciphertext : bstr / nil, 1025 recipients : [+COSE_recipient] 1026 ] 1028 The COSE_recipient structure is a CBOR array. The fields of the 1029 array in order are: 1031 protected as described in Section 3. 1033 unprotected as described in Section 3. 1035 ciphertext contains the encrypted key encoded as a bstr. If there 1036 is not an encrypted key, then this field is encoded as a nil 1037 value. 1039 recipients contains an array of recipient information structures. 1040 The type for the recipient information structure is a 1041 COSE_recipient. (An example of this can be found in Appendix B.) 1042 If there are no recipient information structures, this element is 1043 absent. 1045 The CDDL fragment that corresponds to the above text for 1046 COSE_recipient is: 1048 COSE_recipient = [ 1049 Headers, 1050 ciphertext : bstr / nil, 1051 ? recipients : [+COSE_recipient] 1052 ] 1054 5.1.1. Recipient Algorithm Classes 1056 An encrypted message consists of an encrypted content and an 1057 encrypted CEK for one or more recipients. The CEK is encrypted for 1058 each recipient, using a key specific to that recipient. The details 1059 of this encryption depend on which class the recipient algorithm 1060 falls into. Specific details on each of the classes can be found in 1061 Section 12. A short summary of the five recipient algorithm classes 1062 is: 1064 direct: The CEK is the same as the identified previously distributed 1065 symmetric key or derived from a previously distributed secret. No 1066 CEK is transported in the message. 1068 symmetric key-encryption keys: The CEK is encrypted using a 1069 previously distributed symmetric KEK. 1071 key agreement: The recipient's public key and a sender's private key 1072 are used to generate a pairwise secret, a KDF is applied to derive 1073 a key, and then the CEK is either the derived key or encrypted by 1074 the derived key. 1076 key transport: The CEK is encrypted with the recipient's public key. 1077 No key transport algorithms are defined in this document. 1079 passwords: The CEK is encrypted in a KEK that is derived from a 1080 password. No password algorithms are defined in this document. 1082 5.2. Single Recipient Encrypted 1084 The COSE_Encrypt0 encrypted structure does not have the ability to 1085 specify recipients of the message. The structure assumes that the 1086 recipient of the object will already know the identity of the key to 1087 be used in order to decrypt the message. If a key needs to be 1088 identified to the recipient, the enveloped structure ought to be 1089 used. 1091 Examples of encrypted messages can be found in Appendix C.3. 1093 The COSE_Encrypt0 structure can be encoded either tagged or untagged 1094 depending on the context it will be used in. A tagged COSE_Encrypt0 1095 structure is identified by the CBOR tag TBD3. The CDDL fragment that 1096 represents this is: 1098 COSE_Encrypt0_Tagged = #6.993(COSE_Encrypt0) ; Replace 993 with TBD3 1100 The COSE_Encrypt structure is a CBOR array. The fields of the array 1101 in order are: 1103 protected as described in Section 3. 1105 unprotected as described in Section 3. 1107 ciphertext as described in Section 5.1. 1109 The CDDL fragment for COSE_Encrypt0 that corresponds to the above 1110 text is: 1112 COSE_Encrypt0 = [ 1113 Headers, 1114 ciphertext : bstr / nil, 1115 ] 1117 5.3. Encryption Algorithm for AEAD algorithms 1119 The encryption algorithm for AEAD algorithms is fairly simple. The 1120 first step is to create a consistent byte stream for the 1121 authenticated data structure. For this purpose, we use a CBOR array. 1122 The fields of the array in order are: 1124 1. A text string identifying the context of the authenticated data 1125 structure. The context string is: 1127 "Encrypt0" for the content encryption of a COSE_Encrypt0 data 1128 structure. 1130 "Encrypt" for the first layer of a COSE_Encrypt data structure 1131 (i.e., for content encryption). 1133 "Enc_Recipient" for a recipient encoding to be placed in an 1134 COSE_Encrypt data structure. 1136 "Mac_Recipient" for a recipient encoding to be placed in a MACed 1137 message structure. 1139 "Rec_Recipient" for a recipient encoding to be placed in a 1140 recipient structure. 1142 2. The protected attributes from the body structure encoded in a 1143 bstr type. If there are no protected attributes, a bstr of 1144 length zero is used. 1146 3. The protected attributes from the application encoded in a bstr 1147 type. If this field is not supplied, it defaults to a zero 1148 length bstr. (See Section 4.3 for application guidance on 1149 constructing this field.) 1151 The CDDL fragment that describes the above text is: 1153 Enc_structure = [ 1154 context : "Encrypt" / "Encrypt0" / "Enc_Recipient" / 1155 "Mac_Recipient" / "Rec_Recipient", 1156 protected : empty_or_serialized_map, 1157 external_aad : bstr 1158 ] 1160 How to encrypt a message: 1162 1. Create an Enc_structure and populate it with the appropriate 1163 fields. 1165 2. Encode the Enc_structure to a byte stream (AAD), using the 1166 encoding described in Section 14. 1168 3. Determine the encryption key (K). This step is dependent on the 1169 class of recipient algorithm being used. For: 1171 No Recipients: The key to be used is determined by the algorithm 1172 and key at the current layer. 1174 Direct and Direct Key Agreement: The key is determined by the 1175 key and algorithm in the recipient structure. The encryption 1176 algorithm and size of the key to be used are inputs into the 1177 KDF used for the recipient. (For direct, the KDF can be 1178 thought of as the identity operation.) 1180 Other: The key is randomly generated. 1182 4. Call the encryption algorithm with K (the encryption key), P (the 1183 plain text) and AAD. Place the returned cipher text into the 1184 'ciphertext' field of the structure. 1186 5. For recipients of the message, recursively perform the encryption 1187 algorithm for that recipient, using K (the encryption key) as the 1188 plain text. 1190 How to decrypt a message: 1192 1. Create a Enc_structure and populate it with the appropriate 1193 fields. 1195 2. Encode the Enc_structure to a byte stream (AAD), using the 1196 encoding described in Section 14. 1198 3. Determine the decryption key. This step is dependent on the 1199 class of recipient algorithm being used. For: 1201 No Recipients: The key to be used is determined by the algorithm 1202 and key at the current layer. 1204 Direct and Direct Key Agreement: The key is determined by the 1205 key and algorithm in the recipient structure. The encryption 1206 algorithm and size of the key to be used are inputs into the 1207 KDF used for the recipient. (For direct, the KDF can be 1208 thought of as the identity operation.) 1210 Other: The key is determined by decoding and decrypting one of 1211 the recipient structures. 1213 4. Call the decryption algorithm with K (the decryption key to use), 1214 C (the cipher text) and AAD. 1216 5.4. Encryption algorithm for AE algorithms 1218 How to encrypt a message: 1220 1. Verify that the 'protected' field is empty. 1222 2. Verify that there was no external additional authenticated data 1223 supplied for this operation. 1225 3. Determine the encryption key. This step is dependent on the 1226 class of recipient algorithm being used. For: 1228 No Recipients: The key to be used is determined by the algorithm 1229 and key at the current layer. 1231 Direct and Direct Key Agreement: The key is determined by the 1232 key and algorithm in the recipient structure. The encryption 1233 algorithm and size of the key to be used are inputs into the 1234 KDF used for the recipient. (For direct, the KDF can be 1235 thought of as the identity operation.) 1237 Other: The key is randomly generated. 1239 4. Call the encryption algorithm with K (the encryption key to use) 1240 and the P (the plain text). Place the returned cipher text into 1241 the 'ciphertext' field of the structure. 1243 5. For recipients of the message, recursively perform the encryption 1244 algorithm for that recipient, using K (the encryption key) as the 1245 plain text. 1247 How to decrypt a message: 1249 1. Verify that the 'protected' field is empty. 1251 2. Verify that there was no external additional authenticated data 1252 supplied for this operation. 1254 3. Determine the decryption key. This step is dependent on the 1255 class of recipient algorithm being used. For: 1257 No Recipients: The key to be used is determined by the algorithm 1258 and key at the current layer. 1260 Direct and Direct Key Agreement: The key is determined by the 1261 key and algorithm in the recipient structure. The encryption 1262 algorithm and size of the key to be used are inputs into the 1263 KDF used for the recipient. (For direct, the KDF can be 1264 thought of as the identity operation.) 1266 Other: The key is determined by decoding and decrypting one of 1267 the recipient structures. 1269 4. Call the decryption algorithm with K (the decryption key to use), 1270 and C (the cipher text). 1272 6. MAC Objects 1274 COSE supports two different MAC structures. COSE_MAC0 is used when a 1275 recipient structure is not needed because the key to be used is 1276 implicitly known. COSE_MAC is used for all other cases. These 1277 include a requirement for multiple recipients, the key being unknown, 1278 and a recipient algorithm of other than direct. 1280 In this section, we describe the structure and methods to be used 1281 when doing MAC authentication in COSE. This document allows for the 1282 use of all of the same classes of recipient algorithms as are allowed 1283 for encryption. 1285 When using MAC operations, there are two modes in which they can be 1286 used. The first is just a check that the content has not been 1287 changed since the MAC was computed. Any class of recipient algorithm 1288 can be used for this purpose. The second mode is to both check that 1289 the content has not been changed since the MAC was computed, and to 1290 use the recipient algorithm to verify who sent it. The classes of 1291 recipient algorithms that support this are those that use a pre- 1292 shared secret or do static-static key agreement (without the key wrap 1293 step). In both of these cases, the entity that created and sent the 1294 message MAC can be validated. (This knowledge of sender assumes that 1295 there are only two parties involved and you did not send the message 1296 yourself.) 1298 6.1. MACed Message with Recipients 1300 The multiple recipient MACed message uses two structures, the 1301 COSE_Mac structure defined in this section for carrying the body and 1302 the COSE_recipient structure (Section 5.1) to hold the key used for 1303 the MAC computation. Examples of MACed messages can be found in 1304 Appendix C.5. 1306 The MAC structure can be encoded either tagged or untagged depending 1307 on the context it will be used in. A tagged COSE_Mac structure is 1308 identified by the CBOR tag TBD4. The CDDL fragment that represents 1309 this is: 1311 COSE_Mac_Tagged = #6.994(COSE_Mac) ; Replace 994 with TBD4 1313 The COSE_Mac structure is a CBOR array. The fields of the array in 1314 order are: 1316 protected as described in Section 3. 1318 unprotected as described in Section 3. 1320 payload contains the serialized content to be MACed. If the payload 1321 is not present in the message, the application is required to 1322 supply the payload separately. The payload is wrapped in a bstr 1323 to ensure that it is transported without changes. If the payload 1324 is transported separately (i.e., detached content), then a nil 1325 CBOR value is placed in this location and it is the responsibility 1326 of the application to ensure that it will be transported without 1327 changes. 1329 tag contains the MAC value. 1331 recipients as described in Section 5.1. 1333 The CDDL fragment that represents the above text for COSE_Mac 1334 follows. 1336 COSE_Mac = [ 1337 Headers, 1338 payload : bstr / nil, 1339 tag : bstr, 1340 recipients :[+COSE_recipient] 1341 ] 1343 6.2. MACed Messages with Implicit Key 1345 In this section, we describe the structure and methods to be used 1346 when doing MAC authentication for those cases where the recipient is 1347 implicitly known. 1349 The MACed message uses the COSE_Mac0 structure defined in this 1350 section for carrying the body. Examples of MACed messages with an 1351 implicit key can be found in Appendix C.6. 1353 The MAC structure can be encoded either tagged or untagged depending 1354 on the context it will be used in. A tagged COSE_Mac0 structure is 1355 identified by the CBOR tag TBD6. The CDDL fragment that represents 1356 this is: 1358 COSE_Mac0_Tagged = #6.996(COSE_Mac0) ; Replace 996 with TBD6 1360 The COSE_Mac0 structure is a CBOR array. The fields of the array in 1361 order are: 1363 protected as described in Section 3. 1365 unprotected as described in Section 3. 1367 payload as described in Section 6.1. 1369 tag contains the MAC value. 1371 The CDDL fragment that corresponds to the above text is: 1373 COSE_Mac0 = [ 1374 Headers, 1375 payload : bstr / nil, 1376 tag : bstr, 1377 ] 1379 6.3. How to compute and verify a MAC 1381 In order to get a consistent encoding of the data to be 1382 authenticated, the MAC_structure is used to have a canonical form. 1383 The MAC_structure is a CBOR array. The fields of the MAC_structure 1384 in order are: 1386 1. A text string that identifies the structure that is being 1387 encoded. This string is "MAC" for the COSE_Mac structure. This 1388 string is "MAC0" for the COSE_Mac0 structure. 1390 2. The protected attributes from the COSE_MAC structure. If there 1391 are no protected attributes, a zero length bstr is used. 1393 3. The protected attributes from the application encoded as a bstr 1394 type. If this field is not supplied, it defaults to a zero 1395 length binary string. (See Section 4.3 for application guidance 1396 on constructing this field.) 1398 4. The payload to be MAC-ed encoded in a bstr type. The payload is 1399 placed here independent of how it is transported. 1401 The CDDL fragment that corresponds to the above text is: 1403 MAC_structure = [ 1404 context : "MAC" / "MAC0", 1405 protected : empty_or_serialized_map, 1406 external_aad : bstr, 1407 payload : bstr 1408 ] 1410 The steps to compute a MAC are: 1412 1. Create a MAC_structure and populate it with the appropriate 1413 fields. 1415 2. Create the value ToBeMaced by encoding the MAC_structure to a 1416 byte stream, using the encoding described in Section 14. 1418 3. Call the MAC creation algorithm passing in K (the key to use), 1419 alg (the algorithm to MAC with) and ToBeMaced (the value to 1420 compute the MAC on). 1422 4. Place the resulting MAC in the 'tag' field of the COSE_Mac 1423 structure. 1425 5. Encrypt and encode the MAC key for each recipient of the message. 1427 How to verify a MAC are: 1429 1. Create a MAC_structure object and populate it with the 1430 appropriate fields. 1432 2. Create the value ToBeMaced by encoding the MAC_structure to a 1433 byte stream, using the encoding described in Section 14. 1435 3. Obtain the cryptographic key from one of the recipients of the 1436 message. 1438 4. Call the MAC creation algorithm passing in K (the key to use), 1439 alg (the algorithm to MAC with) and ToBeMaced (the value to 1440 compute the MAC on). 1442 5. Compare the MAC value to the 'tag' field of the COSE_Mac 1443 structure. 1445 7. Key Objects 1447 A COSE Key structure is built on a CBOR map object. The set of 1448 common parameters that can appear in a COSE Key can be found in the 1449 IANA "COSE Key Common Parameters" registry (Section 16.5). 1450 Additional parameters defined for specific key types can be found in 1451 the IANA "COSE Key Type Parameters" registry (Section 16.6). 1453 A COSE Key Set uses a CBOR array object as its underlying type. The 1454 values of the array elements are COSE Keys. A Key Set MUST have at 1455 least one element in the array. 1457 Each element in a key set MUST be processed independently. If one 1458 element in a key set is either malformed or uses a key that is not 1459 understood by an application, that key is ignored and the other keys 1460 are processed normally. 1462 The element "kty" is a required element in a COSE_Key map. 1464 The CDDL grammar describing COSE_Key and COSE_KeySet is: 1466 COSE_Key = { 1467 key_kty => tstr / int, 1468 ? key_ops => [+ (tstr / int) ], 1469 ? key_alg => tstr / int, 1470 ? key_kid => bstr, 1471 ? key_baseIV => bstr, 1472 * label => values 1473 } 1475 COSE_KeySet = [+COSE_Key] 1477 7.1. COSE Key Common Parameters 1479 This document defines a set of common parameters for a COSE Key 1480 object. Table 3 provides a summary of the parameters defined in this 1481 section. There are also parameters that are defined for specific key 1482 types. Key type specific parameters can be found in Section 13. 1484 +---------+-------+----------------+------------+-------------------+ 1485 | name | label | CBOR type | registry | description | 1486 +---------+-------+----------------+------------+-------------------+ 1487 | kty | 1 | tstr / int | COSE Key | Identification of | 1488 | | | | Common | the key type | 1489 | | | | Parameters | | 1490 | | | | | | 1491 | alg | 3 | tstr / int | COSE | Key usage | 1492 | | | | Algorithm | restriction to | 1493 | | | | Values | this algorithm | 1494 | | | | | | 1495 | kid | 2 | bstr | | Key | 1496 | | | | | Identification | 1497 | | | | | value - match to | 1498 | | | | | kid in message | 1499 | | | | | | 1500 | key_ops | 4 | [+ (tstr/int)] | | Restrict set of | 1501 | | | | | permissible | 1502 | | | | | operations | 1503 | | | | | | 1504 | Base IV | 5 | bstr | | Base IV to be | 1505 | | | | | xor-ed with | 1506 | | | | | Partial IVs | 1507 +---------+-------+----------------+------------+-------------------+ 1509 Table 3: Key Map Labels 1511 kty: This parameter is used to identify the family of keys for this 1512 structure, and thus the set of key type specific parameters to be 1513 found. The set of values defined in this document can be found in 1514 Table 21. This parameter MUST be present in a key object. 1515 Implementations MUST verify that the key type is appropriate for 1516 the algorithm being processed. The key type MUST be included as 1517 part of the trust decision process. 1519 alg: This parameter is used to restrict the algorithm that is used 1520 with the key. If this parameter is present in the key structure, 1521 the application MUST verify that this algorithm matches the 1522 algorithm for which the key is being used. If the algorithms do 1523 not match, then this key object MUST NOT be used to perform the 1524 cryptographic operation. Note that the same key can be in a 1525 different key structure with a different or no algorithm 1526 specified, however this is considered to be a poor security 1527 practice. 1529 kid: This parameter is used to give an identifier for a key. The 1530 identifier is not structured and can be anything from a user 1531 provided string to a value computed on the public portion of the 1532 key. This field is intended for matching against a 'kid' 1533 parameter in a message in order to filter down the set of keys 1534 that need to be checked. 1536 key_ops: This parameter is defined to restrict the set of operations 1537 that a key is to be used for. The value of the field is an array 1538 of values from Table 4. Algorithms define the values of key ops 1539 that are permitted to appear and are required for specific 1540 operations. 1542 Base IV: This parameter is defined to carry the base portion of an 1543 IV. It is designed to be used with the partial IV header 1544 parameter defined in Section 3.1. This field provides the ability 1545 to associate a partial IV with a key that is then modified on a 1546 per message basis with the partial IV. 1548 Extreme care needs to be taken when using a Base IV in an 1549 application. Many encryption algorithms lose security if the same 1550 IV is used twice. 1552 If different keys are derived for each sender, starting at the 1553 same base IV is likely to satisfy this condition. If the same key 1554 is used for multiple senders, then the application needs to 1555 provide for a method of dividing the IV space up between the 1556 senders. This could be done by providing a different base point 1557 to start from or a different partial IV to start with and 1558 restricting the number of messages to be sent before re-keying. 1560 +---------+-------+-------------------------------------------------+ 1561 | name | value | description | 1562 +---------+-------+-------------------------------------------------+ 1563 | sign | 1 | The key is used to create signatures. Requires | 1564 | | | private key fields. | 1565 | | | | 1566 | verify | 2 | The key is used for verification of signatures. | 1567 | | | | 1568 | encrypt | 3 | The key is used for key transport encryption. | 1569 | | | | 1570 | decrypt | 4 | The key is used for key transport decryption. | 1571 | | | Requires private key fields. | 1572 | | | | 1573 | wrap | 5 | The key is used for key wrapping. | 1574 | key | | | 1575 | | | | 1576 | unwrap | 6 | The key is used for key unwrapping. Requires | 1577 | key | | private key fields. | 1578 | | | | 1579 | derive | 7 | The key is used for deriving keys. Requires | 1580 | key | | private key fields. | 1581 | | | | 1582 | derive | 8 | The key is used for deriving bits. Requires | 1583 | bits | | private key fields. | 1584 | | | | 1585 | MAC | 9 | The key is used for creating MACs. | 1586 | create | | | 1587 | | | | 1588 | MAC | 10 | The key is used for validating MACs. | 1589 | verify | | | 1590 +---------+-------+-------------------------------------------------+ 1592 Table 4: Key Operation Values 1594 The following provides a CDDL fragment that duplicates the assignment 1595 labels from Table 3. 1597 ;key_labels 1598 key_kty=1 1599 key_kid=2 1600 key_alg=3 1601 key_ops=4 1602 key_baseIV=5 1604 8. Signature Algorithms 1606 There are two signature algorithm schemes. The first is signature 1607 with appendix. In this scheme, the message content is processed and 1608 a signature is produced, the signature is called the appendix. This 1609 is the scheme used by algorithms such as ECDSA and RSASSA-PSS. (In 1610 fact the SSA in RSASSA-PSS stands for Signature Scheme with 1611 Appendix.) 1613 The signature functions for this scheme are: 1615 signature = Sign(message content, key) 1617 valid = Verification(message content, key, signature) 1619 The second scheme is signature with message recovery. (An example of 1620 such an algorithm is [PVSig].) In this scheme, the message content 1621 is processed, but part of it is included in the signature. Moving 1622 bytes of the message content into the signature allows for smaller 1623 signatures, the signature size is still potentially large, but the 1624 message content has shrunk. This has implications for systems 1625 implementing these algorithms and for applications that use them. 1626 The first is that the message content is not fully available until 1627 after a signature has been validated. Until that point the part of 1628 the message contained inside of the signature is unrecoverable. The 1629 second is that the security analysis of the strength of the signature 1630 is very much based on the structure of the message content. Messages 1631 that are highly predictable require additional randomness to be 1632 supplied as part of the signature process. In the worst case, it 1633 becomes the same as doing a signature with appendix. Finally, in the 1634 event that multiple signatures are applied to a message, all of the 1635 signature algorithms are going to be required to consume the same 1636 number of bytes of message content. This means that mixing of the 1637 different schemes in a single message is not supported, and if a 1638 recovery signature scheme is used, then the same amount of content 1639 needs to be consumed by all of the signatures. 1641 The signature functions for this scheme are: 1643 signature, message sent = Sign(message content, key) 1645 valid, message content = Verification(message sent, key, signature) 1647 Signature algorithms are used with the COSE_Signature and COSE_Sign1 1648 structures. At this time, only signatures with appendixes are 1649 defined for use with COSE, however considerable interest has been 1650 expressed in using a signature with message recovery algorithm due to 1651 the effective size reduction that is possible. Implementations will 1652 need to keep this in mind for later possible integration. 1654 8.1. ECDSA 1656 ECDSA [DSS] defines a signature algorithm using ECC. 1658 The ECDSA signature algorithm is parameterized with a hash function 1659 (h). In the event that the length of the hash function output is 1660 greater than the group of the key, the left-most bytes of the hash 1661 output are used. 1663 The algorithms defined in this document can be found in Table 5. 1665 +-------+-------+---------+------------------+ 1666 | name | value | hash | description | 1667 +-------+-------+---------+------------------+ 1668 | ES256 | -7 | SHA-256 | ECDSA w/ SHA-256 | 1669 | | | | | 1670 | ES384 | -35 | SHA-384 | ECDSA w/ SHA-384 | 1671 | | | | | 1672 | ES512 | -36 | SHA-512 | ECDSA w/ SHA-512 | 1673 +-------+-------+---------+------------------+ 1675 Table 5: ECDSA Algorithm Values 1677 This document defines ECDSA to work only with the curves P-256, P-384 1678 and P-521. This document requires that the curves be encoded using 1679 the 'EC2' key type. Implementations need to check that the key type 1680 and curve are correct when creating and verifying a signature. Other 1681 documents can define it to work with other curves and points in the 1682 future. 1684 In order to promote interoperability, it is suggested that SHA-256 be 1685 used only with curve P-256, SHA-384 be used only with curve P-384 and 1686 SHA-512 be used with curve P-521. This is aligned with the 1687 recommendation in Section 4 of [RFC5480]. 1689 The signature algorithm results in a pair of integers (R, S). These 1690 integers will the same length as length of the key used for the 1691 signature process. The signature is encoded by converting the 1692 integers into byte strings of the same length as the key size. The 1693 length is rounded up to the nearest byte and is left padded with zero 1694 bits to get to the correct length. The two integers are then 1695 concatenated together to form a byte string that is the resulting 1696 signature. 1698 Using the function defined in [RFC3447] the signature is: 1700 Signature = I2OSP(R, n) | I2OSP(S, n) 1701 where n = ceiling(key_length / 8) 1703 When using a COSE key for this algorithm, the following checks are 1704 made: 1706 o The 'kty' field MUST be present and it MUST be 'EC2'. 1708 o If the 'alg' field is present, it MUST match the ECDSA signature 1709 algorithm being used. 1711 o If the 'key_ops' field is present, it MUST include 'sign' when 1712 creating an ECDSA signature. 1714 o If the 'key_ops' field is present, it MUST include 'verify' when 1715 verifying an ECDSA signature. 1717 8.1.1. Security Considerations 1719 The security strength of the signature is no greater than the minimum 1720 of the security strength associated with the bit length of the key 1721 and the security strength of the hash function. 1723 Systems that have poor random number generation can leak their keys 1724 by signing two different messages with the same value 'k' (the per- 1725 message random value). [RFC6979] provides a method to deal with this 1726 problem by making 'k' be deterministic based on the message content 1727 rather than randomly generated. Applications that specify ECDSA 1728 should evaluate the ability to get good random number generation and 1729 require deterministic signatures where poor random number generation 1730 exists. 1732 Note: Use of this technique is a good idea even when good random 1733 number generation exists. Doing so both reduces the possibility of 1734 having the same value of 'k' in two signature operations and allows 1735 for reproducible signature values, which helps testing. 1737 There are two substitution attacks that can theoretically be mounted 1738 against the ECDSA signature algorithm. 1740 o Changing the curve used to validate the signature: If one changes 1741 the curve used to validate the signature, then potentially one 1742 could have a two messages with the same signature each computed 1743 under a different curve. The only requirement on the new curve is 1744 that its order be the same as the old one and it be acceptable to 1745 the client. An example would be to change from using the curve 1746 secp256r1 (aka P-256) to using secp256k1. (Both are 256 bit 1747 curves.) We current do not have any way to deal with this version 1748 of the attack except to restrict the overall set of curves that 1749 can be used. 1751 o Change the hash function used to validate the signature: If one 1752 has either two different hash functions of the same length, or one 1753 can truncate a hash function down, then one could potentially find 1754 collisions between the hash functions rather than within a single 1755 hash function. (For example, truncating SHA-512 to 256 bits might 1756 collide with a SHA-256 bit hash value.) This attack can be 1757 mitigated by including the signature algorithm identifier in the 1758 data to be signed. 1760 8.2. Edwards-curve Digital Signature Algorithms (EdDSA) 1762 [I-D.irtf-cfrg-eddsa] describes the elliptic curve signature scheme 1763 Edwards-curve Digital Signature Algorithm (EdDSA). In that document, 1764 the signature algorithm is instantiated using parameters for 1765 edwards25519 and edwards448 curves. The document additionally 1766 describes two variants of the EdDSA algorithm: Pure EdDSA, where no 1767 hash function is applied to the content before signing and, HashEdDSA 1768 where a hash function is applied to the content before signing and 1769 the result of that hash function is signed. For use with COSE, only 1770 the pure EdDSA version is used. This is because it is not expected 1771 that extremely large contents are going to be needed and, based on 1772 the arrangement of the message structure, the entire message is going 1773 to need to be held in memory in order to create or verify a 1774 signature. Thus, the use of an incremental update process would not 1775 be useful. Applications can provide the same features by defining 1776 the content of the message as a hash value and transporting the COSE 1777 object and the content as separate items. 1779 The algorithms defined in this document can be found in Table 6. A 1780 single signature algorithm is defined, which can be used for multiple 1781 curves. 1783 +-------+-------+-------------+ 1784 | name | value | description | 1785 +-------+-------+-------------+ 1786 | EdDSA | -8 | EdDSA | 1787 +-------+-------+-------------+ 1789 Table 6: EdDSA Algorithm Values 1791 [I-D.irtf-cfrg-eddsa] describes the method of encoding the signature 1792 value. 1794 When using a COSE key for this algorithm the following checks are 1795 made: 1797 o The 'kty' field MUST be present and it MUST be 'OKP'. 1799 o The 'crv' field MUST be present, and it MUST be a curve defined 1800 for this signature algorithm. 1802 o If the 'alg' field is present, it MUST match 'EdDSA'. 1804 o If the 'key_ops' field is present, it MUST include 'sign' when 1805 creating an EdDSA signature. 1807 o If the 'key_ops' field is present, it MUST include 'verify' when 1808 verifying an EdDSA signature. 1810 8.2.1. Security Considerations 1812 The Edwards curves for EdDSA and ECDH are distinct and should not be 1813 used for the other algorithm. 1815 If batch signature verification is performed, a well-seeded 1816 cryptographic random number generator is REQUIRED. Signing and non- 1817 batch signature verification are deterministic operations and do not 1818 need random numbers of any kind. 1820 9. Message Authentication (MAC) Algorithms 1822 Message Authentication Codes (MACs) provide data authentication and 1823 integrity protection. They provide either no or very limited data 1824 origination. (One cannot, for example, be used to prove the identity 1825 of the sender to a third party.) 1827 MACs use the same scheme as signature with appendix algorithms. The 1828 message content is processed and an authentication code is produced. 1829 The authentication code is frequently called a tag. 1831 The MAC functions are: 1833 tag = MAC_Create(message content, key) 1835 valid = MAC_Verify(message content, key, tag) 1837 MAC algorithms can be based on either a block cipher algorithm (i.e., 1838 AES-MAC) or a hash algorithm (i.e., HMAC). This document defines a 1839 MAC algorithm using each of these constructions. 1841 MAC algorithms are used in the COSE_Mac and COSE_Mac1 structures. 1843 9.1. Hash-based Message Authentication Codes (HMAC) 1845 The Hash-base Message Authentication Code algorithm (HMAC) 1846 [RFC2104][RFC4231] was designed to deal with length extension 1847 attacks. The algorithm was also designed to allow for new hash 1848 algorithms to be directly plugged in without changes to the hash 1849 function. The HMAC design process has been shown as solid since, 1850 while the security of hash algorithms such as MD5 has decreased over 1851 time, the security of HMAC combined with MD5 has not yet been shown 1852 to be compromised [RFC6151]. 1854 The HMAC algorithm is parameterized by an inner and outer padding, a 1855 hash function (h), and an authentication tag value length. For this 1856 specification, the inner and outer padding are fixed to the values 1857 set in [RFC2104]. The length of the authentication tag corresponds 1858 to the difficulty of producing a forgery. For use in constrained 1859 environments, we define a set of HMAC algorithms that are truncated. 1860 There are currently no known issues with truncation, however the 1861 security strength of the message tag is correspondingly reduced in 1862 strength. When truncating, the left-most tag length bits are kept 1863 and transmitted. 1865 The algorithms defined in this document can be found in Table 7. 1867 +-----------+-------+---------+----------+--------------------------+ 1868 | name | value | Hash | Tag | description | 1869 | | | | Length | | 1870 +-----------+-------+---------+----------+--------------------------+ 1871 | HMAC | 4 | SHA-256 | 64 | HMAC w/ SHA-256 | 1872 | 256/64 | | | | truncated to 64 bits | 1873 | | | | | | 1874 | HMAC | 5 | SHA-256 | 256 | HMAC w/ SHA-256 | 1875 | 256/256 | | | | | 1876 | | | | | | 1877 | HMAC | 6 | SHA-384 | 384 | HMAC w/ SHA-384 | 1878 | 384/384 | | | | | 1879 | | | | | | 1880 | HMAC | 7 | SHA-512 | 512 | HMAC w/ SHA-512 | 1881 | 512/512 | | | | | 1882 +-----------+-------+---------+----------+--------------------------+ 1884 Table 7: HMAC Algorithm Values 1886 Some recipient algorithms carry the key while others derive a key 1887 from secret data. For those algorithms that carry the key (such as 1888 AES-KeyWrap), the size of the HMAC key SHOULD be the same size as the 1889 underlying hash function. For those algorithms that derive the key 1890 (such as ECDH), the derived key MUST be the same size as the 1891 underlying hash function. 1893 When using a COSE key for this algorithm, the following checks are 1894 made: 1896 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 1898 o If the 'alg' field present, it MUST match the HMAC algorithm being 1899 used. 1901 o If the 'key_ops' field is present, it MUST include 'MAC create' 1902 when creating an HMAC authentication tag. 1904 o If the 'key_ops' field is present, it MUST include 'MAC verify' 1905 when verifying an HMAC authentication tag. 1907 Implementations creating and validating MAC values MUST validate that 1908 the key type, key length, and algorithm are correct and appropriate 1909 for the entities involved. 1911 9.1.1. Security Considerations 1913 HMAC has proved to be resistant to attack even when used with 1914 weakened hash algorithms. The current best method appears to be a 1915 brute force attack on the key. This means that key size is going to 1916 be directly related to the security of an HMAC operation. 1918 9.2. AES Message Authentication Code (AES-CBC-MAC) 1920 AES-CBC-MAC is defined in [MAC]. (Note this is not the same 1921 algorithm as AES-CMAC [RFC4493]). 1923 AES-CBC-MAC is parameterized by the key length, the authentication 1924 tag length and the IV used. For all of these algorithms, the IV is 1925 fixed to all zeros. We provide an array of algorithms for various 1926 key lengths and tag lengths. The algorithms defined in this document 1927 are found in Table 8. 1929 +-------------+-------+----------+----------+-----------------------+ 1930 | name | value | key | tag | description | 1931 | | | length | length | | 1932 +-------------+-------+----------+----------+-----------------------+ 1933 | AES-MAC | 14 | 128 | 64 | AES-MAC 128 bit key, | 1934 | 128/64 | | | | 64-bit tag | 1935 | | | | | | 1936 | AES-MAC | 15 | 256 | 64 | AES-MAC 256 bit key, | 1937 | 256/64 | | | | 64-bit tag | 1938 | | | | | | 1939 | AES-MAC | 25 | 128 | 128 | AES-MAC 128 bit key, | 1940 | 128/128 | | | | 128-bit tag | 1941 | | | | | | 1942 | AES-MAC | 26 | 256 | 128 | AES-MAC 256 bit key, | 1943 | 256/128 | | | | 128-bit tag | 1944 +-------------+-------+----------+----------+-----------------------+ 1946 Table 8: AES-MAC Algorithm Values 1948 Keys may be obtained either from a key structure or from a recipient 1949 structure. Implementations creating and validating MAC values MUST 1950 validate that the key type, key length and algorithm are correct and 1951 appropriate for the entities involved. 1953 When using a COSE key for this algorithm, the following checks are 1954 made: 1956 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 1958 o If the 'alg' field present, it MUST match the AES-MAC algorithm 1959 being used. 1961 o If the 'key_ops' field is present, it MUST include 'MAC create' 1962 when creating an AES-MAC authentication tag. 1964 o If the 'key_ops' field is present, it MUST include 'MAC verify' 1965 when verifying an AES-MAC authentication tag. 1967 9.2.1. Security Considerations 1969 A number of attacks exist against CBC-MAC that need to be considered. 1971 o A single key must only be used for messages of a fixed and known 1972 length. If this is not the case, an attacker will be able to 1973 generate a message with a valid tag given two message, tag pairs. 1974 This can be addressed by using different keys for different length 1975 messages. The current structure mitigates this problem, as a 1976 specific encoding structure that includes lengths is build and 1977 signed. (CMAC also addresses this issue.) 1979 o If the same key is used for both encryption and authentication 1980 operations, using CBC modes an attacker can produce messages with 1981 a valid authentication code. 1983 o If the IV can be modified, then messages can be forged. This is 1984 addressed by fixing the IV to all zeros. 1986 10. Content Encryption Algorithms 1988 Content Encryption Algorithms provide data confidentiality for 1989 potentially large blocks of data using a symmetric key. They provide 1990 integrity on the data that was encrypted, however they provide either 1991 no or very limited data origination. (One cannot, for example, be 1992 used to prove the identity of the sender to a third party.) The 1993 ability to provide data origination is linked to how the CEK is 1994 obtained. 1996 COSE restricts the set of legal content encryption algorithms to 1997 those that support authentication both of the content and additional 1998 data. The encryption process will generate some type of 1999 authentication value, but that value may be either explicit or 2000 implicit in terms of the algorithm definition. For simplicity sake, 2001 the authentication code will normally be defined as being appended to 2002 the cipher text stream. The encryption functions are: 2004 ciphertext = Encrypt(message content, key, additional data) 2006 valid, message content = Decrypt(cipher text, key, additional data) 2008 Most AEAD algorithms are logically defined as returning the message 2009 content only if the decryption is valid. Many but not all 2010 implementations will follow this convention. The message content 2011 MUST NOT be used if the decryption does not validate. 2013 These algorithms are used in COSE_Encrypt and COSE_Encrypt0. 2015 10.1. AES GCM 2017 The GCM mode is a generic authenticated encryption block cipher mode 2018 defined in [AES-GCM]. The GCM mode is combined with the AES block 2019 encryption algorithm to define an AEAD cipher. 2021 The GCM mode is parameterized by the size of the authentication tag 2022 and the size of the nonce. This document fixes the size of the nonce 2023 at 96 bits. The size of the authentication tag is limited to a small 2024 set of values. For this document however, the size of the 2025 authentication tag is fixed at 128 bits. 2027 The set of algorithms defined in this document are in Table 9. 2029 +---------+-------+------------------------------------------+ 2030 | name | value | description | 2031 +---------+-------+------------------------------------------+ 2032 | A128GCM | 1 | AES-GCM mode w/ 128-bit key, 128-bit tag | 2033 | | | | 2034 | A192GCM | 2 | AES-GCM mode w/ 192-bit key, 128-bit tag | 2035 | | | | 2036 | A256GCM | 3 | AES-GCM mode w/ 256-bit key, 128-bit tag | 2037 +---------+-------+------------------------------------------+ 2039 Table 9: Algorithm Value for AES-GCM 2041 Keys may be obtained either from a key structure or from a recipient 2042 structure. Implementations encrypting and decrypting MUST validate 2043 that the key type, key length and algorithm are correct and 2044 appropriate for the entities involved. 2046 When using a COSE key for this algorithm, the following checks are 2047 made: 2049 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2051 o If the 'alg' field present, it MUST match the AES-GCM algorithm 2052 being used. 2054 o If the 'key_ops' field is present, it MUST include 'encrypt' or 2055 'key wrap' when encrypting. 2057 o If the 'key_ops' field is present, it MUST include 'decrypt' or 2058 'key unwrap' when decrypting. 2060 10.1.1. Security Considerations 2062 When using AES-GCM, the following restrictions MUST be enforced: 2064 o The key and nonce pair MUST be unique for every message encrypted. 2066 o The total amount of data encrypted for a single key MUST NOT 2067 exceed 2^39 - 256 bits. An explicit check is required only in 2068 environments where it is expected that it might be exceeded. 2070 Consideration was given to supporting smaller tag values; the 2071 constrained community would desire tag sizes in the 64-bit range. 2073 Doing so drastically changes both the maximum messages size 2074 (generally not an issue) and the number of times that a key can be 2075 used. Given that CCM is the usual mode for constrained environments, 2076 restricted modes are not supported. 2078 10.2. AES CCM 2080 Counter with CBC-MAC (CCM) is a generic authentication encryption 2081 block cipher mode defined in [RFC3610]. The CCM mode is combined 2082 with the AES block encryption algorithm to define a commonly used 2083 content encryption algorithm used in constrained devices. 2085 The CCM mode has two parameter choices. The first choice is M, the 2086 size of the authentication field. The choice of the value for M 2087 involves a trade-off between message growth (from the tag) and the 2088 probably that an attacker can undetectably modify a message. The 2089 second choice is L, the size of the length field. This value 2090 requires a trade-off between the maximum message size and the size of 2091 the Nonce. 2093 It is unfortunate that the specification for CCM specified L and M as 2094 a count of bytes rather than a count of bits. This leads to possible 2095 misunderstandings where AES-CCM-8 is frequently used to refer to a 2096 version of CCM mode where the size of the authentication is 64 bits 2097 and not 8 bits. These values have traditionally been specified as 2098 bit counts rather than byte counts. This document will follow the 2099 convention of using bit counts so that it is easier to compare the 2100 different algorithms presented in this document. 2102 We define a matrix of algorithms in this document over the values of 2103 L and M. Constrained devices are usually operating in situations 2104 where they use short messages and want to avoid doing recipient 2105 specific cryptographic operations. This favors smaller values of 2106 both L and M. Less constrained devices will want to be able to user 2107 larger messages and are more willing to generate new keys for every 2108 operation. This favors larger values of L and M. 2110 The following values are used for L: 2112 16 bits (2) limits messages to 2^16 bytes (64 KiB) in length. This 2113 is sufficiently long for messages in the constrained world. The 2114 nonce length is 13 bytes allowing for 2^(13*8) possible values of 2115 the nonce without repeating. 2117 64 bits (8) limits messages to 2^64 bytes in length. The nonce 2118 length is 7 bytes allowing for 2^56 possible values of the nonce 2119 without repeating. 2121 The following values are used for M: 2123 64 bits (8) produces a 64-bit authentication tag. This implies that 2124 there is a 1 in 2^64 chance that a modified message will 2125 authenticate. 2127 128 bits (16) produces a 128-bit authentication tag. This implies 2128 that there is a 1 in 2^128 chance that a modified message will 2129 authenticate. 2131 +--------------------+-------+----+-----+-----+---------------------+ 2132 | name | value | L | M | k | description | 2133 +--------------------+-------+----+-----+-----+---------------------+ 2134 | AES-CCM-16-64-128 | 10 | 16 | 64 | 128 | AES-CCM mode | 2135 | | | | | | 128-bit key, 64-bit | 2136 | | | | | | tag, 13-byte nonce | 2137 | | | | | | | 2138 | AES-CCM-16-64-256 | 11 | 16 | 64 | 256 | AES-CCM mode | 2139 | | | | | | 256-bit key, 64-bit | 2140 | | | | | | tag, 13-byte nonce | 2141 | | | | | | | 2142 | AES-CCM-64-64-128 | 12 | 64 | 64 | 128 | AES-CCM mode | 2143 | | | | | | 128-bit key, 64-bit | 2144 | | | | | | tag, 7-byte nonce | 2145 | | | | | | | 2146 | AES-CCM-64-64-256 | 13 | 64 | 64 | 256 | AES-CCM mode | 2147 | | | | | | 256-bit key, 64-bit | 2148 | | | | | | tag, 7-byte nonce | 2149 | | | | | | | 2150 | AES-CCM-16-128-128 | 30 | 16 | 128 | 128 | AES-CCM mode | 2151 | | | | | | 128-bit key, | 2152 | | | | | | 128-bit tag, | 2153 | | | | | | 13-byte nonce | 2154 | | | | | | | 2155 | AES-CCM-16-128-256 | 31 | 16 | 128 | 256 | AES-CCM mode | 2156 | | | | | | 256-bit key, | 2157 | | | | | | 128-bit tag, | 2158 | | | | | | 13-byte nonce | 2159 | | | | | | | 2160 | AES-CCM-64-128-128 | 32 | 64 | 128 | 128 | AES-CCM mode | 2161 | | | | | | 128-bit key, | 2162 | | | | | | 128-bit tag, 7-byte | 2163 | | | | | | nonce | 2164 | | | | | | | 2165 | AES-CCM-64-128-256 | 33 | 64 | 128 | 256 | AES-CCM mode | 2166 | | | | | | 256-bit key, | 2167 | | | | | | 128-bit tag, 7-byte | 2168 | | | | | | nonce | 2169 +--------------------+-------+----+-----+-----+---------------------+ 2171 Table 10: Algorithm Values for AES-CCM 2173 Keys may be obtained either from a key structure or from a recipient 2174 structure. Implementations encrypting and decrypting MUST validate 2175 that the key type, key length and algorithm are correct and 2176 appropriate for the entities involved. 2178 When using a COSE key for this algorithm, the following checks are 2179 made: 2181 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2183 o If the 'alg' field present, it MUST match the AES-CCM algorithm 2184 being used. 2186 o If the 'key_ops' field is present, it MUST include 'encrypt' or 2187 'key wrap' when encrypting. 2189 o If the 'key_ops' field is present, it MUST include 'decrypt' or 2190 'key unwrap' when decrypting. 2192 10.2.1. Security Considerations 2194 When using AES-CCM, the following restrictions MUST be enforced: 2196 o The key and nonce pair MUST be unique for every message encrypted. 2198 o The total number of times the AES block cipher is used MUST NOT 2199 exceed 2^61 operations. This limitation is the sum of times the 2200 block cipher is used in computing the MAC value and in performing 2201 stream encryption operations. An explicit check is required only 2202 in environments where it is expected that it might be exceeded. 2204 [RFC3610] additionally calls out one other consideration of note. It 2205 is possible to do a pre-computation attack against the algorithm in 2206 cases where portions of the plaintext are highly predictable. This 2207 reduces the security of the key size by half. Ways to deal with this 2208 attack include adding a random portion to the nonce value and/or 2209 increasing the key size used. Using a portion of the nonce for a 2210 random value will decrease the number of messages that a single key 2211 can be used for. Increasing the key size may require more resources 2212 in the constrained device. See sections 5 and 10 of [RFC3610] for 2213 more information. 2215 10.3. ChaCha20 and Poly1305 2217 ChaCha20 and Poly1305 combined together is an AEAD mode that is 2218 defined in [RFC7539]. This is an algorithm defined to be a cipher 2219 that is not AES and thus would not suffer from any future weaknesses 2220 found in AES. These cryptographic functions are designed to be fast 2221 in software-only implementations. 2223 The ChaCha20/Poly1305 AEAD construction defined in [RFC7539] has no 2224 parameterization. It takes a 256-bit key and a 96-bit nonce, as well 2225 as the plain text and additional data as inputs and produces the 2226 cipher text as an option. We define one algorithm identifier for 2227 this algorithm in Table 11. 2229 +-------------------+-------+---------------------------------------+ 2230 | name | value | description | 2231 +-------------------+-------+---------------------------------------+ 2232 | ChaCha20/Poly1305 | 24 | ChaCha20/Poly1305 w/ 256-bit key, | 2233 | | | 128-bit tag | 2234 +-------------------+-------+---------------------------------------+ 2236 Table 11: Algorithm Value for AES-GCM 2238 Keys may be obtained either from a key structure or from a recipient 2239 structure. Implementations encrypting and decrypting MUST validate 2240 that the key type, key length and algorithm are correct and 2241 appropriate for the entities involved. 2243 When using a COSE key for this algorithm, the following checks are 2244 made: 2246 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2248 o If the 'alg' field present, it MUST match the ChaCha algorithm 2249 being used. 2251 o If the 'key_ops' field is present, it MUST include 'encrypt' or 2252 'key wrap' when encrypting. 2254 o If the 'key_ops' field is present, it MUST include 'decrypt' or 2255 'key unwrap' when decrypting. 2257 10.3.1. Security Considerations 2259 The pair of key, nonce MUST be unique for every invocation of the 2260 algorithm. Nonce counters are considered to be an acceptable way of 2261 ensuring that they are unique. 2263 11. Key Derivation Functions (KDF) 2265 Key Derivation Functions (KDFs) are used to take some secret value 2266 and generate a different one. The secret value comes in three 2267 flavors: 2269 o Secrets that are uniformly random: This is the type of secret that 2270 is created by a good random number generator. 2272 o Secrets that are not uniformly random: This is type of secret that 2273 is created by operations like key agreement. 2275 o Secrets that are not random: This is the type of secret that 2276 people generate for things like passwords. 2278 General KDF functions work well with the first type of secret, can do 2279 reasonably well with the second type of secret, and generally do 2280 poorly with the last type of secret. None of the KDF functions in 2281 this section are designed to deal with the type of secrets that are 2282 used for passwords. Functions like PBES2 [RFC2898] need to be used 2283 for that type of secret. 2285 The same KDF function can be setup to deal with the first two types 2286 of secrets in a different way. The KDF function defined in 2287 Section 11.1 is such a function. This is reflected in the set of 2288 algorithms defined for HKDF. 2290 When using KDF functions, one component that is included is context 2291 information. Context information is used to allow for different 2292 keying information to be derived from the same secret. The use of 2293 context based keying material is considered to be a good security 2294 practice. 2296 This document defines a single context structure and a single KDF 2297 function. These elements are used for all of the recipient 2298 algorithms defined in this document that require a KDF process. 2299 These algorithms are defined in Section 12.1.2, Section 12.4.1, and 2300 Section 12.5.1. 2302 11.1. HMAC-based Extract-and-Expand Key Derivation Function (HKDF) 2304 The HKDF key derivation algorithm is defined in [RFC5869]. 2306 The HKDF algorithm takes these inputs: 2308 secret - a shared value that is secret. Secrets may be either 2309 previously shared or derived from operations like a DH key 2310 agreement. 2312 salt - an optional value that is used to change the generation 2313 process. The salt value can be either public or private. If the 2314 salt is public and carried in the message, then the 'salt' 2315 algorithm header parameter defined in Table 13 is used. While 2316 [RFC5869] suggests that the length of the salt be the same as the 2317 length of the underlying hash value, any amount of salt will 2318 improve the security as different key values will be generated. 2319 This parameter is protected by being included in the key 2320 computation and does not need to be separately authenticated. The 2321 salt value does not need to be unique for every message sent. 2323 length - the number of bytes of output that need to be generated. 2325 context information - Information that describes the context in 2326 which the resulting value will be used. Making this information 2327 specific to the context in which the material is going to be used 2328 ensures that the resulting material will always be tied to that 2329 usage. The context structure defined in Section 11.2 is used by 2330 the KDF functions in this document. 2332 PRF - The underlying pseudo-random function to be used in the HKDF 2333 algorithm. The PRF is encoded into the HKDF algorithm selection. 2335 HKDF is defined to use HMAC as the underlying PRF. However, it is 2336 possible to use other functions in the same construct to provide a 2337 different KDF function that is more appropriate in the constrained 2338 world. Specifically, one can use AES-CBC-MAC as the PRF for the 2339 expand step, but not for the extract step. When using a good random 2340 shared secret of the correct length, the extract step can be skipped. 2341 For the AES algorithm versions, the extract step is always skipped. 2343 The extract step cannot be skipped if the secret is not uniformly 2344 random, for example, if it is the result of an ECDH key agreement 2345 step. (This implies that the AES HKDF version cannot be used with 2346 ECDH.) If the extract step is skipped, the 'salt' value is not used 2347 as part of the HKDF functionality. 2349 The algorithms defined in this document are found in Table 12. 2351 +---------------+-----------------+---------------------------------+ 2352 | name | PRF | description | 2353 +---------------+-----------------+---------------------------------+ 2354 | HKDF SHA-256 | HMAC with | HKDF using HMAC SHA-256 as the | 2355 | | SHA-256 | PRF | 2356 | | | | 2357 | HKDF SHA-512 | HMAC with | HKDF using HMAC SHA-512 as the | 2358 | | SHA-512 | PRF | 2359 | | | | 2360 | HKDF AES- | AES-CBC-MAC-128 | HKDF using AES-MAC as the PRF | 2361 | MAC-128 | | w/ 128-bit key | 2362 | | | | 2363 | HKDF AES- | AES-CBC-MAC-256 | HKDF using AES-MAC as the PRF | 2364 | MAC-256 | | w/ 256-bit key | 2365 +---------------+-----------------+---------------------------------+ 2367 Table 12: HKDF algorithms 2369 +------+-------+------+-------------+ 2370 | name | label | type | description | 2371 +------+-------+------+-------------+ 2372 | salt | -20 | bstr | Random salt | 2373 +------+-------+------+-------------+ 2375 Table 13: HKDF Algorithm Parameters 2377 11.2. Context Information Structure 2379 The context information structure is used to ensure that the derived 2380 keying material is "bound" to the context of the transaction. The 2381 context information structure used here is based on that defined in 2382 [SP800-56A]. By using CBOR for the encoding of the context 2383 information structure, we automatically get the same type and length 2384 separation of fields that is obtained by the use of ASN.1. This 2385 means that there is no need to encode the lengths for the base 2386 elements as it is done by the encoding used in JOSE (Section 4.6.2 of 2387 [RFC7518]). 2389 The context information structure refers to PartyU and PartyV as the 2390 two parties that are doing the key derivation. Unless the 2391 application protocol defines differently, we assign PartyU to the 2392 entity that is creating the message and PartyV to the entity that is 2393 receiving the message. By doing this association, different keys 2394 will be derived for each direction as the context information is 2395 different in each direction. 2397 The context structure is built from information that is known to both 2398 entities. This information can be obtained from a variety of 2399 sources: 2401 o Fields can be defined by the application. This is commonly used 2402 to assign fixed names to parties, but can be used for other items 2403 such as nonces. 2405 o Fields can be defined by usage of the output. Examples of this 2406 are the algorithm and key size that are being generated. 2408 o Fields can be defined by parameters from the message. We define a 2409 set of parameters in Table 14 that can be used to carry the values 2410 associated with the context structure. Examples of this are 2411 identities and nonce values. These parameters are designed to be 2412 placed in the unprotected bucket of the recipient structure. 2413 (They do not need to be in the protected bucket since they already 2414 are included in the cryptographic computation by virtue of being 2415 included in the context structure.) 2417 +---------------+-------+-----------+-------------------------------+ 2418 | name | label | type | description | 2419 +---------------+-------+-----------+-------------------------------+ 2420 | PartyU | -21 | bstr | Party U identity Information | 2421 | identity | | | | 2422 | | | | | 2423 | PartyU nonce | -22 | bstr / | Party U provided nonce | 2424 | | | int | | 2425 | | | | | 2426 | PartyU other | -23 | bstr | Party U other provided | 2427 | | | | information | 2428 | | | | | 2429 | PartyV | -24 | bstr | Party V identity Information | 2430 | identity | | | | 2431 | | | | | 2432 | PartyV nonce | -25 | bstr / | Party V provided nonce | 2433 | | | int | | 2434 | | | | | 2435 | PartyV other | -26 | bstr | Party V other provided | 2436 | | | | information | 2437 +---------------+-------+-----------+-------------------------------+ 2439 Table 14: Context Algorithm Parameters 2441 We define a CBOR object to hold the context information. This object 2442 is referred to as CBOR_KDF_Context. The object is based on a CBOR 2443 array type. The fields in the array are: 2445 AlgorithmID This field indicates the algorithm for which the key 2446 material will be used. This normally is either a Key Wrap 2447 algorithm identifier or a Content Encryption algorithm identifier. 2448 The values are from the "COSE Algorithm Value" registry. This 2449 field is required to be present. The field exists in the context 2450 information so that if the same environment is used for different 2451 algorithms, then completely different keys will be generated for 2452 each of those algorithms. (This practice means if algorithm A is 2453 broken and thus is easier to find, the key derived for algorithm B 2454 will not be the same as the key derived for algorithm A.) 2456 PartyUInfo This field holds information about party U. The 2457 PartyUInfo is encoded as a CBOR array. The elements of PartyUInfo 2458 are encoded in the order presented, however if the element does 2459 not exist no element is placed in the array. The elements of the 2460 PartyUInfo array are: 2462 identity This contains the identity information for party U. The 2463 identities can be assigned in one of two manners. Firstly, a 2464 protocol can assign identities based on roles. For example, 2465 the roles of "client" and "server" may be assigned to different 2466 entities in the protocol. Each entity would then use the 2467 correct label for the data they send or receive. The second 2468 way for a protocol to assign identities is to use a name based 2469 on a naming system (i.e., DNS, X.509 names). 2470 We define an algorithm parameter 'PartyU identity' that can be 2471 used to carry identity information in the message. However, 2472 identity information is often known as part of the protocol and 2473 can thus be inferred rather than made explicit. If identity 2474 information is carried in the message, applications SHOULD have 2475 a way of validating the supplied identity information. The 2476 identity information does not need to be specified and is set 2477 to nil in that case. 2479 nonce This contains a nonce value. The nonce can either be 2480 implicit from the protocol or carried as a value in the 2481 unprotected headers. 2482 We define an algorithm parameter 'PartyU nonce' that can be 2483 used to carry this value in the message However, the nonce 2484 value could be determined by the application and the value 2485 determined from elsewhere. 2486 This option does not need to be specified and is set to nil in 2487 that case 2489 other This contains other information that is defined by the 2490 protocol. 2491 This option does not need to be specified and is set to nil in 2492 that case 2494 PartyVInfo This field holds information about party V. The content 2495 of the structure are the same as for the PartyUInfo but for 2496 partyV. 2498 SuppPubInfo This field contains public information that is mutually 2499 known to both parties. 2501 keyDataLength This is set to the number of bits of the desired 2502 output value. (This practice means if algorithm A can use two 2503 different key lengths, the key derived for longer key size will 2504 not contain the key for shorter key size as a prefix.) 2506 protected This field contains the protected parameter field. If 2507 there are no elements in the protected field, then use a zero 2508 length bstr. 2510 other The field other is for free form data defined by the 2511 application. An example is that an application could defined 2512 two different strings to be placed here to generate different 2513 keys for a data stream vs a control stream. This field is 2514 optional and will only be present if the application defines a 2515 structure for this information. Applications that define this 2516 SHOULD use CBOR to encode the data so that types and lengths 2517 are correctly included. 2519 SuppPrivInfo This field contains private information that is 2520 mutually known private information. An example of this 2521 information would be a pre-existing shared secret. (This could, 2522 for example, be used in combination with an ECDH key agreement to 2523 provide a secondary proof of identity.) The field is optional and 2524 will only be present if the application defines a structure for 2525 this information. Applications that define this SHOULD use CBOR 2526 to encode the data so that types and lengths are correctly 2527 included. 2529 The following CDDL fragment corresponds to the text above. 2531 PartyInfo = ( 2532 identity : bstr / nil, 2533 nonce : bstr / int / nil, 2534 other : bstr / nil, 2535 ) 2537 COSE_KDF_Context = [ 2538 AlgorithmID : int / tstr, 2539 PartyUInfo : [ PartyInfo ], 2540 PartyVInfo : [ PartyInfo ], 2541 SuppPubInfo : [ 2542 keyDataLength : uint, 2543 protected : empty_or_serialized_map, 2544 ? other : bstr 2545 ], 2546 ? SuppPrivInfo : bstr 2547 ] 2549 12. Recipient Algorithm Classes 2551 Recipient algorithms can be defined into a number of different 2552 classes. COSE has the ability to support many classes of recipient 2553 algorithms. In this section, a number of classes are listed and then 2554 a set of algorithms are specified for each of the classes. The names 2555 of the recipient algorithm classes used here are the same as are 2556 defined in [RFC7516]. Other specifications use different terms for 2557 the recipient algorithm classes or do not support some of the 2558 recipient algorithm classes. 2560 12.1. Direct Encryption 2562 The direct encryption class algorithms share a secret between the 2563 sender and the recipient that is used either directly or after 2564 manipulation as the CEK. When direct encryption mode is used, it 2565 MUST be the only mode used on the message. 2567 The COSE_Encrypt structure for the recipient is organized as follows: 2569 o The 'protected' field MUST be a zero length item unless it is used 2570 in the computation of the content key. 2572 o The 'alg' parameter MUST be present. 2574 o A parameter identifying the shared secret SHOULD be present. 2576 o The 'ciphertext' field MUST be a zero length item. 2578 o The 'recipients' field MUST be absent. 2580 12.1.1. Direct Key 2582 This recipient algorithm is the simplest; the identified key is 2583 directly used as the key for the next layer down in the message. 2584 There are no algorithm parameters defined for this algorithm. The 2585 algorithm identifier value is assigned in Table 15. 2587 When this algorithm is used, the protected field MUST be zero length. 2588 The key type MUST be 'Symmetric'. 2590 +--------+-------+-------------------+ 2591 | name | value | description | 2592 +--------+-------+-------------------+ 2593 | direct | -6 | Direct use of CEK | 2594 +--------+-------+-------------------+ 2596 Table 15: Direct Key 2598 12.1.1.1. Security Considerations 2600 This recipient algorithm has several potential problems that need to 2601 be considered: 2603 o These keys need to have some method to be regularly updated over 2604 time. All of the content encryption algorithms specified in this 2605 document have limits on how many times a key can be used without 2606 significant loss of security. 2608 o These keys need to be dedicated to a single algorithm. There have 2609 been a number of attacks developed over time when a single key is 2610 used for multiple different algorithms. One example of this is 2611 the use of a single key both for CBC encryption mode and CBC-MAC 2612 authentication mode. 2614 o Breaking one message means all messages are broken. If an 2615 adversary succeeds in determining the key for a single message, 2616 then the key for all messages is also determined. 2618 12.1.2. Direct Key with KDF 2620 These recipient algorithms take a common shared secret between the 2621 two parties and applies the HKDF function (Section 11.1), using the 2622 context structure defined in Section 11.2 to transform the shared 2623 secret into the CEK. The 'protected' field can be of non-zero 2624 length. Either the 'salt' parameter of HKDF or the partyU 'nonce' 2625 parameter of the context structure MUST be present. The salt/nonce 2626 parameter can be generated either randomly or deterministically. The 2627 requirement is that it be a unique value for the shared secret in 2628 question. 2630 If the salt/nonce value is generated randomly, then it is suggested 2631 that the length of the random value be the same length as the hash 2632 function underlying HKDF. While there is no way to guarantee that it 2633 will be unique, there is a high probability that it will be unique. 2634 If the salt/nonce value is generated deterministically, it can be 2635 guaranteed to be unique and thus there is no length requirement. 2637 A new IV must be used for each message if the same key is used. The 2638 IV can be modified in a predictable manner, a random manner or an 2639 unpredictable manner (i.e., encrypting a counter). 2641 The IV used for a key can also be generated from the same HKDF 2642 functionality as the key is generated. If HKDF is used for 2643 generating the IV, the algorithm identifier is set to "IV- 2644 GENERATION". 2646 When these algorithms are used, the key type MUST be 'symmetric'. 2648 The set of algorithms defined in this document can be found in 2649 Table 16. 2651 +---------------------+-------+-------------+-----------------------+ 2652 | name | value | KDF | description | 2653 +---------------------+-------+-------------+-----------------------+ 2654 | direct+HKDF-SHA-256 | -10 | HKDF | Shared secret w/ HKDF | 2655 | | | SHA-256 | and SHA-256 | 2656 | | | | | 2657 | direct+HKDF-SHA-512 | -11 | HKDF | Shared secret w/ HKDF | 2658 | | | SHA-512 | and SHA-512 | 2659 | | | | | 2660 | direct+HKDF-AES-128 | -12 | HKDF AES- | Shared secret w/ AES- | 2661 | | | MAC-128 | MAC 128-bit key | 2662 | | | | | 2663 | direct+HKDF-AES-256 | -13 | HKDF AES- | Shared secret w/ AES- | 2664 | | | MAC-256 | MAC 256-bit key | 2665 +---------------------+-------+-------------+-----------------------+ 2667 Table 16: Direct Key 2669 When using a COSE key for this algorithm, the following checks are 2670 made: 2672 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2674 o If the 'alg' field present, it MUST match the algorithm being 2675 used. 2677 o If the 'key_ops' field is present, it MUST include 'deriveKey' or 2678 'deriveBits'. 2680 12.1.2.1. Security Considerations 2682 The shared secret needs to have some method to be regularly updated 2683 over time. The shared secret forms the basis of trust. Although not 2684 used directly, it should still be subject to scheduled rotation. 2686 While these methods do not provide for PFS, as the same shared secret 2687 is used for all of the keys generated, if the key for any single 2688 message is discovered only the message (or series of messages) using 2689 that derived key are compromised. A new key derivation step will 2690 generate a new key which requires the same amount of work to get the 2691 key. 2693 12.2. Key Wrapping 2695 In key wrapping mode, the CEK is randomly generated and that key is 2696 then encrypted by a shared secret between the sender and the 2697 recipient. All of the currently defined key wrapping algorithms for 2698 COSE are AE algorithms. Key wrapping mode is considered to be 2699 superior to direct encryption if the system has any capability for 2700 doing random key generation. This is because the shared key is used 2701 to wrap random data rather than data that has some degree of 2702 organization and may in fact be repeating the same content. The use 2703 of Key Wrapping loses the weak data origination that is provided by 2704 the direct encryption algorithms. 2706 The COSE_Encrypt structure for the recipient is organized as follows: 2708 o The 'protected' field MUST be absent if the key wrap algorithm is 2709 an AE algorithm. 2711 o The 'recipients' field is normally absent, but can be used. 2712 Applications MUST deal with a recipient field present, not being 2713 able to decrypt that recipient is an acceptable way of dealing 2714 with it. Failing to process the message is not an acceptable way 2715 of dealing with it. 2717 o The plain text to be encrypted is the key from next layer down 2718 (usually the content layer). 2720 o At a minimum, the 'unprotected' field MUST contain the 'alg' 2721 parameter and SHOULD contain a parameter identifying the shared 2722 secret. 2724 12.2.1. AES Key Wrapping 2726 The AES Key Wrapping algorithm is defined in [RFC3394]. This 2727 algorithm uses an AES key to wrap a value that is a multiple of 64 2728 bits. As such, it can be used to wrap a key for any of the content 2729 encryption algorithms defined in this document. The algorithm 2730 requires a single fixed parameter, the initial value. This is fixed 2731 to the value specified in Section 2.2.3.1 of [RFC3394]. There are no 2732 public parameters that vary on a per invocation basis. The protected 2733 header field MUST be empty. 2735 Keys may be obtained either from a key structure or from a recipient 2736 structure. Implementations encrypting and decrypting MUST validate 2737 that the key type, key length and algorithm are correct and 2738 appropriate for the entities involved. 2740 When using a COSE key for this algorithm, the following checks are 2741 made: 2743 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2745 o If the 'alg' field is present, it MUST match the AES Key Wrap 2746 algorithm being used. 2748 o If the 'key_ops' field is present, it MUST include 'encrypt' or 2749 'key wrap' when encrypting. 2751 o If the 'key_ops' field is present, it MUST include 'decrypt' or 2752 'key unwrap' when decrypting. 2754 +--------+-------+----------+-----------------------------+ 2755 | name | value | key size | description | 2756 +--------+-------+----------+-----------------------------+ 2757 | A128KW | -3 | 128 | AES Key Wrap w/ 128-bit key | 2758 | | | | | 2759 | A192KW | -4 | 192 | AES Key Wrap w/ 192-bit key | 2760 | | | | | 2761 | A256KW | -5 | 256 | AES Key Wrap w/ 256-bit key | 2762 +--------+-------+----------+-----------------------------+ 2764 Table 17: AES Key Wrap Algorithm Values 2766 12.2.1.1. Security Considerations for AES-KW 2768 The shared secret needs to have some method to be regularly updated 2769 over time. The shared secret is the basis of trust. 2771 12.3. Key Encryption 2773 Key Encryption mode is also called key transport mode in some 2774 standards. Key Encryption mode differs from Key Wrap mode in that it 2775 uses an asymmetric encryption algorithm rather than a symmetric 2776 encryption algorithm to protect the key. This document does not 2777 define any Key Encryption mode algorithms. 2779 When using a key encryption algorithm, the COSE_Encrypt structure for 2780 the recipient is organized as follows: 2782 o The 'protected' field MUST be absent. 2784 o The plain text to be encrypted is the key from next layer down 2785 (usually the content layer). 2787 o At a minimum, the 'unprotected' field MUST contain the 'alg' 2788 parameter and SHOULD contain a parameter identifying the 2789 asymmetric key. 2791 12.4. Direct Key Agreement 2793 The 'direct key agreement' class of recipient algorithms uses a key 2794 agreement method to create a shared secret. A KDF is then applied to 2795 the shared secret to derive a key to be used in protecting the data. 2797 This key is normally used as a CEK or MAC key, but could be used for 2798 other purposes if more than two layers are in use (see Appendix B). 2800 The most commonly used key agreement algorithm is Diffie-Hellman, but 2801 other variants exist. Since COSE is designed for a store and forward 2802 environment rather than an on-line environment, many of the DH 2803 variants cannot be used as the receiver of the message cannot provide 2804 any dynamic key material. One side-effect of this is that perfect 2805 forward secrecy (see [RFC4949]) is not achievable. A static key will 2806 always be used for the receiver of the COSE object. 2808 Two variants of DH that are supported are: 2810 Ephemeral-Static DH: where the sender of the message creates a 2811 one-time DH key and uses a static key for the recipient. The use 2812 of the ephemeral sender key means that no additional random input 2813 is needed as this is randomly generated for each message. 2815 Static-Static DH: where a static key is used for both the sender 2816 and the recipient. The use of static keys allows for recipient to 2817 get a weak version of data origination for the message. When 2818 static-static key agreement is used, then some piece of unique 2819 data for the KDF is required to ensure that a different key is 2820 created for each message. 2822 When direct key agreement mode is used, there MUST be only one 2823 recipient in the message. This method creates the key directly and 2824 that makes it difficult to mix with additional recipients. If 2825 multiple recipients are needed, then the version with key wrap needs 2826 to be used. 2828 The COSE_Encrypt structure for the recipient is organized as follows: 2830 o At a minimum, headers MUST contain the 'alg' parameter and SHOULD 2831 contain a parameter identifying the recipient's asymmetric key. 2833 o The headers SHOULD identify the sender's key for the static-static 2834 versions and MUST contain the sender's ephemeral key for the 2835 ephemeral-static versions. 2837 12.4.1. ECDH 2839 The mathematics for Elliptic Curve Diffie-Hellman can be found in 2840 [RFC6090]. In this document, the algorithm is extended to be used 2841 with the two curves defined in [RFC7748]. 2843 ECDH is parameterized by the following: 2845 o Curve Type/Curve: The curve selected controls not only the size of 2846 the shared secret, but the mathematics for computing the shared 2847 secret. The curve selected also controls how a point in the curve 2848 is represented and what happens for the identity points on the 2849 curve. In this specification, we allow for a number of different 2850 curves to be used. A set of curves are defined in Table 22. 2851 The math used to obtain the computed secret is based on the curve 2852 selected and not on the ECDH algorithm. For this reason, a new 2853 algorithm does not need to be defined for each of the curves. 2855 o Computed Secret to Shared Secret: Once the computed secret is 2856 known, the resulting value needs to be converted to a byte string 2857 to run the KDF function. The X coordinate is used for all of the 2858 curves defined in this document. For curves X25519 and X448, the 2859 resulting value is used directly as it is a byte string of a known 2860 length. For the P-256, P-384 and P-521 curves, the X coordinate 2861 is run through the I2OSP function defined in [RFC3447], using the 2862 same computation for n as is defined in Section 8.1. 2864 o Ephemeral-static or static-static: The key agreement process may 2865 be done using either a static or an ephemeral key for the sender's 2866 side. When using ephemeral keys, the sender MUST generate a new 2867 ephemeral key for every key agreement operation. The ephemeral 2868 key is placed in the 'ephemeral key' parameter and MUST be present 2869 for all algorithm identifiers that use ephemeral keys. When using 2870 static keys, the sender MUST either generate a new random value or 2871 otherwise create a unique value. For the KDF functions used, this 2872 means either in the 'salt' parameter for HKDF (Table 13) or in the 2873 'PartyU nonce' parameter for the context structure (Table 14) MUST 2874 be present. (Both may be present if desired.) The value in the 2875 parameter MUST be unique for the pair of keys being used. It is 2876 acceptable to use a global counter that is incremented for every 2877 static-static operation and use the resulting value. When using 2878 static keys, the static key should be identified to the recipient. 2879 The static key can be identified either by providing the key 2880 ('static key') or by providing a key identifier for the static key 2881 ('static key id'). Both of these parameters are defined in 2882 Table 19. 2884 o Key derivation algorithm: The result of an ECDH key agreement 2885 process does not provide a uniformly random secret. As such, it 2886 needs to be run through a KDF in order to produce a usable key. 2887 Processing the secret through a KDF also allows for the 2888 introduction of context material: how the key is going to be used, 2889 and one-time material for static-static key agreement. All of the 2890 algorithms defined in this document use one of the HKDF algorithms 2891 defined in Section 11.1 with the context structure defined in 2892 Section 11.2. 2894 o Key Wrap algorithm: No key wrap algorithm is used. This is 2895 represented in Table 18 as 'none'. The key size for the context 2896 structure is the content layer encryption algorithm size. 2898 The set of direct ECDH algorithms defined in this document are found 2899 in Table 18. 2901 +-----------+-------+---------+------------+--------+---------------+ 2902 | name | value | KDF | Ephemeral- | Key | description | 2903 | | | | Static | Wrap | | 2904 +-----------+-------+---------+------------+--------+---------------+ 2905 | ECDH-ES + | -25 | HKDF - | yes | none | ECDH ES w/ | 2906 | HKDF-256 | | SHA-256 | | | HKDF - | 2907 | | | | | | generate key | 2908 | | | | | | directly | 2909 | | | | | | | 2910 | ECDH-ES + | -26 | HKDF - | yes | none | ECDH ES w/ | 2911 | HKDF-512 | | SHA-512 | | | HKDF - | 2912 | | | | | | generate key | 2913 | | | | | | directly | 2914 | | | | | | | 2915 | ECDH-SS + | -27 | HKDF - | no | none | ECDH SS w/ | 2916 | HKDF-256 | | SHA-256 | | | HKDF - | 2917 | | | | | | generate key | 2918 | | | | | | directly | 2919 | | | | | | | 2920 | ECDH-SS + | -28 | HKDF - | no | none | ECDH SS w/ | 2921 | HKDF-512 | | SHA-512 | | | HKDF - | 2922 | | | | | | generate key | 2923 | | | | | | directly | 2924 +-----------+-------+---------+------------+--------+---------------+ 2926 Table 18: ECDH Algorithm Values 2928 +-----------+-------+----------+-----------+------------------------+ 2929 | name | label | type | algorithm | description | 2930 +-----------+-------+----------+-----------+------------------------+ 2931 | ephemeral | -1 | COSE_Key | ECDH-ES | Ephemeral Public key | 2932 | key | | | | for the sender | 2933 | | | | | | 2934 | static | -2 | COSE_Key | ECDH-ES | Static Public key for | 2935 | key | | | | the sender | 2936 | | | | | | 2937 | static | -3 | bstr | ECDH-SS | Static Public key | 2938 | key id | | | | identifier for the | 2939 | | | | | sender | 2940 +-----------+-------+----------+-----------+------------------------+ 2942 Table 19: ECDH Algorithm Parameters 2944 This document defines these algorithms to be used with the curves 2945 P-256, P-384, P-521, X25519, and X448. Implementations MUST verify 2946 that the key type and curve are correct. Different curves are 2947 restricted to different key types. Implementations MUST verify that 2948 the curve and algorithm are appropriate for the entities involved. 2950 When using a COSE key for this algorithm, the following checks are 2951 made: 2953 o The 'kty' field MUST be present and it MUST be 'EC2' or 'OKP'. 2955 o If the 'alg' field present, it MUST match the Key Agreement 2956 algorithm being used. 2958 o If the 'key_ops' field is present, it MUST include 'derive key' or 2959 'derive bits' for the private key. 2961 o If the 'key_ops' field is present, it MUST be empty for the public 2962 key. 2964 12.4.2. Security Considerations 2966 Some method of checking that points provided from external entities 2967 are valid. For the 'EC2' key format, this can be done by checking 2968 that the x and y values form a point on the curve. For the 'OKP' 2969 format, there is no simple way to do point validation. 2971 Consideration was given to requiring that the public keys of both 2972 entities be provided as part of the key derivation process. (As 2973 recommended in section 6.1 of [RFC7748].) This was not done as COSE 2974 is used in a store and forward format rather than in on line key 2975 exchange. In order for this to be a problem, either the receiver 2976 public key has to be chosen maliciously or the sender has to be 2977 malicious. In either case, all security evaporates anyway. 2979 A proof of possession of the private key associated with the public 2980 key is recommended when a key is moved from untrusted to trusted. 2981 (Either by the end user or by the entity that is responsible for 2982 making trust statements on keys.) 2984 12.5. Key Agreement with KDF 2986 Key Agreement with Key Wrapping uses a randomly generated CEK. The 2987 CEK is then encrypted using a Key Wrapping algorithm and a key 2988 derived from the shared secret computed by the key agreement 2989 algorithm. 2991 The COSE_Encrypt structure for the recipient is organized as follows: 2993 o The 'protected' field is fed into the KDF context structure. 2995 o The plain text to be encrypted is the key from next layer down 2996 (usually the content layer). 2998 o The 'alg' parameter MUST be present in the layer. 3000 o A parameter identifying the recipient's key SHOULD be present. A 3001 parameter identifying the sender's key SHOULD be present. 3003 12.5.1. ECDH 3005 These algorithms are defined in Table 20. 3007 ECDH with Key Agreement is parameterized by the same parameters as 3008 for ECDH Section 12.4.1 with the following modifications: 3010 o Key Wrap Algorithm: Any of the key wrap algorithms defined in 3011 Section 12.2.1 are supported. The size of the key used for the 3012 key wrap algorithm is fed into the KDF function. The set of 3013 identifiers are found in Table 20. 3015 +-----------+-------+---------+------------+--------+---------------+ 3016 | name | value | KDF | Ephemeral- | Key | description | 3017 | | | | Static | Wrap | | 3018 +-----------+-------+---------+------------+--------+---------------+ 3019 | ECDH-ES + | -29 | HKDF - | yes | A128KW | ECDH ES w/ | 3020 | A128KW | | SHA-256 | | | Concat KDF | 3021 | | | | | | and AES Key | 3022 | | | | | | wrap w/ 128 | 3023 | | | | | | bit key | 3024 | | | | | | | 3025 | ECDH-ES + | -30 | HKDF - | yes | A192KW | ECDH ES w/ | 3026 | A192KW | | SHA-256 | | | Concat KDF | 3027 | | | | | | and AES Key | 3028 | | | | | | wrap w/ 192 | 3029 | | | | | | bit key | 3030 | | | | | | | 3031 | ECDH-ES + | -31 | HKDF - | yes | A256KW | ECDH ES w/ | 3032 | A256KW | | SHA-256 | | | Concat KDF | 3033 | | | | | | and AES Key | 3034 | | | | | | wrap w/ 256 | 3035 | | | | | | bit key | 3036 | | | | | | | 3037 | ECDH-SS + | -32 | HKDF - | no | A128KW | ECDH SS w/ | 3038 | A128KW | | SHA-256 | | | Concat KDF | 3039 | | | | | | and AES Key | 3040 | | | | | | wrap w/ 128 | 3041 | | | | | | bit key | 3042 | | | | | | | 3043 | ECDH-SS + | -33 | HKDF - | no | A192KW | ECDH SS w/ | 3044 | A192KW | | SHA-256 | | | Concat KDF | 3045 | | | | | | and AES Key | 3046 | | | | | | wrap w/ 192 | 3047 | | | | | | bit key | 3048 | | | | | | | 3049 | ECDH-SS + | -34 | HKDF - | no | A256KW | ECDH SS w/ | 3050 | A256KW | | SHA-256 | | | Concat KDF | 3051 | | | | | | and AES Key | 3052 | | | | | | wrap w/ 256 | 3053 | | | | | | bit key | 3054 +-----------+-------+---------+------------+--------+---------------+ 3056 Table 20: ECDH Algorithm Values 3058 When using a COSE key for this algorithm, the following checks are 3059 made: 3061 o The 'kty' field MUST be present and it MUST be 'EC2' or 'OKP'. 3063 o If the 'alg' field present, it MUST match the Key Agreement 3064 algorithm being used. 3066 o If the 'key_ops' field is present, it MUST include 'derive key' or 3067 'derive bits' for the private key. 3069 o If the 'key_ops' field is present, it MUST be empty for the public 3070 key. 3072 13. Key Object Parameters 3074 The COSE_Key object defines a way to hold a single key object. It is 3075 still required that the members of individual key types be defined. 3076 This section of the document is where we define an initial set of 3077 members for specific key types. 3079 For each of the key types, we define both public and private members. 3080 The public members are what is transmitted to others for their usage. 3081 Private members allow for the archival of keys by individuals. 3082 However, there are some circumstances in which private keys may be 3083 distributed to entities in a protocol. Examples include: entities 3084 that have poor random number generation, centralized key creation for 3085 multi-cast type operations, and protocols in which a shared secret is 3086 used as a bearer token for authorization purposes. 3088 Key types are identified by the 'kty' member of the COSE_Key object. 3089 In this document, we define four values for the member: 3091 +-----------+-------+--------------------------------------------+ 3092 | name | value | description | 3093 +-----------+-------+--------------------------------------------+ 3094 | OKP | 1 | Octet Key Pair | 3095 | | | | 3096 | EC2 | 2 | Elliptic Curve Keys w/ X,Y Coordinate pair | 3097 | | | | 3098 | Symmetric | 4 | Symmetric Keys | 3099 | | | | 3100 | Reserved | 0 | This value is reserved | 3101 +-----------+-------+--------------------------------------------+ 3103 Table 21: Key Type Values 3105 13.1. Elliptic Curve Keys 3107 Two different key structures could be defined for Elliptic Curve 3108 keys. One version uses both an x and a y coordinate, potentially 3109 with point compression ('EC2'). This is the traditional EC point 3110 representation that is used in [RFC5480]. The other version uses 3111 only the x coordinate as the y coordinate is either to be recomputed 3112 or not needed for the key agreement operation ('OKP'). 3114 Applications MUST check that the curve and the key type are 3115 consistent and reject a key if they are not. 3117 +---------+----------+-------+------------------------------------+ 3118 | name | key type | value | description | 3119 +---------+----------+-------+------------------------------------+ 3120 | P-256 | EC2 | 1 | NIST P-256 also known as secp256r1 | 3121 | | | | | 3122 | P-384 | EC2 | 2 | NIST P-384 also known as secp384r1 | 3123 | | | | | 3124 | P-521 | EC2 | 3 | NIST P-521 also known as secp521r1 | 3125 | | | | | 3126 | X25519 | OKP | 4 | X25519 for use w/ ECDH only | 3127 | | | | | 3128 | X448 | OKP | 5 | X448 for use w/ ECDH only | 3129 | | | | | 3130 | Ed25519 | OKP | 6 | Ed25519 for use w/ EdDSA only | 3131 | | | | | 3132 | Ed448 | OKP | 7 | Ed448 for use w/ EdDSA only | 3133 +---------+----------+-------+------------------------------------+ 3135 Table 22: EC Curves 3137 13.1.1. Double Coordinate Curves 3139 The traditional way of sending EC curves has been to send either both 3140 the x and y coordinates, or the x coordinate and a sign bit for the y 3141 coordinate. The latter encoding has not been recommended in the IETF 3142 due to potential IPR issues. However, for operations in constrained 3143 environments, the ability to shrink a message by not sending the y 3144 coordinate is potentially useful. 3146 For EC keys with both coordinates, the 'kty' member is set to 2 3147 (EC2). The key parameters defined in this section are summarized in 3148 Table 23. The members that are defined for this key type are: 3150 crv contains an identifier of the curve to be used with the key. 3151 The curves defined in this document for this key type can be found 3152 in Table 22. Other curves may be registered in the future and 3153 private curves can be used as well. 3155 x contains the x coordinate for the EC point. The integer is 3156 converted to an octet string as defined in [SEC1]. Leading zero 3157 octets MUST be preserved. 3159 y contains either the sign bit or the value of y coordinate for the 3160 EC point. When encoding the value y, the integer is converted to 3161 an octet string (as defined in [SEC1]) and encoded as a CBOR bstr. 3162 Leading zero octets MUST be preserved. The compressed point 3163 encoding is also supported. Compute the sign bit as laid out in 3164 the Elliptic-Curve-Point-to-Octet-String Conversion function of 3165 [SEC1]. If the sign bit is zero, then encode y as a CBOR false 3166 value, otherwise encode y as a CBOR true value. The encoding of 3167 the infinity point is not supported. 3169 d contains the private key. 3171 For public keys, it is REQUIRED that 'crv', 'x' and 'y' be present in 3172 the structure. For private keys, it is REQUIRED that 'crv' and 'd' 3173 be present in the structure. For private keys, it is RECOMMENDED 3174 that 'x' and 'y' also be present, but they can be recomputed from the 3175 required elements and omitting them saves on space. 3177 +------+-------+-------+---------+----------------------------------+ 3178 | name | key | value | type | description | 3179 | | type | | | | 3180 +------+-------+-------+---------+----------------------------------+ 3181 | crv | 2 | -1 | int / | EC Curve identifier - Taken from | 3182 | | | | tstr | the COSE Curves registry | 3183 | | | | | | 3184 | x | 2 | -2 | bstr | X Coordinate | 3185 | | | | | | 3186 | y | 2 | -3 | bstr / | Y Coordinate | 3187 | | | | bool | | 3188 | | | | | | 3189 | d | 2 | -4 | bstr | Private key | 3190 +------+-------+-------+---------+----------------------------------+ 3192 Table 23: EC Key Parameters 3194 13.2. Octet Key Pair 3196 A new key type is defined for Octet Key Pairs (OKP). Do not assume 3197 that keys using this type are elliptic curves. This key type could 3198 be used for other curve types (for example, mathematics based on 3199 hyper-elliptic surfaces). 3201 The key parameters defined in this section are summarized in 3202 Table 24. The members that are defined for this key type are: 3204 crv contains an identifier of the curve to be used with the key. 3205 The curves defined in this document for this key type can be found 3206 in Table 22. Other curves may be registered in the future and 3207 private curves can be used as well. 3209 x contains the x coordinate for the EC point. The octet string 3210 represents a little-endian encoding of x. 3212 d contains the private key. 3214 For public keys, it is REQUIRED that 'crv' and 'x' be present in the 3215 structure. For private keys, it is REQUIRED that 'crv' and 'd' be 3216 present in the structure. For private keys, it is RECOMMENDED that 3217 'x' also be present, but it can be recomputed from the required 3218 elements and omitting it saves on space. 3220 +------+------+-------+-------+-------------------------------------+ 3221 | name | key | value | type | description | 3222 | | type | | | | 3223 +------+------+-------+-------+-------------------------------------+ 3224 | crv | 1 | -1 | int / | EC Curve identifier - Taken from | 3225 | | | | tstr | the COSE Key Common Parameters | 3226 | | | | | registry | 3227 | | | | | | 3228 | x | 1 | -2 | bstr | X Coordinate | 3229 | | | | | | 3230 | d | 1 | -4 | bstr | Private key | 3231 +------+------+-------+-------+-------------------------------------+ 3233 Table 24: EC Key Parameters 3235 13.3. Symmetric Keys 3237 Occasionally it is required that a symmetric key be transported 3238 between entities. This key structure allows for that to happen. 3240 For symmetric keys, the 'kty' member is set to 3 (Symmetric). The 3241 member that is defined for this key type is: 3243 k contains the value of the key. 3245 This key structure does not have a form that contains only public 3246 members. As it is expected that this key structure is going to be 3247 transmitted, care must be taking that it is never transmitted 3248 accidentally or insecurely. For symmetric keys, it is REQUIRED that 3249 'k' be present in the structure. 3251 +------+----------+-------+------+-------------+ 3252 | name | key type | value | type | description | 3253 +------+----------+-------+------+-------------+ 3254 | k | 4 | -1 | bstr | Key Value | 3255 +------+----------+-------+------+-------------+ 3257 Table 25: Symmetric Key Parameters 3259 14. CBOR Encoder Restrictions 3261 There has been an attempt to limit the number of places where the 3262 document needs to impose restrictions on how the CBOR Encoder needs 3263 to work. We have managed to narrow it down to the following 3264 restrictions: 3266 o The restriction applies to the encoding the Sig_structure, the 3267 Enc_structure, and the MAC_structure. 3269 o The rules for Canonical CBOR (Section 3.9 of RFC 7049) MUST be 3270 used in these locations. The main rule that needs to be enforced 3271 is that all lengths in these structures MUST be encoded such that 3272 they are encoded using definite lengths and the minimum length 3273 encoding is used. 3275 o Applications MUST NOT generate messages with the same label used 3276 twice as a key in a single map. Applications MUST NOT parse and 3277 process messages with the same label used twice as a key in a 3278 single map. Applications can enforce the parse and process 3279 requirement by using parsers that will fail the parse step or by 3280 using parsers that will pass all keys to the application and the 3281 application can perform the check for duplicate keys. 3283 15. Application Profiling Considerations 3285 This document is designed to provide a set of security services, but 3286 not to provide implementation requirements for specific usage. The 3287 interoperability requirements are provided for how each of the 3288 individual services are used and how the algorithms are to be used 3289 for interoperability. The requirements about which algorithms and 3290 which services are needed are deferred to each application. 3292 Applications are therefore intended to profile the usage of this 3293 document. This section provides a set of guidelines and topics that 3294 applications need to consider when using this document. 3296 o Applications need to determine the set of messages defined in this 3297 document that they will be using. The set of messages corresponds 3298 fairly directly to the set of security services that are needed 3299 and to the security levels needed. 3301 o Applications may define new header parameters for a specific 3302 purpose. Applications will often times select specific header 3303 parameters to use or not to use. For example, an application 3304 would normally state a preference for using either the IV or the 3305 partial IV parameter. If the partial IV parameter is specified, 3306 then the application would also need to define how the fixed 3307 portion of the IV would be determined. 3309 o When applications use externally defined authenticated data, they 3310 need to define how that data is encoded. This document assumes 3311 that the data will be provided as a byte stream. More information 3312 can be found in Section 4.3. 3314 o Applications need to determine the set of security algorithms that 3315 are to be used. When selecting the algorithms to be used as the 3316 mandatory to implement set, consideration should be given to 3317 choosing different types of algorithms when two are chosen for a 3318 specific purpose. An example of this would be choosing HMAC- 3319 SHA512 and AES-CMAC as different MAC algorithms; the construction 3320 is vastly different between these two algorithms. This means that 3321 a weakening of one algorithm would be unlikely to lead to a 3322 weakening of the other algorithms. Of course, these algorithms do 3323 not provide the same level of security and thus may not be 3324 comparable for the desired security functionality. 3326 o Applications may need to provide some type of negotiation or 3327 discovery method if multiple algorithms or message structures are 3328 permitted. The method can be as simple as requiring 3329 preconfiguration of the set of algorithms to providing a discovery 3330 method built into the protocol. S/MIME provided a number of 3331 different ways to approach the problem that applications could 3332 follow: 3334 * Advertising in the message (S/MIME capabilities) [RFC5751]. 3336 * Advertising in the certificate (capabilities extension) 3337 [RFC4262]. 3339 * Minimum requirements for the S/MIME, which have been updated 3340 over time [RFC2633][RFC5751]. 3342 16. IANA Considerations 3344 16.1. CBOR Tag assignment 3346 It is requested that IANA assign the following tags from the "Concise 3347 Binary Object Representation (CBOR) Tags" registry. It is requested 3348 that the tags for COSE_Sign1, COSE_Encrypt0, and COSE_Mac0 be 3349 assigned in the 1 to 23 value range (one byte long when encoded). It 3350 is requested that the rest of the tags be assigned in the 24 to 255 3351 value range (two bytes long when encoded). 3353 The tags to be assigned are in Table 1. 3355 16.2. COSE Header Parameters Registry 3357 It is requested that IANA create a new registry entitled "COSE Header 3358 Parameters". The registry is to be created as Expert Review 3359 Required. Expert review guidelines are provided in Section 16.10. 3361 The columns of the registry are: 3363 name The name is present to make it easier to refer to and discuss 3364 the registration entry. The value is not used in the protocol. 3365 Names are to be unique in the table. 3367 label This is the value used for the label. The label can be either 3368 an integer or a string. Registration in the table is based on the 3369 value of the label requested. Integer values between 1 and 255 3370 and strings of length 1 are designated as Standards Track Document 3371 required. Integer values from 256 to 65535 and strings of length 3372 2 are designated as Specification Required. Integer values of 3373 greater than 65535 and strings of length greater than 2 are 3374 designated as expert review. Integer values in the range -1 to 3375 -65536 are delegated to the "COSE Header Algorithm Labels" 3376 registry. Integer values less than -65536 are marked as private 3377 use. 3379 value This contains the CBOR type for the value portion of the 3380 label. 3382 value registry This contains a pointer to the registry used to 3383 contain values where the set is limited. 3385 description This contains a brief description of the header field. 3387 specification This contains a pointer to the specification defining 3388 the header field (where public). 3390 The initial contents of the registry can be found in Table 2 and 3391 Table 27. The specification column for all rows in that table should 3392 be this document. 3394 Additionally, the label of 0 is to be marked as 'Reserved'. 3396 16.3. COSE Header Algorithm Labels Registry 3398 It is requested that IANA create a new registry entitled "COSE Header 3399 Algorithm Labels". The registry is to be created as Expert Review 3400 Required. Expert review guidelines are provided in Section 16.10. 3402 The columns of the registry are: 3404 name The name is present to make it easier to refer to and discuss 3405 the registration entry. The value is not used in the protocol. 3407 algorithm The algorithm(s) that this registry entry is used for. 3408 This value is taken from the "COSE Algorithm Values" registry. 3409 Multiple algorithms can be specified in this entry. For the 3410 table, the algorithm, label pair MUST be unique. 3412 label This is the value used for the label. The label is an integer 3413 in the range of -1 to -65536. 3415 value This contains the CBOR type for the value portion of the 3416 label. 3418 value registry This contains a pointer to the registry used to 3419 contain values where the set is limited. 3421 description This contains a brief description of the header field. 3423 specification This contains a pointer to the specification defining 3424 the header field (where public). 3426 The initial contents of the registry can be found in Table 13, 3427 Table 14, and Table 19. The specification column for all rows in 3428 that table should be this document. 3430 16.4. COSE Algorithms Registry 3432 It is requested that IANA create a new registry entitled "COSE 3433 Algorithms Registry". The registry is to be created as Expert Review 3434 Required. Expert review guidelines are provided in Section 16.10. 3436 The columns of the registry are: 3438 value The value to be used to identify this algorithm. Algorithm 3439 values MUST be unique. The value can be a positive integer, a 3440 negative integer or a string. Integer values between -256 and 255 3441 and strings of length 1 are designated as Standards Track Document 3442 required. Integer values from -65536 to 65535 and strings of 3443 length 2 are designated as Specification Required. Integer values 3444 of greater than 65535 and strings of length greater than 2 are 3445 designated as expert review. Integer values less than -65536 are 3446 marked as private use. 3448 description A short description of the algorithm. 3450 specification A document where the algorithm is defined (if publicly 3451 available). 3453 The initial contents of the registry can be found in Table 10, 3454 Table 9, Table 11, Table 5, Table 7, Table 8, Table 15, Table 16, 3455 Table 17, and Table 18. The specification column for all rows in 3456 that table should be this document. 3458 NOTE: The assignment of algorithm identifiers in this document was 3459 done so that positive numbers were used for the first layer objects 3460 (COSE_Sign, COSE_Sign1, COSE_Encrypt, COSE_Encrypt0, COSE_Mac, and 3461 COSE_Mac0). Negative numbers were used for second layer objects 3462 (COSE_Signature and COSE_recipient). Expert reviewers should 3463 consider this practice, but are not expected to be restricted by this 3464 precedent. 3466 16.5. COSE Key Common Parameters Registry 3468 It is requested that IANA create a new registry entitled "COSE Key 3469 Common Parameters" registry. The registry is to be created as Expert 3470 Review Required. Expert review guidelines are provided in 3471 Section 16.10. 3473 The columns of the registry are: 3475 name This is a descriptive name that enables easier reference to the 3476 item. It is not used in the encoding. 3478 label The value to be used to identify this algorithm. Key map 3479 labels MUST be unique. The label can be a positive integer, a 3480 negative integer or a string. Integer values between 0 and 255 3481 and strings of length 1 are designated as Standards Track Document 3482 required. Integer values from 256 to 65535 and strings of length 3483 2 are designated as Specification Required. Integer values of 3484 greater than 65535 and strings of length greater than 2 are 3485 designated as expert review. Integer values in the range -1 to 3486 -65536 are used for key parameters specific to a single algorithm 3487 delegated to the "COSE Key Type Parameter Labels" registry. 3488 Integer values less than -65536 are marked as private use. 3490 CBOR Type This field contains the CBOR type for the field. 3492 registry This field denotes the registry that values come from, if 3493 one exists. 3495 description This field contains a brief description for the field. 3497 specification This contains a pointer to the public specification 3498 for the field if one exists 3500 This registry will be initially populated by the values in 3501 Section 7.1. The specification column for all of these entries will 3502 be this document. 3504 16.6. COSE Key Type Parameters Registry 3506 It is requested that IANA create a new registry "COSE Key Type 3507 Parameters". The registry is to be created as Expert Review 3508 Required. Expert review guidelines are provided in Section 16.10. 3510 The columns of the table are: 3512 key type This field contains a descriptive string of a key type. 3513 This should be a value that is in the COSE Key Common Parameters 3514 table and is placed in the 'kty' field of a COSE Key structure. 3516 name This is a descriptive name that enables easier reference to the 3517 item. It is not used in the encoding. 3519 label The label is to be unique for every value of key type. The 3520 range of values is from -256 to -1. Labels are expected to be 3521 reused for different keys. 3523 CBOR type This field contains the CBOR type for the field. 3525 description This field contains a brief description for the field. 3527 specification This contains a pointer to the public specification 3528 for the field if one exists. 3530 This registry will be initially populated by the values in Table 23 3531 and Table 25. The specification column for all of these entries will 3532 be this document. 3534 16.7. COSE Elliptic Curve Parameters Registry 3536 It is requested that IANA create a new registry "COSE Elliptic Curve 3537 Parameters". The registry is to be created as Expert Review 3538 Required. Expert review guidelines are provided in Section 16.10. 3540 The columns of the table are: 3542 name This is a descriptive name that enables easier reference to the 3543 item. It is not used in the encoding. 3545 value This is the value used to identify the curve. These values 3546 MUST be unique. The integer values from -256 to 255 are 3547 designated as Standards Track Document Required. The integer 3548 values from 256 to 65535 and -65536 to -257 are designated as 3549 Specification Required. Integer values over 65535 are designated 3550 as expert review. Integer values less than -65536 are marked as 3551 private use. 3553 key type This designates the key type(s) that can be used with this 3554 curve. 3556 description This field contains a brief description of the curve. 3558 specification This contains a pointer to the public specification 3559 for the curve if one exists. 3561 This registry will be initially populated by the values in Table 21. 3562 The specification column for all of these entries will be this 3563 document. 3565 16.8. Media Type Registrations 3567 16.8.1. COSE Security Message 3569 This section registers the "application/cose" media type in the 3570 "Media Types" registry. These media types are used to indicate that 3571 the content is a COSE_MSG. 3573 Type name: application 3575 Subtype name: cose 3577 Required parameters: N/A 3579 Optional parameters: cose-type 3581 Encoding considerations: binary 3582 Security considerations: See the Security Considerations section 3583 of RFC TBD. 3585 Interoperability considerations: N/A 3587 Published specification: RFC TBD 3589 Applications that use this media type: To be identified 3591 Fragment identifier considerations: N/A 3593 Additional information: 3595 * Magic number(s): N/A 3597 * File extension(s): cbor 3599 * Macintosh file type code(s): N/A 3601 Person & email address to contact for further information: 3602 iesg@ietf.org 3604 Intended usage: COMMON 3606 Restrictions on usage: N/A 3608 Author: Jim Schaad, ietf@augustcellars.com 3610 Change Controller: IESG 3612 Provisional registration? No 3614 16.8.2. COSE Key media type 3616 This section registers the "application/cose-key" and "application/ 3617 cose-key-set" media types in the "Media Types" registry. These media 3618 types are used to indicate, respectively, that content is a COSE_Key 3619 or COSE_KeySet object. 3621 Type name: application 3623 Subtype name: cose-key 3625 Required parameters: N/A 3627 Optional parameters: N/A 3629 Encoding considerations: binary 3630 Security considerations: See the Security Considerations section 3631 of RFC TBD. 3633 Interoperability considerations: N/A 3635 Published specification: RFC TBD 3637 Applications that use this media type: To be identified 3639 Fragment identifier considerations: N/A 3641 Additional information: 3643 * Magic number(s): N/A 3645 * File extension(s): cbor 3647 * Macintosh file type code(s): N/A 3649 Person & email address to contact for further information: 3650 iesg@ietf.org 3652 Intended usage: COMMON 3654 Restrictions on usage: N/A 3656 Author: Jim Schaad, ietf@augustcellars.com 3658 Change Controller: IESG 3660 Provisional registration? No 3662 Type name: application 3664 Subtype name: cose-key-set 3666 Required parameters: N/A 3668 Optional parameters: N/A 3670 Encoding considerations: binary 3672 Security considerations: See the Security Considerations section 3673 of RFC TBD. 3675 Interoperability considerations: N/A 3677 Published specification: RFC TBD 3678 Applications that use this media type: To be identified 3680 Fragment identifier considerations: N/A 3682 Additional information: 3684 * Magic number(s): N/A 3686 * File extension(s): cbor 3688 * Macintosh file type code(s): N/A 3690 Person & email address to contact for further information: 3691 iesg@ietf.org 3693 Intended usage: COMMON 3695 Restrictions on usage: N/A 3697 Author: Jim Schaad, ietf@augustcellars.com 3699 Change Controller: IESG 3701 Provisional registration? No 3703 16.9. CoAP Content Format Registrations 3705 This section registers a set of content formats for CoAP. ID 3706 assignment in the 24-255 range is requested. 3708 +---------------------------------+----------+-------+--------------+ 3709 | Media Type | Encoding | ID | Reference | 3710 +---------------------------------+----------+-------+--------------+ 3711 | application/cose; cose-type | | TBD10 | [This | 3712 | ="cose-sign" | | | Document] | 3713 | | | | | 3714 | application/cose; cose-type | | TBD11 | [This | 3715 | ="cose-sign1" | | | Document] | 3716 | | | | | 3717 | application/cose; cose-type | | TBD12 | [This | 3718 | ="cose-encrypt" | | | Document] | 3719 | | | | | 3720 | application/cose; cose-type | | TBD13 | [This | 3721 | ="cose-encrypt1" | | | Document] | 3722 | | | | | 3723 | application/cose; cose-type | | TBD14 | [This | 3724 | ="cose-mac" | | | Document] | 3725 | | | | | 3726 | application/cose; cose-type | | TBD15 | [This | 3727 | ="cose-mac0" | | | Document] | 3728 | | | | | 3729 | application/cose-key | | TBD16 | [This | 3730 | | | | Document] | 3731 | | | | | 3732 | application/cose-key-set | | TBD17 | [This | 3733 | | | | Document | 3734 +---------------------------------+----------+-------+--------------+ 3736 Table 26 3738 16.10. Expert Review Instructions 3740 All of the IANA registries established in this document are defined 3741 as expert review. This section gives some general guidelines for 3742 what the experts should be looking for, but they are being designated 3743 as experts for a reason so they should be given substantial latitude. 3745 Expert reviewers should take into consideration the following points: 3747 o Point squatting should be discouraged. Reviewers are encouraged 3748 to get sufficient information for registration requests to ensure 3749 that the usage is not going to duplicate one that is already 3750 registered and that the point is likely to be used in deployments. 3751 The zones tagged as private use are intended for testing purposes 3752 and closed environments, code points in other ranges should not be 3753 assigned for testing. 3755 o Specifications are required for the standards track range of point 3756 assignment. Specifications should exist for specification 3757 required ranges, but early assignment before a specification is 3758 available is considered to be permissible. Specifications are 3759 needed for the first-come, first-serve range if they are expected 3760 to be used outside of closed environments in an interoperable way. 3761 When specifications are not provided, the description provided 3762 needs to have sufficient information to identify what the point is 3763 being used for. 3765 o Experts should take into account the expected usage of fields when 3766 approving point assignment. The fact that there is a range for 3767 standards track documents does not mean that a standards track 3768 document cannot have points assigned outside of that range. Some 3769 of the ranges are restricted in range, items that are not expected 3770 to be common or are not expected to be used in restricted 3771 environments should be assigned to values which will encode to 3772 longer byte strings. 3774 o When algorithms are registered, vanity registrations should be 3775 discouraged. One way to do this is to require applications to 3776 provide additional documentation on security analysis of 3777 algorithms. Another thing that should be considered is to request 3778 for an opinion on the algorithm from the Cryptographic Forum 3779 Research Group. Algorithms that do not meet the security 3780 requirements of the community and the messages structures should 3781 not be registered. 3783 17. Implementation Status 3785 This section records the status of known implementations of the 3786 protocol defined by this specification at the time of posting of this 3787 Internet-Draft, and is based on a proposal described in [RFC6982]. 3788 The description of implementations in this section is intended to 3789 assist the IETF in its decision processes in progressing drafts to 3790 RFCs. Please note that the listing of any individual implementation 3791 here does not imply endorsement by the IETF. Furthermore, no effort 3792 has been spent to verify the information presented here that was 3793 supplied by IETF contributors. This is not intended as, and must not 3794 be construed to be, a catalog of available implementations or their 3795 features. Readers are advised to note that other implementations may 3796 exist. 3798 According to [RFC6982], "this will allow reviewers and working groups 3799 to assign due consideration to documents that have the benefit of 3800 running code, which may serve as evidence of valuable experimentation 3801 and feedback that have made the implemented protocols more mature. 3803 It is up to the individual working groups to use this information as 3804 they see fit". 3806 17.1. Author's Versions 3808 There are three different implementations that have been created by 3809 the author of the document both to create the examples that are 3810 included in the document and to validate the structures and 3811 methodology used in the design of COSE. 3813 Implementation Location: https://github.com/cose-wg 3815 Primary Maintainer: Jim Schaad 3817 Languages: There are three different languages that are currently 3818 supported: Java, C# and C. 3820 Cryptography: The Java and C# libraries use Bouncy Castle to 3821 provide the required cryptography. The C version uses OPENSSL 3822 Version 1.0 for the cryptography. 3824 Coverage: The libraries currently do not have full support for 3825 counter signatures of either variety. They do have support to 3826 allow for implicit algorithm support as they allow for the 3827 application to set attributes that are not to be sent in the 3828 message. 3830 Testing: All of the examples in the example library are generated 3831 by the C# library and then validated using the Java and C 3832 libraries. All three libraries have tests to allow for the 3833 creating of the same messages that are in the example library 3834 followed by validating them. These are not compared against the 3835 example library. The Java and C# libraries have unit testing 3836 included. Not all of the MUST statements in the document have 3837 been implemented as part of the libraries. One such statement is 3838 the requirement that unique labels be present. 3840 Licensing: Revised BSD License 3842 17.2. COSE Testing Library 3844 Implementation Location: https://github.com/cose-wg/Examples 3846 Primary Maintainer: Jim Schaad 3848 Description: A set of tests for the COSE library is provided as 3849 part of the implementation effort. Both success and fail tests 3850 have been provided. All of the examples in this document are part 3851 of this example set. 3853 Coverage: An attempt has been made to have test cases for every 3854 message type and algorithm in the document. Currently examples 3855 dealing with counter signatures, EdDSA, and ECDH with Curve24459 3856 and Goldilocks are missing. 3858 Licensing: Public Domain 3860 18. Security Considerations 3862 There are a number of security considerations that need to be taken 3863 into account by implementers of this specification. The security 3864 considerations that are specific to an individual algorithm are 3865 placed next to the description of the algorithm. While some 3866 considerations have been highlighted here, additional considerations 3867 may be found in the documents listed in the references. 3869 Implementations need to protect the private key for any individuals. 3870 There are some cases in this document that need to be highlighted on 3871 this issue. 3873 o Using the same key for two different algorithms can leak 3874 information about the key. It is therefore recommended that keys 3875 be restricted to a single algorithm. 3877 o Use of 'direct' as a recipient algorithm combined with a second 3878 recipient algorithm, either directly in a separate message, 3879 exposes the direct key to the second recipient. 3881 o Several of the algorithms in this document have limits on the 3882 number of times that a key can be used without leaking information 3883 about the key. 3885 The use of ECDH and direct plus KDF (with no key wrap) will not 3886 directly lead to the private key being leaked; the one way function 3887 of the KDF will prevent that. There is however, a different issue 3888 that needs to be addressed. Having two recipients requires that the 3889 CEK be shared between two recipients. The second recipient therefore 3890 has a CEK that was derived from material that can be used for the 3891 weak proof of origin. The second recipient could create a message 3892 using the same CEK and send it to the first recipient, the first 3893 recipient would, for either static-static ECDH or direct plus KDF, 3894 make an assumption that the CEK could be used for proof of origin 3895 even though it is from the wrong entity. If the key wrap step is 3896 added, then no proof of origin is implied and this is not an issue. 3898 Although it has been mentioned before, the use of a single key for 3899 multiple algorithms has been demonstrated in some cases to leak 3900 information about a key, provide for attackers to forge integrity 3901 tags, or gain information about encrypted content. Binding a key to 3902 a single algorithm prevents these problems. Key creators and key 3903 consumers are strongly encouraged not only to create new keys for 3904 each different algorithm, but to include that selection of algorithm 3905 in any distribution of key material and strictly enforce the matching 3906 of algorithms in the key structure to algorithms in the message 3907 structure. In addition to checking that algorithms are correct, the 3908 key form needs to be checked as well. Do not use an 'EC2' key where 3909 an 'OKP' key is expected. 3911 Before using a key for transmission, or before acting on information 3912 received, a trust decision on a key needs to be made. Is the data or 3913 action something that the entity associated with the key has a right 3914 to see or a right to request? A number of factors are associated 3915 with this trust decision. Some of the ones that are highlighted here 3916 are: 3918 o What are the permissions associated with the key owner? 3920 o Is the cryptographic algorithm acceptable in the current context? 3922 o Have the restrictions associated with the key, such as algorithm 3923 or freshness, been checked and are correct? 3925 o Is the request something that is reasonable, given the current 3926 state of the application? 3928 o Have any security considerations that are part of the message been 3929 enforced (as specified by the application or crit parameter)? 3931 One area that has been starting to get exposure is doing traffic 3932 analysis of encrypted messages based on the length of the message. 3933 This specification does not provide for a uniform method of providing 3934 padding as part of the message structure. An observer can 3935 distinguish between two different strings (for example, 'YES' and 3936 'NO') based on length for all of the content encryption algorithms 3937 that are defined in this document. This means that it is up to 3938 applications to document how content padding is to be done in order 3939 to prevent or discourage such analysis. (For example, the strings 3940 could be defined as 'YES' and 'NO '.) 3942 19. References 3944 19.1. Normative References 3946 [AES-GCM] Dworkin, M., "NIST Special Publication 800-38D: 3947 Recommendation for Block Cipher Modes of Operation: 3948 Galois/Counter Mode (GCM) and GMAC.", Nov 2007. 3950 [DSS] U.S. National Institute of Standards and Technology, 3951 "Digital Signature Standard (DSS)", July 2013. 3953 [MAC] NiST, N., "FIPS PUB 113: Computer Data Authentication", 3954 May 1985. 3956 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 3957 Hashing for Message Authentication", RFC 2104, 3958 DOI 10.17487/RFC2104, February 1997, 3959 . 3961 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3962 Requirement Levels", BCP 14, RFC 2119, 3963 DOI 10.17487/RFC2119, March 1997, 3964 . 3966 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 3967 (AES) Key Wrap Algorithm", RFC 3394, DOI 10.17487/RFC3394, 3968 September 2002, . 3970 [RFC3610] Whiting, D., Housley, R., and N. Ferguson, "Counter with 3971 CBC-MAC (CCM)", RFC 3610, DOI 10.17487/RFC3610, September 3972 2003, . 3974 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 3975 Key Derivation Function (HKDF)", RFC 5869, 3976 DOI 10.17487/RFC5869, May 2010, 3977 . 3979 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 3980 Curve Cryptography Algorithms", RFC 6090, 3981 DOI 10.17487/RFC6090, February 2011, 3982 . 3984 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 3985 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 3986 October 2013, . 3988 [RFC7539] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF 3989 Protocols", RFC 7539, DOI 10.17487/RFC7539, May 2015, 3990 . 3992 [SEC1] Standards for Efficient Cryptography Group, "SEC 1: 3993 Elliptic Curve Cryptography", May 2009. 3995 19.2. Informative References 3997 [I-D.greevenbosch-appsawg-cbor-cddl] 3998 Vigano, C. and H. Birkholz, "CBOR data definition language 3999 (CDDL): a notational convention to express CBOR data 4000 structures", draft-greevenbosch-appsawg-cbor-cddl-08 (work 4001 in progress), March 2016. 4003 [I-D.irtf-cfrg-eddsa] 4004 Josefsson, S. and I. Liusvaara, "Edwards-curve Digital 4005 Signature Algorithm (EdDSA)", draft-irtf-cfrg-eddsa-05 4006 (work in progress), March 2016. 4008 [PVSig] Brown, D. and D. Johnson, "Formal Security Proofs for a 4009 Signature Scheme with Partial Message Recover", February 4010 2000. 4012 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 4013 Extensions (MIME) Part One: Format of Internet Message 4014 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, 4015 . 4017 [RFC2633] Ramsdell, B., Ed., "S/MIME Version 3 Message 4018 Specification", RFC 2633, DOI 10.17487/RFC2633, June 1999, 4019 . 4021 [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography 4022 Specification Version 2.0", RFC 2898, 4023 DOI 10.17487/RFC2898, September 2000, 4024 . 4026 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 4027 Standards (PKCS) #1: RSA Cryptography Specifications 4028 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 4029 2003, . 4031 [RFC4231] Nystrom, M., "Identifiers and Test Vectors for HMAC-SHA- 4032 224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512", 4033 RFC 4231, DOI 10.17487/RFC4231, December 2005, 4034 . 4036 [RFC4262] Santesson, S., "X.509 Certificate Extension for Secure/ 4037 Multipurpose Internet Mail Extensions (S/MIME) 4038 Capabilities", RFC 4262, DOI 10.17487/RFC4262, December 4039 2005, . 4041 [RFC4493] Song, JH., Poovendran, R., Lee, J., and T. Iwata, "The 4042 AES-CMAC Algorithm", RFC 4493, DOI 10.17487/RFC4493, June 4043 2006, . 4045 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 4046 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 4047 . 4049 [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, 4050 "Elliptic Curve Cryptography Subject Public Key 4051 Information", RFC 5480, DOI 10.17487/RFC5480, March 2009, 4052 . 4054 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 4055 RFC 5652, DOI 10.17487/RFC5652, September 2009, 4056 . 4058 [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet 4059 Mail Extensions (S/MIME) Version 3.2 Message 4060 Specification", RFC 5751, DOI 10.17487/RFC5751, January 4061 2010, . 4063 [RFC5752] Turner, S. and J. Schaad, "Multiple Signatures in 4064 Cryptographic Message Syntax (CMS)", RFC 5752, 4065 DOI 10.17487/RFC5752, January 2010, 4066 . 4068 [RFC5990] Randall, J., Kaliski, B., Brainard, J., and S. Turner, 4069 "Use of the RSA-KEM Key Transport Algorithm in the 4070 Cryptographic Message Syntax (CMS)", RFC 5990, 4071 DOI 10.17487/RFC5990, September 2010, 4072 . 4074 [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations 4075 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 4076 RFC 6151, DOI 10.17487/RFC6151, March 2011, 4077 . 4079 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 4080 Algorithm (DSA) and Elliptic Curve Digital Signature 4081 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 4082 2013, . 4084 [RFC6982] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 4085 Code: The Implementation Status Section", RFC 6982, 4086 DOI 10.17487/RFC6982, July 2013, 4087 . 4089 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 4090 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 4091 2014, . 4093 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 4094 Application Protocol (CoAP)", RFC 7252, 4095 DOI 10.17487/RFC7252, June 2014, 4096 . 4098 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 4099 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 4100 2015, . 4102 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 4103 RFC 7516, DOI 10.17487/RFC7516, May 2015, 4104 . 4106 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 4107 DOI 10.17487/RFC7517, May 2015, 4108 . 4110 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 4111 DOI 10.17487/RFC7518, May 2015, 4112 . 4114 [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 4115 for Security", RFC 7748, DOI 10.17487/RFC7748, January 4116 2016, . 4118 [SP800-56A] 4119 Barker, E., Chen, L., Roginsky, A., and M. Smid, "NIST 4120 Special Publication 800-56A: Recommendation for Pair-Wise 4121 Key Establishment Schemes Using Discrete Logarithm 4122 Cryptography", May 2013. 4124 Appendix A. Making Mandatory Algorithm Header Optional 4126 There has been a portion of the working group who have expressed a 4127 strong desire to relax the rule that the algorithm identifier be 4128 required to appear in each level of a COSE object. There are two 4129 basic reasons that have been advanced to support this position. 4130 First, the resulting message will be smaller if the algorithm 4131 identifier is omitted from the most common messages in a CoAP 4132 environment. Second, there is a potential bug that will arise if 4133 full checking is not done correctly between the different places that 4134 an algorithm identifier could be placed (the message itself, an 4135 application statement, the key structure that the sender possesses 4136 and the key structure the recipient possesses). 4138 This appendix lays out how such a change can be made and the details 4139 that an application needs to specify in order to use this option. 4140 Two different sets of details are specified: Those needed to omit an 4141 algorithm identifier and those needed to use a variant on the counter 4142 signature attribute that contains no attributes about itself. 4144 A.1. Algorithm Identification 4146 In this section are laid out three sets of recommendations. The 4147 first set of recommendations apply to having an implicit algorithm 4148 identified for a single layer of a COSE object. The second set of 4149 recommendations apply to having multiple implicit algorithms 4150 identified for multiple layers of a COSE object. The third set of 4151 recommendations apply to having implicit algorithms for multiple COSE 4152 object constructs. 4154 RFC 2119 language is deliberately not used here. This specification 4155 can provide recommendations, but it cannot enforce them. 4157 This set of recommendations applies to the case where an application 4158 is distributing a fixed algorithm along with the key information for 4159 use in a single COSE object. This normally applies to the smallest 4160 of the COSE objects, specifically COSE_Sign1, COSE_Mac0, and 4161 COSE_Encrypt0, but could apply to the other structures as well. 4163 The following items should be taken into account: 4165 o Applications need to list the set of COSE structures that implicit 4166 algorithms are to be used in. Applications need to require that 4167 the receipt of an explicit algorithm identifier in one of these 4168 structures will lead to the message being rejected. This 4169 requirement is stated so that there will never be a case where 4170 there is any ambiguity about the question of which algorithm 4171 should be used, the implicit or the explicit one. This applies 4172 even if the transported algorithm identifier is a protected 4173 attribute. This applies even if the transported algorithm is the 4174 same as the implicit algorithm. 4176 o Applications need to define the set of information that is to be 4177 considered to be part of a context when omitting algorithm 4178 identifiers. At a minimum, this would be the key identifier (if 4179 needed), the key, the algorithm, and the COSE structure it can be 4180 used for. Applications should restrict the use of a single key to 4181 a single algorithm. As noted for some of the algorithms in this 4182 document, the use of the same key in different related algorithms 4183 can lead to leakage of information about the key, leakage about 4184 the data or the ability to perform forgeries. 4186 o In many cases, applications that make the algorithm identifier 4187 implicit will also want to make the context identifier implicit 4188 for the same reason. That is, omitting the context identifier 4189 will decrease the message size (potentially significantly 4190 depending on the length of the identifier). Applications that do 4191 this will need to describe the circumstances where the context 4192 identifier is to be omitted and how the context identifier is to 4193 be inferred in these cases. (Exhaustive search over all of the 4194 keys would normally not be considered to be acceptable.) An 4195 example of how this can be done is to tie the context to a 4196 transaction identifier. Both would be sent on the original 4197 message, but only the transaction identifier would need to be sent 4198 after that point as the context is tied into the transaction 4199 identifier. Another way would be to associate a context with a 4200 network address. All messages coming from a single network 4201 address can be assumed to be associated with a specific context. 4202 (In this case the address would normally be distributed as part of 4203 the context.) 4205 o Applications cannot rely on key identifiers being unique unless 4206 they take significant efforts to ensure that they are computed in 4207 such a way as to create this guarantee. Even when an application 4208 does this, the uniqueness might be violated if the application is 4209 run in different contexts (i.e., with a different context 4210 provider) or if the system combines the security contexts from 4211 different applications together into a single store. 4213 o Applications should continue the practice of protecting the 4214 algorithm identifier. Since this is not done by placing it in the 4215 protected attributes field, applications should define an 4216 application specific external data structure that includes this 4217 value. This external data field can be used as such for content 4218 encryption, MAC, and signature algorithms. It can be used in the 4219 SuppPrivInfo field for those algorithms which use a KDF function 4220 to derive a key value. Applications may also want to protect 4221 other information that is part of the context structure as well. 4222 It should be noted that those fields, such as the key or a base 4223 IV, are protected by virtue of being used in the cryptographic 4224 computation and do not need to be included in the external data 4225 field. 4227 The second case is having multiple implicit algorithm identifiers 4228 specified for a multiple layer COSE object. An example of how this 4229 would work is the encryption context that an application specifies 4230 contains a content encryption algorithm, a key wrap algorithm, a key 4231 identifier, and a shared secret. The sender omits sending the 4232 algorithm identifier for both the content layer and the recipient 4233 layer leaving only the key identifier. The receiver then uses the 4234 key identifier to get the implicit algorithm identifiers. 4236 The following additional items need to be taken into consideration: 4238 o Applications that want to support this will need to define a 4239 structure that allows for, and clearly identifies, both the COSE 4240 structure to be used with a given key and the structure and 4241 algorithm to be used for the secondary layer. The key for the 4242 secondary layer is computed per normal from the recipient layer. 4244 The third case is having multiple implicit algorithm identifiers, but 4245 targeted at potentially unrelated layers or different COSE objects. 4246 There are a number of different scenarios where this might be 4247 applicable. Some of these scenarios are: 4249 o Two contexts are distributed as a pair. Each of the contexts is 4250 for use with a COSE_Encrypt message. Each context will consist of 4251 distinct secret keys and IVs and potentially even different 4252 algorithms. One context is for sending messages from party A to 4253 party B, the second context is for sending messages from party B 4254 to party A. This means that there is no chance for a reflection 4255 attack to occur as each party uses different secret keys to send 4256 its messages, a message that is reflected back to it would fail to 4257 decrypt. 4259 o Two contexts are distributed as a pair. The first context is used 4260 for encryption of the message; the second context is used to place 4261 a counter signature on the message. The intention is that the 4262 second context can be distributed to other entities independently 4263 of the first context. This allows these entities to validate that 4264 the message came from an individual without being able to decrypt 4265 the message and see the content. 4267 o Two contexts are distributed as a pair. The first context 4268 contains a key for dealing with MACed messages, the second context 4269 contains a key for dealing with encrypted messages. This allows 4270 for a unified distribution of keys to participants for different 4271 types of messages that have different keys, but where the keys may 4272 be used in coordinated manner. 4274 For these cases, the following additional items need to be 4275 considered: 4277 o Applications need to ensure that the multiple contexts stay 4278 associated. If one of the contexts is invalidated for any reason, 4279 all of the contexts associated with it should also be invalidated. 4281 A.2. Counter Signature Without Headers 4283 There is a group of people who want to have a counter signature 4284 parameter that is directly tied to the value being signed and thus 4285 the authenticated and unauthenticated buckets can be removed from the 4286 message being sent. The focus on this is an even smaller size, as 4287 all of the information on the process of creating the counter 4288 signature is implicit rather than being explicitly carried in the 4289 message. This includes not only the algorithm identifier as 4290 presented above, but also items such as the key identification is 4291 always external to the signature structure. This means that the 4292 entities that are doing the validation of the counter signature are 4293 required to infer which key is to be used from context rather than 4294 being explicit. One way of doing this would be to presume that all 4295 data coming from a specific port (or to a specific URL) is to be 4296 validated by a specific key. (Note that this does not require that 4297 the key identifier be part of the value signed as it does not serve a 4298 cryptographic purpose. If the key validates the counter signature, 4299 then it should be presumed that the entity associated with that key 4300 produced the signature.) 4302 When computing the signature for the bare counter signature header, 4303 the same Sig_structure defined in Section 4.4. The sign_protected 4304 field is omitted, as there is no protected header field in in this 4305 counter signature header. The value of "CounterSignature0" is placed 4306 in the context field of the Sig_stucture. 4308 +-------------------------------+-------+------------+-------------+ 4309 | name | label | value type | description | 4310 +-------------------------------+-------+------------+-------------+ 4311 | counter signature w/o headers | 9 | bstr | | 4312 +-------------------------------+-------+------------+-------------+ 4314 Table 27 4316 Appendix B. Two Layers of Recipient Information 4318 All of the currently defined recipient algorithms classes only use 4319 two layers of the COSE_Encrypt structure. The first layer is the 4320 message content and the second layer is the content key encryption. 4321 However, if one uses a recipient algorithm such as RSA-KEM (see 4322 Appendix A of RSA-KEM [RFC5990]), then it makes sense to have three 4323 layers of the COSE_Encrypt structure. 4325 These layers would be: 4327 o Layer 0: The content encryption layer. This layer contains the 4328 payload of the message. 4330 o Layer 1: The encryption of the CEK by a KEK. 4332 o Layer 2: The encryption of a long random secret using an RSA key 4333 and a key derivation function to convert that secret into the KEK. 4335 This is an example of what a triple layer message would look like. 4336 The message has the following layers: 4338 o Layer 0: Has a content encrypted with AES-GCM using a 128-bit key. 4340 o Layer 1: Uses the AES Key wrap algorithm with a 128-bit key. 4342 o Layer 2: Uses ECDH Ephemeral-Static direct to generate the layer 1 4343 key. 4345 In effect, this example is a decomposed version of using the ECDH- 4346 ES+A128KW algorithm. 4348 Size of binary file is 184 bytes 4349 992( 4350 [ 4351 / protected / h'a10101' / { 4352 \ alg \ 1:1 \ AES-GCM 128 \ 4353 } / , 4354 / unprotected / { 4355 / iv / 5:h'02d1f7e6f26c43d4868d87ce' 4356 }, 4357 / ciphertext / h'64f84d913ba60a76070a9a48f26e97e863e2852948658f0 4358 811139868826e89218a75715b', 4359 / recipients / [ 4360 [ 4361 / protected / h'', 4362 / unprotected / { 4363 / alg / 1:-3 / A128KW / 4364 }, 4365 / ciphertext / h'dbd43c4e9d719c27c6275c67d628d493f090593db82 4366 18f11', 4367 / recipients / [ 4368 [ 4369 / protected / h'a1013818' / { 4370 \ alg \ 1:-25 \ ECDH-ES + HKDF-256 \ 4371 } / , 4372 / unprotected / { 4373 / ephemeral / -1:{ 4374 / kty / 1:2, 4375 / crv / -1:1, 4376 / x / -2:h'b2add44368ea6d641f9ca9af308b4079aeb519f11 4377 e9b8a55a600b21233e86e68', 4378 / y / -3:false 4379 }, 4380 / kid / 4:'meriadoc.brandybuck@buckland.example' 4381 }, 4382 / ciphertext / h'' 4383 ] 4384 ] 4385 ] 4386 ] 4387 ] 4388 ) 4390 Appendix C. Examples 4392 This appendix includes a set of examples that show the different 4393 features and message types that have been defined in this document. 4394 To make the examples easier to read, they are presented using the 4395 extended CBOR diagnostic notation (defined in 4396 [I-D.greevenbosch-appsawg-cbor-cddl]) rather than as a binary dump. 4398 A GitHub project has been created at https://github.com/cose-wg/ 4399 Examples that contains not only the examples presented in this 4400 document, but a more complete set of testing examples as well. Each 4401 example is found in a JSON file that contains the inputs used to 4402 create the example, some of the intermediate values that can be used 4403 in debugging the example and the output of the example presented in 4404 both a hex and a CBOR diagnostic notation format. Some of the 4405 examples at the site are designed failure testing cases; these are 4406 clearly marked as such in the JSON file. If errors in the examples 4407 in this document are found, the examples on github will be updated 4408 and a note to that effect will be placed in the JSON file. 4410 As noted, the examples are presented using the CBOR's diagnostic 4411 notation. A Ruby based tool exists that can convert between the 4412 diagnostic notation and binary. This tool can be installed with the 4413 command line: 4415 gem install cbor-diag 4417 The diagnostic notation can be converted into binary files using the 4418 following command line: 4420 diag2cbor.rb < inputfile > outputfile 4422 The examples can be extracted from the XML version of this document 4423 via an XPath expression as all of the artwork is tagged with the 4424 attribute type='CBORdiag'. (Depending on the XPath evaluator one is 4425 using, it may be necessary to deal with > as an entity.) 4427 //artwork[@type='CDDL']/text() 4429 C.1. Examples of Signed Message 4431 C.1.1. Single Signature 4433 This example uses the following: 4435 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256-1 4437 Size of binary file is 104 bytes 4438 991( 4439 [ 4440 / protected / h'', 4441 / unprotected / {}, 4442 / payload / 'This is the content.', 4443 / signatures / [ 4444 [ 4445 / protected / h'a10126' / { 4446 \ alg \ 1:-7 \ ECDSA 256 \ 4447 } / , 4448 / unprotected / { 4449 / kid / 4:'11' 4450 }, 4451 / signature / h'eae868ecc176883766c5dc5ba5b8dca25dab3c2e56a5 4452 51ce5705b793914348e14eea4aee6e0c9f09db4ef3ddeca8f3506cd1a98a8fb64327 4453 be470355c9657ce0' 4454 ] 4455 ] 4456 ] 4457 ) 4459 C.1.2. Multiple Signers 4461 This example uses the following: 4463 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256-1 4465 o Signature Algorithm: ECDSA w/ SHA-512, Curve P-521 4467 Size of binary file is 278 bytes 4468 991( 4469 [ 4470 / protected / h'', 4471 / unprotected / {}, 4472 / payload / 'This is the content.', 4473 / signatures / [ 4474 [ 4475 / protected / h'a10126' / { 4476 \ alg \ 1:-7 \ ECDSA 256 \ 4477 } / , 4478 / unprotected / { 4479 / kid / 4:'11' 4480 }, 4481 / signature / h'0dc1c5e62719d8f3cce1468b7c881eee6a8088b46bf8 4482 36ae956dd38fe93199199951a6a5e02a24aed5edde3509748366b1c539aaef7dea34 4483 f2cd618fe19fe55d' 4484 ], 4485 [ 4486 / protected / h'a1013823' / { 4487 \ alg \ 1:-36 4488 } / , 4489 / unprotected / { 4490 / kid / 4:'bilbo.baggins@hobbiton.example' 4491 }, 4492 / signature / h'012ce5b1dfe8b5aa6eaa09a54c58a84ad0900e4fdf27 4493 59ec22d1c861cccd75c7e1c4025a2da35e512fc2874d6ac8fd862d09ad07ed2deac2 4494 97b897561e04a8d42476017c11a4a34e26c570c9eff22c1dc84d56cdf6e03ed34bc9 4495 e934c5fdf676c7948d79e97dfe161730217c57748aadb364a0207cee811e9dde65ae 4496 37942e8a8348cc91' 4497 ] 4498 ] 4499 ] 4500 ) 4502 C.1.3. Counter Signature 4504 This example uses the following: 4506 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256-1 4508 o The same parameters are used for both the signature and the 4509 counter signature. 4511 Size of binary file is 181 bytes 4512 991( 4513 [ 4514 / protected / h'', 4515 / unprotected / { 4516 / countersign / 7:[ 4517 / protected / h'a10126' / { 4518 \ alg \ 1:-7 \ ECDSA 256 \ 4519 } / , 4520 / unprotected / { 4521 / kid / 4:'11' 4522 }, 4523 / signature / h'c9d3402485aa585cee3efc69b14496c0b00714584b26 4524 0f8e05764b7dbc70ae2b23b89812f5895b805f07a792f7ce77ef6d63875dc37d6a78 4525 ef4d175da45c9a51' 4526 ] 4527 }, 4528 / payload / 'This is the content.', 4529 / signatures / [ 4530 [ 4531 / protected / h'a10126' / { 4532 \ alg \ 1:-7 \ ECDSA 256 \ 4533 } / , 4534 / unprotected / { 4535 / kid / 4:'11' 4536 }, 4537 / signature / h'eae868ecc176883766c5dc5ba5b8dca25dab3c2e56a5 4538 51ce5705b793914348e14eea4aee6e0c9f09db4ef3ddeca8f3506cd1a98a8fb64327 4539 be470355c9657ce0' 4540 ] 4541 ] 4542 ] 4543 ) 4545 C.1.4. Signature w/ Criticality 4547 This example uses the following: 4549 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256-1 4551 o There is a criticality marker on the "reserved" header parameter 4553 Size of binary file is 126 bytes 4554 991( 4555 [ 4556 / protected / h'a2687265736572766564f40281687265736572766564' / 4557 { 4558 "reserved":false, 4559 \ crit \ 2:[ 4560 "reserved" 4561 ] 4562 } / , 4563 / unprotected / {}, 4564 / payload / 'This is the content.', 4565 / signatures / [ 4566 [ 4567 / protected / h'a10126' / { 4568 \ alg \ 1:-7 \ ECDSA 256 \ 4569 } / , 4570 / unprotected / { 4571 / kid / 4:'11' 4572 }, 4573 / signature / h'eae868ecc176883766c5dc5ba5b8dca25dab3c2e56a5 4574 51ce5705b793914348e1ff259ead2c38d8a7d8a9c87c2ce534d762dab059773115a6 4575 176fa780e85b6b25' 4576 ] 4577 ] 4578 ] 4579 ) 4581 C.2. Single Signer Examples 4583 C.2.1. Single ECDSA signature 4585 This example uses the following: 4587 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256-1 4589 Size of binary file is 100 bytes 4590 997( 4591 [ 4592 / protected / h'a10126' / { 4593 \ alg \ 1:-7 \ ECDSA 256 \ 4594 } / , 4595 / unprotected / { 4596 / kid / 4:'11' 4597 }, 4598 / payload / 'This is the content.', 4599 / signature / h'eae868ecc176883766c5dc5ba5b8dca25dab3c2e56a551ce 4600 5705b793914348e19f43d6c6ba654472da301b645b293c9ba939295b97c4bdb84778 4601 2bff384c5794' 4602 ] 4603 ) 4605 C.3. Examples of Enveloped Messages 4607 C.3.1. Direct ECDH 4609 This example uses the following: 4611 o CEK: AES-GCM w/ 128-bit key 4613 o Recipient class: ECDH Ephemeral-Static, Curve P-256 4615 Size of binary file is 152 bytes 4616 992( 4617 [ 4618 / protected / h'a10101' / { 4619 \ alg \ 1:1 \ AES-GCM 128 \ 4620 } / , 4621 / unprotected / { 4622 / iv / 5:h'c9cf4df2fe6c632bf7886413' 4623 }, 4624 / ciphertext / h'7adbe2709ca818fb415f1e5df66f4e1a51053ba6d65a1a0 4625 c52a357da7a644b8070a151b0', 4626 / recipients / [ 4627 [ 4628 / protected / h'a1013818' / { 4629 \ alg \ 1:-25 \ ECDH-ES + HKDF-256 \ 4630 } / , 4631 / unprotected / { 4632 / ephemeral / -1:{ 4633 / kty / 1:2, 4634 / crv / -1:1, 4635 / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf 4636 bf054e1c7b4d91d6280', 4637 / y / -3:true 4638 }, 4639 / kid / 4:'meriadoc.brandybuck@buckland.example' 4640 }, 4641 / ciphertext / h'' 4642 ] 4643 ] 4644 ] 4645 ) 4647 C.3.2. Direct plus Key Derivation 4649 This example uses the following: 4651 o CEK: AES-CCM w/128-bit key, truncate the tag to 64 bits 4653 o Recipient class: Use HKDF on a shared secret with the following 4654 implicit fields as part of the context. 4656 * salt: "aabbccddeeffgghh" 4658 * APU identity: "lighting-client" 4660 * APV identity: "lighting-server" 4662 * Supplementary Public Other: "Encryption Example 02" 4664 Size of binary file is 92 bytes 4666 992( 4667 [ 4668 / protected / h'a1010a' / { 4669 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 4670 } / , 4671 / unprotected / { 4672 / iv / 5:h'89f52f65a1c580933b5261a76c' 4673 }, 4674 / ciphertext / h'753548a19b1307084ca7b2056924ed95f2e3b17006dfe93 4675 1b687b847', 4676 / recipients / [ 4677 [ 4678 / protected / h'a10129' / { 4679 \ alg \ 1:-10 4680 } / , 4681 / unprotected / { 4682 / salt / -20:'aabbccddeeffgghh', 4683 / kid / 4:'our-secret' 4684 }, 4685 / ciphertext / h'' 4686 ] 4687 ] 4688 ] 4689 ) 4691 C.3.3. Counter Signature on Encrypted Content 4693 This example uses the following: 4695 o CEK: AES-GCM w/ 128-bit key 4697 o Recipient class: ECDH Ephemeral-Static, Curve P-256 4699 Size of binary file is 327 bytes 4700 992( 4701 [ 4702 / protected / h'a10101' / { 4703 \ alg \ 1:1 \ AES-GCM 128 \ 4704 } / , 4705 / unprotected / { 4706 / iv / 5:h'c9cf4df2fe6c632bf7886413', 4707 / countersign / 7:[ 4708 / protected / h'a1013823' / { 4709 \ alg \ 1:-36 4710 } / , 4711 / unprotected / { 4712 / kid / 4:'bilbo.baggins@hobbiton.example' 4713 }, 4714 / signature / h'00aa98cbfd382610a375d046a275f30266e8d0faacb9 4715 069fde06e37825ae7825419c474f416ded0c8e3e7b55bff68f2a704135bdf99186f6 4716 6659461c8cf929cc7fb300f5e2b33c3b433655042ff719804ff73b0be3e988ecebc0 4717 c70ef6616996809c6eb59a918dbe0a5edb0d15137ece0aba2a0b0f68ad2631cb62f2 4718 ea4d7099804218b0' 4719 ] 4720 }, 4721 / ciphertext / h'7adbe2709ca818fb415f1e5df66f4e1a51053ba6d65a1a0 4722 c52a357da7a644b8070a151b0', 4723 / recipients / [ 4724 [ 4725 / protected / h'a1013818' / { 4726 \ alg \ 1:-25 \ ECDH-ES + HKDF-256 \ 4727 } / , 4728 / unprotected / { 4729 / ephemeral / -1:{ 4730 / kty / 1:2, 4731 / crv / -1:1, 4732 / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf 4733 bf054e1c7b4d91d6280', 4734 / y / -3:true 4735 }, 4736 / kid / 4:'meriadoc.brandybuck@buckland.example' 4737 }, 4738 / ciphertext / h'' 4739 ] 4740 ] 4741 ] 4742 ) 4744 C.3.4. Encrypted Content with External Data 4746 This example uses the following: 4748 o CEK: AES-GCM w/ 128-bit key 4750 o Recipient class: ECDH static-Static, Curve P-256 with AES Key Wrap 4752 o Externally Supplied AAD: h'0011bbcc22dd44ee55ff660077' 4754 Size of binary file is 174 bytes 4756 992( 4757 [ 4758 / protected / h'a10101' / { 4759 \ alg \ 1:1 \ AES-GCM 128 \ 4760 } / , 4761 / unprotected / { 4762 / iv / 5:h'02d1f7e6f26c43d4868d87ce' 4763 }, 4764 / ciphertext / h'64f84d913ba60a76070a9a48f26e97e863e28529d8f5335 4765 e5f0165eee976b4a5f6c6f09d', 4766 / recipients / [ 4767 [ 4768 / protected / h'a101381f' / { 4769 \ alg \ 1:-32 \ ECHD-SS+A128KW \ 4770 } / , 4771 / unprotected / { 4772 / static kid / -3:'peregrin.took@tuckborough.example', 4773 / kid / 4:'meriadoc.brandybuck@buckland.example', 4774 / U nonce / -22:h'0101' 4775 }, 4776 / ciphertext / h'41e0d76f579dbd0d936a662d54d8582037de2e366fd 4777 e1c62' 4778 ] 4779 ] 4780 ] 4781 ) 4783 C.4. Examples of Encrypted Messages 4785 C.4.1. Simple Encrypted Message 4787 This example uses the following: 4789 o CEK: AES-CCM w/ 128-bit key and a 64-bit tag 4791 Size of binary file is 54 bytes 4792 993( 4793 [ 4794 / protected / h'a1010a' / { 4795 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 4796 } / , 4797 / unprotected / { 4798 / iv / 5:h'89f52f65a1c580933b5261a78c' 4799 }, 4800 / ciphertext / h'5974e1b99a3a4cc09a659aa2e9e7fff161d38ce7edd5617 4801 388e77baf' 4802 ] 4803 ) 4805 C.4.2. Encrypted Message w/ a Partial IV 4807 This example uses the following: 4809 o CEK: AES-CCM w/ 128-bit key and a 64-bit tag 4811 o Prefix for IV is 89F52F65A1C580933B52 4813 Size of binary file is 43 bytes 4815 993( 4816 [ 4817 / protected / h'a1010a' / { 4818 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 4819 } / , 4820 / unprotected / { 4821 / partial iv / 6:h'61a7' 4822 }, 4823 / ciphertext / h'252a8911d465c125b6764739700f0141ed09192da5c69e5 4824 33abf852b' 4825 ] 4826 ) 4828 C.5. Examples of MACed messages 4830 C.5.1. Shared Secret Direct MAC 4832 This example uses the following: 4834 o MAC: AES-CMAC, 256-bit key, truncated to 64 bits 4836 o Recipient class: direct shared secret 4838 Size of binary file is 58 bytes 4839 994( 4840 [ 4841 / protected / h'a1010f' / { 4842 \ alg \ 1:15 \ AES-CBC-MAC-256//64 \ 4843 } / , 4844 / unprotected / {}, 4845 / payload / 'This is the content.', 4846 / tag / h'9e1226ba1f81b848', 4847 / recipients / [ 4848 [ 4849 / protected / h'', 4850 / unprotected / { 4851 / alg / 1:-6 / direct /, 4852 / kid / 4:'our-secret' 4853 }, 4854 / ciphertext / h'' 4855 ] 4856 ] 4857 ] 4858 ) 4860 C.5.2. ECDH Direct MAC 4862 This example uses the following: 4864 o MAC: HMAC w/SHA-256, 256-bit key 4866 o Recipient class: ECDH key agreement, two static keys, HKDF w/ 4867 context structure 4869 Size of binary file is 215 bytes 4870 994( 4871 [ 4872 / protected / h'a10105' / { 4873 \ alg \ 1:5 \ HMAC 256//256 \ 4874 } / , 4875 / unprotected / {}, 4876 / payload / 'This is the content.', 4877 / tag / h'81a03448acd3d305376eaa11fb3fe416a955be2cbe7ec96f012c99 4878 4bc3f16a41', 4879 / recipients / [ 4880 [ 4881 / protected / h'a101381a' / { 4882 \ alg \ 1:-27 \ ECDH-SS + HKDF-256 \ 4883 } / , 4884 / unprotected / { 4885 / static kid / -3:'peregrin.took@tuckborough.example', 4886 / kid / 4:'meriadoc.brandybuck@buckland.example', 4887 / U nonce / -22:h'4d8553e7e74f3c6a3a9dd3ef286a8195cbf8a23d 4888 19558ccfec7d34b824f42d92bd06bd2c7f0271f0214e141fb779ae2856abf585a583 4889 68b017e7f2a9e5ce4db5' 4890 }, 4891 / ciphertext / h'' 4892 ] 4893 ] 4894 ] 4895 ) 4897 C.5.3. Wrapped MAC 4899 This example uses the following: 4901 o MAC: AES-MAC, 128-bit key, truncated to 64 bits 4903 o Recipient class: AES keywrap w/ a pre-shared 256-bit key 4905 Size of binary file is 110 bytes 4906 994( 4907 [ 4908 / protected / h'a1010e' / { 4909 \ alg \ 1:14 \ AES-CBC-MAC-128//64 \ 4910 } / , 4911 / unprotected / {}, 4912 / payload / 'This is the content.', 4913 / tag / h'36f5afaf0bab5d43', 4914 / recipients / [ 4915 [ 4916 / protected / h'', 4917 / unprotected / { 4918 / alg / 1:-5 / A256KW /, 4919 / kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037' 4920 }, 4921 / ciphertext / h'711ab0dc2fc4585dce27effa6781c8093eba906f227 4922 b6eb0' 4923 ] 4924 ] 4925 ] 4926 ) 4928 C.5.4. Multi-recipient MACed message 4930 This example uses the following: 4932 o MAC: HMAC w/ SHA-256, 128-bit key 4934 o Recipient class: Uses three different methods 4936 1. ECDH Ephemeral-Static, Curve P-521, AES-Key Wrap w/ 128-bit 4937 key 4939 2. AES-Key Wrap w/ 256-bit key 4941 Size of binary file is 310 bytes 4942 994( 4943 [ 4944 / protected / h'a10105' / { 4945 \ alg \ 1:5 \ HMAC 256//256 \ 4946 } / , 4947 / unprotected / {}, 4948 / payload / 'This is the content.', 4949 / tag / h'bf48235e809b5c42e995f2b7d5fa13620e7ed834e337f6aa43df16 4950 1e49e9323e', 4951 / recipients / [ 4952 [ 4953 / protected / h'a101381c' / { 4954 \ alg \ 1:-29 \ ECHD-ES+A128KW \ 4955 } / , 4956 / unprotected / { 4957 / ephemeral / -1:{ 4958 / kty / 1:2, 4959 / crv / -1:3, 4960 / x / -2:h'0043b12669acac3fd27898ffba0bcd2e6c366d53bc4db 4961 71f909a759304acfb5e18cdc7ba0b13ff8c7636271a6924b1ac63c02688075b55ef2 4962 d613574e7dc242f79c3', 4963 / y / -3:true 4964 }, 4965 / kid / 4:'bilbo.baggins@hobbiton.example' 4966 }, 4967 / ciphertext / h'339bc4f79984cdc6b3e6ce5f315a4c7d2b0ac466fce 4968 a69e8c07dfbca5bb1f661bc5f8e0df9e3eff5' 4969 ], 4970 [ 4971 / protected / h'', 4972 / unprotected / { 4973 / alg / 1:-5 / A256KW /, 4974 / kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037' 4975 }, 4976 / ciphertext / h'0b2c7cfce04e98276342d6476a7723c090dfdd15f9a 4977 518e7736549e998370695e6d6a83b4ae507bb' 4978 ] 4979 ] 4980 ] 4981 ) 4983 C.6. Examples of MAC0 messages 4985 C.6.1. Shared Secret Direct MAC 4987 This example uses the following: 4989 o MAC: AES-CMAC, 256-bit key, truncated to 64 bits 4990 o Recipient class: direct shared secret 4992 Size of binary file is 39 bytes 4994 996( 4995 [ 4996 / protected / h'a1010f' / { 4997 \ alg \ 1:15 \ AES-CBC-MAC-256//64 \ 4998 } / , 4999 / unprotected / {}, 5000 / payload / 'This is the content.', 5001 / tag / h'726043745027214f' 5002 ] 5003 ) 5005 Note that this example uses the same inputs as Appendix C.5.1. 5007 C.7. COSE Keys 5009 C.7.1. Public Keys 5011 This is an example of a COSE Key set. This example includes the 5012 public keys for all of the previous examples. 5014 In order the keys are: 5016 o An EC key with a kid of "meriadoc.brandybuck@buckland.example" 5018 o An EC key with a kid of "peregrin.took@tuckborough.example" 5020 o An EC key with a kid of "bilbo.baggins@hobbiton.example" 5022 o An EC key with a kid of "11" 5024 Size of binary file is 481 bytes 5026 [ 5027 { 5028 -1:1, 5029 -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0 5030 8551d', 5031 -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008 5032 4d19c', 5033 1:2, 5034 2:'meriadoc.brandybuck@buckland.example' 5035 }, 5036 { 5037 -1:1, 5038 -2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a 5039 09eff', 5040 -3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbf 5041 c117e', 5042 1:2, 5043 2:'11' 5044 }, 5045 { 5046 -1:3, 5047 -2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737bf5de 5048 7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620085e5c8 5049 f42ad', 5050 -3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e247e 5051 60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3fe1ea1 5052 d9475', 5053 1:2, 5054 2:'bilbo.baggins@hobbiton.example' 5055 }, 5056 { 5057 -1:1, 5058 -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b4d91 5059 d6280', 5060 -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e03bf 5061 822bb', 5062 1:2, 5063 2:'peregrin.took@tuckborough.example' 5064 } 5065 ] 5067 C.7.2. Private Keys 5069 This is an example of a COSE Key set. This example includes the 5070 private keys for all of the previous examples. 5072 In order the keys are: 5074 o An EC key with a kid of "meriadoc.brandybuck@buckland.example" 5076 o A shared-secret key with a kid of "our-secret" 5078 o An EC key with a kid of "peregrin.took@tuckborough.example" 5080 o A shared-secret key with a kid of "018c0ae5-4d9b-471b- 5081 bfd6-eef314bc7037" 5083 o An EC key with a kid of "bilbo.baggins@hobbiton.example" 5085 o An EC key with a kid of "11" 5087 Size of binary file is 816 bytes 5089 [ 5090 { 5091 1:2, 5092 2:'meriadoc.brandybuck@buckland.example', 5093 -1:1, 5094 -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0 5095 8551d', 5096 -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008 5097 4d19c', 5098 -4:h'aff907c99f9ad3aae6c4cdf21122bce2bd68b5283e6907154ad911840fa 5099 208cf' 5100 }, 5101 { 5102 1:2, 5103 2:'11', 5104 -1:1, 5105 -2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a 5106 09eff', 5107 -3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbf 5108 c117e', 5109 -4:h'57c92077664146e876760c9520d054aa93c3afb04e306705db609030850 5110 7b4d3' 5111 }, 5112 { 5113 1:2, 5114 2:'bilbo.baggins@hobbiton.example', 5115 -1:3, 5116 -2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737bf5de 5117 7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620085e5c8 5118 f42ad', 5119 -3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e247e 5120 60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3fe1ea1 5121 d9475', 5122 -4:h'00085138ddabf5ca975f5860f91a08e91d6d5f9a76ad4018766a476680b 5123 55cd339e8ab6c72b5facdb2a2a50ac25bd086647dd3e2e6e99e84ca2c3609fdf177f 5124 eb26d' 5125 }, 5126 { 5127 1:4, 5128 2:'our-secret', 5129 -1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dcea6c4 5130 27188' 5131 }, 5132 { 5133 1:2, 5134 -1:1, 5135 2:'peregrin.took@tuckborough.example', 5136 -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b4d91 5137 d6280', 5138 -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e03bf 5139 822bb', 5140 -4:h'02d1f7e6f26c43d4868d87ceb2353161740aacf1f7163647984b522a848 5141 df1c3' 5142 }, 5143 { 5144 1:4, 5145 2:'our-secret2', 5146 -1:h'849b5786457c1491be3a76dcea6c4271' 5147 }, 5148 { 5149 1:4, 5150 2:'018c0ae5-4d9b-471b-bfd6-eef314bc7037', 5151 -1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dcea6c4 5152 27188' 5153 } 5154 ] 5156 Acknowledgments 5158 This document is a product of the COSE working group of the IETF. 5160 The following individuals are to blame for getting me started on this 5161 project in the first place: Richard Barnes, Matt Miller, and Martin 5162 Thomson. 5164 The initial version of the draft was based to some degree on the 5165 outputs of the JOSE and S/MIME working groups. 5167 The following individuals provided input into the final form of the 5168 document: Carsten Bormann, John Bradley, Brain Campbell, Michael B. 5170 Jones, Ilari Liusvaara, Francesca Palombini, Goran Selander, and 5171 Ludwig Seitz. 5173 Author's Address 5175 Jim Schaad 5176 August Cellars 5178 Email: ietf@augustcellars.com