idnits 2.17.1 draft-ietf-cose-msg-12.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 705 has weird spacing: '...otected as de...' == Line 707 has weird spacing: '...otected as de...' == Line 709 has weird spacing: '...payload conta...' == Line 725 has weird spacing: '...natures is an...' == Line 739 has weird spacing: '...otected as de...' == (28 more instances...) -- The document date (May 12, 2016) is 2904 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'AES-GCM' -- Possible downref: Non-RFC (?) normative reference: ref. 'DSS' -- Possible downref: Non-RFC (?) normative reference: ref. 'MAC' ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Downref: Normative reference to an Informational RFC: RFC 3394 ** Downref: Normative reference to an Informational RFC: RFC 3610 ** Downref: Normative reference to an Informational RFC: RFC 5869 ** Downref: Normative reference to an Informational RFC: RFC 6090 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 7539 (Obsoleted by RFC 8439) -- Possible downref: Non-RFC (?) normative reference: ref. 'SEC1' == Outdated reference: A later version (-11) exists of draft-greevenbosch-appsawg-cbor-cddl-08 == Outdated reference: A later version (-08) exists of draft-irtf-cfrg-eddsa-05 -- Obsolete informational reference (is this intentional?): RFC 2633 (Obsoleted by RFC 3851) -- Obsolete informational reference (is this intentional?): RFC 2898 (Obsoleted by RFC 8018) -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) -- Obsolete informational reference (is this intentional?): RFC 5751 (Obsoleted by RFC 8551) -- Obsolete informational reference (is this intentional?): RFC 6982 (Obsoleted by RFC 7942) -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) Summary: 7 errors (**), 0 flaws (~~), 9 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 COSE Working Group J. Schaad 3 Internet-Draft August Cellars 4 Intended status: Standards Track May 12, 2016 5 Expires: November 13, 2016 7 CBOR Encoded Message Syntax 8 draft-ietf-cose-msg-12 10 Abstract 12 Concise Binary Object Representation (CBOR) is data format designed 13 for small code size and small message size. There is a need for the 14 ability to have the basic security services defined for this data 15 format. This document specifies processing for signatures, message 16 authentication codes, and encryption using CBOR. This document also 17 specifies a representation for cryptographic keys using CBOR. 19 Contributing to this document 21 The source for this draft is being maintained in GitHub. Suggested 22 changes should be submitted as pull requests at . Instructions are on that page as well. 24 Editorial changes can be managed in GitHub, but any substantial 25 issues need to be discussed on the COSE mailing list. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on November 13, 2016. 44 Copyright Notice 46 Copyright (c) 2016 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 62 1.1. Design changes from JOSE . . . . . . . . . . . . . . . . 5 63 1.2. Requirements Terminology . . . . . . . . . . . . . . . . 6 64 1.3. CBOR Grammar . . . . . . . . . . . . . . . . . . . . . . 6 65 1.4. CBOR Related Terminology . . . . . . . . . . . . . . . . 7 66 1.5. Document Terminology . . . . . . . . . . . . . . . . . . 7 67 2. Basic COSE Structure . . . . . . . . . . . . . . . . . . . . 8 68 3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 9 69 3.1. Common COSE Headers Parameters . . . . . . . . . . . . . 11 70 4. Signing Objects . . . . . . . . . . . . . . . . . . . . . . . 15 71 4.1. Signing with One or More Signers . . . . . . . . . . . . 15 72 4.2. Signing with One Signer . . . . . . . . . . . . . . . . . 17 73 4.3. Externally Supplied Data . . . . . . . . . . . . . . . . 18 74 4.4. Signing and Verification Process . . . . . . . . . . . . 19 75 4.5. Computing Counter Signatures . . . . . . . . . . . . . . 20 76 5. Encryption Objects . . . . . . . . . . . . . . . . . . . . . 21 77 5.1. Enveloped COSE Structure . . . . . . . . . . . . . . . . 21 78 5.1.1. Recipient Algorithm Classes . . . . . . . . . . . . . 23 79 5.2. Single Recipient Encrypted . . . . . . . . . . . . . . . 23 80 5.3. Encryption Algorithm for AEAD algorithms . . . . . . . . 24 81 5.4. Encryption algorithm for AE algorithms . . . . . . . . . 26 82 6. MAC Objects . . . . . . . . . . . . . . . . . . . . . . . . . 27 83 6.1. MAC Message with Recipients . . . . . . . . . . . . . . . 28 84 6.2. MAC Messages with Implicit Key . . . . . . . . . . . . . 29 85 6.3. How to compute and verify a MAC . . . . . . . . . . . . . 30 86 7. Key Structure . . . . . . . . . . . . . . . . . . . . . . . . 31 87 7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 32 88 8. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 34 89 8.1. ECDSA . . . . . . . . . . . . . . . . . . . . . . . . . . 35 90 8.1.1. Security Considerations . . . . . . . . . . . . . . . 37 91 8.2. Edwards-curve Digital Signature Algorithms (EdDSA) . . . 38 92 8.2.1. Security Considerations . . . . . . . . . . . . . . . 39 93 9. Message Authentication (MAC) Algorithms . . . . . . . . . . . 39 94 9.1. Hash-based Message Authentication Codes (HMAC) . . . . . 39 95 9.1.1. Security Considerations . . . . . . . . . . . . . . . 41 96 9.2. AES Message Authentication Code (AES-CBC-MAC) . . . . . . 41 97 9.2.1. Security Considerations . . . . . . . . . . . . . . . 42 98 10. Content Encryption Algorithms . . . . . . . . . . . . . . . . 42 99 10.1. AES GCM . . . . . . . . . . . . . . . . . . . . . . . . 43 100 10.1.1. Security Considerations . . . . . . . . . . . . . . 44 101 10.2. AES CCM . . . . . . . . . . . . . . . . . . . . . . . . 44 102 10.2.1. Security Considerations . . . . . . . . . . . . . . 47 103 10.3. ChaCha20 and Poly1305 . . . . . . . . . . . . . . . . . 47 104 10.3.1. Security Considerations . . . . . . . . . . . . . . 48 105 11. Key Derivation Functions (KDF) . . . . . . . . . . . . . . . 48 106 11.1. HMAC-based Extract-and-Expand Key Derivation Function 107 (HKDF) . . . . . . . . . . . . . . . . . . . . . . . . . 49 108 11.2. Context Information Structure . . . . . . . . . . . . . 51 109 12. Recipient Algorithm Classes . . . . . . . . . . . . . . . . . 54 110 12.1. Direct Encryption . . . . . . . . . . . . . . . . . . . 55 111 12.1.1. Direct Key . . . . . . . . . . . . . . . . . . . . . 55 112 12.1.2. Direct Key with KDF . . . . . . . . . . . . . . . . 56 113 12.2. Key Wrapping . . . . . . . . . . . . . . . . . . . . . . 58 114 12.2.1. AES Key Wrapping . . . . . . . . . . . . . . . . . . 58 115 12.3. Key Encryption . . . . . . . . . . . . . . . . . . . . . 59 116 12.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 60 117 12.4.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 61 118 12.5. Key Agreement with KDF . . . . . . . . . . . . . . . . . 63 119 12.5.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 64 120 13. Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 121 13.1. Elliptic Curve Keys . . . . . . . . . . . . . . . . . . 66 122 13.1.1. Double Coordinate Curves . . . . . . . . . . . . . . 67 123 13.2. Octet Key Pair . . . . . . . . . . . . . . . . . . . . . 68 124 13.3. Symmetric Keys . . . . . . . . . . . . . . . . . . . . . 69 125 14. CBOR Encoder Restrictions . . . . . . . . . . . . . . . . . . 70 126 15. Application Profiling Considerations . . . . . . . . . . . . 70 127 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 72 128 16.1. CBOR Tag assignment . . . . . . . . . . . . . . . . . . 72 129 16.2. COSE Header Parameter Registry . . . . . . . . . . . . . 72 130 16.3. COSE Header Algorithm Label Table . . . . . . . . . . . 73 131 16.4. COSE Algorithm Registry . . . . . . . . . . . . . . . . 73 132 16.5. COSE Key Common Parameter Registry . . . . . . . . . . . 74 133 16.6. COSE Key Type Parameter Registry . . . . . . . . . . . . 75 134 16.7. COSE Elliptic Curve Registry . . . . . . . . . . . . . . 76 135 16.8. Media Type Registrations . . . . . . . . . . . . . . . . 76 136 16.8.1. COSE Security Message . . . . . . . . . . . . . . . 76 137 16.8.2. COSE Key media type . . . . . . . . . . . . . . . . 77 138 16.9. CoAP Content Format Registrations . . . . . . . . . . . 79 139 16.10. Expert Review Instructions . . . . . . . . . . . . . . . 80 140 17. Implementation Status . . . . . . . . . . . . . . . . . . . . 81 141 17.1. Author's Versions . . . . . . . . . . . . . . . . . . . 82 142 17.2. COSE Testing Library . . . . . . . . . . . . . . . . . . 82 143 18. Security Considerations . . . . . . . . . . . . . . . . . . . 83 144 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 85 145 19.1. Normative References . . . . . . . . . . . . . . . . . . 85 146 19.2. Informative References . . . . . . . . . . . . . . . . . 86 147 Appendix A. Making Mandatory Algorithm Header Optional . . . . . 88 148 A.1. Algorithm Identification . . . . . . . . . . . . . . . . 89 149 A.2. Counter Signature Without Headers . . . . . . . . . . . . 92 150 Appendix B. Three Levels of Recipient Information . . . . . . . 92 151 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 93 152 C.1. Examples of Signed Message . . . . . . . . . . . . . . . 94 153 C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 94 154 C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 94 155 C.1.3. Counter Signature . . . . . . . . . . . . . . . . . . 95 156 C.1.4. Signature w/ Criticality . . . . . . . . . . . . . . 96 157 C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 97 158 C.2.1. Single ECDSA signature . . . . . . . . . . . . . . . 97 159 C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 98 160 C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 98 161 C.3.2. Direct plus Key Derivation . . . . . . . . . . . . . 99 162 C.3.3. Counter Signature on Encrypted Content . . . . . . . 100 163 C.3.4. Encrypted Content with External Data . . . . . . . . 102 164 C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 102 165 C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 102 166 C.4.2. Encrypted Message w/ a Partial IV . . . . . . . . . . 103 167 C.5. Examples of MAC messages . . . . . . . . . . . . . . . . 103 168 C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 103 169 C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 104 170 C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 105 171 C.5.4. Multi-recipient MAC message . . . . . . . . . . . . . 106 172 C.6. Examples of MAC0 messages . . . . . . . . . . . . . . . . 107 173 C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 108 174 C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 108 175 C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 108 176 C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 109 177 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 111 178 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 112 180 1. Introduction 182 There has been an increased focus on the small, constrained devices 183 that make up the Internet of Things (IOT). One of the standards that 184 has come out of this process is the Concise Binary Object 185 Representation (CBOR) [RFC7049]. CBOR extended the data model of the 186 JavaScript Object Notation (JSON) [RFC7159] by allowing for binary 187 data among other changes. CBOR is being adopted by several of the 188 IETF working groups dealing with the IOT world as their encoding of 189 data structures. CBOR was designed specifically to be both small in 190 terms of messages transport and implementation size as well having a 191 schema free decoder. A need exists to provide message security 192 services for IOT and using CBOR as the message encoding format makes 193 sense. 195 The JOSE working group produced a set of documents 196 [RFC7515][RFC7516][RFC7517][RFC7518] using JSON that specified how to 197 process encryption, signatures and message authentication (MAC) 198 operations, and how to encode keys using JSON. This document does 199 the same work for use with the CBOR document format. While there is 200 a strong attempt to keep the flavor of the original JOSE documents, 201 two considerations are taken into account: 203 o CBOR has capabilities that are not present in JSON and should be 204 used. One example of this is the fact that CBOR has a method of 205 encoding binary directly without first converting it into a base64 206 encoded string. 208 o COSE is not a direct copy of the JOSE specification. In the 209 process of creating COSE, decisions that were made for JOSE were 210 re-examined. In many cases different results were decided on as 211 the criteria was not always the same. 213 1.1. Design changes from JOSE 215 o Define a single top level message structure so that encrypted, 216 signed and MACed messages can easily identified and still have a 217 consistent view. 219 o Signed messages separate the concept of protected and unprotected 220 parameters that are for the content and the signature. 222 o MAC messages are separated from signed messages. 224 o MAC messages have the ability to use the same set of recipient 225 algorithms as enveloped messages for obtaining the MAC 226 authentication key. 228 o Use binary encodings for binary data rather than base64url 229 encodings. 231 o Combine the authentication tag for encryption algorithms with the 232 ciphertext. 234 o The set of cryptographic algorithms has been expanded in some 235 directions, and trimmed in others. 237 1.2. Requirements Terminology 239 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 240 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 241 "OPTIONAL" in this document are to be interpreted as described in 242 [RFC2119]. 244 When the words appear in lower case, their natural language meaning 245 is used. 247 1.3. CBOR Grammar 249 There currently is no standard CBOR grammar available for use by 250 specifications. We therefore describe the CBOR structures in prose. 252 The document was developed by first working on the grammar and then 253 developing the prose to go with it. An artifact of this is that the 254 prose was written using the primitive type strings defined by CBOR 255 Data Definition Language (CDDL) [I-D.greevenbosch-appsawg-cbor-cddl]. 256 In this specification, the following primitive types are used: 258 any - non-specific value that permits all CBOR values to be placed 259 here. 261 bool - a boolean value (true: major type 7, value 21; false: major 262 type 7, value 20). 264 bstr - byte string (major type 2). 266 int - an unsigned integer or a negative integer. 268 nil - a null value (major type 7, value 22). 270 nint - a negative integer (major type 1). 272 tstr - a UTF-8 text string (major type 3). 274 uint - an unsigned integer (major type 0). 276 As well as the prose description, a version of a CBOR grammar is 277 presented in CDDL. Since CDDL has not be published as an RFC, this 278 grammar may not work with the final version of CDDL. The CDDL 279 grammar is informational, the prose description is normative. 281 The collected CDDL can be extracted from the XML version of this 282 document via the following XPath expression below. (Depending on the 283 XPath evaluator one is using, it may be necessary to deal with > 284 as an entity.) 285 //artwork[@type='CDDL']/text() 287 CDDL expects the initial non-terminal symbol to be the first symbol 288 in the file. For this reason the first fragment of CDDL is presented 289 here. 291 start = COSE_Messages / COSE_Key / COSE_KeySet / Internal_Types 293 ; This is define to make the tool quieter 294 Internal_Types = Sig_structure / Enc_structure / MAC_structure / 295 COSE_KDF_Context 297 The non-terminal Internal_Types is defined for dealing with the 298 automated validation tools used during the writing of this document. 299 It references those non-terminals that are used for security 300 computations, but are not emitted for transport. 302 1.4. CBOR Related Terminology 304 In JSON, maps are called objects and only have one kind of map key: a 305 string. In COSE, we use strings, negative integers and unsigned 306 integers as map keys. The integers are used for compactness of 307 encoding and easy comparison. Since the work "key" is mainly used in 308 its other meaning, as a cryptographic key, we use the term "label" 309 for this usage as a map key. 311 The presence of a label in a map which is not a string or an integer 312 is an error. Applications can either fail processing or process 313 messages with incorrect labels, however they MUST NOT create messages 314 with incorrect labels. 316 A CDDL grammar fragment is defined that defines the non-terminals 317 'label' as in the previous paragraph and 'values' which permits any 318 value to be used. 320 label = int / tstr 321 values = any 323 1.5. Document Terminology 325 In this document we use the following terminology: 327 Byte is a synonym for octet. 329 Constrained Application Protocol (CoAP) is a specialized web transfer 330 protocol for use in constrained systems. It is defined in [RFC7252]. 332 2. Basic COSE Structure 334 The COSE Message structure is designed so that there can be a large 335 amount of common code when parsing and processing the different 336 security messages. All of the message structures are built on the 337 CBOR array type. The first three elements of the array contain the 338 same information. 340 1. The set of protected header parameters wrapped in a bstr. 342 2. The set of unprotected header parameters as a map. 344 3. The content of the message. The content is either the plain text 345 or the cipher text as appropriate. The content may be detached, 346 but the location is still used. The content is wrapped in a bstr 347 when present and is a nil value when detached. 349 Elements after this point are dependent on the specific message type. 351 Identification of which type of message has been presented is done by 352 the following method: 354 1. The specific message type is known from the context. This may be 355 defined by a marker in the containing structure or by 356 restrictions specified by the application protocol. 358 2. The message type is identified by a CBOR tag. This document 359 defines a CBOR tag for each of the message structures. These 360 tags can be found in Table 1. 362 3. When a COSE object is carried in a media type of application/ 363 cose, the optional parameter 'cose-type' can be used to identify 364 the embedded object. The parameter is OPTIONAL if the tagged 365 version of the structure is used. The parameter is REQUIRED if 366 the untagged version of the structure is used. The value to use 367 with the parameter for each of the structures can be found in 368 Table 1. 370 4. When a COSE object is carried as a CoAP payload, the CoAP content 371 type parameter can be used to identify the message content. The 372 CoAP content types can be found in Table 26. The CBOR tag for 373 the message structure is not required as each security message is 374 uniquely identified. 376 +-------+---------------+---------------+---------------------------+ 377 | CBOR | cose-type | Data Item | Semantics | 378 | Tag | | | | 379 +-------+---------------+---------------+---------------------------+ 380 | TBD1 | cose-sign | COSE_Sign | COSE Signed Data Object | 381 | | | | | 382 | TBD7 | cose-sign1 | COSE_Sign1 | COSE Single Signer Data | 383 | | | | Object | 384 | | | | | 385 | TBD2 | cose-encrypt | COSE_Encrypt | COSE Encrypted Data | 386 | | | | Object | 387 | | | | | 388 | TBD3 | cose-encrypt1 | COSE_Encrypt1 | COSE Single Recipient | 389 | | | | Encrypted Data Object | 390 | | | | | 391 | TBD4 | cose-mac | COSE_Mac | COSE Mac-ed Data Object | 392 | | | | | 393 | TBD6 | cose-mac0 | COSE_Mac0 | COSE Mac w/o Recipients | 394 | | | | Object | 395 | | | | | 396 | TBD5 | N/A | COSE_Key, | COSE Key or COSE Key Set | 397 | | | COSE_KeySet | Object | 398 +-------+---------------+---------------+---------------------------+ 400 Table 1: COSE Object Identification 402 The following CDDL fragment identifies all of the top level messages 403 defined in this document. Separate non-terminals are defined for the 404 tagged and the untagged versions of the messages. 406 COSE_Messages = COSE_Untagged_Message / COSE_Tagged_Message 408 COSE_Untagged_Message = COSE_Sign / COSE_Sign1 / 409 COSE_Encrypt / COSE_Encrypt1 / 410 COSE_Mac / COSE_Mac0 412 COSE_Tagged_Message = COSE_Sign_Tagged / COSE_Sign1_Tagged / 413 COSE_Encrypt_Tagged / COSE_Encrypt1_Tagged / 414 COSE_Mac_Tagged / COSE_Mac0_Tagged 416 3. Header Parameters 418 The structure of COSE has been designed to have two buckets of 419 information that are not considered to be part of the payload itself, 420 but are used for holding information about content, algorithms, keys, 421 or evaluation hints for the processing of the layer. These two 422 buckets are available for use in all of the structures except for 423 keys. While these buckets are present, they may not all be usable in 424 all instances. For example, while the protected bucket is defined as 425 part of the recipient structure, some of the algorithms used for 426 recipient structures do not provide for authenticated data. If this 427 is the case, the protected bucket is left empty. 429 Both buckets are implemented as CBOR maps. The map key is a 'label' 430 (Section 1.4). The value portion is dependent on the definition for 431 the label. Both maps use the same set of label/value pairs. The 432 integer and string values for labels has been divided into several 433 sections with a standard range, a private range, and a range that is 434 dependent on the algorithm selected. The defined labels can be found 435 in the 'COSE Header Parameters' IANA registry (Section 16.2). 437 Two buckets are provided for each layer: 439 protected: Contains parameters about the current layer that are to 440 be cryptographically protected. This bucket MUST be empty if it 441 is not going to be included in a cryptographic computation. This 442 bucket is encoded in the message as a binary object. This value 443 is obtained by CBOR encoding the protected map and wrapping it in 444 a bstr object. Senders SHOULD encode an empty protected map as a 445 zero length binary object (it is both shorter and the version used 446 in the authentication structures). Recipients MUST accept both a 447 zero length binary value and a zero length map encoded in the 448 binary value. The wrapping allows for the encoding of the 449 protected map to be transported with a greater chance that it will 450 not be altered in transit. (Badly behaved intermediates could 451 decode and re-encode, but this will result in a failure to verify 452 unless the re-encoded byte string is identical to the decoded byte 453 string.) This finesses the problem of all parties needing to be 454 able to do a common canonical encoding. 456 unprotected: Contains parameters about the current layer that are 457 not cryptographically protected. 459 Only parameters that deal with the current layer are to be placed at 460 that layer. As an example of this, the parameter 'content type' 461 describes the content of the message being carried in the message. 462 As such, this parameter is placed only in the content layer and is 463 not placed in the recipient or signature layers. In principle, one 464 should be able to process any given layer without reference to any 465 other layer. (With the exception of the COSE_Sign structure, the 466 only data that needs to cross layers is the cryptographic key.) 468 The buckets are present in all of the security objects defined in 469 this document. The fields in order are the 'protected' bucket (as a 470 CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map' 471 type). The presence of both buckets is required. The parameters 472 that go into the buckets come from the IANA "COSE Header Parameters" 473 (Section 16.2). Some common parameters are defined in the next 474 section, but a number of parameters are defined throughout this 475 document. 477 Labels in each of the maps MUST be unique. When processing messages, 478 if a label appears multiple times the message MUST be rejected as 479 malformed. Applications SHOULD perform the same checks that the 480 labels appearing in the protected and unprotected headers are unique 481 as well. If the message is not rejected as malformed, attributes 482 MUST be obtained from the protected bucket before they are obtained 483 from the unprotected bucket. 485 The following CDDL fragment represents the two header buckets. A 486 group Headers is defined in CDDL which represents the two buckets in 487 which attributes are placed. This group is used to provide these two 488 fields consistently in all locations. A type is also defined which 489 represents the map of header values. It uses forward references to a 490 group definition of headers for generic and algorithms. 492 Headers = ( 493 protected : bstr, ; Contains a header_map 494 unprotected : header_map 495 ) 497 header_map = { 498 Generic_Headers, 499 ; Algorithm_Headers, 500 * label => values 501 } 503 3.1. Common COSE Headers Parameters 505 This section defines a set of common header parameters. A summary of 506 these parameters can be found in Table 2. This table should be 507 consulted to determine the value of label as well as the type of the 508 value. 510 The set of header parameters defined in this section are: 512 alg This parameter is used to indicate the algorithm used for the 513 security processing. This parameter MUST be present at each level 514 of a signed, encrypted or authenticated message except the 515 COSE_Sign structure. When the algorithm supports authenticating 516 associated data, this parameter MUST be in the protected header 517 bucket. The value is taken from the 'COSE Algorithm Registry' 518 (see Section 16.4). 520 crit The parameter is used to indicate which protected header labels 521 an application that is processing a message is required to 522 understand. Parameters defined in this document do not need to be 523 included as they should be understood by all implementations. 524 When present, this parameter MUST be placed in the protected 525 header bucket. The array MUST have at least one value in it. 526 Not all labels need to be included in the 'crit' parameter. The 527 rules for deciding which header labels are placed in the array 528 are: 530 * Integer labels in the range of 0 to 8 SHOULD be omitted. 532 * Integer labels in the range -1 to -255 can be omitted as they 533 are algorithm dependent. If an application can correctly 534 process an algorithm, it can be assumed that it will correctly 535 process all of the common parameters associated with that 536 algorithm. (The algorithm range is -1 to -65536, the higher 537 end is for more optional algorithm specific items.) 539 * Labels for parameters required for an application MAY be 540 omitted. Applications should have a statement if the label can 541 be omitted. 543 The header parameter values indicated by 'crit' can be processed 544 by either the security library code or by an application using a 545 security library, the only requirement is that the parameter is 546 processed. If the 'crit' value list includes a value for which 547 the parameter is not in the protected bucket, this is a fatal 548 error in processing the message. 550 content type This parameter is used to indicate the content type of 551 the data in the payload or ciphertext fields. Integers are from 552 the 'CoAP Content-Formats' IANA registry table. Strings are from 553 the IANA 'Media Types' registry. Applications SHOULD provide this 554 parameter if the content structure is potentially ambiguous. 556 kid This parameter identifies one piece of data that can be used as 557 input to find the needed cryptographic key. The value of this 558 parameter can be matched against the 'kid' member in a COSE_Key 559 structure. Other methods of key distribution can define an 560 equivalent field to be matched. Applications MUST NOT assume that 561 'kid' values are unique. There may be more than one key with the 562 same 'kid' value, it may be required that all of the keys need to 563 be checked to find the correct one. The internal structure of 564 'kid' values is not defined and cannot be relied on by 565 applications. Key identifier values are hints about which key to 566 use. They are not directly a security critical field. For this 567 reason, they can be placed in the unprotected headers bucket. 569 Initialization Vector This parameter holds the Initialization Vector 570 (IV) value. For some symmetric encryption algorithms this may be 571 referred to as a nonce. As the IV is authenticated by encryption 572 process, it can be placed in the unprotected header bucket. 574 Partial Initialization Vector This parameter holds a part of the IV 575 value. When using the COSE_Encrypt1 structure, a portion of the 576 IV can be part of the context associated with the key. This field 577 is used to carry a value that causes the IV to be changed for each 578 message. As the IV is authenticated by the encryption process, 579 this value can be placed in the unprotected header bucket. The 580 'Initialization Vector' and 'Partial Initialization Vector' 581 parameters MUST NOT be present in the same security layer. 582 The message IV is generated by the following steps: 584 1. Left pad the partial IV with zeros to the length of IV. 586 2. XOR the padded partial IV with the context IV. 588 counter signature This parameter holds a counter signature value. 589 Counter signatures provide a method of having a second party sign 590 some data. The counter signature can occur as an unprotected 591 attribute in any of the following structures: COSE_Sign, 592 COSE_Sign1, COSE_Signature, COSE_Encrypt, COSE_recipient, 593 COSE_Encrypt1, COSE_Mac and COSE_Mac0. These structures all have 594 the same beginning elements so that a consistent calculation of 595 the counter signature can be computed. Details on computing 596 counter signatures are found in Section 4.5. 598 +-----------+-------+----------------+-------------+----------------+ 599 | name | label | value type | value | description | 600 | | | | registry | | 601 +-----------+-------+----------------+-------------+----------------+ 602 | alg | 1 | int / tstr | COSE | Cryptographic | 603 | | | | Algorithm | algorithm to | 604 | | | | Registry | use | 605 | | | | | | 606 | crit | 2 | [+ label] | COSE Header | Critical | 607 | | | | Label | headers to be | 608 | | | | Registry | understood | 609 | | | | | | 610 | content | 3 | tstr / int | CoAP | Content type | 611 | type | | | Content- | of the payload | 612 | | | | Formats or | | 613 | | | | Media Types | | 614 | | | | registry | | 615 | | | | | | 616 | kid | 4 | bstr | | key identifier | 617 | | | | | | 618 | IV | 5 | bstr | | Full | 619 | | | | | Initialization | 620 | | | | | Vector | 621 | | | | | | 622 | Partial | 6 | bstr | | Partial | 623 | IV | | | | Initialization | 624 | | | | | Vector | 625 | | | | | | 626 | counter | 7 | COSE_Signature | | CBOR encoded | 627 | signature | | / [+ | | signature | 628 | | | COSE_Signature | | structure | 629 | | | ] | | | 630 +-----------+-------+----------------+-------------+----------------+ 632 Table 2: Common Header Parameters 634 The CDDL fragment that represents the set of headers defined in this 635 section is given below. Each of the headers is tagged as optional 636 because they do not need to be in every map, headers required in 637 specific maps are discussed above. 639 Generic_Headers = ( 640 ? 1 => int / tstr, ; algorithm identifier 641 ? 2 => [+label], ; criticality 642 ? 3 => tstr / int, ; content type 643 ? 4 => bstr, ; key identifier 644 ? 5 => bstr, ; IV 645 ? 6 => bstr, ; Partial IV 646 ? 7 => COSE_Signature / [+COSE_Signature] ; Counter signature 647 ) 649 4. Signing Objects 651 COSE supports two different signature structures. COSE_Sign allows 652 for one or more signers to be applied to a single content. 653 COSE_Sign1 is restricted to a single signer. The structures cannot 654 be converted between each other, the signature computation includes a 655 parameter identifying which structure is being used. 657 4.1. Signing with One or More Signers 659 The COSE_Sign structure allows for one or more signatures to be 660 applied to a message payload. There are provisions for parameters 661 about the content and parameters about the signature to be carried 662 along with the signature itself. These parameters may be 663 authenticated by the signature, or just present. An example of a 664 parameter about the content is the content type. Examples of 665 parameters about the signature would be the algorithm and key used to 666 create the signature and counter signatures. 668 When more than one signature is present, the successful validation of 669 one signature associated with a given signer is usually treated as a 670 successful signature by that signer. However, there are some 671 application environments where other rules are needed. An 672 application that employs a rule other than one valid signature for 673 each signer must specify those rules. Also, where simple matching of 674 the signer identifier is not sufficient to determine whether the 675 signatures were generated by the same signer, the application 676 specification must describe how to determine which signatures were 677 generated by the same signer. Support of different communities of 678 recipients is the primary reason that signers choose to include more 679 than one signature. For example, the COSE_Sign structure might 680 include signatures generated with the Edwards Digital Signature 681 Algorithm (EdDSA) signature algorithm and with the Elliptic Curve 682 Digital Signature Algorithm (ECDSA) signature algorithm. This allows 683 recipients to verify the signature associated with one algorithm or 684 the other. (The original source of this text is [RFC5652].) More 685 detailed information on multiple signature evaluation can be found in 686 [RFC5752]. 688 The signature structure can be encoded either with or without a tag 689 depending on the context it will be used in. The signature structure 690 is identified by the CBOR tag TBD1. The CDDL fragment that 691 represents this is. 693 COSE_Sign_Tagged = #6.991(COSE_Sign) ; Replace 991 with TBD1 695 A COSE Signed Message is divided into two parts. The CBOR object 696 that carries the body and information about the body is called the 697 COSE_Sign structure. The CBOR object that carries the signature and 698 information about the signature is called the COSE_Signature 699 structure. Examples of COSE Signed Messages can be found in 700 Appendix C.1. 702 The COSE_Sign structure is a CBOR array. The fields of the array in 703 order are: 705 protected as described in Section 3. 707 unprotected as described in Section 3. 709 payload contains the serialized content to be signed. If the 710 payload is not present in the message, the application is required 711 to supply the payload separately. The payload is wrapped in a 712 bstr to ensure that it is transported without changes. If the 713 payload is transported separately (i.e. detached content), then a 714 nil CBOR object is placed in this location and it is the 715 responsibility of the application to ensure that it will be 716 transported without changes. 718 Note: When a signature with message recovery algorithm is used 719 (Section 8), the maximum number of bytes that can be recovered is 720 the length of the payload. The size of the payload is reduced by 721 the number of bytes that will be recovered. If all of the bytes 722 of the payload are consumed, then the payload is encoded as a zero 723 length binary string rather than as being absent. 725 signatures is an array of signatures. Each signature is represented 726 as a COSE_Signature structure. 728 The CDDL fragment which represents the above text for COSE_Sign 729 follows. 731 COSE_Sign = [ 732 Headers, 733 payload : bstr / nil, 734 signatures : [+ COSE_Signature] 735 ] 736 The COSE_Signature structure is a CBOR array. The fields of the 737 array in order are: 739 protected as described in Section 3. 741 unprotected as described in Section 3. 743 signature contains the computed signature value. The type of the 744 field is a bstr. 746 The CDDL fragment which represents the above text for COSE_Signature 747 follows. 749 COSE_Signature = [ 750 Headers, 751 signature : bstr 752 ] 754 4.2. Signing with One Signer 756 The COSE_Sign1 signature structure is used when only one signer is 757 going to be placed on a message. The parameters dealing with the 758 content and the signature are placed in the same pair of buckets 759 rather than having the separation of COSE_Sign. 761 The structure can be encoded either with or without a tag depending 762 on the context it will be used in. The structure is identified by 763 the CBOR tag TBD7. The CDDL fragment that represents this is: 765 COSE_Sign1_Tagged = #6.997(COSE_Sign1) ; Replace 997 with TBD7 767 The CBOR object that carries the body, the signature and the 768 information about the body and signature is called the COSE_Sign1 769 structure. Examples of COSE Single signature messages can be found 770 in Appendix C.2. 772 The COSE_Sign1 structure is a CBOR array. The fields of the array in 773 order are: 775 protected as described in Section 3. 777 unprotected as described in Section 3. 779 payload as described in Section 4.1. 781 signature contains the computed signature value. The type of the 782 field is a bstr. 784 The CDDL fragment which represents the above text for COSE_Sign1 785 follows. 787 COSE_Sign1 = [ 788 Headers, 789 payload : bstr / nil, 790 signature : bstr 791 ] 793 4.3. Externally Supplied Data 795 One of the features that we supply in the COSE document is the 796 ability for applications to provide additional data to be 797 authenticated as part of the security, but that is not carried as 798 part of the COSE object. The primary reason for supporting this can 799 be seen by looking at the CoAP message structure [RFC7252] where the 800 facility exists for options to be carried before the payload. An 801 example of data that can be placed in this location would be CoAP 802 options for transaction ids and nonces to check for replay 803 protection. If the data is in the options section, then it is 804 available for routers to help in performing the replay detection and 805 prevention. However, it may also be desired to protect these values 806 so that if they are be modified in transit it can be detected. 808 This document describes the process for using a byte array of 809 externally supplied authenticated data, however the method of 810 constructing the byte array is a function of the application. 811 Applications that use this feature need to define how the externally 812 supplied authenticated data is to be constructed. Such a 813 construction needs to take into account the following issues: 815 o If multiple items are included, care needs to be taken that data 816 cannot bleed between the items. This is usually addressed by 817 making fields fixed width and/or encoding the length of the field. 818 Using options from CoAP [RFC7252] as an example, these fields use 819 a TLV structure so they can be concatenated without any problems. 821 o If multiple items are included, a defined order for the items 822 needs to be defined. Using options from CoAP as an example, an 823 application could state that the fields are to be ordered by the 824 option number. 826 o Applications need to ensure that the byte stream is going to be 827 the same on both sides. Using options from CoAP might give a 828 problem if the same relative numbering is kept. An intermediate 829 node could insert or remove an option changing how the relative 830 number is done. An application would need to specify that the 831 relative number must be re-encoded to be relative only to the 832 options that are in the external data. 834 4.4. Signing and Verification Process 836 In order to create a signature, a consistent byte stream is needed. 837 This algorithm takes in the body information (COSE_Sign or 838 COSE_Sign1), the signer information (COSE_Signature), and the 839 application data (External). A CBOR array is used to construct the 840 byte stream. The fields of the array in order are: 842 1. A text string identifying the context of the signature. The 843 context string is: 845 "Signature" for signatures using the COSE_Signature structure. 847 "Signature1" for signatures using the COSE_Sign1 structure. 849 "CounterSignature" for signatures used as counter signature 850 attributes. 852 2. The protected attributes from the body structure encoded in a 853 bstr type. If there are no protected attributes, a bstr of 854 length zero is used. 856 3. The protected attributes from the signer structure encoded in a 857 bstr type. If there are no protected attributes, a bstr of 858 length zero is used. This field is omitted for the COSE_Sign1 859 signature structure. 861 4. The protected attributes from the application encoded in a bstr 862 type. If this field is not supplied, it defaults to a zero 863 length binary string. (See Section 4.3 for application guidance 864 on constructing this field.) 866 5. The payload to be signed encoded in a bstr type. The payload is 867 placed here independent of how it is transported. 869 The CDDL fragment which describes the above text is. 871 Sig_structure = [ 872 context: "Signature" / "Signature1" / "CounterSignature", 873 body_protected: bstr, 874 ? sign_protected: bstr, 875 external_aad: bstr, 876 payload: bstr 877 ] 878 How to compute a signature: 880 1. Create a Sig_structure and populate it with the appropriate 881 fields. 883 2. Create the value ToBeSigned by encoding the Sig_structure to a 884 byte string using the encoding described in Section 14. 886 3. Call the signature creation algorithm passing in K (the key to 887 sign with), alg (the algorithm to sign with) and ToBeSigned (the 888 value to sign). 890 4. Place the resulting signature value in the 'signature' field of 891 the array. 893 How to verify a signature: 895 1. Create a Sig_structure object and populate it with the 896 appropriate fields. 898 2. Create the value ToBeSigned by encoding the Sig_structure to a 899 byte string using the encoding described in Section 14. 901 3. Call the signature verification algorithm passing in K (the key 902 to verify with), alg (the algorithm used sign with), ToBeSigned 903 (the value to sign), and sig (the signature to be verified). 905 In addition to performing the signature verification, one must also 906 perform the appropriate checks to ensure that the key is correctly 907 paired with the signing identity and that the appropriate 908 authorization is done. 910 4.5. Computing Counter Signatures 912 Counter signatures provide a method of having a different signature 913 occur on some piece of content. This is normally used to provide a 914 signature on a signature allowing for a proof that a signature 915 existed at a given time (i.e. a Timestamp). In this document we 916 allow for counter signatures to exist in a greater number of 917 environments. As an example, it is possible to place a counter 918 signature in the unprotected attributes of a COSE_Encrypt object. 919 This would allow for an intermediary to either verify that the 920 encrypted byte stream has not been modified, without being able to 921 decrypt it. Or for the intermediary to assert that an encrypted byte 922 stream either existed at a given time or passed through it in terms 923 of routing (i.e. a proxy signature). 925 An example of a counter signature on a signature can be found in 926 Appendix C.1.3. An example of a counter signature in an encryption 927 object can be found in Appendix C.3.3. 929 The creation and validation of counter signatures over the different 930 items relies on the fact that the structure of the objects have the 931 same structure. The elements are a set of protected attributes, a 932 set of unprotected attributes and a body in that order. This means 933 that the Sig_structure can be used in a uniform manner to get the 934 byte stream for processing a signature. If the counter signature is 935 going to be computed over a COSE_Encrypt structure, the 936 body_protected and payload items can be mapped into the Sig_structure 937 in the same manner as from the COSE_Sign structure. 939 It should be noted that only a signature algorithm with appendix (see 940 Section 8) can be used for counter signatures. This is because the 941 body should be able to be processed without having to evaluate the 942 counter signature, and this is not possible for signature schemes 943 with message recovery. 945 5. Encryption Objects 947 COSE supports two different encryption structures. COSE_Encrypt1 is 948 used when a recipient structure is not needed because the key to be 949 used is known implicitly. COSE_Encrypt is used the rest of time 950 time. This includes cases where there are multiple recipients or a 951 recipient algorithm other than direct is used. 953 5.1. Enveloped COSE Structure 955 The enveloped structure allows for one or more recipients of a 956 message. There are provisions for parameters about the content and 957 parameters about the recipient information to be carried in the 958 message. The protected parameters associated with the content are 959 authenticated by the content encryption algorithm. The protected 960 parameters associated with the recipient are authenticated by the 961 recipient algorithm (when the algorithm supports it). Examples of 962 parameters about the content are the type of the content, and the 963 content encryption algorithm. Examples of parameters about the 964 recipient are the recipient's key identifier, the recipient 965 encryption algorithm. 967 The same techniques and structures are used for encrypting both the 968 plain text and the keys used to protect the text. This is different 969 from the approach used by both CMS [RFC5652] and JSON Web Encryption 970 (JWE) [RFC7516] where different structures are used for the content 971 layer and for the recipient layer. Two structures are defined: 972 COSE_Encrypt to hold the encrypted content, and COSE_recipient to 973 hold the encrypted keys for recipients. Examples of encrypted 974 messages can be found in Appendix C.3. 976 The COSE_Encrypt structure can be encoded either with or without a 977 tag depending on the context it will be used in. The structure is 978 identified by the CBOR tag TBD2. The CDDL fragment that represents 979 this is. 981 COSE_Encrypt_Tagged = #6.992(COSE_Encrypt) ; Replace 992 with TBD2 983 The COSE_Encrypt structure is a CBOR array. The fields of the array 984 in order are: 986 protected as described in Section 3. 988 unprotected as described in Section 3. 990 ciphertext contains the cipher text encoded as a bstr. If the 991 ciphertext is to be transported independently of the control 992 information about the encryption process (i.e. detached content) 993 then the field is encoded as a nil value. 995 recipients contains an array of recipient information structures. 996 The type for the recipient information structure is a 997 COSE_recipient. 999 The CDDL fragment that corresponds to the above text is: 1001 COSE_Encrypt = [ 1002 Headers, 1003 ciphertext: bstr / nil, 1004 recipients: [+COSE_recipient] 1005 ] 1007 The COSE_recipient structure is a CBOR array. The fields of the 1008 array in order are: 1010 protected as described in Section 3. 1012 unprotected as described in Section 3. 1014 ciphertext contains the encrypted key encoded as a bstr. If there 1015 is not an encrypted key, then this field is encoded as a nil 1016 value. 1018 recipients contains an array of recipient information structures. 1019 The type for the recipient information structure is a 1020 COSE_recipient. (And example of this can be found in Appendix B.) 1021 If there are no recipient information structures, this element is 1022 absent. 1024 The CDDL fragment that corresponds to the above text for 1025 COSE_recipient is: 1027 COSE_recipient = [ 1028 Headers, 1029 ciphertext: bstr / nil, 1030 ? recipients: [+COSE_recipient] 1031 ] 1033 5.1.1. Recipient Algorithm Classes 1035 An encrypted message consists of an encrypted content and an 1036 encrypted CEK for one or more recipients. The CEK is encrypted for 1037 each recipient, using a key specific to that recipient. The details 1038 of this encryption depends on which class the recipient algorithm 1039 falls into. Specific details on each of the classes can be found in 1040 Section 12. A short summary of the five recipient algorithm classes 1041 is: 1043 direct: The CEK is the same as the identified previously distributed 1044 symmetric key or derived from a previously distributed secret. No 1045 CEK is transported in the message. 1047 symmetric key-encryption keys: The CEK is encrypted using a 1048 previously distributed symmetric KEK. 1050 key agreement: The recipient's public key and a sender's private key 1051 are used to generate a pairwise secret, a KDF is applied to derive 1052 a key, and then the CEK is either the derived key or encrypted by 1053 the derived key. 1055 key transport: The CEK is encrypted with the recipient's public key. 1056 No key transport algorithms are defined in this document. 1058 passwords: The CEK is encrypted in a KEK that is derived from a 1059 password. No password algorithms are defined in this document. 1061 5.2. Single Recipient Encrypted 1063 The COSE_Encrypt1 encrypted structure does not have the ability to 1064 specify recipients of the message. The structure assumes that the 1065 recipient of the object will already know the identity of the key to 1066 be used in order to decrypt the message. If a key needs to be 1067 identified to the recipient, the enveloped structure ought to be 1068 used. 1070 Examples of encrypted messages can be found in Appendix C.3. 1072 The COSE_Encrypt1 structure can be encoded either with or without a 1073 tag depending on the context it will be used in. The COSE_Encrypt1 1074 structure is identified by the CBOR tag TBD3. The CDDL fragment that 1075 represents this is. 1077 COSE_Encrypt1_Tagged = #6.993(COSE_Encrypt1) ; Replace 993 with TBD3 1079 The COSE_Encrypt structure is a CBOR array. The fields of the array 1080 in order are: 1082 protected as described in Section 3. 1084 unprotected as described in Section 3. 1086 ciphertext as described in Section 5.1. 1088 The CDDL fragment for COSE_Encrypt1 that corresponds to the above 1089 text is: 1091 COSE_Encrypt1 = [ 1092 Headers, 1093 ciphertext: bstr / nil, 1094 ] 1096 5.3. Encryption Algorithm for AEAD algorithms 1098 The encryption algorithm for AEAD algorithms is fairly simple. The 1099 first step is to create a consistent byte stream for the 1100 authenticated data structure. For this purpose we use a CBOR array, 1101 the fields of the array in order are: 1103 1. A text string identifying the context of the authenticated data 1104 structure. The context string is: 1106 "Encrypt1" for the content encryption of an COSE_Encrypt1 data 1107 structure. 1109 "Encrypt" for the first level of an COSE_Encrypt data structure 1110 (i.e. for content encryption). 1112 "Enc_Recipient" for a recipient encoding to be placed in an 1113 COSE_Encrypt data structure. 1115 "Mac_Recipient" for a recipient encoding to be placed in a MAC 1116 message structure. 1118 "Rec_Recipient" for a recipient encoding to be placed in a 1119 recipient structure. 1121 2. The protected attributes from the body structure encoded in a 1122 bstr type. If there are no protected attributes, a bstr of 1123 length zero is used. 1125 3. The protected attributes from the application encoded in a bstr 1126 type. If this field is not supplied, it defaults to a zero 1127 length bstr. (See Section 4.3 for application guidance on 1128 constructing this field.) 1130 The CDDL fragment which describes the above text is: 1132 Enc_structure = [ 1133 context : "Encrypt" / "Encrypt1" / "Enc_Recipient" / 1134 "Mac_Recipient" / "Rec_Recipient", 1135 protected: bstr, 1136 external_aad: bstr 1137 ] 1139 How to encrypt a message: 1141 1. Create a Enc_structure and populate it with the appropriate 1142 fields. 1144 2. Encode the Enc_structure to a byte stream (AAD) using the 1145 encoding described in Section 14. 1147 3. Determine the encryption key. This step is dependent on the 1148 class of recipient algorithm being used. For: 1150 No Recipients: The key to be used is determined by the algorithm 1151 and key at the current level. 1153 Direct and Direct Key Agreement: The key is determined by the 1154 key and algorithm in the recipient structure. The encryption 1155 algorithm and size of the key to be used are inputs into the 1156 KDF used for the recipient. (For direct, the KDF can be 1157 thought of as the identity operation.) 1159 Other: The key is randomly generated. 1161 4. Call the encryption algorithm with K (the encryption key to use), 1162 P (the plain text) and AAD. Place the returned cipher text into 1163 the 'ciphertext' field of the structure. 1165 5. For recipients of the message, recursively perform the encryption 1166 algorithm for that recipient using the encryption key as the 1167 plain text. 1169 How to decrypt a message: 1171 1. Create a Enc_structure and populate it with the appropriate 1172 fields. 1174 2. Encode the Enc_structure to a byte stream (AAD) using the 1175 encoding described in Section 14. 1177 3. Determine the decryption key. This step is dependent on the 1178 class of recipient algorithm being used. For: 1180 No Recipients: The key to be used is determined by the algorithm 1181 and key at the current level. 1183 Direct and Direct Key Agreement: The key is determined by the 1184 key and algorithm in the recipient structure. The encryption 1185 algorithm and size of the key to be used are inputs into the 1186 KDF used for the recipient. (For direct, the KDF can be 1187 thought of as the identity operation.) 1189 Other: The key is determined by decoding and decrypting one of 1190 the recipient structures. 1192 4. Call the decryption algorithm with K (the decryption key to use), 1193 C (the cipher text) and AAD. 1195 5.4. Encryption algorithm for AE algorithms 1197 How to encrypt a message: 1199 1. Verify that the 'protected' field is absent. 1201 2. Verify that there was no external additional authenticated data 1202 supplied for this operation. 1204 3. Determine the encryption key. This step is dependent on the 1205 class of recipient algorithm being used. For: 1207 No Recipients: The key to be used is determined by the algorithm 1208 and key at the current level. 1210 Direct and Direct Key Agreement: The key is determined by the 1211 key and algorithm in the recipient structure. The encryption 1212 algorithm and size of the key to be used are inputs into the 1213 KDF used for the recipient. (For direct, the KDF can be 1214 thought of as the identity operation.) 1216 Other: The key is randomly generated. 1218 4. Call the encryption algorithm with K (the encryption key to use) 1219 and the P (the plain text). Place the returned cipher text into 1220 the 'ciphertext' field of the structure. 1222 5. For recipients of the message, recursively perform the encryption 1223 algorithm for that recipient using the encryption key as the 1224 plain text. 1226 How to decrypt a message: 1228 1. Verify that the 'protected' field is absent. 1230 2. Verify that there was no external additional authenticated data 1231 supplied for this operation. 1233 3. Determine the decryption key. This step is dependent on the 1234 class of recipient algorithm being used. For: 1236 No Recipients: The key to be used is determined by the algorithm 1237 and key at the current level. 1239 Direct and Direct Key Agreement: The key is determined by the 1240 key and algorithm in the recipient structure. The encryption 1241 algorithm and size of the key to be used are inputs into the 1242 KDF used for the recipient. (For direct, the KDF can be 1243 thought of as the identity operation.) 1245 Other: The key is determined by decoding and decrypting one of 1246 the recipient structures. 1248 4. Call the decryption algorithm with K (the decryption key to use), 1249 and C (the cipher text). 1251 6. MAC Objects 1253 COSE supports two different MAC structures. COSE_MAC0 is used when a 1254 recipient structure is not needed because the key to be used is 1255 implicitly known. COSE_MAC is used for all other cases. These 1256 include a requirement for multiple recipients, the key being unknown, 1257 a recipient algorithm of other than direct. 1259 In this section we describe the structure and methods to be used when 1260 doing MAC authentication in COSE. This document allows for the use 1261 of all of the same classes of recipient algorithms as are allowed for 1262 encryption. 1264 When using MAC operations, there are two modes in which it can be 1265 used. The first is just a check that the content has not been 1266 changed since the MAC was computed. Any class of recipient algorithm 1267 can be used for this purpose. The second mode is to both check that 1268 the content has not been changed since the MAC was computed, and to 1269 use the recipient algorithm to verify who sent it. The classes of 1270 recipient algorithms that support this are those that use a pre- 1271 shared secret or do static-static key agreement (without the key wrap 1272 step). In both of these cases, the entity that created and sent the 1273 message MAC can be validated. (This knowledge of sender assumes that 1274 there are only two parties involved and you did not send the message 1275 yourself.) 1277 6.1. MAC Message with Recipients 1279 The multiple recipient MAC message uses two structures, the COSE_Mac 1280 structure defined in this section for carrying the body and the 1281 COSE_recipient structure (Section 5.1) to hold the key used for the 1282 MAC computation. Examples of MAC messages can be found in 1283 Appendix C.5. 1285 The MAC structure can be encoded either with or without a tag 1286 depending on the context it will be used in. The MAC structure is 1287 identified by the CBOR tag TBD4. The CDDL fragment that represents 1288 this is: 1290 COSE_Mac_Tagged = #6.994(COSE_Mac) ; Replace 994 with TBD4 1292 The COSE_Mac structure is a CBOR array. The fields of the array in 1293 order are: 1295 protected as described in Section 3. 1297 unprotected as described in Section 3. 1299 payload contains the serialized content to be MACed. If the payload 1300 is not present in the message, the application is required to 1301 supply the payload separately. The payload is wrapped in a bstr 1302 to ensure that it is transported without changes. If the payload 1303 is transported separately (i.e. detached content), then a nil CBOR 1304 value is placed in this location and it is the responsibility of 1305 the application to ensure that it will be transported without 1306 changes. 1308 tag contains the MAC value. 1310 recipients as described in Section 5.1. 1312 The CDDL fragment which represents the above text for COSE_Mac 1313 follows. 1315 COSE_Mac = [ 1316 Headers, 1317 payload: bstr / nil, 1318 tag: bstr, 1319 recipients: [+COSE_recipient] 1320 ] 1322 6.2. MAC Messages with Implicit Key 1324 In this section we describe the structure and methods to be used when 1325 doing MAC authentication for those cases where the recipient is 1326 implicitly known. 1328 The MAC message uses the COSE_Mac0 structure defined in this section 1329 for carrying the body. Examples of MAC messages with an implicit key 1330 can be found in Appendix C.6. 1332 The MAC structure can be encoded either with or without a tag 1333 depending on the context it will be used in. The MAC structure is 1334 identified by the CBOR tag TBD6. The CDDL fragment that represents 1335 this is: 1337 COSE_Mac0_Tagged = #6.996(COSE_Mac0) ; Replace 996 with TBD6 1339 The COSE_Mac0 structure is a CBOR array. The fields of the array in 1340 order are: 1342 protected as described in Section 3. 1344 unprotected as described in Section 3. 1346 payload as described in Section 6.1. 1348 tag contains the MAC value. 1350 The CDDL fragment which corresponds to the above text is: 1352 COSE_Mac0 = [ 1353 Headers, 1354 payload: bstr / nil, 1355 tag: bstr, 1356 ] 1358 6.3. How to compute and verify a MAC 1360 In order to get a consistent encoding of the data to be 1361 authenticated, the MAC_structure is used to have a canonical form. 1362 The MAC_structure is a CBOR array. The fields of the MAC_structure 1363 in order are: 1365 1. A text string that identifies the structure that is being 1366 encoded. This string is "MAC" for the COSE_Mac structure. This 1367 string is "MAC0" for the COSE_Mac0 structure. 1369 2. The protected attributes from the COSE_MAC structure. If there 1370 are no protected attributes, a zero length bstr is used. 1372 3. If the application has supplied external authenticated data, 1373 encode it as a binary value and place in the MAC_structure. If 1374 there is no external authenticated data, then use a zero length 1375 'bstr'. (See Section 4.3 for application guidance on 1376 constructing this field.) 1378 4. The payload to be MAC-ed encoded in a bstr type. The payload is 1379 placed here independent of how it is transported. 1381 The CDDL fragment that corresponds to the above text is: 1383 MAC_structure = [ 1384 context: "MAC" / "MAC0", 1385 protected: bstr, 1386 external_aad: bstr, 1387 payload: bstr 1388 ] 1390 The steps to compute a MAC are: 1392 1. Create a MAC_structure and populate it with the appropriate 1393 fields. 1395 2. Encode the MAC_structure to a byte stream using the encoding 1396 described in Section 14. 1398 3. Call the MAC creation algorithm passing in K (the key to use), 1399 alg (the algorithm to MAC with) and ToBeMaced (the value to 1400 compute the MAC on). 1402 4. Place the resulting MAC in the 'tag' field of the COSE_Mac 1403 structure. 1405 5. Encrypt and encode the MAC key for each recipient of the message. 1407 How to verify a MAC are: 1409 1. Create a MAC_structure object and populate it with the 1410 appropriate fields. 1412 2. Encode the MAC_structure to a byte stream using the encoding 1413 described in Section 14. 1415 3. Obtain the cryptographic key from one of the recipients of the 1416 message. 1418 4. Call the MAC creation algorithm passing in K (the key to use), 1419 alg (the algorithm to MAC with) and ToBeMaced (the value to 1420 compute the MAC on). 1422 5. Compare the MAC value to the 'tag' field of the COSE_Mac 1423 structure. 1425 7. Key Structure 1427 A COSE Key structure is built on a CBOR map object. The set of 1428 common parameters that can appear in a COSE Key can be found in the 1429 IANA registry 'COSE Key Common Parameter Registry' (Section 16.5). 1430 Additional parameters defined for specific key types can be found in 1431 the IANA registry 'COSE Key Type Parameters' (Section 16.6). 1433 A COSE Key Set uses a CBOR array object as its underlying type. The 1434 values of the array elements are COSE Keys. A Key Set MUST have at 1435 least one element in the array. 1437 Each element in a key set MUST be processed independently. If one 1438 element in a key set is either malformed or uses a key which is not 1439 understood by an application, that key is ignored and the other keys 1440 are processed normally. 1442 The element "kty" is a required element in a COSE_Key map. 1444 The CDDL grammar describing COSE_Key and COSE_KeySet is: 1446 COSE_Key = { 1447 key_kty => tstr / int, 1448 ? key_ops => [+ (tstr / int) ], 1449 ? key_alg => tstr / int, 1450 ? key_kid => bstr, 1451 * label => values 1452 } 1454 COSE_KeySet = [+COSE_Key] 1456 7.1. COSE Key Common Parameters 1458 This document defines a set of common parameters for a COSE Key 1459 object. Table 3 provides a summary of the parameters defined in this 1460 section. There are also parameters that are defined for specific key 1461 types. Key type specific parameters can be found in Section 13. 1463 +---------+-------+----------------+-----------+--------------------+ 1464 | name | label | CBOR type | registry | description | 1465 +---------+-------+----------------+-----------+--------------------+ 1466 | kty | 1 | tstr / int | COSE | Identification of | 1467 | | | | General | the key type | 1468 | | | | Values | | 1469 | | | | | | 1470 | key_ops | 4 | [+ (tstr/int)] | | Restrict set of | 1471 | | | | | permissible | 1472 | | | | | operations | 1473 | | | | | | 1474 | alg | 3 | tstr / int | COSE | Key usage | 1475 | | | | Algorithm | restriction to | 1476 | | | | Values | this algorithm | 1477 | | | | | | 1478 | kid | 2 | bstr | | Key Identification | 1479 | | | | | value - match to | 1480 | | | | | kid in message | 1481 | | | | | | 1482 | Base IV | 5 | bstr | | Base IV to be xor- | 1483 | | | | | ed with Partial | 1484 | | | | | IVs | 1485 +---------+-------+----------------+-----------+--------------------+ 1487 Table 3: Key Map Labels 1489 kty: This parameter is used to identify the family of keys for this 1490 structure, and thus the set of key type specific parameters to be 1491 found. The set of values defined in this document can be found in 1492 Table 21. This parameter MUST be present in a key object. 1493 Implementations MUST verify that the key type is appropriate for 1494 the algorithm being processed. The key type MUST be included as 1495 part of the trust decision process. 1497 alg: This parameter is used to restrict the algorithm that is used 1498 with the key. If this parameter is present in the key structure, 1499 the application MUST verify that this algorithm matches the 1500 algorithm for which the key is being used. If the algorithms do 1501 not match, then this key object MUST NOT be used to perform the 1502 cryptographic operation. Note that the same key can be in a 1503 different key structure with a different or no algorithm 1504 specified, however this is considered to be a poor security 1505 practice. 1507 kid: This parameter is used to give an identifier for a key. The 1508 identifier is not structured and can be anything from a user 1509 provided string to a value computed on the public portion of the 1510 key. This field is intended for matching against a 'kid' 1511 parameter in a message in order to filter down the set of keys 1512 that need to be checked. 1514 key_ops: This parameter is defined to restrict the set of operations 1515 that a key is to be used for. The value of the field is an array 1516 of values from Table 4. Algorithms define the values of key ops 1517 that are permitted to appear and are required for specific 1518 operations. 1520 Base IV: This parameter is defined to carry the base portion of an 1521 IV. It is designed to be used with the partial IV header 1522 parameter defined in Section 3.1. This field provides the ability 1523 to associate a partial IV with a key that is then modified on a 1524 per message basis with the parital IV. 1526 Extreme care needs to be taken when using a Base IV in an 1527 application. Many encryption algorithms loose security if the 1528 same IV is used twice. 1530 If different keys are derived for each sender, starting at the 1531 same base IV is likely to satisfy this condition. If the same key 1532 is used for multiple senders, then the application needs to 1533 provide for a method of dividing the IV space up between the 1534 senders. This could be done by providing a different base point 1535 to start from or a different partial IV to start with and 1536 restricting the number of messages to be sent before re-keying. 1538 +---------+-------+-------------------------------------------------+ 1539 | name | value | description | 1540 +---------+-------+-------------------------------------------------+ 1541 | sign | 1 | The key is used to create signatures. Requires | 1542 | | | private key fields. | 1543 | | | | 1544 | verify | 2 | The key is used for verification of signatures. | 1545 | | | | 1546 | encrypt | 3 | The key is used for key transport encryption. | 1547 | | | | 1548 | decrypt | 4 | The key is used for key transport decryption. | 1549 | | | Requires private key fields. | 1550 | | | | 1551 | wrap | 5 | The key is used for key wrapping. | 1552 | key | | | 1553 | | | | 1554 | unwrap | 6 | The key is used for key unwrapping. Requires | 1555 | key | | private key fields. | 1556 | | | | 1557 | derive | 7 | The key is used for deriving keys. Requires | 1558 | key | | private key fields. | 1559 | | | | 1560 | derive | 8 | The key is used for deriving bits. Requires | 1561 | bits | | private key fields. | 1562 +---------+-------+-------------------------------------------------+ 1564 Table 4: Key Operation Values 1566 The following provides a CDDL fragment which duplicates the 1567 assignment labels from Table 3. 1569 ;key_labels 1570 key_kty=1 1571 key_kid=2 1572 key_alg=3 1573 key_ops=4 1575 8. Signature Algorithms 1577 There are two signature algorithm schemes. The first is signature 1578 with appendix. In this scheme, the message content is processed and 1579 a signature is produced, the signature is called the appendix. This 1580 is the scheme used by algorithms such as ECDSA and RSASSA-PSS. (In 1581 fact the SSA in RSASSA-PSS stands for Signature Scheme with 1582 Appendix.) 1584 The signature functions for this scheme are: 1586 signature = Sign(message content, key) 1588 valid = Verification(message content, key, signature) 1590 The second scheme is signature with message recovery. (An example of 1591 such an algorithm is [PVSig].) In this scheme, the message content 1592 is processed, but part of it is included in the signature. Moving 1593 bytes of the message content into the signature allows for smaller 1594 signatures, the signature size is still potentially large, but the 1595 message content has shrunk. This has implications for systems 1596 implementing these algorithms and for applications that use them. 1597 The first is that the message content is not fully available until 1598 after a signature has been validated. Until that point the part of 1599 the message contained inside of the signature is unrecoverable. The 1600 second is that the security analysis of the strength of the signature 1601 is very much based on the structure of the message content. Messages 1602 which are highly predictable require additional randomness to be 1603 supplied as part of the signature process. In the worst case, it 1604 becomes the same as doing a signature with appendix. Finally, in the 1605 event that multiple signatures are applied to a message, all of the 1606 signature algorithms are going to be required to consume the same 1607 number of bytes of message content. This means that mixing of the 1608 different schemes in a single message is not supported, and if a 1609 recovery signature scheme is used then the same amount of content 1610 needs to be consumed by all of the signatures. 1612 The signature functions for this scheme are: 1614 signature, message sent = Sign(message content, key) 1616 valid, message content = Verification(message sent, key, signature) 1618 Signature algorithms are used with the COSE_Signature and COSE_Sign1 1619 structures. At this time, only signatures with appendixes are 1620 defined for use with COSE, however considerable interest has been 1621 expressed in using a signature with message recovery algorithm due to 1622 the effective size reduction that is possible. Implementations will 1623 need to keep this in mind for later possible integration. 1625 8.1. ECDSA 1627 ECDSA [DSS] defines a signature algorithm using ECC. 1629 The ECDSA signature algorithm is parameterized with a hash function 1630 (h). In the event that the length of the hash function output is 1631 greater than the group of the key, the left-most bytes of the hash 1632 output are used. 1634 The algorithms defined in this document can be found in Table 5. 1636 +-------+-------+---------+------------------+ 1637 | name | value | hash | description | 1638 +-------+-------+---------+------------------+ 1639 | ES256 | -7 | SHA-256 | ECDSA w/ SHA-256 | 1640 | | | | | 1641 | ES384 | -35 | SHA-384 | ECDSA w/ SHA-384 | 1642 | | | | | 1643 | ES512 | -36 | SHA-512 | ECDSA w/ SHA-512 | 1644 +-------+-------+---------+------------------+ 1646 Table 5: ECDSA Algorithm Values 1648 This document defines ECDSA to work only with the curves P-256, P-384 1649 and P-521. This document requires that the curves be encoded using 1650 the 'EC2' key type. Implementations need to check that the key type 1651 and curve are correct when creating and verifying a signature. Other 1652 documents can defined it to work with other curves and points in the 1653 future. 1655 In order to promote interoperability, it is suggested that SHA-256 be 1656 used only with curve P-256, SHA-384 be used only with curve P-384 and 1657 SHA-512 be used with curve P-521. This is aligned with the 1658 recommendation in Section 4 of [RFC5480]. 1660 The signature algorithm results in a pair of integers (R, S). These 1661 integers will the same length as length of the key used for the 1662 signature process. The signature is encoded by converting the 1663 integers into byte strings of the same length as the key size. The 1664 length is rounded up to the nearest byte and is left padded with zero 1665 bits to get to the correct length. The two integers are then 1666 concatenated together to form a byte string that is the resulting 1667 signature. 1669 Using the function defined in [RFC3447] the signature is: 1670 Signature = I2OSP(R, n) | I2OSP(S, n) 1671 where n = ceiling(key_length / 8) 1673 When using a COSE key for this algorithm, the following checks are 1674 made: 1676 o The 'kty' field MUST be present and it MUST be 'EC2'. 1678 o If the 'alg' field present, it MUST match the ECDSA signature 1679 algorithm being used. 1681 o If the 'key_ops' field is present, it MUST include 'sign' when 1682 creating an ECDSA signature. 1684 o If the 'key_ops' field is present, it MUST include 'verify' when 1685 verifying an ECDSA signature. 1687 8.1.1. Security Considerations 1689 The security strength of the signature is no greater than the minimum 1690 of the security strength associated with the bit length of the key 1691 and the security strength of the hash function. 1693 System which have poor random number generation can leak their keys 1694 by signing two different messages with the same value 'k' (the per- 1695 message random value). [RFC6979] provides a method to deal with this 1696 problem by making 'k' be deterministic based on the message content 1697 rather than randomly generated. Applications that specify ECDSA 1698 should evaluate the ability to get good random number generation and 1699 require deterministic signatures where poor random number generation 1700 exists. 1702 Note: Use of this technique a good idea even when good random number 1703 generation exists. Doing so both reduces the possibility of having 1704 the same value of 'k' in two signature operations and allows for 1705 reproducible signature values which helps testing. 1707 There are two substitution attacks that can theoretically be mounted 1708 against the ECDSA signature algorithm. 1710 o Changing the curve used to validate the signature: If one changes 1711 the curve used to validate the signature, then potentially one 1712 could have a two messages with the same signature each computed 1713 under a different curve. The only requirement on the new curve is 1714 that its order be the same as the old one and it be acceptable to 1715 the client. An example would be to change from using the curve 1716 secp256r1 (aka P-256) to using secp256k1. (Both are 256 bit 1717 curves.) We current do not have any way to deal with this version 1718 of the attack except to restrict the overall set of curves that 1719 can be used. 1721 o Change the hash function used to validate the signature: If one 1722 has either two different hash functions of the same length, or one 1723 can truncate a hash function down, then one could potentially find 1724 collisions between the hash functions rather than within a single 1725 hash function. (For example, truncating SHA-512 to 256 bits might 1726 collide with a SHA-256 bit hash value.) This attack can be 1727 mitigated by including the signature algorithm identifier in the 1728 data to be signed. 1730 8.2. Edwards-curve Digital Signature Algorithms (EdDSA) 1732 [I-D.irtf-cfrg-eddsa] describes the elliptic curve signature scheme 1733 Edwards-curve Digital Signature Algorithm (EdDSA). In that document, 1734 the signature algorithm is instantiated using parameters for 1735 edwards25519 and edwards448 curves. The document additionally 1736 describes two variants of the EdDSA algorithm: Pure EdDSA, where no 1737 hash function is applied to the content before signing and, HashEdDSA 1738 where a hash function is applied to the content before signing and 1739 the result of that hash function is signed. For use with COSE, only 1740 the pure EdDSA version is used. This is because it is not expected 1741 that extremely large contents are going to be needed and, based on 1742 the arrangement of the message structure, the entire message is going 1743 to need to be held in memory in order to create or verify a 1744 signature. Thus, the use of an incremental update process would not 1745 be useful. Applications can provide the same features by defining 1746 the content of the message as a hash value and transporting the COSE 1747 message and the content as separate items. 1749 The algorithms defined in this document can be found in Table 6. A 1750 single signature algorithm is defined which can be used for multiple 1751 curves. 1753 +-------+-------+-------------+ 1754 | name | value | description | 1755 +-------+-------+-------------+ 1756 | EdDSA | -8 | EdDSA | 1757 +-------+-------+-------------+ 1759 Table 6: EdDSA Algorithm Values 1761 [I-D.irtf-cfrg-eddsa] describes the method of encoding the signature 1762 value. 1764 When using a COSE key for this algorithm the following checks are 1765 made: 1767 o The 'kty' field MUST be present and it MUST be 'OKP'. 1769 o The 'crv' field MUST be present, and it MUST be a curve defined 1770 for this signature algorithm. 1772 o If the 'alg' field is present, it MUST match 'EdDSA'. 1774 o If the 'key_ops' field is present, it MUST include 'sign' when 1775 creating an EdDSA signature. 1777 o If the 'key_ops' field is present, it MUST include 'verify' when 1778 verifying an EdDSA signature. 1780 8.2.1. Security Considerations 1782 The Edwards curves for EdDSA and ECDH are distinct and should not be 1783 used for the other algorithm. 1785 If batch signature verification is performed, a well-seeded 1786 cryptographic random number generator is REQUIRED. Signing and non- 1787 batch signature verification are deterministic operations and do not 1788 nee random nuber of any kind. 1790 9. Message Authentication (MAC) Algorithms 1792 Message Authentication Codes (MACs) provide data authentication and 1793 integrity protection. They provide either no or very limited data 1794 origination. (One cannot, for example, be used to prove the identity 1795 of the sender to a third party.) 1797 MACs use the same scheme as signature with appendix algorithms. The 1798 message content is processed and an authentication code is produced. 1799 The authentication code is frequently called a tag. 1801 The MAC functions are: 1803 tag = MAC_Create(message content, key) 1805 valid = MAC_Verify(message content, key, tag) 1807 MAC algorithms can be based on either a block cipher algorithm (i.e. 1808 AES-MAC) or a hash algorithm (i.e. HMAC). This document defines a 1809 MAC algorithm using each of these constructions. 1811 MAC algorithms are used in the COSE_Mac and COSE_Mac1 structures. 1813 9.1. Hash-based Message Authentication Codes (HMAC) 1815 The Hash-base Message Authentication Code algorithm (HMAC) 1816 [RFC2104][RFC4231] was designed to deal with length extension 1817 attacks. The algorithm was also designed to allow for new hash 1818 algorithms to be directly plugged in without changes to the hash 1819 function. The HMAC design process has been vindicated as, while the 1820 security of hash algorithms such as MD5 has decreased over time, the 1821 security of HMAC combined with MD5 has not yet been shown to be 1822 compromised [RFC6151]. 1824 The HMAC algorithm is parameterized by an inner and outer padding, a 1825 hash function (h) and an authentication tag value length. For this 1826 specification, the inner and outer padding are fixed to the values 1827 set in [RFC2104]. The length of the authentication tag corresponds 1828 to the difficulty of producing a forgery. For use in constrained 1829 environments, we define a set of HMAC algorithms that are truncated. 1830 There are currently no known issues with truncation, however the 1831 security strength of the message tag is correspondingly reduced in 1832 strength. When truncating, the left-most tag length bits are kept 1833 and transmitted. 1835 The algorithm defined in this document can be found in Table 7. 1837 +-----------+-------+---------+----------+--------------------------+ 1838 | name | value | Hash | Tag | description | 1839 | | | | Length | | 1840 +-----------+-------+---------+----------+--------------------------+ 1841 | HMAC | 4 | SHA-256 | 64 | HMAC w/ SHA-256 | 1842 | 256/64 | | | | truncated to 64 bits | 1843 | | | | | | 1844 | HMAC | 5 | SHA-256 | 256 | HMAC w/ SHA-256 | 1845 | 256/256 | | | | | 1846 | | | | | | 1847 | HMAC | 6 | SHA-384 | 384 | HMAC w/ SHA-384 | 1848 | 384/384 | | | | | 1849 | | | | | | 1850 | HMAC | 7 | SHA-512 | 512 | HMAC w/ SHA-512 | 1851 | 512/512 | | | | | 1852 +-----------+-------+---------+----------+--------------------------+ 1854 Table 7: HMAC Algorithm Values 1856 Some recipient algorithms carry the key while others derive a key 1857 from secret data. For those algorithms that carry the key (i.e. 1858 AES-KeyWrap), the size of the HMAC key SHOULD be the same size as the 1859 underlying hash function. For those algorithms that derive the key 1860 (i.e. ECDH), the derived key MUST be the same size as the underlying 1861 hash function. 1863 When using a COSE key for this algorithm, the following checks are 1864 made: 1866 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 1868 o If the 'alg' field present, it MUST match the HMAC algorithm being 1869 used. 1871 o If the 'key_ops' field is present, it MUST include 'sign' when 1872 creating an HMAC authentication tag. 1874 o If the 'key_ops' field is present, it MUST include 'verify' when 1875 verifying an HMAC authentication tag. 1877 Implementations creating and validating MAC values MUST validate that 1878 the key type, key length, and algorithm are correct and appropriate 1879 for the entities involved. 1881 9.1.1. Security Considerations 1883 HMAC has proved to be resistant to attack even when used with 1884 weakened hash algorithms. The current best method appears to be a 1885 brute force attack on the key. This means that key size is going to 1886 be directly related to the security of an HMAC operation. 1888 9.2. AES Message Authentication Code (AES-CBC-MAC) 1890 AES-CBC-MAC is defined in [MAC]. (Note this is not the same 1891 algorithm as AES-CMAC [RFC4493]). 1893 AES-CBC-MAC is parameterized by the key length, the authentication 1894 tag length and the IV used. For all of these algorithms, the IV is 1895 fixed to all zeros. We provide an array of algorithms for various 1896 key lengths and tag lengths. The algorithms defined in this document 1897 are found in Table 8. 1899 +-------------+-------+----------+----------+-----------------------+ 1900 | name | value | key | tag | description | 1901 | | | length | length | | 1902 +-------------+-------+----------+----------+-----------------------+ 1903 | AES-MAC | 14 | 128 | 64 | AES-MAC 128 bit key, | 1904 | 128/64 | | | | 64-bit tag | 1905 | | | | | | 1906 | AES-MAC | 15 | 256 | 64 | AES-MAC 256 bit key, | 1907 | 256/64 | | | | 64-bit tag | 1908 | | | | | | 1909 | AES-MAC | 25 | 128 | 128 | AES-MAC 128 bit key, | 1910 | 128/128 | | | | 128-bit tag | 1911 | | | | | | 1912 | AES-MAC | 26 | 256 | 128 | AES-MAC 256 bit key, | 1913 | 256/128 | | | | 128-bit tag | 1914 +-------------+-------+----------+----------+-----------------------+ 1916 Table 8: AES-MAC Algorithm Values 1918 Keys may be obtained either from a key structure or from a recipient 1919 structure. Implementations creating and validating MAC values MUST 1920 validate that the key type, key length and algorithm are correct and 1921 appropriate for the entities involved. 1923 When using a COSE key for this algorithm, the following checks are 1924 made: 1926 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 1928 o If the 'alg' field present, it MUST match the AES-MAC algorithm 1929 being used. 1931 o If the 'key_ops' field is present, it MUST include 'sign' when 1932 creating an AES-MAC authentication tag. 1934 o If the 'key_ops' field is present, it MUST include 'verify' when 1935 verifying an AES-MAC authentication tag. 1937 9.2.1. Security Considerations 1939 A number of attacks exist against CBC-MAC that need to be considered. 1941 o A single key must only be used for messages of a fixed and known 1942 length. If this is not the case, an attacker will be able to 1943 generate a message with a valid tag given two message, tag pairs. 1944 This can be addressed by using different keys for different length 1945 messages. The current structure mitigates this problem as a 1946 specific encoding structure which includes lengths is build and 1947 signed. (CMAC also addresses this issue.) 1949 o If the same key is used for both encryption and authentication 1950 operations, using CBC modes an attacker can produce messages with 1951 a valid authentication code. 1953 o If the IV can be modified, then messages can be forged. This is 1954 addressed by fixing the IV to all zeros. 1956 10. Content Encryption Algorithms 1958 Content Encryption Algorithms provide data confidentiality for 1959 potentially large blocks of data using a symmetric key. They provide 1960 integrity on the data that was encrypted, however they provide either 1961 no or very limited data origination. (One cannot, for example, be 1962 used to prove the identity of the sender to a third party.) The 1963 ability to provide data origination is linked to how the CEK is 1964 obtained. 1966 COSE restricts the set of legal content encryption algorithms to 1967 those that support authentication both of the content and additional 1968 data. The encryption process will generate some type of 1969 authentication value, but that value may be either explicit or 1970 implicit in terms of the algorithm definition. For simplicity sake, 1971 the authentication code will normally be defined as being appended to 1972 the cipher text stream. The encryption functions are: 1974 ciphertext = Encrypt(message content, key, additional data) 1976 valid, message content = Decrypt(cipher text, key, additional data) 1978 Most AEAD algorithms are logically defined as returning the message 1979 content only if the decryption is valid. Many but not all 1980 implementations will follow this convention. The message content 1981 MUST NOT be used if the decryption does not validate. 1983 This algorithms are used in COSE_Encrypt and COSE_Encrypt1. 1985 10.1. AES GCM 1987 The GCM mode is a generic authenticated encryption block cipher mode 1988 defined in [AES-GCM]. The GCM mode is combined with the AES block 1989 encryption algorithm to define an AEAD cipher. 1991 The GCM mode is parameterized with by the size of the authentication 1992 tag and the size of the nonce. This document fixes the size of the 1993 nonce at 96-bits. The size of the authentication tag is limited to a 1994 small set of values. For this document however, the size of the 1995 authentication tag is fixed at 128 bits. 1997 The set of algorithms defined in this document are in Table 9. 1999 +---------+-------+------------------------------------------+ 2000 | name | value | description | 2001 +---------+-------+------------------------------------------+ 2002 | A128GCM | 1 | AES-GCM mode w/ 128-bit key, 128-bit tag | 2003 | | | | 2004 | A192GCM | 2 | AES-GCM mode w/ 192-bit key, 128-bit tag | 2005 | | | | 2006 | A256GCM | 3 | AES-GCM mode w/ 256-bit key, 128-bit tag | 2007 +---------+-------+------------------------------------------+ 2009 Table 9: Algorithm Value for AES-GCM 2011 Keys may be obtained either from a key structure or from a recipient 2012 structure. Implementations encrypting and decrypting MUST validate 2013 that the key type, key length and algorithm are correct and 2014 appropriate for the entities involved. 2016 When using a COSE key for this algorithm, the following checks are 2017 made: 2019 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2021 o If the 'alg' field present, it MUST match the AES-GCM algorithm 2022 being used. 2024 o If the 'key_ops' field is present, it MUST include 'encrypt' or 2025 'key wrap' when encrypting. 2027 o If the 'key_ops' field is present, it MUST include 'decrypt' or 2028 'key unwrap' when decrypting. 2030 10.1.1. Security Considerations 2032 When using AES-GCM, the following restrictions MUST be enforced: 2034 o The key and nonce pair MUST be unique for every message encrypted. 2036 o The total amount of data encrypted for a single key MUST NOT 2037 exceed 2^39 - 256 bits. An explicit check is required only in 2038 environments where it is expected that it might be exceeded. 2040 Consideration was given to supporting smaller tag values, the 2041 constrained community would desire tag sizes in the 64-bit range. 2042 Doing so drastically changes both the maximum messages size 2043 (generally not an issue) and the number of times that a key can be 2044 used. Given that CCM is the usual mode for constrained environments 2045 restricted modes are not supported. 2047 10.2. AES CCM 2049 Counter with CBC-MAC (CCM) is a generic authentication encryption 2050 block cipher mode defined in [RFC3610]. The CCM mode is combined 2051 with the AES block encryption algorithm to define a commonly used 2052 content encryption algorithm used in constrained devices. 2054 The CCM mode has two parameter choices. The first choice is M, the 2055 size of the authentication field. The choice of the value for M 2056 involves a trade-off between message growth (from the tag) and the 2057 probably that an attacker can undetectably modify a message. The 2058 second choice is L, the size of the length field. This value 2059 requires a trade-off between the maximum message size and the size of 2060 the Nonce. 2062 It is unfortunate that the specification for CCM specified L and M as 2063 a count of bytes rather than a count of bits. This leads to possible 2064 misunderstandings where AES-CCM-8 is frequently used to refer to a 2065 version of CCM mode where the size of the authentication is 64 bits 2066 and not 8 bits. These values have traditionally been specified as 2067 bit counts rather than byte counts. This document will follow the 2068 convention of using bit counts so that it is easier to compare the 2069 different algorithms presented in this document. 2071 We define a matrix of algorithms in this document over the values of 2072 L and M. Constrained devices are usually operating in situations 2073 where they use short messages and want to avoid doing recipient 2074 specific cryptographic operations. This favors smaller values of 2075 both L and M. Less constrained devices do will want to be able to 2076 user larger messages and are more willing to generate new keys for 2077 every operation. This favors larger values of L and M. 2079 The following values are used for L: 2081 16 bits (2) limits messages to 2^16 bytes (64 KiB) in length. This 2082 sufficiently long for messages in the constrained world. The 2083 nonce length is 13 bytes allowing for 2^(13*8) possible values of 2084 the nonce without repeating. 2086 64 bits (8) limits messages to 2^64 bytes in length. The nonce 2087 length is 7 bytes allowing for 2^56 possible values of the nonce 2088 without repeating. 2090 The following values are used for M: 2092 64 bits (8) produces a 64-bit authentication tag. This implies that 2093 there is a 1 in 2^64 chance that a modified message will 2094 authenticate. 2096 128 bits (16) produces a 128-bit authentication tag. This implies 2097 that there is a 1 in 2^128 chance that a modified message will 2098 authenticate. 2100 +--------------------+-------+----+-----+-----+---------------------+ 2101 | name | value | L | M | k | description | 2102 +--------------------+-------+----+-----+-----+---------------------+ 2103 | AES-CCM-16-64-128 | 10 | 16 | 64 | 128 | AES-CCM mode | 2104 | | | | | | 128-bit key, 64-bit | 2105 | | | | | | tag, 13-byte nonce | 2106 | | | | | | | 2107 | AES-CCM-16-64-256 | 11 | 16 | 64 | 256 | AES-CCM mode | 2108 | | | | | | 256-bit key, 64-bit | 2109 | | | | | | tag, 13-byte nonce | 2110 | | | | | | | 2111 | AES-CCM-64-64-128 | 12 | 64 | 64 | 128 | AES-CCM mode | 2112 | | | | | | 128-bit key, 64-bit | 2113 | | | | | | tag, 7-byte nonce | 2114 | | | | | | | 2115 | AES-CCM-64-64-256 | 13 | 64 | 64 | 256 | AES-CCM mode | 2116 | | | | | | 256-bit key, 64-bit | 2117 | | | | | | tag, 7-byte nonce | 2118 | | | | | | | 2119 | AES-CCM-16-128-128 | 30 | 16 | 128 | 128 | AES-CCM mode | 2120 | | | | | | 128-bit key, | 2121 | | | | | | 128-bit tag, | 2122 | | | | | | 13-byte nonce | 2123 | | | | | | | 2124 | AES-CCM-16-128-256 | 31 | 16 | 128 | 256 | AES-CCM mode | 2125 | | | | | | 256-bit key, | 2126 | | | | | | 128-bit tag, | 2127 | | | | | | 13-byte nonce | 2128 | | | | | | | 2129 | AES-CCM-64-128-128 | 32 | 64 | 128 | 128 | AES-CCM mode | 2130 | | | | | | 128-bit key, | 2131 | | | | | | 128-bit tag, 7-byte | 2132 | | | | | | nonce | 2133 | | | | | | | 2134 | AES-CCM-64-128-256 | 33 | 64 | 128 | 256 | AES-CCM mode | 2135 | | | | | | 256-bit key, | 2136 | | | | | | 128-bit tag, 7-byte | 2137 | | | | | | nonce | 2138 +--------------------+-------+----+-----+-----+---------------------+ 2140 Table 10: Algorithm Values for AES-CCM 2142 Keys may be obtained either from a key structure or from a recipient 2143 structure. Implementations encrypting and decrypting MUST validate 2144 that the key type, key length and algorithm are correct and 2145 appropriate for the entities involved. 2147 When using a COSE key for this algorithm, the following checks are 2148 made: 2150 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2152 o If the 'alg' field present, it MUST match the AES-CCM algorithm 2153 being used. 2155 o If the 'key_ops' field is present, it MUST include 'encrypt' or 2156 'key wrap' when encrypting. 2158 o If the 'key_ops' field is present, it MUST include 'decrypt' or 2159 'key unwrap' when decrypting. 2161 10.2.1. Security Considerations 2163 When using AES-CCM, the following restrictions MUST be enforced: 2165 o The key and nonce pair MUST be unique for every message encrypted. 2167 o The total number of times the AES block cipher is used MUST NOT 2168 exceed 2^61 operations. This limitation is the sum of times the 2169 block cipher is used in computing the MAC value and in performing 2170 stream encryption operations. An explicit check is required only 2171 in environments where it is expected that it might be exceeded. 2173 [RFC3610] additionally calls out one other consideration of note. It 2174 is possible to do a pre-computation attack against the algorithm in 2175 cases where the portions encryption content is highly predictable. 2176 This reduces the security of the key size by half. Ways to deal with 2177 this attack include adding a random portion to the nonce value and/or 2178 increasing the key size used. Using a portion of the nonce for a 2179 random value will decrease the number of messages that a single key 2180 can be used for. Increasing the key size may require more resources 2181 in the constrained device. See sections 5 and 10 of [RFC3610] for 2182 more information. 2184 10.3. ChaCha20 and Poly1305 2186 ChaCha20 and Poly1305 combined together is an AEAD mode that is 2187 defined in [RFC7539]. This is an algorithm defined to be a cipher 2188 that is not AES and thus would not suffer from any future weaknesses 2189 found in AES. These cryptographic functions are designed to be fast 2190 in software-only implementations. 2192 The ChaCha20/Poly1305 AEAD construction defined in [RFC7539] has no 2193 parameterization. It takes a 256-bit key and a 96-bit nonce as well 2194 as the plain text and additional data as inputs and produces the 2195 cipher text as an option. We define one algorithm identifier for 2196 this algorithm in Table 11. 2198 +-------------------+-------+---------------------------------------+ 2199 | name | value | description | 2200 +-------------------+-------+---------------------------------------+ 2201 | ChaCha20/Poly1305 | 24 | ChaCha20/Poly1305 w/ 256-bit key, | 2202 | | | 128-bit tag | 2203 +-------------------+-------+---------------------------------------+ 2205 Table 11: Algorithm Value for AES-GCM 2207 Keys may be obtained either from a key structure or from a recipient 2208 structure. Implementations encrypting and decrypting MUST validate 2209 that the key type, key length and algorithm are correct and 2210 appropriate for the entities involved. 2212 When using a COSE key for this algorithm, the following checks are 2213 made: 2215 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2217 o If the 'alg' field present, it MUST match the ChaCha algorithm 2218 being used. 2220 o If the 'key_ops' field is present, it MUST include 'encrypt' or 2221 'key wrap' when encrypting. 2223 o If the 'key_ops' field is present, it MUST include 'decrypt' or 2224 'key unwrap' when decrypting. 2226 10.3.1. Security Considerations 2228 The pair of key, nonce MUST be unique for every invocation of the 2229 algorithm. Nonce counters are considered to be an acceptable way of 2230 ensuring that they are unique. 2232 11. Key Derivation Functions (KDF) 2234 Key Derivation Functions (KDFs) are used to take some secret value 2235 and generate a different one. The secret value comes in three 2236 flavors: 2238 o Secrets that are uniformly random: This is the type of secret 2239 which is created by a good random number generator. 2241 o Secrets that are not uniformly random: This is type of secret 2242 which is created by operations like key agreement. 2244 o Secrets that are not random: This is the type of secret that 2245 people generate for things like passwords. 2247 General KDF functions work well with the first type of secret, can do 2248 reasonable well with the second type of secret and generally do 2249 poorly with the last type of secret. None of the KDF functions in 2250 this section are designed to deal with the type of secrets that are 2251 used for passwords. Functions like PBSE2 [RFC2898] need to be used 2252 for that type of secret. 2254 The same KDF function can be setup to deal with the first two types 2255 of secrets different. The KDF function defined in Section 11.1 is 2256 such a function. This is reflected in the set of algorithms defined 2257 for HKDF. 2259 When using KDF functions, one component that is included is context 2260 information. Context information is used to allow for different 2261 keying information to be derived from the same secret. The use of 2262 context based keying material is considered to be a good security 2263 practice. 2265 This document defines a single context structure and a single KDF 2266 function. These elements are used for all of the recipient 2267 algorithms defined in this document that require a KDF process. 2268 These algorithms are defined in Section 12.1.2, Section 12.4.1, and 2269 Section 12.5.1. 2271 11.1. HMAC-based Extract-and-Expand Key Derivation Function (HKDF) 2273 The HKDF key derivation algorithm is defined in [RFC5869]. 2275 The HKDF algorithm takes these inputs: 2277 secret - a shared value that is secret. Secrets may be either 2278 previously shared or derived from operations like a DH key 2279 agreement. 2281 salt - an optional value that is used to change the generation 2282 process. The salt value can be either public or private. If the 2283 salt is public and carried in the message, then the 'salt' 2284 algorithm header parameter defined in Table 13 is used. While 2285 [RFC5869] suggests that the length of the salt be the same as the 2286 length of the underlying hash value, any amount of salt will 2287 improve the security as different key values will be generated. 2288 This parameter is protected by being included in the key 2289 computation and does not need to be separately authenticated. The 2290 salt value does not need to be unique for every message sent. 2292 length - the number of bytes of output that need to be generated. 2294 context information - Information that describes the context in 2295 which the resulting value will be used. Making this information 2296 specific to the context in which the material is going to be used 2297 ensures that the resulting material will always be tied to that 2298 usage. The context structure defined in Section 11.2 is used by 2299 the KDF functions in this document. 2301 PRF - The underlying pseudo-random function to be used in the HKDF 2302 algorithm. The PRF is encoded into the HKDF algorithm selection. 2304 HKDF is defined to use HMAC as the underlying PRF. However, it is 2305 possible to use other functions in the same construct to provide a 2306 different KDF function that is more appropriate in the constrained 2307 world. Specifically, one can use AES-CBC-MAC as the PRF for the 2308 expand step, but not for the extract step. When using a good random 2309 shared secret of the correct length, the extract step can be skipped. 2310 For the AES algorithm versions, the extract step is always skipped. 2312 The extract step cannot be skipped if the secret is not uniformly 2313 random, for example if it is the result of an ECDH key agreement 2314 step. (This implies that the AES HKDF version cannot be used with 2315 ECDH.) If the extract step is skipped, the 'salt' value is not used 2316 as part of the HKDF functionality. 2318 The algorithms defined in this document are found in Table 12. 2320 +---------------+-----------------+---------------------------------+ 2321 | name | PRF | description | 2322 +---------------+-----------------+---------------------------------+ 2323 | HKDF SHA-256 | HMAC with | HKDF using HMAC SHA-256 as the | 2324 | | SHA-256 | PRF | 2325 | | | | 2326 | HKDF SHA-512 | HMAC with | HKDF using HMAC SHA-512 as the | 2327 | | SHA-512 | PRF | 2328 | | | | 2329 | HKDF AES- | AES-CBC-MAC-128 | HKDF using AES-MAC as the PRF | 2330 | MAC-128 | | w/ 128-bit key | 2331 | | | | 2332 | HKDF AES- | AES-CBC-MAC-256 | HKDF using AES-MAC as the PRF | 2333 | MAC-256 | | w/ 256-bit key | 2334 +---------------+-----------------+---------------------------------+ 2336 Table 12: HKDF algorithms 2338 +------+-------+------+-------------+ 2339 | name | label | type | description | 2340 +------+-------+------+-------------+ 2341 | salt | -20 | bstr | Random salt | 2342 +------+-------+------+-------------+ 2344 Table 13: HKDF Algorithm Parameters 2346 11.2. Context Information Structure 2348 The context information structure is used to ensure that the derived 2349 keying material is "bound" to the context of the transaction. The 2350 context information structure used here is based on that defined in 2351 [SP800-56A]. By using CBOR for the encoding of the context 2352 information structure, we automatically get the same type and length 2353 separation of fields that is obtained by the use of ASN.1. This 2354 means that there is no need to encode the lengths for the base 2355 elements as it is done by the encoding used in JOSE (Section 4.6.2 of 2356 [RFC7518]). 2358 The context information structure refers to PartyU and PartyV as the 2359 two parties which are doing the key derivation. Unless the 2360 application protocol defines differently, we assign PartyU to the 2361 entity that is creating the message and PartyV to the entity that is 2362 receiving the message. By doing this association, different keys 2363 will be derived for each direction as the context information is 2364 different in each direction. 2366 The context structure is built from information that is known to both 2367 entities. This information can be obtained from a variety of 2368 sources: 2370 o Fields can be define by the application. This is commonly used to 2371 assign fixed names to parties, but can be used for other items 2372 such as nonces. 2374 o Fields can be defined by usage of the output. Examples of this 2375 are the algorithm and key size that are being generated. 2377 o Fields can be defined by parameters from the message. We define a 2378 set of parameters in Table 14 which can be used to carry the 2379 values associated with the context structure. Examples of this 2380 are identities and nonce values. These parameters are designed to 2381 be placed in the unprotected bucket of the recipient structure. 2382 (They do not need to be in the protected bucket since they already 2383 are included in the cryptographic computation by virtue of being 2384 included in the context structure.) 2386 +---------------+-------+-----------+-------------------------------+ 2387 | name | label | type | description | 2388 +---------------+-------+-----------+-------------------------------+ 2389 | PartyU | -21 | bstr | Party U identity Information | 2390 | identity | | | | 2391 | | | | | 2392 | PartyU nonce | -22 | bstr / | Party U provided nonce | 2393 | | | int | | 2394 | | | | | 2395 | PartyU other | -23 | bstr | Party U other provided | 2396 | | | | information | 2397 | | | | | 2398 | PartyV | -24 | bstr | Party V identity Information | 2399 | identity | | | | 2400 | | | | | 2401 | PartyV nonce | -25 | bstr / | Party V provided nonce | 2402 | | | int | | 2403 | | | | | 2404 | PartyV other | -26 | bstr | Party V other provided | 2405 | | | | information | 2406 +---------------+-------+-----------+-------------------------------+ 2408 Table 14: Context Algorithm Parameters 2410 We define a CBOR object to hold the context information. This object 2411 is referred to as CBOR_KDF_Context. The object is based on a CBOR 2412 array type. The fields in the array are: 2414 AlgorithmID This field indicates the algorithm for which the key 2415 material will be used. This field is required to be present. The 2416 field exists in the context information so that if the same 2417 environment is used for different algorithms, then completely 2418 different keys will be generated each of those algorithms. (This 2419 practice means if algorithm A is broken and thus can is easier to 2420 find, the key derived for algorithm B will not be the same as the 2421 key for algorithm B.) 2423 PartyUInfo This field holds information about party U. The 2424 PartyUInfo is encoded as a CBOR array. The elements of PartyUInfo 2425 are encoded in the order presented, however if the element does 2426 not exist no element is placed in the array. The elements of the 2427 PartyUInfo array are: 2429 identity This contains the identity information for party U. The 2430 identities can be assigned in one of two manners. Firstly, a 2431 protocol can assign identities based on roles. For example, 2432 the roles of "client" and "server" may be assigned to different 2433 entities in the protocol. Each entity would then use the 2434 correct label for the data they send or receive. The second 2435 way is for a protocol to assign identities is to use a name 2436 based on a naming system (i.e. DNS, X.509 names). 2437 We define an algorithm parameter 'PartyU identity' that can be 2438 used to carry identity information in the message. However, 2439 identity information is often known as part of the protocol and 2440 can thus be inferred rather than made explicit. If identity 2441 information is carried in the message, applications SHOULD have 2442 a way of validating the supplied identity information. The 2443 identity information does not need to be specified and can be 2444 left as absent. 2446 nonce This contains a nonce value. The nonce can either be 2447 implicit from the protocol or carried as a value in the 2448 unprotected headers. 2449 We define an algorithm parameter 'PartyU nonce' that can be 2450 used to carry this value in the message However, the nonce 2451 value could be determined by the application and the value 2452 determined from elsewhere. 2453 This item is optional and can be absent. 2455 other This contains other information that is defined by the 2456 protocol. 2457 This item is optional and can be absent. 2459 PartyVInfo This field holds information about party V. The 2460 PartyVInfo is encoded as a CBOR array. For store and forward 2461 environments, the party V information may be minimal or even 2462 absent. The elements of PartyVInfo are encoded in the order 2463 presented, however if the element does not exist no element is 2464 placed in the array. The elements of the PartyVInfo array are: 2466 identity See description of PartyUInfo identity. 2468 nonce See description of PartyUInfo nonce. 2470 other See description of PartyUInfo other. 2472 SuppPubInfo This field contains public information that is mutually 2473 known to both parties. 2475 keyDataLength This is set to the number of bits of the desired 2476 output value. (This practice means if algorithm A can use two 2477 different key lengths, the key derived for longer key size will 2478 not contain the key for shorter key size as a prefix.) 2480 protected This field contains the protected parameter field. If 2481 there are no elements in the protected field, then use a zero 2482 length bstr. 2484 other The field other is for free form data defined by the 2485 application. An example is that an application could defined 2486 two different strings to be placed here to generate different 2487 keys for a data stream vs a control stream. This field is 2488 optional and will only be present if the application defines a 2489 structure for this information. Applications that define this 2490 SHOULD use CBOR to encode the data so that types and lengths 2491 are correctly include. 2493 SuppPrivInfo This field contains private information that is 2494 mutually known private information. An example of this 2495 information would be a pre-existing shared secret. (This could 2496 for example, be used in combination with an ECDH key agreement to 2497 provide a secondary proof of identity.) The field is optional and 2498 will only be present if the application defines a structure for 2499 this information. Applications that define this SHOULD use CBOR 2500 to encode the data so that types and lengths are correctly 2501 included. 2503 The following CDDL fragment corresponds to the text above. 2505 PartyInfo = ( 2506 ? nonce : bstr / int, 2507 ? identity : bstr, 2508 ? other : bstr, 2509 ) 2511 COSE_KDF_Context = [ 2512 AlgorithmID : int / tstr, 2513 PartyUInfo : [ PartyInfo ], 2514 PartyVInfo : [ PartyInfo ], 2515 SuppPubInfo : [ 2516 keyDataLength : uint, 2517 protected : bstr, 2518 ? other : bstr 2519 ], 2520 ? SuppPrivInfo : bstr 2521 ] 2523 12. Recipient Algorithm Classes 2525 Recipient algorithms can be defined into a number of different 2526 classes. COSE has the ability to support many classes of recipient 2527 algorithms. In this section, a number of classes are listed and then 2528 a set of algorithms are specified for each of the classes. The names 2529 of the recipient algorithm classes used here are the same as are 2530 defined in [RFC7516]. Other specifications use different terms for 2531 the recipient algorithm classes or do not support some of the 2532 recipient algorithm classes. 2534 12.1. Direct Encryption 2536 The direct encryption class algorithms share a secret between the 2537 sender and the recipient that is used either directly or after 2538 manipulation as the CEK. When direct encryption mode is used, it 2539 MUST be the only mode used on the message. 2541 The COSE_Encrypt structure for the recipient is organized as follows: 2543 o The 'protected' field MUST be a zero length item unless it is used 2544 in the computation of the content key. 2546 o The 'alg' parameter MUST be present. 2548 o A parameter identifying the shared secret SHOULD be present. 2550 o The 'ciphertext' field MUST be a zero length item. 2552 o The 'recipients' field MUST be absent. 2554 12.1.1. Direct Key 2556 This recipient algorithm is the simplest, the identified key is 2557 directly used as the key for the next layer down in the message. 2558 There are no algorithm parameters defined for this algorithm. The 2559 algorithm identifier value is assigned in Table 15. 2561 When this algorithm is used, the protected field MUST be zero length. 2562 The key type MUST be 'Symmetric'. 2564 +--------+-------+-------------------+ 2565 | name | value | description | 2566 +--------+-------+-------------------+ 2567 | direct | -6 | Direct use of CEK | 2568 +--------+-------+-------------------+ 2570 Table 15: Direct Key 2572 12.1.1.1. Security Considerations 2574 This recipient algorithm has several potential problems that need to 2575 be considered: 2577 o These keys need to have some method to be regularly updated over 2578 time. All of the content encryption algorithms specified in this 2579 document have limits on how many times a key can be used without 2580 significant loss of security. 2582 o These keys need to be dedicated to a single algorithm. There have 2583 been a number of attacks developed over time when a single key is 2584 used for multiple different algorithms. One example of this is 2585 the use of a single key both for CBC encryption mode and CBC-MAC 2586 authentication mode. 2588 o Breaking one message means all messages are broken. If an 2589 adversary succeeds in determining the key for a single message, 2590 then the key for all messages is also determined. 2592 12.1.2. Direct Key with KDF 2594 These recipient algorithms take a common shared secret between the 2595 two parties and applies the HKDF function (Section 11.1) using the 2596 context structure defined in Section 11.2 to transform the shared 2597 secret into the CEK. The 'protected' field can be of non-zero 2598 length. Either the 'salt' parameter of HKDF or the partyU 'nonce' 2599 parameter of the context structure MUST be present. The salt/nonce 2600 parameter can be generated either randomly or deterministically. The 2601 requirement is that it be a unique value for the shared secret in 2602 question. 2604 If the salt/nonce value is generated randomly, then it is suggested 2605 that the length of the random value be the same length as the hash 2606 function underlying HKDF. While there is no way to guarantee that it 2607 will be unique, there is a high probability that it will be unique. 2608 If the salt/nonce value is generated deterministically, it can be 2609 guaranteed to be unique and thus there is no length requirement. 2611 A new IV must be used for each message if the same key is used. The 2612 IV can be modified in a predictable manner, a random manner or an 2613 unpredictable manner (i.e. encrypting a counter). 2615 The IV used for a key can also be generated from the same HKDF 2616 functionality as the key is generated. If HKDF is used for 2617 generating the IV, the algorithm identifier is set to "IV- 2618 GENERATION". 2620 When these algorithms are used, the key type MUST be 'symmetric'. 2622 The set of algorithms defined in this document can be found in 2623 Table 16. 2625 +---------------------+-------+-------------+-----------------------+ 2626 | name | value | KDF | description | 2627 +---------------------+-------+-------------+-----------------------+ 2628 | direct+HKDF-SHA-256 | -10 | HKDF | Shared secret w/ HKDF | 2629 | | | SHA-256 | and SHA-256 | 2630 | | | | | 2631 | direct+HKDF-SHA-512 | -11 | HKDF | Shared secret w/ HKDF | 2632 | | | SHA-512 | and SHA-512 | 2633 | | | | | 2634 | direct+HKDF-AES-128 | -12 | HKDF AES- | Shared secret w/ AES- | 2635 | | | MAC-128 | MAC 128-bit key | 2636 | | | | | 2637 | direct+HKDF-AES-256 | -13 | HKDF AES- | Shared secret w/ AES- | 2638 | | | MAC-256 | MAC 256-bit key | 2639 +---------------------+-------+-------------+-----------------------+ 2641 Table 16: Direct Key 2643 When using a COSE key for this algorithm, the following checks are 2644 made: 2646 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2648 o If the 'alg' field present, it MUST match the algorithm being 2649 used. 2651 o If the 'key_ops' field is present, it MUST include 'deriveKey or 2652 'deriveBits'. 2654 12.1.2.1. Security Considerations 2656 The shared secret needs to have some method to be regularly updated 2657 over time. The shared secret forms the basis of trust. Although not 2658 used directly, it should still be subject to scheduled rotation. 2660 While these methods do not provide for PFS, as the same shared secret 2661 is used for all of the keys generated, if the key for any single 2662 message is discovered only the message (or series of messages) using 2663 that derived key are compromised. A new key derivation step will 2664 generate a new key which requires the same amount of work to get the 2665 key. 2667 12.2. Key Wrapping 2669 In key wrapping mode, the CEK is randomly generated and that key is 2670 then encrypted by a shared secret between the sender and the 2671 recipient. All of the currently defined key wrapping algorithms for 2672 COSE are AE algorithms. Key wrapping mode is considered to be 2673 superior to direct encryption if the system has any capability for 2674 doing random key generation. This is because the shared key is used 2675 to wrap random data rather than data has some degree of organization 2676 and may in fact be repeating the same content. The use of Key 2677 Wrapping loses the weak data origination that is provided by the 2678 direct encryption algorithms. 2680 The COSE_Encrypt structure for the recipient is organized as follows: 2682 o The 'protected' field MUST be absent if the key wrap algorithm is 2683 an AE algorithm. 2685 o The 'recipients' field is normally absent, but can be used. 2686 Applications MUST deal with a recipient field present, not being 2687 able to decrypt that recipient is an acceptable way of dealing 2688 with it. Failing to process the message is not an acceptable way 2689 of dealing with it. 2691 o The plain text to be encrypted is the key from next layer down 2692 (usually the content layer). 2694 o At a minimum, the 'unprotected' field MUST contain the 'alg' 2695 parameter and SHOULD contain a parameter identifying the shared 2696 secret. 2698 12.2.1. AES Key Wrapping 2700 The AES Key Wrapping algorithm is defined in [RFC3394]. This 2701 algorithm uses an AES key to wrap a value that is a multiple of 64 2702 bits. As such, it can be used to wrap a key for any of the content 2703 encryption algorithms defined in this document. The algorithm 2704 requires a single fixed parameter, the initial value. This is fixed 2705 to the value specified in Section 2.2.3.1 of [RFC3394]. There are no 2706 public parameters that vary on a per invocation basis. The protected 2707 header field MUST be empty. 2709 Keys may be obtained either from a key structure or from a recipient 2710 structure. Implementations encrypting and decrypting MUST validate 2711 that the key type, key length and algorithm are correct and 2712 appropriate for the entities involved. 2714 When using a COSE key for this algorithm, the following checks are 2715 made: 2717 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2719 o If the 'alg' field present, it MUST match the AES Key Wrap 2720 algorithm being used. 2722 o If the 'key_ops' field is present, it MUST include 'encrypt' or 2723 'key wrap' when encrypting. 2725 o If the 'key_ops' field is present, it MUST include 'decrypt' or 2726 'key unwrap' when decrypting. 2728 +--------+-------+----------+-----------------------------+ 2729 | name | value | key size | description | 2730 +--------+-------+----------+-----------------------------+ 2731 | A128KW | -3 | 128 | AES Key Wrap w/ 128-bit key | 2732 | | | | | 2733 | A192KW | -4 | 192 | AES Key Wrap w/ 192-bit key | 2734 | | | | | 2735 | A256KW | -5 | 256 | AES Key Wrap w/ 256-bit key | 2736 +--------+-------+----------+-----------------------------+ 2738 Table 17: AES Key Wrap Algorithm Values 2740 12.2.1.1. Security Considerations for AES-KW 2742 The shared secret need to have some method to be regularly updated 2743 over time. The shared secret is the basis of trust. 2745 12.3. Key Encryption 2747 Key Encryption mode is also called key transport mode in some 2748 standards. Key Encryption mode differs from Key Wrap mode in that it 2749 uses an asymmetric encryption algorithm rather than a symmetric 2750 encryption algorithm to protect the key. This document does not 2751 define any Key Encryption mode algorithms. 2753 When using a key encryption algorithm, the COSE_Encrypt structure for 2754 the recipient is organized as follows: 2756 o The 'protected' field MUST be absent. 2758 o The plain text to be encrypted is the key from next layer down 2759 (usually the content layer). 2761 o At a minimum, the 'unprotected' field MUST contain the 'alg' 2762 parameter and SHOULD contain a parameter identifying the 2763 asymmetric key. 2765 12.4. Direct Key Agreement 2767 The 'direct key agreement' class of recipient algorithms uses a key 2768 agreement method to create a shared secret. A KDF is then applied to 2769 the shared secret to derive a key to be used in protecting the data. 2770 This key is normally used as a CEK or MAC key, but could be used for 2771 other purposes if more than two layers are in use (see Appendix B). 2773 The most commonly used key agreement algorithm is Diffie-Hellman, but 2774 other variants exist. Since COSE is designed for a store and forward 2775 environment rather than an on-line environment, many of the DH 2776 variants cannot be used as the receiver of the message cannot provide 2777 any dynamic key material. One side-effect of this is that perfect 2778 forward secrecy (see [RFC4949]) is not achievable. A static key will 2779 always be used for the receiver of the COSE message. 2781 Two variants of DH that are supported are: 2783 Ephemeral-Static DH: where the sender of the message creates a one 2784 time DH key and uses a static key for the recipient. The use of 2785 the ephemeral sender key means that no additional random input is 2786 needed as this is randomly generated for each message. 2788 Static-Static DH: where a static key is used for both the sender 2789 and the recipient. The use of static keys allows for recipient to 2790 get a weak version of data origination for the message. When 2791 static-static key agreement is used, then some piece of unique 2792 data for the KDF is required to ensure that a different key is 2793 created for each message. 2795 When direct key agreement mode is used, there MUST be only one 2796 recipient in the message. This method creates the key directly and 2797 that makes it difficult to mix with additional recipients. If 2798 multiple recipients are needed, then the version with key wrap needs 2799 to be used. 2801 The COSE_Encrypt structure for the recipient is organized as follows: 2803 o At a minimum, headers MUST contain the 'alg' parameter and SHOULD 2804 contain a parameter identifying the recipient's asymmetric key. 2806 o The headers SHOULD identify the senders key for the static-static 2807 versions and MUST contain the senders ephemeral key for the 2808 ephemeral-static versions. 2810 12.4.1. ECDH 2812 The mathematics for Elliptic Curve Diffie-Hellman can be found in 2813 [RFC6090]. In this document the algorithm is extended to be used 2814 with the two curves defined in [RFC7748]. 2816 ECDH is parameterized by the following: 2818 o Curve Type/Curve: The curve selected controls not only the size of 2819 the shared secret, but the mathematics for computing the shared 2820 secret. The curve selected also controls how a point in the curve 2821 is represented and what happens for the identity points on the 2822 curve. In this specification, we allow for a number of different 2823 curves to be used. A set of curves are defined in Table 22. 2824 Since the only the math is changed by changing the curve, the 2825 curve is not fixed for any of the algorithm identifiers we define. 2827 o Ephemeral-static or static-static: The key agreement process may 2828 be done using either a static or an ephemeral key for the sender's 2829 side. When using ephemeral keys, the sender MUST generate a new 2830 ephemeral key for every key agreement operation. The ephemeral 2831 key is placed in the 'ephemeral key' parameter and MUST be present 2832 for all algorithm identifiers that use ephemeral keys. When using 2833 static keys, the sender MUST either generate a new random value or 2834 otherwise create a unique value. For the KDF functions used, this 2835 means either in the 'salt' parameter for HKDF (Table 13) or in the 2836 'PartyU nonce' parameter for the context structure (Table 14) MUST 2837 be present. (Both may be present if desired.) The value in the 2838 parameter MUST be unique for the pair of keys being used. It is 2839 acceptable to use a global counter that is incremented for every 2840 static-static operation and use the resulting value. When using 2841 static keys, the static key should be identified to the recipient. 2842 The static key can be identified either by providing the key 2843 ('static key') or by providing a key identifier for the static key 2844 ('static key id'). Both of these parameters are defined in 2845 Table 19 2847 o Key derivation algorithm: The result of an ECDH key agreement 2848 process does not provide a uniformly random secret. As such, it 2849 needs to be run through a KDF in order to produce a usable key. 2850 Processing the secret through a KDF also allows for the 2851 introduction of context material: how the key is going to be used, 2852 and one time material for static-static key agreement. All of the 2853 algorithm define in this documeent use one of the HKDF algorithms 2854 defined in Section 11.1 with the context structure defined in 2855 Section 11.2. 2857 o Key Wrap algorithm: No key wrap algorithm is used. This is 2858 represented in Table 18 as 'none'. The key size for the context 2859 structure is the content layer encryption algorithm size. 2861 The set of direct ECDH algorithms defined in this document are found 2862 in Table 18. 2864 +-----------+-------+---------+------------+--------+---------------+ 2865 | name | value | KDF | Ephemeral- | Key | description | 2866 | | | | Static | Wrap | | 2867 +-----------+-------+---------+------------+--------+---------------+ 2868 | ECDH-ES + | -25 | HKDF - | yes | none | ECDH ES w/ | 2869 | HKDF-256 | | SHA-256 | | | HKDF - | 2870 | | | | | | generate key | 2871 | | | | | | directly | 2872 | | | | | | | 2873 | ECDH-ES + | -26 | HKDF - | yes | none | ECDH ES w/ | 2874 | HKDF-512 | | SHA-512 | | | HKDF - | 2875 | | | | | | generate key | 2876 | | | | | | directly | 2877 | | | | | | | 2878 | ECDH-SS + | -27 | HKDF - | no | none | ECDH SS w/ | 2879 | HKDF-256 | | SHA-256 | | | HKDF - | 2880 | | | | | | generate key | 2881 | | | | | | directly | 2882 | | | | | | | 2883 | ECDH-SS + | -28 | HKDF - | no | none | ECDH SS w/ | 2884 | HKDF-512 | | SHA-512 | | | HKDF - | 2885 | | | | | | generate key | 2886 | | | | | | directly | 2887 +-----------+-------+---------+------------+--------+---------------+ 2889 Table 18: ECDH Algorithm Values 2891 +-----------+-------+----------+-----------+------------------------+ 2892 | name | label | type | algorithm | description | 2893 +-----------+-------+----------+-----------+------------------------+ 2894 | ephemeral | -1 | COSE_Key | ECDH-ES | Ephemeral Public key | 2895 | key | | | | for the sender | 2896 | | | | | | 2897 | static | -2 | COSE_Key | ECDH-ES | Static Public key for | 2898 | key | | | | the sender | 2899 | | | | | | 2900 | static | -3 | bstr | ECDH-SS | Static Public key | 2901 | key id | | | | identifier for the | 2902 | | | | | sender | 2903 +-----------+-------+----------+-----------+------------------------+ 2905 Table 19: ECDH Algorithm Parameters 2907 This document defines these algorithms to be used with the curves 2908 P-256, P-384, P-521, X25519, and X448. Implementations MUST verify 2909 that the key type and curve are correct. Different curves are 2910 restricted to different key types. Implementations MUST verify that 2911 the curve and algorithm are appropriate for the entities involved. 2913 When using a COSE key for this algorithm, the following checks are 2914 made: 2916 o The 'kty' field MUST be present and it MUST be 'EC2' or 'OKP'. 2918 o If the 'alg' field present, it MUST match the Key Agreement 2919 algorithm being used. 2921 o If the 'key_ops' field is present, it MUST include 'derive key' or 2922 'derive bits' for the private key. 2924 o If the 'key_ops' field is present, it MUST be empty for the public 2925 key. 2927 12.5. Key Agreement with KDF 2929 Key Agreement with Key Wrapping uses a randomly generated CEK. The 2930 CEK is then encrypted using a Key Wrapping algorithm and a key 2931 derived from the shared secret computed by the key agreement 2932 algorithm. 2934 The COSE_Encrypt structure for the recipient is organized as follows: 2936 o The 'protected' field is fed into the KDF context structure. 2938 o The plain text to be encrypted is the key from next layer down 2939 (usually the content layer). 2941 o The 'alg' parameter MUST be present in the layer. 2943 o A parameter identifying the recipient's key SHOULD be present. A 2944 parameter identifying the sender's key SHOULD be present. 2946 12.5.1. ECDH 2948 These algorithms are defined in Table 20. 2950 ECDH with Key Agreement is parameterized by the same parameters as 2951 for ECDH Section 12.4.1 with the following modifications: 2953 o Key Wrap Algorithm: Any of the key wrap algorithms defined in 2954 Section 12.2.1 are supported. The size of the key used for the 2955 key wrap algorithm is fed into the KDF function. The set of 2956 identifiers are found in Table 20. 2958 +-----------+-------+---------+------------+--------+---------------+ 2959 | name | value | KDF | Ephemeral- | Key | description | 2960 | | | | Static | Wrap | | 2961 +-----------+-------+---------+------------+--------+---------------+ 2962 | ECDH-ES + | -29 | HKDF - | yes | A128KW | ECDH ES w/ | 2963 | A128KW | | SHA-256 | | | Concat KDF | 2964 | | | | | | and AES Key | 2965 | | | | | | wrap w/ 128 | 2966 | | | | | | bit key | 2967 | | | | | | | 2968 | ECDH-ES + | -30 | HKDF - | yes | A192KW | ECDH ES w/ | 2969 | A192KW | | SHA-256 | | | Concat KDF | 2970 | | | | | | and AES Key | 2971 | | | | | | wrap w/ 192 | 2972 | | | | | | bit key | 2973 | | | | | | | 2974 | ECDH-ES + | -31 | HKDF - | yes | A256KW | ECDH ES w/ | 2975 | A256KW | | SHA-256 | | | Concat KDF | 2976 | | | | | | and AES Key | 2977 | | | | | | wrap w/ 256 | 2978 | | | | | | bit key | 2979 | | | | | | | 2980 | ECDH-SS + | -32 | HKDF - | no | A128KW | ECDH SS w/ | 2981 | A128KW | | SHA-256 | | | Concat KDF | 2982 | | | | | | and AES Key | 2983 | | | | | | wrap w/ 128 | 2984 | | | | | | bit key | 2985 | | | | | | | 2986 | ECDH-SS + | -33 | HKDF - | no | A192KW | ECDH SS w/ | 2987 | A192KW | | SHA-256 | | | Concat KDF | 2988 | | | | | | and AES Key | 2989 | | | | | | wrap w/ 192 | 2990 | | | | | | bit key | 2991 | | | | | | | 2992 | ECDH-SS + | -34 | HKDF - | no | A256KW | ECDH SS w/ | 2993 | A256KW | | SHA-256 | | | Concat KDF | 2994 | | | | | | and AES Key | 2995 | | | | | | wrap w/ 256 | 2996 | | | | | | bit key | 2997 +-----------+-------+---------+------------+--------+---------------+ 2999 Table 20: ECDH Algorithm Values 3001 When using a COSE key for this algorithm, the following checks are 3002 made: 3004 o The 'kty' field MUST be present and it MUST be 'EC2' or 'OKP'. 3006 o If the 'alg' field present, it MUST match the Key Agreement 3007 algorithm being used. 3009 o If the 'key_ops' field is present, it MUST include 'derive key' or 3010 'derive bits' for the private key. 3012 o If the 'key_ops' field is present, it MUST be empty for the public 3013 key. 3015 13. Keys 3017 The COSE_Key object defines a way to hold a single key object. It is 3018 still required that the members of individual key types be defined. 3019 This section of the document is where we define an initial set of 3020 members for specific key types. 3022 For each of the key types, we define both public and private members. 3023 The public members are what is transmitted to others for their usage. 3024 Private members allow for the archival of keys by individuals. 3025 However, there are some circumstances in which private keys may be 3026 distributed to entities in a protocol. Examples include: entities 3027 that have poor random number generation, centralized key creation for 3028 multi-cast type operations, and protocols in which a shared secret is 3029 used as a bearer token for authorization purposes. 3031 Key types are identified by the 'kty' member of the COSE_Key object. 3032 In this document, we define four values for the member: 3034 +-----------+-------+--------------------------------------------+ 3035 | name | value | description | 3036 +-----------+-------+--------------------------------------------+ 3037 | OPK | 1 | Octet Key Pair | 3038 | | | | 3039 | EC2 | 2 | Elliptic Curve Keys w/ X,Y Coordinate pair | 3040 | | | | 3041 | Symmetric | 4 | Symmetric Keys | 3042 | | | | 3043 | Reserved | 0 | This value is reserved | 3044 +-----------+-------+--------------------------------------------+ 3046 Table 21: Key Type Values 3048 13.1. Elliptic Curve Keys 3050 Two different key structures could be defined for Elliptic Curve 3051 keys. One version uses both an x and a y coordinate, potentially 3052 with point compression ('EC2'). This is the traditional EC point 3053 representation that is used in [RFC5480]. The other version uses 3054 only the x coordinate as the y coordinate is either to be recomputed 3055 or not needed for the key agreement operation ('OKP'). 3057 Applications MUST check that the curve and the key type are 3058 consistent and reject a key if they are not. 3060 +---------+----------+-------+------------------------------------+ 3061 | name | key type | value | description | 3062 +---------+----------+-------+------------------------------------+ 3063 | P-256 | EC2 | 1 | NIST P-256 also known as secp256r1 | 3064 | | | | | 3065 | P-384 | EC2 | 2 | NIST P-384 also known as secp384r1 | 3066 | | | | | 3067 | P-521 | EC2 | 3 | NIST P-521 also known as secp521r1 | 3068 | | | | | 3069 | X25519 | OKP | 4 | X25519 for use w/ ECDH only | 3070 | | | | | 3071 | X448 | OKP | 5 | X448 for use w/ ECDH only | 3072 | | | | | 3073 | Ed25519 | OKP | 6 | Ed25519 for use w/ EdDSA only | 3074 | | | | | 3075 | Ed448 | OKP | 7 | Ed448 for use w/ EdDSA only | 3076 +---------+----------+-------+------------------------------------+ 3078 Table 22: EC Curves 3080 13.1.1. Double Coordinate Curves 3082 The traditional way of sending EC curves has been to send either both 3083 the x and y coordinates, or the x coordinate and a sign bit for the y 3084 coordinate. The latter encoding has not been recommended in the IETF 3085 due to potential IPR issues. However, for operations in constrained 3086 environments, the ability to shrink a message by not sending the y 3087 coordinate is potentially useful. 3089 For EC keys with both coordinates, the 'kty' member is set to 2 3090 (EC2). The key parameters defined in this section are summarized in 3091 Table 23. The members that are defined for this key type are: 3093 crv contains an identifier of the curve to be used with the key. 3094 The curves defined in this document for this key type can be found 3095 in Table 22. Other curves may be registered in the future and 3096 private curves can be used as well. 3098 x contains the x coordinate for the EC point. The integer is 3099 converted to an octet string as defined in [SEC1]. Leading zero 3100 octets MUST be preserved. 3102 y contains either the sign bit or the value of y coordinate for the 3103 EC point. When encoding the value y, the integer is converted to 3104 an octet string (as defined in [SEC1]) and encoded as a CBOR bstr. 3105 Leading zero octets MUST be preserved. The compressed point 3106 encoding is also supported. Compute the sign bit as laid out in 3107 the Elliptic-Curve-Point-to-Octet-String Conversion function of 3108 [SEC1]. If the sign bit is zero, then encode y as a CBOR false 3109 value, otherwise encode y as a CBOR true value. The encoding of 3110 the infinity point is not supported. 3112 d contains the private key. 3114 For public keys, it is REQUIRED that 'crv', 'x' and 'y' be present in 3115 the structure. For private keys, it is REQUIRED that 'crv' and 'd' 3116 be present in the structure. For private keys, it is RECOMMENDED 3117 that 'x' and 'y' also be present, but they can be recomputed from the 3118 required elements and omitting them saves on space. 3120 +------+-------+-------+---------+----------------------------------+ 3121 | name | key | value | type | description | 3122 | | type | | | | 3123 +------+-------+-------+---------+----------------------------------+ 3124 | crv | 2 | -1 | int / | EC Curve identifier - Taken from | 3125 | | | | tstr | the COSE Curve Registry | 3126 | | | | | | 3127 | x | 2 | -2 | bstr | X Coordinate | 3128 | | | | | | 3129 | y | 2 | -3 | bstr / | Y Coordinate | 3130 | | | | bool | | 3131 | | | | | | 3132 | d | 2 | -4 | bstr | Private key | 3133 +------+-------+-------+---------+----------------------------------+ 3135 Table 23: EC Key Parameters 3137 13.2. Octet Key Pair 3139 A new key type is defined for Octet Key Pairs (OKP). Do not assume 3140 that keys using this type are elliptic curves. This key type could 3141 be used for other curve types (for example mathematics based on 3142 hyper-elliptic surfaces). 3144 The key parameters defined in this section are summarized in 3145 Table 24. The members that are defined for this key type are: 3147 crv contains an identifier of the curve to be used with the key. 3148 The curves defined in this document for this key type can be found 3149 in Table 22. Other curves may be registered in the future and 3150 private curves can be used as well. 3152 x contains the x coordinate for the EC point. The octet string 3153 represents a little-endian encoding of x. 3155 d contains the private key. 3157 For public keys, it is REQUIRED that 'crv' and 'x' be present in the 3158 structure. For private keys, it is REQUIRED that 'crv' and 'd' be 3159 present in the structure. For private keys, it is RECOMMENDED that 3160 'x' also be present, but it can be recomputed from the required 3161 elements and omitting it saves on space. 3163 +------+-------+-------+--------+-----------------------------------+ 3164 | name | key | value | type | description | 3165 | | type | | | | 3166 +------+-------+-------+--------+-----------------------------------+ 3167 | crv | 1 | -1 | int / | EC Curve identifier - Taken from | 3168 | | | | tstr | the COSE General Registry | 3169 | | | | | | 3170 | x | 1 | -2 | bstr | X Coordinate | 3171 | | | | | | 3172 | d | 1 | -4 | bstr | Private key | 3173 +------+-------+-------+--------+-----------------------------------+ 3175 Table 24: EC Key Parameters 3177 13.3. Symmetric Keys 3179 Occasionally it is required that a symmetric key be transported 3180 between entities. This key structure allows for that to happen. 3182 For symmetric keys, the 'kty' member is set to 3 (Symmetric). The 3183 member that is defined for this key type is: 3185 k contains the value of the key. 3187 This key structure contains only private key information, care must 3188 be taken that it is never transmitted accidentally. For public keys, 3189 there are no required fields. For private keys, it is REQUIRED that 3190 'k' be present in the structure. 3192 +------+----------+-------+------+-------------+ 3193 | name | key type | value | type | description | 3194 +------+----------+-------+------+-------------+ 3195 | k | 4 | -1 | bstr | Key Value | 3196 +------+----------+-------+------+-------------+ 3198 Table 25: Symmetric Key Parameters 3200 14. CBOR Encoder Restrictions 3202 There has been an attempt to limit the number of places where the 3203 document needs to impose restrictions on how the CBOR Encoder needs 3204 to work. We have managed to narrow it down to the following 3205 restrictions: 3207 o The restriction applies to the encoding the Sig_structure, the 3208 Enc_structure, and the MAC_structure. 3210 o The rules for Canonical CBOR (Section 3.9 of RFC 7049) MUST be 3211 used in these locations. The main rule that needs to be enforced 3212 is that all lengths in these structures MUST be encoded such that 3213 they are encoded using definite lengths and the minimum length 3214 encoding is used. 3216 o Applications MUST NOT generate messages with the same label used 3217 twice as a key in a single map. Applications MUST NOT parse and 3218 process messages with the same label used twice as a key in a 3219 single map. Applications can enforce the parse and process 3220 requirement by using parsers that will fail the parse step or by 3221 using parsers that will pass all keys to the application and the 3222 application can perform the check for duplicate keys. 3224 15. Application Profiling Considerations 3226 This document is designed to provide a set of security services, but 3227 not to provide implementation requirements for specific usage. The 3228 interoperability requirements are provided for how each of the 3229 individual services are used and how the algorithms are to be used 3230 for interoperability. The requirements about which algorithms and 3231 which services are needed is deferred to each application. 3233 Applications are therefore intended to profile the usage of this 3234 document. This section provides a set of guidelines and topics that 3235 applications need to consider when using this document. 3237 o Applications need to determine the set of messages defined in this 3238 document that they will be using. The set of messages corresponds 3239 fairly directly to the set of security services that are needed 3240 and to the security levels needed. 3242 o Applications may define new header parameters for a specific 3243 purpose. Applications will often times select specific header 3244 parameters to use or not to use. For example, an application 3245 would normally state a preference for using either the IV or the 3246 partial IV parameter. If the partial IV parameter is specified, 3247 then the application would also need to define how the fixed 3248 portion of the IV would be determined. 3250 o When applications use externally defined authenticated data, they 3251 need to define how that data is encoded. This document assumes 3252 that the data will be provided as a byte stream. More information 3253 can be found in Section 4.3. 3255 o Applications need to determine the set of security algorithms that 3256 are to be used. When selecting the algorithms to be used as the 3257 mandatory to implement set, consideration should be given to 3258 choosing different types of algorithms when two are chosen for a 3259 specific purpose. An example of this would be choosing HMAC- 3260 SHA512 and AES-CMAC as different MAC algorithms, the construction 3261 is vastly different between these two algorithms. This means that 3262 a weakening of one algorithm would be unlikely to lead to a 3263 weakening of the other algorithms. Of course, these algorithms do 3264 not provide the same level of security and thus may not be 3265 comparable for the desired security functionality. 3267 o Applications may need to provide some type of negotiation or 3268 discovery method if multiple algorithms or message structures are 3269 permitted. The method can be as simple as requiring 3270 preconfiguration of the set of algorithms to providing a discovery 3271 method built into the protocol. S/MIME provided a number of 3272 different ways to approach the problem that applications could 3273 follow: 3275 * Advertising in the message (S/MIME capabilities) [RFC5751]. 3277 * Advertising in the certificate (capabilities extension) 3278 [RFC4262]. 3280 * Minimum requirements for the S/MIME, which have been updated 3281 over time [RFC2633][RFC5751]. 3283 16. IANA Considerations 3285 16.1. CBOR Tag assignment 3287 It is requested that IANA assign the following tags from the "Concise 3288 Binary Object Representation (CBOR) Tags" registry. It is requested 3289 that the tags for COSE_Sign1, COSE_Encrypt1 and COSE_Mac0 be assigned 3290 in the 1 to 23 value range (i.e. one byte long when encoded). It is 3291 requested that the rest of the tags be assigned in the 24 to 255 3292 value range (i.e. two bytes long when encoded). 3294 The tags to be assigned are in table Table 1. 3296 16.2. COSE Header Parameter Registry 3298 It is requested that IANA create a new registry entitled "COSE Header 3299 Parameters". The registry is to be created as Expert Review 3300 Required. Expert review guidelines are provided in Section 16.10 3302 The columns of the registry are: 3304 name The name is present to make it easier to refer to and discuss 3305 the registration entry. The value is not used in the protocol. 3306 Names are to be unique in the table. 3308 label This is the value used for the label. The label can be either 3309 an integer or a string. Registration in the table is based on the 3310 value of the label requested. Integer values between 1 and 255 3311 and strings of length 1 are designated as Standards Track Document 3312 required. Integer values from 256 to 65535 and strings of length 3313 2 are designated as Specification Required. Integer values of 3314 greater than 65535 and strings of length greater than 2 are 3315 designated as expert review. Integer values in the range -1 to 3316 -65536 are delegated to the "COSE Header Algorithm Label" 3317 registry. Integer values beyond -65536 are marked as private use. 3319 value This contains the CBOR type for the value portion of the 3320 label. 3322 value registry This contains a pointer to the registry used to 3323 contain values where the set is limited. 3325 description This contains a brief description of the header field. 3327 specification This contains a pointer to the specification defining 3328 the header field (where public). 3330 The initial contents of the registry can be found in Table 2. The 3331 specification column for all rows in that table should be this 3332 document. 3334 Additionally, the label of 0 is to be marked as 'Reserved'. 3336 16.3. COSE Header Algorithm Label Table 3338 It is requested that IANA create a new registry entitled "COSE Header 3339 Algorithm Labels". The registry is to be created as Expert Review 3340 Required. Expert review guidelines are provided in Section 16.10 3342 The columns of the registry are: 3344 name The name is present to make it easier to refer to and discuss 3345 the registration entry. The value is not used in the protocol. 3347 algorithm The algorithm(s) that this registry entry is used for. 3348 This value is taken from the "COSE Algorithm Value" registry. 3349 Multiple algorithms can be specified in this entry. For the 3350 table, the algorithm, label pair MUST be unique. 3352 label This is the value used for the label. The label is an integer 3353 in the range of -1 to -65536. 3355 value This contains the CBOR type for the value portion of the 3356 label. 3358 value registry This contains a pointer to the registry used to 3359 contain values where the set is limited. 3361 description This contains a brief description of the header field. 3363 specification This contains a pointer to the specification defining 3364 the header field (where public). 3366 The initial contents of the registry can be found in Table 13, 3367 Table 14, and Table 19. The specification column for all rows in 3368 that table should be this document. 3370 16.4. COSE Algorithm Registry 3372 It is requested that IANA create a new registry entitled "COSE 3373 Algorithm Registry". The registry is to be created as Expert Review 3374 Required. Expert review guidelines are provided in Section 16.10 3376 The columns of the registry are: 3378 value The value to be used to identify this algorithm. Algorithm 3379 values MUST be unique. The value can be a positive integer, a 3380 negative integer or a string. Integer values between -256 and 255 3381 and strings of length 1 are designated as Standards Track Document 3382 required. Integer values from -65536 to 65535 and strings of 3383 length 2 are designated as Specification Required. Integer values 3384 of greater than 65535 and strings of length greater than 2 are 3385 designated as expert review. Integer values beyond -65536 are 3386 marked as private use. 3388 description A short description of the algorithm. 3390 specification A document where the algorithm is defined (if publicly 3391 available). 3393 The initial contents of the registry can be found in Table 10, 3394 Table 9, Table 11, Table 5, Table 7, Table 8, Table 15, Table 16, 3395 Table 17, and Table 18. The specification column for all rows in 3396 that table should be this document. 3398 NOTE: The assignment of algorithm identifiers in this document was 3399 done so that positive numbers were used for the first level objects 3400 (COSE_Sign, COSE_Sign1, COSE_Encrypt, COSE_Encrypt1, COSE_Mac and 3401 COSE_Mac0). Negative numbers were used for second level objects 3402 (COSE_Signature and COSE_recipient). Expert reviewers should 3403 consider this practice, but are not expected to be restricted by this 3404 precedent. 3406 16.5. COSE Key Common Parameter Registry 3408 It is requested that IANA create a new registry entitled "COSE Key 3409 Common Parameter" Registry. The registry is to be created as Expert 3410 Review Required. Expert review guidelines are provided in 3411 Section 16.10 3413 The columns of the registry are: 3415 name This is a descriptive name that enables easier reference to the 3416 item. It is not used in the encoding. 3418 label The value to be used to identify this algorithm. Key map 3419 labels MUST be unique. The label can be a positive integer, a 3420 negative integer or a string. Integer values between 0 and 255 3421 and strings of length 1 are designated as Standards Track Document 3422 required. Integer values from 256 to 65535 and strings of length 3423 2 are designated as Specification Required. Integer values of 3424 greater than 65535 and strings of length greater than 2 are 3425 designated as expert review. Integer values in the range -1 to 3426 -65536 are used for key parameters specific to a single algorithm 3427 delegated to the "COSE Key Type Parameter Label" registry. 3428 Integer values beyond -65536 are marked as private use. 3430 CBOR Type This field contains the CBOR type for the field 3432 registry This field denotes the registry that values come from, if 3433 one exists. 3435 description This field contains a brief description for the field 3437 specification This contains a pointer to the public specification 3438 for the field if one exists 3440 This registry will be initially populated by the values in 3441 Section 7.1. The specification column for all of these entries will 3442 be this document. 3444 16.6. COSE Key Type Parameter Registry 3446 It is requested that IANA create a new registry "COSE Key Type 3447 Parameters". The registry is to be created as Expert Review 3448 Required. Expert review guidelines are provided in Section 16.10 3450 The columns of the table are: 3452 key type This field contains a descriptive string of a key type. 3453 This should be a value that is in the COSE General Values table 3454 and is placed in the 'kty' field of a COSE Key structure. 3456 name This is a descriptive name that enables easier reference to the 3457 item. It is not used in the encoding. 3459 label The label is to be unique for every value of key type. The 3460 range of values is from -256 to -1. Labels are expected to be 3461 reused for different keys. 3463 CBOR type This field contains the CBOR type for the field 3465 description This field contains a brief description for the field 3467 specification This contains a pointer to the public specification 3468 for the field if one exists 3470 This registry will be initially populated by the values in Table 23 3471 and Table 25. The specification column for all of these entries will 3472 be this document. 3474 16.7. COSE Elliptic Curve Registry 3476 It is requested that IANA create a new registry "COSE Elliptic Curve 3477 Parameters". The registry is to be created as Expert Review 3478 Required. Expert review guidelines are provided in Section 16.10 3480 The columns of the table are: 3482 name This is a descriptive name that enables easier reference to the 3483 item. It is not used in the encoding. 3485 value This is the value used to identify the curve. These values 3486 MUST be unique. The integer values from -256 to 255 are 3487 designated as Standards Track Document Required. The integer 3488 values from 256 to 65535 and -65536 to -257 are designated as 3489 Specification Required. Integer values over 65535 are designated 3490 as expert review. Integer values less than -65536 are marked as 3491 private use. 3493 key type This designates the key type(s) that can be used with this 3494 curve. 3496 description This field contains a brief description of the curve. 3498 specification This contains a pointer to the public specification 3499 for the curve if one exists. 3501 This registry will be initially populated by the values in Table 21. 3502 The specification column for all of these entries will be this 3503 document. 3505 16.8. Media Type Registrations 3507 16.8.1. COSE Security Message 3509 This section registers the "application/cose" media type in the 3510 "Media Types" registry. These media types are used to indicate that 3511 the content is a COSE_MSG. 3513 Type name: application 3515 Subtype name: cose 3517 Required parameters: N/A 3519 Optional parameters: cose-type 3521 Encoding considerations: binary 3522 Security considerations: See the Security Considerations section 3523 of RFC TBD. 3525 Interoperability considerations: N/A 3527 Published specification: RFC TBD 3529 Applications that use this media type: To be identified 3531 Fragment identifier considerations: N/A 3533 Additional information: 3535 * Magic number(s): N/A 3537 * File extension(s): cbor 3539 * Macintosh file type code(s): N/A 3541 Person & email address to contact for further information: 3542 iesg@ietf.org 3544 Intended usage: COMMON 3546 Restrictions on usage: N/A 3548 Author: Jim Schaad, ietf@augustcellars.com 3550 Change Controller: IESG 3552 Provisional registration? No 3554 16.8.2. COSE Key media type 3556 This section registers the "application/cose-key+cbor" and 3557 "application/cose-key-set+cbor" media types in the "Media Types" 3558 registry. These media types are used to indicate, respectively, that 3559 content is a COSE_Key or COSE_KeySet object. 3561 Type name: application 3563 Subtype name: cose-key+cbor 3565 Required parameters: N/A 3567 Optional parameters: N/A 3569 Encoding considerations: binary 3570 Security considerations: See the Security Considerations section 3571 of RFC TBD. 3573 Interoperability considerations: N/A 3575 Published specification: RFC TBD 3577 Applications that use this media type: To be identified 3579 Fragment identifier considerations: N/A 3581 Additional information: 3583 * Magic number(s): N/A 3585 * File extension(s): cbor 3587 * Macintosh file type code(s): N/A 3589 Person & email address to contact for further information: 3590 iesg@ietf.org 3592 Intended usage: COMMON 3594 Restrictions on usage: N/A 3596 Author: Jim Schaad, ietf@augustcellars.com 3598 Change Controller: IESG 3600 Provisional registration? No 3602 Type name: application 3604 Subtype name: cose-key-set+cbor 3606 Required parameters: N/A 3608 Optional parameters: N/A 3610 Encoding considerations: binary 3612 Security considerations: See the Security Considerations section 3613 of RFC TBD. 3615 Interoperability considerations: N/A 3617 Published specification: RFC TBD 3618 Applications that use this media type: To be identified 3620 Fragment identifier considerations: N/A 3622 Additional information: 3624 * Magic number(s): N/A 3626 * File extension(s): cbor 3628 * Macintosh file type code(s): N/A 3630 Person & email address to contact for further information: 3631 iesg@ietf.org 3633 Intended usage: COMMON 3635 Restrictions on usage: N/A 3637 Author: Jim Schaad, ietf@augustcellars.com 3639 Change Controller: IESG 3641 Provisional registration? No 3643 16.9. CoAP Content Format Registrations 3645 This section registers a set of content formats for CoAP. ID 3646 assignment in the 24-255 range is requested. 3648 +---------------------------------+----------+-------+--------------+ 3649 | Media Type | Encoding | ID | Reference | 3650 +---------------------------------+----------+-------+--------------+ 3651 | application/cose; cose-type | | TBD10 | [This | 3652 | ="cose-sign" | | | Document] | 3653 | | | | | 3654 | application/cose; cose-type | | TBD11 | [This | 3655 | ="cose-sign1" | | | Document] | 3656 | | | | | 3657 | application/cose; cose-type | | TBD12 | [This | 3658 | ="cose-encrypt" | | | Document] | 3659 | | | | | 3660 | application/cose; cose-type | | TBD13 | [This | 3661 | ="cose-encrypt1" | | | Document] | 3662 | | | | | 3663 | application/cose; cose-type | | TBD14 | [This | 3664 | ="cose-mac" | | | Document] | 3665 | | | | | 3666 | application/cose; cose-type | | TBD15 | [This | 3667 | ="cose-mac0" | | | Document] | 3668 | | | | | 3669 | application/cose-key | | TBD16 | [This | 3670 | | | | Document] | 3671 | | | | | 3672 | application/cose-key-set | | TBD17 | [This | 3673 | | | | Document | 3674 +---------------------------------+----------+-------+--------------+ 3676 Table 26 3678 16.10. Expert Review Instructions 3680 All of the IANA registries established in this document are defined 3681 as expert review. This section gives some general guidelines for 3682 what the experts should be looking for, but they are being designated 3683 as experts for a reason so they should be given substantial latitude. 3685 Expert reviewers should take into consideration the following points: 3687 o Point squatting should be discouraged. Reviewers are encouraged 3688 to get sufficient information for registration requests to ensure 3689 that the usage is not going to duplicate one that is already 3690 registered and that the point is likely to be used in deployments. 3691 The zones tagged as private use are intended for testing purposes 3692 and closed environments, code points in other ranges should not be 3693 assigned for testing. 3695 o Specifications are required for the standards track range of point 3696 assignment. Specifications should exist for specification 3697 required ranges, but early assignment before a specification is 3698 available is considered to be permissible. Specifications are 3699 needed for the first-come, first-serve range if they are expected 3700 to be used outside of closed environments in an inoperable way. 3701 When specifications are not provided, the description provided 3702 needs to have sufficient information to identify what point is 3703 being used for. 3705 o Experts should take into account the expected usage of fields when 3706 approving point assignment. The fact that there is a range for 3707 standards track documents does not mean that a standards track 3708 document cannot have points assigned outside of that range. Some 3709 of the ranges are restricted in range, items which are not 3710 expected to be common or are not expected to be used in restricted 3711 environments should be assigned to values which will encode to 3712 longer byte strings. 3714 o When algorithms are registered, vanity registrations should be 3715 discouraged. One way to do this is to require applications to 3716 provide additional documentation on security analysis of 3717 algorithms. Another thing that should be considered is to request 3718 for an opinion on the algorithm from the Cryptographic Forum 3719 Research Group. Algorithms which do not meet the security 3720 requirements of the community and the messages structures should 3721 not be registered. 3723 17. Implementation Status 3725 This section records the status of known implementations of the 3726 protocol defined by this specification at the time of posting of this 3727 Internet-Draft, and is based on a proposal described in [RFC6982]. 3728 The description of implementations in this section is intended to 3729 assist the IETF in its decision processes in progressing drafts to 3730 RFCs. Please note that the listing of any individual implementation 3731 here does not imply endorsement by the IETF. Furthermore, no effort 3732 has been spent to verify the information presented here that was 3733 supplied by IETF contributors. This is not intended as, and must not 3734 be construed to be, a catalog of available implementations or their 3735 features. Readers are advised to note that other implementations may 3736 exist. 3738 According to [RFC6982], "this will allow reviewers and working groups 3739 to assign due consideration to documents that have the benefit of 3740 running code, which may serve as evidence of valuable experimentation 3741 and feedback that have made the implemented protocols more mature. 3743 It is up to the individual working groups to use this information as 3744 they see fit". 3746 17.1. Author's Versions 3748 There are three different implementations that have been created by 3749 the author of the document both to create the examples that are 3750 included in the document and to validate the structures and 3751 methodology used in the design of COSE. 3753 Implemenation Location: https://github.com/cose-wg 3755 Primary Maintainer: Jim Schaad 3757 Languages: There are three different languages that are current 3758 supported: JAVA, C# and C. 3760 Cryptography: The JAVA and C# libraries use Bouncy Castle to 3761 provide the required cryptography. The C version uses OPENSSL 3762 Version 1.0 for the cryptography. 3764 Coverage: The libraries currently do not have full support for 3765 counter signatures of either variety. They do have support to 3766 allow for implicit algorithm support as they allow for the 3767 application to set attributes which are not to be sent in the 3768 message. 3770 Testing: All of the examples in the example library are generated 3771 by the C# library and then validated using the JAVA and C 3772 libraries. All three libraries have tests to allow for the 3773 creating of a the same messages that are in the example library 3774 followed by validating them. These are not compared against the 3775 example library. The JAVA and C# libraries have unit testing 3776 included. Not all of the MUST statements in the document have 3777 been implemented as part of the libraries. One such statement is 3778 the requirement that unique labels be present. 3780 Licensing: Revised BSD License 3782 17.2. COSE Testing Library 3784 Implemenation Location: https://github.com/cose-wg/Examples 3786 Primary Maintainer: Jim Schaad 3788 Description: A set of tests for the COSE library is provided as 3789 part of the implementation effort. Both success and fail tests 3790 has been provided. All of the examples in this document are are 3791 part of this example set. 3793 Coverage: The attempt has been to have test cases for every 3794 message type and algorithm in the document. Current examples 3795 dealing with counter signatures, EdDSA and ECDH with Curve24459 3796 and Goldilocks are missing. 3798 Licensing: Public Domain 3800 18. Security Considerations 3802 There are a number of security considerations that need to be taken 3803 into account by implementers of this specification. The security 3804 considerations that are specific to an individual algorithm are 3805 placed next to the description of the algorithm. While some 3806 considerations have been highlighted here, additional considerations 3807 may be found in the documents listed in the references. 3809 Implementations need to protect the private key for any individuals. 3810 There are some cases in this document that need to be highlighted on 3811 this issue. 3813 o Using the same key for two different algorithms can leak 3814 information about the key. It is therefore recommended that keys 3815 be restricted to a single algorithm. 3817 o Use of 'direct' as a recipient algorithm combined with a second 3818 recipient algorithm, either directly in a separate message, 3819 exposes the direct key to the second recipient. 3821 o Several of the algorithms in this document have limits on the 3822 number of times that a key can be used without leaking information 3823 about the key. 3825 The use of ECDH and direct plus KDF (with no key wrap) will not 3826 directly lead to the private key being leaked, the one way function 3827 of the KDF will prevent that. There is however a different issue 3828 that needs to be addressed. Having two recipients, requires that the 3829 CEK be shared between two recipients. The second recipient therefore 3830 has a CEK that was derived from material that can be used for the 3831 weak proof of origin. The second recipient could create a message 3832 using the same CEK and send it to the first recipient, the first 3833 recipient would, for either static-static ECDH or direct plus KDF, 3834 make an assumption that the CEK could be used for proof of origin 3835 even though it is from the wrong entity. If the key wrap step is 3836 added, then no proof of origin is implied and thus is not an issue. 3838 Although it has been mentioned before, the use of a single key for 3839 multiple algorithms has been demonstrated in some cases to leak 3840 information about a key, provide for attackers to forge integrity 3841 tags, or gain information about encrypted content. Binding a key to 3842 a single algorithm prevents these problems. Key creators and key 3843 consumers are strongly encourged not only to create new keys for each 3844 different algorithm, but to include that selection of algorithm in 3845 any distribution of key material and strictly enforce the matching of 3846 algorithms in the key structure to algorithms in the message 3847 structure. In addition to checking that algorithms are correct, the 3848 key form needs to be checked as well. Do not use an 'EC2' key where 3849 an 'oct' key is expected. 3851 Before using a key for transmission, or before acting on information 3852 recieved, a trust decision on a key needs to be made. Is the data or 3853 action something that the entity associated with the key has a right 3854 to see or a right to request. A number of factors are associated 3855 with this trust decision. Some of the ones that are highlighted here 3856 are: 3858 o What are the permissions associated with the key owner? 3860 o Is the cryptographic algorithm acceptable in the current context? 3862 o Have the restrictions associated with the key, such as algorithm 3863 or freshness, been checked and are correct? 3865 o Is the request something that is reasonable given the current 3866 state of the application? 3868 o Have any security considerations that are part of the message been 3869 enforced? (As specified by the application or crit parameter.) 3871 One area that has been starting to get exposure is doing traffic 3872 analysis of encrypted messages based on the length of the message. 3873 This specification does not provide for a uniform method of providing 3874 padding as part of the message structure. An observer can 3875 distinguish between two different strings (for example 'YES' and 3876 'NO') based on length for all of the content encryption algorithms 3877 that are defined in this document. This means that it is up to 3878 applications to document how content padding is to be done in order 3879 to prevent or discourage such analysis. (For example the strings 3880 could be defined as 'YES' and 'NO '.) 3882 Timing Issues - TBD 3884 19. References 3886 19.1. Normative References 3888 [AES-GCM] Dworkin, M., "NIST Special Publication 800-38D: 3889 Recommendation for Block Cipher Modes of Operation: 3890 Galois/Counter Mode (GCM) and GMAC.", Nov 2007. 3892 [DSS] U.S. National Institute of Standards and Technology, 3893 "Digital Signature Standard (DSS)", July 2013. 3895 [MAC] NiST, N., "FIPS PUB 113: Computer Data Authentication", 3896 May 1985. 3898 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 3899 Hashing for Message Authentication", RFC 2104, 3900 DOI 10.17487/RFC2104, February 1997, 3901 . 3903 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3904 Requirement Levels", BCP 14, RFC 2119, 3905 DOI 10.17487/RFC2119, March 1997, 3906 . 3908 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 3909 (AES) Key Wrap Algorithm", RFC 3394, DOI 10.17487/RFC3394, 3910 September 2002, . 3912 [RFC3610] Whiting, D., Housley, R., and N. Ferguson, "Counter with 3913 CBC-MAC (CCM)", RFC 3610, DOI 10.17487/RFC3610, September 3914 2003, . 3916 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 3917 Key Derivation Function (HKDF)", RFC 5869, 3918 DOI 10.17487/RFC5869, May 2010, 3919 . 3921 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 3922 Curve Cryptography Algorithms", RFC 6090, 3923 DOI 10.17487/RFC6090, February 2011, 3924 . 3926 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 3927 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 3928 October 2013, . 3930 [RFC7539] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF 3931 Protocols", RFC 7539, DOI 10.17487/RFC7539, May 2015, 3932 . 3934 [SEC1] Standards for Efficient Cryptography Group, "SEC 1: 3935 Elliptic Curve Cryptography", May 2009. 3937 19.2. Informative References 3939 [I-D.greevenbosch-appsawg-cbor-cddl] 3940 Vigano, C. and H. Birkholz, "CBOR data definition language 3941 (CDDL): a notational convention to express CBOR data 3942 structures", draft-greevenbosch-appsawg-cbor-cddl-08 (work 3943 in progress), March 2016. 3945 [I-D.irtf-cfrg-eddsa] 3946 Josefsson, S. and I. Liusvaara, "Edwards-curve Digital 3947 Signature Algorithm (EdDSA)", draft-irtf-cfrg-eddsa-05 3948 (work in progress), March 2016. 3950 [PVSig] Brown, D. and D. Johnson, "Formal Security Proofs for a 3951 Signature Scheme with Partial Message Recover", February 3952 2000. 3954 [RFC2633] Ramsdell, B., Ed., "S/MIME Version 3 Message 3955 Specification", RFC 2633, DOI 10.17487/RFC2633, June 1999, 3956 . 3958 [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography 3959 Specification Version 2.0", RFC 2898, 3960 DOI 10.17487/RFC2898, September 2000, 3961 . 3963 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 3964 Standards (PKCS) #1: RSA Cryptography Specifications 3965 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 3966 2003, . 3968 [RFC4231] Nystrom, M., "Identifiers and Test Vectors for HMAC-SHA- 3969 224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512", 3970 RFC 4231, DOI 10.17487/RFC4231, December 2005, 3971 . 3973 [RFC4262] Santesson, S., "X.509 Certificate Extension for Secure/ 3974 Multipurpose Internet Mail Extensions (S/MIME) 3975 Capabilities", RFC 4262, DOI 10.17487/RFC4262, December 3976 2005, . 3978 [RFC4493] Song, JH., Poovendran, R., Lee, J., and T. Iwata, "The 3979 AES-CMAC Algorithm", RFC 4493, DOI 10.17487/RFC4493, June 3980 2006, . 3982 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 3983 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 3984 . 3986 [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, 3987 "Elliptic Curve Cryptography Subject Public Key 3988 Information", RFC 5480, DOI 10.17487/RFC5480, March 2009, 3989 . 3991 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 3992 RFC 5652, DOI 10.17487/RFC5652, September 2009, 3993 . 3995 [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet 3996 Mail Extensions (S/MIME) Version 3.2 Message 3997 Specification", RFC 5751, DOI 10.17487/RFC5751, January 3998 2010, . 4000 [RFC5752] Turner, S. and J. Schaad, "Multiple Signatures in 4001 Cryptographic Message Syntax (CMS)", RFC 5752, 4002 DOI 10.17487/RFC5752, January 2010, 4003 . 4005 [RFC5990] Randall, J., Kaliski, B., Brainard, J., and S. Turner, 4006 "Use of the RSA-KEM Key Transport Algorithm in the 4007 Cryptographic Message Syntax (CMS)", RFC 5990, 4008 DOI 10.17487/RFC5990, September 2010, 4009 . 4011 [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations 4012 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 4013 RFC 6151, DOI 10.17487/RFC6151, March 2011, 4014 . 4016 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 4017 Algorithm (DSA) and Elliptic Curve Digital Signature 4018 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 4019 2013, . 4021 [RFC6982] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 4022 Code: The Implementation Status Section", RFC 6982, 4023 DOI 10.17487/RFC6982, July 2013, 4024 . 4026 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 4027 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 4028 2014, . 4030 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 4031 Application Protocol (CoAP)", RFC 7252, 4032 DOI 10.17487/RFC7252, June 2014, 4033 . 4035 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 4036 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 4037 2015, . 4039 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 4040 RFC 7516, DOI 10.17487/RFC7516, May 2015, 4041 . 4043 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 4044 DOI 10.17487/RFC7517, May 2015, 4045 . 4047 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 4048 DOI 10.17487/RFC7518, May 2015, 4049 . 4051 [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 4052 for Security", RFC 7748, DOI 10.17487/RFC7748, January 4053 2016, . 4055 [SP800-56A] 4056 Barker, E., Chen, L., Roginsky, A., and M. Smid, "NIST 4057 Special Publication 800-56A: Recommendation for Pair-Wise 4058 Key Establishment Schemes Using Discrete Logarithm 4059 Cryptography", May 2013. 4061 Appendix A. Making Mandatory Algorithm Header Optional 4063 There has been a portion of the working group who have expressed a 4064 strong desire to relax the rule that the algorithm identifier be 4065 required to appear in each level of a COSE message. There are two 4066 basic reasons that have been advanced to support this position. 4067 First, the resulting message will be smaller if the algorithm 4068 identifier is omitted from the most common messages in a CoAP 4069 environment. Second, there is a potential bug that will arise if 4070 full checking is not done correctly between the different places that 4071 an algorithm identifier could be placed. (The message itself, an 4072 application statement, the key structure that the sender possesses 4073 and the key structure the recipient possesses.) 4074 This appendix lays out how such a change can be made and the details 4075 that an application needs to specify in order to use this option. 4076 Two different sets of details are specified: Those needed to omit an 4077 algorithm identifier and those needed to use a variant on the counter 4078 signature attribute which contains no attributes about itself. 4080 A.1. Algorithm Identification 4082 In this section are laid out three sets of recommendations. The 4083 first set of recommendations apply to having an implicit algorithm 4084 identified for a single layer of a COSE message. The second set of 4085 recommendations apply to having multiple implicit algorithm 4086 identified for multiple layers of a COSE message. The third set of 4087 recommendations apply to having implicit algorithms for multiple COSE 4088 message constructs. 4090 RFC 2119 language is deliberately not used here, this specification 4091 can provide recommendations, but it cannot enforce them. 4093 This set of recommendations applies to the case where an application 4094 is distributing a fixed algorithm along with the key information for 4095 use in a single COSE message object. This normally applies to the 4096 smallest of the COSE messages, specifically COSE_Sign1, COSE_Mac0 and 4097 COSE_Encrypt1, but could apply to the other structures as well. 4099 The following items should be taken into account: 4101 o Applications need to list the set of COSE structures that implicit 4102 algorithms are to be used in. Applications need to require that 4103 the receipt of an explicit algorithm identifier in one of these 4104 structures will lead to the message being rejected. This 4105 requirement is stated so that there will never be a case where 4106 there is any ambiguity about the question of which algorithm 4107 should be used, the implicit or the explicit one. This applies 4108 even if the transported algorithm identifier is a protected 4109 attribute. This applies even if the transported algorithm is the 4110 same as the implicit algorithm. 4112 o Applications need to define the set of information that is to be 4113 considered to be part of a context when omitting algorithm 4114 identifiers. At a minimum this would be the key identifier (if 4115 needed), the key, the algorithm and the COSE structure it can be 4116 used for. Applications should restrict the use of a single key to 4117 a single algorithm. As noted for some of the algorithms in this 4118 document, the use of the same key in different related algorithms 4119 can lead to leakage of information about the key, leakage about 4120 the data or the ability to perform forgeries. 4122 o In many cases applications which make the algorithm identifier 4123 implicit will also want to make the context identifier implicit 4124 for the same reason. That is omitting the context identifier will 4125 decrease the message size (potentially significantly depending on 4126 the length of the identifier). Applications that do this will 4127 need to describe the circumstances where the context identifier is 4128 to be omitted and how the context identifier is to be inferred in 4129 these cases. (Exhaustive search over all of the keys would 4130 normally not be considered to be acceptable.) An example of how 4131 this can be done is to tie the context to a transaction 4132 identifier. Both would be sent on the original message, but only 4133 the transaction identifier would need to be sent after that point 4134 as the context is tied into the transaction identifier. Another 4135 way would be to associate a context with a network address. All 4136 messages coming from a single network address can be assumed to be 4137 associated with a specific context. (In this case the address 4138 would normally be distributed as part of the context.) 4140 o Applications cannot rely on key identifiers being unique unless 4141 they take significant efforts to ensure that they are computed in 4142 such a way as to create this guarantee. Even when an application 4143 does this, the uniqueness might be violated if the application is 4144 run in different contexts (i.e. with a different context provider) 4145 or if the system combines the security contexts from different 4146 applications together into a single store. 4148 o Applications should continue the practice of protecting the 4149 algorithm identifier. Since this is not done by placing it in the 4150 protected attributes field, applications should define an 4151 application specific external data structure which includes this 4152 value. This external data field can be used as such for content 4153 encryption, MAC and signature algorithms. It can be used in the 4154 SuppPrivInfo field for those algorithms which use a KDF function 4155 to derive a key value. Applications may also want to protect 4156 other information that is part of the context structure as well. 4157 It should be noted that those fields, such as the key or a base 4158 IV, protected by virtue of being used in the cryptogrpahic 4159 computation and do not need to be included in the external data 4160 field. 4162 The second case is having multiple implicit algorithm identifiers 4163 specified for a multiple layer COSE message. An example of how this 4164 would work is the encryption context that an application specifies 4165 contains a content encryption algorithm, a key wrap algorithm, a key 4166 identifier, and a shared secret. The sender omits sending the 4167 algorithm identifier for both the content layer and the recipient 4168 layer leaving only the key identifier. The receiver then uses the 4169 key identifier to get the implicit algorithm identifiers. 4171 The following additional items need to be taken into consideration: 4173 o Applications that want to support this will need to define a 4174 structure that allows for, and clearly identifies, both the COSE 4175 structure to be used with a given key and the structure and 4176 algorithm to be used for the secondary layer. The key for the 4177 secondary layer is computed per normal from the recipient layer. 4179 The third case is having multiple implicit algorithm identifiers, but 4180 targeted at potentially unrelated layers or different COSE messages. 4181 There are a number of different scenarios where this might be 4182 applicable. Some of these scenarios are: 4184 o Two contexts are distributed as a pair. Each of the contexts is 4185 for use with a COSE_Encrypt message. Each context will consist of 4186 distinct secret keys and IVs and potentially even different 4187 algorithms. One context is for sending messages from party A to 4188 party B, the second context is for sending messages from party B 4189 to party A. This means that there is no chance for a reflection 4190 attack to occur as each party uses different secret keys to send 4191 its messages, a message that is reflected back to it would fail to 4192 decrypt. 4194 o Two contexts are distributed as a pair. The first context is used 4195 for encryption of the message, the second context is used to place 4196 a counter signature on the message. The intention is that the 4197 second context can be distributed to other entities independently 4198 of the first context. This allows these entities to validate that 4199 the message came from an individual without being able to decrypt 4200 the message and see the content. 4202 o Two contexts are distributed as a pair. The first context 4203 contains a key for dealing with MAC messages, the second context 4204 contains a key for dealing with encrypted messages. This allows 4205 for a unified distribution of keys to participants for different 4206 types of messages which have different keys, but where the keys 4207 may be used in coordinated manner. 4209 For these cases, the following additional items need to be 4210 considered: 4212 o Applications need to ensure that the multiple contexts stay 4213 associated. If one of the contexts is invalidated for any reason, 4214 all of the contexts associated with it should also be invalidated. 4216 A.2. Counter Signature Without Headers 4218 There is a group of people who want to have a counter signature 4219 parameter that is directly tied to the value being signed and thus 4220 the authenticated and unauthenticated buckets can be removed from the 4221 message being sent. The focus on this is an even smaller size, as 4222 all of the information on the process of creating the counter 4223 signature is implicit rather than being explicitly carried in the 4224 message. This includes not only the algorithm identifier as 4225 presented above, but also items such as the key identification is 4226 always external to the signature structure. This means that the 4227 entities that are doing the validation of the counter signature are 4228 required to infer which key is to be used from context rather than 4229 being explicit. One way of doing this would be to presume that all 4230 data coming from a specific port (or to a specific URL) is to be 4231 validated by a specific key. (Note that this does not require that 4232 the key identifier be part of the value signed as it does not serve a 4233 cryptographic purpose. If the key validates the counter signature, 4234 then it should be presumed that the entity associated with that key 4235 produced the signature.) 4237 When computing the signature for the bare counter signature header, 4238 the same Sig_structure defined in Section 4.4. The sign_protected 4239 field is omitted as there is no protected header field in in this 4240 counter signature header. The value of "CounterSignature0" is placed 4241 in the context field of the Sig_stucture. 4243 +-------------------------------+-------+------------+-------------+ 4244 | name | label | value type | description | 4245 +-------------------------------+-------+------------+-------------+ 4246 | counter signature w/o headers | 9 | bstr | | 4247 +-------------------------------+-------+------------+-------------+ 4249 Table 27 4251 Appendix B. Three Levels of Recipient Information 4253 All of the currently defined recipient algorithms classes only use 4254 two levels of the COSE_Encrypt structure. The first level is the 4255 message content and the second level is the content key encryption. 4256 However, if one uses a recipient algorithm such as RSA-KEM (see 4257 Appendix A of RSA-KEM [RFC5990], then it make sense to have three 4258 levels of the COSE_Encrypt structure. 4260 These levels would be: 4262 o Level 0: The content encryption level. This level contains the 4263 payload of the message. 4265 o Level 1: The encryption of the CEK by a KEK. 4267 o Level 2: The encryption of a long random secret using an RSA key 4268 and a key derivation function to convert that secret into the KEK. 4270 This is an example of what a triple layer message would look like. 4271 The message has the following layers: 4273 o Level 0: Has a content encrypted with AES-GCM using a 128-bit key. 4275 o Level 1: Uses the AES Key wrap algorithm with a 128-bit key. 4277 o Level 2: Uses ECDH Ephemeral-Static direct to generate the level 1 4278 key. 4280 In effect this example is a decomposed version of using the ECDH- 4281 ES+A128KW algorithm. 4283 Appendix C. Examples 4285 This appendix includes a set of examples that show the different 4286 features and message types that have been defined in this document. 4287 To make the examples easier to read, they are presented using the 4288 extended CBOR diagnostic notation (defined in 4289 [I-D.greevenbosch-appsawg-cbor-cddl]) rather than as a binary dump. 4291 A GITHUB project has been created at https://github.com/cose-wg/ 4292 Examples that contains not only the examples presented in this 4293 document, but a more complete set of testing examples as well. Each 4294 example is found in a JSON file that contains the inputs used to 4295 create the example, some of the intermediate values that can be used 4296 in debugging the example and the output of the example presented in 4297 both a hex and a CBOR diagnostic notation format. Some of the 4298 examples at the site are designed failure testing cases, these are 4299 clearly marked as such in the JSON file. If errors in the examples 4300 in this document are found, the examples on github will be updated 4301 and a note to that effect will be placed in the JSON file. 4303 As noted, the examples are presented using the CBOR's diagnostic 4304 notation. A ruby based tool exists that can convert between the 4305 diagnostic notation and binary. This tool can be installed with the 4306 command line: 4308 gem install cbor-diag 4310 The diagnostic notation can be converted into binary files using the 4311 following command line: 4313 diag2cbor < inputfile > outputfile 4315 The examples can be extracted from the XML version of this document 4316 via an XPath expression as all of the artwork is tagged with the 4317 attribute type='CBORdiag'. (Depending on the XPath evaluator one is 4318 using, it may be necessary to deal with > as an entity.) 4320 //artwork[@type='CDDL']/text() 4322 C.1. Examples of Signed Message 4324 C.1.1. Single Signature 4326 This example uses the following: 4328 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256-1 4330 Size of binary file is 104 bytes 4332 991( 4333 [ 4334 / protected / h'', 4335 / unprotected / {}, 4336 / payload / 'This is the content.', 4337 / signatures / [ 4338 [ 4339 / protected / h'a10126' / { 4340 \ alg \ 1:-7 \ ECDSA 256 \ 4341 } / , 4342 / unprotected / { 4343 / kid / 4:'11' 4344 }, 4345 / signature / h'eae868ecc176883766c5dc5ba5b8dca25dab3c2e56a5 4346 51ce5705b793914348e14eea4aee6e0c9f09db4ef3ddeca8f3506cd1a98a8fb64327 4347 be470355c9657ce0' 4348 ] 4349 ] 4350 ] 4351 ) 4353 C.1.2. Multiple Signers 4355 This example uses the following: 4357 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256-1 4359 o Signature Algorithm: ECDSA w/ SHA-512, Curve P-521 4360 Size of binary file is 278 bytes 4362 991( 4363 [ 4364 / protected / h'', 4365 / unprotected / {}, 4366 / payload / 'This is the content.', 4367 / signatures / [ 4368 [ 4369 / protected / h'a10126' / { 4370 \ alg \ 1:-7 \ ECDSA 256 \ 4371 } / , 4372 / unprotected / { 4373 / kid / 4:'11' 4374 }, 4375 / signature / h'0dc1c5e62719d8f3cce1468b7c881eee6a8088b46bf8 4376 36ae956dd38fe93199199951a6a5e02a24aed5edde3509748366b1c539aaef7dea34 4377 f2cd618fe19fe55d' 4378 ], 4379 [ 4380 / protected / h'a1013823' / { 4381 \ alg \ 1:-36 4382 } / , 4383 / unprotected / { 4384 / kid / 4:'bilbo.baggins@hobbiton.example' 4385 }, 4386 / signature / h'012ce5b1dfe8b5aa6eaa09a54c58a84ad0900e4fdf27 4387 59ec22d1c861cccd75c7e1c4025a2da35e512fc2874d6ac8fd862d09ad07ed2deac2 4388 97b897561e04a8d42476017c11a4a34e26c570c9eff22c1dc84d56cdf6e03ed34bc9 4389 e934c5fdf676c7948d79e97dfe161730217c57748aadb364a0207cee811e9dde65ae 4390 37942e8a8348cc91' 4391 ] 4392 ] 4393 ] 4394 ) 4396 C.1.3. Counter Signature 4398 This example uses the following: 4400 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256-1 4402 o The same parameters are used for both the signature and the 4403 counter signature. 4405 Size of binary file is 181 bytes 4406 991( 4407 [ 4408 / protected / h'', 4409 / unprotected / { 4410 / countersign / 7:[ 4411 / protected / h'a10126' / { 4412 \ alg \ 1:-7 \ ECDSA 256 \ 4413 } / , 4414 / unprotected / { 4415 / kid / 4:'11' 4416 }, 4417 / signature / h'c9d3402485aa585cee3efc69b14496c0b00714584b26 4418 0f8e05764b7dbc70ae2be52a463555fc78e8da59bf8b3af281e739741dbac0b6f56a 4419 4b03ef23cb93b1e1' 4420 ] 4421 }, 4422 / payload / 'This is the content.', 4423 / signatures / [ 4424 [ 4425 / protected / h'a10126' / { 4426 \ alg \ 1:-7 \ ECDSA 256 \ 4427 } / , 4428 / unprotected / { 4429 / kid / 4:'11' 4430 }, 4431 / signature / h'eae868ecc176883766c5dc5ba5b8dca25dab3c2e56a5 4432 51ce5705b793914348e14eea4aee6e0c9f09db4ef3ddeca8f3506cd1a98a8fb64327 4433 be470355c9657ce0' 4434 ] 4435 ] 4436 ] 4437 ) 4439 C.1.4. Signature w/ Criticality 4441 This example uses the following: 4443 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256-1 4445 o There is a criticality marker on the "reserved" header parameter 4447 Size of binary file is 126 bytes 4448 991( 4449 [ 4450 / protected / h'a2687265736572766564f40281687265736572766564' / 4451 { 4452 "reserved":false, 4453 \ crit \ 2:[ 4454 "reserved" 4455 ] 4456 } / , 4457 / unprotected / {}, 4458 / payload / 'This is the content.', 4459 / signatures / [ 4460 [ 4461 / protected / h'a10126' / { 4462 \ alg \ 1:-7 \ ECDSA 256 \ 4463 } / , 4464 / unprotected / { 4465 / kid / 4:'11' 4466 }, 4467 / signature / h'eae868ecc176883766c5dc5ba5b8dca25dab3c2e56a5 4468 51ce5705b793914348e1ff259ead2c38d8a7d8a9c87c2ce534d762dab059773115a6 4469 176fa780e85b6b25' 4470 ] 4471 ] 4472 ] 4473 ) 4475 C.2. Single Signer Examples 4477 C.2.1. Single ECDSA signature 4479 This example uses the following: 4481 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256-1 4483 Size of binary file is 100 bytes 4484 997( 4485 [ 4486 / protected / h'a10126' / { 4487 \ alg \ 1:-7 \ ECDSA 256 \ 4488 } / , 4489 / unprotected / { 4490 / kid / 4:'11' 4491 }, 4492 / payload / 'This is the content.', 4493 h'eae868ecc176883766c5dc5ba5b8dca25dab3c2e56a551ce5705b793914348 4494 e19f43d6c6ba654472da301b645b293c9ba939295b97c4bdb847782bff384c5794' 4495 ] 4496 ) 4498 C.3. Examples of Enveloped Messages 4500 C.3.1. Direct ECDH 4502 This example uses the following: 4504 o CEK: AES-GCM w/ 128-bit key 4506 o Recipient class: ECDH Ephemeral-Static, Curve P-256 4508 Size of binary file is 185 bytes 4509 992( 4510 [ 4511 / protected / h'a10101' / { 4512 \ alg \ 1:1 \ AES-GCM 128 \ 4513 } / , 4514 / unprotected / { 4515 / iv / 5:h'c9cf4df2fe6c632bf7886413' 4516 }, 4517 / ciphertext / h'40970cd7ab5fbd10f505bf7a86e6fc0a99a3122475fbed3 4518 36488c3220f884f011ba219ea', 4519 / recipients / [ 4520 [ 4521 / protected / h'a1013818' / { 4522 \ alg \ 1:-25 \ ECDH-ES + HKDF-256 \ 4523 } / , 4524 / unprotected / { 4525 / ephemeral / -1:{ 4526 / kty / 1:2, 4527 / crv / -1:1, 4528 / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf 4529 bf054e1c7b4d91d6280', 4530 / y / -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069 4531 170d924b7e03bf822bb' 4532 }, 4533 / kid / 4:'meriadoc.brandybuck@buckland.example' 4534 }, 4535 / ciphertext / h'' 4536 ] 4537 ] 4538 ] 4539 ) 4541 C.3.2. Direct plus Key Derivation 4543 This example uses the following: 4545 o CEK: AES-CCM w/128-bit key, truncate the tag to 64 bits 4547 o Recipient class: Use HKDF on a shared secret with the following 4548 implicit fields as part of the context. 4550 * salt: "aabbccddeeffgghh" 4552 * APU identity: "lighting-client" 4554 * APV identity: "lighting-server" 4556 * Supplementary Public Other: "Encryption Example 02" 4558 Size of binary file is 92 bytes 4560 992( 4561 [ 4562 / protected / h'a1010a' / { 4563 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 4564 } / , 4565 / unprotected / { 4566 / iv / 5:h'89f52f65a1c580933b5261a76c' 4567 }, 4568 / ciphertext / h'89bedc91e9909346a8fe87834445679ee12b2c95f57feed 4569 836e6d4bd', 4570 / recipients / [ 4571 [ 4572 / protected / h'a10129' / { 4573 \ alg \ 1:-10 4574 } / , 4575 / unprotected / { 4576 / salt / -20:'aabbccddeeffgghh', 4577 / kid / 4:'our-secret' 4578 }, 4579 / ciphertext / h'' 4580 ] 4581 ] 4582 ] 4583 ) 4585 C.3.3. Counter Signature on Encrypted Content 4587 This example uses the following: 4589 o CEK: AES-GCM w/ 128-bit key 4591 o Recipient class: ECDH Ephemeral-Static, Curve P-256 4593 Size of binary file is 360 bytes 4594 992( 4595 [ 4596 / protected / h'a10101' / { 4597 \ alg \ 1:1 \ AES-GCM 128 \ 4598 } / , 4599 / unprotected / { 4600 / iv / 5:h'c9cf4df2fe6c632bf7886413', 4601 / countersign / 7:[ 4602 / protected / h'a1013823' / { 4603 \ alg \ 1:-36 4604 } / , 4605 / unprotected / { 4606 / kid / 4:'bilbo.baggins@hobbiton.example' 4607 }, 4608 / signature / h'00aa98cbfd382610a375d046a275f30266e8d0faacb9 4609 069fde06e37825ae7825419c474f416ded0c8e3e7b55bff68f2a704135bdf99186f6 4610 6659461c8cf929cc7fb301d57eb4d42d95dc0a61b72ee49dda4ce431d434dc7e02c2 4611 cdff49d9189cfbffdaf0444f10bfe9a9ebd96bee2c0d76743936f6f56ac62c8ed4d3 4612 ee3758390d877901' 4613 ] 4614 }, 4615 / ciphertext / h'40970cd7ab5fbd10f505bf7a86e6fc0a99a3122475fbed3 4616 36488c3220f884f011ba219ea', 4617 / recipients / [ 4618 [ 4619 / protected / h'a1013818' / { 4620 \ alg \ 1:-25 \ ECDH-ES + HKDF-256 \ 4621 } / , 4622 / unprotected / { 4623 / ephemeral / -1:{ 4624 / kty / 1:2, 4625 / crv / -1:1, 4626 / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf 4627 bf054e1c7b4d91d6280', 4628 / y / -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069 4629 170d924b7e03bf822bb' 4630 }, 4631 / kid / 4:'meriadoc.brandybuck@buckland.example' 4632 }, 4633 / ciphertext / h'' 4634 ] 4635 ] 4636 ] 4637 ) 4639 C.3.4. Encrypted Content with External Data 4641 This example uses the following: 4643 o CEK: AES-GCM w/ 128-bit key 4645 o Recipient class: ECDH static-Static, Curve P-256 with AES Key Wrap 4647 o Externally Supplied AAD: h'0011bbcc22dd44ee55ff660077' 4649 Size of binary file is 174 bytes 4651 992( 4652 [ 4653 / protected / h'a10101' / { 4654 \ alg \ 1:1 \ AES-GCM 128 \ 4655 } / , 4656 / unprotected / { 4657 / iv / 5:h'02d1f7e6f26c43d4868d87ce' 4658 }, 4659 / ciphertext / h'64f84d913ba60a76070a9a48f26e97e863e28529d8f5335 4660 e5f0165eee976b4a5f6c6f09d', 4661 / recipients / [ 4662 [ 4663 / protected / h'a101381f' / { 4664 \ alg \ 1:-32 \ ECHD-SS+A128KW \ 4665 } / , 4666 / unprotected / { 4667 / static kid / -3:'peregrin.took@tuckborough.example', 4668 / kid / 4:'meriadoc.brandybuck@buckland.example', 4669 / U nonce / -22:h'0101' 4670 }, 4671 / ciphertext / h'59463342fd2193f30daeb1ebb2dc7310b56cee0939d 4672 d6692' 4673 ] 4674 ] 4675 ] 4676 ) 4678 C.4. Examples of Encrypted Messages 4680 C.4.1. Simple Encrypted Message 4682 This example uses the following: 4684 o CEK: AES-CCM w/ 128-bit key and a 64-bit tag 4686 Size of binary file is 54 bytes 4687 993( 4688 [ 4689 / protected / h'a1010a' / { 4690 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 4691 } / , 4692 / unprotected / { 4693 / iv / 5:h'89f52f65a1c580933b5261a78c' 4694 }, 4695 / ciphertext / h'5974e1b99a3a4cc09a659aa2e9e7fff161d38ce7edd5617 4696 388e77baf' 4697 ] 4698 ) 4700 C.4.2. Encrypted Message w/ a Partial IV 4702 This example uses the following: 4704 o CEK: AES-CCM w/ 128-bit key and a 64-bit tag 4706 o Prefix for IV is 89F52F65A1C580933B52 4708 Size of binary file is 43 bytes 4710 993( 4711 [ 4712 / protected / h'a1010a' / { 4713 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 4714 } / , 4715 / unprotected / { 4716 / partial iv / 6:h'61a7' 4717 }, 4718 / ciphertext / h'252a8911d465c125b6764739700f0141ed09192da5c69e5 4719 33abf852b' 4720 ] 4721 ) 4723 C.5. Examples of MAC messages 4725 C.5.1. Shared Secret Direct MAC 4727 This example users the following: 4729 o MAC: AES-CMAC, 256-bit key, truncated to 64 bits 4731 o Recipient class: direct shared secret 4733 Size of binary file is 58 bytes 4734 994( 4735 [ 4736 / protected / h'a1010f' / { 4737 \ alg \ 1:15 \ AES-CBC-MAC-256//64 \ 4738 } / , 4739 / unprotected / {}, 4740 / payload / 'This is the content.', 4741 / tag / h'9e1226ba1f81b848', 4742 / recipients / [ 4743 [ 4744 / protected / h'', 4745 / unprotected / { 4746 / alg / 1:-6 / direct /, 4747 / kid / 4:'our-secret' 4748 }, 4749 / ciphertext / h'' 4750 ] 4751 ] 4752 ] 4753 ) 4755 C.5.2. ECDH Direct MAC 4757 This example uses the following: 4759 o MAC: HMAC w/SHA-256, 256-bit key 4761 o Recipient class: ECDH key agreement, two static keys, HKDF w/ 4762 context structure 4764 Size of binary file is 215 bytes 4765 994( 4766 [ 4767 / protected / h'a10105' / { 4768 \ alg \ 1:5 \ HMAC 256//256 \ 4769 } / , 4770 / unprotected / {}, 4771 / payload / 'This is the content.', 4772 / tag / h'42cf68ae1253948c500dff27da3904342625a23e914f7aa545dcf6 4773 629519f18e', 4774 / recipients / [ 4775 [ 4776 / protected / h'a101381a' / { 4777 \ alg \ 1:-27 \ ECDH-SS + HKDF-256 \ 4778 } / , 4779 / unprotected / { 4780 / static kid / -3:'peregrin.took@tuckborough.example', 4781 / kid / 4:'meriadoc.brandybuck@buckland.example', 4782 / U nonce / -22:h'4d8553e7e74f3c6a3a9dd3ef286a8195cbf8a23d 4783 19558ccfec7d34b824f42d92bd06bd2c7f0271f0214e141fb779ae2856abf585a583 4784 68b017e7f2a9e5ce4db5' 4785 }, 4786 / ciphertext / h'' 4787 ] 4788 ] 4789 ] 4790 ) 4792 C.5.3. Wrapped MAC 4794 This example uses the following: 4796 o MAC: AES-MAC, 128-bit key, truncated to 64 bits 4798 o Recipient class: AES keywrap w/ a pre-shared 256-bit key 4800 Size of binary file is 110 bytes 4801 994( 4802 [ 4803 / protected / h'a1010e' / { 4804 \ alg \ 1:14 \ AES-CBC-MAC-128//64 \ 4805 } / , 4806 / unprotected / {}, 4807 / payload / 'This is the content.', 4808 / tag / h'36f5afaf0bab5d43', 4809 / recipients / [ 4810 [ 4811 / protected / h'', 4812 / unprotected / { 4813 / alg / 1:-5 / A256KW /, 4814 / kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037' 4815 }, 4816 / ciphertext / h'711ab0dc2fc4585dce27effa6781c8093eba906f227 4817 b6eb0' 4818 ] 4819 ] 4820 ] 4821 ) 4823 C.5.4. Multi-recipient MAC message 4825 This example uses the following: 4827 o MAC: HMAC w/ SHA-256, 128-bit key 4829 o Recipient class: Uses three different methods 4831 1. ECDH Ephemeral-Static, Curve P-521, AES-Key Wrap w/ 128-bit 4832 key 4834 2. AES-Key Wrap w/ 256-bit key 4836 Size of binary file is 377 bytes 4837 994( 4838 [ 4839 / protected / h'a10105' / { 4840 \ alg \ 1:5 \ HMAC 256//256 \ 4841 } / , 4842 / unprotected / {}, 4843 / payload / 'This is the content.', 4844 / tag / h'bf48235e809b5c42e995f2b7d5fa13620e7ed834e337f6aa43df16 4845 1e49e9323e', 4846 / recipients / [ 4847 [ 4848 / protected / h'a101381c' / { 4849 \ alg \ 1:-29 \ ECHD-ES+A128KW \ 4850 } / , 4851 / unprotected / { 4852 / ephemeral / -1:{ 4853 / kty / 1:2, 4854 / crv / -1:3, 4855 / x / -2:h'0043b12669acac3fd27898ffba0bcd2e6c366d53bc4db 4856 71f909a759304acfb5e18cdc7ba0b13ff8c7636271a6924b1ac63c02688075b55ef2 4857 d613574e7dc242f79c3', 4858 / y / -3:h'00812dd694f4ef32b11014d74010a954689c6b6e8785b 4859 333d1ab44f22b9d1091ae8fc8ae40b687e5cfbe7ee6f8b47918a07bb04e9f5b1a51a 4860 334a16bc09777434113' 4861 }, 4862 / kid / 4:'bilbo.baggins@hobbiton.example' 4863 }, 4864 / ciphertext / h'c07072310285bbd3f0675774418138e14388ed47a4a 4865 81219d42a8bfbe3a5559c19de83435d21c6bc' 4866 ], 4867 [ 4868 / protected / h'', 4869 / unprotected / { 4870 / alg / 1:-5 / A256KW /, 4871 / kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037' 4872 }, 4873 / ciphertext / h'0b2c7cfce04e98276342d6476a7723c090dfdd15f9a 4874 518e7736549e998370695e6d6a83b4ae507bb' 4875 ] 4876 ] 4877 ] 4878 ) 4880 C.6. Examples of MAC0 messages 4881 C.6.1. Shared Secret Direct MAC 4883 This example users the following: 4885 o MAC: AES-CMAC, 256-bit key, truncated to 64 bits 4887 o Recipient class: direct shared secret 4889 Size of binary file is 39 bytes 4891 996( 4892 [ 4893 / protected / h'a1010f' / { 4894 \ alg \ 1:15 \ AES-CBC-MAC-256//64 \ 4895 } / , 4896 / unprotected / {}, 4897 / payload / 'This is the content.', 4898 / tag / h'726043745027214f' 4899 ] 4900 ) 4902 Note that this example uses the same inputs as Appendix C.5.1. 4904 C.7. COSE Keys 4906 C.7.1. Public Keys 4908 This is an example of a COSE Key set. This example includes the 4909 public keys for all of the previous examples. 4911 In order the keys are: 4913 o An EC key with a kid of "meriadoc.brandybuck@buckland.example" 4915 o An EC key with a kid of "peregrin.took@tuckborough.example" 4917 o An EC key with a kid of "bilbo.baggins@hobbiton.example" 4919 o An EC key with a kid of "11" 4921 Size of binary file is 481 bytes 4923 [ 4924 { 4925 -1:1, 4926 -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0 4927 8551d', 4928 -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008 4929 4d19c', 4930 1:2, 4931 2:'meriadoc.brandybuck@buckland.example' 4932 }, 4933 { 4934 -1:1, 4935 -2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a 4936 09eff', 4937 -3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbf 4938 c117e', 4939 1:2, 4940 2:'11' 4941 }, 4942 { 4943 -1:3, 4944 -2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737bf5de 4945 7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620085e5c8 4946 f42ad', 4947 -3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e247e 4948 60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3fe1ea1 4949 d9475', 4950 1:2, 4951 2:'bilbo.baggins@hobbiton.example' 4952 }, 4953 { 4954 -1:1, 4955 -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b4d91 4956 d6280', 4957 -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e03bf 4958 822bb', 4959 1:2, 4960 2:'peregrin.took@tuckborough.example' 4961 } 4962 ] 4964 C.7.2. Private Keys 4966 This is an example of a COSE Key set. This example includes the 4967 private keys for all of the previous examples. 4969 In order the keys are: 4971 o An EC key with a kid of "meriadoc.brandybuck@buckland.example" 4973 o A shared-secret key with a kid of "our-secret" 4975 o An EC key with a kid of "peregrin.took@tuckborough.example" 4977 o A shared-secret key with a kid of "018c0ae5-4d9b-471b- 4978 bfd6-eef314bc7037" 4980 o An EC key with a kid of "bilbo.baggins@hobbiton.example" 4982 o An EC key with a kid of "11" 4984 Size of binary file is 816 bytes 4986 [ 4987 { 4988 1:2, 4989 2:'meriadoc.brandybuck@buckland.example', 4990 -1:1, 4991 -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0 4992 8551d', 4993 -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008 4994 4d19c', 4995 -4:h'aff907c99f9ad3aae6c4cdf21122bce2bd68b5283e6907154ad911840fa 4996 208cf' 4997 }, 4998 { 4999 1:2, 5000 2:'11', 5001 -1:1, 5002 -2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a 5003 09eff', 5004 -3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbf 5005 c117e', 5006 -4:h'57c92077664146e876760c9520d054aa93c3afb04e306705db609030850 5007 7b4d3' 5008 }, 5009 { 5010 1:2, 5011 2:'bilbo.baggins@hobbiton.example', 5012 -1:3, 5013 -2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737bf5de 5014 7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620085e5c8 5015 f42ad', 5016 -3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e247e 5017 60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3fe1ea1 5018 d9475', 5019 -4:h'00085138ddabf5ca975f5860f91a08e91d6d5f9a76ad4018766a476680b 5020 55cd339e8ab6c72b5facdb2a2a50ac25bd086647dd3e2e6e99e84ca2c3609fdf177f 5021 eb26d' 5022 }, 5023 { 5024 1:4, 5025 2:'our-secret', 5026 -1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dcea6c4 5027 27188' 5028 }, 5029 { 5030 1:2, 5031 -1:1, 5032 2:'peregrin.took@tuckborough.example', 5033 -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b4d91 5034 d6280', 5035 -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e03bf 5036 822bb', 5037 -4:h'02d1f7e6f26c43d4868d87ceb2353161740aacf1f7163647984b522a848 5038 df1c3' 5039 }, 5040 { 5041 1:4, 5042 2:'our-secret2', 5043 -1:h'849b5786457c1491be3a76dcea6c4271' 5044 }, 5045 { 5046 1:4, 5047 2:'018c0ae5-4d9b-471b-bfd6-eef314bc7037', 5048 -1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dcea6c4 5049 27188' 5050 } 5051 ] 5053 Acknowledgments 5055 This document is a product of the COSE working group of the IETF. 5057 The following individuals are to blame for getting me started on this 5058 project in the first place: Richard Barnes, Matt Miller, and Martin 5059 Thomson. 5061 The initial version of the draft was based to some degree on the 5062 outputs of the JOSE and S/MIME working groups. 5064 The following individuals provided input into the final form of the 5065 document: Carsten Bormann, John Bradley, Brain Campbell, Mike Jones, 5066 Ilari Liusvaara, Francesca Palombini, Goran Selander, and Ludwig 5067 Seitz. 5069 Author's Address 5071 Jim Schaad 5072 August Cellars 5074 Email: ietf@augustcellars.com