idnits 2.17.1 draft-ietf-cose-rfc8152bis-struct-13.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([I-D.ietf-cose-RFC8152bis-algs]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 2917 has weird spacing: '...otected h'a10...' == Line 2935 has weird spacing: '...otected h'a10...' == Line 3201 has weird spacing: '...otected h'a10...' == Line 3286 has weird spacing: '...otected h'a10...' == Line 3310 has weird spacing: '...otected h'a10...' == (3 more instances...) -- The document date (September 4, 2020) is 1329 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) == Outdated reference: A later version (-16) exists of draft-ietf-cbor-7049bis-14 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-cbor-7049bis' == Outdated reference: A later version (-12) exists of draft-ietf-cose-rfc8152bis-algs-11 ** Downref: Normative reference to an Informational draft: draft-ietf-cose-rfc8152bis-algs (ref. 'I-D.ietf-cose-rfc8152bis-algs') -- Obsolete informational reference (is this intentional?): RFC 8152 (Obsoleted by RFC 9052, RFC 9053) -- Obsolete informational reference (is this intentional?): RFC 2633 (Obsoleted by RFC 3851) -- Obsolete informational reference (is this intentional?): RFC 5751 (Obsoleted by RFC 8551) == Outdated reference: A later version (-09) exists of draft-ietf-cose-hash-algs-08 == Outdated reference: A later version (-11) exists of draft-ietf-core-groupcomm-bis-01 == Outdated reference: A later version (-13) exists of draft-irtf-cfrg-argon2-11 Summary: 2 errors (**), 0 flaws (~~), 12 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 COSE Working Group J. Schaad 3 Internet-Draft August Cellars 4 Obsoletes: 8152 (if approved) September 4, 2020 5 Intended status: Standards Track 6 Expires: March 8, 2021 8 CBOR Object Signing and Encryption (COSE): Structures and Process 9 draft-ietf-cose-rfc8152bis-struct-13 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 March 8, 2021. 51 Copyright Notice 53 Copyright (c) 2020 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. Requirements Terminology . . . . . . . . . . . . . . . . 6 69 1.2. Changes from RFC8152 . . . . . . . . . . . . . . . . . . 6 70 1.3. Design Changes from JOSE . . . . . . . . . . . . . . . . 6 71 1.4. CBOR Grammar . . . . . . . . . . . . . . . . . . . . . . 7 72 1.5. CBOR-Related Terminology . . . . . . . . . . . . . . . . 8 73 1.6. Document Terminology . . . . . . . . . . . . . . . . . . 9 74 2. Basic COSE Structure . . . . . . . . . . . . . . . . . . . . 10 75 3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 13 76 3.1. Common COSE Header Parameters . . . . . . . . . . . . . . 15 77 4. Signing Objects . . . . . . . . . . . . . . . . . . . . . . . 18 78 4.1. Signing with One or More Signers . . . . . . . . . . . . 18 79 4.2. Signing with One Signer . . . . . . . . . . . . . . . . . 20 80 4.3. Externally Supplied Data . . . . . . . . . . . . . . . . 21 81 4.4. Signing and Verification Process . . . . . . . . . . . . 22 82 5. Encryption Objects . . . . . . . . . . . . . . . . . . . . . 24 83 5.1. Enveloped COSE Structure . . . . . . . . . . . . . . . . 24 84 5.1.1. Content Key Distribution Methods . . . . . . . . . . 26 85 5.2. Single Recipient Encrypted . . . . . . . . . . . . . . . 26 86 5.3. How to Encrypt and Decrypt for AEAD Algorithms . . . . . 27 87 5.4. How to Encrypt and Decrypt for AE Algorithms . . . . . . 29 88 6. MAC Objects . . . . . . . . . . . . . . . . . . . . . . . . . 30 89 6.1. MACed Message with Recipients . . . . . . . . . . . . . . 31 90 6.2. MACed Messages with Implicit Key . . . . . . . . . . . . 32 91 6.3. How to Compute and Verify a MAC . . . . . . . . . . . . . 33 92 7. Key Objects . . . . . . . . . . . . . . . . . . . . . . . . . 34 93 7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 35 94 8. Taxonomy of Algorithms used by COSE . . . . . . . . . . . . . 37 95 8.1. Signature Algorithms . . . . . . . . . . . . . . . . . . 38 96 8.2. Message Authentication Code (MAC) Algorithms . . . . . . 39 97 8.3. Content Encryption Algorithms . . . . . . . . . . . . . . 39 98 8.4. Key Derivation Functions (KDFs) . . . . . . . . . . . . . 40 99 8.5. Content Key Distribution Methods . . . . . . . . . . . . 41 100 8.5.1. Direct Encryption . . . . . . . . . . . . . . . . . . 41 101 8.5.2. Key Wrap . . . . . . . . . . . . . . . . . . . . . . 41 102 8.5.3. Key Transport . . . . . . . . . . . . . . . . . . . . 42 103 8.5.4. Direct Key Agreement . . . . . . . . . . . . . . . . 42 104 8.5.5. Key Agreement with Key Wrap . . . . . . . . . . . . . 43 105 9. CBOR Encoding Restrictions . . . . . . . . . . . . . . . . . 44 106 10. Application Profiling Considerations . . . . . . . . . . . . 44 107 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46 108 11.1. COSE Header Parameters Registry . . . . . . . . . . . . 46 109 11.2. COSE Key Common Parameters Registry . . . . . . . . . . 46 110 11.3. Media Type Registrations . . . . . . . . . . . . . . . . 46 111 11.3.1. COSE Security Message . . . . . . . . . . . . . . . 46 112 11.3.2. COSE Key Media Type . . . . . . . . . . . . . . . . 47 113 11.4. CoAP Content-Formats Registry . . . . . . . . . . . . . 49 114 11.5. Expert Review Instructions . . . . . . . . . . . . . . . 49 115 12. Security Considerations . . . . . . . . . . . . . . . . . . . 50 116 13. Implementation Status . . . . . . . . . . . . . . . . . . . . 52 117 13.1. Author's Versions . . . . . . . . . . . . . . . . . . . 53 118 13.2. JavaScript Version . . . . . . . . . . . . . . . . . . . 53 119 13.3. Python Version . . . . . . . . . . . . . . . . . . . . . 54 120 13.4. COSE Testing Library . . . . . . . . . . . . . . . . . . 54 121 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 54 122 14.1. Normative References . . . . . . . . . . . . . . . . . . 54 123 14.2. Informative References . . . . . . . . . . . . . . . . . 55 124 Appendix A. Guidelines for External Data Authentication of 125 Algorithms . . . . . . . . . . . . . . . . . . . . . . . 59 126 Appendix B. Two Layers of Recipient Information . . . . . . . . 62 127 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 64 128 C.1. Examples of Signed Messages . . . . . . . . . . . . . . . 64 129 C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 64 130 C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 65 131 C.1.3. Signature with Criticality . . . . . . . . . . . . . 66 132 C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 67 133 C.2.1. Single ECDSA Signature . . . . . . . . . . . . . . . 67 134 C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 68 135 C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 68 136 C.3.2. Direct Plus Key Derivation . . . . . . . . . . . . . 69 137 C.3.3. Encrypted Content with External Data . . . . . . . . 70 138 C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 71 139 C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 71 140 C.4.2. Encrypted Message with a Partial IV . . . . . . . . . 72 141 C.5. Examples of MACed Messages . . . . . . . . . . . . . . . 72 142 C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 72 143 C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 73 144 C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 74 145 C.5.4. Multi-Recipient MACed Message . . . . . . . . . . . . 75 146 C.6. Examples of MAC0 Messages . . . . . . . . . . . . . . . . 76 147 C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 76 148 C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 77 149 C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 77 150 C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 78 151 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 80 152 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 81 154 1. Introduction 156 There has been an increased focus on small, constrained devices that 157 make up the Internet of Things (IoT). One of the standards that has 158 come out of this process is "Concise Binary Object Representation 159 (CBOR)" [I-D.ietf-cbor-7049bis]. CBOR extended the data model of the 160 JavaScript Object Notation (JSON) [STD90] by allowing for binary 161 data, among other changes. CBOR has been adopted by several of the 162 IETF working groups dealing with the IoT world as their encoding of 163 data structures. CBOR was designed specifically both to be small in 164 terms of messages transported and implementation size and to be a 165 schema-free decoder. A need exists to provide message security 166 services for IoT, and using CBOR as the message-encoding format makes 167 sense. 169 The JOSE working group produced a set of documents [RFC7515] 170 [RFC7516] [RFC7517] [RFC7518] that specified how to process 171 encryption, signatures, and Message Authentication Code (MAC) 172 operations and how to encode keys using JSON. This document defines 173 the CBOR Object Signing and Encryption (COSE) standard, which does 174 the same thing for the CBOR encoding format. This document is 175 combined with [I-D.ietf-cose-rfc8152bis-algs] which provides an 176 initial set of algorithms. While there is a strong attempt to keep 177 the flavor of the original JSON Object Signing and Encryption (JOSE) 178 documents, two considerations are taken into account: 180 * CBOR has capabilities that are not present in JSON and are 181 appropriate to use. One example of this is the fact that CBOR has 182 a method of encoding binary directly without first converting it 183 into a base64-encoded text string. 185 * COSE is not a direct copy of the JOSE specification. In the 186 process of creating COSE, decisions that were made for JOSE were 187 re-examined. In many cases, different results were decided on as 188 the criteria were not always the same. 190 This document contains: 192 * The description of the structure for the CBOR objects which are 193 transmitted over the wire. Two objects are defined for each of 194 encryption, signing and message authentication. One object is 195 defined for transporting keys and one for transporting groups of 196 keys. 198 * The procedures used to build the inputs to the cryptographic 199 functions required for each of the structures. 201 * A set of attributes that apply to the different security objects. 203 This document does not contain the rules and procedures for using 204 specific cryptographic algorithms. Details on specific algorithms 205 can be found in [I-D.ietf-cose-rfc8152bis-algs] and [RFC8230]. 206 Details for additional algorithms are expected to be defined in 207 future documents. 209 COSE was initially designed as part of a solution to provide security 210 to Constrained RESTful Environments (CoRE), and this is done using 211 [RFC8613] and [I-D.ietf-core-groupcomm-bis]. However, COSE is not 212 restricted to just these cases and can be used in any place where one 213 would consider either JOSE or CMS [RFC5652] for the purpose of 214 providing security services. The use of COSE, like JOSE and CMS, is 215 only for use in store and forward or offline protocols. The use of 216 COSE in online protocols needing encryption, require that an online 217 key establishment process be done before sending objects back and 218 forth. Any application which uses COSE for security services first 219 needs to determine what security services are required and then 220 select the appropriate COSE structures and cryptographic algorithms 221 based on those needs. Section 10 provides additional information on 222 what applications need to specify when using COSE. 224 One feature that is present in CMS that is not present in this 225 standard is a digest structure. This omission is deliberate. It is 226 better for the structure to be defined in each protocol as different 227 protocols will want to include a different set of fields as part of 228 the structure. While an algorithm identifier and the digest value 229 are going to be common to all applications, the two values may not 230 always be adjacent as the algorithm could be defined once with 231 multiple values. Applications may additionally want to define 232 additional data fields as part of the structure. A one such 233 application-specific element would be to include a URI or other 234 pointer to where the data that is being hashed can be obtained. 235 [I-D.ietf-cose-hash-algs] contains one such possible structure along 236 with defining a set of digest algorithms. 238 During the process of advancing COSE to Internet Standard, it was 239 noticed the description of the security properties of 240 countersignatures was incorrect for the COSE_Sign1 structure. Since 241 the security properties that were described, those of a true 242 countersignature, were those that the working group desired, the 243 decision was made to remove all of the countersignature text from 244 this document and create a new document [I-D.ietf-cose-countersign] 245 to both deprecate the old countersignature algorithm and header 246 parameters and to define a new algorithm and header parameters with 247 the desired security properties. 249 1.1. Requirements Terminology 251 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 252 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 253 "OPTIONAL" in this document are to be interpreted as described in BCP 254 14 [RFC2119] [RFC8174] when, and only when, they appear in all 255 capitals, as shown here. 257 1.2. Changes from RFC8152 259 * Split the original document into this document and 260 [I-D.ietf-cose-rfc8152bis-algs]. 262 * Add some text describing why there is no digest structure defined 263 by COSE. 265 * Text clarifications and changes in terminology. 267 * All of the details relating to countersignatures have been removed 268 and placed in [I-D.ietf-cose-countersign]. 270 1.3. Design Changes from JOSE 272 * Define a single overall message structure so that encrypted, 273 signed, and MACed messages can easily be identified and still have 274 a consistent view. 276 * Signed messages distinguish between the protected and unprotected 277 header parameters that relate to the content and those that relate 278 to the signature. 280 * MACed messages are separated from signed messages. 282 * MACed messages have the ability to use the same set of recipient 283 algorithms as enveloped messages for obtaining the MAC 284 authentication key. 286 * Use binary encodings, rather than base64url encodings, to encode 287 binary data. 289 * Combine the authentication tag for encryption algorithms with the 290 ciphertext. 292 * The set of cryptographic algorithms has been expanded in some 293 directions and trimmed in others. 295 1.4. CBOR Grammar 297 There was not a standard CBOR grammar available when COSE was 298 originally written. For that reason the CBOR data objects defined 299 here are described in prose. Since that time CBOR Data Definition 300 Language (CDDL) [RFC8610] has been published as an RFC. The CBOR 301 grammar presented in this document is compatible with CDDL. 303 The document was developed by first working on the grammar and then 304 developing the prose to go with it. An artifact of this is that the 305 prose was written using the primitive type strings defined by CBOR 306 Data Definition Language (CDDL) [RFC8610]. In this specification, 307 the following primitive types are used: 309 any -- non-specific value that permits all CBOR values to be 310 placed here. 312 bool -- a boolean value (true: major type 7, value 21; false: 313 major type 7, value 20). 315 bstr -- byte string (major type 2). 317 int -- an unsigned integer or a negative integer. 319 nil -- a null value (major type 7, value 22). 321 nint -- a negative integer (major type 1). 323 tstr -- a UTF-8 text string (major type 3). 325 uint -- an unsigned integer (major type 0). 327 Two syntaxes from CDDL appear in this document as shorthand. These 328 are: 330 FOO / BAR -- indicates that either FOO or BAR can appear here. 332 [+ FOO] -- indicates that the type FOO appears one or more times 333 in an array. 335 * FOO -- indicates that the type FOO appears zero or more times. 337 Two of the constraints defined by CDDL are also used in this 338 document. These are: 340 type1 .cbor type2 -- indicates that the contents of type1, usually 341 bstr, contains a value of type2. 343 type1 .size integer -- indicates that the contents of type1 is 344 integer bytes long 346 As well as the prose description, a version of a CBOR grammar is 347 presented in CDDL. The CDDL grammar is informational; the prose 348 description is normative. 350 The collected CDDL can be extracted from the XML version of this 351 document via the following XPath expression below. (Depending on the 352 XPath evaluator one is using, it may be necessary to deal with > 353 as an entity.) 355 //sourcecode[@type='CDDL']/text() 357 CDDL expects the initial non-terminal symbol to be the first symbol 358 in the file. For this reason, the first fragment of CDDL is 359 presented here. 361 start = COSE_Messages / COSE_Key / COSE_KeySet / Internal_Types 363 ; This is defined to make the tool quieter: 364 Internal_Types = Sig_structure / Enc_structure / MAC_structure 366 The non-terminal Internal_Types is defined for dealing with the 367 automated validation tools used during the writing of this document. 368 It references those non-terminals that are used for security 369 computations but are not emitted for transport. 371 1.5. CBOR-Related Terminology 373 In JSON, maps are called objects and only have one kind of map key: a 374 text string. In COSE, we use text strings, negative integers, and 375 unsigned integers as map keys. The integers are used for compactness 376 of encoding and easy comparison. The inclusion of text strings 377 allows for an additional range of short encoded values to be used as 378 well. Since the word "key" is mainly used in its other meaning, as a 379 cryptographic key, we use the term "label" for this usage as a map 380 key. 382 The presence a label that is neither a a text string or an integer, 383 in a CBOR map, is an error. Applications can either fail processing 384 or process messages by ignoring incorrect labels; however, they MUST 385 NOT create messages with incorrect labels. 387 A CDDL grammar fragment defines the non-terminal 'label', as in the 388 previous paragraph, and 'values', which permits any value to be used. 390 label = int / tstr 391 values = any 393 1.6. Document Terminology 395 In this document, we use the following terminology: 397 Byte is a synonym for octet. 399 Constrained Application Protocol (CoAP) is a specialized web transfer 400 protocol for use in constrained systems. It is defined in [RFC7252]. 402 Authenticated Encryption (AE) [RFC5116] algorithms are encryption 403 algorithms that provide an authentication check of the contents with 404 the encryption service. An example of an AE algorithm used in COSE 405 is AES Key Wrap [RFC3394]. These algorithms are used for key 406 encryption algorithms, but AEAD algorithms would be preferred. 408 Authenticated Encryption with Associated Data (AEAD) [RFC5116] 409 algorithms provide the same authentication service of the content as 410 AE algorithms do. They also allow for associated data to be included 411 in the authentication service, but which is not part of the encrypted 412 body. An example of an AEAD algorithm used in COSE is AES-GCM 413 [RFC5116]. These algorithms are used for content encryption and can 414 be used for key encryption as well. 416 Context is used throughout the document to represent information that 417 is not part of the COSE message. Information which is part of the 418 context can come from several different sources including: Protocol 419 interactions, associated key structures, and program configuration. 420 The context to use can be implicit, identified using the 'kid 421 context' header parameter defined in [RFC8613], or identified by a 422 protocol-specific identifier. Context should generally be included 423 in the cryptographic construction; for more details see Section 4.3. 425 The term 'byte string' is used for sequences of bytes, while the term 426 'text string' is used for sequences of characters. 428 2. Basic COSE Structure 430 The COSE object structure is designed so that there can be a large 431 amount of common code when parsing and processing the different types 432 of security messages. All of the message structures are built on the 433 CBOR array type. The first three elements of the array always 434 contain the same information: 436 1. The protected header parameters, encoded and wrapped in a bstr. 438 2. The unprotected header parameters as a map. 440 3. The content of the message. The content is either the plaintext 441 or the ciphertext as appropriate. The content may be detached 442 (i.e. transported separately from the COSE structure), but the 443 location is still used. The content is wrapped in a bstr when 444 present and is a nil value when detached. 446 Elements after this point are dependent on the specific message type. 448 COSE messages are built using the concept of layers to separate 449 different types of cryptographic concepts. As an example of how this 450 works, consider the COSE_Encrypt message (Section 5.1). This message 451 type is broken into two layers: the content layer and the recipient 452 layer. The content layer contains the plaintext is encrypted and 453 information about the encrypted message. The recipient layer contins 454 the content encryption key (CEK) is encrypted and information about 455 how it is encrypted for each recipient. A single layer version of 456 the encryption message COSE_Encrypt0 (Section 5.2) is provided for 457 cases where the CEK is pre-shared. 459 Identification of which type of message has been presented is done by 460 the following methods: 462 1. The specific message type is known from the context. This may be 463 defined by a marker in the containing structure or by 464 restrictions specified by the application protocol. 466 2. The message type is identified by a CBOR tag. Messages with a 467 CBOR tag are known in this specification as tagged messages, 468 while those without the CBOR tag are known as untagged messages. 469 This document defines a CBOR tag for each of the message 470 structures. These tags can be found in Table 1. 472 3. When a COSE object is carried in a media type of 'application/ 473 cose', the optional parameter 'cose-type' can be used to identify 474 the embedded object. The parameter is OPTIONAL if the tagged 475 version of the structure is used. The parameter is REQUIRED if 476 the untagged version of the structure is used. The value to use 477 with the parameter for each of the structures can be found in 478 Table 1. 480 4. When a COSE object is carried as a CoAP payload, the CoAP 481 Content-Format Option can be used to identify the message 482 content. The CoAP Content-Format values can be found in Table 2. 483 The CBOR tag for the message structure is not required as each 484 security message is uniquely identified. 486 +==========+===============+===============+=======================+ 487 | CBOR Tag | cose-type | Data Item | Semantics | 488 +==========+===============+===============+=======================+ 489 | 98 | cose-sign | COSE_Sign | COSE Signed Data | 490 | | | | Object | 491 +----------+---------------+---------------+-----------------------+ 492 | 18 | cose-sign1 | COSE_Sign1 | COSE Single Signer | 493 | | | | Data Object | 494 +----------+---------------+---------------+-----------------------+ 495 | 96 | cose-encrypt | COSE_Encrypt | COSE Encrypted Data | 496 | | | | Object | 497 +----------+---------------+---------------+-----------------------+ 498 | 16 | cose-encrypt0 | COSE_Encrypt0 | COSE Single Recipient | 499 | | | | Encrypted Data Object | 500 +----------+---------------+---------------+-----------------------+ 501 | 97 | cose-mac | COSE_Mac | COSE MACed Data | 502 | | | | Object | 503 +----------+---------------+---------------+-----------------------+ 504 | 17 | cose-mac0 | COSE_Mac0 | COSE Mac w/o | 505 | | | | Recipients Object | 506 +----------+---------------+---------------+-----------------------+ 508 Table 1: COSE Message Identification 510 +===========================+==========+=====+============+ 511 | Media Type | Encoding | ID | Reference | 512 +===========================+==========+=====+============+ 513 | application/cose; cose- | | 98 | [[THIS | 514 | type="cose-sign" | | | DOCUMENT]] | 515 +---------------------------+----------+-----+------------+ 516 | application/cose; cose- | | 18 | [[THIS | 517 | type="cose-sign1" | | | DOCUMENT]] | 518 +---------------------------+----------+-----+------------+ 519 | application/cose; cose- | | 96 | [[THIS | 520 | type="cose-encrypt" | | | DOCUMENT]] | 521 +---------------------------+----------+-----+------------+ 522 | application/cose; cose- | | 16 | [[THIS | 523 | type="cose-encrypt0" | | | DOCUMENT]] | 524 +---------------------------+----------+-----+------------+ 525 | application/cose; cose- | | 97 | [[THIS | 526 | type="cose-mac" | | | DOCUMENT]] | 527 +---------------------------+----------+-----+------------+ 528 | application/cose; cose- | | 17 | [[THIS | 529 | type="cose-mac0" | | | DOCUMENT]] | 530 +---------------------------+----------+-----+------------+ 531 | application/cose-key | | 101 | [[THIS | 532 | | | | DOCUMENT]] | 533 +---------------------------+----------+-----+------------+ 534 | application/cose-key-set | | 102 | [[THIS | 535 | | | | DOCUMENT]] | 536 +---------------------------+----------+-----+------------+ 538 Table 2: CoAP Content-Formats for COSE 540 The following CDDL fragment identifies all of the top messages 541 defined in this document. Separate non-terminals are defined for the 542 tagged and the untagged versions of the messages. 544 COSE_Messages = COSE_Untagged_Message / COSE_Tagged_Message 546 COSE_Untagged_Message = COSE_Sign / COSE_Sign1 / 547 COSE_Encrypt / COSE_Encrypt0 / 548 COSE_Mac / COSE_Mac0 550 COSE_Tagged_Message = COSE_Sign_Tagged / COSE_Sign1_Tagged / 551 COSE_Encrypt_Tagged / COSE_Encrypt0_Tagged / 552 COSE_Mac_Tagged / COSE_Mac0_Tagged 554 3. Header Parameters 556 The structure of COSE has been designed to have two buckets of 557 information that are not considered to be part of the payload itself, 558 but are used for holding information about content, algorithms, keys, 559 or evaluation hints for the processing of the layer. These two 560 buckets are available for use in all of the structures except for 561 keys. While these buckets are present, they may not always be usable 562 in all instances. For example, while the protected bucket is defined 563 as part of the recipient structure, some of the algorithms used for 564 recipient structures do not provide for authenticated data. If this 565 is the case, the protected bucket is left empty. 567 Both buckets are implemented as CBOR maps. The map key is a 'label' 568 (Section 1.5). The value portion is dependent on the definition for 569 the label. Both maps use the same set of label/value pairs. The 570 integer and text string values for labels have been divided into 571 several sections including a standard range, a private range, and a 572 range that is dependent on the algorithm selected. The defined 573 labels can be found in the "COSE Header Parameters" IANA registry 574 (Section 11.1). 576 The two buckets are: 578 protected: Contains parameters about the current layer that are 579 cryptographically protected. This bucket MUST be empty if it is 580 not going to be included in a cryptographic computation. This 581 bucket is encoded in the message as a binary object. This value 582 is obtained by CBOR encoding the protected map and wrapping it in 583 a bstr object. Senders SHOULD encode a zero-length map as a zero- 584 length byte string rather than as a zero-length map (encoded as 585 h'a0'). The zero-length binary encoding is preferred because it 586 is both shorter and the version used in the serialization 587 structures for cryptographic computation. Recipients MUST accept 588 both a zero-length byte string and a zero-length map encoded in a 589 byte string. 591 Wrapping the encoding with a byte string allows for the protected 592 map to be transported with a greater chance that it will not be 593 altered accidentally in transit. (Badly behaved intermediates 594 could decode and re-encode, but this will result in a failure to 595 verify unless the re-encoded byte string is identical to the 596 decoded byte string.) This avoids the problem of all parties 597 needing to be able to do a common canonical encoding of the map 598 for input to cyprtographic operations. 600 unprotected: Contains parameters about the current layer that are 601 not cryptographically protected. 603 Only header parameters that deal with the current layer are to be 604 placed at that layer. As an example of this, the header parameter 605 'content type' describes the content of the message being carried in 606 the message. As such, this header parameter is placed only in the 607 content layer and is not placed in the recipient or signature layers. 608 In principle, one should be able to process any given layer without 609 reference to any other layer. With the exception of the COSE_Sign 610 structure, the only data that needs to cross layers is the 611 cryptographic key. 613 The buckets are present in all of the security objects defined in 614 this document. The fields in order are the 'protected' bucket (as a 615 CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map' 616 type). The presence of both buckets is required. The header 617 parameters that go into the buckets come from the IANA "COSE Header 618 Parameters" registry (Section 11.1). Some header parameters are 619 defined in the next section. 621 Labels in each of the maps MUST be unique. When processing messages, 622 if a label appears multiple times, the message MUST be rejected as 623 malformed. Applications SHOULD verify that the same label does not 624 occur in both the protected and unprotected header parameters. If 625 the message is not rejected as malformed, attributes MUST be obtained 626 from the protected bucket, and only if not found are attributes 627 obtained from the unprotected bucket. 629 The following CDDL fragment represents the two header parameter 630 buckets. A group "Headers" is defined in CDDL that represents the 631 two buckets in which attributes are placed. This group is used to 632 provide these two fields consistently in all locations. A type is 633 also defined that represents the map of common header parameters. 635 Headers = ( 636 protected : empty_or_serialized_map, 637 unprotected : header_map 638 ) 640 header_map = { 641 Generic_Headers, 642 * label => values 643 } 645 empty_or_serialized_map = bstr .cbor header_map / bstr .size 0 647 3.1. Common COSE Header Parameters 649 This section defines a set of common header parameters. A summary of 650 these header parameters can be found in Table 3. This table should 651 be consulted to determine the value of label and the type of the 652 value. 654 The set of header parameters defined in this section are: 656 alg: This header parameter is used to indicate the algorithm used 657 for the security processing. This header parameter MUST be 658 authenticated where the ability to do so exists. This support is 659 provided by AEAD algorithms or construction (e.g. COSE_Sign and 660 COSE_Mac0). This authentication can be done either by placing the 661 header parameter in the protected header parameter bucket or as 662 part of the externally supplied data Section 4.3). The value is 663 taken from the "COSE Algorithms" registry (see [COSE.Algorithms]). 665 crit: This header parameter is used to indicate which protected 666 header parameters an application that is processing a message is 667 required to understand. Header parameters defined in this 668 document do not need to be included as they should be understood 669 by all implementations. When present, this the 'crit' header 670 parameter MUST be placed in the protected header parameter bucket. 671 The array MUST have at least one value in it. 673 Not all header parameter labels need to be included in the 'crit' 674 header parameter. The rules for deciding which header parameters 675 are placed in the array are: 677 * Integer labels in the range of 0 to 7 SHOULD be omitted. 679 * Integer labels in the range -1 to -128 can be omitted. 680 Algorithms can assign labels in this range where the ability to 681 process the content of the label is considered to be core to 682 implementing the algorithm. Algorithms can assign labels 683 outside of this range where the ability to process the content 684 of the label is not considered to be core, but needs to be 685 understood to correctly process this instance. Integer labels 686 in the range -129 to -65536 SHOULD be included as these would 687 be less common header parameters that might not be generally 688 supported. 690 * Labels for header parameters required for an application MAY be 691 omitted. Applications should have a statement if the label can 692 be omitted. 694 The header parameters indicated by 'crit' can be processed by 695 either the security library code or an application using a 696 security library; the only requirement is that the header 697 parameter is processed. If the 'crit' value list includes a label 698 for which the header parameter is not in the protected header 699 parameters bucket, this is a fatal error in processing the 700 message. 702 content type: This header parameter is used to indicate the content 703 type of the data in the payload or ciphertext fields. Integers 704 are from the "CoAP Content-Formats" IANA registry table 705 [COAP.Formats]. Text values following the syntax of "/" where and are 707 defined in Section 4.2 of [RFC6838]. Leading and trailing 708 whitespace is also omitted. Textual content values along with 709 parameters and subparameters can be located using the IANA "Media 710 Types" registry. Applications SHOULD provide this header 711 parameter if the content structure is potentially ambiguous. 713 kid: This header parameter identifies one piece of data that can be 714 used as input to find the needed cryptographic key. The value of 715 this header parameter can be matched against the 'kid' member in a 716 COSE_Key structure. Other methods of key distribution can define 717 an equivalent field to be matched. Applications MUST NOT assume 718 that 'kid' values are unique. There may be more than one key with 719 the same 'kid' value, so all of the keys associated with this 720 'kid' may need to be checked. The internal structure of 'kid' 721 values is not defined and cannot be relied on by applications. 722 Key identifier values are hints about which key to use. This is 723 not a security-critical field. For this reason, it can be placed 724 in the unprotected header parameters bucket. 726 IV: This header parameter holds the Initialization Vector (IV) 727 value. For some symmetric encryption algorithms, this may be 728 referred to as a nonce. The IV can be placed in the unprotected 729 bucket as modifying the IV will cause the decryption to yield 730 plaintext that is readily detectable as garbled. 732 Partial IV: This header parameter holds a part of the IV value. 733 When using the COSE_Encrypt0 structure, a portion of the IV can be 734 part of the context associated with the key (Context IV) while a 735 portion can be changed with each message (Partial IV). This field 736 is used to carry a value that causes the IV to be changed for each 737 message. The Partial IV can be placed in the unprotected bucket 738 as modifying the value will cause the decryption to yield 739 plaintext that is readily detectable as garbled. The 740 'Initialization Vector' and 'Partial Initialization Vector' header 741 parameters MUST NOT both be present in the same security layer. 743 The message IV is generated by the following steps: 745 1. Left-pad the Partial IV with zeros to the length of IV 746 (determined by the algorithm). 748 2. XOR the padded Partial IV with the context IV. 750 +=========+=======+========+=====================+==================+ 751 | Name | Label | Value | Value Registry | Description | 752 | | | Type | | | 753 +=========+=======+========+=====================+==================+ 754 | alg | 1 | int / | COSE Algorithms | Cryptographic | 755 | | | tstr | registry | algorithm to use | 756 +---------+-------+--------+---------------------+------------------+ 757 | crit | 2 | [+ | COSE Header | Critical header | 758 | | | label] | Parameters | parameters to be | 759 | | | | registry | understood | 760 +---------+-------+--------+---------------------+------------------+ 761 | content | 3 | tstr / | CoAP Content- | Content type of | 762 | type | | uint | Formats or Media | the payload | 763 | | | | Types registries | | 764 +---------+-------+--------+---------------------+------------------+ 765 | kid | 4 | bstr | | Key identifier | 766 +---------+-------+--------+---------------------+------------------+ 767 | IV | 5 | bstr | | Full | 768 | | | | | Initialization | 769 | | | | | Vector | 770 +---------+-------+--------+---------------------+------------------+ 771 | Partial | 6 | bstr | | Partial | 772 | IV | | | | Initialization | 773 | | | | | Vector | 774 +---------+-------+--------+---------------------+------------------+ 776 Table 3: Common Header Parameters 778 The CDDL fragment that represents the set of header parameters 779 defined in this section is given below. Each of the header 780 parameters is tagged as optional because they do not need to be in 781 every map; header parameters required in specific maps are discussed 782 above. 784 Generic_Headers = ( 785 ? 1 => int / tstr, ; algorithm identifier 786 ? 2 => [+label], ; criticality 787 ? 3 => tstr / int, ; content type 788 ? 4 => bstr, ; key identifier 789 ? 5 => bstr, ; IV 790 ? 6 => bstr ; Partial IV 791 ) 793 4. Signing Objects 795 COSE supports two different signature structures. COSE_Sign allows 796 for one or more signatures to be applied to the same content. 797 COSE_Sign1 is restricted to a single signer. The structures cannot 798 be converted between each other; as the signature computation 799 includes a parameter identifying which structure is being used, the 800 converted structure will fail signature validation. 802 4.1. Signing with One or More Signers 804 The COSE_Sign structure allows for one or more signatures to be 805 applied to a message payload. Header parameters relating to the 806 content and header parameters relating to the signature are carried 807 along with the signature itself. These header parameters may be 808 authenticated by the signature, or just present. An example of a 809 header parameter about the content is the content type header 810 parameter. An examples of a header parameter about the signature 811 would be the algorithm and key used to create the signature. 813 RFC 5652 indicates that: 815 | When more than one signature is present, the successful validation 816 | of one signature associated with a given signer is usually treated 817 | as a successful signature by that signer. However, there are some 818 | application environments where other rules are needed. An 819 | application that employs a rule other than one valid signature for 820 | each signer must specify those rules. Also, where simple matching 821 | of the signer identifier is not sufficient to determine whether 822 | the signatures were generated by the same signer, the application 823 | specification must describe how to determine which signatures were 824 | generated by the same signer. Support for different communities 825 | of recipients is the primary reason that signers choose to include 826 | more than one signature. 828 For example, the COSE_Sign structure might include signatures 829 generated with the Edwards-curve Digital Signature Algorithm (EdDSA) 830 [RFC8032] and with the Elliptic Curve Digital Signature Algorithm 831 (ECDSA) [DSS]. This allows recipients to verify the signature 832 associated with one algorithm or the other. More-detailed 833 information on multiple signature evaluations can be found in 834 [RFC5752]. 836 The signature structure can be encoded as either tagged or untagged 837 depending on the context it will be used in. A tagged COSE_Sign 838 structure is identified by the CBOR tag 98. The CDDL fragment that 839 represents this is: 841 COSE_Sign_Tagged = #6.98(COSE_Sign) 843 A COSE Signed Message is defined in two parts. The CBOR object that 844 carries the body and information about the body is called the 845 COSE_Sign structure. The CBOR object that carries the signature and 846 information about the signature is called the COSE_Signature 847 structure. Examples of COSE Signed Messages can be found in 848 Appendix C.1. 850 The COSE_Sign structure is a CBOR array. The fields of the array in 851 order are: 853 protected: This is as described in Section 3. 855 unprotected: This is as described in Section 3. 857 payload: This field contains the serialized content to be signed. 858 If the payload is not present in the message, the application is 859 required to supply the payload separately. The payload is wrapped 860 in a bstr to ensure that it is transported without changes. If 861 the payload is transported separately ("detached content"), then a 862 nil CBOR object is placed in this location, and it is the 863 responsibility of the application to ensure that it will be 864 transported without changes. 866 Note: When a signature with a message recovery algorithm is used 867 (Section 8.1), the maximum number of bytes that can be recovered 868 is the length of the original payload. The size of the encoded 869 payload is reduced by the number of bytes that will be recovered. 870 If all of the bytes of the original payload are consumed, then the 871 transmitted payload is encoded as a zero-length byte string rather 872 than as being absent. 874 signatures: This field is an array of signatures. Each signature is 875 represented as a COSE_Signature structure. 877 The CDDL fragment that represents the above text for COSE_Sign 878 follows. 880 COSE_Sign = [ 881 Headers, 882 payload : bstr / nil, 883 signatures : [+ COSE_Signature] 884 ] 886 The COSE_Signature structure is a CBOR array. The fields of the 887 array in order are: 889 protected: This is as described in Section 3. 891 unprotected: This is as described in Section 3. 893 signature: This field contains the computed signature value. The 894 type of the field is a bstr. Algorithms MUST specify padding if 895 the signature value is not a multiple of 8 bits. 897 The CDDL fragment that represents the above text for COSE_Signature 898 follows. 900 COSE_Signature = [ 901 Headers, 902 signature : bstr 903 ] 905 4.2. Signing with One Signer 907 The COSE_Sign1 signature structure is used when only one signature is 908 going to be placed on a message. The header parameters dealing with 909 the content and the signature are placed in the same pair of buckets 910 rather than having the separation of COSE_Sign. 912 The structure can be encoded as either tagged or untagged depending 913 on the context it will be used in. A tagged COSE_Sign1 structure is 914 identified by the CBOR tag 18. The CDDL fragment that represents 915 this is: 917 COSE_Sign1_Tagged = #6.18(COSE_Sign1) 919 The CBOR object that carries the body, the signature, and the 920 information about the body and signature is called the COSE_Sign1 921 structure. Examples of COSE_Sign1 messages can be found in 922 Appendix C.2. 924 The COSE_Sign1 structure is a CBOR array. The fields of the array in 925 order are: 927 protected: This is as described in Section 3. 929 unprotected: This is as described in Section 3. 931 payload: This is as described in Section 4.1. 933 signature: This field contains the computed signature value. The 934 type of the field is a bstr. 936 The CDDL fragment that represents the above text for COSE_Sign1 937 follows. 939 COSE_Sign1 = [ 940 Headers, 941 payload : bstr / nil, 942 signature : bstr 943 ] 945 4.3. Externally Supplied Data 947 One of the features offered in the COSE document is the ability for 948 applications to provide additional data to be authenticated, but that 949 is not carried as part of the COSE object. The primary reason for 950 supporting this can be seen by looking at the CoAP message structure 951 [RFC7252], where the facility exists for options to be carried before 952 the payload. Examples of data that can be placed in this location 953 would be the CoAP code or CoAP options. If the data is in the 954 headers of the CoAP message, then it is available for proxies to help 955 in performing its operations. For example, the Accept Option can be 956 used by a proxy to determine if an appropriate value is in the 957 proxy's cache. But the sender can cause a failure at the server if a 958 proxy, or an attacker, changes the set of accept values by including 959 the field in the externally supplied data. 961 This document describes the process for using a byte array of 962 externally supplied authenticated data; the method of constructing 963 the byte array is a function of the application. Applications that 964 use this feature need to define how the externally supplied 965 authenticated data is to be constructed. Such a construction needs 966 to take into account the following issues: 968 * If multiple items are included, applications need to ensure that 969 the same byte string cannot be produced if there are different 970 inputs. This would occur by concatenating the text strings 'AB' 971 and 'CDE' or by concatenating the text strings 'ABC' and 'DE'. 972 This is usually addressed by making fields a fixed width and/or 973 encoding the length of the field as part of the output. Using 974 options from CoAP [RFC7252] as an example, these fields use a TLV 975 structure so they can be concatenated without any problems. 977 * If multiple items are included, an order for the items needs to be 978 defined. Using options from CoAP as an example, an application 979 could state that the fields are to be ordered by the option 980 number. 982 * Applications need to ensure that the byte string is going to be 983 the same on both sides. Using options from CoAP might give a 984 problem if the same relative numbering is kept. An intermediate 985 node could insert or remove an option, changing how the relative 986 number is done. An application would need to specify that the 987 relative number must be re-encoded to be relative only to the 988 options that are in the external data. 990 4.4. Signing and Verification Process 992 In order to create a signature, a well-defined byte string is needed. 993 The Sig_structure is used to create the canonical form. This signing 994 and verification process takes in the body information (COSE_Sign or 995 COSE_Sign1), the signer information (COSE_Signature), and the 996 application data (external source). A Sig_structure is a CBOR array. 997 The fields of the Sig_structure in order are: 999 1. A context text string identifying the context of the signature. 1000 The context text string is: 1002 "Signature" for signatures using the COSE_Signature structure. 1004 "Signature1" for signatures using the COSE_Sign1 structure. 1006 2. The protected attributes from the body structure encoded in a 1007 bstr type. If there are no protected attributes, a zero-length 1008 byte string is used. 1010 3. The protected attributes from the signer structure encoded in a 1011 bstr type. If there are no protected attributes, a zero-length 1012 byte string is used. This field is omitted for the COSE_Sign1 1013 signature structure. 1015 4. The externally supplied data from the application encoded in a 1016 bstr type. If this field is not supplied, it defaults to a zero- 1017 length byte string. (See Section 4.3 for application guidance on 1018 constructing this field.) 1020 5. The payload to be signed encoded in a bstr type. The payload is 1021 placed here independent of how it is transported. 1023 The CDDL fragment that describes the above text is: 1025 Sig_structure = [ 1026 context : "Signature" / "Signature1", 1027 body_protected : empty_or_serialized_map, 1028 ? sign_protected : empty_or_serialized_map, 1029 external_aad : bstr, 1030 payload : bstr 1031 ] 1033 How to compute a signature: 1035 1. Create a Sig_structure and populate it with the appropriate 1036 fields. 1038 2. Create the value ToBeSigned by encoding the Sig_structure to a 1039 byte string, using the encoding described in Section 9. 1041 3. Call the signature creation algorithm passing in K (the key to 1042 sign with), alg (the algorithm to sign with), and ToBeSigned (the 1043 value to sign). 1045 4. Place the resulting signature value in the correct location. 1046 This is the 'signature' field of the COSE_Signature or COSE_Sign1 1047 structure. 1049 The steps for verifying a signature are: 1051 1. Create a Sig_structure and populate it with the appropriate 1052 fields. 1054 2. Create the value ToBeSigned by encoding the Sig_structure to a 1055 byte string, using the encoding described in Section 9. 1057 3. Call the signature verification algorithm passing in K (the key 1058 to verify with), alg (the algorithm used sign with), ToBeSigned 1059 (the value to sign), and sig (the signature to be verified). 1061 In addition to performing the signature verification, the application 1062 performs the appropriate checks to ensure that the key is correctly 1063 paired with the signing identity and that the signing identity is 1064 authorized before performing actions. 1066 5. Encryption Objects 1068 COSE supports two different encryption structures. COSE_Encrypt0 is 1069 used when a recipient structure is not needed because the key to be 1070 used is known implicitly. COSE_Encrypt is used the rest of the time. 1071 This includes cases where there are multiple recipients or a 1072 recipient algorithm other than direct (i.e. pre-shared secret) is 1073 used. 1075 5.1. Enveloped COSE Structure 1077 The enveloped structure allows for one or more recipients of a 1078 message. There are provisions for header parameters about the 1079 content and header parameters about the recipient information to be 1080 carried in the message. The protected header parameters associated 1081 with the content are authenticated by the content encryption 1082 algorithm. The protected header parameters associated with the 1083 recipient are authenticated by the recipient algorithm (when the 1084 algorithm supports it). Examples of header parameters about the 1085 content are the type of the content and the content encryption 1086 algorithm. Examples of header parameters about the recipient are the 1087 recipient's key identifier and the recipient's encryption algorithm. 1089 The same techniques and nearly the same structure are used for 1090 encrypting both the plaintext and the keys. This is different from 1091 the approach used by both "Cryptographic Message Syntax (CMS)" 1092 [RFC5652] and "JSON Web Encryption (JWE)" [RFC7516] where different 1093 structures are used for the content layer and for the recipient 1094 layer. Two structures are defined: COSE_Encrypt to hold the 1095 encrypted content and COSE_recipient to hold the encrypted keys for 1096 recipients. Examples of encrypted messages can be found in 1097 Appendix C.3. 1099 The COSE_Encrypt structure can be encoded as either tagged or 1100 untagged depending on the context it will be used in. A tagged 1101 COSE_Encrypt structure is identified by the CBOR tag 96. The CDDL 1102 fragment that represents this is: 1104 COSE_Encrypt_Tagged = #6.96(COSE_Encrypt) 1106 The COSE_Encrypt structure is a CBOR array. The fields of the array 1107 in order are: 1109 protected: This is as described in Section 3. 1111 unprotected: This is as described in Section 3. 1113 ciphertext: This field contains the ciphertext encoded as a bstr. 1115 If the ciphertext is to be transported independently of the 1116 control information about the encryption process (i.e., detached 1117 content), then the field is encoded as a nil value. 1119 recipients: This field contains an array of recipient information 1120 structures. The type for the recipient information structure is a 1121 COSE_recipient. 1123 The CDDL fragment that corresponds to the above text is: 1125 COSE_Encrypt = [ 1126 Headers, 1127 ciphertext : bstr / nil, 1128 recipients : [+COSE_recipient] 1129 ] 1131 The COSE_recipient structure is a CBOR array. The fields of the 1132 array in order are: 1134 protected: This is as described in Section 3. 1136 unprotected: This is as described in Section 3. 1138 ciphertext: This field contains the encrypted key encoded as a bstr. 1139 All encoded keys are symmetric keys; the binary value of the key 1140 is the content. If there is not an encrypted key, then this field 1141 is encoded as a nil value. 1143 recipients: This field contains an array of recipient information 1144 structures. The type for the recipient information structure is a 1145 COSE_recipient (an example of this can be found in Appendix B). 1146 If there are no recipient information structures, this element is 1147 absent. 1149 The CDDL fragment that corresponds to the above text for 1150 COSE_recipient is: 1152 COSE_recipient = [ 1153 Headers, 1154 ciphertext : bstr / nil, 1155 ? recipients : [+COSE_recipient] 1156 ] 1158 5.1.1. Content Key Distribution Methods 1160 An encrypted message consists of an encrypted content and an 1161 encrypted CEK for one or more recipients. The CEK is encrypted for 1162 each recipient, using a key specific to that recipient. The details 1163 of this encryption depend on which class the recipient algorithm 1164 falls into. Specific details on each of the classes can be found in 1165 Section 8.5. A short summary of the five content key distribution 1166 methods is: 1168 direct: The CEK is the same as the identified previously distributed 1169 symmetric key or is derived from a previously distributed secret. 1170 No CEK is transported in the message. 1172 symmetric key-encryption keys (KEK): The CEK is encrypted using a 1173 previously distributed symmetric KEK. Also known as key wrap. 1175 key agreement: The recipient's public key and a sender's private key 1176 are used to generate a pairwise secret, a Key Derivation Function 1177 (KDF) is applied to derive a key, and then the CEK is either the 1178 derived key or encrypted by the derived key. 1180 key transport: The CEK is encrypted with the recipient's public key. 1182 passwords: The CEK is encrypted in a KEK that is derived from a 1183 password. As of when this document was published, no password 1184 algorithms have been defined. 1186 5.2. Single Recipient Encrypted 1188 The COSE_Encrypt0 encrypted structure does not have the ability to 1189 specify recipients of the message. The structure assumes that the 1190 recipient of the object will already know the identity of the key to 1191 be used in order to decrypt the message. If a key needs to be 1192 identified to the recipient, the enveloped structure ought to be 1193 used. 1195 Examples of encrypted messages can be found in Appendix C.3. 1197 The COSE_Encrypt0 structure can be encoded as either tagged or 1198 untagged depending on the context it will be used in. A tagged 1199 COSE_Encrypt0 structure is identified by the CBOR tag 16. The CDDL 1200 fragment that represents this is: 1202 COSE_Encrypt0_Tagged = #6.16(COSE_Encrypt0) 1204 The COSE_Encrypt0 structure is a CBOR array. The fields of the array 1205 in order are: 1207 protected: This is as described in Section 3. 1209 unprotected: This is as described in Section 3. 1211 ciphertext: This is as described in Section 5.1. 1213 The CDDL fragment for COSE_Encrypt0 that corresponds to the above 1214 text is: 1216 COSE_Encrypt0 = [ 1217 Headers, 1218 ciphertext : bstr / nil, 1219 ] 1221 5.3. How to Encrypt and Decrypt for AEAD Algorithms 1223 The encryption algorithm for AEAD algorithms is fairly simple. The 1224 first step is to create a consistent byte string for the 1225 authenticated data structure. For this purpose, we use an 1226 Enc_structure. The Enc_structure is a CBOR array. The fields of the 1227 Enc_structure in order are: 1229 1. A context text string identifying the context of the 1230 authenticated data structure. The context text string is: 1232 "Encrypt0" for the content encryption of a COSE_Encrypt0 data 1233 structure. 1235 "Encrypt" for the first layer of a COSE_Encrypt data structure 1236 (i.e., for content encryption). 1238 "Enc_Recipient" for a recipient encoding to be placed in an 1239 COSE_Encrypt data structure. 1241 "Mac_Recipient" for a recipient encoding to be placed in a 1242 MACed message structure. 1244 "Rec_Recipient" for a recipient encoding to be placed in a 1245 recipient structure. 1247 2. The protected attributes from the body structure encoded in a 1248 bstr type. If there are no protected attributes, a zero-length 1249 byte string is used. 1251 3. The externally supplied data from the application encoded in a 1252 bstr type. If this field is not supplied, it defaults to a zero- 1253 length byte string. (See Section 4.3 for application guidance on 1254 constructing this field.) 1256 The CDDL fragment that describes the above text is: 1258 Enc_structure = [ 1259 context : "Encrypt" / "Encrypt0" / "Enc_Recipient" / 1260 "Mac_Recipient" / "Rec_Recipient", 1261 protected : empty_or_serialized_map, 1262 external_aad : bstr 1263 ] 1265 How to encrypt a message: 1267 1. Create an Enc_structure and populate it with the appropriate 1268 fields. 1270 2. Encode the Enc_structure to a byte string (Additional 1271 Authenticated Data (AAD)), using the encoding described in 1272 Section 9. 1274 3. Determine the encryption key (K). This step is dependent on the 1275 class of recipient algorithm being used. For: 1277 No Recipients: The key to be used is determined by the algorithm 1278 and key at the current layer. Examples are key transport keys 1279 (Section 8.5.3), key wrap keys (Section 8.5.2), or pre-shared 1280 secrets. 1282 Direct Encryption and Direct Key Agreement: The key is 1283 determined by the key and algorithm in the recipient 1284 structure. The encryption algorithm and size of the key to be 1285 used are inputs into the KDF used for the recipient. (For 1286 direct, the KDF can be thought of as the identity operation.) 1287 Examples of these algorithms are found in Sections 6.1.2 and 1288 6.3 of [I-D.ietf-cose-rfc8152bis-algs]. 1290 Other: The key is randomly or pseudo-randomly generated. 1292 4. Call the encryption algorithm with K (the encryption key), P (the 1293 plaintext), and AAD. Place the returned ciphertext into the 1294 'ciphertext' field of the structure. 1296 5. For recipients of the message, recursively perform the encryption 1297 algorithm for that recipient, using K (the encryption key) as the 1298 plaintext. 1300 How to decrypt a message: 1302 1. Create an Enc_structure and populate it with the appropriate 1303 fields. 1305 2. Encode the Enc_structure to a byte string (AAD), using the 1306 encoding described in Section 9. 1308 3. Determine the decryption key. This step is dependent on the 1309 class of recipient algorithm being used. For: 1311 No Recipients: The key to be used is determined by the algorithm 1312 and key at the current layer. Examples are key transport keys 1313 (Section 8.5.3), key wrap keys (Section 8.5.2), or pre-shared 1314 secrets. 1316 Direct Encryption and Direct Key Agreement: The key is 1317 determined by the key and algorithm in the recipient 1318 structure. The encryption algorithm and size of the key to be 1319 used are inputs into the KDF used for the recipient. (For 1320 direct, the KDF can be thought of as the identity operation.) 1322 Other: The key is determined by decoding and decrypting one of 1323 the recipient structures. 1325 4. Call the decryption algorithm with K (the decryption key to use), 1326 C (the ciphertext), and AAD. 1328 5.4. How to Encrypt and Decrypt for AE Algorithms 1330 How to encrypt a message: 1332 1. Verify that the 'protected' field is empty. 1334 2. Verify that there was no external additional authenticated data 1335 supplied for this operation. 1337 3. Determine the encryption key. This step is dependent on the 1338 class of recipient algorithm being used. For: 1340 No Recipients: The key to be used is determined by the algorithm 1341 and key at the current layer. Examples are key transport keys 1342 (Section 8.5.3), key wrap keys (Section 8.5.2), or pre-shared 1343 secrets. 1345 Direct Encryption and Direct Key Agreement: The key is 1346 determined by the key and algorithm in the recipient 1347 structure. The encryption algorithm and size of the key to be 1348 used are inputs into the KDF used for the recipient. (For 1349 direct, the KDF can be thought of as the identity operation.) 1350 Examples of these algorithms are found in Sections 6.1.2 and 1351 6.3 of [I-D.ietf-cose-rfc8152bis-algs]. 1353 Other: The key is randomly generated. 1355 4. Call the encryption algorithm with K (the encryption key to use) 1356 and P (the plaintext). Place the returned ciphertext into the 1357 'ciphertext' field of the structure. 1359 5. For recipients of the message, recursively perform the encryption 1360 algorithm for that recipient, using K (the encryption key) as the 1361 plaintext. 1363 How to decrypt a message: 1365 1. Verify that the 'protected' field is empty. 1367 2. Verify that there was no external additional authenticated data 1368 supplied for this operation. 1370 3. Determine the decryption key. This step is dependent on the 1371 class of recipient algorithm being used. For: 1373 No Recipients: The key to be used is determined by the algorithm 1374 and key at the current layer. Examples are key transport keys 1375 (Section 8.5.3), key wrap keys (Section 8.5.2), or pre-shared 1376 secrets. 1378 Direct Encryption and Direct Key Agreement: The key is 1379 determined by the key and algorithm in the recipient 1380 structure. The encryption algorithm and size of the key to be 1381 used are inputs into the KDF used for the recipient. (For 1382 direct, the KDF can be thought of as the identity operation.) 1383 Examples of these algorithms are found in Sections 6.1.2 and 1384 6.3 of [I-D.ietf-cose-rfc8152bis-algs]. 1386 Other: The key is determined by decoding and decrypting one of 1387 the recipient structures. 1389 4. Call the decryption algorithm with K (the decryption key to use) 1390 and C (the ciphertext). 1392 6. MAC Objects 1394 COSE supports two different MAC structures. COSE_MAC0 is used when a 1395 recipient structure is not needed because the key to be used is 1396 implicitly known. COSE_MAC is used for all other cases. These 1397 include a requirement for multiple recipients, the key being unknown, 1398 or a recipient algorithm of other than direct. 1400 In this section, we describe the structure and methods to be used 1401 when doing MAC authentication in COSE. This document allows for the 1402 use of all of the same classes of recipient algorithms as are allowed 1403 for encryption. 1405 When using MAC operations, there are two modes in which they can be 1406 used. The first is just a check that the content has not been 1407 changed since the MAC was computed. Any class of recipient algorithm 1408 can be used for this purpose. The second mode is to both check that 1409 the content has not been changed since the MAC was computed and to 1410 use the recipient algorithm to verify who sent it. The classes of 1411 recipient algorithms that support this are those that use a pre- 1412 shared secret or do static-static (SS) key agreement (without the key 1413 wrap step). In both of these cases, the entity that created and sent 1414 the message MAC can be validated. (This knowledge of the sender 1415 assumes that there are only two parties involved and that you did not 1416 send the message to yourself.) The origination property can be 1417 obtained with both of the MAC message structures. 1419 6.1. MACed Message with Recipients 1421 The multiple recipient MACed message uses two structures: the 1422 COSE_Mac structure defined in this section for carrying the body and 1423 the COSE_recipient structure (Section 5.1) to hold the key used for 1424 the MAC computation. Examples of MACed messages can be found in 1425 Appendix C.5. 1427 The MAC structure can be encoded as either tagged or untagged 1428 depending on the context it will be used in. A tagged COSE_Mac 1429 structure is identified by the CBOR tag 97. The CDDL fragment that 1430 represents this is: 1432 COSE_Mac_Tagged = #6.97(COSE_Mac) 1434 The COSE_Mac structure is a CBOR array. The fields of the array in 1435 order are: 1437 protected: This is as described in Section 3. 1439 unprotected: This is as described in Section 3. 1441 payload: This field contains the serialized content to be MACed. If 1442 the payload is not present in the message, the application is 1443 required to supply the payload separately. The payload is wrapped 1444 in a bstr to ensure that it is transported without changes. If 1445 the payload is transported separately (i.e., detached content), 1446 then a nil CBOR value is placed in this location, and it is the 1447 responsibility of the application to ensure that it will be 1448 transported without changes. 1450 tag: This field contains the MAC value. 1452 recipients: This is as described in Section 5.1. 1454 The CDDL fragment that represents the above text for COSE_Mac 1455 follows. 1457 COSE_Mac = [ 1458 Headers, 1459 payload : bstr / nil, 1460 tag : bstr, 1461 recipients :[+COSE_recipient] 1462 ] 1464 6.2. MACed Messages with Implicit Key 1466 In this section, we describe the structure and methods to be used 1467 when doing MAC authentication for those cases where the recipient is 1468 implicitly known. 1470 The MACed message uses the COSE_Mac0 structure defined in this 1471 section for carrying the body. Examples of MACed messages with an 1472 implicit key can be found in Appendix C.6. 1474 The MAC structure can be encoded as either tagged or untagged 1475 depending on the context it will be used in. A tagged COSE_Mac0 1476 structure is identified by the CBOR tag 17. The CDDL fragment that 1477 represents this is: 1479 COSE_Mac0_Tagged = #6.17(COSE_Mac0) 1481 The COSE_Mac0 structure is a CBOR array. The fields of the array in 1482 order are: 1484 protected: This is as described in Section 3. 1486 unprotected: This is as described in Section 3. 1488 payload: This is as described in Section 6.1. 1490 tag: This field contains the MAC value. 1492 The CDDL fragment that corresponds to the above text is: 1494 COSE_Mac0 = [ 1495 Headers, 1496 payload : bstr / nil, 1497 tag : bstr, 1498 ] 1500 6.3. How to Compute and Verify a MAC 1502 In order to get a consistent encoding of the data to be 1503 authenticated, the MAC_structure is used to have a canonical form. 1504 The MAC_structure is a CBOR array. The fields of the MAC_structure 1505 in order are: 1507 1. A context text string that identifies the structure that is being 1508 encoded. This context text string is "MAC" for the COSE_Mac 1509 structure. This context text string is "MAC0" for the COSE_Mac0 1510 structure. 1512 2. The protected attributes from the COSE_MAC structure. If there 1513 are no protected attributes, a zero-length bstr is used. 1515 3. The externally supplied data from the application encoded as a 1516 bstr type. If this field is not supplied, it defaults to a zero- 1517 length byte string. (See Section 4.3 for application guidance on 1518 constructing this field.) 1520 4. The payload to be MACed encoded in a bstr type. The payload is 1521 placed here independent of how it is transported. 1523 The CDDL fragment that corresponds to the above text is: 1525 MAC_structure = [ 1526 context : "MAC" / "MAC0", 1527 protected : empty_or_serialized_map, 1528 external_aad : bstr, 1529 payload : bstr 1530 ] 1532 The steps to compute a MAC are: 1534 1. Create a MAC_structure and populate it with the appropriate 1535 fields. 1537 2. Create the value ToBeMaced by encoding the MAC_structure to a 1538 byte string, using the encoding described in Section 9. 1540 3. Call the MAC creation algorithm passing in K (the key to use), 1541 alg (the algorithm to MAC with), and ToBeMaced (the value to 1542 compute the MAC on). 1544 4. Place the resulting MAC in the 'tag' field of the COSE_Mac or 1545 COSE_Mac0 structure. 1547 5. For COSE_Mac structures, encrypt and encode the MAC key for each 1548 recipient of the message. 1550 The steps to verify a MAC are: 1552 1. Create a MAC_structure and populate it with the appropriate 1553 fields. 1555 2. Create the value ToBeMaced by encoding the MAC_structure to a 1556 byte string, using the encoding described in Section 9. 1558 3. For COSE_Mac structures, obtain the cryptographic key from one of 1559 the recipients of the message. 1561 4. Call the MAC creation algorithm passing in K (the key to use), 1562 alg (the algorithm to MAC with), and ToBeMaced (the value to 1563 compute the MAC on). 1565 5. Compare the MAC value to the 'tag' field of the COSE_Mac or 1566 COSE_Mac0 structure. 1568 7. Key Objects 1570 A COSE Key structure is built on a CBOR map. The set of common 1571 parameters that can appear in a COSE Key can be found in the IANA 1572 "COSE Key Common Parameters" registry (Section 11.2). Additional 1573 parameters defined for specific key types can be found in the IANA 1574 "COSE Key Type Parameters" registry ([COSE.KeyParameters]). 1576 A COSE Key Set uses a CBOR array object as its underlying type. The 1577 values of the array elements are COSE Keys. A COSE Key Set MUST have 1578 at least one element in the array. Examples of COSE Key Sets can be 1579 found in Appendix C.7. 1581 Each element in a COSE Key Set MUST be processed independently. If 1582 one element in a COSE Key Set is either malformed or uses a key that 1583 is not understood by an application, that key is ignored and the 1584 other keys are processed normally. 1586 The element "kty" is a required element in a COSE_Key map. 1588 The CDDL grammar describing COSE_Key and COSE_KeySet is: 1590 COSE_Key = { 1591 1 => tstr / int, ; kty 1592 ? 2 => bstr, ; kid 1593 ? 3 => tstr / int, ; alg 1594 ? 4 => [+ (tstr / int) ], ; key_ops 1595 ? 5 => bstr, ; Base IV 1596 * label => values 1597 } 1599 COSE_KeySet = [+COSE_Key] 1601 7.1. COSE Key Common Parameters 1603 This document defines a set of common parameters for a COSE Key 1604 object. Table 4 provides a summary of the parameters defined in this 1605 section. There are also parameters that are defined for specific key 1606 types. Key-type-specific parameters can be found in 1607 [I-D.ietf-cose-rfc8152bis-algs]. 1609 +=========+=======+========+============+====================+ 1610 | Name | Label | CBOR | Value | Description | 1611 | | | Type | Registry | | 1612 +=========+=======+========+============+====================+ 1613 | kty | 1 | tstr / | COSE Key | Identification of | 1614 | | | int | Types | the key type | 1615 +---------+-------+--------+------------+--------------------+ 1616 | kid | 2 | bstr | | Key identification | 1617 | | | | | value -- match to | 1618 | | | | | kid in message | 1619 +---------+-------+--------+------------+--------------------+ 1620 | alg | 3 | tstr / | COSE | Key usage | 1621 | | | int | Algorithms | restriction to | 1622 | | | | | this algorithm | 1623 +---------+-------+--------+------------+--------------------+ 1624 | key_ops | 4 | [+ | | Restrict set of | 1625 | | | (tstr/ | | permissible | 1626 | | | int)] | | operations | 1627 +---------+-------+--------+------------+--------------------+ 1628 | Base IV | 5 | bstr | | Base IV to be xor- | 1629 | | | | | ed with Partial | 1630 | | | | | IVs | 1631 +---------+-------+--------+------------+--------------------+ 1633 Table 4: Key Map Labels 1635 kty: This parameter is used to identify the family of keys for this 1636 structure and, thus, the set of key-type-specific parameters to be 1637 found. The set of values defined in this document can be found in 1638 [COSE.KeyTypes]. This parameter MUST be present in a key object. 1639 Implementations MUST verify that the key type is appropriate for 1640 the algorithm being processed. The key type MUST be included as 1641 part of the trust decision process. 1643 alg: This parameter is used to restrict the algorithm that is used 1644 with the key. If this parameter is present in the key structure, 1645 the application MUST verify that this algorithm matches the 1646 algorithm for which the key is being used. If the algorithms do 1647 not match, then this key object MUST NOT be used to perform the 1648 cryptographic operation. Note that the same key can be in a 1649 different key structure with a different or no algorithm 1650 specified; however, this is considered to be a poor security 1651 practice. 1653 kid: This parameter is used to give an identifier for a key. The 1654 identifier is not structured and can be anything from a user- 1655 provided byte string to a value computed on the public portion of 1656 the key. This field is intended for matching against a 'kid' 1657 parameter in a message in order to filter down the set of keys 1658 that need to be checked. The value of the identifier is not a 1659 unique value and can occur in other key objects, even for 1660 different keys. 1662 key_ops: This parameter is defined to restrict the set of operations 1663 that a key is to be used for. The value of the field is an array 1664 of values from Table 5. Algorithms define the values of key ops 1665 that are permitted to appear and are required for specific 1666 operations. The set of values matches that in [RFC7517] and 1667 [W3C.WebCrypto]. 1669 Base IV: This parameter is defined to carry the base portion of an 1670 IV. It is designed to be used with the Partial IV header 1671 parameter defined in Section 3.1. This field provides the ability 1672 to associate a Base IV with a key that is then modified on a per 1673 message basis with the Partial IV. 1675 Extreme care needs to be taken when using a Base IV in an 1676 application. Many encryption algorithms lose security if the same 1677 IV is used twice. 1679 If different keys are derived for each sender, starting at the 1680 same Base IV is likely to satisfy this condition. If the same key 1681 is used for multiple senders, then the application needs to 1682 provide for a method of dividing the IV space up between the 1683 senders. This could be done by providing a different base point 1684 to start from or a different Partial IV to start with and 1685 restricting the number of messages to be sent before rekeying. 1687 +=========+=======+==============================================+ 1688 | Name | Value | Description | 1689 +=========+=======+==============================================+ 1690 | sign | 1 | The key is used to create signatures. | 1691 | | | Requires private key fields. | 1692 +---------+-------+----------------------------------------------+ 1693 | verify | 2 | The key is used for verification of | 1694 | | | signatures. | 1695 +---------+-------+----------------------------------------------+ 1696 | encrypt | 3 | The key is used for key transport | 1697 | | | encryption. | 1698 +---------+-------+----------------------------------------------+ 1699 | decrypt | 4 | The key is used for key transport | 1700 | | | decryption. Requires private key fields. | 1701 +---------+-------+----------------------------------------------+ 1702 | wrap | 5 | The key is used for key wrap encryption. | 1703 | key | | | 1704 +---------+-------+----------------------------------------------+ 1705 | unwrap | 6 | The key is used for key wrap decryption. | 1706 | key | | Requires private key fields. | 1707 +---------+-------+----------------------------------------------+ 1708 | derive | 7 | The key is used for deriving keys. Requires | 1709 | key | | private key fields. | 1710 +---------+-------+----------------------------------------------+ 1711 | derive | 8 | The key is used for deriving bits not to be | 1712 | bits | | used as a key. Requires private key fields. | 1713 +---------+-------+----------------------------------------------+ 1714 | MAC | 9 | The key is used for creating MACs. | 1715 | create | | | 1716 +---------+-------+----------------------------------------------+ 1717 | MAC | 10 | The key is used for validating MACs. | 1718 | verify | | | 1719 +---------+-------+----------------------------------------------+ 1721 Table 5: Key Operation Values 1723 8. Taxonomy of Algorithms used by COSE 1725 In this section, a taxonomy of the different algorithm types that can 1726 be used in COSE is laid out. This taxonomy should not be considered 1727 to be exhaustive. New algorithms will be created which will not fit 1728 into this taxonomy. 1730 8.1. Signature Algorithms 1732 Signature algorithms provide data origination and data integrity 1733 services. Data origination provides the ability to infer who 1734 originated the data based on who signed the data. Data integrity 1735 provides the ability to verify that the data has not been modified 1736 since it was signed. 1738 There are two signature algorithm schemes. The first is signature 1739 with appendix. In this scheme, the message content is processed and 1740 a signature is produced; the signature is called the appendix. This 1741 is the scheme used by algorithms such as ECDSA and the RSA 1742 Probabilistic Signature Scheme (RSASSA-PSS). (In fact, the SSA in 1743 RSASSA-PSS stands for Signature Scheme with Appendix.) 1745 The signature functions for this scheme are: 1747 signature = Sign(message content, key) 1749 valid = Verification(message content, key, signature) 1751 The second scheme is signature with message recovery (an example of 1752 such an algorithm is [PVSig]). In this scheme, the message content 1753 is processed, but part of it is included in the signature. Moving 1754 bytes of the message content into the signature allows for smaller 1755 signatures; the signature size is still potentially large, but the 1756 message content has shrunk. This has implications for systems 1757 implementing these algorithms and for applications that use them. 1758 The first is that the message content is not fully available until 1759 after a signature has been validated. Until that point, the part of 1760 the message contained inside of the signature is unrecoverable. The 1761 second is that the security analysis of the strength of the signature 1762 is very much based on the structure of the message content. Messages 1763 that are highly predictable require additional randomness to be 1764 supplied as part of the signature process. In the worst case, it 1765 becomes the same as doing a signature with appendix. Finally, in the 1766 event that multiple signatures are applied to a message, all of the 1767 signature algorithms are going to be required to consume the same 1768 number of bytes of message content. This means that the mixing of 1769 the different schemes in a single message is not supported, and if a 1770 recovery signature scheme is used, then the same amount of content 1771 needs to be consumed by all of the signatures. 1773 The signature functions for this scheme are: 1775 signature, message sent = Sign(message content, key) 1777 valid, message content = Verification(message sent, key, signature) 1778 Signature algorithms are used with the COSE_Signature and COSE_Sign1 1779 structures. At this time, only signatures with appendixes are 1780 defined for use with COSE; however, considerable interest has been 1781 expressed in using a signature with message recovery algorithm due to 1782 the effective size reduction that is possible. Implementations will 1783 need to keep this in mind for later possible integration. 1785 8.2. Message Authentication Code (MAC) Algorithms 1787 Message Authentication Codes (MACs) provide data authentication and 1788 integrity protection. They provide either no or very limited data 1789 origination. A MAC, for example, cannot be used to prove the 1790 identity of the sender to a third party. 1792 MACs use the same scheme as signature with appendix algorithms. The 1793 message content is processed and an authentication code is produced. 1794 The authentication code is frequently called a tag. 1796 The MAC functions are: 1798 tag = MAC_Create(message content, key) 1800 valid = MAC_Verify(message content, key, tag) 1802 MAC algorithms can be based on either a block cipher algorithm (i.e., 1803 AES-MAC) or a hash algorithm (i.e., a Hash-based Message 1804 Authentication Code (HMAC)). [I-D.ietf-cose-rfc8152bis-algs] defines 1805 a MAC algorithm using each of these constructions. 1807 MAC algorithms are used in the COSE_Mac and COSE_Mac0 structures. 1809 8.3. Content Encryption Algorithms 1811 Content encryption algorithms provide data confidentiality for 1812 potentially large blocks of data using a symmetric key. They provide 1813 integrity on the data that was encrypted; however, they provide 1814 either no or very limited data origination. (One cannot, for 1815 example, be used to prove the identity of the sender to a third 1816 party.) The ability to provide data origination is linked to how the 1817 CEK is obtained. 1819 COSE restricts the set of legal content encryption algorithms to 1820 those that support authentication both of the content and additional 1821 data. The encryption process will generate some type of 1822 authentication value, but that value may be either explicit or 1823 implicit in terms of the algorithm definition. For simplicity's 1824 sake, the authentication code will normally be defined as being 1825 appended to the ciphertext stream. The encryption functions are: 1827 ciphertext = Encrypt(message content, key, additional data) 1829 valid, message content = Decrypt(ciphertext, key, additional data) 1831 Most AEAD algorithms are logically defined as returning the message 1832 content only if the decryption is valid. Many but not all 1833 implementations will follow this convention. The message content 1834 MUST NOT be used if the decryption does not validate. 1836 These algorithms are used in COSE_Encrypt and COSE_Encrypt0. 1838 8.4. Key Derivation Functions (KDFs) 1840 KDFs are used to take some secret value and generate a different one. 1841 The secret value comes in three flavors: 1843 * Secrets that are uniformly random: This is the type of secret that 1844 is created by a good random number generator. 1846 * Secrets that are not uniformly random: This is type of secret that 1847 is created by operations like key agreement. 1849 * Secrets that are not random: This is the type of secret that 1850 people generate for things like passwords. 1852 General KDFs work well with the first type of secret, can do 1853 reasonably well with the second type of secret, and generally do 1854 poorly with the last type of secret. Functions like Argon2 1855 [I-D.irtf-cfrg-argon2] need to be used for non-random secrets. 1857 The same KDF can be set up to deal with the first two types of 1858 secrets in a different way. The KDF defined in section 5.1 of 1859 [I-D.ietf-cose-rfc8152bis-algs] is such a function. This is 1860 reflected in the set of algorithms defined around the HMAC-based 1861 Extract-and-Expand Key Derivation Function (HKDF). 1863 When using KDFs, one component that is included is context 1864 information. Context information is used to allow for different 1865 keying information to be derived from the same secret. The use of 1866 context-based keying material is considered to be a good security 1867 practice. 1869 8.5. Content Key Distribution Methods 1871 Content key distribution methods (recipient algorithms) can be 1872 defined into a number of different classes. COSE has the ability to 1873 support many classes of recipient algorithms. In this section, a 1874 number of classes are listed. The names of the recipient algorithm 1875 classes used here are the same as those defined in [RFC7516]. Other 1876 specifications use different terms for the recipient algorithm 1877 classes or do not support some of the recipient algorithm classes. 1879 8.5.1. Direct Encryption 1881 The direct encryption class algorithms share a secret between the 1882 sender and the recipient that is used either directly or after 1883 manipulation as the CEK. When direct encryption mode is used, it 1884 MUST be the only mode used on the message. 1886 The COSE_Recipient structure for the recipient is organized as 1887 follows: 1889 * The 'protected' field MUST be a zero-length byte string unless it 1890 is used in the computation of the content key. 1892 * The 'alg' header parameter MUST be present. 1894 * A header parameter identifying the shared secret SHOULD be 1895 present. 1897 * The 'ciphertext' field MUST be a zero-length byte string. 1899 * The 'recipients' field MUST be absent. 1901 8.5.2. Key Wrap 1903 In key wrap mode, the CEK is randomly generated and that key is then 1904 encrypted by a shared secret between the sender and the recipient. 1905 All of the currently defined key wrap algorithms for COSE are AE 1906 algorithms. Key wrap mode is considered to be superior to direct 1907 encryption if the system has any capability for doing random key 1908 generation. This is because the shared key is used to wrap random 1909 data rather than data that has some degree of organization and may in 1910 fact be repeating the same content. The use of key wrap loses the 1911 weak data origination that is provided by the direct encryption 1912 algorithms. 1914 The COSE_Recipient structure for the recipient is organized as 1915 follows: 1917 * The 'protected' field MUST be absent if the key wrap algorithm is 1918 an AE algorithm. 1920 * The 'recipients' field is normally absent, but can be used. 1921 Applications MUST deal with a recipient field being present that 1922 has an unsupported algorithm. Failing to decrypt that specific 1923 recipient is an acceptable way of dealing with it. Failing to 1924 process the message is not an acceptable way of dealing with it. 1926 * The plaintext to be encrypted is the key from next layer down 1927 (usually the content layer). 1929 * At a minimum, the 'unprotected' field MUST contain the 'alg' 1930 header parameter and SHOULD contain a header parameter identifying 1931 the shared secret. 1933 8.5.3. Key Transport 1935 Key transport mode is also called key encryption mode in some 1936 standards. Key transport mode differs from key wrap mode in that it 1937 uses an asymmetric encryption algorithm rather than a symmetric 1938 encryption algorithm to protect the key. A set of key transport 1939 algorithms are defined in [RFC8230]. 1941 When using a key transport algorithm, the COSE_Recipient structure 1942 for the recipient is organized as follows: 1944 * The 'protected' field MUST be absent. 1946 * The plaintext to be encrypted is the key from the next layer down 1947 (usually the content layer). 1949 * At a minimum, the 'unprotected' field MUST contain the 'alg' 1950 header parameter and SHOULD contain a parameter identifying the 1951 asymmetric key. 1953 8.5.4. Direct Key Agreement 1955 The 'direct key agreement' class of recipient algorithms uses a key 1956 agreement method to create a shared secret. A KDF is then applied to 1957 the shared secret to derive a key to be used in protecting the data. 1958 This key is normally used as a CEK or MAC key, but could be used for 1959 other purposes if more than two layers are in use (see Appendix B). 1961 The most commonly used key agreement algorithm is Diffie-Hellman, but 1962 other variants exist. Since COSE is designed for a store and forward 1963 environment rather than an online environment, many of the DH 1964 variants cannot be used as the receiver of the message cannot provide 1965 any dynamic key material. One side effect of this is that forward 1966 secrecy (see [RFC4949]) is not achievable. A static key will always 1967 be used for the receiver of the COSE object. 1969 Two variants of DH that are supported are: 1971 Ephemeral-Static (ES) DH: where the sender of the message creates 1972 a one-time DH key and uses a static key for the recipient. The 1973 use of the ephemeral sender key means that no additional random 1974 input is needed as this is randomly generated for each message. 1976 Static-Static (SS) DH: where a static key is used for both the 1977 sender and the recipient. The use of static keys allows for the 1978 recipient to get a weak version of data origination for the 1979 message. When static-static key agreement is used, then some 1980 piece of unique data for the KDF is required to ensure that a 1981 different key is created for each message. 1983 When direct key agreement mode is used, there MUST be only one 1984 recipient in the message. This method creates the key directly, and 1985 that makes it difficult to mix with additional recipients. If 1986 multiple recipients are needed, then the version with key wrap needs 1987 to be used. 1989 The COSE_Recipient structure for the recipient is organized as 1990 follows: 1992 * At a minimum, headers MUST contain the 'alg' header parameter and 1993 SHOULD contain a header parameter identifying the recipient's 1994 asymmetric key. 1996 * The headers SHOULD identify the sender's key for the static-static 1997 versions and MUST contain the sender's ephemeral key for the 1998 ephemeral-static versions. 2000 8.5.5. Key Agreement with Key Wrap 2002 Key Agreement with Key Wrap uses a randomly generated CEK. The CEK 2003 is then encrypted using a key wrap algorithm and a key derived from 2004 the shared secret computed by the key agreement algorithm. The 2005 function for this would be: 2007 encryptedKey = KeyWrap(KDF(DH-Shared, context), CEK) 2009 The COSE_Recipient structure for the recipient is organized as 2010 follows: 2012 * The 'protected' field is fed into the KDF context structure. 2014 * The plaintext to be encrypted is the key from the next layer down 2015 (usually the content layer). 2017 * The 'alg' header parameter MUST be present in the layer. 2019 * A header parameter identifying the recipient's key SHOULD be 2020 present. A header parameter identifying the sender's key SHOULD 2021 be present. 2023 9. CBOR Encoding Restrictions 2025 This document limits the restrictions it imposes on how the CBOR 2026 Encoder needs to work. It has been narrowed down to the following 2027 restrictions: 2029 * The restriction applies to the encoding of the Sig_structure, the 2030 Enc_structure, and the MAC_structure. 2032 * Encoding MUST be done using definite lengths and values MUST be 2033 the minimum possible length. This means that the integer 1 is 2034 encoded as "0x01" and not "0x1801". 2036 * Applications MUST NOT generate messages with the same label used 2037 twice as a key in a single map. Applications MUST NOT parse and 2038 process messages with the same label used twice as a key in a 2039 single map. Applications can enforce the parse and process 2040 requirement by using parsers that will fail the parse step or by 2041 using parsers that will pass all keys to the application, and the 2042 application can perform the check for duplicate keys. 2044 10. Application Profiling Considerations 2046 This document is designed to provide a set of security services, but 2047 not impose algorithm implementation requirements for specific usage. 2048 The interoperability requirements are provided for how each of the 2049 individual services are used and how the algorithms are to be used 2050 for interoperability. The requirements about which algorithms and 2051 which services are needed are deferred to each application. 2053 An example of a profile can be found in [RFC8613] where one was 2054 developed for carrying content in combination with CoAP headers. 2056 It is intended that a profile of this document be created that 2057 defines the interoperability requirements for that specific 2058 application. This section provides a set of guidelines and topics 2059 that need to be considered when profiling this document. 2061 * Applications need to determine the set of messages defined in this 2062 document that they will be using. The set of messages corresponds 2063 fairly directly to the set of security services that are needed 2064 and to the security levels needed. 2066 * Applications may define new header parameters for a specific 2067 purpose. Applications will often times select specific header 2068 parameters to use or not to use. For example, an application 2069 would normally state a preference for using either the IV or the 2070 Partial IV header parameter. If the Partial IV header parameter 2071 is specified, then the application also needs to define how the 2072 fixed portion of the IV is determined. 2074 * When applications use externally defined authenticated data, they 2075 need to define how that data is encoded. This document assumes 2076 that the data will be provided as a byte string. More information 2077 can be found in Section 4.3. 2079 * Applications need to determine the set of security algorithms that 2080 are to be used. When selecting the algorithms to be used as the 2081 mandatory-to-implement set, consideration should be given to 2082 choosing different types of algorithms when two are chosen for a 2083 specific purpose. An example of this would be choosing HMAC- 2084 SHA512 and AES-CMAC as different MAC algorithms; the construction 2085 is vastly different between these two algorithms. This means that 2086 a weakening of one algorithm would be unlikely to lead to a 2087 weakening of the other algorithms. Of course, these algorithms do 2088 not provide the same level of security and thus may not be 2089 comparable for the desired security functionality. Additional 2090 guidence can be found in [BCP201]. 2092 * Applications may need to provide some type of negotiation or 2093 discovery method if multiple algorithms or message structures are 2094 permitted. The method can be as simple as requiring pre- 2095 configuration of the set of algorithms to providing a discovery 2096 method built into the protocol. S/MIME provided a number of 2097 different ways to approach the problem that applications could 2098 follow: 2100 - Advertising in the message (S/MIME capabilities) [RFC5751]. 2102 - Advertising in the certificate (capabilities extension) 2103 [RFC4262]. 2105 - Minimum requirements for the S/MIME, which have been updated 2106 over time [RFC2633] [RFC5751] (note that [RFC2633] has been 2107 obsoleted by [RFC5751]). 2109 11. IANA Considerations 2111 The registries and registrations listed below were created during 2112 processing of RFC 8152 [RFC8152]. The majority of the actions are to 2113 update the references to point to this document. 2115 11.1. COSE Header Parameters Registry 2117 IANA created a registry titled "COSE Header Parameters" as part of 2118 processing [RFC8152]. IANA is requested to update the reference for 2119 all entries, except "counter signature" and "CounterSignature0", in 2120 the table from [RFC8152] to this document. The reference for 2121 "counter signature" and "CounterSignature0" are to be left alone. 2123 IANA is requested to update the pointer for expert rview to [[this 2124 document]]. 2126 11.2. COSE Key Common Parameters Registry 2128 IANA created a registry titled "COSE Key Common Parameters" as part 2129 of the processing of [RFC8152]. IANA is requested to update the 2130 reference for entries in the table from [RFC8152] to this document. 2132 IANA is requested to update the pointer for expert rview to [[this 2133 document]]. 2135 11.3. Media Type Registrations 2137 11.3.1. COSE Security Message 2139 This section registers the 'application/cose' media type in the 2140 "Media Types" registry. These media types are used to indicate that 2141 the content is a COSE message. 2143 Type name: application 2145 Subtype name: cose 2147 Required parameters: N/A 2149 Optional parameters: cose-type 2151 Encoding considerations: binary 2153 Security considerations: See the Security Considerations section 2154 of [[This Document]]. 2156 Interoperability considerations: N/A 2157 Published specification: [[this document]] 2159 Applications that use this media type: IoT applications sending 2160 security content over HTTP(S) transports. 2162 Fragment identifier considerations: N/A 2164 Additional information: 2166 - Deprecated alias names for this type: N/A 2168 - Magic number(s): N/A 2170 - File extension(s): cbor 2172 - Macintosh file type code(s): N/A 2174 Person & email address to contact for further information: 2175 iesg@ietf.org 2177 Intended usage: COMMON 2179 Restrictions on usage: N/A 2181 Author: Jim Schaad, ietf@augustcellars.com 2183 Change Controller: IESG 2185 Provisional registration? No 2187 11.3.2. COSE Key Media Type 2189 This section registers the 'application/cose-key' and 'application/ 2190 cose-key-set' media types in the "Media Types" registry. These media 2191 types are used to indicate, respectively, that content is a COSE_Key 2192 or COSE_KeySet object. 2194 The template for registering 'application/cose-key' is: 2196 Type name: application 2198 Subtype name: cose-key 2200 Required parameters: N/A 2202 Optional parameters: N/A 2204 Encoding considerations: binary 2205 Security considerations: See the Security Considerations section 2206 of [[This Document]]. 2208 Interoperability considerations: N/A 2210 Published specification: [[this document]] 2212 Applications that use this media type: Distribution of COSE based 2213 keys for IoT applications. 2215 Fragment identifier considerations: N/A 2217 Additional information: 2219 - Deprecated alias names for this type: N/A 2221 - Magic number(s): N/A 2223 - File extension(s): cbor 2225 - Macintosh file type code(s): N/A 2227 Person & email address to contact for further information: 2228 iesg@ietf.org 2230 Intended usage: COMMON 2232 Restrictions on usage: N/A 2234 Author: Jim Schaad, ietf@augustcellars.com 2236 Change Controller: IESG 2238 Provisional registration? No 2240 The template for registering 'application/cose-key-set' is: 2242 Type name: application 2244 Subtype name: cose-key-set 2246 Required parameters: N/A 2248 Optional parameters: N/A 2250 Encoding considerations: binary 2251 Security considerations: See the Security Considerations section 2252 of [[This Document]]. 2254 Interoperability considerations: N/A 2256 Published specification: [[this document]] 2258 Applications that use this media type: Distribution of COSE based 2259 keys for IoT applications. 2261 Fragment identifier considerations: N/A 2263 Additional information: 2265 - Deprecated alias names for this type: N/A 2267 - Magic number(s): N/A 2269 - File extension(s): cbor 2271 - Macintosh file type code(s): N/A 2273 Person & email address to contact for further information: 2274 iesg@ietf.org 2276 Intended usage: COMMON 2278 Restrictions on usage: N/A 2280 Author: Jim Schaad, ietf@augustcellars.com 2282 Change Controller: IESG 2284 Provisional registration? No 2286 11.4. CoAP Content-Formats Registry 2288 IANA added entries to the "CoAP Content-Formats" registry while 2289 processing [RFC8152]. IANA is requested to update the reference 2290 value from [RFC8152] to [[This Document]]. 2292 11.5. Expert Review Instructions 2294 All of the IANA registries established by [RFC8152] are, at least in 2295 part, defined as expert review. This section gives some general 2296 guidelines for what the experts should be looking for, but they are 2297 being designated as experts for a reason, so they should be given 2298 substantial latitude. 2300 Expert reviewers should take into consideration the following points: 2302 * Point squatting should be discouraged. Reviewers are encouraged 2303 to get sufficient information for registration requests to ensure 2304 that the usage is not going to duplicate one that is already 2305 registered, and that the point is likely to be used in 2306 deployments. The zones tagged as private use are intended for 2307 testing purposes and closed environments; code points in other 2308 ranges should not be assigned for testing. 2310 * Specifications are required for the standards track range of point 2311 assignment. Specifications should exist for specification 2312 required ranges, but early assignment before a specification is 2313 available is considered to be permissible. Specifications are 2314 needed for the first-come, first-serve range if they are expected 2315 to be used outside of closed environments in an interoperable way. 2316 When specifications are not provided, the description provided 2317 needs to have sufficient information to identify what the point is 2318 being used for. 2320 * Experts should take into account the expected usage of fields when 2321 approving point assignment. The fact that there is a range for 2322 standards track documents does not mean that a standards track 2323 document cannot have points assigned outside of that range. The 2324 length of the encoded value should be weighed against how many 2325 code points of that length are left, the size of device it will be 2326 used on, and the number of code points left that encode to that 2327 size. 2329 * When algorithms are registered, vanity registrations should be 2330 discouraged. One way to do this is to require registrations to 2331 provide additional documentation on security analysis of the 2332 algorithm. Another thing that should be considered is requesting 2333 an opinion on the algorithm from the Crypto Forum Research Group 2334 (CFRG). Algorithms that do not meet the security requirements of 2335 the community and the messages structures should not be 2336 registered. 2338 12. Security Considerations 2340 There are a number of security considerations that need to be taken 2341 into account by implementers of this specification. While some 2342 considerations have been highlighted here, additional considerations 2343 may be found in the documents listed in the references. 2345 Implementations need to protect the private key material for any 2346 individuals. There are some cases that need to be highlighted on 2347 this issue. 2349 * Using the same key for two different algorithms can leak 2350 information about the key. It is therefore recommended that keys 2351 be restricted to a single algorithm. 2353 * Use of 'direct' as a recipient algorithm combined with a second 2354 recipient algorithm exposes the direct key to the second 2355 recipient. 2357 * Several of the algorithms in [I-D.ietf-cose-rfc8152bis-algs] have 2358 limits on the number of times that a key can be used without 2359 leaking information about the key. 2361 The use of ECDH and direct plus KDF (with no key wrap) will not 2362 directly lead to the private key being leaked; the one way function 2363 of the KDF will prevent that. There is, however, a different issue 2364 that needs to be addressed. Having two recipients requires that the 2365 CEK be shared between two recipients. The second recipient therefore 2366 has a CEK that was derived from material that can be used for the 2367 weak proof of origin. The second recipient could create a message 2368 using the same CEK and send it to the first recipient; the first 2369 recipient would, for either static-static ECDH or direct plus KDF, 2370 make an assumption that the CEK could be used for proof of origin 2371 even though it is from the wrong entity. If the key wrap step is 2372 added, then no proof of origin is implied and this is not an issue. 2374 Although it has been mentioned before, the use of a single key for 2375 multiple algorithms has been demonstrated in some cases to leak 2376 information about that key, provide the opportunity for attackers to 2377 forge integrity tags, or gain information about encrypted content. 2378 Binding a key to a single algorithm prevents these problems. Key 2379 creators and key consumers are strongly encouraged not only to create 2380 new keys for each different algorithm, but to include that selection 2381 of algorithm in any distribution of key material and strictly enforce 2382 the matching of algorithms in the key structure to algorithms in the 2383 message structure. In addition to checking that algorithms are 2384 correct, the key form needs to be checked as well. Do not use an 2385 'EC2' key where an 'OKP' key is expected. 2387 Before using a key for transmission, or before acting on information 2388 received, a trust decision on a key needs to be made. Is the data or 2389 action something that the entity associated with the key has a right 2390 to see or a right to request? A number of factors are associated 2391 with this trust decision. Some of the ones that are highlighted here 2392 are: 2394 * What are the permissions associated with the key owner? 2396 * Is the cryptographic algorithm acceptable in the current context? 2397 * Have the restrictions associated with the key, such as algorithm 2398 or freshness, been checked and are they correct? 2400 * Is the request something that is reasonable, given the current 2401 state of the application? 2403 * Have any security considerations that are part of the message been 2404 enforced (as specified by the application or 'crit' header 2405 parameter)? 2407 One area that has been getting exposure is traffic analysis of 2408 encrypted messages based on the length of the message. This 2409 specification does not provide for a uniform method of providing 2410 padding as part of the message structure. An observer can 2411 distinguish between two different messages (for example, 'YES' and 2412 'NO') based on the length for all of the content encryption 2413 algorithms that are defined in [I-D.ietf-cose-rfc8152bis-algs] 2414 document. This means that it is up to the applications to document 2415 how content padding is to be done in order to prevent or discourage 2416 such analysis. (For example, the text strings could be defined as 2417 'YES' and 'NO '.) 2419 13. Implementation Status 2421 This section is to be removed before publishing as an RFC. 2423 This section records the status of known implementations of the 2424 protocol defined by this specification at the time of posting of this 2425 Internet-Draft, and is based on a proposal described in [RFC7942]. 2426 The description of implementations in this section is intended to 2427 assist the IETF in its decision processes in progressing drafts to 2428 RFCs. Please note that the listing of any individual implementation 2429 here does not imply endorsement by the IETF. Furthermore, no effort 2430 has been spent to verify the information presented here that was 2431 supplied by IETF contributors. This is not intended as, and must not 2432 be construed to be, a catalog of available implementations or their 2433 features. Readers are advised to note that other implementations may 2434 exist. 2436 According to [RFC7942], "this will allow reviewers and working groups 2437 to assign due consideration to documents that have the benefit of 2438 running code, which may serve as evidence of valuable experimentation 2439 and feedback that have made the implemented protocols more mature. 2440 It is up to the individual working groups to use this information as 2441 they see fit". 2443 13.1. Author's Versions 2445 There are three different implementations that have been created by 2446 the author of the document both to create the examples that are 2447 included in the document and to validate the structures and 2448 methodology used in the design of COSE. 2450 * Implementation Location: https://github.com/cose-wg 2452 * Primary Maintainer: Jim Schaad 2454 * Languages: There are three different languages that are currently 2455 supported: Java, C# and C. 2457 * Cryptography: The Java and C# libraries use Bouncy Castle to 2458 provide the required cryptography. The C version uses OPENSSL 2459 Version 1.1 for the cryptography. 2461 * Coverage: All versions have support to allow for implicit 2462 algorithm support as they allow for the application to set 2463 attributes that are not to be sent in the message. 2465 * Testing: All of the examples in the example library are generated 2466 by the C# library and then validated using the Java and C 2467 libraries. All three libraries have tests to allow for the 2468 creating of the same messages that are in the example library 2469 followed by validating them. These are not compared against the 2470 example library. The Java and C# libraries have unit testing 2471 included. Not all of the MUST statements in the document have 2472 been implemented as part of the libraries. One such statement is 2473 the requirement that unique labels be present. 2475 * Licensing: Revised BSD License 2477 13.2. JavaScript Version 2479 * Implementation Location: https://github.com/erdtman/cose-js 2481 * Primary Maintainer: Samuel Erdtman 2483 * Languages: JavaScript 2485 * Cryptography: TBD 2487 * Coverage: Full Encrypt, Signature and MAC objects are supported. 2489 * Testing: Basic testing against the common example library. 2491 * Licensing: Apache License 2.0 2493 13.3. Python Version 2495 * Implementation Location: https://github.com/TimothyClaeys/COSE- 2496 PYTHON 2498 * Primary Maintainer: Timothy Claeys 2500 * Languages: Python 2502 * Cryptography: pyecdsak, crypto python libraries 2504 * Coverage: TBD 2506 * Testing: Basic testing plus running against the common example 2507 library. 2509 * Licensing: BSD 3-Clause License 2511 13.4. COSE Testing Library 2513 * Implementation Location: https://github.com/cose-wg/Examples 2515 * Primary Maintainer: Jim Schaad 2517 * Description: A set of tests for the COSE library is provided as 2518 part of the implementation effort. Both success and fail tests 2519 have been provided. All of the examples in this document are part 2520 of this example set. 2522 * Coverage: An attempt has been made to have test cases for every 2523 message type and algorithm in the document. Currently examples 2524 dealing with ECDH with Goldilocks are missing. 2526 * Licensing: Public Domain 2528 14. References 2530 14.1. Normative References 2532 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2533 Requirement Levels", BCP 14, RFC 2119, 2534 DOI 10.17487/RFC2119, March 1997, 2535 . 2537 [I-D.ietf-cbor-7049bis] 2538 Bormann, C. and P. Hoffman, "Concise Binary Object 2539 Representation (CBOR)", Work in Progress, Internet-Draft, 2540 draft-ietf-cbor-7049bis-14, June 16, 2020, 2541 . 2543 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2544 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2545 May 2017, . 2547 [I-D.ietf-cose-rfc8152bis-algs] 2548 Schaad, J., "CBOR Object Signing and Encryption (COSE): 2549 Initial Algorithms", Work in Progress, Internet-Draft, 2550 draft-ietf-cose-rfc8152bis-algs-11, July 1, 2020, 2551 . 2554 14.2. Informative References 2556 [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", 2557 RFC 8152, DOI 10.17487/RFC8152, July 2017, 2558 . 2560 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 2561 Definition Language (CDDL): A Notational Convention to 2562 Express Concise Binary Object Representation (CBOR) and 2563 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 2564 June 2019, . 2566 [RFC2633] Ramsdell, B., Ed., "S/MIME Version 3 Message 2567 Specification", RFC 2633, DOI 10.17487/RFC2633, June 1999, 2568 . 2570 [RFC4262] Santesson, S., "X.509 Certificate Extension for Secure/ 2571 Multipurpose Internet Mail Extensions (S/MIME) 2572 Capabilities", RFC 4262, DOI 10.17487/RFC4262, December 2573 2005, . 2575 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2576 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 2577 . 2579 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 2580 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 2581 . 2583 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 2584 RFC 5652, DOI 10.17487/RFC5652, September 2009, 2585 . 2587 [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet 2588 Mail Extensions (S/MIME) Version 3.2 Message 2589 Specification", RFC 5751, DOI 10.17487/RFC5751, January 2590 2010, . 2592 [RFC5752] Turner, S. and J. Schaad, "Multiple Signatures in 2593 Cryptographic Message Syntax (CMS)", RFC 5752, 2594 DOI 10.17487/RFC5752, January 2010, 2595 . 2597 [RFC5990] Randall, J., Kaliski, B., Brainard, J., and S. Turner, 2598 "Use of the RSA-KEM Key Transport Algorithm in the 2599 Cryptographic Message Syntax (CMS)", RFC 5990, 2600 DOI 10.17487/RFC5990, September 2010, 2601 . 2603 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 2604 Specifications and Registration Procedures", BCP 13, 2605 RFC 6838, DOI 10.17487/RFC6838, January 2013, 2606 . 2608 [STD90] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2609 Interchange Format", STD 90, RFC 8259, December 2017. 2611 2613 [BCP201] Housley, R., "Guidelines for Cryptographic Algorithm 2614 Agility and Selecting Mandatory-to-Implement Algorithms", 2615 BCP 201, RFC 7696, November 2015. 2617 2619 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2620 Application Protocol (CoAP)", RFC 7252, 2621 DOI 10.17487/RFC7252, June 2014, 2622 . 2624 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2625 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2626 2015, . 2628 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 2629 RFC 7516, DOI 10.17487/RFC7516, May 2015, 2630 . 2632 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 2633 DOI 10.17487/RFC7517, May 2015, 2634 . 2636 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 2637 DOI 10.17487/RFC7518, May 2015, 2638 . 2640 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital 2641 Signature Algorithm (EdDSA)", RFC 8032, 2642 DOI 10.17487/RFC8032, January 2017, 2643 . 2645 [DSS] National Institute of Standards and Technology, "Digital 2646 Signature Standard (DSS)", DOI 10.6028/NIST.FIPS.186-4, 2647 FIPS PUB 186-4, July 2013, 2648 . 2651 [PVSig] Brown, D. and D. Johnson, "Formal Security Proofs for a 2652 Signature Scheme with Partial Message Recovery", 2653 DOI 10.1007/3-540-45353-9_11, LNCS Volume 2020, June 2000, 2654 . 2656 [W3C.WebCrypto] 2657 Watson, M., "Web Cryptography API", W3C Recommendation, 2658 January 2017, . 2660 [RFC8230] Jones, M., "Using RSA Algorithms with CBOR Object Signing 2661 and Encryption (COSE) Messages", RFC 8230, 2662 DOI 10.17487/RFC8230, September 2017, 2663 . 2665 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 2666 Code: The Implementation Status Section", BCP 205, 2667 RFC 7942, DOI 10.17487/RFC7942, July 2016, 2668 . 2670 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 2671 (AES) Key Wrap Algorithm", RFC 3394, DOI 10.17487/RFC3394, 2672 September 2002, . 2674 [I-D.ietf-cose-hash-algs] 2675 Schaad, J., "CBOR Object Signing and Encryption (COSE): 2676 Hash Algorithms", Work in Progress, Internet-Draft, draft- 2677 ietf-cose-hash-algs-08, July 29, 2020, 2678 . 2681 [I-D.ietf-core-groupcomm-bis] 2682 Dijk, E., Wang, C., and M. Tiloca, "Group Communication 2683 for the Constrained Application Protocol (CoAP)", Work in 2684 Progress, Internet-Draft, draft-ietf-core-groupcomm-bis- 2685 01, July 13, 2020, . 2688 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 2689 "Object Security for Constrained RESTful Environments 2690 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 2691 . 2693 [I-D.irtf-cfrg-argon2] 2694 Biryukov, A., Dinu, D., Khovratovich, D., and S. 2695 Josefsson, "The memory-hard Argon2 password hash and 2696 proof-of-work function", Work in Progress, Internet-Draft, 2697 draft-irtf-cfrg-argon2-11, July 9, 2020, 2698 . 2700 [COAP.Formats] 2701 IANA, "CoAP Content-Formats", 2702 . 2705 [COSE.Algorithms] 2706 IANA, "COSE Algorithms", 2707 . 2710 [COSE.KeyParameters] 2711 IANA, "COSE Key Parameters", 2712 . 2715 [COSE.KeyTypes] 2716 IANA, "COSE Key Types", 2717 . 2720 [I-D.ietf-cose-countersign] 2721 Schaad, J., "CBOR Object Signing and Encryption (COSE): 2722 Countersignatures". 2724 Appendix A. Guidelines for External Data Authentication of Algorithms 2726 During development of COSE, the requirement that the algorithm 2727 identifier be located in the protected attributes was relaxed from a 2728 must to a should. There were two basic reasons that have been 2729 advanced to support this position. First, the resulting message will 2730 be smaller if the algorithm identifier is omitted from the most 2731 common messages in a CoAP environment. Second, there is a potential 2732 bug that will arise if full checking is not done correctly between 2733 the different places that an algorithm identifier could be placed 2734 (the message itself, an application statement, the key structure that 2735 the sender possesses, and the key structure the recipient possesses). 2737 This appendix lays out how such a change can be made and the details 2738 that an application needs to specify in order to use this option. 2739 Two different sets of details are specified: those needed to omit an 2740 algorithm identifier and those needed to use the variant on the 2741 countersignature attribute that contains no attributes about itself. 2743 Three sets of recommendations are laid out. The first set of 2744 recommendations applies to having an implicit algorithm identified 2745 for a single layer of a COSE object. The second set of 2746 recommendations applies to having multiple implicit algorithms 2747 identified for multiple layers of a COSE object. The third set of 2748 recommendations applies to having implicit algorithms for multiple 2749 COSE object constructs. 2751 The key words from [RFC2119] are deliberately not used here. This 2752 specification can provide recommendations, but it cannot enforce 2753 them. 2755 This set of recommendations applies to the case where an application 2756 is distributing a fixed algorithm along with the key information for 2757 use in a single COSE object. This normally applies to the smallest 2758 of the COSE objects, specifically COSE_Sign1, COSE_Mac0, and 2759 COSE_Encrypt0, but could apply to the other structures as well. 2761 The following items should be taken into account: 2763 * Applications need to list the set of COSE structures that implicit 2764 algorithms are to be used in. Applications need to require that 2765 the receipt of an explicit algorithm identifier in one of these 2766 structures will lead to the message being rejected. This 2767 requirement is stated so that there will never be a case where 2768 there is any ambiguity about the question of which algorithm 2769 should be used, the implicit or the explicit one. This applies 2770 even if the transported algorithm identifier is a protected 2771 attribute. This applies even if the transported algorithm is the 2772 same as the implicit algorithm. 2774 * Applications need to define the set of information that is to be 2775 considered to be part of a context when omitting algorithm 2776 identifiers. At a minimum, this would be the key identifier (if 2777 needed), the key, the algorithm, and the COSE structure it is used 2778 with. Applications should restrict the use of a single key to a 2779 single algorithm. As noted for some of the algorithms in 2780 [I-D.ietf-cose-rfc8152bis-algs], the use of the same key in 2781 different related algorithms can lead to leakage of information 2782 about the key, leakage about the data or the ability to perform 2783 forgeries. 2785 * In many cases, applications that make the algorithm identifier 2786 implicit will also want to make the context identifier implicit 2787 for the same reason. That is, omitting the context identifier 2788 will decrease the message size (potentially significantly 2789 depending on the length of the identifier). Applications that do 2790 this will need to describe the circumstances where the context 2791 identifier is to be omitted and how the context identifier is to 2792 be inferred in these cases. (An exhaustive search over all of the 2793 keys would normally not be considered to be acceptable.) An 2794 example of how this can be done is to tie the context to a 2795 transaction identifier. Both would be sent on the original 2796 message, but only the transaction identifier would need to be sent 2797 after that point as the context is tied into the transaction 2798 identifier. Another way would be to associate a context with a 2799 network address. All messages coming from a single network 2800 address can be assumed to be associated with a specific context. 2801 (In this case, the address would normally be distributed as part 2802 of the context.) 2804 * Applications cannot rely on key identifiers being unique unless 2805 they take significant efforts to ensure that they are computed in 2806 such a way as to create this guarantee. Even when an application 2807 does this, the uniqueness might be violated if the application is 2808 run in different contexts (i.e., with a different context 2809 provider) or if the system combines the security contexts from 2810 different applications together into a single store. 2812 * Applications should continue the practice of protecting the 2813 algorithm identifier. Since this is not done by placing it in the 2814 protected attributes field, applications should define an 2815 application-specific external data structure that includes this 2816 value. This external data field can be used as such for content 2817 encryption, MAC, and signature algorithms. It can be used in the 2818 SuppPrivInfo field for those algorithms that use a KDF to derive a 2819 key value. Applications may also want to protect other 2820 information that is part of the context structure as well. It 2821 should be noted that those fields, such as the key or a Base IV, 2822 are protected by virtue of being used in the cryptographic 2823 computation and do not need to be included in the external data 2824 field. 2826 The second case is having multiple implicit algorithm identifiers 2827 specified for a multiple layer COSE object. An example of how this 2828 would work is the encryption context that an application specifies, 2829 which contains a content encryption algorithm, a key wrap algorithm, 2830 a key identifier, and a shared secret. The sender omits sending the 2831 algorithm identifier for both the content layer and the recipient 2832 layer leaving only the key identifier. The receiver then uses the 2833 key identifier to get the implicit algorithm identifiers. 2835 The following additional items need to be taken into consideration: 2837 * Applications that want to support this will need to define a 2838 structure that allows for, and clearly identifies, both the COSE 2839 structure to be used with a given key and the structure and 2840 algorithm to be used for the secondary layer. The key for the 2841 secondary layer is computed as normal from the recipient layer. 2843 The third case is having multiple implicit algorithm identifiers, but 2844 targeted at potentially unrelated layers or different COSE objects. 2845 There are a number of different scenarios where this might be 2846 applicable. Some of these scenarios are: 2848 * Two contexts are distributed as a pair. Each of the contexts is 2849 for use with a COSE_Encrypt message. Each context will consist of 2850 distinct secret keys and IVs and potentially even different 2851 algorithms. One context is for sending messages from party A to 2852 party B, and the second context is for sending messages from party 2853 B to party A. This means that there is no chance for a reflection 2854 attack to occur as each party uses different secret keys to send 2855 its messages; a message that is reflected back to it would fail to 2856 decrypt. 2858 * Two contexts are distributed as a pair. The first context is used 2859 for encryption of the message, and the second context is used to 2860 place a countersignature on the message. The intention is that 2861 the second context can be distributed to other entities 2862 independently of the first context. This allows these entities to 2863 validate that the message came from an individual without being 2864 able to decrypt the message and see the content. 2866 * Two contexts are distributed as a pair. The first context 2867 contains a key for dealing with MACed messages, and the second 2868 context contains a different key for dealing with encrypted 2869 messages. This allows for a unified distribution of keys to 2870 participants for different types of messages that have different 2871 keys, but where the keys may be used in a coordinated manner. 2873 For these cases, the following additional items need to be 2874 considered: 2876 * Applications need to ensure that the multiple contexts stay 2877 associated. If one of the contexts is invalidated for any reason, 2878 all of the contexts associated with it should also be invalidated. 2880 Appendix B. Two Layers of Recipient Information 2882 All of the currently defined recipient algorithm classes only use two 2883 layers of the COSE structure. The first layer (COSE_Encrypt) is the 2884 message content, and the second layer (COSE_Recipint) is the content 2885 key encryption. However, if one uses a recipient algorithm such as 2886 the RSA Key Encapsulation Mechanism (RSA-KEM) (see Appendix A of RSA- 2887 KEM [RFC5990]), then it makes sense to have two layers of the 2888 COSE_Recipient structure. 2890 These layers would be: 2892 * Layer 0: The content encryption layer. This layer contains the 2893 payload of the message. 2895 * Layer 1: The encryption of the CEK by a KEK. 2897 * Layer 2: The encryption of a long random secret using an RSA key 2898 and a key derivation function to convert that secret into the KEK. 2900 This is an example of what a triple layer message would look like. 2901 The message has the following layers: 2903 * Layer 0: Has a content encrypted with AES-GCM using a 128-bit key. 2905 * Layer 1: Uses the AES Key Wrap algorithm with a 128-bit key. 2907 * Layer 2: Uses ECDH Ephemeral-Static direct to generate the layer 1 2908 key. 2910 In effect, this example is a decomposed version of using the 2911 ECDH-ES+A128KW algorithm. 2913 Size of binary file is 183 bytes 2915 96( 2916 [ / COSE_Encrypt / 2917 / protected h'a10101' / << { 2918 / alg / 1:1 / AES-GCM 128 / 2919 } >>, 2920 / unprotected / { 2921 / iv / 5:h'02d1f7e6f26c43d4868d87ce' 2922 }, 2923 / ciphertext / h'64f84d913ba60a76070a9a48f26e97e863e2852948658f0 2924 811139868826e89218a75715b', 2925 / recipients / [ 2926 [ / COSE_Recipient / 2927 / protected / h'', 2928 / unprotected / { 2929 / alg / 1:-3 / A128KW / 2930 }, 2931 / ciphertext / h'dbd43c4e9d719c27c6275c67d628d493f090593db82 2932 18f11', 2933 / recipients / [ 2934 [ / COSE_Recipient / 2935 / protected h'a1013818' / << { 2936 / alg / 1:-25 / ECDH-ES + HKDF-256 / 2937 } >> , 2938 / unprotected / { 2939 / ephemeral / -1:{ 2940 / kty / 1:2, 2941 / crv / -1:1, 2942 / x / -2:h'b2add44368ea6d641f9ca9af308b4079aeb519f11 2943 e9b8a55a600b21233e86e68', 2944 / y / -3:false 2945 }, 2946 / kid / 4:'meriadoc.brandybuck@buckland.example' 2947 }, 2948 / ciphertext / h'' 2949 ] 2950 ] 2951 ] 2952 ] 2953 ] 2954 ) 2956 Appendix C. Examples 2958 This appendix includes a set of examples that show the different 2959 features and message types that have been defined in this document. 2960 To make the examples easier to read, they are presented using the 2961 extended CBOR diagnostic notation (defined in [RFC8610]) rather than 2962 as a binary dump. 2964 A GitHub project has been created at that contains not only the examples presented in this 2966 document, but a more complete set of testing examples as well. Each 2967 example is found in a JSON file that contains the inputs used to 2968 create the example, some of the intermediate values that can be used 2969 in debugging the example and the output of the example presented both 2970 as a hex dump and in CBOR diagnostic notation format. Some of the 2971 examples at the site are designed failure testing cases; these are 2972 clearly marked as such in the JSON file. If errors in the examples 2973 in this document are found, the examples on GitHub will be updated, 2974 and a note to that effect will be placed in the JSON file. 2976 As noted, the examples are presented using the CBOR's diagnostic 2977 notation. A Ruby-based tool exists that can convert between the 2978 diagnostic notation and binary. This tool can be installed with the 2979 command line: 2981 gem install cbor-diag 2983 The diagnostic notation can be converted into binary files using the 2984 following command line: 2986 diag2cbor.rb < inputfile > outputfile 2988 The examples can be extracted from the XML version of this document 2989 via an XPath expression as all of the sourcecode is tagged with the 2990 attribute type='CBORdiag'. (Depending on the XPath evaluator one is 2991 using, it may be necessary to deal with > as an entity.) 2993 //sourcecode[@type='CDDL']/text() 2995 C.1. Examples of Signed Messages 2997 C.1.1. Single Signature 2999 This example uses the following: 3001 * Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 3003 Size of binary file is 103 bytes 3004 98( 3005 [ 3006 / protected / h'', 3007 / unprotected / {}, 3008 / payload / 'This is the content.', 3009 / signatures / [ 3010 [ 3011 / protected h'a10126' / << { 3012 / alg / 1:-7 / ECDSA 256 / 3013 } >>, 3014 / unprotected / { 3015 / kid / 4:'11' 3016 }, 3017 / signature / h'e2aeafd40d69d19dfe6e52077c5d7ff4e408282cbefb 3018 5d06cbf414af2e19d982ac45ac98b8544c908b4507de1e90b717c3d34816fe926a2b 3019 98f53afd2fa0f30a' 3020 ] 3021 ] 3022 ] 3023 ) 3025 C.1.2. Multiple Signers 3027 This example uses the following: 3029 * Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 3031 * Signature Algorithm: ECDSA w/ SHA-512, Curve P-521 3033 Size of binary file is 277 bytes 3034 98( 3035 [ 3036 / protected / h'', 3037 / unprotected / {}, 3038 / payload / 'This is the content.', 3039 / signatures / [ 3040 [ 3041 / protected h'a10126' / << { 3042 / alg / 1:-7 / ECDSA 256 / 3043 } >>, 3044 / unprotected / { 3045 / kid / 4:'11' 3046 }, 3047 / signature / h'e2aeafd40d69d19dfe6e52077c5d7ff4e408282cbefb 3048 5d06cbf414af2e19d982ac45ac98b8544c908b4507de1e90b717c3d34816fe926a2b 3049 98f53afd2fa0f30a' 3050 ], 3051 [ 3052 / protected h'a1013823' / << { 3053 / alg / 1:-36 / ECDSA 521 / 3054 } >> , 3055 / unprotected / { 3056 / kid / 4:'bilbo.baggins@hobbiton.example' 3057 }, 3058 / signature / h'00a2d28a7c2bdb1587877420f65adf7d0b9a06635dd1 3059 de64bb62974c863f0b160dd2163734034e6ac003b01e8705524c5c4ca479a952f024 3060 7ee8cb0b4fb7397ba08d009e0c8bf482270cc5771aa143966e5a469a09f613488030 3061 c5b07ec6d722e3835adb5b2d8c44e95ffb13877dd2582866883535de3bb03d01753f 3062 83ab87bb4f7a0297' 3063 ] 3064 ] 3065 ] 3066 ) 3068 C.1.3. Signature with Criticality 3070 This example uses the following: 3072 * Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 3074 * There is a criticality marker on the "reserved" header parameter 3076 Size of binary file is 125 bytes 3077 98( 3078 [ 3079 / protected h'a2687265736572766564f40281687265736572766564' / 3080 << { 3081 "reserved":false, 3082 / crit / 2:[ 3083 "reserved" 3084 ] 3085 } >>, 3086 / unprotected / {}, 3087 / payload / 'This is the content.', 3088 / signatures / [ 3089 [ 3090 / protected h'a10126' / << { 3091 / alg / 1:-7 / ECDSA 256 / 3092 } >>, 3093 / unprotected / { 3094 / kid / 4:'11' 3095 }, 3096 / signature / h'3fc54702aa56e1b2cb20284294c9106a63f91bac658d 3097 69351210a031d8fc7c5ff3e4be39445b1a3e83e1510d1aca2f2e8a7c081c7645042b 3098 18aba9d1fad1bd9c' 3099 ] 3100 ] 3101 ] 3102 ) 3104 C.2. Single Signer Examples 3106 C.2.1. Single ECDSA Signature 3108 This example uses the following: 3110 * Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 3112 Size of binary file is 98 bytes 3113 18( 3114 [ 3115 / protected h'a10126' / << { 3116 / alg / 1:-7 / ECDSA 256 / 3117 } >>, 3118 / unprotected / { 3119 / kid / 4:'11' 3120 }, 3121 / payload / 'This is the content.', 3122 / signature / h'8eb33e4ca31d1c465ab05aac34cc6b23d58fef5c083106c4 3123 d25a91aef0b0117e2af9a291aa32e14ab834dc56ed2a223444547e01f11d3b0916e5 3124 a4c345cacb36' 3125 ] 3126 ) 3128 C.3. Examples of Enveloped Messages 3130 C.3.1. Direct ECDH 3132 This example uses the following: 3134 * CEK: AES-GCM w/ 128-bit key 3136 * Recipient class: ECDH Ephemeral-Static, Curve P-256 3138 Size of binary file is 151 bytes 3139 96( 3140 [ 3141 / protected h'a10101' / << { 3142 / alg / 1:1 / AES-GCM 128 / 3143 } >>, 3144 / unprotected / { 3145 / iv / 5:h'c9cf4df2fe6c632bf7886413' 3146 }, 3147 / ciphertext / h'7adbe2709ca818fb415f1e5df66f4e1a51053ba6d65a1a0 3148 c52a357da7a644b8070a151b0', 3149 / recipients / [ 3150 [ 3151 / protected h'a1013818' / << { 3152 / alg / 1:-25 / ECDH-ES + HKDF-256 / 3153 } >>, 3154 / unprotected / { 3155 / ephemeral / -1:{ 3156 / kty / 1:2, 3157 / crv / -1:1, 3158 / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf 3159 bf054e1c7b4d91d6280', 3160 / y / -3:true 3161 }, 3162 / kid / 4:'meriadoc.brandybuck@buckland.example' 3163 }, 3164 / ciphertext / h'' 3165 ] 3166 ] 3167 ] 3168 ) 3170 C.3.2. Direct Plus Key Derivation 3172 This example uses the following: 3174 * CEK: AES-CCM w/ 128-bit key, truncate the tag to 64 bits 3176 * Recipient class: Use HKDF on a shared secret with the following 3177 implicit fields as part of the context. 3179 - salt: "aabbccddeeffgghh" 3181 - PartyU identity: "lighting-client" 3183 - PartyV identity: "lighting-server" 3185 - Supplementary Public Other: "Encryption Example 02" 3187 Size of binary file is 91 bytes 3189 96( 3190 [ 3191 / protected h'a1010a' / << { 3192 / alg / 1:10 / AES-CCM-16-64-128 / 3193 } >>, 3194 / unprotected / { 3195 / iv / 5:h'89f52f65a1c580933b5261a76c' 3196 }, 3197 / ciphertext / h'753548a19b1307084ca7b2056924ed95f2e3b17006dfe93 3198 1b687b847', 3199 / recipients / [ 3200 [ 3201 / protected h'a10129' / << { 3202 / alg / 1:-10 3203 } >>, 3204 / unprotected / { 3205 / salt / -20:'aabbccddeeffgghh', 3206 / kid / 4:'our-secret' 3207 }, 3208 / ciphertext / h'' 3209 ] 3210 ] 3211 ] 3212 ) 3214 C.3.3. Encrypted Content with External Data 3216 This example uses the following: 3218 * CEK: AES-GCM w/ 128-bit key 3220 * Recipient class: ECDH static-Static, Curve P-256 with AES Key Wrap 3222 * Externally Supplied AAD: h'0011bbcc22dd44ee55ff660077' 3224 Size of binary file is 173 bytes 3225 96( 3226 [ 3227 / protected h'a10101' / << { 3228 / alg / 1:1 / AES-GCM 128 / 3229 } >> , 3230 / unprotected / { 3231 / iv / 5:h'02d1f7e6f26c43d4868d87ce' 3232 }, 3233 / ciphertext / h'64f84d913ba60a76070a9a48f26e97e863e28529d8f5335 3234 e5f0165eee976b4a5f6c6f09d', 3235 / recipients / [ 3236 [ 3237 / protected / h'a101381f' / { 3238 \ alg \ 1:-32 \ ECHD-SS+A128KW \ 3239 } / , 3240 / unprotected / { 3241 / static kid / -3:'peregrin.took@tuckborough.example', 3242 / kid / 4:'meriadoc.brandybuck@buckland.example', 3243 / U nonce / -22:h'0101' 3244 }, 3245 / ciphertext / h'41e0d76f579dbd0d936a662d54d8582037de2e366fd 3246 e1c62' 3247 ] 3248 ] 3249 ] 3250 ) 3252 C.4. Examples of Encrypted Messages 3254 C.4.1. Simple Encrypted Message 3256 This example uses the following: 3258 * CEK: AES-CCM w/ 128-bit key and a 64-bit tag 3260 Size of binary file is 52 bytes 3261 16( 3262 [ 3263 / protected h'a1010a' / << { 3264 / alg / 1:10 / AES-CCM-16-64-128 / 3265 } >> , 3266 / unprotected / { 3267 / iv / 5:h'89f52f65a1c580933b5261a78c' 3268 }, 3269 / ciphertext / h'5974e1b99a3a4cc09a659aa2e9e7fff161d38ce71cb45ce 3270 460ffb569' 3271 ] 3272 ) 3274 C.4.2. Encrypted Message with a Partial IV 3276 This example uses the following: 3278 * CEK: AES-CCM w/ 128-bit key and a 64-bit tag 3280 * Prefix for IV is 89F52F65A1C580933B52 3282 Size of binary file is 41 bytes 3284 16( 3285 [ 3286 / protected h'a1010a' / << { 3287 / alg / 1:10 / AES-CCM-16-64-128 / 3288 } >> , 3289 / unprotected / { 3290 / partial iv / 6:h'61a7' 3291 }, 3292 / ciphertext / h'252a8911d465c125b6764739700f0141ed09192de139e05 3293 3bd09abca' 3294 ] 3295 ) 3297 C.5. Examples of MACed Messages 3299 C.5.1. Shared Secret Direct MAC 3301 This example uses the following: 3303 * MAC: AES-CMAC, 256-bit key, truncated to 64 bits 3305 * Recipient class: direct shared secret 3307 Size of binary file is 57 bytes 3308 97( 3309 [ 3310 / protected h'a1010f' / << { 3311 / alg / 1:15 / AES-CBC-MAC-256//64 / 3312 } >> , 3313 / unprotected / {}, 3314 / payload / 'This is the content.', 3315 / tag / h'9e1226ba1f81b848', 3316 / recipients / [ 3317 [ 3318 / protected / h'', 3319 / unprotected / { 3320 / alg / 1:-6 / direct /, 3321 / kid / 4:'our-secret' 3322 }, 3323 / ciphertext / h'' 3324 ] 3325 ] 3326 ] 3327 ) 3329 C.5.2. ECDH Direct MAC 3331 This example uses the following: 3333 * MAC: HMAC w/SHA-256, 256-bit key 3335 * Recipient class: ECDH key agreement, two static keys, HKDF w/ 3336 context structure 3338 Size of binary file is 214 bytes 3339 97( 3340 [ 3341 / protected h'a10105' / << { 3342 / alg / 1:5 / HMAC 256//256 / 3343 } >> , 3344 / unprotected / {}, 3345 / payload / 'This is the content.', 3346 / tag / h'81a03448acd3d305376eaa11fb3fe416a955be2cbe7ec96f012c99 3347 4bc3f16a41', 3348 / recipients / [ 3349 [ 3350 / protected h'a101381a' / << { 3351 / alg / 1:-27 / ECDH-SS + HKDF-256 / 3352 } >> , 3353 / unprotected / { 3354 / static kid / -3:'peregrin.took@tuckborough.example', 3355 / kid / 4:'meriadoc.brandybuck@buckland.example', 3356 / U nonce / -22:h'4d8553e7e74f3c6a3a9dd3ef286a8195cbf8a23d 3357 19558ccfec7d34b824f42d92bd06bd2c7f0271f0214e141fb779ae2856abf585a583 3358 68b017e7f2a9e5ce4db5' 3359 }, 3360 / ciphertext / h'' 3361 ] 3362 ] 3363 ] 3364 ) 3366 C.5.3. Wrapped MAC 3368 This example uses the following: 3370 * MAC: AES-MAC, 128-bit key, truncated to 64 bits 3372 * Recipient class: AES Key Wrap w/ a pre-shared 256-bit key 3374 Size of binary file is 109 bytes 3375 97( 3376 [ 3377 / protected h'a1010e' / << { 3378 / alg / 1:14 / AES-CBC-MAC-128//64 / 3379 } >> , 3380 / unprotected / {}, 3381 / payload / 'This is the content.', 3382 / tag / h'36f5afaf0bab5d43', 3383 / recipients / [ 3384 [ 3385 / protected / h'', 3386 / unprotected / { 3387 / alg / 1:-5 / A256KW /, 3388 / kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037' 3389 }, 3390 / ciphertext / h'711ab0dc2fc4585dce27effa6781c8093eba906f227 3391 b6eb0' 3392 ] 3393 ] 3394 ] 3395 ) 3397 C.5.4. Multi-Recipient MACed Message 3399 This example uses the following: 3401 * MAC: HMAC w/ SHA-256, 128-bit key 3403 * Recipient class: Uses three different methods 3405 1. ECDH Ephemeral-Static, Curve P-521, AES Key Wrap w/ 128-bit 3406 key 3408 2. AES Key Wrap w/ 256-bit key 3410 Size of binary file is 309 bytes 3411 97( 3412 [ 3413 / protected h'a10105' / << { 3414 / alg / 1:5 / HMAC 256//256 / 3415 } >> , 3416 / unprotected / {}, 3417 / payload / 'This is the content.', 3418 / tag / h'bf48235e809b5c42e995f2b7d5fa13620e7ed834e337f6aa43df16 3419 1e49e9323e', 3420 / recipients / [ 3421 [ 3422 / protected h'a101381c' / << { 3423 / alg / 1:-29 / ECHD-ES+A128KW / 3424 } >> , 3425 / unprotected / { 3426 / ephemeral / -1:{ 3427 / kty / 1:2, 3428 / crv / -1:3, 3429 / x / -2:h'0043b12669acac3fd27898ffba0bcd2e6c366d53bc4db 3430 71f909a759304acfb5e18cdc7ba0b13ff8c7636271a6924b1ac63c02688075b55ef2 3431 d613574e7dc242f79c3', 3432 / y / -3:true 3433 }, 3434 / kid / 4:'bilbo.baggins@hobbiton.example' 3435 }, 3436 / ciphertext / h'339bc4f79984cdc6b3e6ce5f315a4c7d2b0ac466fce 3437 a69e8c07dfbca5bb1f661bc5f8e0df9e3eff5' 3438 ], 3439 [ 3440 / protected / h'', 3441 / unprotected / { 3442 / alg / 1:-5 / A256KW /, 3443 / kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037' 3444 }, 3445 / ciphertext / h'0b2c7cfce04e98276342d6476a7723c090dfdd15f9a 3446 518e7736549e998370695e6d6a83b4ae507bb' 3447 ] 3448 ] 3449 ] 3450 ) 3452 C.6. Examples of MAC0 Messages 3454 C.6.1. Shared Secret Direct MAC 3456 This example uses the following: 3458 * MAC: AES-CMAC, 256-bit key, truncated to 64 bits 3459 * Recipient class: direct shared secret 3461 Size of binary file is 37 bytes 3463 17( 3464 [ 3465 / protected h'a1010f' / << { 3466 / alg / 1:15 / AES-CBC-MAC-256//64 / 3467 } >> , 3468 / unprotected / {}, 3469 / payload / 'This is the content.', 3470 / tag / h'726043745027214f' 3471 ] 3472 ) 3474 Note that this example uses the same inputs as Appendix C.5.1. 3476 C.7. COSE Keys 3478 C.7.1. Public Keys 3480 This is an example of a COSE Key Set. This example includes the 3481 public keys for all of the previous examples. 3483 In order the keys are: 3485 * An EC key with a kid of "meriadoc.brandybuck@buckland.example" 3487 * An EC key with a kid of "peregrin.took@tuckborough.example" 3489 * An EC key with a kid of "bilbo.baggins@hobbiton.example" 3491 * An EC key with a kid of "11" 3493 Size of binary file is 481 bytes 3495 [ 3496 { 3497 -1:1, 3498 -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0 3499 8551d', 3500 -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008 3501 4d19c', 3502 1:2, 3503 2:'meriadoc.brandybuck@buckland.example' 3504 }, 3505 { 3506 -1:1, 3507 -2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a 3508 09eff', 3509 -3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbf 3510 c117e', 3511 1:2, 3512 2:'11' 3513 }, 3514 { 3515 -1:3, 3516 -2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737bf5de 3517 7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620085e5c8 3518 f42ad', 3519 -3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e247e 3520 60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3fe1ea1 3521 d9475', 3522 1:2, 3523 2:'bilbo.baggins@hobbiton.example' 3524 }, 3525 { 3526 -1:1, 3527 -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b4d91 3528 d6280', 3529 -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e03bf 3530 822bb', 3531 1:2, 3532 2:'peregrin.took@tuckborough.example' 3533 } 3534 ] 3536 C.7.2. Private Keys 3538 This is an example of a COSE Key Set. This example includes the 3539 private keys for all of the previous examples. 3541 In order the keys are: 3543 * An EC key with a kid of "meriadoc.brandybuck@buckland.example" 3545 * A shared-secret key with a kid of "our-secret" 3547 * An EC key with a kid of "peregrin.took@tuckborough.example" 3549 * A shared-secret key with a kid of "018c0ae5-4d9b-471b- 3550 bfd6-eef314bc7037" 3552 * An EC key with a kid of "bilbo.baggins@hobbiton.example" 3554 * An EC key with a kid of "11" 3556 Size of binary file is 816 bytes 3558 [ 3559 { 3560 1:2, 3561 2:'meriadoc.brandybuck@buckland.example', 3562 -1:1, 3563 -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0 3564 8551d', 3565 -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008 3566 4d19c', 3567 -4:h'aff907c99f9ad3aae6c4cdf21122bce2bd68b5283e6907154ad911840fa 3568 208cf' 3569 }, 3570 { 3571 1:2, 3572 2:'11', 3573 -1:1, 3574 -2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a 3575 09eff', 3576 -3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbf 3577 c117e', 3578 -4:h'57c92077664146e876760c9520d054aa93c3afb04e306705db609030850 3579 7b4d3' 3580 }, 3581 { 3582 1:2, 3583 2:'bilbo.baggins@hobbiton.example', 3584 -1:3, 3585 -2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737bf5de 3586 7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620085e5c8 3587 f42ad', 3588 -3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e247e 3589 60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3fe1ea1 3590 d9475', 3591 -4:h'00085138ddabf5ca975f5860f91a08e91d6d5f9a76ad4018766a476680b 3592 55cd339e8ab6c72b5facdb2a2a50ac25bd086647dd3e2e6e99e84ca2c3609fdf177f 3593 eb26d' 3594 }, 3595 { 3596 1:4, 3597 2:'our-secret', 3598 -1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dcea6c4 3599 27188' 3600 }, 3601 { 3602 1:2, 3603 -1:1, 3604 2:'peregrin.took@tuckborough.example', 3605 -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b4d91 3606 d6280', 3607 -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e03bf 3608 822bb', 3609 -4:h'02d1f7e6f26c43d4868d87ceb2353161740aacf1f7163647984b522a848 3610 df1c3' 3611 }, 3612 { 3613 1:4, 3614 2:'our-secret2', 3615 -1:h'849b5786457c1491be3a76dcea6c4271' 3616 }, 3617 { 3618 1:4, 3619 2:'018c0ae5-4d9b-471b-bfd6-eef314bc7037', 3620 -1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dcea6c4 3621 27188' 3622 } 3623 ] 3625 Acknowledgments 3627 This document is a product of the COSE working group of the IETF. 3629 The following individuals are to blame for getting me started on this 3630 project in the first place: Richard Barnes, Matt Miller, and Martin 3631 Thomson. 3633 The initial version of the specification was based to some degree on 3634 the outputs of the JOSE and S/MIME working groups. 3636 The following individuals provided input into the final form of the 3637 document: Carsten Bormann, John Bradley, Brain Campbell, Michael B. 3638 Jones, Ilari Liusvaara, Francesca Palombini, Ludwig Seitz, and 3639 Göran Selander. 3641 Author's Address 3643 Jim Schaad 3644 August Cellars 3646 Email: ietf@augustcellars.com