idnits 2.17.1 draft-ietf-cose-rfc8152bis-struct-05.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 : ---------------------------------------------------------------------------- ** There are 8 instances of too long lines in the document, the longest one being 2 characters in excess of 72. ** 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. -- The abstract seems to indicate that this document obsoletes RFC8152, but the header doesn't have an 'Obsoletes:' line to match this. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (August 18, 2019) is 1707 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-03 ** 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: 5 errors (**), 0 flaws (~~), 2 warnings (==), 6 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 Obsoletes8152 (if approved) August 18, 2019 5 Intended status: Standards Track 6 Expires: February 19, 2020 8 CBOR Object Signing and Encryption (COSE): Structures and Process 9 draft-ietf-cose-rfc8152bis-struct-05 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 This note is to be removed before publishing as an RFC. 29 The source for this draft is being maintained in GitHub. Suggested 30 changes should be submitted as pull requests at https://github.com/ 31 cose-wg/cose-rfc8152bis. Instructions are on that page as well. 32 Editorial changes can be managed in GitHub, but any substantial 33 issues need to be discussed on the COSE mailing list. 35 Status of This Memo 37 This Internet-Draft is submitted in full conformance with the 38 provisions of BCP 78 and BCP 79. 40 Internet-Drafts are working documents of the Internet Engineering 41 Task Force (IETF). Note that other groups may also distribute 42 working documents as Internet-Drafts. The list of current Internet- 43 Drafts is at https://datatracker.ietf.org/drafts/current/. 45 Internet-Drafts are draft documents valid for a maximum of six months 46 and may be updated, replaced, or obsoleted by other documents at any 47 time. It is inappropriate to use Internet-Drafts as reference 48 material or to cite them other than as "work in progress." 49 This Internet-Draft will expire on February 19, 2020. 51 Copyright Notice 53 Copyright (c) 2019 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 58 license-info) in effect on the date of publication of this document. 59 Please review these documents carefully, as they describe your rights 60 and restrictions with respect to this document. Code Components 61 extracted from this document must include Simplified BSD License text 62 as described in Section 4.e of the Trust Legal Provisions and are 63 provided without warranty as 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 . . . . . . . . . . . . . . . . 8 73 1.6. Document Terminology . . . . . . . . . . . . . . . . . . 8 74 2. Basic COSE Structure . . . . . . . . . . . . . . . . . . . . 9 75 3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 13 76 3.1. Common COSE Headers Parameters . . . . . . . . . . . . . 15 77 4. Signing Objects . . . . . . . . . . . . . . . . . . . . . . . 19 78 4.1. Signing with One or More Signers . . . . . . . . . . . . 19 79 4.2. Signing with One Signer . . . . . . . . . . . . . . . . . 21 80 4.3. Externally Supplied Data . . . . . . . . . . . . . . . . 22 81 4.4. Signing and Verification Process . . . . . . . . . . . . 23 82 5. Counter Signatures . . . . . . . . . . . . . . . . . . . . . 25 83 5.1. Full Countersignatures . . . . . . . . . . . . . . . . . 25 84 5.2. Abbreviated Countersignatures . . . . . . . . . . . . . . 26 85 6. Encryption Objects . . . . . . . . . . . . . . . . . . . . . 27 86 6.1. Enveloped COSE Structure . . . . . . . . . . . . . . . . 27 87 6.1.1. Content Key Distribution Methods . . . . . . . . . . 29 88 6.2. Single Recipient Encrypted . . . . . . . . . . . . . . . 29 89 6.3. How to Encrypt and Decrypt for AEAD Algorithms . . . . . 30 90 6.4. How to Encrypt and Decrypt for AE Algorithms . . . . . . 32 91 7. MAC Objects . . . . . . . . . . . . . . . . . . . . . . . . . 34 92 7.1. MACed Message with Recipients . . . . . . . . . . . . . . 34 93 7.2. MACed Messages with Implicit Key . . . . . . . . . . . . 35 94 7.3. How to Compute and Verify a MAC . . . . . . . . . . . . . 36 95 8. Key Objects . . . . . . . . . . . . . . . . . . . . . . . . . 38 96 8.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 38 98 9. Taxonomy of Algorithms used by COSE . . . . . . . . . . . . . 41 99 9.1. Signature Algorithms . . . . . . . . . . . . . . . . . . 42 100 9.2. Message Authentication Code (MAC) Algorithms . . . . . . 43 101 9.3. Content Encryption Algorithms . . . . . . . . . . . . . . 43 102 9.4. Key Derivation Functions (KDFs) . . . . . . . . . . . . . 44 103 9.5. Content Key Distribution Methods . . . . . . . . . . . . 44 104 9.5.1. Direct Encryption . . . . . . . . . . . . . . . . . . 45 105 9.5.2. Key Wrap . . . . . . . . . . . . . . . . . . . . . . 45 106 9.5.3. Key Transport . . . . . . . . . . . . . . . . . . . . 46 107 9.5.4. Direct Key Agreement . . . . . . . . . . . . . . . . 46 108 9.5.5. Key Agreement with Key Wrap . . . . . . . . . . . . . 47 109 10. CBOR Encoding Restrictions . . . . . . . . . . . . . . . . . 48 110 11. Application Profiling Considerations . . . . . . . . . . . . 48 111 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 49 112 12.1. CBOR Tag Assignment . . . . . . . . . . . . . . . . . . 50 113 12.2. COSE Header Parameters Registry . . . . . . . . . . . . 50 114 12.3. COSE Header Algorithm Parameters Registry . . . . . . . 50 115 12.4. COSE Key Common Parameters Registry . . . . . . . . . . 50 116 12.5. Media Type Registrations . . . . . . . . . . . . . . . . 51 117 12.5.1. COSE Security Message . . . . . . . . . . . . . . . 51 118 12.5.2. COSE Key Media Type . . . . . . . . . . . . . . . . 52 119 12.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 54 120 13. Security Considerations . . . . . . . . . . . . . . . . . . . 54 121 14. Implementation Status . . . . . . . . . . . . . . . . . . . . 56 122 14.1. Author's Versions . . . . . . . . . . . . . . . . . . . 56 123 14.2. JavaScript Version . . . . . . . . . . . . . . . . . . . 57 124 14.3. Python Version . . . . . . . . . . . . . . . . . . . . . 57 125 14.4. COSE Testing Library . . . . . . . . . . . . . . . . . . 58 126 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 58 127 15.1. Normative References . . . . . . . . . . . . . . . . . . 58 128 15.2. Informative References . . . . . . . . . . . . . . . . . 59 129 Appendix A. Guidelines for External Data Authentication of 130 Algorithms . . . . . . . . . . . . . . . . . . . . . . . 62 131 Appendix B. Two Layers of Recipient Information . . . . . . . . 65 132 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 67 133 C.1. Examples of Signed Messages . . . . . . . . . . . . . . . 67 134 C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 67 135 C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 68 136 C.1.3. Counter Signature . . . . . . . . . . . . . . . . . . 69 137 C.1.4. Signature with Criticality . . . . . . . . . . . . . 70 138 C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 71 139 C.2.1. Single ECDSA Signature . . . . . . . . . . . . . . . 71 140 C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 72 141 C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 72 142 C.3.2. Direct Plus Key Derivation . . . . . . . . . . . . . 73 143 C.3.3. Counter Signature on Encrypted Content . . . . . . . 74 144 C.3.4. Encrypted Content with External Data . . . . . . . . 75 145 C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 76 146 C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 76 147 C.4.2. Encrypted Message with a Partial IV . . . . . . . . . 77 148 C.5. Examples of MACed Messages . . . . . . . . . . . . . . . 77 149 C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 77 150 C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 78 151 C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 79 152 C.5.4. Multi-Recipient MACed Message . . . . . . . . . . . . 80 153 C.6. Examples of MAC0 Messages . . . . . . . . . . . . . . . . 81 154 C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 81 155 C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 82 156 C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 82 157 C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 83 158 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 85 159 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 86 161 1. Introduction 163 There has been an increased focus on small, constrained devices that 164 make up the Internet of Things (IoT). One of the standards that has 165 come out of this process is "Concise Binary Object Representation 166 (CBOR)" [RFC7049]. CBOR extended the data model of the JavaScript 167 Object Notation (JSON) [RFC8259] by allowing for binary data, among 168 other changes. CBOR has been adopted by several of the IETF working 169 groups dealing with the IoT world as their encoding of data 170 structures. CBOR was designed specifically to be both small in terms 171 of messages transport and implementation size and be a schema-free 172 decoder. A need exists to provide message security services for IoT, 173 and using CBOR as the message-encoding format makes sense. 175 The JOSE working group produced a set of documents [RFC7515] 176 [RFC7516] [RFC7517] [RFC7518] using JSON that specified how to 177 process encryption, signatures, and Message Authentication Code (MAC) 178 operations and how to encode keys using JSON. This document along 179 with [I-D.ietf-cose-rfc8152bis-algs] defines the CBOR Object Signing 180 and Encryption (COSE) standard, which does the same thing for the 181 CBOR encoding format. While there is a strong attempt to keep the 182 flavor of the original JSON Object Signing and Encryption (JOSE) 183 documents, two considerations are taken into account: 185 * CBOR has capabilities that are not present in JSON and are 186 appropriate to use. One example of this is the fact that CBOR has 187 a method of encoding binary directly without first converting it 188 into a base64-encoded string. 190 * COSE is not a direct copy of the JOSE specification. In the 191 process of creating COSE, decisions that were made for JOSE were 192 re-examined. In many cases, different results were decided on as 193 the criteria were not always the same. 195 This document contains: 197 * The description of the structure for the CBOR objects which are 198 transmitted over the wire. Two objects are defined for 199 encryption, signing and message authentication. One object is 200 defined for transporting keys and one for transporting groups of 201 keys. 203 * The procedures used to build the inputs to the cryptographic 204 functions required for each of the structures. 206 * A starting set of attributes that apply to the different security 207 objects. 209 This document does not contain the rules and procedures for using 210 specific cryptographic algorithms. Details on specific algorithms 211 can be found in [I-D.ietf-cose-rfc8152bis-algs] and [RFC8230]. 212 Details for additional algorithms are expected to be defined in 213 future documents. 215 One feature that is present in CMS [RFC5652] that is not present in 216 this standard is a digest structure. This omission is deliberate. 217 It is better for the structure to be defined in each document as 218 different protocols will want to include a different set of fields as 219 part of the structure. While an algorithm identifier and the digesst 220 value are going to be common to all applications, the two values may 221 not always be adjacent as the algorithm could be defined once with 222 multiple values. Applications may additionally want to define 223 additional data fields as part of the stucture. A common structure 224 is going to include a URI or other pointer to where the data that is 225 being hashed is kept, allowing this to be application specific. 227 1.1. Design Changes from JOSE 229 * Define a single top message structure so that encrypted, signed, 230 and MACed messages can easily be identified and still have a 231 consistent view. 233 * Signed messages distinguish between the protected and unprotected 234 parameters that relate to the content from those that relate to 235 the signature. 237 * MACed messages are separated from signed messages. 239 * MACed messages have the ability to use the same set of recipient 240 algorithms as enveloped messages for obtaining the MAC 241 authentication key. 243 * Use binary encodings for binary data rather than base64url 244 encodings. 246 * Combine the authentication tag for encryption algorithms with the 247 ciphertext. 249 * The set of cryptographic algorithms has been expanded in some 250 directions and trimmed in others. 252 1.2. Changes from RFC8152 254 * Split the orignal document into this document and 255 [I-D.ietf-cose-rfc8152bis-algs]. 257 * Add some text describing why there is no digest structure defined 258 by COSE. 260 * Rearrange the text around counter signatures and define a CBOR Tag 261 for a standalone countersignature. 263 1.3. Requirements Terminology 265 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 266 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 267 "OPTIONAL" in this document are to be interpreted as described in BCP 268 14 [RFC2119] [RFC8174] when, and only when, they appear in all 269 capitals, as shown here. 271 1.4. CBOR Grammar 273 There was not a standard CBOR grammar available when COSE was 274 originally written. For that reason the CBOR structures defined here 275 are described in prose. Since that time CBOR Data Definition 276 Language (CDDL) [RFC8610] has been published as an RFC. The CBOR 277 grammar presented in this document is compatible with CDDL. 279 The document was developed by first working on the grammar and then 280 developing the prose to go with it. An artifact of this is that the 281 prose was written using the primitive type strings defined by CBOR 282 Data Definition Language (CDDL) [RFC8610]. In this specification, 283 the following primitive types are used: 285 any -- non-specific value that permits all CBOR values to be 286 placed here. 288 bool -- a boolean value (true: major type 7, value 21; false: 289 major type 7, value 20). 291 bstr -- byte string (major type 2). 293 int -- an unsigned integer or a negative integer. 295 nil -- a null value (major type 7, value 22). 297 nint -- a negative integer (major type 1). 299 tstr -- a UTF-8 text string (major type 3). 301 uint -- an unsigned integer (major type 0). 303 Two syntaxes from CDDL appear in this document as shorthand. These 304 are: 306 FOO / BAR -- indicates that either FOO or BAR can appear here. 308 [+ FOO] -- indicates that the type FOO appears one or more times 309 in an array. 311 Two of the constraints defined by CDDL are also used in this 312 document. These are: 314 type1 .cbor type2 -- indicates that the contents of type1, usually 315 bstr, contains a value of type2. 317 type1 .size integer -- indicates that the contents of type1 is 318 integer bytes long 320 As well as the prose description, a version of a CBOR grammar is 321 presented in CDDL. The CDDL grammar is informational; the prose 322 description is normative. 324 The collected CDDL can be extracted from the XML version of this 325 document via the following XPath expression below. (Depending on the 326 XPath evaluator one is using, it may be necessary to deal with > 327 as an entity.) 329 //artwork[@type='CDDL']/text() 331 CDDL expects the initial non-terminal symbol to be the first symbol 332 in the file. For this reason, the first fragment of CDDL is 333 presented here. 335 start = COSE_Messages / COSE_Key / COSE_KeySet / Internal_Types 337 ; This is defined to make the tool quieter: 338 Internal_Types = Sig_structure / Enc_structure / MAC_structure 339 The non-terminal Internal_Types is defined for dealing with the 340 automated validation tools used during the writing of this document. 341 It references those non-terminals that are used for security 342 computations but are not emitted for transport. 344 1.5. CBOR-Related Terminology 346 In JSON, maps are called objects and only have one kind of map key: a 347 string. In COSE, we use strings, negative integers, and unsigned 348 integers as map keys. The integers are used for compactness of 349 encoding and easy comparison. The inclusion of strings allows for an 350 additional range of short encoded values to be used as well. Since 351 the word "key" is mainly used in its other meaning, as a 352 cryptographic key, we use the term "label" for this usage as a map 353 key. 355 The presence of a label in a COSE map that is not a string or an 356 integer is an error. Applications can either fail processing or 357 process messages by ignoring incorrect labels; however, they MUST NOT 358 create messages with incorrect labels. 360 A CDDL grammar fragment defines the non-terminal 'label', as in the 361 previous paragraph, and 'values', which permits any value to be used. 363 label = int / tstr 364 values = any 366 1.6. Document Terminology 368 In this document, we use the following terminology: 370 Byte is a synonym for octet. 372 Constrained Application Protocol (CoAP) is a specialized web transfer 373 protocol for use in constrained systems. It is defined in [RFC7252]. 375 Authenticated Encryption (AE) [RFC5116] algorithms are those 376 encryption algorithms that provide an authentication check of the 377 contents algorithm with the encryption service. 379 Authenticated Encryption with Associated Data (AEAD) [RFC5116] 380 algorithms provide the same content authentication service as AE 381 algorithms, but they additionally provide for authentication of non- 382 encrypted data as well. 384 Context is used throughout the document to represent information that 385 is not part of the COSE message. Information which is part of the 386 context can come from several different sources including: Protocol 387 interactions, associated key structures and program configuration. 388 The context to use can be implicit, identified using the 'kid 389 context' header field defined in [RFC8613], or identified by a 390 protocol specific identifier. Context should generally be included 391 in the cryptographic configuration, for more details see Section 4.3. 393 2. Basic COSE Structure 395 The COSE object structure is designed so that there can be a large 396 amount of common code when parsing and processing the different types 397 of security messages. All of the message structures are built on the 398 CBOR array type. The first three elements of the array always 399 contain the same information: 401 1. The set of protected header parameters wrapped in a bstr. 403 2. The set of unprotected header parameters as a map. 405 3. The content of the message. The content is either the plaintext 406 or the ciphertext as appropriate. The content may be detached 407 (i.e. transported separately from the COSE structure), but the 408 location is still used. The content is wrapped in a bstr when 409 present and is a nil value when detached. 411 Elements after this point are dependent on the specific message type. 413 COSE messages are built using the concept of layers to separate 414 different types of cryptographic concepts. As an example of how this 415 works, consider the COSE_Encrypt message (Section 6.1). This message 416 type is broken into two layers: the content layer and the recipient 417 layer. In the content layer, the plaintext is encrypted and 418 information about the encrypted message is placed. In the recipient 419 layer, the content encryption key (CEK) is encrypted and information 420 about how it is encrypted for each recipient is placed. A single 421 layer version of the encryption message COSE_Encrypt0 (Section 6.2) 422 is provided for cases where the CEK is pre-shared. 424 Identification of which type of message has been presented is done by 425 the following methods: 427 1. The specific message type is known from the context. This may be 428 defined by a marker in the containing structure or by 429 restrictions specified by the application protocol. 431 2. The message type is identified by a CBOR tag. Messages with a 432 CBOR tag are known in this specification as tagged messages, 433 while those without the CBOR tag are known as untagged messages. 435 This document defines a CBOR tag for each of the message 436 structures. These tags can be found in Table 1. 438 3. When a COSE object is carried in a media type of 'application/ 439 cose', the optional parameter 'cose-type' can be used to identify 440 the embedded object. The parameter is OPTIONAL if the tagged 441 version of the structure is used. The parameter is REQUIRED if 442 the untagged version of the structure is used. The value to use 443 with the parameter for each of the structures can be found in 444 Table 1. 446 4. When a COSE object is carried as a CoAP payload, the CoAP 447 Content-Format Option can be used to identify the message 448 content. The CoAP Content-Format values can be found in Table 2. 449 The CBOR tag for the message structure is not required as each 450 security message is uniquely identified. 452 +------+------------------+-----------------------+-------------+ 453 | CBOR | cose-type | Data Item | Semantics | 454 | Tag | | | | 455 +======+==================+=======================+=============+ 456 | 98 | cose-sign | COSE_Sign | COSE Signed | 457 | | | | Data Object | 458 +------+------------------+-----------------------+-------------+ 459 | 18 | cose-sign1 | COSE_Sign1 | COSE Single | 460 | | | | Signer Data | 461 | | | | Object | 462 +------+------------------+-----------------------+-------------+ 463 | 96 | cose-encrypt | COSE_Encrypt | COSE | 464 | | | | Encrypted | 465 | | | | Data Object | 466 +------+------------------+-----------------------+-------------+ 467 | 16 | cose-encrypt0 | COSE_Encrypt0 | COSE Single | 468 | | | | Recipient | 469 | | | | Encrypted | 470 | | | | Data Object | 471 +------+------------------+-----------------------+-------------+ 472 | 97 | cose-mac | COSE_Mac | COSE MACed | 473 | | | | Data Object | 474 +------+------------------+-----------------------+-------------+ 475 | 17 | cose-mac0 | COSE_Mac0 | COSE Mac w/ | 476 | | | | o | 477 | | | | Recipients | 478 | | | | Object | 479 +------+------------------+-----------------------+-------------+ 480 | TBD0 | cose-countersign | COSE_Countersignature | COSE | 481 | | | | standalone | 482 | | | | counter | 483 | | | | signature | 484 +------+------------------+-----------------------+-------------+ 486 Table 1: COSE Message Identification 488 +---------------------------+----------+-----+------------+ 489 | Media Type | Encoding | ID | Reference | 490 +===========================+==========+=====+============+ 491 | application/cose; cose- | | 98 | [[THIS | 492 | type="cose-sign" | | | DOCUMENT]] | 493 +---------------------------+----------+-----+------------+ 494 | application/cose; cose- | | 18 | [[THIS | 495 | type="cose-sign1" | | | DOCUMENT]] | 496 +---------------------------+----------+-----+------------+ 497 | application/cose; cose- | | 96 | [[THIS | 498 | type="cose-encrypt" | | | DOCUMENT]] | 499 +---------------------------+----------+-----+------------+ 500 | application/cose; cose- | | 16 | [[THIS | 501 | type="cose-encrypt0" | | | DOCUMENT]] | 502 +---------------------------+----------+-----+------------+ 503 | application/cose; cose- | | 97 | [[THIS | 504 | type="cose-mac" | | | DOCUMENT]] | 505 +---------------------------+----------+-----+------------+ 506 | application/cose; cose- | | 17 | [[THIS | 507 | type="cose-mac0" | | | DOCUMENT]] | 508 +---------------------------+----------+-----+------------+ 509 | application/cose-key | | 101 | [[THIS | 510 | | | | DOCUMENT]] | 511 +---------------------------+----------+-----+------------+ 512 | application/cose-key-set | | 102 | [[THIS | 513 | | | | DOCUMENT]] | 514 +---------------------------+----------+-----+------------+ 516 Table 2: CoAP Content-Formats for COSE 518 The following CDDL fragment identifies all of the top messages 519 defined in this document. Separate non-terminals are defined for the 520 tagged and the untagged versions of the messages. 522 COSE_Messages = COSE_Untagged_Message / COSE_Tagged_Message 524 COSE_Untagged_Message = COSE_Sign / COSE_Sign1 / 525 COSE_Encrypt / COSE_Encrypt0 / 526 COSE_Mac / COSE_Mac0 / COSE_Countersignature 528 COSE_Tagged_Message = COSE_Sign_Tagged / COSE_Sign1_Tagged / 529 COSE_Encrypt_Tagged / COSE_Encrypt0_Tagged / 530 COSE_Mac_Tagged / COSE_Mac0_Tagged / COSE_Countersignature_Tagged 532 3. Header Parameters 534 The structure of COSE has been designed to have two buckets of 535 information that are not considered to be part of the payload itself, 536 but are used for holding information about content, algorithms, keys, 537 or evaluation hints for the processing of the layer. These two 538 buckets are available for use in all of the structures except for 539 keys. While these buckets are present, they may not all be usable in 540 all instances. For example, while the protected bucket is defined as 541 part of the recipient structure, some of the algorithms used for 542 recipient structures do not provide for authenticated data. If this 543 is the case, the protected bucket is left empty. 545 Both buckets are implemented as CBOR maps. The map key is a 'label' 546 (Section 1.5). The value portion is dependent on the definition for 547 the label. Both maps use the same set of label/value pairs. The 548 integer and string values for labels have been divided into several 549 sections including a standard range, a private range, and a range 550 that is dependent on the algorithm selected. The defined labels can 551 be found in the "COSE Header Parameters" IANA registry 552 (Section 12.2). 554 The two buckets are: 556 protected: Contains parameters about the current layer that are 557 cryptographically protected. This bucket MUST be empty 558 if it is not going to be included in a cryptographic 559 computation. This bucket is encoded in the message as 560 a binary object. This value is obtained by CBOR 561 encoding the protected map and wrapping it in a bstr 562 object. Senders SHOULD encode a zero-length map as a 563 zero-length byte string rather than as a zero-length 564 map (encoded as h'a0'). The zero-length binary 565 encoding is preferred because it is both shorter and 566 the version used in the serialization structures for 567 cryptographic computation. After encoding the map, the 568 value is wrapped in the binary object. Recipients MUST 569 accept both a zero-length binary value and a zero- 570 length map encoded in the binary value. The wrapping 571 allows for the encoding of the protected map to be 572 transported with a greater chance that it will not be 573 altered in transit. (Badly behaved intermediates could 574 decode and re-encode, but this will result in a failure 575 to verify unless the re-encoded byte string is 576 identical to the decoded byte string.) This avoids the 577 problem of all parties needing to be able to do a 578 common canonical encoding. 580 unprotected: Contains parameters about the current layer that are 581 not cryptographically protected. 583 Only parameters that deal with the current layer are to be placed at 584 that layer. As an example of this, the parameter 'content type' 585 describes the content of the message being carried in the message. 586 As such, this parameter is placed only in the content layer and is 587 not placed in the recipient or signature layers. In principle, one 588 should be able to process any given layer without reference to any 589 other layer. With the exception of the COSE_Sign structure, the only 590 data that needs to cross layers is the cryptographic key. 592 The buckets are present in all of the security objects defined in 593 this document. The fields in order are the 'protected' bucket (as a 594 CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map' 595 type). The presence of both buckets is required. The parameters 596 that go into the buckets come from the IANA "COSE Header Parameters" 597 registry (Section 12.2). Some common parameters are defined in the 598 next section. 600 Labels in each of the maps MUST be unique. When processing messages, 601 if a label appears multiple times, the message MUST be rejected as 602 malformed. Applications SHOULD verify that the same label does not 603 occur in both the protected and unprotected headers. If the message 604 is not rejected as malformed, attributes MUST be obtained from the 605 protected bucket before they are obtained from the unprotected 606 bucket. 608 The following CDDL fragment represents the two header buckets. A 609 group "Headers" is defined in CDDL that represents the two buckets in 610 which attributes are placed. This group is used to provide these two 611 fields consistently in all locations. A type is also defined that 612 represents the map of common headers. 614 Headers = ( 615 protected : empty_or_serialized_map, 616 unprotected : header_map 617 ) 619 header_map = { 620 Generic_Headers, 621 * label => values 622 } 624 empty_or_serialized_map = bstr .cbor header_map / bstr .size 0 626 3.1. Common COSE Headers Parameters 628 This section defines a set of common header parameters. A summary of 629 these parameters can be found in Table 3. This table should be 630 consulted to determine the value of label and the type of the value. 632 The set of header parameters defined in this section are: 634 alg: This parameter is used to indicate the algorithm 635 used for the security processing. This parameter 636 MUST be authenticated where the ability to do so 637 exists. This support is provided by AEAD 638 algorithms or construction (COSE_Sign, 639 COSE_Sign1, COSE_Mac, and COSE_Mac0). This 640 authentication can be done either by placing the 641 parameter in the protected header bucket or as 642 part of the externally supplied data. The value 643 is taken from the "COSE Algorithms" registry (see 644 [COSE.Algorithms]). 646 crit: The parameter is used to indicate which protected 647 header labels an application that is processing a 648 message is required to understand. Parameters 649 defined in this document do not need to be 650 included as they should be understood by all 651 implementations. When present, this parameter 652 MUST be placed in the protected header bucket. 653 The array MUST have at least one value in it. 655 Not all labels need to be included in the 'crit' 656 parameter. The rules for deciding which header 657 labels are placed in the array are: 659 * Integer labels in the range of 0 to 7 SHOULD 660 be omitted. 662 * Integer labels in the range -1 to -128 can be 663 omitted as they are algorithm dependent. If 664 an application can correctly process an 665 algorithm, it can be assumed that it will 666 correctly process all of the common parameters 667 associated with that algorithm. Integer 668 labels in the range -129 to -65536 SHOULD be 669 included as these would be less common 670 parameters that might not be generally 671 supported. 673 * Labels for parameters required for an 674 application MAY be omitted. Applications 675 should have a statement if the label can be 676 omitted. 678 The header parameter values indicated by 'crit' 679 can be processed by either the security library 680 code or an application using a security library; 681 the only requirement is that the parameter is 682 processed. If the 'crit' value list includes a 683 value for which the parameter is not in the 684 protected bucket, this is a fatal error in 685 processing the message. 687 content type: This parameter is used to indicate the content 688 type of the data in the payload or ciphertext 689 fields. Integers are from the "CoAP Content- 690 Formats" IANA registry table [COAP.Formats]. 691 Text values following the syntax of "/" where and 693 are defined in Section 4.2 of 694 [RFC6838]. Leading and trailing whitespace is 695 also omitted. Textual content values along with 696 parameters and subparameters can be located using 697 the IANA "Media Types" registry. Applications 698 SHOULD provide this parameter if the content 699 structure is potentially ambiguous. 701 kid: This parameter identifies one piece of data that 702 can be used as input to find the needed 703 cryptographic key. The value of this parameter 704 can be matched against the 'kid' member in a 705 COSE_Key structure. Other methods of key 706 distribution can define an equivalent field to be 707 matched. Applications MUST NOT assume that 'kid' 708 values are unique. There may be more than one 709 key with the same 'kid' value, so all of the keys 710 associated with this 'kid' may need to be 711 checked. The internal structure of 'kid' values 712 is not defined and cannot be relied on by 713 applications. Key identifier values are hints 714 about which key to use. This is not a security- 715 critical field. For this reason, it can be 716 placed in the unprotected headers bucket. 718 IV: This parameter holds the Initialization Vector 719 (IV) value. For some symmetric encryption 720 algorithms, this may be referred to as a nonce. 721 The IV can be placed in the unprotected header as 722 modifying the IV will cause the decryption to 723 yield plaintext that is readily detectable as 724 garbled. 726 Partial IV: This parameter holds a part of the IV value. 727 When using the COSE_Encrypt0 structure, a portion 728 of the IV can be part of the context associated 729 with the key (Context IV) while a portion can be 730 changed with each message (Parital IV). This 731 field is used to carry a value that causes the IV 732 to be changed for each message. The Parital IV 733 can be placed in the unprotected header as 734 modifying the value will cause the decryption to 735 yield plaintext that is readily detectable as 736 garbled. The 'Initialization Vector' and 737 'Partial Initialization Vector' parameters MUST 738 NOT both be present in the same security layer. 740 The message IV is generated by the following 741 steps: 743 1. Left-pad the Partial IV with zeros to the 744 length of IV. 746 2. XOR the padded Partial IV with the context 747 IV. 749 counter signature: This parameter holds one or more counter 750 signature values. Counter signatures provide a 751 method of having a second party sign some data. 752 The counter signature parameter can occur as an 753 unprotected attribute in any of the following 754 structures: COSE_Sign1, COSE_Signature, 755 COSE_Encrypt, COSE_recipient, COSE_Encrypt0, 756 COSE_Mac, and COSE_Mac0. These structures all 757 have the same beginning elements, so that a 758 consistent calculation of the counter signature 759 can be computed. Details on counter signatures 760 are found in Section 5. 762 +---------+-----+----------------+-----------------+----------------+ 763 |Name |Label| Value Type | Value Registry | Description | 764 +=========+=====+================+=================+================+ 765 |alg |1 | int / tstr | COSE Algorithms | Cryptographic | 766 | | | | registry | algorithm to use | 767 +---------+-----+----------------+-----------------+----------------+ 768 |crit |2 | [+ label] | COSE Header | Critical headers | 769 | | | | Parameters | to be understood | 770 | | | | registry | | 771 +---------+-----+----------------+-----------------+----------------+ 772 |content |3 | tstr / uint | CoAP Content- | Content type of | 773 |type | | | Formats or Media | the payload | 774 | | | | Types registries | | 775 +---------+-----+----------------+-----------------+----------------+ 776 |kid |4 | bstr | | Key identifier | 777 +---------+-----+----------------+-----------------+----------------+ 778 |IV |5 | bstr | | Full | 779 | | | | | Initialization | 780 | | | | | Vector | 781 +---------+-----+----------------+-----------------+----------------+ 782 |Partial |6 | bstr | | Partial | 783 |IV | | | | Initialization | 784 | | | | | Vector | 785 +---------+-----+----------------+-----------------+----------------+ 786 |counter |7 | COSE_Signature / | | CBOR-encoded | 787 |signature| | [+ | | signature | 788 | | | COSE_Signature ] | | structure | 789 +---------+-----+----------------+-----------------+----------------+ 791 Table 3: Common Header Parameters 793 The CDDL fragment that represents the set of headers defined in this 794 section is given below. Each of the headers is tagged as optional 795 because they do not need to be in every map; headers required in 796 specific maps are discussed above. 798 Generic_Headers = ( 799 ? 1 => int / tstr, ; algorithm identifier 800 ? 2 => [+label], ; criticality 801 ? 3 => tstr / int, ; content type 802 ? 4 => bstr, ; key identifier 803 ? 5 => bstr, ; IV 804 ? 6 => bstr, ; Partial IV 805 ? 7 => COSE_Signature / [+COSE_Signature] ; Counter signature 806 ) 808 4. Signing Objects 810 COSE supports two different signature structures. COSE_Sign allows 811 for one or more signatures to be applied to the same content. 812 COSE_Sign1 is restricted to a single signer. The structures cannot 813 be converted between each other; as the signature computation 814 includes a parameter identifying which structure is being used, the 815 converted structure will fail signature validation. 817 4.1. Signing with One or More Signers 819 The COSE_Sign structure allows for one or more signatures to be 820 applied to a message payload. Parameters relating to the content and 821 parameters relating to the signature are carried along with the 822 signature itself. These parameters may be authenticated by the 823 signature, or just present. An example of a parameter about the 824 content is the content type. Examples of parameters about the 825 signature would be the algorithm and key used to create the signature 826 and counter signatures. 828 RFC 5652 indicates that: 830 | When more than one signature is present, the successful validation 831 | of one signature associated with a given signer is usually treated 832 | as a successful signature by that signer. However, there are some 833 | application environments where other rules are needed. An 834 | application that employs a rule other than one valid signature for 835 | each signer must specify those rules. Also, where simple matching 836 | of the signer identifier is not sufficient to determine whether 837 | the signatures were generated by the same signer, the application 838 | specification must describe how to determine which signatures were 839 | generated by the same signer. Support for different communities 840 | of recipients is the primary reason that signers choose to include 841 | more than one signature. 843 For example, the COSE_Sign structure might include signatures 844 generated with the Edwards-curve Digital Signature Algorithm (EdDSA) 845 [RFC8032] and with the Elliptic Curve Digital Signature Algorithm 846 (ECDSA) [DSS]. This allows recipients to verify the signature 847 associated with one algorithm or the other. More-detailed 848 information on multiple signature evaluations can be found in 849 [RFC5752]. 851 The signature structure can be encoded as either tagged or untagged 852 depending on the context it will be used in. A tagged COSE_Sign 853 structure is identified by the CBOR tag 98. The CDDL fragment that 854 represents this is: 856 COSE_Sign_Tagged = #6.98(COSE_Sign) 858 A COSE Signed Message is defined in two parts. The CBOR object that 859 carries the body and information about the body is called the 860 COSE_Sign structure. The CBOR object that carries the signature and 861 information about the signature is called the COSE_Signature 862 structure. Examples of COSE Signed Messages can be found in 863 Section c.1. 865 The COSE_Sign structure is a CBOR array. The fields of the array in 866 order are: 868 protected: This is as described in Section 3. 870 unprotected: This is as described in Section 3. 872 payload: This field contains the serialized content to be 873 signed. If the payload is not present in the message, 874 the application is required to supply the payload 875 separately. The payload is wrapped in a bstr to ensure 876 that it is transported without changes. If the payload 877 is transported separately ("detached content"), then a 878 nil CBOR object is placed in this location, and it is 879 the responsibility of the application to ensure that it 880 will be transported without changes. 882 Note: When a signature with a message recovery 883 algorithm is used (Section 9.1), the maximum number of 884 bytes that can be recovered is the length of the 885 payload. The size of the payload is reduced by the 886 number of bytes that will be recovered. If all of the 887 bytes of the payload are consumed, then the payload is 888 encoded as a zero-length binary string rather than as 889 being absent. 891 signatures: This field is an array of signatures. Each signature 892 is represented as a COSE_Signature structure. 894 The CDDL fragment that represents the above text for COSE_Sign 895 follows. 897 COSE_Sign = [ 898 Headers, 899 payload : bstr / nil, 900 signatures : [+ COSE_Signature] 901 ] 902 The COSE_Signature structure is a CBOR array. The fields of the 903 array in order are: 905 protected: This is as described in Section 3. 907 unprotected: This is as described in Section 3. 909 signature: This field contains the computed signature value. The 910 type of the field is a bstr. Algorithms MUST specify 911 padding if the signature value is not a multiple of 8 912 bits. 914 The CDDL fragment that represents the above text for COSE_Signature 915 follows. 917 COSE_Signature = [ 918 Headers, 919 signature : bstr 920 ] 922 4.2. Signing with One Signer 924 The COSE_Sign1 signature structure is used when only one signature is 925 going to be placed on a message. The parameters dealing with the 926 content and the signature are placed in the same pair of buckets 927 rather than having the separation of COSE_Sign. 929 The structure can be encoded as either tagged or untagged depending 930 on the context it will be used in. A tagged COSE_Sign1 structure is 931 identified by the CBOR tag 18. The CDDL fragment that represents 932 this is: 934 COSE_Sign1_Tagged = #6.18(COSE_Sign1) 936 The CBOR object that carries the body, the signature, and the 937 information about the body and signature is called the COSE_Sign1 938 structure. Examples of COSE_Sign1 messages can be found in 939 Section c.2. 941 The COSE_Sign1 structure is a CBOR array. The fields of the array in 942 order are: 944 protected: This is as described in Section 3. 946 unprotected: This is as described in Section 3. 948 payload: This is as described in Section 4.1. 950 signature: This field contains the computed signature value. The 951 type of the field is a bstr. 953 The CDDL fragment that represents the above text for COSE_Sign1 954 follows. 956 COSE_Sign1 = [ 957 Headers, 958 payload : bstr / nil, 959 signature : bstr 960 ] 962 4.3. Externally Supplied Data 964 One of the features offered in the COSE document is the ability for 965 applications to provide additional data to be authenticated, but that 966 is not carried as part of the COSE object. The primary reason for 967 supporting this can be seen by looking at the CoAP message structure 968 [RFC7252], where the facility exists for options to be carried before 969 the payload. Examples of data that can be placed in this location 970 would be the CoAP code or CoAP options. If the data is in the header 971 section, then it is available for proxies to help in performing its 972 operations. For example, the Accept Option can be used by a proxy to 973 determine if an appropriate value is in the proxy's cache. But the 974 sender can cause a failure at the server if a proxy, or an attacker, 975 changes the set of accept values by including the field in the 976 application supplied data. 978 This document describes the process for using a byte array of 979 externally supplied authenticated data; the method of constructing 980 the byte array is a function of the application. Applications that 981 use this feature need to define how the externally supplied 982 authenticated data is to be constructed. Such a construction needs 983 to take into account the following issues: 985 * If multiple items are included, applications need to ensure that 986 the same byte string cannot produced if there are different 987 inputs. This would occur by appending the strings 'AB' and 'CDE' 988 or by appending the strings 'ABC' and 'DE'. This is usually 989 addressed by making fields a fixed width and/or encoding the 990 length of the field as part of the output. Using options from 991 CoAP [RFC7252] as an example, these fields use a TLV structure so 992 they can be concatenated without any problems. 994 * If multiple items are included, an order for the items needs to be 995 defined. Using options from CoAP as an example, an application 996 could state that the fields are to be ordered by the option 997 number. 999 * Applications need to ensure that the byte string is going to be 1000 the same on both sides. Using options from CoAP might give a 1001 problem if the same relative numbering is kept. An intermediate 1002 node could insert or remove an option, changing how the relative 1003 number is done. An application would need to specify that the 1004 relative number must be re-encoded to be relative only to the 1005 options that are in the external data. 1007 4.4. Signing and Verification Process 1009 In order to create a signature, a well-defined byte string is needed. 1010 The Sig_structure is used to create the canonical form. This signing 1011 and verification process takes in the body information (COSE_Sign or 1012 COSE_Sign1), the signer information (COSE_Signature), and the 1013 application data (external source). A Sig_structure is a CBOR array. 1014 The fields of the Sig_structure in order are: 1016 1. A text string identifying the context of the signature. The 1017 context string is: 1019 "Signature" for signatures using the COSE_Signature structure. 1021 "Signature1" for signatures using the COSE_Sign1 structure. 1023 "CounterSignature" for signatures used as counter signature 1024 attributes. 1026 "CounterSignature0" for signatures used as CounterSignature0 1027 attributes. 1029 2. The protected attributes from the body structure encoded in a 1030 bstr type. If there are no protected attributes, a bstr of 1031 length zero is used. 1033 3. The protected attributes from the signer structure encoded in a 1034 bstr type. If there are no protected attributes, a bstr of 1035 length zero is used. This field is omitted for the COSE_Sign1 1036 signature structure and CounterSignature0 attributes. 1038 4. The protected attributes from the application encoded in a bstr 1039 type. If this field is not supplied, it defaults to a zero- 1040 length binary string. (See Section 4.3 for application guidance 1041 on constructing this field.) 1043 5. The payload to be signed encoded in a bstr type. The payload is 1044 placed here independent of how it is transported. 1046 The CDDL fragment that describes the above text is: 1048 Sig_structure = [ 1049 context : "Signature" / "Signature1" / "CounterSignature" / 1050 "CounterSignature0", 1051 body_protected : empty_or_serialized_map, 1052 ? sign_protected : empty_or_serialized_map, 1053 external_aad : bstr, 1054 payload : bstr 1055 ] 1057 How to compute a signature: 1059 1. Create a Sig_structure and populate it with the appropriate 1060 fields. 1062 2. Create the value ToBeSigned by encoding the Sig_structure to a 1063 byte string, using the encoding described in Section 10. 1065 3. Call the signature creation algorithm passing in K (the key to 1066 sign with), alg (the algorithm to sign with), and ToBeSigned (the 1067 value to sign). 1069 4. Place the resulting signature value in the correct location. 1070 This is the 'signature' field of the COSE_Signature, COSE_Sign1 1071 or COSE_Countersignature structures. This is the value of the 1072 Countersignature0 attribute. 1074 The steps for verifying a signature are: 1076 1. Create a Sig_structure object and populate it with the 1077 appropriate fields. 1079 2. Create the value ToBeSigned by encoding the Sig_structure to a 1080 byte string, using the encoding described in Section 10. 1082 3. Call the signature verification algorithm passing in K (the key 1083 to verify with), alg (the algorithm used sign with), ToBeSigned 1084 (the value to sign), and sig (the signature to be verified). 1086 In addition to performing the signature verification, the application 1087 performs the appropriate checks to ensure that the key is correctly 1088 paired with the signing identity and that the signing identity is 1089 authorized before performing actions. 1091 5. Counter Signatures 1093 COSE supports two different forms for counter signatures. Full 1094 countersignatures use the structure COSE_Countersign. This is same 1095 structure as COSE_Signature and thus it can have protected 1096 attributes, chained countersignatures and information about 1097 identifying the key. Abbreviated countersignatures use the structure 1098 COSE_Countersign1. This structure only contains the signature value 1099 and nothing else. The structures cannot be converted between each 1100 other; as the signature computation includes a parameter identifying 1101 which structure is being used, the converted structure will fail 1102 signature validation. 1104 COSE was designed for uniformity in how the data strutures are 1105 specified. One result of this is that for COSE one can expand the 1106 concept of countersignatures beyond just the idea of signing a 1107 signature to being able to sign most of the structures without having 1108 to create a new signing layer. When creating a countersignature, one 1109 needs to be clear about the security properties that result. When 1110 done on a COSE_Signature, the normal countersignature semantics are 1111 preserved. That is the countersignature makes a statement about the 1112 existence of a signature and, when used as a timestamp, a time point 1113 at which the signature exists. When done on a COSE_Mac or a 1114 COSE_Mac0, one effectively upgrades the MAC operation to a sginature 1115 operation. When done on a COSE_Encrypt or COSE_Encrypt0, the 1116 existence of the encrypted data is attested to. It should be noted 1117 that there is a big difference between attesting to the encrypted 1118 data as opposed to attesting to the unencrypted data. If the latter 1119 is what is desired, then one needs to apply a signature to the data 1120 and then encrypt that. It is always possible to construct cases 1121 where the decryption is successful, while providing completely 1122 different answers by using a different key. This situation is not 1123 detectable by a countersignature on the encrypted data. 1125 5.1. Full Countersignatures 1127 The COSE_Countersignature structure allows for the same set of 1128 capabilities of a COSE_Signature. This means that all of the 1129 capabilities of a signature are duplicated with this structure. 1130 Specifically, the countersigner does not need to be related to the 1131 producer of what is being counter signed as key and algorithm 1132 identification can be placed in the countersignature attributes. 1133 This also means that the countersignature can itself be 1134 countersigned. This is a feature required by protocols such as long- 1135 term archiving services. More information on how this is used can be 1136 found in the evidence record syntax described in [RFC4998]. 1138 The full countersignature structure can be encoded as either a tagged 1139 or untagged depending on the context it is used in. A tagged 1140 COSE_Countersign structure is identified by the CBOR tag TBD0. The 1141 CDDL fragment for full countersignatures is: 1143 COSE_CounterSignature_Tagged = #6.98(COSE_CounterSignature) 1144 COSE_CounterSignature = COSE_Signature 1146 The details of the fields of a countersignature can be found in 1147 Section 4.1. The process of creating and validating abbreviated 1148 countersignatures is defined in Section 4.4. 1150 An example of a counter signature on a signature can be found in 1151 Section c.1.3. An example of a counter signature in an encryption 1152 object can be found in Section c.3.3. 1154 It should be noted that only a signature algorithm with appendix (see 1155 Section 9.1) can be used for counter signatures. This is because the 1156 body should be able to be processed without having to evaluate the 1157 counter signature, and this is not possible for signature schemes 1158 with message recovery. 1160 5.2. Abbreviated Countersignatures 1162 Abbreviated countersignatures were designed primarily to deal with 1163 the problem of having group encrypted messaging, but still needing to 1164 know who originated the message. The objective was to keep the 1165 countersignature as small as possible while still providing the 1166 needed security. For abbreviated countersignatures, there is no 1167 provision for any protected attributes related to the signing 1168 operation. Instead, the parameters for computing or verifying the 1169 abbreviated countersignature are inferred from the same context used 1170 to describe the encryption, signature, or MAC processing. 1172 The byte string representing the signature value is placed in the 1173 CounterSignature0 attribute. This attribute is then encoded as an 1174 unprotected header. The attribute is defined below. 1176 The process of creating and validating abbreviated countersignatures 1177 is defined in Section 4.4. 1179 +-------------------+-------+------------+-------+------------------+ 1180 | Name | Label | Value | Value | Description | 1181 | | | Type | | | 1182 +===================+=======+============+=======+==================+ 1183 | CounterSignature0 | 9 | bstr | | Abbreviated | 1184 | | | | | Countersignature | 1185 +-------------------+-------+------------+-------+------------------+ 1187 Table 4: Header Parameter for CounterSignature0 1189 6. Encryption Objects 1191 COSE supports two different encryption structures. COSE_Encrypt0 is 1192 used when a recipient structure is not needed because the key to be 1193 used is known implicitly. COSE_Encrypt is used the rest of the time. 1194 This includes cases where there are multiple recipients or a 1195 recipient algorithm other than direct (i.e. pre-shared secret) is 1196 used. 1198 6.1. Enveloped COSE Structure 1200 The enveloped structure allows for one or more recipients of a 1201 message. There are provisions for parameters about the content and 1202 parameters about the recipient information to be carried in the 1203 message. The protected parameters associated with the content are 1204 authenticated by the content encryption algorithm. The protected 1205 parameters associated with the recipient are authenticated by the 1206 recipient algorithm (when the algorithm supports it). Examples of 1207 parameters about the content are the type of the content and the 1208 content encryption algorithm. Examples of parameters about the 1209 recipient are the recipient's key identifier and the recipient's 1210 encryption algorithm. 1212 The same techniques and nearly the same structure is used for 1213 encrypting both the plaintext and the keys. This is different from 1214 the approach used by both "Cryptographic Message Syntax (CMS)" 1215 [RFC5652] and "JSON Web Encryption (JWE)" [RFC7516] where different 1216 structures are used for the content layer and for the recipient 1217 layer. Two structures are defined: COSE_Encrypt to hold the 1218 encrypted content and COSE_recipient to hold the encrypted keys for 1219 recipients. Examples of encrypted messages can be found in 1220 Section c.3. 1222 The COSE_Encrypt structure can be encoded as either tagged or 1223 untagged depending on the context it will be used in. A tagged 1224 COSE_Encrypt structure is identified by the CBOR tag 96. The CDDL 1225 fragment that represents this is: 1227 COSE_Encrypt_Tagged = #6.96(COSE_Encrypt) 1229 The COSE_Encrypt structure is a CBOR array. The fields of the array 1230 in order are: 1232 protected: This is as described in Section 3. 1234 unprotected: This is as described in Section 3. 1236 ciphertext: This field contains the ciphertext encoded as a bstr. 1237 If the ciphertext is to be transported independently of 1238 the control information about the encryption process 1239 (i.e., detached content), then the field is encoded as 1240 a nil value. 1242 recipients: This field contains an array of recipient information 1243 structures. The type for the recipient information 1244 structure is a COSE_recipient. 1246 The CDDL fragment that corresponds to the above text is: 1248 COSE_Encrypt = [ 1249 Headers, 1250 ciphertext : bstr / nil, 1251 recipients : [+COSE_recipient] 1252 ] 1254 The COSE_recipient structure is a CBOR array. The fields of the 1255 array in order are: 1257 protected: This is as described in Section 3. 1259 unprotected: This is as described in Section 3. 1261 ciphertext: This field contains the encrypted key encoded as a 1262 bstr. All encoded keys are symmetric keys; the binary 1263 value of the key is the content. If there is not an 1264 encrypted key, then this field is encoded as a nil 1265 value. 1267 recipients: This field contains an array of recipient information 1268 structures. The type for the recipient information 1269 structure is a COSE_recipient (an example of this can 1270 be found in Appendix B). If there are no recipient 1271 information structures, this element is absent. 1273 The CDDL fragment that corresponds to the above text for 1274 COSE_recipient is: 1276 COSE_recipient = [ 1277 Headers, 1278 ciphertext : bstr / nil, 1279 ? recipients : [+COSE_recipient] 1280 ] 1282 6.1.1. Content Key Distribution Methods 1284 An encrypted message consists of an encrypted content and an 1285 encrypted CEK for one or more recipients. The CEK is encrypted for 1286 each recipient, using a key specific to that recipient. The details 1287 of this encryption depend on which class the recipient algorithm 1288 falls into. Specific details on each of the classes can be found in 1289 Section 9.5. A short summary of the five content key distribution 1290 methods is: 1292 direct: The CEK is the same as the identified previously distributed 1293 symmetric key or is derived from a previously distributed secret. 1294 No CEK is transported in the message. 1296 symmetric key-encryption keys (KEK): The CEK is encrypted using a 1297 previously distributed symmetric KEK. Also known as key wrap. 1299 key agreement: The recipient's public key and a sender's private key 1300 are used to generate a pairwise secret, a Key Derivation Function 1301 (KDF) is applied to derive a key, and then the CEK is either the 1302 derived key or encrypted by the derived key. 1304 key transport: The CEK is encrypted with the recipient's public key. 1306 passwords: The CEK is encrypted in a KEK that is derived from a 1307 password. As of when this document was published, no password 1308 algorithms have been defined. 1310 6.2. Single Recipient Encrypted 1312 The COSE_Encrypt0 encrypted structure does not have the ability to 1313 specify recipients of the message. The structure assumes that the 1314 recipient of the object will already know the identity of the key to 1315 be used in order to decrypt the message. If a key needs to be 1316 identified to the recipient, the enveloped structure ought to be 1317 used. 1319 Examples of encrypted messages can be found in Section c.3. 1321 The COSE_Encrypt0 structure can be encoded as either tagged or 1322 untagged depending on the context it will be used in. A tagged 1323 COSE_Encrypt0 structure is identified by the CBOR tag 16. The CDDL 1324 fragment that represents this is: 1326 COSE_Encrypt0_Tagged = #6.16(COSE_Encrypt0) 1328 The COSE_Encrypt0 structure is a CBOR array. The fields of the array 1329 in order are: 1331 protected: This is as described in Section 3. 1333 unprotected: This is as described in Section 3. 1335 ciphertext: This is as described in Section 6.1. 1337 The CDDL fragment for COSE_Encrypt0 that corresponds to the above 1338 text is: 1340 COSE_Encrypt0 = [ 1341 Headers, 1342 ciphertext : bstr / nil, 1343 ] 1345 6.3. How to Encrypt and Decrypt for AEAD Algorithms 1347 The encryption algorithm for AEAD algorithms is fairly simple. The 1348 first step is to create a consistent byte string for the 1349 authenticated data structure. For this purpose, we use an 1350 Enc_structure. The Enc_structure is a CBOR array. The fields of the 1351 Enc_structure in order are: 1353 1. A text string identifying the context of the authenticated data 1354 structure. The context string is: 1356 "Encrypt0" for the content encryption of a COSE_Encrypt0 data 1357 structure. 1359 "Encrypt" for the first layer of a COSE_Encrypt data structure 1360 (i.e., for content encryption). 1362 "Enc_Recipient" for a recipient encoding to be placed in an 1363 COSE_Encrypt data structure. 1365 "Mac_Recipient" for a recipient encoding to be placed in a 1366 MACed message structure. 1368 "Rec_Recipient" for a recipient encoding to be placed in a 1369 recipient structure. 1371 2. The protected attributes from the body structure encoded in a 1372 bstr type. If there are no protected attributes, a bstr of 1373 length zero is used. 1375 3. The protected attributes from the application encoded in a bstr 1376 type. If this field is not supplied, it defaults to a zero- 1377 length bstr. (See Section 4.3 for application guidance on 1378 constructing this field.) 1380 The CDDL fragment that describes the above text is: 1382 Enc_structure = [ 1383 context : "Encrypt" / "Encrypt0" / "Enc_Recipient" / 1384 "Mac_Recipient" / "Rec_Recipient", 1385 protected : empty_or_serialized_map, 1386 external_aad : bstr 1387 ] 1389 How to encrypt a message: 1391 1. Create an Enc_structure and populate it with the appropriate 1392 fields. 1394 2. Encode the Enc_structure to a byte string (Additional 1395 Authenticated Data (AAD)), using the encoding described in 1396 Section 10. 1398 3. Determine the encryption key (K). This step is dependent on the 1399 class of recipient algorithm being used. For: 1401 No Recipients: The key to be used is determined by the algorithm 1402 and key at the current layer. Examples are key transport keys 1403 (Section 9.5.3), key wrap keys (Section 9.5.2), or pre-shared 1404 secrets. 1406 Direct Encryption and Direct Key 1407 Agreement: The key is determined by the 1408 key and algorithm in the recipient structure. The encryption 1409 algorithm and size of the key to be used are inputs into the 1410 KDF used for the recipient. (For direct, the KDF can be 1411 thought of as the identity operation.) Examples of these 1412 algorithms are found in Sections 6.1.2 and 6.3 of 1413 [I-D.ietf-cose-rfc8152bis-algs]. 1415 Other: The key is randomly or pseudorandomly generated. 1417 4. Call the encryption algorithm with K (the encryption key), P (the 1418 plaintext), and AAD. Place the returned ciphertext into the 1419 'ciphertext' field of the structure. 1421 5. For recipients of the message, recursively perform the encryption 1422 algorithm for that recipient, using K (the encryption key) as the 1423 plaintext. 1425 How to decrypt a message: 1427 1. Create an Enc_structure and populate it with the appropriate 1428 fields. 1430 2. Encode the Enc_structure to a byte string (AAD), using the 1431 encoding described in Section 10. 1433 3. Determine the decryption key. This step is dependent on the 1434 class of recipient algorithm being used. For: 1436 No Recipients: The key to be used is determined by the algorithm 1437 and key at the current layer. Examples are key transport keys 1438 (Section 9.5.3), key wrap keys (Section 9.5.2), or pre-shared 1439 secrets. 1441 Direct Encryption and Direct Key 1442 Agreement: The key is determined by the 1443 key and algorithm in the recipient structure. The encryption 1444 algorithm and size of the key to be used are inputs into the 1445 KDF used for the recipient. (For direct, the KDF can be 1446 thought of as the identity operation.) 1448 Other: The key is determined by decoding and decrypting one of 1449 the recipient structures. 1451 4. Call the decryption algorithm with K (the decryption key to use), 1452 C (the ciphertext), and AAD. 1454 6.4. How to Encrypt and Decrypt for AE Algorithms 1456 How to encrypt a message: 1458 1. Verify that the 'protected' field is empty. 1460 2. Verify that there was no external additional authenticated data 1461 supplied for this operation. 1463 3. Determine the encryption key. This step is dependent on the 1464 class of recipient algorithm being used. For: 1466 No Recipients: The key to be used is determined by the algorithm 1467 and key at the current layer. Examples are key transport keys 1468 (Section 9.5.3), key wrap keys (Section 9.5.2), or pre-shared 1469 secrets. 1471 Direct Encryption and Direct Key 1472 Agreement: The key is determined by the 1473 key and algorithm in the recipient structure. The encryption 1474 algorithm and size of the key to be used are inputs into the 1475 KDF used for the recipient. (For direct, the KDF can be 1476 thought of as the identity operation.) Examples of these 1477 algorithms are found in Sections 6.1.2 and 6.3 of 1478 [I-D.ietf-cose-rfc8152bis-algs]. 1480 Other: The key is randomly generated. 1482 4. Call the encryption algorithm with K (the encryption key to use) 1483 and P (the plaintext). Place the returned ciphertext into the 1484 'ciphertext' field of the structure. 1486 5. For recipients of the message, recursively perform the encryption 1487 algorithm for that recipient, using K (the encryption key) as the 1488 plaintext. 1490 How to decrypt a message: 1492 1. Verify that the 'protected' field is empty. 1494 2. Verify that there was no external additional authenticated data 1495 supplied for this operation. 1497 3. Determine the decryption key. This step is dependent on the 1498 class of recipient algorithm being used. For: 1500 No Recipients: The key to be used is determined by the algorithm 1501 and key at the current layer. Examples are key transport keys 1502 (Section 9.5.3), key wrap keys (Section 9.5.2), or pre-shared 1503 secrets. 1505 Direct Encryption and Direct Key 1506 Agreement: The key is determined by the 1507 key and algorithm in the recipient structure. The encryption 1508 algorithm and size of the key to be used are inputs into the 1509 KDF used for the recipient. (For direct, the KDF can be 1510 thought of as the identity operation.) Examples of these 1511 algorithms are found in Sections 6.1.2 and 6.3 of 1512 [I-D.ietf-cose-rfc8152bis-algs]. 1514 Other: The key is determined by decoding and decrypting one of 1515 the recipient structures. 1517 4. Call the decryption algorithm with K (the decryption key to use) 1518 and C (the ciphertext). 1520 7. MAC Objects 1522 COSE supports two different MAC structures. COSE_MAC0 is used when a 1523 recipient structure is not needed because the key to be used is 1524 implicitly known. COSE_MAC is used for all other cases. These 1525 include a requirement for multiple recipients, the key being unknown, 1526 and a recipient algorithm of other than direct. 1528 In this section, we describe the structure and methods to be used 1529 when doing MAC authentication in COSE. This document allows for the 1530 use of all of the same classes of recipient algorithms as are allowed 1531 for encryption. 1533 When using MAC operations, there are two modes in which they can be 1534 used. The first is just a check that the content has not been 1535 changed since the MAC was computed. Any class of recipient algorithm 1536 can be used for this purpose. The second mode is to both check that 1537 the content has not been changed since the MAC was computed and to 1538 use the recipient algorithm to verify who sent it. The classes of 1539 recipient algorithms that support this are those that use a pre- 1540 shared secret or do static-static (SS) key agreement (without the key 1541 wrap step). In both of these cases, the entity that created and sent 1542 the message MAC can be validated. (This knowledge of the sender 1543 assumes that there are only two parties involved and that you did not 1544 send the message to yourself.) The origination property can be 1545 obtained with both of the MAC message structures. 1547 7.1. MACed Message with Recipients 1549 The multiple recipient MACed message uses two structures: the 1550 COSE_Mac structure defined in this section for carrying the body and 1551 the COSE_recipient structure (Section 6.1) to hold the key used for 1552 the MAC computation. Examples of MACed messages can be found in 1553 Section c.5. 1555 The MAC structure can be encoded as either tagged or untagged 1556 depending on the context it will be used in. A tagged COSE_Mac 1557 structure is identified by the CBOR tag 97. The CDDL fragment that 1558 represents this is: 1560 COSE_Mac_Tagged = #6.97(COSE_Mac) 1561 The COSE_Mac structure is a CBOR array. The fields of the array in 1562 order are: 1564 protected: This is as described in Section 3. 1566 unprotected: This is as described in Section 3. 1568 payload: This field contains the serialized content to be MACed. 1569 If the payload is not present in the message, the 1570 application is required to supply the payload 1571 separately. The payload is wrapped in a bstr to ensure 1572 that it is transported without changes. If the payload 1573 is transported separately (i.e., detached content), 1574 then a nil CBOR value is placed in this location, and 1575 it is the responsibility of the application to ensure 1576 that it will be transported without changes. 1578 tag: This field contains the MAC value. 1580 recipients: This is as described in Section 6.1. 1582 The CDDL fragment that represents the above text for COSE_Mac 1583 follows. 1585 COSE_Mac = [ 1586 Headers, 1587 payload : bstr / nil, 1588 tag : bstr, 1589 recipients :[+COSE_recipient] 1590 ] 1592 7.2. MACed Messages with Implicit Key 1594 In this section, we describe the structure and methods to be used 1595 when doing MAC authentication for those cases where the recipient is 1596 implicitly known. 1598 The MACed message uses the COSE_Mac0 structure defined in this 1599 section for carrying the body. Examples of MACed messages with an 1600 implicit key can be found in Section c.6. 1602 The MAC structure can be encoded as either tagged or untagged 1603 depending on the context it will be used in. A tagged COSE_Mac0 1604 structure is identified by the CBOR tag 17. The CDDL fragment that 1605 represents this is: 1607 COSE_Mac0_Tagged = #6.17(COSE_Mac0) 1608 The COSE_Mac0 structure is a CBOR array. The fields of the array in 1609 order are: 1611 protected: This is as described in Section 3. 1613 unprotected: This is as described in Section 3. 1615 payload: This is as described in Section 7.1. 1617 tag: This field contains the MAC value. 1619 The CDDL fragment that corresponds to the above text is: 1621 COSE_Mac0 = [ 1622 Headers, 1623 payload : bstr / nil, 1624 tag : bstr, 1625 ] 1627 7.3. How to Compute and Verify a MAC 1629 In order to get a consistent encoding of the data to be 1630 authenticated, the MAC_structure is used to have a canonical form. 1631 The MAC_structure is a CBOR array. The fields of the MAC_structure 1632 in order are: 1634 1. A text string that identifies the structure that is being 1635 encoded. This string is "MAC" for the COSE_Mac structure. This 1636 string is "MAC0" for the COSE_Mac0 structure. 1638 2. The protected attributes from the COSE_MAC structure. If there 1639 are no protected attributes, a zero-length bstr is used. 1641 3. The protected attributes from the application encoded as a bstr 1642 type. If this field is not supplied, it defaults to a zero- 1643 length binary string. (See Section 4.3 for application guidance 1644 on constructing this field.) 1646 4. The payload to be MACed encoded in a bstr type. The payload is 1647 placed here independent of how it is transported. 1649 The CDDL fragment that corresponds to the above text is: 1651 MAC_structure = [ 1652 context : "MAC" / "MAC0", 1653 protected : empty_or_serialized_map, 1654 external_aad : bstr, 1655 payload : bstr 1656 ] 1658 The steps to compute a MAC are: 1660 1. Create a MAC_structure and populate it with the appropriate 1661 fields. 1663 2. Create the value ToBeMaced by encoding the MAC_structure to a 1664 byte string, using the encoding described in Section 10. 1666 3. Call the MAC creation algorithm passing in K (the key to use), 1667 alg (the algorithm to MAC with), and ToBeMaced (the value to 1668 compute the MAC on). 1670 4. Place the resulting MAC in the 'tag' field of the COSE_Mac or 1671 COSE_Mac0 structure. 1673 5. For COSE_Mac structures, encrypt and encode the MAC key for each 1674 recipient of the message. 1676 The steps to verify a MAC are: 1678 1. Create a MAC_structure object and populate it with the 1679 appropriate fields. 1681 2. Create the value ToBeMaced by encoding the MAC_structure to a 1682 byte string, using the encoding described in Section 10. 1684 3. For COSE_Mac structures, obtain the cryptographic key from one of 1685 the recipients of the message. 1687 4. Call the MAC creation algorithm passing in K (the key to use), 1688 alg (the algorithm to MAC with), and ToBeMaced (the value to 1689 compute the MAC on). 1691 5. Compare the MAC value to the 'tag' field of the COSE_Mac or 1692 COSE_Mac0 structure. 1694 8. Key Objects 1696 A COSE Key structure is built on a CBOR map object. The set of 1697 common parameters that can appear in a COSE Key can be found in the 1698 IANA "COSE Key Common Parameters" registry (Section 12.4). 1699 Additional parameters defined for specific key types can be found in 1700 the IANA "COSE Key Type Parameters" registry ([COSE.KeyParameters]). 1702 A COSE Key Set uses a CBOR array object as its underlying type. The 1703 values of the array elements are COSE Keys. A COSE Key Set MUST have 1704 at least one element in the array. Examples of COSE Key Sets can be 1705 found in Section c.7. 1707 Each element in a COSE Key Set MUST be processed independently. If 1708 one element in a COSE Key Set is either malformed or uses a key that 1709 is not understood by an application, that key is ignored and the 1710 other keys are processed normally. 1712 The element "kty" is a required element in a COSE_Key map. 1714 The CDDL grammar describing COSE_Key and COSE_KeySet is: 1716 COSE_Key = { 1717 1 => tstr / int, ; kty 1718 ? 2 => bstr, ; kid 1719 ? 3 => tstr / int, ; alg 1720 ? 4 => [+ (tstr / int) ], ; key_ops 1721 ? 5 => bstr, ; Base IV 1722 * label => values 1723 } 1725 COSE_KeySet = [+COSE_Key] 1727 8.1. COSE Key Common Parameters 1729 This document defines a set of common parameters for a COSE Key 1730 object. Table 5 provides a summary of the parameters defined in this 1731 section. There are also parameters that are defined for specific key 1732 types. Key-type-specific parameters can be found in 1733 [I-D.ietf-cose-rfc8152bis-algs]. 1735 +---------+-------+-------------+------------+--------------------+ 1736 | Name | Label | CBOR Type | Value | Description | 1737 | | | | Registry | | 1738 +=========+=======+=============+============+====================+ 1739 | kty | 1 | tstr / int | COSE Key | Identification of | 1740 | | | | Types | the key type | 1741 +---------+-------+-------------+------------+--------------------+ 1742 | kid | 2 | bstr | | Key identification | 1743 | | | | | value -- match to | 1744 | | | | | kid in message | 1745 +---------+-------+-------------+------------+--------------------+ 1746 | alg | 3 | tstr / int | COSE | Key usage | 1747 | | | | Algorithms | restriction to | 1748 | | | | | this algorithm | 1749 +---------+-------+-------------+------------+--------------------+ 1750 | key_ops | 4 | [+ (tstr/ | | Restrict set of | 1751 | | | int)] | | permissible | 1752 | | | | | operations | 1753 +---------+-------+-------------+------------+--------------------+ 1754 | Base IV | 5 | bstr | | Base IV to be xor- | 1755 | | | | | ed with Partial | 1756 | | | | | IVs | 1757 +---------+-------+-------------+------------+--------------------+ 1759 Table 5: Key Map Labels 1761 kty: This parameter is used to identify the family of keys for 1762 this structure and, thus, the set of key-type-specific 1763 parameters to be found. The set of values defined in this 1764 document can be found in [COSE.KeyTypes]. This parameter 1765 MUST be present in a key object. Implementations MUST 1766 verify that the key type is appropriate for the algorithm 1767 being processed. The key type MUST be included as part of 1768 the trust decision process. 1770 alg: This parameter is used to restrict the algorithm that is 1771 used with the key. If this parameter is present in the key 1772 structure, the application MUST verify that this algorithm 1773 matches the algorithm for which the key is being used. If 1774 the algorithms do not match, then this key object MUST NOT 1775 be used to perform the cryptographic operation. Note that 1776 the same key can be in a different key structure with a 1777 different or no algorithm specified; however, this is 1778 considered to be a poor security practice. 1780 kid: This parameter is used to give an identifier for a key. 1781 The identifier is not structured and can be anything from a 1782 user-provided string to a value computed on the public 1783 portion of the key. This field is intended for matching 1784 against a 'kid' parameter in a message in order to filter 1785 down the set of keys that need to be checked. 1787 key_ops: This parameter is defined to restrict the set of operations 1788 that a key is to be used for. The value of the field is an 1789 array of values from Table 6. Algorithms define the values 1790 of key ops that are permitted to appear and are required 1791 for specific operations. The set of values matches that in 1792 [RFC7517] and [W3C.WebCrypto]. 1794 Base IV: This parameter is defined to carry the base portion of an 1795 IV. It is designed to be used with the Partial IV header 1796 parameter defined in Section 3.1. This field provides the 1797 ability to associate a Partial IV with a key that is then 1798 modified on a per message basis with the Partial IV. 1800 Extreme care needs to be taken when using a Base IV in an 1801 application. Many encryption algorithms lose security if 1802 the same IV is used twice. 1804 If different keys are derived for each sender, using the 1805 same Base IV with Partial IVs starting at zero is likely to 1806 ensure that the IV would not be used twice for a single 1807 key. If different keys are derived for each sender, 1808 starting at the same Base IV is likely to satisfy this 1809 condition. If the same key is used for multiple senders, 1810 then the application needs to provide for a method of 1811 dividing the IV space up between the senders. This could 1812 be done by providing a different base point to start from 1813 or a different Partial IV to start with and restricting the 1814 number of messages to be sent before rekeying. 1816 +---------+-------+----------------------------------------------+ 1817 | Name | Value | Description | 1818 +=========+=======+==============================================+ 1819 | sign | 1 | The key is used to create signatures. | 1820 | | | Requires private key fields. | 1821 +---------+-------+----------------------------------------------+ 1822 | verify | 2 | The key is used for verification of | 1823 | | | signatures. | 1824 +---------+-------+----------------------------------------------+ 1825 | encrypt | 3 | The key is used for key transport | 1826 | | | encryption. | 1827 +---------+-------+----------------------------------------------+ 1828 | decrypt | 4 | The key is used for key transport | 1829 | | | decryption. Requires private key fields. | 1830 +---------+-------+----------------------------------------------+ 1831 | wrap | 5 | The key is used for key wrap encryption. | 1832 | key | | | 1833 +---------+-------+----------------------------------------------+ 1834 | unwrap | 6 | The key is used for key wrap decryption. | 1835 | key | | Requires private key fields. | 1836 +---------+-------+----------------------------------------------+ 1837 | derive | 7 | The key is used for deriving keys. Requires | 1838 | key | | private key fields. | 1839 +---------+-------+----------------------------------------------+ 1840 | derive | 8 | The key is used for deriving bits not to be | 1841 | bits | | used as a key. Requires private key fields. | 1842 +---------+-------+----------------------------------------------+ 1843 | MAC | 9 | The key is used for creating MACs. | 1844 | create | | | 1845 +---------+-------+----------------------------------------------+ 1846 | MAC | 10 | The key is used for validating MACs. | 1847 | verify | | | 1848 +---------+-------+----------------------------------------------+ 1850 Table 6: Key Operation Values 1852 9. Taxonomy of Algorithms used by COSE 1854 In this section, a taxonomy of the different algorithm types that can 1855 be used in COSE is laid out. This taxonomy should not be considered 1856 to be exhaustive as there are new algorithm structures that could be 1857 found or are not known to the author. 1859 9.1. Signature Algorithms 1861 There are two signature algorithm schemes. The first is signature 1862 with appendix. In this scheme, the message content is processed and 1863 a signature is produced; the signature is called the appendix. This 1864 is the scheme used by algorithms such as ECDSA and the RSA 1865 Probabilistic Signature Scheme (RSASSA-PSS). (In fact, the SSA in 1866 RSASSA-PSS stands for Signature Scheme with Appendix.) 1868 The signature functions for this scheme are: 1870 signature = Sign(message content, key) 1872 valid = Verification(message content, key, signature) 1874 The second scheme is signature with message recovery (an example of 1875 such an algorithm is [PVSig]). In this scheme, the message content 1876 is processed, but part of it is included in the signature. Moving 1877 bytes of the message content into the signature allows for smaller 1878 signatures; the signature size is still potentially large, but the 1879 message content has shrunk. This has implications for systems 1880 implementing these algorithms and for applications that use them. 1881 The first is that the message content is not fully available until 1882 after a signature has been validated. Until that point, the part of 1883 the message contained inside of the signature is unrecoverable. The 1884 second is that the security analysis of the strength of the signature 1885 is very much based on the structure of the message content. Messages 1886 that are highly predictable require additional randomness to be 1887 supplied as part of the signature process. In the worst case, it 1888 becomes the same as doing a signature with appendix. Finally, in the 1889 event that multiple signatures are applied to a message, all of the 1890 signature algorithms are going to be required to consume the same 1891 number of bytes of message content. This means that the mixing of 1892 the different schemes in a single message is not supported, and if a 1893 recovery signature scheme is used, then the same amount of content 1894 needs to be consumed by all of the signatures. 1896 The signature functions for this scheme are: 1898 signature, message sent = Sign(message content, key) 1900 valid, message content = Verification(message sent, key, signature) 1902 Signature algorithms are used with the COSE_Signature and COSE_Sign1 1903 structures. At this time, only signatures with appendixes are 1904 defined for use with COSE; however, considerable interest has been 1905 expressed in using a signature with message recovery algorithm due to 1906 the effective size reduction that is possible. Implementations will 1907 need to keep this in mind for later possible integration. 1909 9.2. Message Authentication Code (MAC) Algorithms 1911 Message Authentication Codes (MACs) provide data authentication and 1912 integrity protection. They provide either no or very limited data 1913 origination. A MAC, for example, cannot be used to prove the 1914 identity of the sender to a third party. 1916 MACs use the same scheme as signature with appendix algorithms. The 1917 message content is processed and an authentication code is produced. 1918 The authentication code is frequently called a tag. 1920 The MAC functions are: 1922 tag = MAC_Create(message content, key) 1924 valid = MAC_Verify(message content, key, tag) 1926 MAC algorithms can be based on either a block cipher algorithm (i.e., 1927 AES-MAC) or a hash algorithm (i.e., a Hash-based Message 1928 Authentication Code (HMAC)). [I-D.ietf-cose-rfc8152bis-algs] defines 1929 a MAC algorithm using each of these constructions. 1931 MAC algorithms are used in the COSE_Mac and COSE_Mac0 structures. 1933 9.3. Content Encryption Algorithms 1935 Content encryption algorithms provide data confidentiality for 1936 potentially large blocks of data using a symmetric key. They provide 1937 integrity on the data that was encrypted; however, they provide 1938 either no or very limited data origination. (One cannot, for 1939 example, be used to prove the identity of the sender to a third 1940 party.) The ability to provide data origination is linked to how the 1941 CEK is obtained. 1943 COSE restricts the set of legal content encryption algorithms to 1944 those that support authentication both of the content and additional 1945 data. The encryption process will generate some type of 1946 authentication value, but that value may be either explicit or 1947 implicit in terms of the algorithm definition. For simplicity's 1948 sake, the authentication code will normally be defined as being 1949 appended to the ciphertext stream. The encryption functions are: 1951 ciphertext = Encrypt(message content, key, additional data) 1953 valid, message content = Decrypt(ciphertext, key, additional data) 1954 Most AEAD algorithms are logically defined as returning the message 1955 content only if the decryption is valid. Many but not all 1956 implementations will follow this convention. The message content 1957 MUST NOT be used if the decryption does not validate. 1959 These algorithms are used in COSE_Encrypt and COSE_Encrypt0. 1961 9.4. Key Derivation Functions (KDFs) 1963 KDFs are used to take some secret value and generate a different one. 1964 The secret value comes in three flavors: 1966 * Secrets that are uniformly random: This is the type of secret that 1967 is created by a good random number generator. 1969 * Secrets that are not uniformly random: This is type of secret that 1970 is created by operations like key agreement. 1972 * Secrets that are not random: This is the type of secret that 1973 people generate for things like passwords. 1975 General KDFs work well with the first type of secret, can do 1976 reasonably well with the second type of secret, and generally do 1977 poorly with the last type of secret. Functions like PBES2 [RFC8018] 1978 need to be used for non-random secrets. 1980 The same KDF can be set up to deal with the first two types of 1981 secrets in a different way. The KDF defined in section 5.1 of 1982 [I-D.ietf-cose-rfc8152bis-algs] is such a function. This is 1983 reflected in the set of algorithms defined around the HMAC-based 1984 Extract-and-Expand Key Derivation Function (HKDF). 1986 When using KDFs, one component that is included is context 1987 information. Context information is used to allow for different 1988 keying information to be derived from the same secret. The use of 1989 context-based keying material is considered to be a good security 1990 practice. 1992 9.5. Content Key Distribution Methods 1994 Content key distribution methods (recipient algorithms) can be 1995 defined into a number of different classes. COSE has the ability to 1996 support many classes of recipient algorithms. In this section, a 1997 number of classes are listed. The names of the recipient algorithm 1998 classes used here are the same as those defined in [RFC7516]. Other 1999 specifications use different terms for the recipient algorithm 2000 classes or do not support some of the recipient algorithm classes. 2002 9.5.1. Direct Encryption 2004 The direct encryption class algorithms share a secret between the 2005 sender and the recipient that is used either directly or after 2006 manipulation as the CEK. When direct encryption mode is used, it 2007 MUST be the only mode used on the message. 2009 The COSE_Recipient structure for the recipient is organized as 2010 follows: 2012 * The 'protected' field MUST be a zero-length item unless it is used 2013 in the computation of the content key. 2015 * The 'alg' parameter MUST be present. 2017 * A parameter identifying the shared secret SHOULD be present. 2019 * The 'ciphertext' field MUST be a zero-length item. 2021 * The 'recipients' field MUST be absent. 2023 9.5.2. Key Wrap 2025 In key wrap mode, the CEK is randomly generated and that key is then 2026 encrypted by a shared secret between the sender and the recipient. 2027 All of the currently defined key wrap algorithms for COSE are AE 2028 algorithms. Key wrap mode is considered to be superior to direct 2029 encryption if the system has any capability for doing random key 2030 generation. This is because the shared key is used to wrap random 2031 data rather than data that has some degree of organization and may in 2032 fact be repeating the same content. The use of key wrap loses the 2033 weak data origination that is provided by the direct encryption 2034 algorithms. 2036 The COSE_Encrypt structure for the recipient is organized as follows: 2038 * The 'protected' field MUST be absent if the key wrap algorithm is 2039 an AE algorithm. 2041 * The 'recipients' field is normally absent, but can be used. 2042 Applications MUST deal with a recipient field being present that 2043 has an unsupported algorthms, not being able to decrypt that 2044 recipient is an acceptable way of dealing with it. Failing to 2045 process the message is not an acceptable way of dealing with it. 2047 * The plaintext to be encrypted is the key from next layer down 2048 (usually the content layer). 2050 * At a minimum, the 'unprotected' field MUST contain the 'alg' 2051 parameter and SHOULD contain a parameter identifying the shared 2052 secret. 2054 9.5.3. Key Transport 2056 Key transport mode is also called key encryption mode in some 2057 standards. Key transport mode differs from key wrap mode in that it 2058 uses an asymmetric encryption algorithm rather than a symmetric 2059 encryption algorithm to protect the key. A set of key transport 2060 algorithms are defined in [RFC8230]. 2062 When using a key transport algorithm, the COSE_Encrypt structure for 2063 the recipient is organized as follows: 2065 * The 'protected' field MUST be absent. 2067 * The plaintext to be encrypted is the key from the next layer down 2068 (usually the content layer). 2070 * At a minimum, the 'unprotected' field MUST contain the 'alg' 2071 parameter and SHOULD contain a parameter identifying the 2072 asymmetric key. 2074 9.5.4. Direct Key Agreement 2076 The 'direct key agreement' class of recipient algorithms uses a key 2077 agreement method to create a shared secret. A KDF is then applied to 2078 the shared secret to derive a key to be used in protecting the data. 2079 This key is normally used as a CEK or MAC key, but could be used for 2080 other purposes if more than two layers are in use (see Appendix B). 2082 The most commonly used key agreement algorithm is Diffie-Hellman, but 2083 other variants exist. Since COSE is designed for a store and forward 2084 environment rather than an online environment, many of the DH 2085 variants cannot be used as the receiver of the message cannot provide 2086 any dynamic key material. One side effect of this is that perfect 2087 forward secrecy (see [RFC4949]) is not achievable. A static key will 2088 always be used for the receiver of the COSE object. 2090 Two variants of DH that are supported are: 2092 Ephemeral-Static (ES) DH: where the sender of the message creates 2093 a one-time DH key and uses a static key for the recipient. The 2094 use of the ephemeral sender key means that no additional random 2095 input is needed as this is randomly generated for each message. 2097 Static-Static (SS) DH: where a static key is used for both the 2098 sender and the recipient. The use of static keys allows for the 2099 recipient to get a weak version of data origination for the 2100 message. When static-static key agreement is used, then some 2101 piece of unique data for the KDF is required to ensure that a 2102 different key is created for each message. 2104 When direct key agreement mode is used, there MUST be only one 2105 recipient in the message. This method creates the key directly, and 2106 that makes it difficult to mix with additional recipients. If 2107 multiple recipients are needed, then the version with key wrap needs 2108 to be used. 2110 The COSE_Encrypt structure for the recipient is organized as follows: 2112 * At a minimum, headers MUST contain the 'alg' parameter and SHOULD 2113 contain a parameter identifying the recipient's asymmetric key. 2115 * The headers SHOULD identify the sender's key for the static-static 2116 versions and MUST contain the sender's ephemeral key for the 2117 ephemeral-static versions. 2119 9.5.5. Key Agreement with Key Wrap 2121 Key Agreement with Key Wrap uses a randomly generated CEK. The CEK 2122 is then encrypted using a key wrap algorithm and a key derived from 2123 the shared secret computed by the key agreement algorithm. The 2124 function for this would be: 2126 encryptedKey = KeyWrap(KDF(DH-Shared, context), CEK) 2128 The COSE_Encrypt structure for the recipient is organized as follows: 2130 * The 'protected' field is fed into the KDF context structure. 2132 * The plaintext to be encrypted is the key from the next layer down 2133 (usually the content layer). 2135 * The 'alg' parameter MUST be present in the layer. 2137 * A parameter identifying the recipient's key SHOULD be present. A 2138 parameter identifying the sender's key SHOULD be present. 2140 10. CBOR Encoding Restrictions 2142 There has been an attempt to limit the number of places where the 2143 document needs to impose restrictions on how the CBOR Encoder needs 2144 to work. We have managed to narrow it down to the following 2145 restrictions: 2147 * The restriction applies to the encoding of the Sig_structure, the 2148 Enc_structure, and the MAC_structure. 2150 * Encoding MUST be done using definite lengths and values MUST be 2151 the minimum possible length. This means that the integer 1 is 2152 encoded as "0x01" and not "0x1801". 2154 * Applications MUST NOT generate messages with the same label used 2155 twice as a key in a single map. Applications MUST NOT parse and 2156 process messages with the same label used twice as a key in a 2157 single map. Applications can enforce the parse and process 2158 requirement by using parsers that will fail the parse step or by 2159 using parsers that will pass all keys to the application, and the 2160 application can perform the check for duplicate keys. 2162 11. Application Profiling Considerations 2164 This document is designed to provide a set of security services, but 2165 not impose algorithm implementation requirements for specific usage. 2166 The interoperability requirements are provided for how each of the 2167 individual services are used and how the algorithms are to be used 2168 for interoperability. The requirements about which algorithms and 2169 which services are needed are deferred to each application. 2171 An example of a profile can be found in [RFC8613] where one was 2172 developed for carrying content in combination with CoAP headers. 2174 It is intended that a profile of this document be created that 2175 defines the interoperability requirements for that specific 2176 application. This section provides a set of guidelines and topics 2177 that need to be considered when profiling this document. 2179 * Applications need to determine the set of messages defined in this 2180 document that they will be using. The set of messages corresponds 2181 fairly directly to the set of security services that are needed 2182 and to the security levels needed. 2184 * Applications may define new header parameters for a specific 2185 purpose. Applications will often times select specific header 2186 parameters to use or not to use. For example, an application 2187 would normally state a preference for using either the IV or the 2188 Partial IV parameter. If the Partial IV parameter is specified, 2189 then the application also needs to define how the fixed portion of 2190 the IV is determined. 2192 * When applications use externally defined authenticated data, they 2193 need to define how that data is encoded. This document assumes 2194 that the data will be provided as a byte string. More information 2195 can be found in Section 4.3. 2197 * Applications need to determine the set of security algorithms that 2198 are to be used. When selecting the algorithms to be used as the 2199 mandatory-to-implement set, consideration should be given to 2200 choosing different types of algorithms when two are chosen for a 2201 specific purpose. An example of this would be choosing HMAC- 2202 SHA512 and AES-CMAC as different MAC algorithms; the construction 2203 is vastly different between these two algorithms. This means that 2204 a weakening of one algorithm would be unlikely to lead to a 2205 weakening of the other algorithms. Of course, these algorithms do 2206 not provide the same level of security and thus may not be 2207 comparable for the desired security functionality. 2209 * Applications may need to provide some type of negotiation or 2210 discovery method if multiple algorithms or message structures are 2211 permitted. The method can be as simple as requiring 2212 preconfiguration of the set of algorithms to providing a discovery 2213 method built into the protocol. S/MIME provided a number of 2214 different ways to approach the problem that applications could 2215 follow: 2217 - Advertising in the message (S/MIME capabilities) [RFC5751]. 2219 - Advertising in the certificate (capabilities extension) 2220 [RFC4262]. 2222 - Minimum requirements for the S/MIME, which have been updated 2223 over time [RFC2633] [RFC5751] (note that [RFC2633] has been 2224 obsoleted by [RFC5751]). 2226 12. IANA Considerations 2228 The registeries and registrations listed below were created during 2229 processing of RFC 8152 [RFC8152]. The only known action at this time 2230 is to update the references. 2232 12.1. CBOR Tag Assignment 2234 IANA assigned tags in the "CBOR Tags" registry as part of processing 2235 [RFC8152]. IANA is requested to update the references from [RFC8152] 2236 to this document. 2238 IANA is requested to register a new tag for the CounterSignature 2239 type. 2241 * Tag: TBD0 2243 * Data Item: COSE_Signature 2245 * Semantics: COSE standalone counter signature 2247 * Reference: [[this document]] 2249 12.2. COSE Header Parameters Registry 2251 IANA created a registry titled "COSE Header Parameters" as part of 2252 processing [RFC8152]. The registry has been created to use the 2253 "Expert Review Required" registration procedure [RFC8126]. 2255 IANA is requested to update the reference for entries in the table 2256 from [RFC8152] to this document. This document does not update the 2257 expert review guidelines provided in [RFC8152]. 2259 12.3. COSE Header Algorithm Parameters Registry 2261 IANA created a registry titled "COSE Header Algorithm Parameters" as 2262 part of processing [RFC8152]. The registry has been created to use 2263 the "Expert Review Required" registration procedure [RFC8126]. 2265 IANA is requested to update the references from [RFC8152] to this 2266 document. This document does not update the expert review guidelines 2267 provided in [RFC8152]. 2269 12.4. COSE Key Common Parameters Registry 2271 IANA created a registry titled "COSE Key Common Parameters" as part 2272 of the processing of [RFC8152]. The registry has been created to use 2273 the "Expert Review Required" registration procedure [RFC8126]. 2275 IANA is requested to update the reference for entries in the table 2276 from [RFC8152] to this document. This document does not update the 2277 expert review guidelines provided in [RFC8152]. 2279 12.5. Media Type Registrations 2281 12.5.1. COSE Security Message 2283 This section registers the 'application/cose' media type in the 2284 "Media Types" registry. These media types are used to indicate that 2285 the content is a COSE message. 2287 Type name: application 2289 Subtype name: cose 2291 Required parameters: N/A 2293 Optional parameters: cose-type 2295 Encoding considerations: binary 2297 Security considerations: See the Security Considerations section 2298 of [[This Document]]. 2300 Interoperability considerations: N/A 2302 Published specification: [[this document]] 2304 Applications that use this media type: IoT applications sending 2305 security content over HTTP(S) transports. 2307 Fragment identifier considerations: N/A 2309 Additional information: 2311 - Deprecated alias names for this type: N/A 2313 - Magic number(s): N/A 2315 - File extension(s): cbor 2317 - Macintosh file type code(s): N/A 2319 Person & email address to contact for further information: 2320 iesg@ietf.org 2322 Intended usage: COMMON 2324 Restrictions on usage: N/A 2326 Author: Jim Schaad, ietf@augustcellars.com 2327 Change Controller: IESG 2329 Provisional registration? No 2331 12.5.2. COSE Key Media Type 2333 This section registers the 'application/cose-key' and 'application/ 2334 cose-key-set' media types in the "Media Types" registry. These media 2335 types are used to indicate, respectively, that content is a COSE_Key 2336 or COSE_KeySet object. 2338 The template for registering 'application/cose-key' is: 2340 Type name: application 2342 Subtype name: cose-key 2344 Required parameters: N/A 2346 Optional parameters: N/A 2348 Encoding considerations: binary 2350 Security considerations: See the Security Considerations section 2351 of [[This Document]]. 2353 Interoperability considerations: N/A 2355 Published specification: [[this document]] 2357 Applications that use this media type: Distribution of COSE based 2358 keys for IoT applications. 2360 Fragment identifier considerations: N/A 2362 Additional information: 2364 - Deprecated alias names for this type: N/A 2366 - Magic number(s): N/A 2368 - File extension(s): cbor 2370 - Macintosh file type code(s): N/A 2372 Person & email address to contact for further information: 2373 iesg@ietf.org 2374 Intended usage: COMMON 2376 Restrictions on usage: N/A 2378 Author: Jim Schaad, ietf@augustcellars.com 2380 Change Controller: IESG 2382 Provisional registration? No 2384 The template for registering 'application/cose-key-set' is: 2386 Type name: application 2388 Subtype name: cose-key-set 2390 Required parameters: N/A 2392 Optional parameters: N/A 2394 Encoding considerations: binary 2396 Security considerations: See the Security Considerations section 2397 of [[This Document]]. 2399 Interoperability considerations: N/A 2401 Published specification: [[this document]] 2403 Applications that use this media type: Distribution of COSE based 2404 keys for IoT applications. 2406 Fragment identifier considerations: N/A 2408 Additional information: 2410 - Deprecated alias names for this type: N/A 2412 - Magic number(s): N/A 2414 - File extension(s): cbor 2416 - Macintosh file type code(s): N/A 2418 Person & email address to contact for further information: 2419 iesg@ietf.org 2421 Intended usage: COMMON 2422 Restrictions on usage: N/A 2424 Author: Jim Schaad, ietf@augustcellars.com 2426 Change Controller: IESG 2428 Provisional registration? No 2430 12.6. CoAP Content-Formats Registry 2432 IANA added the following entries to the "CoAP Content-Formats" 2433 registry while processing [RFC8152]. IANA is requested to update the 2434 reference value from [RFC8152] to [[This Document]]. 2436 13. Security Considerations 2438 There are a number of security considerations that need to be taken 2439 into account by implementers of this specification. The security 2440 considerations that are specific to an individual algorithm are 2441 placed next to the description of the algorithm. While some 2442 considerations have been highlighted here, additional considerations 2443 may be found in the documents listed in the references. 2445 Implementations need to protect the private key material for any 2446 individuals. There are some cases that need to be highlighted on 2447 this issue. 2449 * Using the same key for two different algorithms can leak 2450 information about the key. It is therefore recommended that keys 2451 be restricted to a single algorithm. 2453 * Use of 'direct' as a recipient algorithm combined with a second 2454 recipient algorithm exposes the direct key to the second 2455 recipient. 2457 * Several of the algorithms in [I-D.ietf-cose-rfc8152bis-algs] have 2458 limits on the number of times that a key can be used without 2459 leaking information about the key. 2461 The use of ECDH and direct plus KDF (with no key wrap) will not 2462 directly lead to the private key being leaked; the one way function 2463 of the KDF will prevent that. There is, however, a different issue 2464 that needs to be addressed. Having two recipients requires that the 2465 CEK be shared between two recipients. The second recipient therefore 2466 has a CEK that was derived from material that can be used for the 2467 weak proof of origin. The second recipient could create a message 2468 using the same CEK and send it to the first recipient; the first 2469 recipient would, for either static-static ECDH or direct plus KDF, 2470 make an assumption that the CEK could be used for proof of origin 2471 even though it is from the wrong entity. If the key wrap step is 2472 added, then no proof of origin is implied and this is not an issue. 2474 Although it has been mentioned before, the use of a single key for 2475 multiple algorithms has been demonstrated in some cases to leak 2476 information about a key, provide the opportunity for attackers to 2477 forge integrity tags, or gain information about encrypted content. 2478 Binding a key to a single algorithm prevents these problems. Key 2479 creators and key consumers are strongly encouraged not only to create 2480 new keys for each different algorithm, but to include that selection 2481 of algorithm in any distribution of key material and strictly enforce 2482 the matching of algorithms in the key structure to algorithms in the 2483 message structure. In addition to checking that algorithms are 2484 correct, the key form needs to be checked as well. Do not use an 2485 'EC2' key where an 'OKP' key is expected. 2487 Before using a key for transmission, or before acting on information 2488 received, a trust decision on a key needs to be made. Is the data or 2489 action something that the entity associated with the key has a right 2490 to see or a right to request? A number of factors are associated 2491 with this trust decision. Some of the ones that are highlighted here 2492 are: 2494 * What are the permissions associated with the key owner? 2496 * Is the cryptographic algorithm acceptable in the current context? 2498 * Have the restrictions associated with the key, such as algorithm 2499 or freshness, been checked and are they correct? 2501 * Is the request something that is reasonable, given the current 2502 state of the application? 2504 * Have any security considerations that are part of the message been 2505 enforced (as specified by the application or 'crit' parameter)? 2507 There are a large number of algorithms presented in 2508 [I-D.ietf-cose-rfc8152bis-algs] that use nonce values. Nonces 2509 generally have some type of restriction on their values. Generally a 2510 nonce needs to be a unique value either for a key or for some other 2511 conditions. In all of these cases, there is no known requirement on 2512 the nonce being both unique and unpredictable; under these 2513 circumstances, it's reasonable to use a counter for creation of the 2514 nonce. In cases where one wants the pattern of the nonce to be 2515 unpredictable as well as unique, one can use a key created for that 2516 purpose and encrypt the counter to produce the nonce value. 2518 One area that has been starting to get exposure is doing traffic 2519 analysis of encrypted messages based on the length of the message. 2520 This specification does not provide for a uniform method of providing 2521 padding as part of the message structure. An observer can 2522 distinguish between two different strings (for example, 'YES' and 2523 'NO') based on the length for all of the content encryption 2524 algorithms that are defined in [I-D.ietf-cose-rfc8152bis-algs] 2525 document. This means that it is up to the applications to document 2526 how content padding is to be done in order to prevent or discourage 2527 such analysis. (For example, the strings could be defined as 'YES' 2528 and 'NO '.) 2530 14. Implementation Status 2532 This section is to be removed before publishing as an RFC. 2534 This section records the status of known implementations of the 2535 protocol defined by this specification at the time of posting of this 2536 Internet-Draft, and is based on a proposal described in [RFC7942]. 2537 The description of implementations in this section is intended to 2538 assist the IETF in its decision processes in progressing drafts to 2539 RFCs. Please note that the listing of any individual implementation 2540 here does not imply endorsement by the IETF. Furthermore, no effort 2541 has been spent to verify the information presented here that was 2542 supplied by IETF contributors. This is not intended as, and must not 2543 be construed to be, a catalog of available implementations or their 2544 features. Readers are advised to note that other implementations may 2545 exist. 2547 According to [RFC7942], "this will allow reviewers and working groups 2548 to assign due consideration to documents that have the benefit of 2549 running code, which may serve as evidence of valuable experimentation 2550 and feedback that have made the implemented protocols more mature. 2551 It is up to the individual working groups to use this information as 2552 they see fit". 2554 14.1. Author's Versions 2556 There are three different implementations that have been created by 2557 the author of the document both to create the examples that are 2558 included in the document and to validate the structures and 2559 methodology used in the design of COSE. 2561 * Implementation Location: https://github.com/cose-wg 2563 * Primary Maintainer: Jim Schaad 2564 * Languages: There are three different languages that are currently 2565 supported: Java, C# and C. 2567 * Cryptography: The Java and C# libraries use Bouncy Castle to 2568 provide the required cryptography. The C version uses OPENSSL 2569 Version 1.0 for the cryptography. 2571 * Coverage: The C version currently does not have full countersign 2572 support. The other two versions do. They do have support to 2573 allow for implicit algorithm support as they allow for the 2574 application to set attributes that are not to be sent in the 2575 message. 2577 * Testing: All of the examples in the example library are generated 2578 by the C# library and then validated using the Java and C 2579 libraries. All three libraries have tests to allow for the 2580 creating of the same messages that are in the example library 2581 followed by validating them. These are not compared against the 2582 example library. The Java and C# libraries have unit testing 2583 included. Not all of the MUST statements in the document have 2584 been implemented as part of the libraries. One such statement is 2585 the requirement that unique labels be present. 2587 * Licensing: Revised BSD License 2589 14.2. JavaScript Version 2591 * Implementation Location: https://github.com/erdtman/cose-js 2593 * Primary Maintainer: Samuel Erdtman 2595 * Languages: JavaScript 2597 * Cryptography: TBD 2599 * Coverage: Full Encrypt, Signature and MAC objects are supported. 2601 * Testing: Basic testing against the common example library. 2603 * Licensing: Apache License 2.0 2605 14.3. Python Version 2607 * Implementation Location: https://github.com/TimothyClaeys/COSE- 2608 PYTHON 2610 * Primary Maintainer: Timothy Claeys 2611 * Languages: Python 2613 * Cryptography: pyecdsak, crypto python libraries 2615 * Coverage: TBD 2617 * Testing: Basic testing plus running against the common example 2618 library. 2620 * Licensing: BSD 3-Clause License 2622 14.4. COSE Testing Library 2624 * Implementation Location: https://github.com/cose-wg/Examples 2626 * Primary Maintainer: Jim Schaad 2628 * Description: A set of tests for the COSE library is provided as 2629 part of the implementation effort. Both success and fail tests 2630 have been provided. All of the examples in this document are part 2631 of this example set. 2633 * Coverage: An attempt has been made to have test cases for every 2634 message type and algorithm in the document. Currently examples 2635 dealing with counter signatures, and ECDH with Curve24459 and 2636 Goldilocks are missing. 2638 * Licensing: Public Domain 2640 15. References 2642 15.1. Normative References 2644 [COAP.Formats] 2645 IANA, "CoAP Content-Formats", August 2019, 2646 . 2649 [COSE.Algorithms] 2650 IANA, "COSE Algorithms", August 2019, 2651 . 2654 [COSE.KeyParameters] 2655 IANA, "COSE Key Parameters", August 2019, 2656 . 2659 [COSE.KeyTypes] 2660 IANA, "COSE Key Types", August 2019, 2661 . 2664 [DSS] National Institute of Standards and Technology, "Digital 2665 Signature Standard (DSS)", DOI 10.6028/NIST.FIPS.186-4, 2666 FIPS PUB 186-4, July 2013, 2667 . 2670 [I-D.ietf-cose-rfc8152bis-algs] 2671 Schaad, J., "CBOR Object Signing and Encryption (COSE): 2672 Initial Algorithms", draft-ietf-cose-rfc8152bis-algs-03 2673 (work in progress), June 10, 2019, 2674 . 2677 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2678 Requirement Levels", BCP 14, RFC 2119, 2679 DOI 10.17487/RFC2119, March 1997, 2680 . 2682 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2683 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2684 October 2013, . 2686 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital 2687 Signature Algorithm (EdDSA)", RFC 8032, 2688 DOI 10.17487/RFC8032, January 2017, 2689 . 2691 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2692 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2693 May 2017, . 2695 15.2. Informative References 2697 [PVSig] Brown, D. and D. Johnson, "Formal Security Proofs for a 2698 Signature Scheme with Partial Message Recovery", 2699 DOI 10.1007/3-540-45353-9_11, LNCS Volume 2020, June 2000, 2700 . 2702 [RFC2633] Ramsdell, B., Ed., "S/MIME Version 3 Message 2703 Specification", RFC 2633, DOI 10.17487/RFC2633, June 1999, 2704 . 2706 [RFC4262] Santesson, S., "X.509 Certificate Extension for Secure/ 2707 Multipurpose Internet Mail Extensions (S/MIME) 2708 Capabilities", RFC 4262, DOI 10.17487/RFC4262, December 2709 2005, . 2711 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2712 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 2713 . 2715 [RFC4998] Gondrom, T., Brandner, R., and U. Pordesch, "Evidence 2716 Record Syntax (ERS)", RFC 4998, DOI 10.17487/RFC4998, 2717 August 2007, . 2719 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 2720 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 2721 . 2723 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 2724 RFC 5652, DOI 10.17487/RFC5652, September 2009, 2725 . 2727 [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet 2728 Mail Extensions (S/MIME) Version 3.2 Message 2729 Specification", RFC 5751, DOI 10.17487/RFC5751, January 2730 2010, . 2732 [RFC5752] Turner, S. and J. Schaad, "Multiple Signatures in 2733 Cryptographic Message Syntax (CMS)", RFC 5752, 2734 DOI 10.17487/RFC5752, January 2010, 2735 . 2737 [RFC5990] Randall, J., Kaliski, B., Brainard, J., and S. Turner, 2738 "Use of the RSA-KEM Key Transport Algorithm in the 2739 Cryptographic Message Syntax (CMS)", RFC 5990, 2740 DOI 10.17487/RFC5990, September 2010, 2741 . 2743 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 2744 Specifications and Registration Procedures", BCP 13, 2745 RFC 6838, DOI 10.17487/RFC6838, January 2013, 2746 . 2748 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2749 Application Protocol (CoAP)", RFC 7252, 2750 DOI 10.17487/RFC7252, June 2014, 2751 . 2753 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2754 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2755 2015, . 2757 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 2758 RFC 7516, DOI 10.17487/RFC7516, May 2015, 2759 . 2761 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 2762 DOI 10.17487/RFC7517, May 2015, 2763 . 2765 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 2766 DOI 10.17487/RFC7518, May 2015, 2767 . 2769 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 2770 Code: The Implementation Status Section", BCP 205, 2771 RFC 7942, DOI 10.17487/RFC7942, July 2016, 2772 . 2774 [RFC8018] Moriarty, K., Ed., Kaliski, B., and A. Rusch, "PKCS #5: 2775 Password-Based Cryptography Specification Version 2.1", 2776 RFC 8018, DOI 10.17487/RFC8018, January 2017, 2777 . 2779 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2780 Writing an IANA Considerations Section in RFCs", BCP 26, 2781 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2782 . 2784 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2785 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2786 . 2788 [RFC8230] Jones, M., "Using RSA Algorithms with CBOR Object Signing 2789 and Encryption (COSE) Messages", RFC 8230, 2790 DOI 10.17487/RFC8230, September 2017, 2791 . 2793 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2794 Interchange Format", STD 90, RFC 8259, 2795 DOI 10.17487/RFC8259, December 2017, 2796 . 2798 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 2799 Definition Language (CDDL): A Notational Convention to 2800 Express Concise Binary Object Representation (CBOR) and 2801 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 2802 June 2019, . 2804 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 2805 "Object Security for Constrained RESTful Environments 2806 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 2807 . 2809 [W3C.WebCrypto] 2810 Watson, M., "Web Cryptography API", W3C Recommendation, 2811 January 2017, . 2813 Appendix A. Guidelines for External Data Authentication of Algorithms 2815 During development of COSE, the requirement that the algorithm 2816 identifier be located in the protected attributes was relaxed from a 2817 must to a should. There were two basic reasons that have been 2818 advanced to support this position. First, the resulting message will 2819 be smaller if the algorithm identifier is omitted from the most 2820 common messages in a CoAP environment. Second, there is a potential 2821 bug that will arise if full checking is not done correctly between 2822 the different places that an algorithm identifier could be placed 2823 (the message itself, an application statement, the key structure that 2824 the sender possesses, and the key structure the recipient possesses). 2826 This appendix lays out how such a change can be made and the details 2827 that an application needs to specify in order to use this option. 2828 Two different sets of details are specified: those needed to omit an 2829 algorithm identifier and those needed to use a variant on the counter 2830 signature attribute that contains no attributes about itself. 2832 Three sets of recommendations are laid out. The first set of 2833 recommendations apply to having an implicit algorithm identified for 2834 a single layer of a COSE object. The second set of recommendations 2835 apply to having multiple implicit algorithms identified for multiple 2836 layers of a COSE object. The third set of recommendations apply to 2837 having implicit algorithms for multiple COSE object constructs. 2839 The key words from [RFC2119] are deliberately not used here. This 2840 specification can provide recommendations, but it cannot enforce 2841 them. 2843 This set of recommendations applies to the case where an application 2844 is distributing a fixed algorithm along with the key information for 2845 use in a single COSE object. This normally applies to the smallest 2846 of the COSE objects, specifically COSE_Sign1, COSE_Mac0, and 2847 COSE_Encrypt0, but could apply to the other structures as well. 2849 The following items should be taken into account: 2851 * Applications need to list the set of COSE structures that implicit 2852 algorithms are to be used in. Applications need to require that 2853 the receipt of an explicit algorithm identifier in one of these 2854 structures will lead to the message being rejected. This 2855 requirement is stated so that there will never be a case where 2856 there is any ambiguity about the question of which algorithm 2857 should be used, the implicit or the explicit one. This applies 2858 even if the transported algorithm identifier is a protected 2859 attribute. This applies even if the transported algorithm is the 2860 same as the implicit algorithm. 2862 * Applications need to define the set of information that is to be 2863 considered to be part of a context when omitting algorithm 2864 identifiers. At a minimum, this would be the key identifier (if 2865 needed), the key, the algorithm, and the COSE structure it is used 2866 with. Applications should restrict the use of a single key to a 2867 single algorithm. As noted for some of the algorithms in 2868 [I-D.ietf-cose-rfc8152bis-algs], the use of the same key in 2869 different related algorithms can lead to leakage of information 2870 about the key, leakage about the data or the ability to perform 2871 forgeries. 2873 * In many cases, applications that make the algorithm identifier 2874 implicit will also want to make the context identifier implicit 2875 for the same reason. That is, omitting the context identifier 2876 will decrease the message size (potentially significantly 2877 depending on the length of the identifier). Applications that do 2878 this will need to describe the circumstances where the context 2879 identifier is to be omitted and how the context identifier is to 2880 be inferred in these cases. (An exhaustive search over all of the 2881 keys would normally not be considered to be acceptable.) An 2882 example of how this can be done is to tie the context to a 2883 transaction identifier. Both would be sent on the original 2884 message, but only the transaction identifier would need to be sent 2885 after that point as the context is tied into the transaction 2886 identifier. Another way would be to associate a context with a 2887 network address. All messages coming from a single network 2888 address can be assumed to be associated with a specific context. 2889 (In this case, the address would normally be distributed as part 2890 of the context.) 2892 * Applications cannot rely on key identifiers being unique unless 2893 they take significant efforts to ensure that they are computed in 2894 such a way as to create this guarantee. Even when an application 2895 does this, the uniqueness might be violated if the application is 2896 run in different contexts (i.e., with a different context 2897 provider) or if the system combines the security contexts from 2898 different applications together into a single store. 2900 * Applications should continue the practice of protecting the 2901 algorithm identifier. Since this is not done by placing it in the 2902 protected attributes field, applications should define an 2903 application-specific external data structure that includes this 2904 value. This external data field can be used as such for content 2905 encryption, MAC, and signature algorithms. It can be used in the 2906 SuppPrivInfo field for those algorithms that use a KDF to derive a 2907 key value. Applications may also want to protect other 2908 information that is part of the context structure as well. It 2909 should be noted that those fields, such as the key or a Base IV, 2910 are protected by virtue of being used in the cryptographic 2911 computation and do not need to be included in the external data 2912 field. 2914 The second case is having multiple implicit algorithm identifiers 2915 specified for a multiple layer COSE object. An example of how this 2916 would work is the encryption context that an application specifies, 2917 which contains a content encryption algorithm, a key wrap algorithm, 2918 a key identifier, and a shared secret. The sender omits sending the 2919 algorithm identifier for both the content layer and the recipient 2920 layer leaving only the key identifier. The receiver then uses the 2921 key identifier to get the implicit algorithm identifiers. 2923 The following additional items need to be taken into consideration: 2925 * Applications that want to support this will need to define a 2926 structure that allows for, and clearly identifies, both the COSE 2927 structure to be used with a given key and the structure and 2928 algorithm to be used for the secondary layer. The key for the 2929 secondary layer is computed as normal from the recipient layer. 2931 The third case is having multiple implicit algorithm identifiers, but 2932 targeted at potentially unrelated layers or different COSE objects. 2933 There are a number of different scenarios where this might be 2934 applicable. Some of these scenarios are: 2936 * Two contexts are distributed as a pair. Each of the contexts is 2937 for use with a COSE_Encrypt message. Each context will consist of 2938 distinct secret keys and IVs and potentially even different 2939 algorithms. One context is for sending messages from party A to 2940 party B, and the second context is for sending messages from party 2941 B to party A. This means that there is no chance for a reflection 2942 attack to occur as each party uses different secret keys to send 2943 its messages; a message that is reflected back to it would fail to 2944 decrypt. 2946 * Two contexts are distributed as a pair. The first context is used 2947 for encryption of the message, and the second context is used to 2948 place a counter signature on the message. The intention is that 2949 the second context can be distributed to other entities 2950 independently of the first context. This allows these entities to 2951 validate that the message came from an individual without being 2952 able to decrypt the message and see the content. 2954 * Two contexts are distributed as a pair. The first context 2955 contains a key for dealing with MACed messages, and the second 2956 context contains a key for dealing with encrypted messages. This 2957 allows for a unified distribution of keys to participants for 2958 different types of messages that have different keys, but where 2959 the keys may be used in a coordinated manner. 2961 For these cases, the following additional items need to be 2962 considered: 2964 * Applications need to ensure that the multiple contexts stay 2965 associated. If one of the contexts is invalidated for any reason, 2966 all of the contexts associated with it should also be invalidated. 2968 Appendix B. Two Layers of Recipient Information 2970 All of the currently defined recipient algorithm classes only use two 2971 layers of the COSE_Encrypt structure. The first layer is the message 2972 content, and the second layer is the content key encryption. 2973 However, if one uses a recipient algorithm such as the RSA Key 2974 Encapsulation Mechanism (RSA-KEM) (see Appendix A of RSA-KEM 2975 [RFC5990]), then it makes sense to have three layers of the 2976 COSE_Encrypt structure. 2978 These layers would be: 2980 * Layer 0: The content encryption layer. This layer contains the 2981 payload of the message. 2983 * Layer 1: The encryption of the CEK by a KEK. 2985 * Layer 2: The encryption of a long random secret using an RSA key 2986 and a key derivation function to convert that secret into the KEK. 2988 This is an example of what a triple layer message would look like. 2989 The message has the following layers: 2991 * Layer 0: Has a content encrypted with AES-GCM using a 128-bit key. 2993 * Layer 1: Uses the AES Key Wrap algorithm with a 128-bit key. 2995 * Layer 2: Uses ECDH Ephemeral-Static direct to generate the layer 1 2996 key. 2998 In effect, this example is a decomposed version of using the 2999 ECDH-ES+A128KW algorithm. 3001 Size of binary file is 183 bytes 3003 96( 3004 [ 3005 / protected / h'a10101' / { 3006 \ alg \ 1:1 \ AES-GCM 128 \ 3007 } / , 3008 / unprotected / { 3009 / iv / 5:h'02d1f7e6f26c43d4868d87ce' 3010 }, 3011 / ciphertext / h'64f84d913ba60a76070a9a48f26e97e863e2852948658f0 3012 811139868826e89218a75715b', 3013 / recipients / [ 3014 [ 3015 / protected / h'', 3016 / unprotected / { 3017 / alg / 1:-3 / A128KW / 3018 }, 3019 / ciphertext / h'dbd43c4e9d719c27c6275c67d628d493f090593db82 3020 18f11', 3021 / recipients / [ 3022 [ 3023 / protected / h'a1013818' / { 3024 \ alg \ 1:-25 \ ECDH-ES + HKDF-256 \ 3025 } / , 3026 / unprotected / { 3027 / ephemeral / -1:{ 3028 / kty / 1:2, 3029 / crv / -1:1, 3030 / x / -2:h'b2add44368ea6d641f9ca9af308b4079aeb519f11 3031 e9b8a55a600b21233e86e68', 3032 / y / -3:false 3033 }, 3034 / kid / 4:'meriadoc.brandybuck@buckland.example' 3035 }, 3036 / ciphertext / h'' 3037 ] 3038 ] 3039 ] 3040 ] 3041 ] 3042 ) 3044 Appendix C. Examples 3046 This appendix includes a set of examples that show the different 3047 features and message types that have been defined in this document. 3048 To make the examples easier to read, they are presented using the 3049 extended CBOR diagnostic notation (defined in [RFC8610]) rather than 3050 as a binary dump. 3052 A GitHub project has been created at that contains not only the examples presented in this 3054 document, but a more complete set of testing examples as well. Each 3055 example is found in a JSON file that contains the inputs used to 3056 create the example, some of the intermediate values that can be used 3057 in debugging the example and the output of the example presented in 3058 both a hex and a CBOR diagnostic notation format. Some of the 3059 examples at the site are designed failure testing cases; these are 3060 clearly marked as such in the JSON file. If errors in the examples 3061 in this document are found, the examples on GitHub will be updated, 3062 and a note to that effect will be placed in the JSON file. 3064 As noted, the examples are presented using the CBOR's diagnostic 3065 notation. A Ruby-based tool exists that can convert between the 3066 diagnostic notation and binary. This tool can be installed with the 3067 command line: 3069 gem install cbor-diag 3071 The diagnostic notation can be converted into binary files using the 3072 following command line: 3074 diag2cbor.rb < inputfile > outputfile 3076 The examples can be extracted from the XML version of this document 3077 via an XPath expression as all of the artwork is tagged with the 3078 attribute type='CBORdiag'. (Depending on the XPath evaluator one is 3079 using, it may be necessary to deal with > as an entity.) 3081 //artwork[@type='CDDL']/text() 3083 C.1. Examples of Signed Messages 3085 C.1.1. Single Signature 3087 This example uses the following: 3089 * Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 3091 Size of binary file is 103 bytes 3092 98( 3093 [ 3094 / protected / h'', 3095 / unprotected / {}, 3096 / payload / 'This is the content.', 3097 / signatures / [ 3098 [ 3099 / protected / h'a10126' / { 3100 \ alg \ 1:-7 \ ECDSA 256 \ 3101 } / , 3102 / unprotected / { 3103 / kid / 4:'11' 3104 }, 3105 / signature / h'e2aeafd40d69d19dfe6e52077c5d7ff4e408282cbefb 3106 5d06cbf414af2e19d982ac45ac98b8544c908b4507de1e90b717c3d34816fe926a2b 3107 98f53afd2fa0f30a' 3108 ] 3109 ] 3110 ] 3111 ) 3113 C.1.2. Multiple Signers 3115 This example uses the following: 3117 * Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 3119 * Signature Algorithm: ECDSA w/ SHA-512, Curve P-521 3121 Size of binary file is 277 bytes 3122 98( 3123 [ 3124 / protected / h'', 3125 / unprotected / {}, 3126 / payload / 'This is the content.', 3127 / signatures / [ 3128 [ 3129 / protected / h'a10126' / { 3130 \ alg \ 1:-7 \ ECDSA 256 \ 3131 } / , 3132 / unprotected / { 3133 / kid / 4:'11' 3134 }, 3135 / signature / h'e2aeafd40d69d19dfe6e52077c5d7ff4e408282cbefb 3136 5d06cbf414af2e19d982ac45ac98b8544c908b4507de1e90b717c3d34816fe926a2b 3137 98f53afd2fa0f30a' 3138 ], 3139 [ 3140 / protected / h'a1013823' / { 3141 \ alg \ 1:-36 3142 } / , 3143 / unprotected / { 3144 / kid / 4:'bilbo.baggins@hobbiton.example' 3145 }, 3146 / signature / h'00a2d28a7c2bdb1587877420f65adf7d0b9a06635dd1 3147 de64bb62974c863f0b160dd2163734034e6ac003b01e8705524c5c4ca479a952f024 3148 7ee8cb0b4fb7397ba08d009e0c8bf482270cc5771aa143966e5a469a09f613488030 3149 c5b07ec6d722e3835adb5b2d8c44e95ffb13877dd2582866883535de3bb03d01753f 3150 83ab87bb4f7a0297' 3151 ] 3152 ] 3153 ] 3154 ) 3156 C.1.3. Counter Signature 3158 This example uses the following: 3160 * Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 3162 * The same parameters are used for both the signature and the 3163 counter signature. 3165 Size of binary file is 180 bytes 3166 98( 3167 [ 3168 / protected / h'', 3169 / unprotected / { 3170 / countersign / 7:[ 3171 / protected / h'a10126' / { 3172 \ alg \ 1:-7 \ ECDSA 256 \ 3173 } / , 3174 / unprotected / { 3175 / kid / 4:'11' 3176 }, 3177 / signature / h'5ac05e289d5d0e1b0a7f048a5d2b643813ded50bc9e4 3178 9220f4f7278f85f19d4a77d655c9d3b51e805a74b099e1e085aacd97fc29d72f887e 3179 8802bb6650cceb2c' 3180 ] 3181 }, 3182 / payload / 'This is the content.', 3183 / signatures / [ 3184 [ 3185 / protected / h'a10126' / { 3186 \ alg \ 1:-7 \ ECDSA 256 \ 3187 } / , 3188 / unprotected / { 3189 / kid / 4:'11' 3190 }, 3191 / signature / h'e2aeafd40d69d19dfe6e52077c5d7ff4e408282cbefb 3192 5d06cbf414af2e19d982ac45ac98b8544c908b4507de1e90b717c3d34816fe926a2b 3193 98f53afd2fa0f30a' 3194 ] 3195 ] 3196 ] 3197 ) 3199 C.1.4. Signature with Criticality 3201 This example uses the following: 3203 * Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 3205 * There is a criticality marker on the "reserved" header parameter 3207 Size of binary file is 125 bytes 3208 98( 3209 [ 3210 / protected / h'a2687265736572766564f40281687265736572766564' / 3211 { 3212 "reserved":false, 3213 \ crit \ 2:[ 3214 "reserved" 3215 ] 3216 } / , 3217 / unprotected / {}, 3218 / payload / 'This is the content.', 3219 / signatures / [ 3220 [ 3221 / protected / h'a10126' / { 3222 \ alg \ 1:-7 \ ECDSA 256 \ 3223 } / , 3224 / unprotected / { 3225 / kid / 4:'11' 3226 }, 3227 / signature / h'3fc54702aa56e1b2cb20284294c9106a63f91bac658d 3228 69351210a031d8fc7c5ff3e4be39445b1a3e83e1510d1aca2f2e8a7c081c7645042b 3229 18aba9d1fad1bd9c' 3230 ] 3231 ] 3232 ] 3233 ) 3235 C.2. Single Signer Examples 3237 C.2.1. Single ECDSA Signature 3239 This example uses the following: 3241 * Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 3243 Size of binary file is 98 bytes 3244 18( 3245 [ 3246 / protected / h'a10126' / { 3247 \ alg \ 1:-7 \ ECDSA 256 \ 3248 } / , 3249 / unprotected / { 3250 / kid / 4:'11' 3251 }, 3252 / payload / 'This is the content.', 3253 / signature / h'8eb33e4ca31d1c465ab05aac34cc6b23d58fef5c083106c4 3254 d25a91aef0b0117e2af9a291aa32e14ab834dc56ed2a223444547e01f11d3b0916e5 3255 a4c345cacb36' 3256 ] 3257 ) 3259 C.3. Examples of Enveloped Messages 3261 C.3.1. Direct ECDH 3263 This example uses the following: 3265 * CEK: AES-GCM w/ 128-bit key 3267 * Recipient class: ECDH Ephemeral-Static, Curve P-256 3269 Size of binary file is 151 bytes 3270 96( 3271 [ 3272 / protected / h'a10101' / { 3273 \ alg \ 1:1 \ AES-GCM 128 \ 3274 } / , 3275 / unprotected / { 3276 / iv / 5:h'c9cf4df2fe6c632bf7886413' 3277 }, 3278 / ciphertext / h'7adbe2709ca818fb415f1e5df66f4e1a51053ba6d65a1a0 3279 c52a357da7a644b8070a151b0', 3280 / recipients / [ 3281 [ 3282 / protected / h'a1013818' / { 3283 \ alg \ 1:-25 \ ECDH-ES + HKDF-256 \ 3284 } / , 3285 / unprotected / { 3286 / ephemeral / -1:{ 3287 / kty / 1:2, 3288 / crv / -1:1, 3289 / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf 3290 bf054e1c7b4d91d6280', 3291 / y / -3:true 3292 }, 3293 / kid / 4:'meriadoc.brandybuck@buckland.example' 3294 }, 3295 / ciphertext / h'' 3296 ] 3297 ] 3298 ] 3299 ) 3301 C.3.2. Direct Plus Key Derivation 3303 This example uses the following: 3305 * CEK: AES-CCM w/ 128-bit key, truncate the tag to 64 bits 3307 * Recipient class: Use HKDF on a shared secret with the following 3308 implicit fields as part of the context. 3310 - salt: "aabbccddeeffgghh" 3312 - PartyU identity: "lighting-client" 3314 - PartyV identity: "lighting-server" 3316 - Supplementary Public Other: "Encryption Example 02" 3318 Size of binary file is 91 bytes 3320 96( 3321 [ 3322 / protected / h'a1010a' / { 3323 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 3324 } / , 3325 / unprotected / { 3326 / iv / 5:h'89f52f65a1c580933b5261a76c' 3327 }, 3328 / ciphertext / h'753548a19b1307084ca7b2056924ed95f2e3b17006dfe93 3329 1b687b847', 3330 / recipients / [ 3331 [ 3332 / protected / h'a10129' / { 3333 \ alg \ 1:-10 3334 } / , 3335 / unprotected / { 3336 / salt / -20:'aabbccddeeffgghh', 3337 / kid / 4:'our-secret' 3338 }, 3339 / ciphertext / h'' 3340 ] 3341 ] 3342 ] 3343 ) 3345 C.3.3. Counter Signature on Encrypted Content 3347 This example uses the following: 3349 * CEK: AES-GCM w/ 128-bit key 3351 * Recipient class: ECDH Ephemeral-Static, Curve P-256 3353 Size of binary file is 326 bytes 3354 96( 3355 [ 3356 / protected / h'a10101' / { 3357 \ alg \ 1:1 \ AES-GCM 128 \ 3358 } / , 3359 / unprotected / { 3360 / iv / 5:h'c9cf4df2fe6c632bf7886413', 3361 / countersign / 7:[ 3362 / protected / h'a1013823' / { 3363 \ alg \ 1:-36 3364 } / , 3365 / unprotected / { 3366 / kid / 4:'bilbo.baggins@hobbiton.example' 3367 }, 3368 / signature / h'00929663c8789bb28177ae28467e66377da12302d7f9 3369 594d2999afa5dfa531294f8896f2b6cdf1740014f4c7f1a358e3a6cf57f4ed6fb02f 3370 cf8f7aa989f5dfd07f0700a3a7d8f3c604ba70fa9411bd10c2591b483e1d2c31de00 3371 3183e434d8fba18f17a4c7e3dfa003ac1cf3d30d44d2533c4989d3ac38c38b71481c 3372 c3430c9d65e7ddff' 3373 ] 3374 }, 3375 / ciphertext / h'7adbe2709ca818fb415f1e5df66f4e1a51053ba6d65a1a0 3376 c52a357da7a644b8070a151b0', 3377 / recipients / [ 3378 [ 3379 / protected / h'a1013818' / { 3380 \ alg \ 1:-25 \ ECDH-ES + HKDF-256 \ 3381 } / , 3382 / unprotected / { 3383 / ephemeral / -1:{ 3384 / kty / 1:2, 3385 / crv / -1:1, 3386 / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf 3387 bf054e1c7b4d91d6280', 3388 / y / -3:true 3389 }, 3390 / kid / 4:'meriadoc.brandybuck@buckland.example' 3391 }, 3392 / ciphertext / h'' 3393 ] 3394 ] 3395 ] 3396 ) 3398 C.3.4. Encrypted Content with External Data 3400 This example uses the following: 3402 * CEK: AES-GCM w/ 128-bit key 3404 * Recipient class: ECDH static-Static, Curve P-256 with AES Key Wrap 3406 * Externally Supplied AAD: h'0011bbcc22dd44ee55ff660077' 3408 Size of binary file is 173 bytes 3410 96( 3411 [ 3412 / protected / h'a10101' / { 3413 \ alg \ 1:1 \ AES-GCM 128 \ 3414 } / , 3415 / unprotected / { 3416 / iv / 5:h'02d1f7e6f26c43d4868d87ce' 3417 }, 3418 / ciphertext / h'64f84d913ba60a76070a9a48f26e97e863e28529d8f5335 3419 e5f0165eee976b4a5f6c6f09d', 3420 / recipients / [ 3421 [ 3422 / protected / h'a101381f' / { 3423 \ alg \ 1:-32 \ ECHD-SS+A128KW \ 3424 } / , 3425 / unprotected / { 3426 / static kid / -3:'peregrin.took@tuckborough.example', 3427 / kid / 4:'meriadoc.brandybuck@buckland.example', 3428 / U nonce / -22:h'0101' 3429 }, 3430 / ciphertext / h'41e0d76f579dbd0d936a662d54d8582037de2e366fd 3431 e1c62' 3432 ] 3433 ] 3434 ] 3435 ) 3437 C.4. Examples of Encrypted Messages 3439 C.4.1. Simple Encrypted Message 3441 This example uses the following: 3443 * CEK: AES-CCM w/ 128-bit key and a 64-bit tag 3445 Size of binary file is 52 bytes 3446 16( 3447 [ 3448 / protected / h'a1010a' / { 3449 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 3450 } / , 3451 / unprotected / { 3452 / iv / 5:h'89f52f65a1c580933b5261a78c' 3453 }, 3454 / ciphertext / h'5974e1b99a3a4cc09a659aa2e9e7fff161d38ce71cb45ce 3455 460ffb569' 3456 ] 3457 ) 3459 C.4.2. Encrypted Message with a Partial IV 3461 This example uses the following: 3463 * CEK: AES-CCM w/ 128-bit key and a 64-bit tag 3465 * Prefix for IV is 89F52F65A1C580933B52 3467 Size of binary file is 41 bytes 3469 16( 3470 [ 3471 / protected / h'a1010a' / { 3472 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 3473 } / , 3474 / unprotected / { 3475 / partial iv / 6:h'61a7' 3476 }, 3477 / ciphertext / h'252a8911d465c125b6764739700f0141ed09192de139e05 3478 3bd09abca' 3479 ] 3480 ) 3482 C.5. Examples of MACed Messages 3484 C.5.1. Shared Secret Direct MAC 3486 This example uses the following: 3488 * MAC: AES-CMAC, 256-bit key, truncated to 64 bits 3490 * Recipient class: direct shared secret 3492 Size of binary file is 57 bytes 3493 97( 3494 [ 3495 / protected / h'a1010f' / { 3496 \ alg \ 1:15 \ AES-CBC-MAC-256//64 \ 3497 } / , 3498 / unprotected / {}, 3499 / payload / 'This is the content.', 3500 / tag / h'9e1226ba1f81b848', 3501 / recipients / [ 3502 [ 3503 / protected / h'', 3504 / unprotected / { 3505 / alg / 1:-6 / direct /, 3506 / kid / 4:'our-secret' 3507 }, 3508 / ciphertext / h'' 3509 ] 3510 ] 3511 ] 3512 ) 3514 C.5.2. ECDH Direct MAC 3516 This example uses the following: 3518 * MAC: HMAC w/SHA-256, 256-bit key 3520 * Recipient class: ECDH key agreement, two static keys, HKDF w/ 3521 context structure 3523 Size of binary file is 214 bytes 3524 97( 3525 [ 3526 / protected / h'a10105' / { 3527 \ alg \ 1:5 \ HMAC 256//256 \ 3528 } / , 3529 / unprotected / {}, 3530 / payload / 'This is the content.', 3531 / tag / h'81a03448acd3d305376eaa11fb3fe416a955be2cbe7ec96f012c99 3532 4bc3f16a41', 3533 / recipients / [ 3534 [ 3535 / protected / h'a101381a' / { 3536 \ alg \ 1:-27 \ ECDH-SS + HKDF-256 \ 3537 } / , 3538 / unprotected / { 3539 / static kid / -3:'peregrin.took@tuckborough.example', 3540 / kid / 4:'meriadoc.brandybuck@buckland.example', 3541 / U nonce / -22:h'4d8553e7e74f3c6a3a9dd3ef286a8195cbf8a23d 3542 19558ccfec7d34b824f42d92bd06bd2c7f0271f0214e141fb779ae2856abf585a583 3543 68b017e7f2a9e5ce4db5' 3544 }, 3545 / ciphertext / h'' 3546 ] 3547 ] 3548 ] 3549 ) 3551 C.5.3. Wrapped MAC 3553 This example uses the following: 3555 * MAC: AES-MAC, 128-bit key, truncated to 64 bits 3557 * Recipient class: AES Key Wrap w/ a pre-shared 256-bit key 3559 Size of binary file is 109 bytes 3560 97( 3561 [ 3562 / protected / h'a1010e' / { 3563 \ alg \ 1:14 \ AES-CBC-MAC-128//64 \ 3564 } / , 3565 / unprotected / {}, 3566 / payload / 'This is the content.', 3567 / tag / h'36f5afaf0bab5d43', 3568 / recipients / [ 3569 [ 3570 / protected / h'', 3571 / unprotected / { 3572 / alg / 1:-5 / A256KW /, 3573 / kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037' 3574 }, 3575 / ciphertext / h'711ab0dc2fc4585dce27effa6781c8093eba906f227 3576 b6eb0' 3577 ] 3578 ] 3579 ] 3580 ) 3582 C.5.4. Multi-Recipient MACed Message 3584 This example uses the following: 3586 * MAC: HMAC w/ SHA-256, 128-bit key 3588 * Recipient class: Uses three different methods 3590 1. ECDH Ephemeral-Static, Curve P-521, AES Key Wrap w/ 128-bit 3591 key 3593 2. AES Key Wrap w/ 256-bit key 3595 Size of binary file is 309 bytes 3596 97( 3597 [ 3598 / protected / h'a10105' / { 3599 \ alg \ 1:5 \ HMAC 256//256 \ 3600 } / , 3601 / unprotected / {}, 3602 / payload / 'This is the content.', 3603 / tag / h'bf48235e809b5c42e995f2b7d5fa13620e7ed834e337f6aa43df16 3604 1e49e9323e', 3605 / recipients / [ 3606 [ 3607 / protected / h'a101381c' / { 3608 \ alg \ 1:-29 \ ECHD-ES+A128KW \ 3609 } / , 3610 / unprotected / { 3611 / ephemeral / -1:{ 3612 / kty / 1:2, 3613 / crv / -1:3, 3614 / x / -2:h'0043b12669acac3fd27898ffba0bcd2e6c366d53bc4db 3615 71f909a759304acfb5e18cdc7ba0b13ff8c7636271a6924b1ac63c02688075b55ef2 3616 d613574e7dc242f79c3', 3617 / y / -3:true 3618 }, 3619 / kid / 4:'bilbo.baggins@hobbiton.example' 3620 }, 3621 / ciphertext / h'339bc4f79984cdc6b3e6ce5f315a4c7d2b0ac466fce 3622 a69e8c07dfbca5bb1f661bc5f8e0df9e3eff5' 3623 ], 3624 [ 3625 / protected / h'', 3626 / unprotected / { 3627 / alg / 1:-5 / A256KW /, 3628 / kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037' 3629 }, 3630 / ciphertext / h'0b2c7cfce04e98276342d6476a7723c090dfdd15f9a 3631 518e7736549e998370695e6d6a83b4ae507bb' 3632 ] 3633 ] 3634 ] 3635 ) 3637 C.6. Examples of MAC0 Messages 3639 C.6.1. Shared Secret Direct MAC 3641 This example uses the following: 3643 * MAC: AES-CMAC, 256-bit key, truncated to 64 bits 3644 * Recipient class: direct shared secret 3646 Size of binary file is 37 bytes 3648 17( 3649 [ 3650 / protected / h'a1010f' / { 3651 \ alg \ 1:15 \ AES-CBC-MAC-256//64 \ 3652 } / , 3653 / unprotected / {}, 3654 / payload / 'This is the content.', 3655 / tag / h'726043745027214f' 3656 ] 3657 ) 3659 Note that this example uses the same inputs as Section c.5.1. 3661 C.7. COSE Keys 3663 C.7.1. Public Keys 3665 This is an example of a COSE Key Set. This example includes the 3666 public keys for all of the previous examples. 3668 In order the keys are: 3670 * An EC key with a kid of "meriadoc.brandybuck@buckland.example" 3672 * An EC key with a kid of "peregrin.took@tuckborough.example" 3674 * An EC key with a kid of "bilbo.baggins@hobbiton.example" 3676 * An EC key with a kid of "11" 3678 Size of binary file is 481 bytes 3680 [ 3681 { 3682 -1:1, 3683 -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0 3684 8551d', 3685 -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008 3686 4d19c', 3687 1:2, 3688 2:'meriadoc.brandybuck@buckland.example' 3689 }, 3690 { 3691 -1:1, 3692 -2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a 3693 09eff', 3694 -3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbf 3695 c117e', 3696 1:2, 3697 2:'11' 3698 }, 3699 { 3700 -1:3, 3701 -2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737bf5de 3702 7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620085e5c8 3703 f42ad', 3704 -3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e247e 3705 60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3fe1ea1 3706 d9475', 3707 1:2, 3708 2:'bilbo.baggins@hobbiton.example' 3709 }, 3710 { 3711 -1:1, 3712 -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b4d91 3713 d6280', 3714 -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e03bf 3715 822bb', 3716 1:2, 3717 2:'peregrin.took@tuckborough.example' 3718 } 3719 ] 3721 C.7.2. Private Keys 3723 This is an example of a COSE Key Set. This example includes the 3724 private keys for all of the previous examples. 3726 In order the keys are: 3728 * An EC key with a kid of "meriadoc.brandybuck@buckland.example" 3730 * A shared-secret key with a kid of "our-secret" 3732 * An EC key with a kid of "peregrin.took@tuckborough.example" 3734 * A shared-secret key with a kid of "018c0ae5-4d9b-471b- 3735 bfd6-eef314bc7037" 3737 * An EC key with a kid of "bilbo.baggins@hobbiton.example" 3739 * An EC key with a kid of "11" 3741 Size of binary file is 816 bytes 3743 [ 3744 { 3745 1:2, 3746 2:'meriadoc.brandybuck@buckland.example', 3747 -1:1, 3748 -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0 3749 8551d', 3750 -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008 3751 4d19c', 3752 -4:h'aff907c99f9ad3aae6c4cdf21122bce2bd68b5283e6907154ad911840fa 3753 208cf' 3754 }, 3755 { 3756 1:2, 3757 2:'11', 3758 -1:1, 3759 -2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a 3760 09eff', 3761 -3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbf 3762 c117e', 3763 -4:h'57c92077664146e876760c9520d054aa93c3afb04e306705db609030850 3764 7b4d3' 3765 }, 3766 { 3767 1:2, 3768 2:'bilbo.baggins@hobbiton.example', 3769 -1:3, 3770 -2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737bf5de 3771 7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620085e5c8 3772 f42ad', 3773 -3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e247e 3774 60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3fe1ea1 3775 d9475', 3776 -4:h'00085138ddabf5ca975f5860f91a08e91d6d5f9a76ad4018766a476680b 3777 55cd339e8ab6c72b5facdb2a2a50ac25bd086647dd3e2e6e99e84ca2c3609fdf177f 3778 eb26d' 3779 }, 3780 { 3781 1:4, 3782 2:'our-secret', 3783 -1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dcea6c4 3784 27188' 3785 }, 3786 { 3787 1:2, 3788 -1:1, 3789 2:'peregrin.took@tuckborough.example', 3790 -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b4d91 3791 d6280', 3792 -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e03bf 3793 822bb', 3794 -4:h'02d1f7e6f26c43d4868d87ceb2353161740aacf1f7163647984b522a848 3795 df1c3' 3796 }, 3797 { 3798 1:4, 3799 2:'our-secret2', 3800 -1:h'849b5786457c1491be3a76dcea6c4271' 3801 }, 3802 { 3803 1:4, 3804 2:'018c0ae5-4d9b-471b-bfd6-eef314bc7037', 3805 -1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dcea6c4 3806 27188' 3807 } 3808 ] 3810 Acknowledgments 3812 This document is a product of the COSE working group of the IETF. 3814 The following individuals are to blame for getting me started on this 3815 project in the first place: Richard Barnes, Matt Miller, and Martin 3816 Thomson. 3818 The initial version of the specification was based to some degree on 3819 the outputs of the JOSE and S/MIME working groups. 3821 The following individuals provided input into the final form of the 3822 document: Carsten Bormann, John Bradley, Brain Campbell, Michael B. 3824 Jones, Ilari Liusvaara, Francesca Palombini, Ludwig Seitz, and Goran 3825 Selander. 3827 Author's Address 3829 Jim Schaad 3830 August Cellars 3832 Email: ietf@augustcellars.com