idnits 2.17.1 draft-ietf-cose-rfc8152bis-struct-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([I-D.ietf-cose-RFC8152bis-algs]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 10, 2019) is 1781 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. 'DSS' == Outdated reference: A later version (-12) exists of draft-ietf-cose-rfc8152bis-algs-02 ** Downref: Normative reference to an Informational draft: draft-ietf-cose-rfc8152bis-algs (ref. 'I-D.ietf-cose-rfc8152bis-algs') ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Downref: Normative reference to an Informational RFC: RFC 8032 -- Obsolete informational reference (is this intentional?): RFC 2633 (Obsoleted by RFC 3851) -- Obsolete informational reference (is this intentional?): RFC 5751 (Obsoleted by RFC 8551) -- Obsolete informational reference (is this intentional?): RFC 8152 (Obsoleted by RFC 9052, RFC 9053) Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 COSE Working Group J. Schaad 3 Internet-Draft August Cellars 4 Obsoletes: 8152 (if approved) June 10, 2019 5 Intended status: Standards Track 6 Expires: December 12, 2019 8 CBOR Object Signing and Encryption (COSE): Structures and Process 9 draft-ietf-cose-rfc8152bis-struct-03 11 Abstract 13 Concise Binary Object Representation (CBOR) is a data format designed 14 for small code size and small message size. There is a need for the 15 ability to have basic security services defined for this data format. 16 This document defines the CBOR Object Signing and Encryption (COSE) 17 protocol. This specification describes how to create and process 18 signatures, message authentication codes, and encryption using CBOR 19 for serialization. This specification additionally describes how to 20 represent cryptographic keys using CBOR. 22 This document along with [I-D.ietf-cose-rfc8152bis-algs] obsoletes 23 RFC8152. 25 Contributing to this document 27 The source for this draft is being maintained in GitHub. Suggested 28 changes should be submitted as pull requests at . Instructions are on that page as well. 30 Editorial changes can be managed in GitHub, but any substantial 31 issues need to be discussed on the COSE mailing list. 33 Status of This Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at https://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on December 12, 2019. 50 Copyright Notice 52 Copyright (c) 2019 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (https://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 68 1.1. Design Changes from JOSE . . . . . . . . . . . . . . . . 5 69 1.2. Changes from RFC8152 . . . . . . . . . . . . . . . . . . 6 70 1.3. Requirements Terminology . . . . . . . . . . . . . . . . 6 71 1.4. CBOR Grammar . . . . . . . . . . . . . . . . . . . . . . 6 72 1.5. CBOR-Related Terminology . . . . . . . . . . . . . . . . 7 73 1.6. Document Terminology . . . . . . . . . . . . . . . . . . 8 74 2. Basic COSE Structure . . . . . . . . . . . . . . . . . . . . 8 75 3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 11 76 3.1. Common COSE Headers Parameters . . . . . . . . . . . . . 13 77 4. Signing Objects . . . . . . . . . . . . . . . . . . . . . . . 17 78 4.1. Signing with One or More Signers . . . . . . . . . . . . 17 79 4.2. Signing with One Signer . . . . . . . . . . . . . . . . . 19 80 4.3. Externally Supplied Data . . . . . . . . . . . . . . . . 20 81 4.4. Signing and Verification Process . . . . . . . . . . . . 21 82 5. Counter Signatures . . . . . . . . . . . . . . . . . . . . . 22 83 5.1. Full Countersignatures . . . . . . . . . . . . . . . . . 23 84 5.2. Abbreviated Countersignatures . . . . . . . . . . . . . . 24 85 6. Encryption Objects . . . . . . . . . . . . . . . . . . . . . 24 86 6.1. Enveloped COSE Structure . . . . . . . . . . . . . . . . 25 87 6.1.1. Content Key Distribution Methods . . . . . . . . . . 26 88 6.2. Single Recipient Encrypted . . . . . . . . . . . . . . . 27 89 6.3. How to Encrypt and Decrypt for AEAD Algorithms . . . . . 28 90 6.4. How to Encrypt and Decrypt for AE Algorithms . . . . . . 30 91 7. MAC Objects . . . . . . . . . . . . . . . . . . . . . . . . . 31 92 7.1. MACed Message with Recipients . . . . . . . . . . . . . . 32 93 7.2. MACed Messages with Implicit Key . . . . . . . . . . . . 33 94 7.3. How to Compute and Verify a MAC . . . . . . . . . . . . . 34 95 8. Key Objects . . . . . . . . . . . . . . . . . . . . . . . . . 35 96 8.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 36 97 9. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 38 98 10. Message Authentication Code (MAC) Algorithms . . . . . . . . 39 99 11. Content Encryption Algorithms . . . . . . . . . . . . . . . . 40 100 12. Key Derivation Functions (KDFs) . . . . . . . . . . . . . . . 40 101 13. Content Key Distribution Methods . . . . . . . . . . . . . . 41 102 13.1. Direct Encryption . . . . . . . . . . . . . . . . . . . 41 103 13.2. Key Wrap . . . . . . . . . . . . . . . . . . . . . . . . 42 104 13.3. Key Transport . . . . . . . . . . . . . . . . . . . . . 42 105 13.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 43 106 13.5. Key Agreement with Key Wrap . . . . . . . . . . . . . . 44 107 14. CBOR Encoding Restrictions . . . . . . . . . . . . . . . . . 44 108 15. Application Profiling Considerations . . . . . . . . . . . . 44 109 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46 110 16.1. CBOR Tag Assignment . . . . . . . . . . . . . . . . . . 46 111 16.2. COSE Header Parameters Registry . . . . . . . . . . . . 46 112 16.3. COSE Header Algorithm Parameters Registry . . . . . . . 47 113 16.4. COSE Key Common Parameters Registry . . . . . . . . . . 47 114 16.5. Media Type Registrations . . . . . . . . . . . . . . . . 47 115 16.5.1. COSE Security Message . . . . . . . . . . . . . . . 47 116 16.5.2. COSE Key Media Type . . . . . . . . . . . . . . . . 48 117 16.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 50 118 17. Security Considerations . . . . . . . . . . . . . . . . . . . 50 119 18. Implementation Status . . . . . . . . . . . . . . . . . . . . 52 120 18.1. Author's Versions . . . . . . . . . . . . . . . . . . . 53 121 18.2. Java Script Version . . . . . . . . . . . . . . . . . . 53 122 18.3. Python Version . . . . . . . . . . . . . . . . . . . . . 54 123 18.4. COSE Testing Library . . . . . . . . . . . . . . . . . . 54 124 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 55 125 19.1. Normative References . . . . . . . . . . . . . . . . . . 55 126 19.2. Informative References . . . . . . . . . . . . . . . . . 56 127 Appendix A. Guidelines for External Data Authentication of 128 Algorithms . . . . . . . . . . . . . . . . . . . . . 58 129 Appendix B. Two Layers of Recipient Information . . . . . . . . 61 130 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 63 131 C.1. Examples of Signed Messages . . . . . . . . . . . . . . . 64 132 C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 64 133 C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 65 134 C.1.3. Counter Signature . . . . . . . . . . . . . . . . . . 66 135 C.1.4. Signature with Criticality . . . . . . . . . . . . . 67 136 C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 68 137 C.2.1. Single ECDSA Signature . . . . . . . . . . . . . . . 68 138 C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 69 139 C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 69 140 C.3.2. Direct Plus Key Derivation . . . . . . . . . . . . . 70 141 C.3.3. Counter Signature on Encrypted Content . . . . . . . 71 142 C.3.4. Encrypted Content with External Data . . . . . . . . 73 143 C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 73 144 C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 73 145 C.4.2. Encrypted Message with a Partial IV . . . . . . . . . 74 147 C.5. Examples of MACed Messages . . . . . . . . . . . . . . . 74 148 C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 74 149 C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 75 150 C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 76 151 C.5.4. Multi-Recipient MACed Message . . . . . . . . . . . . 77 152 C.6. Examples of MAC0 Messages . . . . . . . . . . . . . . . . 78 153 C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 78 154 C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 79 155 C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 79 156 C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 80 157 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 82 158 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 83 160 1. Introduction 162 There has been an increased focus on small, constrained devices that 163 make up the Internet of Things (IoT). One of the standards that has 164 come out of this process is "Concise Binary Object Representation 165 (CBOR)" [RFC7049]. CBOR extended the data model of the JavaScript 166 Object Notation (JSON) [RFC8259] by allowing for binary data, among 167 other changes. CBOR has been adopted by several of the IETF working 168 groups dealing with the IoT world as their encoding of data 169 structures. CBOR was designed specifically to be both small in terms 170 of messages transport and implementation size and be a schema-free 171 decoder. A need exists to provide message security services for IoT, 172 and using CBOR as the message-encoding format makes sense. 174 The JOSE working group produced a set of documents [RFC7515] 175 [RFC7516] [RFC7517] [RFC7518] using JSON that specified how to 176 process encryption, signatures, and Message Authentication Code (MAC) 177 operations and how to encode keys using JSON. This document along 178 with [I-D.ietf-cose-rfc8152bis-algs] defines the CBOR Object Signing 179 and Encryption (COSE) standard, which does the same thing for the 180 CBOR encoding format. While there is a strong attempt to keep the 181 flavor of the original JSON Object Signing and Encryption (JOSE) 182 documents, two considerations are taken into account: 184 o CBOR has capabilities that are not present in JSON and are 185 appropriate to use. One example of this is the fact that CBOR has 186 a method of encoding binary directly without first converting it 187 into a base64-encoded string. 189 o COSE is not a direct copy of the JOSE specification. In the 190 process of creating COSE, decisions that were made for JOSE were 191 re-examined. In many cases, different results were decided on as 192 the criteria were not always the same. 194 This document contains: 196 o The description of the structure for the CBOR objects which are 197 transmitted over the wire. Two objects are defined for 198 encryption, signing and message authentication. One object is 199 defined for transporting keys and one for transporting groups of 200 keys. 202 o The procedures used to compute build the inputs to the 203 cryptographic functions required for each of the structures. 205 o A starting set of attributes that apply to the different security 206 objects. 208 This document does not contain the rules and procedures for using 209 specific cryptographic algorithms. Details on specific algorithms 210 can be found in [I-D.ietf-cose-rfc8152bis-algs] and [RFC8230]. 211 Details for additional algorithms are expected to be defined in 212 future documents. 214 One feature that is present in CMS [RFC5652] that is not present in 215 this standard is a digest structure. This omission is deliberate. 216 It is better for the structure to be defined in each document as 217 different protocols will want to include a different set of fields as 218 part of the structure. While an algorithm identifier and the digesst 219 value are going to be common to all applications, the two values may 220 not always be adjacent as the algorithm could be defined once with 221 multiple values. Applications may additionally want to defined 222 additional data fields as part of the stucture. A common structure 223 is going to include a URI or other pointer to where the data that is 224 being hashed is kept, allowing this to be application specific. 226 1.1. Design Changes from JOSE 228 o Define a single top message structure so that encrypted, signed, 229 and MACed messages can easily be identified and still have a 230 consistent view. 232 o Signed messages distinguish between the protected and unprotected 233 parameters that relate to the content from those that relate to 234 the signature. 236 o MACed messages are separated from signed messages. 238 o MACed messages have the ability to use the same set of recipient 239 algorithms as enveloped messages for obtaining the MAC 240 authentication key. 242 o Use binary encodings for binary data rather than base64url 243 encodings. 245 o Combine the authentication tag for encryption algorithms with the 246 ciphertext. 248 o The set of cryptographic algorithms has been expanded in some 249 directions and trimmed in others. 251 1.2. Changes from RFC8152 253 o Split the orignal document into this document and 254 [I-D.ietf-cose-rfc8152bis-algs]. 256 o Add some text describing why there is no digest structure defined 257 by COSE. 259 o Rearrange the text around counter signatures and define a CBOR Tag 260 for a standalong countersignature. 262 1.3. Requirements Terminology 264 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 265 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 266 "OPTIONAL" in this document are to be interpreted as described in BCP 267 14 [RFC2119] [RFC8174] when, and only when, they appear in all 268 capitals, as shown here. 270 1.4. CBOR Grammar 272 There was not a standard CBOR grammar available when COSE was 273 originally written. For that reason the CBOR structures defined here 274 are described in prose. Since that time CBOR Data Definition 275 Language (CDDL) [I-D.ietf-cbor-cddl] has been published as an RFC. 276 The CBOR grammar presented in this document is compatible with CDDL. 278 The document was developed by first working on the grammar and then 279 developing the prose to go with it. An artifact of this is that the 280 prose was written using the primitive type strings defined by CBOR 281 Data Definition Language (CDDL) [I-D.ietf-cbor-cddl]. In this 282 specification, the following primitive types are used: 284 any -- non-specific value that permits all CBOR values to be 285 placed here. 287 bool -- a boolean value (true: major type 7, value 21; false: 288 major type 7, value 20). 290 bstr -- byte string (major type 2). 292 int -- an unsigned integer or a negative integer. 294 nil -- a null value (major type 7, value 22). 296 nint -- a negative integer (major type 1). 298 tstr -- a UTF-8 text string (major type 3). 300 uint -- an unsigned integer (major type 0). 302 Two syntaxes from CDDL appear in this document as shorthand. These 303 are: 305 FOO / BAR -- indicates that either FOO or BAR can appear here. 307 [+ FOO] -- indicates that the type FOO appears one or more times 308 in an array. 310 As well as the prose description, a version of a CBOR grammar is 311 presented in CDDL. The CDDL grammar is informational; the prose 312 description is normative. 314 The collected CDDL can be extracted from the XML version of this 315 document via the following XPath expression below. (Depending on the 316 XPath evaluator one is using, it may be necessary to deal with > 317 as an entity.) 319 //artwork[@type='CDDL']/text() 321 CDDL expects the initial non-terminal symbol to be the first symbol 322 in the file. For this reason, the first fragment of CDDL is 323 presented here. 325 start = COSE_Messages / COSE_Key / COSE_KeySet / Internal_Types 327 ; This is defined to make the tool quieter: 328 Internal_Types = Sig_structure / Enc_structure / MAC_structure 330 The non-terminal Internal_Types is defined for dealing with the 331 automated validation tools used during the writing of this document. 332 It references those non-terminals that are used for security 333 computations but are not emitted for transport. 335 1.5. CBOR-Related Terminology 337 In JSON, maps are called objects and only have one kind of map key: a 338 string. In COSE, we use strings, negative integers, and unsigned 339 integers as map keys. The integers are used for compactness of 340 encoding and easy comparison. The inclusion of strings allows for an 341 additional range of short encoded values to be used as well. Since 342 the word "key" is mainly used in its other meaning, as a 343 cryptographic key, we use the term "label" for this usage as a map 344 key. 346 The presence of a label in a COSE map that is not a string or an 347 integer is an error. Applications can either fail processing or 348 process messages by ignoring incorrect labels; however, they MUST NOT 349 create messages with incorrect labels. 351 A CDDL grammar fragment defines the non-terminal 'label', as in the 352 previous paragraph, and 'values', which permits any value to be used. 354 label = int / tstr 355 values = any 357 1.6. Document Terminology 359 In this document, we use the following terminology: 361 Byte is a synonym for octet. 363 Constrained Application Protocol (CoAP) is a specialized web transfer 364 protocol for use in constrained systems. It is defined in [RFC7252]. 366 Authenticated Encryption (AE) [RFC5116] algorithms are those 367 encryption algorithms that provide an authentication check of the 368 contents algorithm with the encryption service. 370 Authenticated Encryption with Authenticated Data (AEAD) [RFC5116] 371 algorithms provide the same content authentication service as AE 372 algorithms, but they additionally provide for authentication of non- 373 encrypted data as well. 375 2. Basic COSE Structure 377 The COSE object structure is designed so that there can be a large 378 amount of common code when parsing and processing the different types 379 of security messages. All of the message structures are built on the 380 CBOR array type. The first three elements of the array always 381 contain the same information: 383 1. The set of protected header parameters wrapped in a bstr. 385 2. The set of unprotected header parameters as a map. 387 3. The content of the message. The content is either the plaintext 388 or the ciphertext as appropriate. The content may be detached 389 (i.e. transported separately from the COSE structure), but the 390 location is still used. The content is wrapped in a bstr when 391 present and is a nil value when detached. 393 Elements after this point are dependent on the specific message type. 395 COSE messages are built using the concept of layers to separate 396 different types of cryptographic concepts. As an example of how this 397 works, consider the COSE_Encrypt message (Section 6.1). This message 398 type is broken into two layers: the content layer and the recipient 399 layer. In the content layer, the plaintext is encrypted and 400 information about the encrypted message is placed. In the recipient 401 layer, the content encryption key (CEK) is encrypted and information 402 about how it is encrypted for each recipient is placed. A single 403 layer version of the encryption message COSE_Encrypt0 (Section 6.2) 404 is provided for cases where the CEK is pre-shared. 406 Identification of which type of message has been presented is done by 407 the following methods: 409 1. The specific message type is known from the context. This may be 410 defined by a marker in the containing structure or by 411 restrictions specified by the application protocol. 413 2. The message type is identified by a CBOR tag. Messages with a 414 CBOR tag are known in this specification as tagged messages, 415 while those without the CBOR tag are known as untagged messages. 416 This document defines a CBOR tag for each of the message 417 structures. These tags can be found in Table 1. 419 3. When a COSE object is carried in a media type of 'application/ 420 cose', the optional parameter 'cose-type' can be used to identify 421 the embedded object. The parameter is OPTIONAL if the tagged 422 version of the structure is used. The parameter is REQUIRED if 423 the untagged version of the structure is used. The value to use 424 with the parameter for each of the structures can be found in 425 Table 1. 427 4. When a COSE object is carried as a CoAP payload, the CoAP 428 Content-Format Option can be used to identify the message 429 content. The CoAP Content-Format values can be found in Table 2. 430 The CBOR tag for the message structure is not required as each 431 security message is uniquely identified. 433 +-------+------------------+----------------+-----------------------+ 434 | CBOR | cose-type | Data Item | Semantics | 435 | Tag | | | | 436 +-------+------------------+----------------+-----------------------+ 437 | 98 | cose-sign | COSE_Sign | COSE Signed Data | 438 | | | | Object | 439 | 18 | cose-sign1 | COSE_Sign1 | COSE Single Signer | 440 | | | | Data Object | 441 | 96 | cose-encrypt | COSE_Encrypt | COSE Encrypted Data | 442 | | | | Object | 443 | 16 | cose-encrypt0 | COSE_Encrypt0 | COSE Single Recipient | 444 | | | | Encrypted Data Object | 445 | 97 | cose-mac | COSE_Mac | COSE MACed Data | 446 | | | | Object | 447 | 17 | cose-mac0 | COSE_Mac0 | COSE Mac w/o | 448 | | | | Recipients Object | 449 | TBD0 | cose-countersign | COSE_Signature | COSE standalone | 450 | | | | counter signature | 451 +-------+------------------+----------------+-----------------------+ 453 Table 1: COSE Message Identification 455 +--------------------------------------+----------+-----+-----------+ 456 | Media Type | Encoding | ID | Reference | 457 +--------------------------------------+----------+-----+-----------+ 458 | application/cose; cose-type="cose- | | 98 | [RFC8152] | 459 | sign" | | | | 460 | application/cose; cose-type="cose- | | 18 | [RFC8152] | 461 | sign1" | | | | 462 | application/cose; cose-type="cose- | | 96 | [RFC8152] | 463 | encrypt" | | | | 464 | application/cose; cose-type="cose- | | 16 | [RFC8152] | 465 | encrypt0" | | | | 466 | application/cose; cose-type="cose- | | 97 | [RFC8152] | 467 | mac" | | | | 468 | application/cose; cose-type="cose- | | 17 | [RFC8152] | 469 | mac0" | | | | 470 | application/cose-key | | 101 | [RFC8152] | 471 | application/cose-key-set | | 102 | [RFC8152] | 472 +--------------------------------------+----------+-----+-----------+ 474 Table 2: CoAP Content-Formats for COSE 476 The following CDDL fragment identifies all of the top messages 477 defined in this document. Separate non-terminals are defined for the 478 tagged and the untagged versions of the messages. 480 COSE_Messages = COSE_Untagged_Message / COSE_Tagged_Message 482 COSE_Untagged_Message = COSE_Sign / COSE_Sign1 / 483 COSE_Encrypt / COSE_Encrypt0 / 484 COSE_Mac / COSE_Mac0 / COSE_Countersignature 486 COSE_Tagged_Message = COSE_Sign_Tagged / COSE_Sign1_Tagged / 487 COSE_Encrypt_Tagged / COSE_Encrypt0_Tagged / 488 COSE_Mac_Tagged / COSE_Mac0_Tagged / COSE_Countersignature_Tagged 490 3. Header Parameters 492 The structure of COSE has been designed to have two buckets of 493 information that are not considered to be part of the payload itself, 494 but are used for holding information about content, algorithms, keys, 495 or evaluation hints for the processing of the layer. These two 496 buckets are available for use in all of the structures except for 497 keys. While these buckets are present, they may not all be usable in 498 all instances. For example, while the protected bucket is defined as 499 part of the recipient structure, some of the algorithms used for 500 recipient structures do not provide for authenticated data. If this 501 is the case, the protected bucket is left empty. 503 Both buckets are implemented as CBOR maps. The map key is a 'label' 504 (Section 1.5). The value portion is dependent on the definition for 505 the label. Both maps use the same set of label/value pairs. The 506 integer and string values for labels have been divided into several 507 sections including a standard range, a private range, and a range 508 that is dependent on the algorithm selected. The defined labels can 509 be found in the "COSE Header Parameters" IANA registry 510 (Section 16.2). 512 Two buckets are provided for each layer: 514 protected: Contains parameters about the current layer that are 515 cryptographically protected. This bucket MUST be empty if it is 516 not going to be included in a cryptographic computation. This 517 bucket is encoded in the message as a binary object. This value 518 is obtained by CBOR encoding the protected map and wrapping it in 519 a bstr object. Senders SHOULD encode a zero-length map as a zero- 520 length byte string rather than as a zero-length map (encoded as 521 h'a0'). The zero-length binary encoding is preferred because it 522 is both shorter and the version used in the serialization 523 structures for cryptographic computation. After encoding the map, 524 the value is wrapped in the binary object. Recipients MUST accept 525 both a zero-length binary value and a zero-length map encoded in 526 the binary value. The wrapping allows for the encoding of the 527 protected map to be transported with a greater chance that it will 528 not be altered in transit. (Badly behaved intermediates could 529 decode and re-encode, but this will result in a failure to verify 530 unless the re-encoded byte string is identical to the decoded byte 531 string.) This avoids the problem of all parties needing to be 532 able to do a common canonical encoding. 534 unprotected: Contains parameters about the current layer that are 535 not cryptographically protected. 537 Only parameters that deal with the current layer are to be placed at 538 that layer. As an example of this, the parameter 'content type' 539 describes the content of the message being carried in the message. 540 As such, this parameter is placed only in the content layer and is 541 not placed in the recipient or signature layers. In principle, one 542 should be able to process any given layer without reference to any 543 other layer. With the exception of the COSE_Sign structure, the only 544 data that needs to cross layers is the cryptographic key. 546 The buckets are present in all of the security objects defined in 547 this document. The fields in order are the 'protected' bucket (as a 548 CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map' 549 type). The presence of both buckets is required. The parameters 550 that go into the buckets come from the IANA "COSE Header Parameters" 551 registry (Section 16.2). Some common parameters are defined in the 552 next section. 554 Labels in each of the maps MUST be unique. When processing messages, 555 if a label appears multiple times, the message MUST be rejected as 556 malformed. Applications SHOULD verify that the same label does not 557 occur in both the protected and unprotected headers. If the message 558 is not rejected as malformed, attributes MUST be obtained from the 559 protected bucket before they are obtained from the unprotected 560 bucket. 562 The following CDDL fragment represents the two header buckets. A 563 group "Headers" is defined in CDDL that represents the two buckets in 564 which attributes are placed. This group is used to provide these two 565 fields consistently in all locations. A type is also defined that 566 represents the map of common headers. 568 Headers = ( 569 protected : empty_or_serialized_map, 570 unprotected : header_map 571 ) 573 header_map = { 574 Generic_Headers, 575 * label => values 576 } 578 empty_or_serialized_map = bstr .cbor header_map / bstr .size 0 580 3.1. Common COSE Headers Parameters 582 This section defines a set of common header parameters. A summary of 583 these parameters can be found in Table 3. This table should be 584 consulted to determine the value of label and the type of the value. 586 The set of header parameters defined in this section are: 588 alg: This parameter is used to indicate the algorithm used for the 589 security processing. This parameter MUST be authenticated where 590 the ability to do so exists. This support is provided by AEAD 591 algorithms or construction (COSE_Sign, COSE_Sign1, COSE_Mac, and 592 COSE_Mac0). This authentication can be done either by placing the 593 parameter in the protected header bucket or as part of the 594 externally supplied data. The value is taken from the "COSE 595 Algorithms" registry (see [COSE.Algorithms]). 597 crit: The parameter is used to indicate which protected header 598 labels an application that is processing a message is required to 599 understand. Parameters defined in this document do not need to be 600 included as they should be understood by all implementations. 601 When present, this parameter MUST be placed in the protected 602 header bucket. The array MUST have at least one value in it. 603 Not all labels need to be included in the 'crit' parameter. The 604 rules for deciding which header labels are placed in the array 605 are: 607 * Integer labels in the range of 0 to 7 SHOULD be omitted. 609 * Integer labels in the range -1 to -128 can be omitted as they 610 are algorithm dependent. If an application can correctly 611 process an algorithm, it can be assumed that it will correctly 612 process all of the common parameters associated with that 613 algorithm. Integer labels in the range -129 to -65536 SHOULD 614 be included as these would be less common parameters that might 615 not be generally supported. 617 * Labels for parameters required for an application MAY be 618 omitted. Applications should have a statement if the label can 619 be omitted. 621 The header parameter values indicated by 'crit' can be processed 622 by either the security library code or an application using a 623 security library; the only requirement is that the parameter is 624 processed. If the 'crit' value list includes a value for which 625 the parameter is not in the protected bucket, this is a fatal 626 error in processing the message. 628 content type: This parameter is used to indicate the content type of 629 the data in the payload or ciphertext fields. Integers are from 630 the "CoAP Content-Formats" IANA registry table [COAP.Formats]. 631 Text values following the syntax of "/" 632 where and are defined in Section 4.2 of 633 [RFC6838]. Leading and trailing whitespace is also omitted. 634 Textual content values along with parameters and subparameters can 635 be located using the IANA "Media Types" registry. Applications 636 SHOULD provide this parameter if the content structure is 637 potentially ambiguous. 639 kid: This parameter identifies one piece of data that can be used as 640 input to find the needed cryptographic key. The value of this 641 parameter can be matched against the 'kid' member in a COSE_Key 642 structure. Other methods of key distribution can define an 643 equivalent field to be matched. Applications MUST NOT assume that 644 'kid' values are unique. There may be more than one key with the 645 same 'kid' value, so all of the keys associated with this 'kid' 646 may need to be checked. The internal structure of 'kid' values is 647 not defined and cannot be relied on by applications. Key 648 identifier values are hints about which key to use. This is not a 649 security-critical field. For this reason, it can be placed in the 650 unprotected headers bucket. 652 IV: This parameter holds the Initialization Vector (IV) value. For 653 some symmetric encryption algorithms, this may be referred to as a 654 nonce. The IV can be placed in the unprotected header as 655 modifying the IV will cause the decryption to yield plaintext that 656 is readily detectable as garbled. 658 Partial IV: This parameter holds a part of the IV value. When using 659 the COSE_Encrypt0 structure, a portion of the IV can be part of 660 the context associated with the key. This field is used to carry 661 a value that causes the IV to be changed for each message. The IV 662 can be placed in the unprotected header as modifying the IV will 663 cause the decryption to yield plaintext that is readily detectable 664 as garbled. The 'Initialization Vector' and 'Partial 665 Initialization Vector' parameters MUST NOT both be present in the 666 same security layer. 668 The message IV is generated by the following steps: 670 1. Left-pad the Partial IV with zeros to the length of IV. 672 2. XOR the padded Partial IV with the context IV. 674 counter signature: This parameter holds one or more counter 675 signature values. Counter signatures provide a method of having a 676 second party sign some data. The counter signature parameter can 677 occur as an unprotected attribute in any of the following 678 structures: COSE_Sign1, COSE_Signature, COSE_Encrypt, 679 COSE_recipient, COSE_Encrypt0, COSE_Mac, and COSE_Mac0. These 680 structures all have the same beginning elements, so that a 681 consistent calculation of the counter signature can be computed. 682 Details on counter signatures are found in Section 5. 684 +-----------+-------+----------------+-------------+----------------+ 685 | Name | Label | Value Type | Value | Description | 686 | | | | Registry | | 687 +-----------+-------+----------------+-------------+----------------+ 688 | alg | 1 | int / tstr | COSE | Cryptographic | 689 | | | | Algorithms | algorithm to | 690 | | | | registry | use | 691 | crit | 2 | [+ label] | COSE Header | Critical | 692 | | | | Parameters | headers to be | 693 | | | | registry | understood | 694 | content | 3 | tstr / uint | CoAP | Content type | 695 | type | | | Content- | of the payload | 696 | | | | Formats or | | 697 | | | | Media Types | | 698 | | | | registries | | 699 | kid | 4 | bstr | | Key identifier | 700 | IV | 5 | bstr | | Full | 701 | | | | | Initialization | 702 | | | | | Vector | 703 | Partial | 6 | bstr | | Partial | 704 | IV | | | | Initialization | 705 | | | | | Vector | 706 | counter | 7 | COSE_Signature | | CBOR-encoded | 707 | signature | | / [+ | | signature | 708 | | | COSE_Signature | | structure | 709 | | | ] | | | 710 +-----------+-------+----------------+-------------+----------------+ 712 Table 3: Common Header Parameters 714 The CDDL fragment that represents the set of headers defined in this 715 section is given below. Each of the headers is tagged as optional 716 because they do not need to be in every map; headers required in 717 specific maps are discussed above. 719 Generic_Headers = ( 720 ? 1 => int / tstr, ; algorithm identifier 721 ? 2 => [+label], ; criticality 722 ? 3 => tstr / int, ; content type 723 ? 4 => bstr, ; key identifier 724 ? 5 => bstr, ; IV 725 ? 6 => bstr, ; Partial IV 726 ? 7 => COSE_Signature / [+COSE_Signature] ; Counter signature 727 ) 729 4. Signing Objects 731 COSE supports two different signature structures. COSE_Sign allows 732 for one or more signatures to be applied to the same content. 733 COSE_Sign1 is restricted to a single signer. The structures cannot 734 be converted between each other; as the signature computation 735 includes a parameter identifying which structure is being used, the 736 converted structure will fail signature validation. 738 4.1. Signing with One or More Signers 740 The COSE_Sign structure allows for one or more signatures to be 741 applied to a message payload. Parameters relating to the content and 742 parameters relating to the signature are carried along with the 743 signature itself. These parameters may be authenticated by the 744 signature, or just present. An example of a parameter about the 745 content is the content type. Examples of parameters about the 746 signature would be the algorithm and key used to create the signature 747 and counter signatures. 749 RFC 5652 indicates that: 751 When more than one signature is present, the successful validation 752 of one signature associated with a given signer is usually treated 753 as a successful signature by that signer. However, there are some 754 application environments where other rules are needed. An 755 application that employs a rule other than one valid signature for 756 each signer must specify those rules. Also, where simple matching 757 of the signer identifier is not sufficient to determine whether 758 the signatures were generated by the same signer, the application 759 specification must describe how to determine which signatures were 760 generated by the same signer. Support for different communities 761 of recipients is the primary reason that signers choose to include 762 more than one signature. 764 For example, the COSE_Sign structure might include signatures 765 generated with the Edwards-curve Digital Signature Algorithm (EdDSA) 766 [RFC8032] and with the Elliptic Curve Digital Signature Algorithm 767 (ECDSA) [DSS]. This allows recipients to verify the signature 768 associated with one algorithm or the other. More-detailed 769 information on multiple signature evaluations can be found in 770 [RFC5752]. 772 The signature structure can be encoded as either tagged or untagged 773 depending on the context it will be used in. A tagged COSE_Sign 774 structure is identified by the CBOR tag 98. The CDDL fragment that 775 represents this is: 777 COSE_Sign_Tagged = #6.98(COSE_Sign) 779 A COSE Signed Message is defined in two parts. The CBOR object that 780 carries the body and information about the body is called the 781 COSE_Sign structure. The CBOR object that carries the signature and 782 information about the signature is called the COSE_Signature 783 structure. Examples of COSE Signed Messages can be found in 784 Appendix C.1. 786 The COSE_Sign structure is a CBOR array. The fields of the array in 787 order are: 789 protected: This is as described in Section 3. 791 unprotected: This is as described in Section 3. 793 payload: This field contains the serialized content to be signed. 794 If the payload is not present in the message, the application is 795 required to supply the payload separately. The payload is wrapped 796 in a bstr to ensure that it is transported without changes. If 797 the payload is transported separately ("detached content"), then a 798 nil CBOR object is placed in this location, and it is the 799 responsibility of the application to ensure that it will be 800 transported without changes. 802 Note: When a signature with a message recovery algorithm is used 803 (Section 9), the maximum number of bytes that can be recovered is 804 the length of the payload. The size of the payload is reduced by 805 the number of bytes that will be recovered. If all of the bytes 806 of the payload are consumed, then the payload is encoded as a 807 zero-length binary string rather than as being absent. 809 signatures: This field is an array of signatures. Each signature is 810 represented as a COSE_Signature structure. 812 The CDDL fragment that represents the above text for COSE_Sign 813 follows. 815 COSE_Sign = [ 816 Headers, 817 payload : bstr / nil, 818 signatures : [+ COSE_Signature] 819 ] 821 The COSE_Signature structure is a CBOR array. The fields of the 822 array in order are: 824 protected: This is as described in Section 3. 826 unprotected: This is as described in Section 3. 828 signature: This field contains the computed signature value. The 829 type of the field is a bstr. Algorithms MUST specify padding if 830 the signature value is not a multiple of 8 bits. 832 The CDDL fragment that represents the above text for COSE_Signature 833 follows. 835 COSE_Signature = [ 836 Headers, 837 signature : bstr 838 ] 840 4.2. Signing with One Signer 842 The COSE_Sign1 signature structure is used when only one signature is 843 going to be placed on a message. The parameters dealing with the 844 content and the signature are placed in the same pair of buckets 845 rather than having the separation of COSE_Sign. 847 The structure can be encoded as either tagged or untagged depending 848 on the context it will be used in. A tagged COSE_Sign1 structure is 849 identified by the CBOR tag 18. The CDDL fragment that represents 850 this is: 852 COSE_Sign1_Tagged = #6.18(COSE_Sign1) 854 The CBOR object that carries the body, the signature, and the 855 information about the body and signature is called the COSE_Sign1 856 structure. Examples of COSE_Sign1 messages can be found in 857 Appendix C.2. 859 The COSE_Sign1 structure is a CBOR array. The fields of the array in 860 order are: 862 protected: This is as described in Section 3. 864 unprotected: This is as described in Section 3. 866 payload: This is as described in Section 4.1. 868 signature: This field contains the computed signature value. The 869 type of the field is a bstr. 871 The CDDL fragment that represents the above text for COSE_Sign1 872 follows. 874 COSE_Sign1 = [ 875 Headers, 876 payload : bstr / nil, 877 signature : bstr 878 ] 880 4.3. Externally Supplied Data 882 One of the features offered in the COSE document is the ability for 883 applications to provide additional data to be authenticated, but that 884 is not carried as part of the COSE object. The primary reason for 885 supporting this can be seen by looking at the CoAP message structure 886 [RFC7252], where the facility exists for options to be carried before 887 the payload. Examples of data that can be placed in this location 888 would be the CoAP code or CoAP options. If the data is in the header 889 section, then it is available for proxies to help in performing its 890 operations. For example, the Accept Option can be used by a proxy to 891 determine if an appropriate value is in the proxy's cache. But the 892 sender can cause a failure at the server if a proxy, or an attacker, 893 changes the set of accept values by including the field in the 894 application supplied data. 896 This document describes the process for using a byte array of 897 externally supplied authenticated data; the method of constructing 898 the byte array is a function of the application. Applications that 899 use this feature need to define how the externally supplied 900 authenticated data is to be constructed. Such a construction needs 901 to take into account the following issues: 903 o If multiple items are included, applications need to ensure that 904 the same byte string cannot produced if there are different 905 inputs. This would occur by appending the strings 'AB' and 'CDE' 906 or by appending the strings 'ABC' and 'DE'. This is usually 907 addressed by making fields a fixed width and/or encoding the 908 length of the field as part of the output. Using options from 909 CoAP [RFC7252] as an example, these fields use a TLV structure so 910 they can be concatenated without any problems. 912 o If multiple items are included, an order for the items needs to be 913 defined. Using options from CoAP as an example, an application 914 could state that the fields are to be ordered by the option 915 number. 917 o Applications need to ensure that the byte string is going to be 918 the same on both sides. Using options from CoAP might give a 919 problem if the same relative numbering is kept. An intermediate 920 node could insert or remove an option, changing how the relative 921 number is done. An application would need to specify that the 922 relative number must be re-encoded to be relative only to the 923 options that are in the external data. 925 4.4. Signing and Verification Process 927 In order to create a signature, a well-defined byte string is needed. 928 The Sig_structure is used to create the canonical form. This signing 929 and verification process takes in the body information (COSE_Sign or 930 COSE_Sign1), the signer information (COSE_Signature), and the 931 application data (external source). A Sig_structure is a CBOR array. 932 The fields of the Sig_structure in order are: 934 1. A text string identifying the context of the signature. The 935 context string is: 937 "Signature" for signatures using the COSE_Signature structure. 939 "Signature1" for signatures using the COSE_Sign1 structure. 941 "CounterSignature" for signatures used as counter signature 942 attributes. 944 "CounterSignature0" for signatures used as CounterSignature0 945 attributes. 947 2. The protected attributes from the body structure encoded in a 948 bstr type. If there are no protected attributes, a bstr of 949 length zero is used. 951 3. The protected attributes from the signer structure encoded in a 952 bstr type. If there are no protected attributes, a bstr of 953 length zero is used. This field is omitted for the COSE_Sign1 954 signature structure and CounterSignature0 attributes. 956 4. The protected attributes from the application encoded in a bstr 957 type. If this field is not supplied, it defaults to a zero- 958 length binary string. (See Section 4.3 for application guidance 959 on constructing this field.) 961 5. The payload to be signed encoded in a bstr type. The payload is 962 placed here independent of how it is transported. 964 The CDDL fragment that describes the above text is: 966 Sig_structure = [ 967 context : "Signature" / "Signature1" / "CounterSignature", 968 body_protected : empty_or_serialized_map, 969 ? sign_protected : empty_or_serialized_map, 970 external_aad : bstr, 971 payload : bstr 972 ] 974 How to compute a signature: 976 1. Create a Sig_structure and populate it with the appropriate 977 fields. 979 2. Create the value ToBeSigned by encoding the Sig_structure to a 980 byte string, using the encoding described in Section 14. 982 3. Call the signature creation algorithm passing in K (the key to 983 sign with), alg (the algorithm to sign with), and ToBeSigned (the 984 value to sign). 986 4. Place the resulting signature value in the 'signature' field of 987 the array. 989 The steps for verifying a signature are: 991 1. Create a Sig_structure object and populate it with the 992 appropriate fields. 994 2. Create the value ToBeSigned by encoding the Sig_structure to a 995 byte string, using the encoding described in Section 14. 997 3. Call the signature verification algorithm passing in K (the key 998 to verify with), alg (the algorithm used sign with), ToBeSigned 999 (the value to sign), and sig (the signature to be verified). 1001 In addition to performing the signature verification, the application 1002 performs the appropriate checks to ensure that the key is correctly 1003 paired with the signing identity and that the signing identity is 1004 authorized before performing actions. 1006 5. Counter Signatures 1008 COSE supports two different forms for counter signatures. Full 1009 countersignatures use the structure COSE_Countersign. This is same 1010 structure as COSE_Signature and thus it can have protected 1011 attributes, chained countersignatures and information about 1012 identifying the key. Abbreviated countersignatures use the structure 1013 COSE_Countersign1. This structure only contains the signature value 1014 and nothing else. The structures cannot be converted between each 1015 other; as the signature computation includes a parameter identifying 1016 which structure is being used, the converted structure will fail 1017 signature validation. 1019 COSE was designed for uniformity in how the data strutures are 1020 specified. One result of this is that for COSE one can expand the 1021 concept of countersignatures beyond just the idea of signing a 1022 signature to being able to sign most of the structures without having 1023 to create a new signing layer. When creating a countersignature, one 1024 needs to be clear about the security properties that result. When 1025 done on a COSE_Signature, the normal countersignature semantics are 1026 preserved. That is the countersignature makes a statement about the 1027 existance of a signature and, when used as a timestamp, a time point 1028 at which the signature exists. When done on a COSE_Mac or a 1029 COSE_Mac0, one effectively upgrades the MAC operation to a sginature 1030 operation. When done on a COSE_Encrypt or COSE_Encrypt0, the 1031 existance of the encrypted data is attested to. It should be noted 1032 that there is a big difference between attesting to the enrypted data 1033 as oppose to attesting to the unencrypted data. If the latter is 1034 what is desired, then one needs to apply a signature to the data and 1035 then encrypt that. It is always possible to construct cases where 1036 the decryption is successful, while providing completely different 1037 answers by using a different key. This situation is not detectable 1038 by a countersignature on the encrypted data. 1040 5.1. Full Countersignatures 1042 The COSE_Countersignature structure allows for the same set of 1043 capabilities of a COSE_Signature. This means that all of the 1044 capabilities of a signature are duplicated with this structure. 1045 Specifically, the countersigner does not need to be related to the 1046 producer of what is being counter signed as key and algorithm 1047 identification can be placed in the countersignature attributes. 1048 This also means that the countersignature can itself be 1049 countersigned. This is a feature required by protocols such as long- 1050 term archiving services. More information on how this is used can be 1051 found in the evidence record syntax described in [RFC4998]. 1053 The full countersignature structure can be encoded as either a tagged 1054 or untagged depending on the context it is used in. A tagged 1055 COSE_Countersign steruture is identified byt the CBOR tag TBD0. The 1056 CDDL fragment for full countersignatures is: 1058 COSE_CounterSignature_Tagged = #6.98(COSE_CounterSignature) 1059 COSE_CounterSignature = COSE_Signature 1060 The details of the fields of a countersignature can be found in 1061 Section 4.1. The process of creating and validating abbreviated 1062 countersignatures is defined in Section 4.4. 1064 An example of a counter signature on a signature can be found in 1065 Appendix C.1.3. An example of a counter signature in an encryption 1066 object can be found in Appendix C.3.3. 1068 It should be noted that only a signature algorithm with appendix (see 1069 Section 9) can be used for counter signatures. This is because the 1070 body should be able to be processed without having to evaluate the 1071 counter signature, and this is not possible for signature schemes 1072 with message recovery. 1074 5.2. Abbreviated Countersignatures 1076 Abbreviated countersignatures were designed primarily to deal with 1077 the problem of having group encrypted messaging, but still needing to 1078 know who orginated the message. The object was to keep the 1079 countersignature as small as possible while still providing the 1080 needed security. For abbreviated countersignatures, there is no 1081 provision for any protected attributes related to the signing 1082 operation. Instead, the context that was used to describe the 1083 encryption processing is also assumed to describe the context that 1084 was used to create the countersignature. 1086 The byte string representing the signature value is placed in the 1087 CounterSignature0 attribute. This attribute is then encoded as an 1088 unprotected header. The attribute is defined below. 1090 The process of creating and validating abbreviated countersignatures 1091 is defined in Section 4.4. 1093 +-------------------+-------+---------+-------+---------------------+ 1094 | Name | Label | Value | Value | Description | 1095 | | | Type | | | 1096 +-------------------+-------+---------+-------+---------------------+ 1097 | CounterSignature0 | 9 | bstr | | Abbreviated | 1098 | | | | | Countersignature | 1099 +-------------------+-------+---------+-------+---------------------+ 1101 Table 4: Header Parameter for CounterSignature0 1103 6. Encryption Objects 1105 COSE supports two different encryption structures. COSE_Encrypt0 is 1106 used when a recipient structure is not needed because the key to be 1107 used is known implicitly. COSE_Encrypt is used the rest of the time. 1109 This includes cases where there are multiple recipients or a 1110 recipient algorithm other than direct (i.e. pre-shared secret) is 1111 used. 1113 6.1. Enveloped COSE Structure 1115 The enveloped structure allows for one or more recipients of a 1116 message. There are provisions for parameters about the content and 1117 parameters about the recipient information to be carried in the 1118 message. The protected parameters associated with the content are 1119 authenticated by the content encryption algorithm. The protected 1120 parameters associated with the recipient are authenticated by the 1121 recipient algorithm (when the algorithm supports it). Examples of 1122 parameters about the content are the type of the content and the 1123 content encryption algorithm. Examples of parameters about the 1124 recipient are the recipient's key identifier and the recipient's 1125 encryption algorithm. 1127 The same techniques and nearly the same structure is used for 1128 encrypting both the plaintext and the keys. This is different from 1129 the approach used by both "Cryptographic Message Syntax (CMS)" 1130 [RFC5652] and "JSON Web Encryption (JWE)" [RFC7516] where different 1131 structures are used for the content layer and for the recipient 1132 layer. Two structures are defined: COSE_Encrypt to hold the 1133 encrypted content and COSE_recipient to hold the encrypted keys for 1134 recipients. Examples of encrypted messages can be found in 1135 Appendix C.3. 1137 The COSE_Encrypt structure can be encoded as either tagged or 1138 untagged depending on the context it will be used in. A tagged 1139 COSE_Encrypt structure is identified by the CBOR tag 96. The CDDL 1140 fragment that represents this is: 1142 COSE_Encrypt_Tagged = #6.96(COSE_Encrypt) 1144 The COSE_Encrypt structure is a CBOR array. The fields of the array 1145 in order are: 1147 protected: This is as described in Section 3. 1149 unprotected: This is as described in Section 3. 1151 ciphertext: This field contains the ciphertext encoded as a bstr. 1152 If the ciphertext is to be transported independently of the 1153 control information about the encryption process (i.e., detached 1154 content), then the field is encoded as a nil value. 1156 recipients: This field contains an array of recipient information 1157 structures. The type for the recipient information structure is a 1158 COSE_recipient. 1160 The CDDL fragment that corresponds to the above text is: 1162 COSE_Encrypt = [ 1163 Headers, 1164 ciphertext : bstr / nil, 1165 recipients : [+COSE_recipient] 1166 ] 1168 The COSE_recipient structure is a CBOR array. The fields of the 1169 array in order are: 1171 protected: This is as described in Section 3. 1173 unprotected: This is as described in Section 3. 1175 ciphertext: This field contains the encrypted key encoded as a bstr. 1176 All encoded keys are symmetric keys; the binary value of the key 1177 is the content. If there is not an encrypted key, then this field 1178 is encoded as a nil value. 1180 recipients: This field contains an array of recipient information 1181 structures. The type for the recipient information structure is a 1182 COSE_recipient (an example of this can be found in Appendix B). 1183 If there are no recipient information structures, this element is 1184 absent. 1186 The CDDL fragment that corresponds to the above text for 1187 COSE_recipient is: 1189 COSE_recipient = [ 1190 Headers, 1191 ciphertext : bstr / nil, 1192 ? recipients : [+COSE_recipient] 1193 ] 1195 6.1.1. Content Key Distribution Methods 1197 An encrypted message consists of an encrypted content and an 1198 encrypted CEK for one or more recipients. The CEK is encrypted for 1199 each recipient, using a key specific to that recipient. The details 1200 of this encryption depend on which class the recipient algorithm 1201 falls into. Specific details on each of the classes can be found in 1202 Section 13. A short summary of the five content key distribution 1203 methods is: 1205 direct: The CEK is the same as the identified previously distributed 1206 symmetric key or is derived from a previously distributed secret. 1207 No CEK is transported in the message. 1209 symmetric key-encryption keys (KEK): The CEK is encrypted using a 1210 previously distributed symmetric KEK. Also known as key wrap. 1212 key agreement: The recipient's public key and a sender's private key 1213 are used to generate a pairwise secret, a Key Derivation Function 1214 (KDF) is applied to derive a key, and then the CEK is either the 1215 derived key or encrypted by the derived key. 1217 key transport: The CEK is encrypted with the recipient's public key. 1218 No key transport algorithms are defined in this document. 1220 passwords: The CEK is encrypted in a KEK that is derived from a 1221 password. No password algorithms are defined in this document. 1223 6.2. Single Recipient Encrypted 1225 The COSE_Encrypt0 encrypted structure does not have the ability to 1226 specify recipients of the message. The structure assumes that the 1227 recipient of the object will already know the identity of the key to 1228 be used in order to decrypt the message. If a key needs to be 1229 identified to the recipient, the enveloped structure ought to be 1230 used. 1232 Examples of encrypted messages can be found in Appendix C.3. 1234 The COSE_Encrypt0 structure can be encoded as either tagged or 1235 untagged depending on the context it will be used in. A tagged 1236 COSE_Encrypt0 structure is identified by the CBOR tag 16. The CDDL 1237 fragment that represents this is: 1239 COSE_Encrypt0_Tagged = #6.16(COSE_Encrypt0) 1241 The COSE_Encrypt0 structure is a CBOR array. The fields of the array 1242 in order are: 1244 protected: This is as described in Section 3. 1246 unprotected: This is as described in Section 3. 1248 ciphertext: This is as described in Section 6.1. 1250 The CDDL fragment for COSE_Encrypt0 that corresponds to the above 1251 text is: 1253 COSE_Encrypt0 = [ 1254 Headers, 1255 ciphertext : bstr / nil, 1256 ] 1258 6.3. How to Encrypt and Decrypt for AEAD Algorithms 1260 The encryption algorithm for AEAD algorithms is fairly simple. The 1261 first step is to create a consistent byte string for the 1262 authenticated data structure. For this purpose, we use an 1263 Enc_structure. The Enc_structure is a CBOR array. The fields of the 1264 Enc_structure in order are: 1266 1. A text string identifying the context of the authenticated data 1267 structure. The context string is: 1269 "Encrypt0" for the content encryption of a COSE_Encrypt0 data 1270 structure. 1272 "Encrypt" for the first layer of a COSE_Encrypt data structure 1273 (i.e., for content encryption). 1275 "Enc_Recipient" for a recipient encoding to be placed in an 1276 COSE_Encrypt data structure. 1278 "Mac_Recipient" for a recipient encoding to be placed in a 1279 MACed message structure. 1281 "Rec_Recipient" for a recipient encoding to be placed in a 1282 recipient structure. 1284 2. The protected attributes from the body structure encoded in a 1285 bstr type. If there are no protected attributes, a bstr of 1286 length zero is used. 1288 3. The protected attributes from the application encoded in a bstr 1289 type. If this field is not supplied, it defaults to a zero- 1290 length bstr. (See Section 4.3 for application guidance on 1291 constructing this field.) 1293 The CDDL fragment that describes the above text is: 1295 Enc_structure = [ 1296 context : "Encrypt" / "Encrypt0" / "Enc_Recipient" / 1297 "Mac_Recipient" / "Rec_Recipient", 1298 protected : empty_or_serialized_map, 1299 external_aad : bstr 1300 ] 1301 How to encrypt a message: 1303 1. Create an Enc_structure and populate it with the appropriate 1304 fields. 1306 2. Encode the Enc_structure to a byte string (Additional 1307 Authenticated Data (AAD)), using the encoding described in 1308 Section 14. 1310 3. Determine the encryption key (K). This step is dependent on the 1311 class of recipient algorithm being used. For: 1313 No Recipients: The key to be used is determined by the algorithm 1314 and key at the current layer. Examples are key transport keys 1315 (Section 13.3), key wrap keys (Section 13.2), or pre-shared 1316 secrets. 1318 Direct Encryption and Direct Key Agreement: The key is 1319 determined by the key and algorithm in the recipient 1320 structure. The encryption algorithm and size of the key to be 1321 used are inputs into the KDF used for the recipient. (For 1322 direct, the KDF can be thought of as the identity operation.) 1323 Examples of these algorithms are found in Sections 6.1.2 and 1324 6.3 of [I-D.ietf-cose-rfc8152bis-algs]. 1326 Other: The key is randomly or pseudorandomly generated. 1328 4. Call the encryption algorithm with K (the encryption key), P (the 1329 plaintext), and AAD. Place the returned ciphertext into the 1330 'ciphertext' field of the structure. 1332 5. For recipients of the message, recursively perform the encryption 1333 algorithm for that recipient, using K (the encryption key) as the 1334 plaintext. 1336 How to decrypt a message: 1338 1. Create an Enc_structure and populate it with the appropriate 1339 fields. 1341 2. Encode the Enc_structure to a byte string (AAD), using the 1342 encoding described in Section 14. 1344 3. Determine the decryption key. This step is dependent on the 1345 class of recipient algorithm being used. For: 1347 No Recipients: The key to be used is determined by the algorithm 1348 and key at the current layer. Examples are key transport keys 1349 (Section 13.3), key wrap keys (Section 13.2), or pre-shared 1350 secrets. 1352 Direct Encryption and Direct Key Agreement: The key is 1353 determined by the key and algorithm in the recipient 1354 structure. The encryption algorithm and size of the key to be 1355 used are inputs into the KDF used for the recipient. (For 1356 direct, the KDF can be thought of as the identity operation.) 1358 Other: The key is determined by decoding and decrypting one of 1359 the recipient structures. 1361 4. Call the decryption algorithm with K (the decryption key to use), 1362 C (the ciphertext), and AAD. 1364 6.4. How to Encrypt and Decrypt for AE Algorithms 1366 How to encrypt a message: 1368 1. Verify that the 'protected' field is empty. 1370 2. Verify that there was no external additional authenticated data 1371 supplied for this operation. 1373 3. Determine the encryption key. This step is dependent on the 1374 class of recipient algorithm being used. For: 1376 No Recipients: The key to be used is determined by the algorithm 1377 and key at the current layer. Examples are key transport keys 1378 (Section 13.3), key wrap keys (Section 13.2), or pre-shared 1379 secrets. 1381 Direct Encryption and Direct Key Agreement: The key is 1382 determined by the key and algorithm in the recipient 1383 structure. The encryption algorithm and size of the key to be 1384 used are inputs into the KDF used for the recipient. (For 1385 direct, the KDF can be thought of as the identity operation.) 1386 Examples of these algorithms are found in Sections 6.1.2 and 1387 6.3 of [I-D.ietf-cose-rfc8152bis-algs]. 1389 Other: The key is randomly generated. 1391 4. Call the encryption algorithm with K (the encryption key to use) 1392 and P (the plaintext). Place the returned ciphertext into the 1393 'ciphertext' field of the structure. 1395 5. For recipients of the message, recursively perform the encryption 1396 algorithm for that recipient, using K (the encryption key) as the 1397 plaintext. 1399 How to decrypt a message: 1401 1. Verify that the 'protected' field is empty. 1403 2. Verify that there was no external additional authenticated data 1404 supplied for this operation. 1406 3. Determine the decryption key. This step is dependent on the 1407 class of recipient algorithm being used. For: 1409 No Recipients: The key to be used is determined by the algorithm 1410 and key at the current layer. Examples are key transport keys 1411 (Section 13.3), key wrap keys (Section 13.2), or pre-shared 1412 secrets. 1414 Direct Encryption and Direct Key Agreement: The key is 1415 determined by the key and algorithm in the recipient 1416 structure. The encryption algorithm and size of the key to be 1417 used are inputs into the KDF used for the recipient. (For 1418 direct, the KDF can be thought of as the identity operation.) 1419 Examples of these algorithms are found in Sections 6.1.2 and 1420 6.3 of [I-D.ietf-cose-rfc8152bis-algs]. 1422 Other: The key is determined by decoding and decrypting one of 1423 the recipient structures. 1425 4. Call the decryption algorithm with K (the decryption key to use) 1426 and C (the ciphertext). 1428 7. MAC Objects 1430 COSE supports two different MAC structures. COSE_MAC0 is used when a 1431 recipient structure is not needed because the key to be used is 1432 implicitly known. COSE_MAC is used for all other cases. These 1433 include a requirement for multiple recipients, the key being unknown, 1434 and a recipient algorithm of other than direct. 1436 In this section, we describe the structure and methods to be used 1437 when doing MAC authentication in COSE. This document allows for the 1438 use of all of the same classes of recipient algorithms as are allowed 1439 for encryption. 1441 When using MAC operations, there are two modes in which they can be 1442 used. The first is just a check that the content has not been 1443 changed since the MAC was computed. Any class of recipient algorithm 1444 can be used for this purpose. The second mode is to both check that 1445 the content has not been changed since the MAC was computed and to 1446 use the recipient algorithm to verify who sent it. The classes of 1447 recipient algorithms that support this are those that use a pre- 1448 shared secret or do static-static (SS) key agreement (without the key 1449 wrap step). In both of these cases, the entity that created and sent 1450 the message MAC can be validated. (This knowledge of the sender 1451 assumes that there are only two parties involved and that you did not 1452 send the message to yourself.) The origination property can be 1453 obtained with both of the MAC message structures. 1455 7.1. MACed Message with Recipients 1457 The multiple recipient MACed message uses two structures: the 1458 COSE_Mac structure defined in this section for carrying the body and 1459 the COSE_recipient structure (Section 6.1) to hold the key used for 1460 the MAC computation. Examples of MACed messages can be found in 1461 Appendix C.5. 1463 The MAC structure can be encoded as either tagged or untagged 1464 depending on the context it will be used in. A tagged COSE_Mac 1465 structure is identified by the CBOR tag 97. The CDDL fragment that 1466 represents this is: 1468 COSE_Mac_Tagged = #6.97(COSE_Mac) 1470 The COSE_Mac structure is a CBOR array. The fields of the array in 1471 order are: 1473 protected: This is as described in Section 3. 1475 unprotected: This is as described in Section 3. 1477 payload: This field contains the serialized content to be MACed. If 1478 the payload is not present in the message, the application is 1479 required to supply the payload separately. The payload is wrapped 1480 in a bstr to ensure that it is transported without changes. If 1481 the payload is transported separately (i.e., detached content), 1482 then a nil CBOR value is placed in this location, and it is the 1483 responsibility of the application to ensure that it will be 1484 transported without changes. 1486 tag: This field contains the MAC value. 1488 recipients: This is as described in Section 6.1. 1490 The CDDL fragment that represents the above text for COSE_Mac 1491 follows. 1493 COSE_Mac = [ 1494 Headers, 1495 payload : bstr / nil, 1496 tag : bstr, 1497 recipients :[+COSE_recipient] 1498 ] 1500 7.2. MACed Messages with Implicit Key 1502 In this section, we describe the structure and methods to be used 1503 when doing MAC authentication for those cases where the recipient is 1504 implicitly known. 1506 The MACed message uses the COSE_Mac0 structure defined in this 1507 section for carrying the body. Examples of MACed messages with an 1508 implicit key can be found in Appendix C.6. 1510 The MAC structure can be encoded as either tagged or untagged 1511 depending on the context it will be used in. A tagged COSE_Mac0 1512 structure is identified by the CBOR tag 17. The CDDL fragment that 1513 represents this is: 1515 COSE_Mac0_Tagged = #6.17(COSE_Mac0) 1517 The COSE_Mac0 structure is a CBOR array. The fields of the array in 1518 order are: 1520 protected: This is as described in Section 3. 1522 unprotected: This is as described in Section 3. 1524 payload: This is as described in Section 7.1. 1526 tag: This field contains the MAC value. 1528 The CDDL fragment that corresponds to the above text is: 1530 COSE_Mac0 = [ 1531 Headers, 1532 payload : bstr / nil, 1533 tag : bstr, 1534 ] 1536 7.3. How to Compute and Verify a MAC 1538 In order to get a consistent encoding of the data to be 1539 authenticated, the MAC_structure is used to have a canonical form. 1540 The MAC_structure is a CBOR array. The fields of the MAC_structure 1541 in order are: 1543 1. A text string that identifies the structure that is being 1544 encoded. This string is "MAC" for the COSE_Mac structure. This 1545 string is "MAC0" for the COSE_Mac0 structure. 1547 2. The protected attributes from the COSE_MAC structure. If there 1548 are no protected attributes, a zero-length bstr is used. 1550 3. The protected attributes from the application encoded as a bstr 1551 type. If this field is not supplied, it defaults to a zero- 1552 length binary string. (See Section 4.3 for application guidance 1553 on constructing this field.) 1555 4. The payload to be MACed encoded in a bstr type. The payload is 1556 placed here independent of how it is transported. 1558 The CDDL fragment that corresponds to the above text is: 1560 MAC_structure = [ 1561 context : "MAC" / "MAC0", 1562 protected : empty_or_serialized_map, 1563 external_aad : bstr, 1564 payload : bstr 1565 ] 1567 The steps to compute a MAC are: 1569 1. Create a MAC_structure and populate it with the appropriate 1570 fields. 1572 2. Create the value ToBeMaced by encoding the MAC_structure to a 1573 byte string, using the encoding described in Section 14. 1575 3. Call the MAC creation algorithm passing in K (the key to use), 1576 alg (the algorithm to MAC with), and ToBeMaced (the value to 1577 compute the MAC on). 1579 4. Place the resulting MAC in the 'tag' field of the COSE_Mac or 1580 COSE_Mac0 structure. 1582 5. For COSE_Mac structures, encrypt and encode the MAC key for each 1583 recipient of the message. 1585 The steps to verify a MAC are: 1587 1. Create a MAC_structure object and populate it with the 1588 appropriate fields. 1590 2. Create the value ToBeMaced by encoding the MAC_structure to a 1591 byte string, using the encoding described in Section 14. 1593 3. For COSE_Mac structures, obtain the cryptographic key from one of 1594 the recipients of the message. 1596 4. Call the MAC creation algorithm passing in K (the key to use), 1597 alg (the algorithm to MAC with), and ToBeMaced (the value to 1598 compute the MAC on). 1600 5. Compare the MAC value to the 'tag' field of the COSE_Mac or 1601 COSE_Mac0 structure. 1603 8. Key Objects 1605 A COSE Key structure is built on a CBOR map object. The set of 1606 common parameters that can appear in a COSE Key can be found in the 1607 IANA "COSE Key Common Parameters" registry (Section 16.4). 1608 Additional parameters defined for specific key types can be found in 1609 the IANA "COSE Key Type Parameters" registry ([COSE.KeyParameters]). 1611 A COSE Key Set uses a CBOR array object as its underlying type. The 1612 values of the array elements are COSE Keys. A COSE Key Set MUST have 1613 at least one element in the array. Examples of COSE Key Sets can be 1614 found in Appendix C.7. 1616 Each element in a COSE Key Set MUST be processed independently. If 1617 one element in a COSE Key Set is either malformed or uses a key that 1618 is not understood by an application, that key is ignored and the 1619 other keys are processed normally. 1621 The element "kty" is a required element in a COSE_Key map. 1623 The CDDL grammar describing COSE_Key and COSE_KeySet is: 1625 COSE_Key = { 1626 1 => tstr / int, ; kty 1627 ? 2 => bstr, ; kid 1628 ? 3 => tstr / int, ; alg 1629 ? 4 => [+ (tstr / int) ], ; key_ops 1630 ? 5 => bstr, ; Base IV 1631 * label => values 1632 } 1634 COSE_KeySet = [+COSE_Key] 1636 8.1. COSE Key Common Parameters 1638 This document defines a set of common parameters for a COSE Key 1639 object. Table 5 provides a summary of the parameters defined in this 1640 section. There are also parameters that are defined for specific key 1641 types. Key-type-specific parameters can be found in 1642 [I-D.ietf-cose-rfc8152bis-algs]. 1644 +---------+-------+----------------+------------+-------------------+ 1645 | Name | Label | CBOR Type | Value | Description | 1646 | | | | Registry | | 1647 +---------+-------+----------------+------------+-------------------+ 1648 | kty | 1 | tstr / int | COSE Key | Identification of | 1649 | | | | Types | the key type | 1650 | | | | | | 1651 | kid | 2 | bstr | | Key | 1652 | | | | | identification | 1653 | | | | | value -- match to | 1654 | | | | | kid in message | 1655 | | | | | | 1656 | alg | 3 | tstr / int | COSE | Key usage | 1657 | | | | Algorithms | restriction to | 1658 | | | | | this algorithm | 1659 | | | | | | 1660 | key_ops | 4 | [+ (tstr/int)] | | Restrict set of | 1661 | | | | | permissible | 1662 | | | | | operations | 1663 | | | | | | 1664 | Base IV | 5 | bstr | | Base IV to be | 1665 | | | | | xor-ed with | 1666 | | | | | Partial IVs | 1667 +---------+-------+----------------+------------+-------------------+ 1669 Table 5: Key Map Labels 1671 kty: This parameter is used to identify the family of keys for this 1672 structure and, thus, the set of key-type-specific parameters to be 1673 found. The set of values defined in this document can be found in 1674 [COSE.KeyTypes]. This parameter MUST be present in a key object. 1675 Implementations MUST verify that the key type is appropriate for 1676 the algorithm being processed. The key type MUST be included as 1677 part of the trust decision process. 1679 alg: This parameter is used to restrict the algorithm that is used 1680 with the key. If this parameter is present in the key structure, 1681 the application MUST verify that this algorithm matches the 1682 algorithm for which the key is being used. If the algorithms do 1683 not match, then this key object MUST NOT be used to perform the 1684 cryptographic operation. Note that the same key can be in a 1685 different key structure with a different or no algorithm 1686 specified; however, this is considered to be a poor security 1687 practice. 1689 kid: This parameter is used to give an identifier for a key. The 1690 identifier is not structured and can be anything from a user- 1691 provided string to a value computed on the public portion of the 1692 key. This field is intended for matching against a 'kid' 1693 parameter in a message in order to filter down the set of keys 1694 that need to be checked. 1696 key_ops: This parameter is defined to restrict the set of operations 1697 that a key is to be used for. The value of the field is an array 1698 of values from Table 6. Algorithms define the values of key ops 1699 that are permitted to appear and are required for specific 1700 operations. The set of values matches that in [RFC7517] and 1701 [W3C.WebCrypto]. 1703 Base IV: This parameter is defined to carry the base portion of an 1704 IV. It is designed to be used with the Partial IV header 1705 parameter defined in Section 3.1. This field provides the ability 1706 to associate a Partial IV with a key that is then modified on a 1707 per message basis with the Partial IV. 1709 Extreme care needs to be taken when using a Base IV in an 1710 application. Many encryption algorithms lose security if the same 1711 IV is used twice. 1713 If different keys are derived for each sender, using the same Base 1714 IV with Partial IVs starting at zero is likely to ensure that the 1715 IV would not be used twice for a single key. If different keys 1716 are derived for each sender, starting at the same Base IV is 1717 likely to satisfy this condition. If the same key is used for 1718 multiple senders, then the application needs to provide for a 1719 method of dividing the IV space up between the senders. This 1720 could be done by providing a different base point to start from or 1721 a different Partial IV to start with and restricting the number of 1722 messages to be sent before rekeying. 1724 +---------+-------+-------------------------------------------------+ 1725 | Name | Value | Description | 1726 +---------+-------+-------------------------------------------------+ 1727 | sign | 1 | The key is used to create signatures. Requires | 1728 | | | private key fields. | 1729 | verify | 2 | The key is used for verification of signatures. | 1730 | encrypt | 3 | The key is used for key transport encryption. | 1731 | decrypt | 4 | The key is used for key transport decryption. | 1732 | | | Requires private key fields. | 1733 | wrap | 5 | The key is used for key wrap encryption. | 1734 | key | | | 1735 | unwrap | 6 | The key is used for key wrap decryption. | 1736 | key | | Requires private key fields. | 1737 | derive | 7 | The key is used for deriving keys. Requires | 1738 | key | | private key fields. | 1739 | derive | 8 | The key is used for deriving bits not to be | 1740 | bits | | used as a key. Requires private key fields. | 1741 | MAC | 9 | The key is used for creating MACs. | 1742 | create | | | 1743 | MAC | 10 | The key is used for validating MACs. | 1744 | verify | | | 1745 +---------+-------+-------------------------------------------------+ 1747 Table 6: Key Operation Values 1749 9. Signature Algorithms 1751 There are two signature algorithm schemes. The first is signature 1752 with appendix. In this scheme, the message content is processed and 1753 a signature is produced; the signature is called the appendix. This 1754 is the scheme used by algorithms such as ECDSA and the RSA 1755 Probabilistic Signature Scheme (RSASSA-PSS). (In fact, the SSA in 1756 RSASSA-PSS stands for Signature Scheme with Appendix.) 1758 The signature functions for this scheme are: 1760 signature = Sign(message content, key) 1762 valid = Verification(message content, key, signature) 1764 The second scheme is signature with message recovery (an example of 1765 such an algorithm is [PVSig]). In this scheme, the message content 1766 is processed, but part of it is included in the signature. Moving 1767 bytes of the message content into the signature allows for smaller 1768 signatures; the signature size is still potentially large, but the 1769 message content has shrunk. This has implications for systems 1770 implementing these algorithms and for applications that use them. 1771 The first is that the message content is not fully available until 1772 after a signature has been validated. Until that point, the part of 1773 the message contained inside of the signature is unrecoverable. The 1774 second is that the security analysis of the strength of the signature 1775 is very much based on the structure of the message content. Messages 1776 that are highly predictable require additional randomness to be 1777 supplied as part of the signature process. In the worst case, it 1778 becomes the same as doing a signature with appendix. Finally, in the 1779 event that multiple signatures are applied to a message, all of the 1780 signature algorithms are going to be required to consume the same 1781 number of bytes of message content. This means that the mixing of 1782 the different schemes in a single message is not supported, and if a 1783 recovery signature scheme is used, then the same amount of content 1784 needs to be consumed by all of the signatures. 1786 The signature functions for this scheme are: 1788 signature, message sent = Sign(message content, key) 1790 valid, message content = Verification(message sent, key, signature) 1792 Signature algorithms are used with the COSE_Signature and COSE_Sign1 1793 structures. At this time, only signatures with appendixes are 1794 defined for use with COSE; however, considerable interest has been 1795 expressed in using a signature with message recovery algorithm due to 1796 the effective size reduction that is possible. Implementations will 1797 need to keep this in mind for later possible integration. 1799 10. Message Authentication Code (MAC) Algorithms 1801 Message Authentication Codes (MACs) provide data authentication and 1802 integrity protection. They provide either no or very limited data 1803 origination. A MAC, for example, cannot be used to prove the 1804 identity of the sender to a third party. 1806 MACs use the same scheme as signature with appendix algorithms. The 1807 message content is processed and an authentication code is produced. 1808 The authentication code is frequently called a tag. 1810 The MAC functions are: 1812 tag = MAC_Create(message content, key) 1814 valid = MAC_Verify(message content, key, tag) 1815 MAC algorithms can be based on either a block cipher algorithm (i.e., 1816 AES-MAC) or a hash algorithm (i.e., a Hash-based Message 1817 Authentication Code (HMAC)). This document defines a MAC algorithm 1818 using each of these constructions. 1820 MAC algorithms are used in the COSE_Mac and COSE_Mac0 structures. 1822 11. Content Encryption Algorithms 1824 Content encryption algorithms provide data confidentiality for 1825 potentially large blocks of data using a symmetric key. They provide 1826 integrity on the data that was encrypted; however, they provide 1827 either no or very limited data origination. (One cannot, for 1828 example, be used to prove the identity of the sender to a third 1829 party.) The ability to provide data origination is linked to how the 1830 CEK is obtained. 1832 COSE restricts the set of legal content encryption algorithms to 1833 those that support authentication both of the content and additional 1834 data. The encryption process will generate some type of 1835 authentication value, but that value may be either explicit or 1836 implicit in terms of the algorithm definition. For simplicity's 1837 sake, the authentication code will normally be defined as being 1838 appended to the ciphertext stream. The encryption functions are: 1840 ciphertext = Encrypt(message content, key, additional data) 1842 valid, message content = Decrypt(ciphertext, key, additional data) 1844 Most AEAD algorithms are logically defined as returning the message 1845 content only if the decryption is valid. Many but not all 1846 implementations will follow this convention. The message content 1847 MUST NOT be used if the decryption does not validate. 1849 These algorithms are used in COSE_Encrypt and COSE_Encrypt0. 1851 12. Key Derivation Functions (KDFs) 1853 KDFs are used to take some secret value and generate a different one. 1854 The secret value comes in three flavors: 1856 o Secrets that are uniformly random: This is the type of secret that 1857 is created by a good random number generator. 1859 o Secrets that are not uniformly random: This is type of secret that 1860 is created by operations like key agreement. 1862 o Secrets that are not random: This is the type of secret that 1863 people generate for things like passwords. 1865 General KDFs work well with the first type of secret, can do 1866 reasonably well with the second type of secret, and generally do 1867 poorly with the last type of secret. Functions like PBES2 [RFC8018] 1868 need to be used for non-random secrets. 1870 The same KDF can be set up to deal with the first two types of 1871 secrets in a different way. The KDF defined in section 5.1 of 1872 [I-D.ietf-cose-rfc8152bis-algs] is such a function. This is 1873 reflected in the set of algorithms defined around the HMAC-based 1874 Extract-and-Expand Key Derivation Function (HKDF). 1876 When using KDFs, one component that is included is context 1877 information. Context information is used to allow for different 1878 keying information to be derived from the same secret. The use of 1879 context-based keying material is considered to be a good security 1880 practice. 1882 13. Content Key Distribution Methods 1884 Content key distribution methods (recipient algorithms) can be 1885 defined into a number of different classes. COSE has the ability to 1886 support many classes of recipient algorithms. In this section, a 1887 number of classes are listed. The names of the recipient algorithm 1888 classes used here are the same as those defined in [RFC7516]. Other 1889 specifications use different terms for the recipient algorithm 1890 classes or do not support some of the recipient algorithm classes. 1892 13.1. Direct Encryption 1894 The direct encryption class algorithms share a secret between the 1895 sender and the recipient that is used either directly or after 1896 manipulation as the CEK. When direct encryption mode is used, it 1897 MUST be the only mode used on the message. 1899 The COSE_Recipient structure for the recipient is organized as 1900 follows: 1902 o The 'protected' field MUST be a zero-length item unless it is used 1903 in the computation of the content key. 1905 o The 'alg' parameter MUST be present. 1907 o A parameter identifying the shared secret SHOULD be present. 1909 o The 'ciphertext' field MUST be a zero-length item. 1911 o The 'recipients' field MUST be absent. 1913 13.2. Key Wrap 1915 In key wrap mode, the CEK is randomly generated and that key is then 1916 encrypted by a shared secret between the sender and the recipient. 1917 All of the currently defined key wrap algorithms for COSE are AE 1918 algorithms. Key wrap mode is considered to be superior to direct 1919 encryption if the system has any capability for doing random key 1920 generation. This is because the shared key is used to wrap random 1921 data rather than data that has some degree of organization and may in 1922 fact be repeating the same content. The use of key wrap loses the 1923 weak data origination that is provided by the direct encryption 1924 algorithms. 1926 The COSE_Encrypt structure for the recipient is organized as follows: 1928 o The 'protected' field MUST be absent if the key wrap algorithm is 1929 an AE algorithm. 1931 o The 'recipients' field is normally absent, but can be used. 1932 Applications MUST deal with a recipient field being present that 1933 has an unsupported algorthms, not being able to decrypt that 1934 recipient is an acceptable way of dealing with it. Failing to 1935 process the message is not an acceptable way of dealing with it. 1937 o The plaintext to be encrypted is the key from next layer down 1938 (usually the content layer). 1940 o At a minimum, the 'unprotected' field MUST contain the 'alg' 1941 parameter and SHOULD contain a parameter identifying the shared 1942 secret. 1944 13.3. Key Transport 1946 Key transport mode is also called key encryption mode in some 1947 standards. Key transport mode differs from key wrap mode in that it 1948 uses an asymmetric encryption algorithm rather than a symmetric 1949 encryption algorithm to protect the key. A set of key transport 1950 algorithms are defined in [RFC8230]. 1952 When using a key transport algorithm, the COSE_Encrypt structure for 1953 the recipient is organized as follows: 1955 o The 'protected' field MUST be absent. 1957 o The plaintext to be encrypted is the key from the next layer down 1958 (usually the content layer). 1960 o At a minimum, the 'unprotected' field MUST contain the 'alg' 1961 parameter and SHOULD contain a parameter identifying the 1962 asymmetric key. 1964 13.4. Direct Key Agreement 1966 The 'direct key agreement' class of recipient algorithms uses a key 1967 agreement method to create a shared secret. A KDF is then applied to 1968 the shared secret to derive a key to be used in protecting the data. 1969 This key is normally used as a CEK or MAC key, but could be used for 1970 other purposes if more than two layers are in use (see Appendix B). 1972 The most commonly used key agreement algorithm is Diffie-Hellman, but 1973 other variants exist. Since COSE is designed for a store and forward 1974 environment rather than an online environment, many of the DH 1975 variants cannot be used as the receiver of the message cannot provide 1976 any dynamic key material. One side effect of this is that perfect 1977 forward secrecy (see [RFC4949]) is not achievable. A static key will 1978 always be used for the receiver of the COSE object. 1980 Two variants of DH that are supported are: 1982 Ephemeral-Static (ES) DH: where the sender of the message creates 1983 a one-time DH key and uses a static key for the recipient. The 1984 use of the ephemeral sender key means that no additional random 1985 input is needed as this is randomly generated for each message. 1987 Static-Static (SS) DH: where a static key is used for both the 1988 sender and the recipient. The use of static keys allows for the 1989 recipient to get a weak version of data origination for the 1990 message. When static-static key agreement is used, then some 1991 piece of unique data for the KDF is required to ensure that a 1992 different key is created for each message. 1994 When direct key agreement mode is used, there MUST be only one 1995 recipient in the message. This method creates the key directly, and 1996 that makes it difficult to mix with additional recipients. If 1997 multiple recipients are needed, then the version with key wrap needs 1998 to be used. 2000 The COSE_Encrypt structure for the recipient is organized as follows: 2002 o At a minimum, headers MUST contain the 'alg' parameter and SHOULD 2003 contain a parameter identifying the recipient's asymmetric key. 2005 o The headers SHOULD identify the sender's key for the static-static 2006 versions and MUST contain the sender's ephemeral key for the 2007 ephemeral-static versions. 2009 13.5. Key Agreement with Key Wrap 2011 Key Agreement with Key Wrap uses a randomly generated CEK. The CEK 2012 is then encrypted using a key wrap algorithm and a key derived from 2013 the shared secret computed by the key agreement algorithm. The 2014 function for this would be: 2016 encryptedKey = KeyWrap(KDF(DH-Shared, context), CEK) 2018 The COSE_Encrypt structure for the recipient is organized as follows: 2020 o The 'protected' field is fed into the KDF context structure. 2022 o The plaintext to be encrypted is the key from the next layer down 2023 (usually the content layer). 2025 o The 'alg' parameter MUST be present in the layer. 2027 o A parameter identifying the recipient's key SHOULD be present. A 2028 parameter identifying the sender's key SHOULD be present. 2030 14. CBOR Encoding Restrictions 2032 There has been an attempt to limit the number of places where the 2033 document needs to impose restrictions on how the CBOR Encoder needs 2034 to work. We have managed to narrow it down to the following 2035 restrictions: 2037 o The restriction applies to the encoding of the Sig_structure, the 2038 Enc_structure, and the MAC_structure. 2040 o Encoding MUST be done using definite lengths and the length of the 2041 MUST be the minimum possible length. This means that the integer 2042 1 is encoded as "0x01" and not "0x1801". 2044 o Applications MUST NOT generate messages with the same label used 2045 twice as a key in a single map. Applications MUST NOT parse and 2046 process messages with the same label used twice as a key in a 2047 single map. Applications can enforce the parse and process 2048 requirement by using parsers that will fail the parse step or by 2049 using parsers that will pass all keys to the application, and the 2050 application can perform the check for duplicate keys. 2052 15. Application Profiling Considerations 2054 This document is designed to provide a set of security services, but 2055 not impose algorithm implementation requirements for specific usage. 2056 The interoperability requirements are provided for how each of the 2057 individual services are used and how the algorithms are to be used 2058 for interoperability. The requirements about which algorithms and 2059 which services are needed are deferred to each application. 2061 An example of a profile can be found in 2062 [I-D.ietf-core-object-security] where a profiles was developed for 2063 carrying content in combination with CoAP headers. 2065 It is intended that a profile of this document be created that 2066 defines the interoperability requirements for that specific 2067 application. This section provides a set of guidelines and topics 2068 that need to be considered when profiling this document. 2070 o Applications need to determine the set of messages defined in this 2071 document that they will be using. The set of messages corresponds 2072 fairly directly to the set of security services that are needed 2073 and to the security levels needed. 2075 o Applications may define new header parameters for a specific 2076 purpose. Applications will often times select specific header 2077 parameters to use or not to use. For example, an application 2078 would normally state a preference for using either the IV or the 2079 Partial IV parameter. If the Partial IV parameter is specified, 2080 then the application also needs to define how the fixed portion of 2081 the IV is determined. 2083 o When applications use externally defined authenticated data, they 2084 need to define how that data is encoded. This document assumes 2085 that the data will be provided as a byte string. More information 2086 can be found in Section 4.3. 2088 o Applications need to determine the set of security algorithms that 2089 are to be used. When selecting the algorithms to be used as the 2090 mandatory-to-implement set, consideration should be given to 2091 choosing different types of algorithms when two are chosen for a 2092 specific purpose. An example of this would be choosing HMAC- 2093 SHA512 and AES-CMAC as different MAC algorithms; the construction 2094 is vastly different between these two algorithms. This means that 2095 a weakening of one algorithm would be unlikely to lead to a 2096 weakening of the other algorithms. Of course, these algorithms do 2097 not provide the same level of security and thus may not be 2098 comparable for the desired security functionality. 2100 o Applications may need to provide some type of negotiation or 2101 discovery method if multiple algorithms or message structures are 2102 permitted. The method can be as simple as requiring 2103 preconfiguration of the set of algorithms to providing a discovery 2104 method built into the protocol. S/MIME provided a number of 2105 different ways to approach the problem that applications could 2106 follow: 2108 * Advertising in the message (S/MIME capabilities) [RFC5751]. 2110 * Advertising in the certificate (capabilities extension) 2111 [RFC4262]. 2113 * Minimum requirements for the S/MIME, which have been updated 2114 over time [RFC2633] [RFC5751] (note that [RFC2633] has been 2115 obsoleted by [RFC5751]). 2117 16. IANA Considerations 2119 The registeries and registrations listed below were created during 2120 processing of RFC 8152 [RFC8152]. The only known action at this time 2121 is to update the references. 2123 16.1. CBOR Tag Assignment 2125 IANA assigned tags in the "CBOR Tags" registry as part of processing 2126 [RFC8152]. IANA is requested to update the references from [RFC8152] 2127 to this document. 2129 IANA is requested to register a new tag for the CounterSignature 2130 type. 2132 Tag: TBD0 2134 Data Item: COSE_Signature 2136 Semantics: COSE standalone counter signature 2138 Reference: [[this document]] 2140 16.2. COSE Header Parameters Registry 2142 IANA created a registry titled "COSE Header Parameters" as part of 2143 processing [RFC8152]. The registry has been created to use the 2144 "Expert Review Required" registration procedure [RFC8126]. 2146 IANA is requested to update the reference for entries in the table 2147 from [RFC8152] to this document. This document does not update the 2148 expert review guidelines provided in [RFC8152]. 2150 16.3. COSE Header Algorithm Parameters Registry 2152 IANA created a registry titled "COSE Header Algorithm Parameters" as 2153 part of processing [RFC8152]. The registry has been created to use 2154 the "Expert Review Required" registration procedure [RFC8126]. 2156 IANA is requested to update the references from [RFC8152] to this 2157 document. This document does not update the expert review guidelines 2158 provided in [RFC8152]. 2160 16.4. COSE Key Common Parameters Registry 2162 IANA created a registry titled "COSE Key Common Parameters" as part 2163 of the processing of [RFC8152]. The registry has been created to use 2164 the "Expert Review Required" registration procedure [RFC8126]. 2166 IANA is requested to update the reference for entries in the table 2167 from [RFC8152] to this document. This document does not update the 2168 expert review guidelines provided in [RFC8152]. 2170 16.5. Media Type Registrations 2172 16.5.1. COSE Security Message 2174 This section registers the 'application/cose' media type in the 2175 "Media Types" registry. These media types are used to indicate that 2176 the content is a COSE message. 2178 Type name: application 2180 Subtype name: cose 2182 Required parameters: N/A 2184 Optional parameters: cose-type 2186 Encoding considerations: binary 2188 Security considerations: See the Security Considerations section 2189 of [[This Document]]. 2191 Interoperability considerations: N/A 2193 Published specification: [[this document]] 2195 Applications that use this media type: IoT applications sending 2196 security content over HTTP(S) transports. 2198 Fragment identifier considerations: N/A 2200 Additional information: 2202 * Deprecated alias names for this type: N/A 2204 * Magic number(s): N/A 2206 * File extension(s): cbor 2208 * Macintosh file type code(s): N/A 2210 Person & email address to contact for further information: 2211 iesg@ietf.org 2213 Intended usage: COMMON 2215 Restrictions on usage: N/A 2217 Author: Jim Schaad, ietf@augustcellars.com 2219 Change Controller: IESG 2221 Provisional registration? No 2223 16.5.2. COSE Key Media Type 2225 This section registers the 'application/cose-key' and 'application/ 2226 cose-key-set' media types in the "Media Types" registry. These media 2227 types are used to indicate, respectively, that content is a COSE_Key 2228 or COSE_KeySet object. 2230 The template for registering 'application/cose-key' is: 2232 Type name: application 2234 Subtype name: cose-key 2236 Required parameters: N/A 2238 Optional parameters: N/A 2240 Encoding considerations: binary 2242 Security considerations: See the Security Considerations section 2243 of [[This Document]]. 2245 Interoperability considerations: N/A 2246 Published specification: [[this document]] 2248 Applications that use this media type: Distribution of COSE based 2249 keys for IoT applications. 2251 Fragment identifier considerations: N/A 2253 Additional information: 2255 * Deprecated alias names for this type: N/A 2257 * Magic number(s): N/A 2259 * File extension(s): cbor 2261 * Macintosh file type code(s): N/A 2263 Person & email address to contact for further information: 2264 iesg@ietf.org 2266 Intended usage: COMMON 2268 Restrictions on usage: N/A 2270 Author: Jim Schaad, ietf@augustcellars.com 2272 Change Controller: IESG 2274 Provisional registration? No 2276 The template for registering 'application/cose-key-set' is: 2278 Type name: application 2280 Subtype name: cose-key-set 2282 Required parameters: N/A 2284 Optional parameters: N/A 2286 Encoding considerations: binary 2288 Security considerations: See the Security Considerations section 2289 of [[This Document]]. 2291 Interoperability considerations: N/A 2293 Published specification: [[this document]] 2294 Applications that use this media type: Distribution of COSE based 2295 keys for IoT applications. 2297 Fragment identifier considerations: N/A 2299 Additional information: 2301 * Deprecated alias names for this type: N/A 2303 * Magic number(s): N/A 2305 * File extension(s): cbor 2307 * Macintosh file type code(s): N/A 2309 Person & email address to contact for further information: 2310 iesg@ietf.org 2312 Intended usage: COMMON 2314 Restrictions on usage: N/A 2316 Author: Jim Schaad, ietf@augustcellars.com 2318 Change Controller: IESG 2320 Provisional registration? No 2322 16.6. CoAP Content-Formats Registry 2324 IANA added the following entries to the "CoAP Content-Formats" 2325 registry while processing [RFC8152]. IANA is requested to update the 2326 reference value from [RFC8152] to [[This Document]]. 2328 17. Security Considerations 2330 There are a number of security considerations that need to be taken 2331 into account by implementers of this specification. The security 2332 considerations that are specific to an individual algorithm are 2333 placed next to the description of the algorithm. While some 2334 considerations have been highlighted here, additional considerations 2335 may be found in the documents listed in the references. 2337 Implementations need to protect the private key material for any 2338 individuals. There are some cases in this document that need to be 2339 highlighted on this issue. 2341 o Using the same key for two different algorithms can leak 2342 information about the key. It is therefore recommended that keys 2343 be restricted to a single algorithm. 2345 o Use of 'direct' as a recipient algorithm combined with a second 2346 recipient algorithm exposes the direct key to the second 2347 recipient. 2349 o Several of the algorithms in this document have limits on the 2350 number of times that a key can be used without leaking information 2351 about the key. 2353 The use of ECDH and direct plus KDF (with no key wrap) will not 2354 directly lead to the private key being leaked; the one way function 2355 of the KDF will prevent that. There is, however, a different issue 2356 that needs to be addressed. Having two recipients requires that the 2357 CEK be shared between two recipients. The second recipient therefore 2358 has a CEK that was derived from material that can be used for the 2359 weak proof of origin. The second recipient could create a message 2360 using the same CEK and send it to the first recipient; the first 2361 recipient would, for either static-static ECDH or direct plus KDF, 2362 make an assumption that the CEK could be used for proof of origin 2363 even though it is from the wrong entity. If the key wrap step is 2364 added, then no proof of origin is implied and this is not an issue. 2366 Although it has been mentioned before, the use of a single key for 2367 multiple algorithms has been demonstrated in some cases to leak 2368 information about a key, provide the opportunity for attackers to 2369 forge integrity tags, or gain information about encrypted content. 2370 Binding a key to a single algorithm prevents these problems. Key 2371 creators and key consumers are strongly encouraged not only to create 2372 new keys for each different algorithm, but to include that selection 2373 of algorithm in any distribution of key material and strictly enforce 2374 the matching of algorithms in the key structure to algorithms in the 2375 message structure. In addition to checking that algorithms are 2376 correct, the key form needs to be checked as well. Do not use an 2377 'EC2' key where an 'OKP' key is expected. 2379 Before using a key for transmission, or before acting on information 2380 received, a trust decision on a key needs to be made. Is the data or 2381 action something that the entity associated with the key has a right 2382 to see or a right to request? A number of factors are associated 2383 with this trust decision. Some of the ones that are highlighted here 2384 are: 2386 o What are the permissions associated with the key owner? 2388 o Is the cryptographic algorithm acceptable in the current context? 2389 o Have the restrictions associated with the key, such as algorithm 2390 or freshness, been checked and are they correct? 2392 o Is the request something that is reasonable, given the current 2393 state of the application? 2395 o Have any security considerations that are part of the message been 2396 enforced (as specified by the application or 'crit' parameter)? 2398 There are a large number of algorithms presented in this document 2399 that use nonce values. For all of the nonces defined in this 2400 document, there is some type of restriction on the nonce being a 2401 unique value either for a key or for some other conditions. In all 2402 of these cases, there is no known requirement on the nonce being both 2403 unique and unpredictable; under these circumstances, it's reasonable 2404 to use a counter for creation of the nonce. In cases where one wants 2405 the pattern of the nonce to be unpredictable as well as unique, one 2406 can use a key created for that purpose and encrypt the counter to 2407 produce the nonce value. 2409 One area that has been starting to get exposure is doing traffic 2410 analysis of encrypted messages based on the length of the message. 2411 This specification does not provide for a uniform method of providing 2412 padding as part of the message structure. An observer can 2413 distinguish between two different strings (for example, 'YES' and 2414 'NO') based on the length for all of the content encryption 2415 algorithms that are defined in this document. This means that it is 2416 up to the applications to document how content padding is to be done 2417 in order to prevent or discourage such analysis. (For example, the 2418 strings could be defined as 'YES' and 'NO '.) 2420 18. Implementation Status 2422 This section records the status of known implementations of the 2423 protocol defined by this specification at the time of posting of this 2424 Internet-Draft, and is based on a proposal described in [RFC7942]. 2425 The description of implementations in this section is intended to 2426 assist the IETF in its decision processes in progressing drafts to 2427 RFCs. Please note that the listing of any individual implementation 2428 here does not imply endorsement by the IETF. Furthermore, no effort 2429 has been spent to verify the information presented here that was 2430 supplied by IETF contributors. This is not intended as, and must not 2431 be construed to be, a catalog of available implementations or their 2432 features. Readers are advised to note that other implementations may 2433 exist. 2435 According to [RFC7942], "this will allow reviewers and working groups 2436 to assign due consideration to documents that have the benefit of 2437 running code, which may serve as evidence of valuable experimentation 2438 and feedback that have made the implemented protocols more mature. 2439 It is up to the individual working groups to use this information as 2440 they see fit". 2442 18.1. Author's Versions 2444 There are three different implementations that have been created by 2445 the author of the document both to create the examples that are 2446 included in the document and to validate the structures and 2447 methodology used in the design of COSE. 2449 Implementation Location: https://github.com/cose-wg 2451 Primary Maintainer: Jim Schaad 2453 Languages: There are three different languages that are currently 2454 supported: Java, C# and C. 2456 Cryptography: The Java and C# libraries use Bouncy Castle to 2457 provide the required cryptography. The C version uses OPENSSL 2458 Version 1.0 for the cryptography. 2460 Coverage: The C version currently does not have full countersign 2461 support. THe other two versions do. They do have support to 2462 allow for implicit algorithm support as they allow for the 2463 application to set attributes that are not to be sent in the 2464 message. 2466 Testing: All of the examples in the example library are generated 2467 by the C# library and then validated using the Java and C 2468 libraries. All three libraries have tests to allow for the 2469 creating of the same messages that are in the example library 2470 followed by validating them. These are not compared against the 2471 example library. The Java and C# libraries have unit testing 2472 included. Not all of the MUST statements in the document have 2473 been implemented as part of the libraries. One such statement is 2474 the requirement that unique labels be present. 2476 Licensing: Revised BSD License 2478 18.2. Java Script Version 2480 Implementation Location: https://github.com/erdtman/cose-js 2482 Primary Maintainer: Samuel Erdtman 2484 Languages: JavaScript 2485 Cryptography: TBD 2487 Coverage: Full Encrypt, Signature and MAC objects are supported. 2489 Testing: Basic testing against the common example library. 2491 Licensing: Apache License 2.0 2493 18.3. Python Version 2495 Implementation Location: https://github.com/TimothyClaeys/COSE- 2496 PYTHON 2498 Primary Maintainer: Timothy Claeys 2500 Languages: Python 2502 Cryptography: pyecdsak, crypto python libraries 2504 Coverage: TBD 2506 Testing: Basic testing plus running against the common example 2507 library. 2509 Licensing: BSD 3-Clause License 2511 18.4. COSE Testing Library 2513 Implementation Location: https://github.com/cose-wg/Examples 2515 Primary Maintainer: Jim Schaad 2517 Description: A set of tests for the COSE library is provided as 2518 part of the implementation effort. Both success and fail tests 2519 have been provided. All of the examples in this document are part 2520 of this example set. 2522 Coverage: An attempt has been made to have test cases for every 2523 message type and algorithm in the document. Currently examples 2524 dealing with counter signatures, and ECDH with Curve24459 and 2525 Goldilocks are missing. 2527 Licensing: Public Domain 2529 19. References 2531 19.1. Normative References 2533 [COAP.Formats] 2534 IANA, "CoAP Content-Formats", 2535 . 2538 [COSE.Algorithms] 2539 IANA, "COSE Algorithms", 2540 . 2543 [COSE.KeyParameters] 2544 IANA, "COSE Key Parameters", 2545 . 2548 [COSE.KeyTypes] 2549 IANA, "COSE Key Types", 2550 . 2553 [DSS] National Institute of Standards and Technology, "Digital 2554 Signature Standard (DSS)", FIPS PUB 186-4, 2555 DOI 10.6028/NIST.FIPS.186-4, July 2013, 2556 . 2559 [I-D.ietf-cose-rfc8152bis-algs] 2560 Schaad, J., "CBOR Object Signing and Encryption (COSE): 2561 Initial Algorithms", draft-ietf-cose-rfc8152bis-algs-02 2562 (work in progress), March 2019. 2564 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2565 Requirement Levels", BCP 14, RFC 2119, 2566 DOI 10.17487/RFC2119, March 1997, 2567 . 2569 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2570 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2571 October 2013, . 2573 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital 2574 Signature Algorithm (EdDSA)", RFC 8032, 2575 DOI 10.17487/RFC8032, January 2017, 2576 . 2578 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2579 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2580 May 2017, . 2582 19.2. Informative References 2584 [I-D.ietf-cbor-cddl] 2585 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 2586 definition language (CDDL): a notational convention to 2587 express CBOR and JSON data structures", draft-ietf-cbor- 2588 cddl-08 (work in progress), March 2019. 2590 [I-D.ietf-core-object-security] 2591 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 2592 "Object Security for Constrained RESTful Environments 2593 (OSCORE)", draft-ietf-core-object-security-16 (work in 2594 progress), March 2019. 2596 [PVSig] Brown, D. and D. Johnson, "Formal Security Proofs for a 2597 Signature Scheme with Partial Message Recovery", 2598 DOI 10.1007/3-540-45353-9_11, LNCS Volume 2020, June 2000. 2600 [RFC2633] Ramsdell, B., Ed., "S/MIME Version 3 Message 2601 Specification", RFC 2633, DOI 10.17487/RFC2633, June 1999, 2602 . 2604 [RFC4262] Santesson, S., "X.509 Certificate Extension for Secure/ 2605 Multipurpose Internet Mail Extensions (S/MIME) 2606 Capabilities", RFC 4262, DOI 10.17487/RFC4262, December 2607 2005, . 2609 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2610 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 2611 . 2613 [RFC4998] Gondrom, T., Brandner, R., and U. Pordesch, "Evidence 2614 Record Syntax (ERS)", RFC 4998, DOI 10.17487/RFC4998, 2615 August 2007, . 2617 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 2618 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 2619 . 2621 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 2622 RFC 5652, DOI 10.17487/RFC5652, September 2009, 2623 . 2625 [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet 2626 Mail Extensions (S/MIME) Version 3.2 Message 2627 Specification", RFC 5751, DOI 10.17487/RFC5751, January 2628 2010, . 2630 [RFC5752] Turner, S. and J. Schaad, "Multiple Signatures in 2631 Cryptographic Message Syntax (CMS)", RFC 5752, 2632 DOI 10.17487/RFC5752, January 2010, 2633 . 2635 [RFC5990] Randall, J., Kaliski, B., Brainard, J., and S. Turner, 2636 "Use of the RSA-KEM Key Transport Algorithm in the 2637 Cryptographic Message Syntax (CMS)", RFC 5990, 2638 DOI 10.17487/RFC5990, September 2010, 2639 . 2641 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 2642 Specifications and Registration Procedures", BCP 13, 2643 RFC 6838, DOI 10.17487/RFC6838, January 2013, 2644 . 2646 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2647 Application Protocol (CoAP)", RFC 7252, 2648 DOI 10.17487/RFC7252, June 2014, 2649 . 2651 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2652 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2653 2015, . 2655 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 2656 RFC 7516, DOI 10.17487/RFC7516, May 2015, 2657 . 2659 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 2660 DOI 10.17487/RFC7517, May 2015, 2661 . 2663 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 2664 DOI 10.17487/RFC7518, May 2015, 2665 . 2667 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 2668 Code: The Implementation Status Section", BCP 205, 2669 RFC 7942, DOI 10.17487/RFC7942, July 2016, 2670 . 2672 [RFC8018] Moriarty, K., Ed., Kaliski, B., and A. Rusch, "PKCS #5: 2673 Password-Based Cryptography Specification Version 2.1", 2674 RFC 8018, DOI 10.17487/RFC8018, January 2017, 2675 . 2677 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2678 Writing an IANA Considerations Section in RFCs", BCP 26, 2679 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2680 . 2682 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2683 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2684 . 2686 [RFC8230] Jones, M., "Using RSA Algorithms with CBOR Object Signing 2687 and Encryption (COSE) Messages", RFC 8230, 2688 DOI 10.17487/RFC8230, September 2017, 2689 . 2691 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2692 Interchange Format", STD 90, RFC 8259, 2693 DOI 10.17487/RFC8259, December 2017, 2694 . 2696 [W3C.WebCrypto] 2697 Watson, M., "Web Cryptography API", W3C Recommendation, 2698 January 2017, . 2700 Appendix A. Guidelines for External Data Authentication of Algorithms 2702 During development of COSE, the requirement that the algorithm 2703 identifier be located in the protected attributes was relaxed from a 2704 must to a should. There were two basic reasons that have been 2705 advanced to support this position. First, the resulting message will 2706 be smaller if the algorithm identifier is omitted from the most 2707 common messages in a CoAP environment. Second, there is a potential 2708 bug that will arise if full checking is not done correctly between 2709 the different places that an algorithm identifier could be placed 2710 (the message itself, an application statement, the key structure that 2711 the sender possesses, and the key structure the recipient possesses). 2713 This appendix lays out how such a change can be made and the details 2714 that an application needs to specify in order to use this option. 2715 Two different sets of details are specified: those needed to omit an 2716 algorithm identifier and those needed to use a variant on the counter 2717 signature attribute that contains no attributes about itself. 2719 Three sets of recommendations are laid out. The first set of 2720 recommendations apply to having an implicit algorithm identified for 2721 a single layer of a COSE object. The second set of recommendations 2722 apply to having multiple implicit algorithms identified for multiple 2723 layers of a COSE object. The third set of recommendations apply to 2724 having implicit algorithms for multiple COSE object constructs. 2726 The key words from [RFC2119] are deliberately not used here. This 2727 specification can provide recommendations, but it cannot enforce 2728 them. 2730 This set of recommendations applies to the case where an application 2731 is distributing a fixed algorithm along with the key information for 2732 use in a single COSE object. This normally applies to the smallest 2733 of the COSE objects, specifically COSE_Sign1, COSE_Mac0, and 2734 COSE_Encrypt0, but could apply to the other structures as well. 2736 The following items should be taken into account: 2738 o Applications need to list the set of COSE structures that implicit 2739 algorithms are to be used in. Applications need to require that 2740 the receipt of an explicit algorithm identifier in one of these 2741 structures will lead to the message being rejected. This 2742 requirement is stated so that there will never be a case where 2743 there is any ambiguity about the question of which algorithm 2744 should be used, the implicit or the explicit one. This applies 2745 even if the transported algorithm identifier is a protected 2746 attribute. This applies even if the transported algorithm is the 2747 same as the implicit algorithm. 2749 o Applications need to define the set of information that is to be 2750 considered to be part of a context when omitting algorithm 2751 identifiers. At a minimum, this would be the key identifier (if 2752 needed), the key, the algorithm, and the COSE structure it is used 2753 with. Applications should restrict the use of a single key to a 2754 single algorithm. As noted for some of the algorithms in this 2755 document, the use of the same key in different related algorithms 2756 can lead to leakage of information about the key, leakage about 2757 the data or the ability to perform forgeries. 2759 o In many cases, applications that make the algorithm identifier 2760 implicit will also want to make the context identifier implicit 2761 for the same reason. That is, omitting the context identifier 2762 will decrease the message size (potentially significantly 2763 depending on the length of the identifier). Applications that do 2764 this will need to describe the circumstances where the context 2765 identifier is to be omitted and how the context identifier is to 2766 be inferred in these cases. (An exhaustive search over all of the 2767 keys would normally not be considered to be acceptable.) An 2768 example of how this can be done is to tie the context to a 2769 transaction identifier. Both would be sent on the original 2770 message, but only the transaction identifier would need to be sent 2771 after that point as the context is tied into the transaction 2772 identifier. Another way would be to associate a context with a 2773 network address. All messages coming from a single network 2774 address can be assumed to be associated with a specific context. 2775 (In this case, the address would normally be distributed as part 2776 of the context.) 2778 o Applications cannot rely on key identifiers being unique unless 2779 they take significant efforts to ensure that they are computed in 2780 such a way as to create this guarantee. Even when an application 2781 does this, the uniqueness might be violated if the application is 2782 run in different contexts (i.e., with a different context 2783 provider) or if the system combines the security contexts from 2784 different applications together into a single store. 2786 o Applications should continue the practice of protecting the 2787 algorithm identifier. Since this is not done by placing it in the 2788 protected attributes field, applications should define an 2789 application-specific external data structure that includes this 2790 value. This external data field can be used as such for content 2791 encryption, MAC, and signature algorithms. It can be used in the 2792 SuppPrivInfo field for those algorithms that use a KDF to derive a 2793 key value. Applications may also want to protect other 2794 information that is part of the context structure as well. It 2795 should be noted that those fields, such as the key or a Base IV, 2796 are protected by virtue of being used in the cryptographic 2797 computation and do not need to be included in the external data 2798 field. 2800 The second case is having multiple implicit algorithm identifiers 2801 specified for a multiple layer COSE object. An example of how this 2802 would work is the encryption context that an application specifies, 2803 which contains a content encryption algorithm, a key wrap algorithm, 2804 a key identifier, and a shared secret. The sender omits sending the 2805 algorithm identifier for both the content layer and the recipient 2806 layer leaving only the key identifier. The receiver then uses the 2807 key identifier to get the implicit algorithm identifiers. 2809 The following additional items need to be taken into consideration: 2811 o Applications that want to support this will need to define a 2812 structure that allows for, and clearly identifies, both the COSE 2813 structure to be used with a given key and the structure and 2814 algorithm to be used for the secondary layer. The key for the 2815 secondary layer is computed as normal from the recipient layer. 2817 The third case is having multiple implicit algorithm identifiers, but 2818 targeted at potentially unrelated layers or different COSE objects. 2819 There are a number of different scenarios where this might be 2820 applicable. Some of these scenarios are: 2822 o Two contexts are distributed as a pair. Each of the contexts is 2823 for use with a COSE_Encrypt message. Each context will consist of 2824 distinct secret keys and IVs and potentially even different 2825 algorithms. One context is for sending messages from party A to 2826 party B, and the second context is for sending messages from party 2827 B to party A. This means that there is no chance for a reflection 2828 attack to occur as each party uses different secret keys to send 2829 its messages; a message that is reflected back to it would fail to 2830 decrypt. 2832 o Two contexts are distributed as a pair. The first context is used 2833 for encryption of the message, and the second context is used to 2834 place a counter signature on the message. The intention is that 2835 the second context can be distributed to other entities 2836 independently of the first context. This allows these entities to 2837 validate that the message came from an individual without being 2838 able to decrypt the message and see the content. 2840 o Two contexts are distributed as a pair. The first context 2841 contains a key for dealing with MACed messages, and the second 2842 context contains a key for dealing with encrypted messages. This 2843 allows for a unified distribution of keys to participants for 2844 different types of messages that have different keys, but where 2845 the keys may be used in a coordinated manner. 2847 For these cases, the following additional items need to be 2848 considered: 2850 o Applications need to ensure that the multiple contexts stay 2851 associated. If one of the contexts is invalidated for any reason, 2852 all of the contexts associated with it should also be invalidated. 2854 Appendix B. Two Layers of Recipient Information 2856 All of the currently defined recipient algorithm classes only use two 2857 layers of the COSE_Encrypt structure. The first layer is the message 2858 content, and the second layer is the content key encryption. 2859 However, if one uses a recipient algorithm such as the RSA Key 2860 Encapsulation Mechanism (RSA-KEM) (see Appendix A of RSA-KEM 2862 [RFC5990]), then it makes sense to have three layers of the 2863 COSE_Encrypt structure. 2865 These layers would be: 2867 o Layer 0: The content encryption layer. This layer contains the 2868 payload of the message. 2870 o Layer 1: The encryption of the CEK by a KEK. 2872 o Layer 2: The encryption of a long random secret using an RSA key 2873 and a key derivation function to convert that secret into the KEK. 2875 This is an example of what a triple layer message would look like. 2876 The message has the following layers: 2878 o Layer 0: Has a content encrypted with AES-GCM using a 128-bit key. 2880 o Layer 1: Uses the AES Key Wrap algorithm with a 128-bit key. 2882 o Layer 2: Uses ECDH Ephemeral-Static direct to generate the layer 1 2883 key. 2885 In effect, this example is a decomposed version of using the 2886 ECDH-ES+A128KW algorithm. 2888 Size of binary file is 183 bytes 2889 96( 2890 [ 2891 / protected / h'a10101' / { 2892 \ alg \ 1:1 \ AES-GCM 128 \ 2893 } / , 2894 / unprotected / { 2895 / iv / 5:h'02d1f7e6f26c43d4868d87ce' 2896 }, 2897 / ciphertext / h'64f84d913ba60a76070a9a48f26e97e863e2852948658f0 2898 811139868826e89218a75715b', 2899 / recipients / [ 2900 [ 2901 / protected / h'', 2902 / unprotected / { 2903 / alg / 1:-3 / A128KW / 2904 }, 2905 / ciphertext / h'dbd43c4e9d719c27c6275c67d628d493f090593db82 2906 18f11', 2907 / recipients / [ 2908 [ 2909 / protected / h'a1013818' / { 2910 \ alg \ 1:-25 \ ECDH-ES + HKDF-256 \ 2911 } / , 2912 / unprotected / { 2913 / ephemeral / -1:{ 2914 / kty / 1:2, 2915 / crv / -1:1, 2916 / x / -2:h'b2add44368ea6d641f9ca9af308b4079aeb519f11 2917 e9b8a55a600b21233e86e68', 2918 / y / -3:false 2919 }, 2920 / kid / 4:'meriadoc.brandybuck@buckland.example' 2921 }, 2922 / ciphertext / h'' 2923 ] 2924 ] 2925 ] 2926 ] 2927 ] 2928 ) 2930 Appendix C. Examples 2932 This appendix includes a set of examples that show the different 2933 features and message types that have been defined in this document. 2934 To make the examples easier to read, they are presented using the 2935 extended CBOR diagnostic notation (defined in [I-D.ietf-cbor-cddl]) 2936 rather than as a binary dump. 2938 A GitHub project has been created at that contains not only the examples presented in this 2940 document, but a more complete set of testing examples as well. Each 2941 example is found in a JSON file that contains the inputs used to 2942 create the example, some of the intermediate values that can be used 2943 in debugging the example and the output of the example presented in 2944 both a hex and a CBOR diagnostic notation format. Some of the 2945 examples at the site are designed failure testing cases; these are 2946 clearly marked as such in the JSON file. If errors in the examples 2947 in this document are found, the examples on GitHub will be updated, 2948 and a note to that effect will be placed in the JSON file. 2950 As noted, the examples are presented using the CBOR's diagnostic 2951 notation. A Ruby-based tool exists that can convert between the 2952 diagnostic notation and binary. This tool can be installed with the 2953 command line: 2955 gem install cbor-diag 2957 The diagnostic notation can be converted into binary files using the 2958 following command line: 2960 diag2cbor.rb < inputfile > outputfile 2962 The examples can be extracted from the XML version of this document 2963 via an XPath expression as all of the artwork is tagged with the 2964 attribute type='CBORdiag'. (Depending on the XPath evaluator one is 2965 using, it may be necessary to deal with > as an entity.) 2967 //artwork[@type='CDDL']/text() 2969 C.1. Examples of Signed Messages 2971 C.1.1. Single Signature 2973 This example uses the following: 2975 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 2977 Size of binary file is 103 bytes 2978 98( 2979 [ 2980 / protected / h'', 2981 / unprotected / {}, 2982 / payload / 'This is the content.', 2983 / signatures / [ 2984 [ 2985 / protected / h'a10126' / { 2986 \ alg \ 1:-7 \ ECDSA 256 \ 2987 } / , 2988 / unprotected / { 2989 / kid / 4:'11' 2990 }, 2991 / signature / h'e2aeafd40d69d19dfe6e52077c5d7ff4e408282cbefb 2992 5d06cbf414af2e19d982ac45ac98b8544c908b4507de1e90b717c3d34816fe926a2b 2993 98f53afd2fa0f30a' 2994 ] 2995 ] 2996 ] 2997 ) 2999 C.1.2. Multiple Signers 3001 This example uses the following: 3003 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 3005 o Signature Algorithm: ECDSA w/ SHA-512, Curve P-521 3007 Size of binary file is 277 bytes 3008 98( 3009 [ 3010 / protected / h'', 3011 / unprotected / {}, 3012 / payload / 'This is the content.', 3013 / signatures / [ 3014 [ 3015 / protected / h'a10126' / { 3016 \ alg \ 1:-7 \ ECDSA 256 \ 3017 } / , 3018 / unprotected / { 3019 / kid / 4:'11' 3020 }, 3021 / signature / h'e2aeafd40d69d19dfe6e52077c5d7ff4e408282cbefb 3022 5d06cbf414af2e19d982ac45ac98b8544c908b4507de1e90b717c3d34816fe926a2b 3023 98f53afd2fa0f30a' 3024 ], 3025 [ 3026 / protected / h'a1013823' / { 3027 \ alg \ 1:-36 3028 } / , 3029 / unprotected / { 3030 / kid / 4:'bilbo.baggins@hobbiton.example' 3031 }, 3032 / signature / h'00a2d28a7c2bdb1587877420f65adf7d0b9a06635dd1 3033 de64bb62974c863f0b160dd2163734034e6ac003b01e8705524c5c4ca479a952f024 3034 7ee8cb0b4fb7397ba08d009e0c8bf482270cc5771aa143966e5a469a09f613488030 3035 c5b07ec6d722e3835adb5b2d8c44e95ffb13877dd2582866883535de3bb03d01753f 3036 83ab87bb4f7a0297' 3037 ] 3038 ] 3039 ] 3040 ) 3042 C.1.3. Counter Signature 3044 This example uses the following: 3046 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 3048 o The same parameters are used for both the signature and the 3049 counter signature. 3051 Size of binary file is 180 bytes 3052 98( 3053 [ 3054 / protected / h'', 3055 / unprotected / { 3056 / countersign / 7:[ 3057 / protected / h'a10126' / { 3058 \ alg \ 1:-7 \ ECDSA 256 \ 3059 } / , 3060 / unprotected / { 3061 / kid / 4:'11' 3062 }, 3063 / signature / h'5ac05e289d5d0e1b0a7f048a5d2b643813ded50bc9e4 3064 9220f4f7278f85f19d4a77d655c9d3b51e805a74b099e1e085aacd97fc29d72f887e 3065 8802bb6650cceb2c' 3066 ] 3067 }, 3068 / payload / 'This is the content.', 3069 / signatures / [ 3070 [ 3071 / protected / h'a10126' / { 3072 \ alg \ 1:-7 \ ECDSA 256 \ 3073 } / , 3074 / unprotected / { 3075 / kid / 4:'11' 3076 }, 3077 / signature / h'e2aeafd40d69d19dfe6e52077c5d7ff4e408282cbefb 3078 5d06cbf414af2e19d982ac45ac98b8544c908b4507de1e90b717c3d34816fe926a2b 3079 98f53afd2fa0f30a' 3080 ] 3081 ] 3082 ] 3083 ) 3085 C.1.4. Signature with Criticality 3087 This example uses the following: 3089 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 3091 o There is a criticality marker on the "reserved" header parameter 3093 Size of binary file is 125 bytes 3094 98( 3095 [ 3096 / protected / h'a2687265736572766564f40281687265736572766564' / 3097 { 3098 "reserved":false, 3099 \ crit \ 2:[ 3100 "reserved" 3101 ] 3102 } / , 3103 / unprotected / {}, 3104 / payload / 'This is the content.', 3105 / signatures / [ 3106 [ 3107 / protected / h'a10126' / { 3108 \ alg \ 1:-7 \ ECDSA 256 \ 3109 } / , 3110 / unprotected / { 3111 / kid / 4:'11' 3112 }, 3113 / signature / h'3fc54702aa56e1b2cb20284294c9106a63f91bac658d 3114 69351210a031d8fc7c5ff3e4be39445b1a3e83e1510d1aca2f2e8a7c081c7645042b 3115 18aba9d1fad1bd9c' 3116 ] 3117 ] 3118 ] 3119 ) 3121 C.2. Single Signer Examples 3123 C.2.1. Single ECDSA Signature 3125 This example uses the following: 3127 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 3129 Size of binary file is 98 bytes 3130 18( 3131 [ 3132 / protected / h'a10126' / { 3133 \ alg \ 1:-7 \ ECDSA 256 \ 3134 } / , 3135 / unprotected / { 3136 / kid / 4:'11' 3137 }, 3138 / payload / 'This is the content.', 3139 / signature / h'8eb33e4ca31d1c465ab05aac34cc6b23d58fef5c083106c4 3140 d25a91aef0b0117e2af9a291aa32e14ab834dc56ed2a223444547e01f11d3b0916e5 3141 a4c345cacb36' 3142 ] 3143 ) 3145 C.3. Examples of Enveloped Messages 3147 C.3.1. Direct ECDH 3149 This example uses the following: 3151 o CEK: AES-GCM w/ 128-bit key 3153 o Recipient class: ECDH Ephemeral-Static, Curve P-256 3155 Size of binary file is 151 bytes 3156 96( 3157 [ 3158 / protected / h'a10101' / { 3159 \ alg \ 1:1 \ AES-GCM 128 \ 3160 } / , 3161 / unprotected / { 3162 / iv / 5:h'c9cf4df2fe6c632bf7886413' 3163 }, 3164 / ciphertext / h'7adbe2709ca818fb415f1e5df66f4e1a51053ba6d65a1a0 3165 c52a357da7a644b8070a151b0', 3166 / recipients / [ 3167 [ 3168 / protected / h'a1013818' / { 3169 \ alg \ 1:-25 \ ECDH-ES + HKDF-256 \ 3170 } / , 3171 / unprotected / { 3172 / ephemeral / -1:{ 3173 / kty / 1:2, 3174 / crv / -1:1, 3175 / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf 3176 bf054e1c7b4d91d6280', 3177 / y / -3:true 3178 }, 3179 / kid / 4:'meriadoc.brandybuck@buckland.example' 3180 }, 3181 / ciphertext / h'' 3182 ] 3183 ] 3184 ] 3185 ) 3187 C.3.2. Direct Plus Key Derivation 3189 This example uses the following: 3191 o CEK: AES-CCM w/ 128-bit key, truncate the tag to 64 bits 3193 o Recipient class: Use HKDF on a shared secret with the following 3194 implicit fields as part of the context. 3196 * salt: "aabbccddeeffgghh" 3198 * PartyU identity: "lighting-client" 3200 * PartyV identity: "lighting-server" 3202 * Supplementary Public Other: "Encryption Example 02" 3204 Size of binary file is 91 bytes 3206 96( 3207 [ 3208 / protected / h'a1010a' / { 3209 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 3210 } / , 3211 / unprotected / { 3212 / iv / 5:h'89f52f65a1c580933b5261a76c' 3213 }, 3214 / ciphertext / h'753548a19b1307084ca7b2056924ed95f2e3b17006dfe93 3215 1b687b847', 3216 / recipients / [ 3217 [ 3218 / protected / h'a10129' / { 3219 \ alg \ 1:-10 3220 } / , 3221 / unprotected / { 3222 / salt / -20:'aabbccddeeffgghh', 3223 / kid / 4:'our-secret' 3224 }, 3225 / ciphertext / h'' 3226 ] 3227 ] 3228 ] 3229 ) 3231 C.3.3. Counter Signature on Encrypted Content 3233 This example uses the following: 3235 o CEK: AES-GCM w/ 128-bit key 3237 o Recipient class: ECDH Ephemeral-Static, Curve P-256 3239 Size of binary file is 326 bytes 3240 96( 3241 [ 3242 / protected / h'a10101' / { 3243 \ alg \ 1:1 \ AES-GCM 128 \ 3244 } / , 3245 / unprotected / { 3246 / iv / 5:h'c9cf4df2fe6c632bf7886413', 3247 / countersign / 7:[ 3248 / protected / h'a1013823' / { 3249 \ alg \ 1:-36 3250 } / , 3251 / unprotected / { 3252 / kid / 4:'bilbo.baggins@hobbiton.example' 3253 }, 3254 / signature / h'00929663c8789bb28177ae28467e66377da12302d7f9 3255 594d2999afa5dfa531294f8896f2b6cdf1740014f4c7f1a358e3a6cf57f4ed6fb02f 3256 cf8f7aa989f5dfd07f0700a3a7d8f3c604ba70fa9411bd10c2591b483e1d2c31de00 3257 3183e434d8fba18f17a4c7e3dfa003ac1cf3d30d44d2533c4989d3ac38c38b71481c 3258 c3430c9d65e7ddff' 3259 ] 3260 }, 3261 / ciphertext / h'7adbe2709ca818fb415f1e5df66f4e1a51053ba6d65a1a0 3262 c52a357da7a644b8070a151b0', 3263 / recipients / [ 3264 [ 3265 / protected / h'a1013818' / { 3266 \ alg \ 1:-25 \ ECDH-ES + HKDF-256 \ 3267 } / , 3268 / unprotected / { 3269 / ephemeral / -1:{ 3270 / kty / 1:2, 3271 / crv / -1:1, 3272 / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf 3273 bf054e1c7b4d91d6280', 3274 / y / -3:true 3275 }, 3276 / kid / 4:'meriadoc.brandybuck@buckland.example' 3277 }, 3278 / ciphertext / h'' 3279 ] 3280 ] 3281 ] 3282 ) 3284 C.3.4. Encrypted Content with External Data 3286 This example uses the following: 3288 o CEK: AES-GCM w/ 128-bit key 3290 o Recipient class: ECDH static-Static, Curve P-256 with AES Key Wrap 3292 o Externally Supplied AAD: h'0011bbcc22dd44ee55ff660077' 3294 Size of binary file is 173 bytes 3296 96( 3297 [ 3298 / protected / h'a10101' / { 3299 \ alg \ 1:1 \ AES-GCM 128 \ 3300 } / , 3301 / unprotected / { 3302 / iv / 5:h'02d1f7e6f26c43d4868d87ce' 3303 }, 3304 / ciphertext / h'64f84d913ba60a76070a9a48f26e97e863e28529d8f5335 3305 e5f0165eee976b4a5f6c6f09d', 3306 / recipients / [ 3307 [ 3308 / protected / h'a101381f' / { 3309 \ alg \ 1:-32 \ ECHD-SS+A128KW \ 3310 } / , 3311 / unprotected / { 3312 / static kid / -3:'peregrin.took@tuckborough.example', 3313 / kid / 4:'meriadoc.brandybuck@buckland.example', 3314 / U nonce / -22:h'0101' 3315 }, 3316 / ciphertext / h'41e0d76f579dbd0d936a662d54d8582037de2e366fd 3317 e1c62' 3318 ] 3319 ] 3320 ] 3321 ) 3323 C.4. Examples of Encrypted Messages 3325 C.4.1. Simple Encrypted Message 3327 This example uses the following: 3329 o CEK: AES-CCM w/ 128-bit key and a 64-bit tag 3331 Size of binary file is 52 bytes 3332 16( 3333 [ 3334 / protected / h'a1010a' / { 3335 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 3336 } / , 3337 / unprotected / { 3338 / iv / 5:h'89f52f65a1c580933b5261a78c' 3339 }, 3340 / ciphertext / h'5974e1b99a3a4cc09a659aa2e9e7fff161d38ce71cb45ce 3341 460ffb569' 3342 ] 3343 ) 3345 C.4.2. Encrypted Message with a Partial IV 3347 This example uses the following: 3349 o CEK: AES-CCM w/ 128-bit key and a 64-bit tag 3351 o Prefix for IV is 89F52F65A1C580933B52 3353 Size of binary file is 41 bytes 3355 16( 3356 [ 3357 / protected / h'a1010a' / { 3358 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 3359 } / , 3360 / unprotected / { 3361 / partial iv / 6:h'61a7' 3362 }, 3363 / ciphertext / h'252a8911d465c125b6764739700f0141ed09192de139e05 3364 3bd09abca' 3365 ] 3366 ) 3368 C.5. Examples of MACed Messages 3370 C.5.1. Shared Secret Direct MAC 3372 This example uses the following: 3374 o MAC: AES-CMAC, 256-bit key, truncated to 64 bits 3376 o Recipient class: direct shared secret 3378 Size of binary file is 57 bytes 3379 97( 3380 [ 3381 / protected / h'a1010f' / { 3382 \ alg \ 1:15 \ AES-CBC-MAC-256//64 \ 3383 } / , 3384 / unprotected / {}, 3385 / payload / 'This is the content.', 3386 / tag / h'9e1226ba1f81b848', 3387 / recipients / [ 3388 [ 3389 / protected / h'', 3390 / unprotected / { 3391 / alg / 1:-6 / direct /, 3392 / kid / 4:'our-secret' 3393 }, 3394 / ciphertext / h'' 3395 ] 3396 ] 3397 ] 3398 ) 3400 C.5.2. ECDH Direct MAC 3402 This example uses the following: 3404 o MAC: HMAC w/SHA-256, 256-bit key 3406 o Recipient class: ECDH key agreement, two static keys, HKDF w/ 3407 context structure 3409 Size of binary file is 214 bytes 3410 97( 3411 [ 3412 / protected / h'a10105' / { 3413 \ alg \ 1:5 \ HMAC 256//256 \ 3414 } / , 3415 / unprotected / {}, 3416 / payload / 'This is the content.', 3417 / tag / h'81a03448acd3d305376eaa11fb3fe416a955be2cbe7ec96f012c99 3418 4bc3f16a41', 3419 / recipients / [ 3420 [ 3421 / protected / h'a101381a' / { 3422 \ alg \ 1:-27 \ ECDH-SS + HKDF-256 \ 3423 } / , 3424 / unprotected / { 3425 / static kid / -3:'peregrin.took@tuckborough.example', 3426 / kid / 4:'meriadoc.brandybuck@buckland.example', 3427 / U nonce / -22:h'4d8553e7e74f3c6a3a9dd3ef286a8195cbf8a23d 3428 19558ccfec7d34b824f42d92bd06bd2c7f0271f0214e141fb779ae2856abf585a583 3429 68b017e7f2a9e5ce4db5' 3430 }, 3431 / ciphertext / h'' 3432 ] 3433 ] 3434 ] 3435 ) 3437 C.5.3. Wrapped MAC 3439 This example uses the following: 3441 o MAC: AES-MAC, 128-bit key, truncated to 64 bits 3443 o Recipient class: AES Key Wrap w/ a pre-shared 256-bit key 3445 Size of binary file is 109 bytes 3446 97( 3447 [ 3448 / protected / h'a1010e' / { 3449 \ alg \ 1:14 \ AES-CBC-MAC-128//64 \ 3450 } / , 3451 / unprotected / {}, 3452 / payload / 'This is the content.', 3453 / tag / h'36f5afaf0bab5d43', 3454 / recipients / [ 3455 [ 3456 / protected / h'', 3457 / unprotected / { 3458 / alg / 1:-5 / A256KW /, 3459 / kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037' 3460 }, 3461 / ciphertext / h'711ab0dc2fc4585dce27effa6781c8093eba906f227 3462 b6eb0' 3463 ] 3464 ] 3465 ] 3466 ) 3468 C.5.4. Multi-Recipient MACed Message 3470 This example uses the following: 3472 o MAC: HMAC w/ SHA-256, 128-bit key 3474 o Recipient class: Uses three different methods 3476 1. ECDH Ephemeral-Static, Curve P-521, AES Key Wrap w/ 128-bit 3477 key 3479 2. AES Key Wrap w/ 256-bit key 3481 Size of binary file is 309 bytes 3482 97( 3483 [ 3484 / protected / h'a10105' / { 3485 \ alg \ 1:5 \ HMAC 256//256 \ 3486 } / , 3487 / unprotected / {}, 3488 / payload / 'This is the content.', 3489 / tag / h'bf48235e809b5c42e995f2b7d5fa13620e7ed834e337f6aa43df16 3490 1e49e9323e', 3491 / recipients / [ 3492 [ 3493 / protected / h'a101381c' / { 3494 \ alg \ 1:-29 \ ECHD-ES+A128KW \ 3495 } / , 3496 / unprotected / { 3497 / ephemeral / -1:{ 3498 / kty / 1:2, 3499 / crv / -1:3, 3500 / x / -2:h'0043b12669acac3fd27898ffba0bcd2e6c366d53bc4db 3501 71f909a759304acfb5e18cdc7ba0b13ff8c7636271a6924b1ac63c02688075b55ef2 3502 d613574e7dc242f79c3', 3503 / y / -3:true 3504 }, 3505 / kid / 4:'bilbo.baggins@hobbiton.example' 3506 }, 3507 / ciphertext / h'339bc4f79984cdc6b3e6ce5f315a4c7d2b0ac466fce 3508 a69e8c07dfbca5bb1f661bc5f8e0df9e3eff5' 3509 ], 3510 [ 3511 / protected / h'', 3512 / unprotected / { 3513 / alg / 1:-5 / A256KW /, 3514 / kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037' 3515 }, 3516 / ciphertext / h'0b2c7cfce04e98276342d6476a7723c090dfdd15f9a 3517 518e7736549e998370695e6d6a83b4ae507bb' 3518 ] 3519 ] 3520 ] 3521 ) 3523 C.6. Examples of MAC0 Messages 3525 C.6.1. Shared Secret Direct MAC 3527 This example uses the following: 3529 o MAC: AES-CMAC, 256-bit key, truncated to 64 bits 3530 o Recipient class: direct shared secret 3532 Size of binary file is 37 bytes 3534 17( 3535 [ 3536 / protected / h'a1010f' / { 3537 \ alg \ 1:15 \ AES-CBC-MAC-256//64 \ 3538 } / , 3539 / unprotected / {}, 3540 / payload / 'This is the content.', 3541 / tag / h'726043745027214f' 3542 ] 3543 ) 3545 Note that this example uses the same inputs as Appendix C.5.1. 3547 C.7. COSE Keys 3549 C.7.1. Public Keys 3551 This is an example of a COSE Key Set. This example includes the 3552 public keys for all of the previous examples. 3554 In order the keys are: 3556 o An EC key with a kid of "meriadoc.brandybuck@buckland.example" 3558 o An EC key with a kid of "peregrin.took@tuckborough.example" 3560 o An EC key with a kid of "bilbo.baggins@hobbiton.example" 3562 o An EC key with a kid of "11" 3564 Size of binary file is 481 bytes 3566 [ 3567 { 3568 -1:1, 3569 -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0 3570 8551d', 3571 -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008 3572 4d19c', 3573 1:2, 3574 2:'meriadoc.brandybuck@buckland.example' 3575 }, 3576 { 3577 -1:1, 3578 -2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a 3579 09eff', 3580 -3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbf 3581 c117e', 3582 1:2, 3583 2:'11' 3584 }, 3585 { 3586 -1:3, 3587 -2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737bf5de 3588 7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620085e5c8 3589 f42ad', 3590 -3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e247e 3591 60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3fe1ea1 3592 d9475', 3593 1:2, 3594 2:'bilbo.baggins@hobbiton.example' 3595 }, 3596 { 3597 -1:1, 3598 -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b4d91 3599 d6280', 3600 -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e03bf 3601 822bb', 3602 1:2, 3603 2:'peregrin.took@tuckborough.example' 3604 } 3605 ] 3607 C.7.2. Private Keys 3609 This is an example of a COSE Key Set. This example includes the 3610 private keys for all of the previous examples. 3612 In order the keys are: 3614 o An EC key with a kid of "meriadoc.brandybuck@buckland.example" 3616 o A shared-secret key with a kid of "our-secret" 3618 o An EC key with a kid of "peregrin.took@tuckborough.example" 3620 o A shared-secret key with a kid of "018c0ae5-4d9b-471b- 3621 bfd6-eef314bc7037" 3623 o An EC key with a kid of "bilbo.baggins@hobbiton.example" 3625 o An EC key with a kid of "11" 3627 Size of binary file is 816 bytes 3629 [ 3630 { 3631 1:2, 3632 2:'meriadoc.brandybuck@buckland.example', 3633 -1:1, 3634 -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0 3635 8551d', 3636 -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008 3637 4d19c', 3638 -4:h'aff907c99f9ad3aae6c4cdf21122bce2bd68b5283e6907154ad911840fa 3639 208cf' 3640 }, 3641 { 3642 1:2, 3643 2:'11', 3644 -1:1, 3645 -2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a 3646 09eff', 3647 -3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbf 3648 c117e', 3649 -4:h'57c92077664146e876760c9520d054aa93c3afb04e306705db609030850 3650 7b4d3' 3651 }, 3652 { 3653 1:2, 3654 2:'bilbo.baggins@hobbiton.example', 3655 -1:3, 3656 -2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737bf5de 3657 7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620085e5c8 3658 f42ad', 3659 -3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e247e 3660 60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3fe1ea1 3661 d9475', 3662 -4:h'00085138ddabf5ca975f5860f91a08e91d6d5f9a76ad4018766a476680b 3663 55cd339e8ab6c72b5facdb2a2a50ac25bd086647dd3e2e6e99e84ca2c3609fdf177f 3664 eb26d' 3665 }, 3666 { 3667 1:4, 3668 2:'our-secret', 3669 -1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dcea6c4 3670 27188' 3671 }, 3672 { 3673 1:2, 3674 -1:1, 3675 2:'peregrin.took@tuckborough.example', 3676 -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b4d91 3677 d6280', 3678 -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e03bf 3679 822bb', 3680 -4:h'02d1f7e6f26c43d4868d87ceb2353161740aacf1f7163647984b522a848 3681 df1c3' 3682 }, 3683 { 3684 1:4, 3685 2:'our-secret2', 3686 -1:h'849b5786457c1491be3a76dcea6c4271' 3687 }, 3688 { 3689 1:4, 3690 2:'018c0ae5-4d9b-471b-bfd6-eef314bc7037', 3691 -1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dcea6c4 3692 27188' 3693 } 3694 ] 3696 Acknowledgments 3698 This document is a product of the COSE working group of the IETF. 3700 The following individuals are to blame for getting me started on this 3701 project in the first place: Richard Barnes, Matt Miller, and Martin 3702 Thomson. 3704 The initial version of the specification was based to some degree on 3705 the outputs of the JOSE and S/MIME working groups. 3707 The following individuals provided input into the final form of the 3708 document: Carsten Bormann, John Bradley, Brain Campbell, Michael B. 3710 Jones, Ilari Liusvaara, Francesca Palombini, Ludwig Seitz, and Goran 3711 Selander. 3713 Author's Address 3715 Jim Schaad 3716 August Cellars 3718 Email: ietf@augustcellars.com