idnits 2.17.1 draft-ietf-cose-msg-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 8 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 619 has weird spacing: '...otected is de...' == Line 621 has weird spacing: '...otected is de...' == Line 623 has weird spacing: '...payload conta...' == Line 631 has weird spacing: '...natures is an...' == Line 637 has weird spacing: '...otected is de...' == (19 more instances...) -- The document date (November 3, 2015) is 3097 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'CREF1' is mentioned on line 3824, but not defined == Missing Reference: 'CREF2' is mentioned on line 3826, but not defined == Missing Reference: 'CREF3' is mentioned on line 3830, but not defined == Missing Reference: 'CREF4' is mentioned on line 3834, but not defined == Missing Reference: 'CREF5' is mentioned on line 3838, but not defined == Missing Reference: 'CREF6' is mentioned on line 3843, but not defined == Missing Reference: 'CREF7' is mentioned on line 3846, but not defined == Missing Reference: 'CREF8' is mentioned on line 3853, but not defined == Missing Reference: 'CREF9' is mentioned on line 3857, but not defined == Missing Reference: 'CREF10' is mentioned on line 3859, but not defined == Unused Reference: 'MultiPrimeRSA' is defined on line 3043, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-11) exists of draft-greevenbosch-appsawg-cbor-cddl-07 -- 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 7159 (Obsoleted by RFC 8259) -- Obsolete informational reference (is this intentional?): RFC 7539 (Obsoleted by RFC 8439) Summary: 2 errors (**), 0 flaws (~~), 19 warnings (==), 7 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: Informational November 3, 2015 5 Expires: May 6, 2016 7 CBOR Encoded Message Syntax 8 draft-ietf-cose-msg-07 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 procesing for signatures, message 16 authentication codes, and encryption using CBOR. This document also 17 specifies a represention 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 May 6, 2016. 44 Copyright Notice 46 Copyright (c) 2015 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 . . . . . . . . . . . . . . . . 5 64 1.3. CBOR Grammar . . . . . . . . . . . . . . . . . . . . . . 6 65 1.4. CBOR Related Terminology . . . . . . . . . . . . . . . . 6 66 1.5. Document Terminology . . . . . . . . . . . . . . . . . . 7 67 1.6. Mandatory to Implement Algorithms . . . . . . . . . . . . 7 68 2. Basic COSE Structure . . . . . . . . . . . . . . . . . . . . 8 69 3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 8 70 3.1. Common COSE Headers Parameters . . . . . . . . . . . . . 10 71 4. Signing Structure . . . . . . . . . . . . . . . . . . . . . . 13 72 4.1. Externally Supplied Data . . . . . . . . . . . . . . . . 15 73 4.2. Signing and Verification Process . . . . . . . . . . . . 15 74 4.3. Computing Counter Signatures . . . . . . . . . . . . . . 17 75 5. Encryption objects . . . . . . . . . . . . . . . . . . . . . 18 76 5.1. Enveloped COSE structure . . . . . . . . . . . . . . . . 18 77 5.1.1. Recipient Algorithm Classes . . . . . . . . . . . . . 19 78 5.2. Encrypted COSE structure . . . . . . . . . . . . . . . . 20 79 5.3. Encryption Algorithm for AEAD algorithms . . . . . . . . 20 80 5.4. Encryption algorithm for AE algorithms . . . . . . . . . 21 81 6. MAC objects . . . . . . . . . . . . . . . . . . . . . . . . . 22 82 6.1. How to compute a MAC . . . . . . . . . . . . . . . . . . 23 83 7. Key Structure . . . . . . . . . . . . . . . . . . . . . . . . 24 84 7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 24 85 8. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 27 86 8.1. ECDSA . . . . . . . . . . . . . . . . . . . . . . . . . . 28 87 8.1.1. Security Considerations . . . . . . . . . . . . . . . 29 88 9. Message Authentication (MAC) Algorithms . . . . . . . . . . . 29 89 9.1. Hash-based Message Authentication Codes (HMAC) . . . . . 30 90 9.1.1. Security Considerations . . . . . . . . . . . . . . . 31 91 9.2. AES Message Authentication Code (AES-CBC-MAC) . . . . . . 31 92 9.2.1. Security Considerations . . . . . . . . . . . . . . . 32 93 10. Content Encryption Algorithms . . . . . . . . . . . . . . . . 32 94 10.1. AES GCM . . . . . . . . . . . . . . . . . . . . . . . . 33 95 10.1.1. Security Considerations . . . . . . . . . . . . . . 34 96 10.2. AES CCM . . . . . . . . . . . . . . . . . . . . . . . . 34 97 10.2.1. Security Considerations . . . . . . . . . . . . . . 37 98 10.3. ChaCha20 and Poly1305 . . . . . . . . . . . . . . . . . 37 99 10.3.1. Security Considerations . . . . . . . . . . . . . . 38 100 11. Key Derivation Functions (KDF) . . . . . . . . . . . . . . . 38 101 11.1. HMAC-based Extract-and-Expand Key Derivation Function 102 (HKDF) . . . . . . . . . . . . . . . . . . . . . . . . . 39 103 11.2. Context Information Structure . . . . . . . . . . . . . 40 104 12. Recipient Algorithm Classes . . . . . . . . . . . . . . . . . 44 105 12.1. Direct Encryption . . . . . . . . . . . . . . . . . . . 44 106 12.1.1. Direct Key . . . . . . . . . . . . . . . . . . . . . 45 107 12.1.2. Direct Key with KDF . . . . . . . . . . . . . . . . 45 108 12.2. Key Wrapping . . . . . . . . . . . . . . . . . . . . . . 47 109 12.2.1. AES Key Wrapping . . . . . . . . . . . . . . . . . . 47 110 12.3. Key Encryption . . . . . . . . . . . . . . . . . . . . . 48 111 12.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 48 112 12.4.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 49 113 12.5. Key Agreement with KDF . . . . . . . . . . . . . . . . . 53 114 12.5.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 53 115 13. Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 116 13.1. Elliptic Curve Keys . . . . . . . . . . . . . . . . . . 54 117 13.1.1. Double Coordinate Curves . . . . . . . . . . . . . . 54 118 13.2. Symmetric Keys . . . . . . . . . . . . . . . . . . . . . 55 119 14. CBOR Encoder Restrictions . . . . . . . . . . . . . . . . . . 56 120 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 56 121 15.1. CBOR Tag assignment . . . . . . . . . . . . . . . . . . 56 122 15.2. COSE Header Parameter Registry . . . . . . . . . . . . . 57 123 15.3. COSE Header Algorithm Label Table . . . . . . . . . . . 58 124 15.4. COSE Algorithm Registry . . . . . . . . . . . . . . . . 58 125 15.5. COSE Key Common Parameter Registry . . . . . . . . . . . 59 126 15.6. COSE Key Type Parameter Registry . . . . . . . . . . . . 60 127 15.7. COSE Elliptic Curve Registry . . . . . . . . . . . . . . 60 128 15.8. Media Type Registrations . . . . . . . . . . . . . . . . 61 129 15.8.1. COSE Security Message . . . . . . . . . . . . . . . 61 130 15.8.2. COSE Key media type . . . . . . . . . . . . . . . . 63 131 15.9. CoAP Content Format Registrations . . . . . . . . . . . 65 132 16. Security Considerations . . . . . . . . . . . . . . . . . . . 65 133 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 66 134 17.1. Normative References . . . . . . . . . . . . . . . . . . 66 135 17.2. Informative References . . . . . . . . . . . . . . . . . 66 136 Appendix A. CDDL Grammar . . . . . . . . . . . . . . . . . . . . 69 137 Appendix B. Three Levels of Recipient Information . . . . . . . 69 138 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 71 139 C.1. Examples of MAC messages . . . . . . . . . . . . . . . . 72 140 C.1.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 72 141 C.1.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 73 142 C.1.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 74 143 C.1.4. Multi-recipient MAC message . . . . . . . . . . . . . 75 144 C.2. Examples of Encrypted Messages . . . . . . . . . . . . . 76 145 C.2.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 76 146 C.2.2. Direct plus Key Derivation . . . . . . . . . . . . . 77 147 C.3. Examples of Signed Message . . . . . . . . . . . . . . . 78 148 C.3.1. Single Signature . . . . . . . . . . . . . . . . . . 78 149 C.3.2. Multiple Signers . . . . . . . . . . . . . . . . . . 79 150 C.4. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 79 151 C.4.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 79 152 C.4.2. Private Keys . . . . . . . . . . . . . . . . . . . . 82 153 Appendix D. Document Updates . . . . . . . . . . . . . . . . . . 83 154 D.1. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 83 155 D.2. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 84 156 D.3. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 84 157 D.4. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 84 158 D.5. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 84 159 D.6. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 85 160 D.7. Version -01 to -2 . . . . . . . . . . . . . . . . . . . . 85 161 D.8. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 85 162 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 86 164 1. Introduction 166 There has been an increased focus on the small, constrained devices 167 that make up the Internet of Things (IOT). One of the standards that 168 has come out of this process is the Concise Binary Object 169 Representation (CBOR). CBOR extended the data model of the 170 JavaScript Object Notation (JSON) by allowing for binary data among 171 other changes. CBOR is being adopted by several of the IETF working 172 groups dealing with the IOT world as their encoding of data 173 structures. CBOR was designed specifically to be both small in terms 174 of messages transport and implementation size as well having a schema 175 free decoder. A need exists to provide basic message security 176 services for IOT and using CBOR as the message encoding format makes 177 sense. 179 The JOSE working group produced a set of documents 180 [RFC7515][RFC7516][RFC7517][RFC7518] using JSON [RFC7159] that 181 specified how to process encryption, signatures and message 182 authentication (MAC) operations, and how to encode keys using JSON. 183 This document does the same work for use with the CBOR [RFC7049] 184 document format. While there is a strong attempt to keep the flavor 185 of the original JOSE documents, two considerations are taken into 186 account: 188 o CBOR has capabilities that are not present in JSON and should be 189 used. One example of this is the fact that CBOR has a method of 190 encoding binary directly without first converting it into a base64 191 encoded string. 193 o COSE is not a direct copy of the JOSE specification. In the 194 process of creating COSE, decisions that were made for JOSE were 195 re-examined. In many cases different results were decided on as 196 the criteria were not always the same as for JOSE. 198 1.1. Design changes from JOSE 200 o Define a top level message structure so that encrypted, signed and 201 MACed messages can easily identified and still have a consistent 202 view. 204 o Signed messages separate the concept of protected and unprotected 205 parameters that are for the content and the signature. 207 o Recipient processing has been made more uniform. A recipient 208 structure is required for all recipients rather than only for 209 some. 211 o MAC messages are separated from signed messages. 213 o MAC messages have the ability to use all recipient algorithms on 214 the MAC authentication key. 216 o Use binary encodings for binary data rather than base64url 217 encodings. 219 o Combine the authentication tag for encryption algorithms with the 220 ciphertext. 222 o Remove the flattened mode of encoding. Forcing the use of an 223 array of recipients at all times forces the message size to be two 224 bytes larger, but one gets a corresponding decrease in the 225 implementation size that should compensate for this. [CREF1] 227 1.2. Requirements Terminology 229 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 230 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 231 "OPTIONAL" in this document are to be interpreted as described in 232 [RFC2119]. 234 When the words appear in lower case, their natural language meaning 235 is used. 237 1.3. CBOR Grammar 239 There currently is no standard CBOR grammar available for use by 240 specifications. We therefore describe the CBOR structures in prose. 241 There is a version of a CBOR grammar in the CBOR Data Definition 242 Language (CDDL) [I-D.greevenbosch-appsawg-cbor-cddl]. An 243 informational version of the CBOR grammar that reflects what is in 244 the prose can be found in Appendix A. CDDL has not been fixed, so 245 this grammar may will only work with the version of CDDL at the time 246 of publishing. 248 The document was developed by first working on the grammar and then 249 developing the prose to go with it. An artifact of this is that the 250 prose was written using the primitive type strings defined by early 251 versions CDDL. In this specification, the following primitive types 252 are used: 254 bstr - byte string (major type 2). 256 int - an unsigned integer or a negative integer. 258 nil - a null value (major type 7, value 22). 260 nint - a negative integer (major type 1). 262 tstr - a UTF-8 text string (major type 3). 264 uint - an unsigned integer (major type 0). 266 bool - a boolean value (true: major type 7, value 21, false: major 267 type 7, value 20). 269 Text from here to start of next section to be removed 271 NOTE: For the purposes of review, we are currently interlacing the 272 CDDL grammar into the text of document. This is being done for 273 simplicity of comparison of the grammar against the prose. The 274 grammar will be removed to an appendix during WGLC. 276 start = COSE_Untagged_Message / COSE_Tagged_Message / 277 COSE_Key / COSE_KeySet / Internal_Types 279 1.4. CBOR Related Terminology 281 In JSON, maps are called objects and only have one kind of map key: a 282 string. In COSE, we use both strings and integers (both negative and 283 non-negative integers) as map keys. The integers are used for 284 compactness of encoding and easy comparison. (Generally, in this 285 document the value zero is going to be reserved and not used.) Since 286 the work "key" is mainly used in its other meaning, as a 287 cryptographic key, we use the term "label" for this usage as a map 288 keys. 290 Text from here to start of next section to be removed 292 label = int / tstr 293 values = any 295 1.5. Document Terminology 297 In this document we use the following terminology: [CREF2] 299 Byte is a synonym for octet. 301 Key management is used as a term to describe how a key at level n is 302 obtained from level n+1 in encrypted and MACed messages. The term is 303 also used to discuss key life cycle management, this document does 304 not discuss key life cycle operations. 306 1.6. Mandatory to Implement Algorithms 308 One of the issues that needs to be addressed is a requirement that a 309 standard specify a set of algorithms that are required to be 310 implemented. [CREF3] This is done to promote interoperability as it 311 provides a minimal set of algorithms that all devices can be sure 312 will exist at both ends. However, we have elected not to specify a 313 set of mandatory algorithms in this document. 315 It is expected that COSE is going to be used in a wide variety of 316 applications and on a wide variety of devices. Many of the 317 constrained devices are going to be setup to use a small fixed set of 318 algorithms, and this set of algorithms may not match those available 319 on a device. We therefore have deferred to the application protocols 320 the decision of what to specify for mandatory algorithms. 322 Since the set of algorithms in an environment of constrained devices 323 may depend on what the set of devices are and how long they have been 324 in operation, we want to highlight that application protocols will 325 need to specify some type of discovery method of algorithm 326 capabilities. The discovery method may be as simple as requiring 327 preconfiguration of the set of algorithms to providing a discovery 328 method built into the protocol. S/MIME provided a number of 329 different ways to approach the problem: 331 o Advertising in the message (S/MIME capabilities) [RFC5751]. 333 o Advertising in the certificate (capabilities extension) [RFC4262] 335 o Minimum requirements for the S/MIME, which have been updated over 336 time [RFC2633][RFC5751] 338 2. Basic COSE Structure 340 The COSE Message structure is designed so that there can be a large 341 amount of common code when parsing and processing the different 342 security messages. All of the message structures are built on a CBOR 343 array type. The first three elements of the array contains the same 344 basic information. The first element is a set of protected header 345 information. The second element is a set of unprotected header 346 information. The third element is the content of the message (either 347 as plain text or encrypted). Elements after this point are dependent 348 on the specific message type. 350 Identification of which message is present is done by one of two 351 methods: 353 o The specific message type is known from the context in which it is 354 placed. This may be defined by a marker in the containing 355 structure or by restrictions specified by the application 356 protocol. 358 o The message type is identified by a CBOR tag. This document 359 defines a CBOR tag for each of the message structures. 361 Text from here to start of next section to be removed 363 COSE_Untagged_Message = COSE_Sign / 364 COSE_enveloped / 365 COSE_encryptData / 366 COSE_Mac 368 COSE_Tagged_Message = COSE_Sign_Tagged / 369 COSE_Enveloped_Tagged / 370 COSE_EncryptedData_Tagged / 371 COSE_Mac_Tagged 373 3. Header Parameters 375 The structure of COSE has been designed to have two buckets of 376 information that are not considered to be part of the payload itself, 377 but are used for holding information about content, algorithms, keys, 378 or evaluation hints for the processing of the layer. These two 379 buckets are available for use in all of the structures in this 380 document except for keys. While these buckets can be present, they 381 may not all be usable in all instances. For example, while the 382 protected bucket is defined as part of recipient structures, most of 383 the algorithms that are used for recipients do not provide the 384 necessary functionality to provide the needed protection and thus the 385 bucket should not be used. 387 Both buckets are implemented as CBOR maps. The map key is a 'label' 388 (Section 1.4). The value portion is dependent on the definition for 389 the label. Both maps use the same set of label/value pairs. The 390 integer and string values for labels has been divided into several 391 sections with a standard range, a private range, and a range that is 392 dependent on the algorithm selected. The defined labels can be found 393 in the 'COSE Header Parameters' IANA registry (Section 15.2). 395 Two buckets are provided for each layer: 397 protected: Contains parameters about the current layer that are to 398 be cryptographically protected. This bucket MUST be empty if it 399 is not going to be included in a cryptographic computation. This 400 bucket is encoded in the message as a binary object. This value 401 is obtained by CBOR encoding the protected map and wrapping it in 402 a bstr object. Senders SHOULD encode an empty protected map as a 403 zero length binary object (it is shorter). Recipients MUST accept 404 both a zero length binary value and a zero length map encoded in 405 the binary value. The wrapping allows for the encoding of the 406 protected map to be transported with a greater chance that it will 407 not be altered in transit. (Badly behaved intermediates could 408 decode and re-encode, but this will result in a failure to verify 409 unless the re-encoded byte string is identical to the decoded byte 410 string.) This finesses the problem of all parties needing to be 411 able to do a common canonical encoding. 413 unprotected: Contains parameters about the current layer that are 414 not cryptographically protected. 416 Only parameters that deal with the current layer are to be placed at 417 that layer. As an example of this, the parameter 'content type' 418 describes the content of the message being carried in the message. 419 As such, this parameter is placed only in the content layer and is 420 not placed in the recipient or signature layers. In principle, one 421 should be able to process any given layer without reference to any 422 other layer. (The only data that should need to cross layers is the 423 cryptographic key.) 424 The buckets are present in all of the security objects defined in 425 this document. The fields in order are the 'protected' bucket (as a 426 CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map' 427 type). The presence of both buckets is required. The parameters 428 that go into the buckets come from the IANA "COSE Header Parameters" 429 (Section 15.2). Some common parameters are defined in the next 430 section, but a number of parameters are defined throughout this 431 document. 433 Text from here to start of next section to be removed [CREF4] 435 header_map = {+ label => any } 437 Headers = ( 438 protected : bstr, ; Contains a header_map 439 unprotected : header_map 440 ) 442 3.1. Common COSE Headers Parameters 444 This section defines a set of common header parameters. A summary of 445 those parameters can be found in Table 1. This table should be 446 consulted to determine the value of label used as well as the type of 447 the value. 449 The set of header parameters defined in this section are: 451 alg This parameter is used to indicate the algorithm used for the 452 security processing. This parameter MUST be present at each level 453 of a signed, encrypted or authenticated message. The value is 454 taken from the 'COSE Algorithm Registry' (see Section 15.4). 456 crit This parameter is used to ensure that applications will take 457 appropriate action based on the values found. The parameter is 458 used to indicate which protected header labels an application that 459 is processing a message is required to understand. The value is 460 an array of COSE Header Labels. When present, this parameter MUST 461 be placed in the protected header bucket. 463 * Integer labels in the range of 0 to 10 SHOULD be omitted. 465 * Integer labels in the range -1 to -255 can be omitted as they 466 are algorithm dependent. If an application can correctly 467 process an algorithm, it can be assumed that it will correctly 468 process all of the parameters associated with that algorithm. 469 (The algorithm range is -1 to -65536, it is assumed that the 470 higher end will deal with more optional algorithm specific 471 items.) 473 The header parameter values indicated by 'crit' can be processed 474 by either the security library code or by an application using a 475 security library, the only requirement is that the parameter is 476 processed. If the 'crit' value list includes a value for which 477 the parameter is not in the protected bucket, this is a fatal 478 error in processing the message. 480 content type This parameter is used to indicate the content type of 481 the data in the payload or ciphertext fields. Integers are from 482 the 'CoAP Content-Formats' IANA registry table. Strings are from 483 the IANA 'Media Types' registry. Applications SHOULD provide this 484 parameter if the content structure is potentially ambiguous. 486 kid This parameter one of the ways that can be used to find the key 487 to be used. The value of this parameter is matched against the 488 'kid' member in a COSE_Key structure. Applications MUST NOT 489 assume that 'kid' values are unique. There may be more than one 490 key with the same 'kid' value, it may be required that all of the 491 keys need to be checked to find the correct one. The internal 492 structure of 'kid' values is not defined and generally cannot be 493 relied on by applications. Key identifier values are hints about 494 which key to use. They are not directly a security critical 495 field. For this reason, they can be placed in the unprotected 496 headers bucket. 498 nonce This parameter holds either a nonce or Initialization Vector 499 value. The value can be used either as a counter value for a 500 protocol or as an IV for an algorithm. 502 counter signature This parameter holds a counter signature value. 503 Counter signatures provide a method of having a second party sign 504 some data. The counter signature can occur as an unprotected 505 attribute in any of the following structures: COSE_Sign, 506 COSE_signature, COSE_enveloped, COSE_recipient, 507 COSE_encryptedData, COSE_mac. These structures all have the same 508 basic structure so that a consistent calculation of the counter 509 signature can be computed. Details on computing counter 510 signatures are found in Section 4.3. 512 creation time This parameter provides the time the content was 513 created. For signatures and recipient structures, this would be 514 the time that the signature or recipient key object was created. 515 For content structures, this would be the time that the content 516 was created. The unsigned integer value is the number of seconds, 517 excluding leap seconds; after midnight UTC, January 1, 1970. 519 sequence number This parameter provides a counter field. The use of 520 this parameter is application specific. 522 +----------+-------+---------------+----------------+---------------+ 523 | name | label | value type | value registry | description | 524 +----------+-------+---------------+----------------+---------------+ 525 | alg | 1 | int / tstr | COSE Algorithm | Integers are | 526 | | | | Registry | taken from | 527 | | | | | table --POINT | 528 | | | | | TO REGISTRY-- | 529 | | | | | | 530 | crit | 2 | [+ label] | COSE Header | integer | 531 | | | | Label Registry | values are | 532 | | | | | from -- | 533 | | | | | POINT TO | 534 | | | | | REGISTRY -- | 535 | | | | | | 536 | content | 3 | tstr / int | CoAP Content- | Value is | 537 | type | | | Formats or | either a | 538 | | | | Media Types | Media Type or | 539 | | | | registry | an integer | 540 | | | | | from the CoAP | 541 | | | | | Content | 542 | | | | | Format | 543 | | | | | registry | 544 | | | | | | 545 | kid | 4 | bstr | | key | 546 | | | | | identifier | 547 | | | | | | 548 | nonce | 5 | bstr | | Nonce or Init | 549 | | | | | ialization | 550 | | | | | Vector (IV) | 551 | | | | | | 552 | counter | 6 | COSE_signatur | | CBOR encoded | 553 | signatur | | e | | signature | 554 | e | | | | structure | 555 | | | | | | 556 | creation | * | uint | | Time the | 557 | time | | | | content was | 558 | | | | | created | 559 | | | | | | 560 | sequence | * | uint | | Application | 561 | number | | | | specific | 562 | | | | | Integer value | 563 +----------+-------+---------------+----------------+---------------+ 565 Table 1: Common Header Parameters 567 OPEN ISSUES: 569 1. I am currently torn on the question "Should epk and iv/nonce be 570 algorithm specific or generic headers?" They are really specific 571 to an algorithm and can potentially be defined in different ways 572 for different algorithms. As an example, it would make sense to 573 defined nonce for CCM and GCM modes that can have the leading 574 zero bytes stripped, while for other algorithms this might be 575 undesirable. 577 2. We might want to define some additional items. What are they? A 578 possible example would be a sequence number as this might be 579 common. On the other hand, this is the type of things that is 580 frequently used as the nonce in some places and thus should not 581 be used in the same way. Other items might be challenge/response 582 fields for freshness as these are likely to be common. 584 4. Signing Structure 586 The signature structure allows for one or more signatures to be 587 applied to a message payload. There are provisions for parameters 588 about the content and parameters about the signature to be carried 589 along with the signature itself. These parameters may be 590 authenticated by the signature, or just present. Examples of 591 parameters about the content would be the type of content, when the 592 content was created, and who created the content. [CREF5] Examples 593 of parameters about the signature would be the algorithm and key used 594 to create the signature, when the signature was created, and counter- 595 signatures. 597 When more than one signature is present, the successful validation of 598 one signature associated with a given signer is usually treated as a 599 successful signature by that signer. However, there are some 600 application environments where other rules are needed. An 601 application that employs a rule other than one valid signature for 602 each signer must specify those rules. Also, where simple matching of 603 the signer identifier is not sufficient to determine whether the 604 signatures were generated by the same signer, the application 605 specification must describe how to determine which signatures were 606 generated by the same signer. Support of different communities of 607 recipients is the primary reason that signers choose to include more 608 than one signature. For example, the COSE_Sign structure might 609 include signatures generated with the RSA signature algorithm and 610 with the Elliptic Curve Digital Signature Algorithm (ECDSA) signature 611 algorithm. This allows recipients to verify the signature associated 612 with one algorithm or the other. (The original source of this text 613 is [RFC5652].) More detailed information on multiple signature 614 evaluation can be found in [RFC5752]. 616 The COSE_Sign structure is a CBOR array. The fields of the array in 617 order are: 619 protected is described in Section 3. 621 unprotected is described in Section 3. 623 payload contains the serialized content to be signed. If the 624 payload is not present in the message, the application is required 625 to supply the payload separately. The payload is wrapped in a 626 bstr to ensure that it is transported without changes. If the 627 payload is transported separately, then a nil CBOR object is 628 placed in this location and it is the responsibility of the 629 application to ensure that it will be transported without changes. 631 signatures is an array of signature items. Each of these items uses 632 the COSE_signature structure for its representation. 634 The COSE_signature structure is a CBOR array. The fields of the 635 array in order are: 637 protected is described in Section 3. 639 unprotected is described in Section 3. 641 signature contains the computed signature value. The type of the 642 field is a bstr. 644 Text from here to start of next section to be removed 646 COSE_Sign_Tagged = #6.999(COSE_Sign) ; Replace 999 with TBD1 648 COSE_Sign = [ 649 Headers, 650 payload : bstr / nil, 651 signatures : [+ COSE_signature] 652 ] 654 COSE_signature = [ 655 Headers, 656 signature : bstr 657 ] 659 4.1. Externally Supplied Data 661 One of the features that we supply in the COSE document is the 662 ability for applications to provide additional data to be 663 authenticated as part of the security, but that is not carried as 664 part of the COSE object. The primary reason for supporting this can 665 be seen by looking at the CoAP message structure [RFC7252] where the 666 facility exists for options to be carried before the payload. 667 [CREF6] An example of data that can be placed in this location would 668 be transaction ids and nonces to check for replay protection. If the 669 data is in the options section, then it is available for routers to 670 help in performing the replay detection and prevention. However, it 671 may also be desired to protect these values so that they cannot be 672 modified in transit. This is the purpose of the externally supplied 673 data field. 675 This document describes the process for using a byte array of 676 externally supplied authenticated data, however the method of 677 constructing the byte array is a function of the application. 678 Applications that use this feature need to define how the externally 679 supplied authenticated data is to be constructed. Such a 680 construction needs to take into account the following issues: 682 o If multiple items are included, care needs to be taken that data 683 cannot bleed between the items. This is usually addressed by 684 making fields fixed width and/or encoding the length of the field. 685 Using options from CoAP as an example, these fields use a TLV 686 structure so they can be concatenated without any problems. 688 o If multiple items are included, a defined order for the items 689 needs to be defined. Using options from CoAP as an example, an 690 application could state that the fields are to be ordered by the 691 option number. 693 4.2. Signing and Verification Process 695 In order to create a signature, a consistent byte stream is needed in 696 order to process. This algorithm takes in the body information 697 (COSE_Sign), the signer information (COSE_Signer), and the 698 application data (External). This document uses a CBOR array to 699 construct the byte stream to be processed. The fields of the array 700 in order are: 702 1. The protected attributes from the body structure encoded in a 703 bstr type. 705 2. The protected attributes from the signer structure encoded in a 706 bstr type. 708 3. The protected attributes from the application encoded in a bstr 709 type. If this field is not supplied, it defaults to a zero 710 length binary string. 712 4. The payload to be signed encoded in a bstr type. The payload is 713 placed here independent of how it is transported. 715 How to compute a signature: 717 1. Create a CBOR array and populate it with the appropriate fields. 718 For body_protected and sign_protected, if the fields are not 719 present in their corresponding maps, a bstr of length zero is 720 used. 722 2. If the application has supplied external additional authenticated 723 data to be included in the computation, then it is placed in the 724 third field. If no data was supplied, then a zero length binary 725 value is used. 727 3. Create the value ToBeSigned by encoding the Sig_structure to a 728 byte string. 730 4. Call the signature creation algorithm passing in K (the key to 731 sign with), alg (the algorithm to sign with) and ToBeSigned (the 732 value to sign). 734 5. Place the resulting signature value in the 'signature' field of 735 the map. 737 How to verify a signature: 739 1. Create a Sig_structure object and populate it with the 740 appropriate fields. For body_protected and sign_protected, if 741 the fields are not present in their corresponding maps, a bstr of 742 length zero is used. 744 2. If the application has supplied external additional authenticated 745 data to be included in the computation, then it is placed in the 746 third field. If no data was supplied, then a zero length binary 747 value is used. 749 3. Create the value ToBeSigned by encoding the Sig_structure to a 750 byte string. 752 4. Call the signature verification algorithm passing in K (the key 753 to verify with), alg (the algorithm to sign with), ToBeSigned 754 (the value to sign), and sig (the signature to be verified). 756 In addition to performing the signature verification, one must also 757 perform the appropriate checks to ensure that the key is correctly 758 paired with the signing identity and that the appropriate 759 authorization is done. 761 Text from here to start of next section to be removed 763 The COSE structure used to create the byte stream to be signed uses 764 the following CDDL grammar structure: 766 Sig_structure = [ 767 body_protected: bstr, 768 sign_protected: bstr, 769 external_aad: bstr, 770 payload: bstr 771 ] 773 4.3. Computing Counter Signatures 775 Counter signatures provide a method of having a different signature 776 occur on some piece of content. This is normally used to provide a 777 signature on a signature allowing for a proof that a signature 778 existed at a given time. In this document we allow for counter 779 signatures to exist in a greater number of environments. A counter 780 signature can exist, for example, on a COSE_encryptedData object and 781 allow for a signature to be present on the encrypted content of a 782 message. 784 The creation and validation of counter signatures over the different 785 items relies on the fact that the structure all of our objects have 786 the same structure. The first element may be a message type, this is 787 followed by a set of protected attributes, a set of unprotected 788 attributes and a body in that order. This means that the 789 Sig_structure can be used for in a uniform manner to get the byte 790 stream for processing a signature. If the counter signature is going 791 to be computed over a COSE_encryptedData structure, the 792 body_protected and payload items can be mapped into the Sig_structure 793 in the same manner as from the COSE_Sign structure. 795 While one can create a counter signature for a COSE_Sign structure, 796 there is not much of a point to doing so. It is equivalent to create 797 a new COSE_signature structure and placing it in the signatures 798 array. It is strongly suggested that it not be done, but it is not 799 banned. 801 5. Encryption objects 803 COSE supports two different encryption structures. COSE_enveloped is 804 used when the key needs to be explicitly identified. This structure 805 supports the use of recipient structures to allow for random content 806 encryption keys to be used. COSE_encrypted is used when a recipient 807 structure is not needed because the key to be used is known 808 implicitly. 810 5.1. Enveloped COSE structure 812 The enveloped structure allows for one or more recipients of a 813 message. There are provisions for parameters about the content and 814 parameters about the recipient information to be carried in the 815 message. The parameters associated with the content can be 816 authenticated by the content encryption algorithm. The parameters 817 associated with the recipient can be authenticated by the recipient 818 algorithm (when the algorithm supports it). Examples of parameters 819 about the content are the type of the content, when the content was 820 created, and the content encryption algorithm. Examples of 821 parameters about the recipient are the recipient's key identifier, 822 the recipient encryption algorithm. 824 In COSE, the same techniques and structures are used for encrypting 825 both the plain text and the keys used to protect the text. This is 826 different from the approach used by both [RFC5652] and [RFC7516] 827 where different structures are used for the content layer and for the 828 recipient layer. 830 The COSE_encrypt structure is a CBOR array. The fields of the array 831 in order are: 833 protected is described in Section 3. 835 unprotected is described in Section 3. 837 ciphertext contains the encrypted plain text encoded as a bstr. If 838 the ciphertext is to be transported independently of the control 839 information about the encryption process (i.e. detached content) 840 then the field is encoded as a null object. 842 recipients contains an array of recipient information structures. 843 The type for the recipient information structure is a 844 COSE_recipient. 846 The COSE_recipient structure is a CBOR array. The fields of the 847 array in order are: 849 protected is described in Section 3. 851 unprotected is described in Section 3. 853 ciphertext contains the encrypted key encoded as a bstr. If there 854 is not an encrypted key, then this field is encoded as a nil 855 value. 857 recipients contains an array of recipient information structures. 858 The type for the recipient information structure is a 859 COSE_recipient. If there are no recipient information structures, 860 this element is absent. 862 Text from here to start of next section to be removed 864 COSE_Enveloped_Tagged = #6.998(COSE_enveloped) ; Replace 998 with TBD32 866 COSE_enveloped = [ 867 COSE_encrypt_fields 868 recipients: [+COSE_recipient] 869 ] 871 COSE_encrypt_fields = ( 872 Headers, 873 ciphertext: bstr / nil, 874 ) 876 COSE_recipient = [ 877 COSE_encrypt_fields 878 ? recipients: [+COSE_recipient] 879 ] 881 5.1.1. Recipient Algorithm Classes 883 A typical encrypted message consists of an encrypted content and an 884 encrypted CEK for one or more recipients. The content-encryption key 885 is encrypted for each recipient, using a key specific to that 886 recipient. The details of this encryption depends on which class the 887 recipient algorithm falls into. Specific details on each of the 888 classes can be found in Section 12. A short summary of the five 889 recipient algorithm classes is: 891 none: The CEK is the same as the identified previously distributed 892 symmetric key or derived from a previously distributed secret. 894 symmetric key-encryption keys: The CEK is encrypted using a 895 previously distributed symmetric key-encryption key. 897 key agreement: the recipient's public key and a sender's private key 898 are used to generate a pairwise secret, a KDF is applied to derive 899 a key, and then the CEK is either the derived key or encrypted by 900 the derived key. 902 key transport: the CEK is encrypted with the recipient's public key 904 passwords: the CEK is encrypted in a key-encryption key that is 905 derived from a password. 907 5.2. Encrypted COSE structure 909 The encrypted structure does not have the ability to specify 910 recipients of the message. The structure assumes that the recipient 911 of the object will already know the identity of the key to be used in 912 order to decrypt the message. If a key needs to be identified to the 913 recipient, the enveloped structure is used. 915 The CDDL grammar structure for encrypted data is: 917 COSE_EncryptedData_Tagged = #6.997(COSE_encryptData) ; Replace 997 with TBD3 919 COSE_encryptData = [ 920 COSE_encrypt_fields 921 ] 923 The COSE_encryptedData structure is a CBOR array. The fields of the 924 array in order are: 926 protected is described in Section 3. 928 unprotected is described in Section 3. 930 ciphertext contains the encrypted plain text. If the ciphertext is 931 to be transported independently of the control information about 932 the encryption process (i.e. detached content) then the field is 933 encoded as a null object. 935 5.3. Encryption Algorithm for AEAD algorithms 937 The encryption algorithm for AEAD algorithms is fairly simple. In 938 order to get a consistent encoding of the data to be authenticated, 939 the Enc_structure is used to have canonical form of the AAD. 941 1. Copy the protected header field from the message to be sent. 943 2. If the application has supplied external additional authenticated 944 data to be included in the computation, then it is placed in the 945 'external_aad' field. If no data was supplied, then a zero 946 length binary value is used. (See Section 4.1 for application 947 guidance on constructing this field.) 949 3. Encode the Enc_structure using a CBOR Canonical encoding 950 Section 14 to get the AAD value. 952 4. Determine the encryption key. This step is dependent on the 953 class of recipient algorithm being used. For: 955 No Recipients: The key to be used is determined by the algorithm 956 and key at the current level. 958 Direct and Direct Key Agreement: The key is determined by the 959 key and algorithm in the recipient structure. The encryption 960 algorithm and size of the key to be used are inputs into the 961 KDF used for the recipient. (For direct, the KDF can be 962 thought of as the identity operation.) 964 Other: The key is randomly generated. 966 5. Call the encryption algorithm with K (the encryption key to use), 967 P (the plain text) and AAD (the additional authenticated data). 968 Place the returned cipher text into the 'ciphertext' field of the 969 structure. 971 6. For recipients of the message, recursively perform the encryption 972 algorithm for that recipient using the encryption key as the 973 plain text. 975 Text from here to start of next section to be removed 977 Enc_structure = [ 978 protected: bstr, 979 external_aad: bstr 980 ] 982 5.4. Encryption algorithm for AE algorithms 984 1. Verify that the 'protected' field is absent. 986 2. Verify that there was no external additional authenticated data 987 supplied for this operation. 989 3. Determine the encryption key. This step is dependent on the 990 class of recipient algorithm being used. For: 992 No Recipients: The key to be used is determined by the algorithm 993 and key at the current level. 995 Direct and Direct Key Agreement: The key is determined by the 996 key and algorithm in the recipient structure. The encryption 997 algorithm and size of the key to be used are inputs into the 998 KDF used for the recipient. (For direct, the KDF can be 999 thought of as the identity operation.) 1001 Other: The key is randomly generated. 1003 4. Call the encryption algorithm with K (the encryption key to use) 1004 and the P (the plain text). Place the returned cipher text into 1005 the 'ciphertext' field of the structure. 1007 5. For recipients of the message, recursively perform the encryption 1008 algorithm for that recipient using the encryption key as the 1009 plain text. 1011 6. MAC objects 1013 In this section we describe the structure and methods to be used when 1014 doing MAC authentication in COSE. This document allows for the use 1015 of all of the same classes of recipient algorithms as are allowed for 1016 encryption. 1018 When using MAC operations, there are two modes in which it can be 1019 used. The first is just a check that the content has not been 1020 changed since the MAC was computed. Any class of recipient algorithm 1021 can be used for this purpose. The second mode is to both check that 1022 the content has not been changed since the MAC was computed, and to 1023 use the recipient algorithm to verify who sent it. The classes of 1024 recipient algorithms that support this are those that use a pre- 1025 shared secret or do static-static key agreement (without the key wrap 1026 step). In both of these cases, the entity MACing the message can be 1027 validated by a key binding. (The binding of identity assumes that 1028 there are only two parties involved and you did not send the message 1029 yourself.) 1031 The COSE_Mac structure is a CBOR array. The fields of the array in 1032 order are: 1034 protected is described in Section 3. 1036 unprotected is described in Section 3. 1038 payload contains the serialized content to be MACed. If the payload 1039 is not present in the message, the application is required to 1040 supply the payload separately. The payload is wrapped in a bstr 1041 to ensure that it is transported without changes. If the payload 1042 is transported separately, then a null CBOR object is placed in 1043 this location and it is the responsibility of the application to 1044 ensure that it will be transported without changes. 1046 tag contains the MAC value. 1048 recipients contains the recipient information. See the description 1049 under COSE_Encryption for more info. 1051 Text from here to start of next section to be removed 1053 COSE_Mac_Tagged = #6.996(COSE_Mac) ; Replace 996 with TBD4 1055 COSE_Mac = [ 1056 Headers, 1057 payload: bstr / nil, 1058 tag: bstr, 1059 recipients: [+COSE_recipient] 1060 ] 1062 6.1. How to compute a MAC 1064 How to compute a MAC: 1066 1. Create a MAC_structure and copy the protected and payload fields 1067 from the COSE_Mac structure. 1069 2. If the application has supplied external authenticated data, 1070 encode it as a binary value and place in the MAC_structure. If 1071 there is no external authenticated data, then use a zero length 1072 'bstr'. (See Section 4.1 for application guidance on 1073 constructing this field.) 1075 3. Encode the MAC_structure using a canonical CBOR encoder. The 1076 resulting bytes is the value to compute the MAC on. 1078 4. Compute the MAC and place the result in the 'tag' field of the 1079 COSE_Mac structure. 1081 5. Encrypt and encode the MAC key for each recipient of the message. 1083 Text from here to start of next section to be removed 1084 MAC_structure = [ 1085 protected: bstr, 1086 external_aad: bstr, 1087 payload: bstr 1088 ] 1090 7. Key Structure 1092 A COSE Key structure is built on a CBOR map object. The set of 1093 common parameters that can appear in a COSE Key can be found in the 1094 IANA registry 'COSE Key Common Parameter Registry' (Section 15.5). 1095 Additional parameters defined for specific key types can be found in 1096 the IANA registry 'COSE Key Type Parameters' (Section 15.6). 1098 A COSE Key Set uses a CBOR array object as its underlying type. The 1099 values of the array elements are COSE Keys. A Key Set MUST have at 1100 least one element in the array. 1102 The element "kty" is a required element in a COSE_Key map. 1104 Text from here to start of next section to be removed 1106 The CDDL grammar describing a COSE_Key and COSE_KeySet is: [CREF7] 1108 COSE_Key = { 1109 key_kty => tstr / int, 1110 ? key_ops => [+ (tstr / int) ], 1111 ? key_alg => tstr / int, 1112 ? key_kid => bstr, 1113 * label => values 1114 } 1116 COSE_KeySet = [+COSE_Key] 1118 7.1. COSE Key Common Parameters 1120 This document defines a set of common parameters for a COSE Key 1121 object. Table 2 provides a summary of the parameters defined in this 1122 section. There are also a set of parameters that are defined for a 1123 specific key type. Key type specific parameters can be found in 1124 Section 13. 1126 +---------+-------+-------------+-------------+---------------------+ 1127 | name | label | CBOR type | registry | description | 1128 +---------+-------+-------------+-------------+---------------------+ 1129 | kty | 1 | tstr / int | COSE | Identification of | 1130 | | | | General | the key type | 1131 | | | | Values | | 1132 | | | | | | 1133 | key_ops | 4 | [* | | Restrict set of | 1134 | | | (tstr/int)] | | permissible | 1135 | | | | | operations | 1136 | | | | | | 1137 | alg | 3 | tstr / int | COSE | Key usage | 1138 | | | | Algorithm | restriction to this | 1139 | | | | Values | algorithm | 1140 | | | | | | 1141 | kid | 2 | bstr | | Key Identification | 1142 | | | | | value - match to | 1143 | | | | | kid in message | 1144 | | | | | | 1145 | use | * | tstr | | deprecated - don't | 1146 | | | | | use | 1147 +---------+-------+-------------+-------------+---------------------+ 1149 Table 2: Key Map Labels 1151 kty: This parameter is used to identify the family of keys for this 1152 structure, and thus the set of key type specific parameters to be 1153 found. The set of values can be found in Table 18. This 1154 parameter MUST be present in a key object. Implementations MUST 1155 verify that the key type is appropriate for the algorithm being 1156 processed. The key type MUST be included as part of a trust 1157 decision process. 1159 alg: This parameter is used to restrict the algorithms that are to 1160 be used with this key. If this parameter is present in the key 1161 structure, the application MUST verify that this algorithm matches 1162 the algorithm for which the key is being used. If the algorithms 1163 do not match, then this key object MUST NOT be used to perform the 1164 cryptographic operation. Note that the same key can be in a 1165 different key structure with a different or no algorithm 1166 specified, however this is considered to be a poor security 1167 practice. 1169 kid: This parameter is used to give an identifier for a key. The 1170 identifier is not structured and can be anything from a user 1171 provided string to a value computed on the public portion of the 1172 key. This field is intended for matching against a 'kid' 1173 parameter in a message in order to filter down the set of keys 1174 that need to be checked. 1176 key_ops: This parameter is defined to restrict the set of operations 1177 that a key is to be used for. The value of the field is an array 1178 of values from Table 3. 1180 +---------+-------+-------------------------------------------------+ 1181 | name | value | description | 1182 +---------+-------+-------------------------------------------------+ 1183 | sign | 1 | The key is used to create signatures. Requires | 1184 | | | private key fields. | 1185 | | | | 1186 | verify | 2 | The key is used for verification of signatures. | 1187 | | | | 1188 | encrypt | 3 | The key is used for key transport encryption. | 1189 | | | | 1190 | decrypt | 4 | The key is used for key transport decryption. | 1191 | | | Requires private key fields. | 1192 | | | | 1193 | wrap | 5 | The key is used for key wrapping. | 1194 | key | | | 1195 | | | | 1196 | unwrap | 6 | The key is used for key unwrapping. Requires | 1197 | key | | private key fields. | 1198 | | | | 1199 | key | 7 | The key is used for key agreement. | 1200 | agree | | | 1201 +---------+-------+-------------------------------------------------+ 1203 Table 3: Key Operation Values 1205 Text from here to start of next section to be removed 1207 The following provides a CDDL fragment which duplicates the 1208 assignment labels from Table 2 and Table 3. 1210 ;key_labels 1211 key_kty=1 1212 key_kid=2 1213 key_alg=3 1214 key_ops=4 1216 ;key_ops values 1217 key_ops_values = (key_ops_sign:1, key_ops_verify:2, key_ops_encrypt:3, 1218 key_ops_decrypt:4, key_ops_wrap:5, key_ops_unwrap:6, 1219 key_ops_agree:7) 1221 8. Signature Algorithms 1223 There are two basic signature algorithm structures that can be used. 1224 The first is the common signature with appendix. In this structure, 1225 the message content is processed and a signature is produced, the 1226 signature is called the appendix. This is the message structure used 1227 by our common algorithms such as ECDSA and RSASSA-PSS. (In fact the 1228 SSA in RSASSA-PSS stands for Signature Scheme with Appendix.) The 1229 basic structure becomes: 1231 signature = Sign(message content, key) 1233 valid = Verification(message content, key, signature) 1235 The second is a signature with message recovery. (An example of such 1236 an algorithm is [PVSig].) In this structure, the message content is 1237 processed, but part of it is included in the signature. Moving bytes 1238 of the message content into the signature allows for an effectively 1239 smaller signature, the signature size is still potentially large, but 1240 the message content is shrunk. This has implications for systems 1241 implementing these algorithms and for applications that use them. 1242 The first is that the message content is not fully available until 1243 after a signature has been validated. Until that point the part of 1244 the message contained inside of the signature is unrecoverable. The 1245 second is that the security analysis of the strength of the signature 1246 is very much based on the structure of the message content. Messages 1247 which are highly predictable require additional randomness to be 1248 supplied as part of the signature process. In the worst case, it 1249 becomes the same as doing a signature with appendix. Thirdly, in the 1250 event that multiple signatures are applied to a message, all of the 1251 signature algorithms are going to be required to consume the same 1252 number of bytes of message content. 1254 signature, message sent = Sign(message content, key) 1256 valid, message content = Verification(message sent, key, signature) 1258 At this time, only signatures with appendixes are defined for use 1259 with COSE, however considerable interest has been expressed in using 1260 a signature with message recovery algorithm due to the effective size 1261 reduction that is possible. Implementations will need to keep this 1262 in mind for later possible integration. 1264 8.1. ECDSA 1266 ECDSA [DSS] defines a signature algorithm using ECC. 1268 The ECDSA signature algorithm is parameterized with a hash function 1269 (h). In the event that the length of the hash function output is 1270 greater than the group of the key, the left-most bytes of the hash 1271 output are used. 1273 The algorithms defined in this document can be found in Table 4. 1275 +-------+-------+---------+------------------+ 1276 | name | value | hash | description | 1277 +-------+-------+---------+------------------+ 1278 | ES256 | -7 | SHA-256 | ECDSA w/ SHA-256 | 1279 | | | | | 1280 | ES384 | -8 | SHA-384 | ECDSA w/ SHA-384 | 1281 | | | | | 1282 | ES512 | -9 | SHA-512 | ECDSA w/ SHA-512 | 1283 +-------+-------+---------+------------------+ 1285 Table 4: ECDSA Algorithm Values 1287 This document defines ECDSA to work only with the curves P-256, P-384 1288 and P-521. This document requires that the curves be encoded using 1289 the 'EC2' key type. Implementations need to check that the key type 1290 and curve are correct when creating and verifying a signature. Other 1291 documents can defined it to work with other curves and points in the 1292 future. 1294 In order to promote interoperability, it is suggested that SHA-256 be 1295 used only with curve P-256, SHA-384 be used only with curve P-384 and 1296 SHA-512 be used with curve P-521. This is aligned with the 1297 recommendation in Section 4 of [RFC5480]. 1299 The signature algorithm results in a pair of integers (R, S). These 1300 integers will be of the same order as length of the key used for the 1301 signature process. The signature is encoded by converting the 1302 integers into byte strings of the same length as the key size. The 1303 length is rounded up to the nearest byte and is left padded with zero 1304 bits to get to the correct length. The two integers are then 1305 concatenated together to form a byte string that is the resulting 1306 signature. 1308 Using the function defined in [RFC3447] the signature is: 1309 Signature = I2OSP(R, n) | I2OSP(S, n) 1310 where n = ceiling(key_length / 8) 1312 8.1.1. Security Considerations 1314 The security strength of the signature is no greater than the minimum 1315 of the security strength associated with the bit length of the key 1316 and the security strength of the hash function. 1318 System which have poor random number generation can leak their keys 1319 by signing two different messages with the same value 'k' (the per- 1320 message random value). [RFC6979] provides a method to deal with this 1321 problem by making 'k' be deterministic based on the message content 1322 rather than randomly generated. Applications that specify ECDSA 1323 should evaluate the ability to get good random number generation and 1324 require this when it is not possible. Note: Use of this technique a 1325 good idea even when good random number generation exists. Doing so 1326 both reduces the possibility of having the same value of 'k' in two 1327 signature operations, but allows for reproducible signature values 1328 which helps testing. 1330 There are two substitution attacks that can theoretically be mounted 1331 against the ECDSA signature algorithm. 1333 o Changing the curve used to validate the signature: If one changes 1334 the curve used to validate the signature, then potentially one 1335 could have a two messages with the same signature each computed 1336 under a different curve. The only requirement on the new curve is 1337 that its order be the same as the old one and it be acceptable to 1338 the client. An example would be to change from using the curve 1339 secp256r1 (aka P-256) to using secp256k1. (Both are 256 bit 1340 curves.) We current do not have any way to deal with this version 1341 of the attack except to restrict the overall set of curves that 1342 can be used. 1344 o Change the hash function used to validate the signature: If one 1345 has either two different hash functions of the same length, or one 1346 can truncate a hash function down, then one could potentially find 1347 collisions between the hash functions rather than within a single 1348 hash function. (For example, truncating SHA-512 to 256 bits might 1349 collide with a SHA-256 bit hash value.) This attack can be 1350 mitigated by including the signature algorithm identifier in the 1351 data to be signed. 1353 9. Message Authentication (MAC) Algorithms 1355 Message Authentication Codes (MACs) provide data authentication and 1356 integrity protection. They provide either no or very limited data 1357 origination. (One cannot, for example, be used to prove the identity 1358 of the sender to a third party.) 1359 MACs use the same basic structure as signature with appendix 1360 algorithms. The message content is processed and an authentication 1361 code is produced. The authentication code is frequently called a 1362 tag. The basic structure becomes: 1364 tag = MAC_Create(message content, key) 1366 valid = MAC_Verify(message content, key, tag) 1368 MAC algorithms can be based on either a block cipher algorithm (i.e. 1369 AES-MAC) or a hash algorithm (i.e. HMAC). This document defines a 1370 MAC algorithm for each of these two constructions. 1372 9.1. Hash-based Message Authentication Codes (HMAC) 1374 The Hash-base Message Authentication Code algorithm (HMAC) 1375 [RFC2104][RFC4231] was designed to deal with length extension 1376 attacks. The algorithm was also designed to allow for new hash 1377 algorithms to be directly plugged in without changes to the hash 1378 function. The HMAC design process has been vindicated as, while the 1379 security of hash algorithms such as MD5 has decreased over time, the 1380 security of HMAC combined with MD5 has not yet been shown to be 1381 compromised [RFC6151]. 1383 The HMAC algorithm is parameterized by an inner and outer padding, a 1384 hash function (h) and an authentication tag value length. For this 1385 specification, the inner and outer padding are fixed to the values 1386 set in [RFC2104]. The length of the authentication tag corresponds 1387 to the difficulty of producing a forgery. For use in constrained 1388 environments, we define a set of HMAC algorithms that are truncated. 1389 There are currently no known issues when truncating, however the 1390 security strength of the message tag is correspondingly reduced in 1391 strength. When truncating, the left-most tag length bits are kept 1392 and transmitted. 1394 The algorithm defined in this document can be found in Table 5. 1396 +-----------+-------+---------+--------+----------------------------+ 1397 | name | value | Hash | Length | description | 1398 +-----------+-------+---------+--------+----------------------------+ 1399 | HMAC | * | SHA-256 | 64 | HMAC w/ SHA-256 truncated | 1400 | 256/64 | | | | to 64 bits | 1401 | | | | | | 1402 | HMAC | 4 | SHA-256 | 256 | HMAC w/ SHA-256 | 1403 | 256/256 | | | | | 1404 | | | | | | 1405 | HMAC | 5 | SHA-384 | 384 | HMAC w/ SHA-384 | 1406 | 384/384 | | | | | 1407 | | | | | | 1408 | HMAC | 6 | SHA-512 | 512 | HMAC w/ SHA-512 | 1409 | 512/512 | | | | | 1410 +-----------+-------+---------+--------+----------------------------+ 1412 Table 5: HMAC Algorithm Values 1414 Some recipient algorithms carry the key while others derive a key 1415 from secret data. For those algorithms that carry the key (i.e. 1416 RSA-OAEP and AES-KeyWrap), the size of the HMAC key SHOULD be the 1417 same size as the underlying hash function. For those algorithms that 1418 derive the key, the derived key MUST be the same size as the 1419 underlying hash function. 1421 If the key is obtained from a key structure, the key type MUST be 1422 'Symmetric'. Implementations creating and validating MAC values MUST 1423 validate that the key type, key length, and algorithm are correct and 1424 appropriate for the entities involved. 1426 9.1.1. Security Considerations 1428 HMAC has proved to be resistant to attack even when used with 1429 weakening hash algorithms. The current best method appears to be a 1430 brute force attack on the key. This means that key size is going to 1431 be directly related to the security of an HMAC operation. 1433 9.2. AES Message Authentication Code (AES-CBC-MAC) 1435 AES-CBC-MAC is defined in [MAC]. 1437 AES-CBC-MAC is parameterized by the key length, the authentication 1438 tag length and the IV used. For all of these algorithms, the IV is 1439 fixed to all zeros. We provide an array of algorithms for various 1440 key lengths and tag lengths. The algorithms defined in this document 1441 are found in Table 6. 1443 +-------------+-------+----------+----------+-----------------------+ 1444 | name | value | key | tag | description | 1445 | | | length | length | | 1446 +-------------+-------+----------+----------+-----------------------+ 1447 | AES-MAC | * | 128 | 64 | AES-MAC 128 bit key, | 1448 | 128/64 | | | | 64-bit tag | 1449 | | | | | | 1450 | AES-MAC | * | 256 | 64 | AES-MAC 256 bit key, | 1451 | 256/64 | | | | 64-bit tag | 1452 | | | | | | 1453 | AES-MAC | * | 128 | 128 | AES-MAC 128 bit key, | 1454 | 128/128 | | | | 128-bit tag | 1455 | | | | | | 1456 | AES-MAC | * | 256 | 128 | AES-MAC 256 bit key, | 1457 | 256/128 | | | | 128-bit tag | 1458 +-------------+-------+----------+----------+-----------------------+ 1460 Table 6: AES-MAC Algorithm Values 1462 Keys may be obtained either from a key structure or from a recipient 1463 structure. If the key obtained from a key structure, the key type 1464 MUST be 'Symmetric'. Implementations creating and validating MAC 1465 values MUST validate that the key type, key length and algorithm are 1466 correct and appropriate for the entities involved. 1468 9.2.1. Security Considerations 1470 A number of attacks exist against CBC-MAC that need to be considered. 1472 o A single key must only be used for messages of a fixed and known 1473 length. If this is not the case, an attacker will be able to 1474 generate a message with a valid tag given two message, tag pairs. 1475 This can be addressed by using different keys for different length 1476 messages. (CMAC mode also addresses this issue.) 1478 o If the same key is used for both encryption and authentication 1479 operations, using CBC modes an attacker can produce messages with 1480 a valid authentication code. 1482 o If the IV can be modified, then messages can be forged. This is 1483 addressed by fixing the IV to all zeros. 1485 10. Content Encryption Algorithms 1487 Content Encryption Algorithms provide data confidentiality for 1488 potentially large blocks of data using a symmetric key. They provide 1489 either no or very limited data origination. (One cannot, for 1490 example, be used to prove the identity of the sender to a third 1491 party.) The ability to provide data origination is linked to how the 1492 symmetric key is obtained. 1494 We restrict the set of legal content encryption algorithms to those 1495 that support authentication both of the content and additional data. 1496 The encryption process will generate some type of authentication 1497 value, but that value may be either explicit or implicit in terms of 1498 the algorithm definition. For simplicity sake, the authentication 1499 code will normally be defined as being appended to the cipher text 1500 stream. The basic structure becomes: 1502 ciphertext = Encrypt(message content, key, additional data) 1504 valid, message content = Decrypt(cipher text, key, additional data) 1506 Most AEAD algorithms are logically defined as returning the message 1507 content only if the decryption is valid. Many but not all 1508 implementations will follow this convention. The message content 1509 MUST NOT be used if the decryption does not validate. 1511 10.1. AES GCM 1513 The GCM mode is a generic authenticated encryption block cipher mode 1514 defined in [AES-GCM]. The GCM mode is combined with the AES block 1515 encryption algorithm to define an AEAD cipher. 1517 The GCM mode is parameterized with by the size of the authentication 1518 tag. The size of the authentication tag is limited to a small set of 1519 values. For this document however, the size of the authentication 1520 tag is fixed at 128 bits. 1522 The set of algorithms defined in this document are in Table 7. 1524 +---------+-------+-----------------------------+ 1525 | name | value | description | 1526 +---------+-------+-----------------------------+ 1527 | A128GCM | 1 | AES-GCM mode w/ 128-bit key | 1528 | | | | 1529 | A192GCM | 2 | AES-GCM mode w/ 192-bit key | 1530 | | | | 1531 | A256GCM | 3 | AES-GCM mode w/ 256-bit key | 1532 +---------+-------+-----------------------------+ 1534 Table 7: Algorithm Value for AES-GCM 1536 Keys may be obtained either from a key structure or from a recipient 1537 structure. If the key obtained from a key structure, the key type 1538 MUST be 'Symmetric'. Implementations encrypting and decrrypting MUST 1539 validate that the key type, key length and algorithm are correct and 1540 appropriate for the entities involved. 1542 10.1.1. Security Considerations 1544 When using AES-CCM, the following restrictions MUST be enforced: 1546 o The key and nonce pair MUST be unique for every message encrypted. 1548 o The total amount of data encrypted MUST NOT exceed 2^39 - 256 1549 bits. An explicit check is required only in environments where it 1550 is expected that it might be exceeded. 1552 10.2. AES CCM 1554 Counter with CBC-MAC (CCM) is a generic authentication encryption 1555 block cipher mode defined in [RFC3610]. The CCM mode is combined 1556 with the AES block encryption algorithm to define a commonly used 1557 content encryption algorithm used in constrained devices. 1559 The CCM mode has two parameter choices. The first choice is M, the 1560 size of the authentication field. The choice of the value for M 1561 involves a trade-off between message expansion and the probably that 1562 an attacker can undetectably modify a message. The second choice is 1563 L, the size of the length field. This value requires a trade-off 1564 between the maximum message size and the size of the Nonce. 1566 It is unfortunate that the specification for CCM specified L and M as 1567 a count of bytes rather than a count of bits. This leads to possible 1568 misunderstandings where AES-CCM-8 is frequently used to refer to a 1569 version of CCM mode where the size of the authentication is 64 bits 1570 and not 8 bits. These values have traditionally been specified as 1571 bit counts rather than byte counts. This document will follow the 1572 tradition of using bit counts so that it is easier to compare the 1573 different algorithms presented in this document. 1575 We define a matrix of algorithms in this document over the values of 1576 L and M. Constrained devices are usually operating in situations 1577 where they use short messages and want to avoid doing recipient 1578 specific cryptographic operations. This favors smaller values of M 1579 and larger values of L. Less constrained devices do will want to be 1580 able to user larger messages and are more willing to generate new 1581 keys for every operation. This favors larger values of M and smaller 1582 values of L. (The use of a large nonce means that random generation 1583 of both the key and the nonce will decrease the chances of repeating 1584 the pair on two different messages.) 1586 The following values are used for L: 1588 16 bits (2) limits messages to 2^16 bytes (64 KiB) in length. This 1589 sufficiently long for messages in the constrained world. The 1590 nonce length is 13 bytes allowing for 2^(13*8) possible values of 1591 the nonce without repeating. 1593 64 bits (8) limits messages to 2^64 bytes in length. The nonce 1594 length is 7 bytes allowing for 2^56 possible values of the nonce 1595 without repeating. 1597 The following values are used for M: 1599 64 bits (8) produces a 64-bit authentication tag. This implies that 1600 there is a 1 in 2^64 chance that a modified message will 1601 authenticate. 1603 128 bits (16) produces a 128-bit authentication tag. This implies 1604 that there is a 1 in 2^128 chance that a modified message will 1605 authenticate. 1607 +--------------------+-------+----+-----+-----+---------------------+ 1608 | name | value | L | M | k | description | 1609 +--------------------+-------+----+-----+-----+---------------------+ 1610 | AES-CCM-16-64-128 | 10 | 16 | 64 | 128 | AES-CCM mode | 1611 | | | | | | 128-bit key, 64-bit | 1612 | | | | | | tag, 13-byte nonce | 1613 | | | | | | | 1614 | AES-CCM-16-64-256 | 11 | 16 | 64 | 256 | AES-CCM mode | 1615 | | | | | | 256-bit key, 64-bit | 1616 | | | | | | tag, 13-byte nonce | 1617 | | | | | | | 1618 | AES-CCM-64-64-128 | 30 | 64 | 64 | 128 | AES-CCM mode | 1619 | | | | | | 128-bit key, 64-bit | 1620 | | | | | | tag, 7-byte nonce | 1621 | | | | | | | 1622 | AES-CCM-64-64-256 | 31 | 64 | 64 | 256 | AES-CCM mode | 1623 | | | | | | 256-bit key, 64-bit | 1624 | | | | | | tag, 7-byte nonce | 1625 | | | | | | | 1626 | AES-CCM-16-128-128 | 12 | 16 | 128 | 128 | AES-CCM mode | 1627 | | | | | | 128-bit key, | 1628 | | | | | | 128-bit tag, | 1629 | | | | | | 13-byte nonce | 1630 | | | | | | | 1631 | AES-CCM-16-128-256 | 13 | 16 | 128 | 256 | AES-CCM mode | 1632 | | | | | | 256-bit key, | 1633 | | | | | | 128-bit tag, | 1634 | | | | | | 13-byte nonce | 1635 | | | | | | | 1636 | AES-CCM-64-128-128 | 32 | 64 | 128 | 128 | AES-CCM mode | 1637 | | | | | | 128-bit key, | 1638 | | | | | | 128-bit tag, 7-byte | 1639 | | | | | | nonce | 1640 | | | | | | | 1641 | AES-CCM-64-128-256 | 33 | 64 | 128 | 256 | AES-CCM mode | 1642 | | | | | | 256-bit key, | 1643 | | | | | | 128-bit tag, 7-byte | 1644 | | | | | | nonce | 1645 +--------------------+-------+----+-----+-----+---------------------+ 1647 Table 8: Algorithm Values for AES-CCM 1649 Keys may be obtained either from a key structure or from a recipient 1650 structure. If the key obtained from a key structure, the key type 1651 MUST be 'Symmetric'. Implementations encrypting and decrrypting MUST 1652 validate that the key type, key length and algorithm are correct and 1653 appropriate for the entities involved. 1655 10.2.1. Security Considerations 1657 When using AES-CCM, the following restrictions MUST be enforced: 1659 o The key and nonce pair MUST be unique for every message encrypted. 1661 o The total number of times the AES block cipher is used MUST NOT 1662 exceed 2^61 operations. This limitation is the sum of times the 1663 block cipher is used in computing the MAC value and in performing 1664 stream encryption operations. An explicit check is required only 1665 in environments where it is expected that it might be exceeded. 1667 [RFC3610] additionally calls out one other consideration of note. It 1668 is possible to do a pre-computation attack against the algorithm in 1669 cases where the portions encryption content is highly predictable. 1670 This reduces the security of the key size by half. Ways to deal with 1671 this attack include adding a random portion to the nonce value and/or 1672 increasing the key size used. Using a portion of the nonce for a 1673 random value will decrease the number of messages that a single key 1674 can be used for. Increasing the key size may require more resources 1675 in the constrained device. See sections 5 and 10 of [RFC3610] for 1676 more information. 1678 10.3. ChaCha20 and Poly1305 1680 ChaCha20 and Poly1305 combined together is a new AEAD mode that is 1681 defined in [RFC7539]. This is a new algorithm defined to be a cipher 1682 that is not AES and thus would not suffer from any future weaknesses 1683 found in AES. These cryptographic functions are designed to be fast 1684 in software-only implementations. 1686 The ChaCha20/Poly1305 AEAD construction defined in [RFC7539] has no 1687 parameterization. It takes a 256-bit key and a 96-bit nonce as well 1688 as the plain text and additional data as inputs and produces the 1689 cipher text as an option. We define one algorithm identifier for 1690 this algorithm in Table 9. 1692 +-------------------+-------+----------------------------------+ 1693 | name | value | description | 1694 +-------------------+-------+----------------------------------+ 1695 | ChaCha20/Poly1305 | 11 | ChaCha20/Poly1305 w/ 256-bit key | 1696 +-------------------+-------+----------------------------------+ 1698 Table 9: Algorithm Value for AES-GCM 1700 Keys may be obtained either from a key structure or from a recipient 1701 structure. If the key obtained from a key structure, the key type 1702 MUST be 'Symmetric'. Implementations encrypting and decrrypting MUST 1703 validate that the key type, key length and algorithm are correct and 1704 appropriate for the entities involved. 1706 10.3.1. Security Considerations 1708 The pair of key, nonce MUST be unique for every invocation of the 1709 algorithm. Nonce counters are considered to be an acceptable way of 1710 ensuring that they are unique. 1712 11. Key Derivation Functions (KDF) 1714 Key Derivation Functions (KDFs) are used to take some secret value 1715 and generate a different one. The original secret values come in 1716 three basic flavors: 1718 o Secrets that are uniformly random: This is the type of secret 1719 which is created by a good random number generator. 1721 o Secrets that are not uniformly random: This is type of secret 1722 which is created by operations like key agreement. 1724 o Secrets that are not random: This is the type of secret that 1725 people generate for things like passwords. 1727 General KDF functions work well with the first type of secret, can do 1728 reasonable well with the second type of secret and generally do 1729 poorly with the last type of secret. None of the KDF functions in 1730 this section are designed to deal with the type of secrets that are 1731 used for passwords. Functions like PBSE2 [RFC2898] need to be used 1732 for that type of secret. 1734 Many functions are going to handle the first two type of secrets 1735 differently. The KDF function defined in Section 11.1 can use 1736 different underlying constructions if the secret is uniformly random 1737 than if the secret is not uniformly random. This is reflected in the 1738 set of algorithms defined for HKDF. 1740 When using KDF functions, one component that is generally included is 1741 context information. Context information is used to allow for 1742 different keying information to be derived from the same secret. The 1743 use of context based keying material is considered to be a good 1744 security practice. This document defines a single context structure 1745 and a single KDF function. 1747 11.1. HMAC-based Extract-and-Expand Key Derivation Function (HKDF) 1749 The HKDF key derivation algorithm is defined in [RFC5869]. 1751 The HKDF algorithm takes these inputs: 1753 secret - a shared value that is secret. Secrets may be either 1754 previously shared or derived from operations like a DH key 1755 agreement. 1757 salt - an optional public value that is used to change the 1758 generation process. If specified, the salt is carried using the 1759 'salt' algorithm parameter. While [RFC5869] suggests that the 1760 length of the salt be the same as the length of the underlying 1761 hash value, any amount of salt will improve the security as 1762 different key values will be generated. A parameter to carry the 1763 salt is defined in Table 11. This parameter is protected by being 1764 included in the key computation and does not need to be separately 1765 authenticated. 1767 length - the number of bytes of output that need to be generated. 1769 context information - Information that describes the context in 1770 which the resulting value will be used. Making this information 1771 specific to the context that the material is going to be used 1772 ensures that the resulting material will always be unique. The 1773 context structure used is encoded into the algorithm identifier. 1775 hash function - The underlying hash function to be used in the 1776 HKDF algorithm. The hash function is encoded into the HKDF 1777 algorithm selection. 1779 HKDF is defined to use HMAC as the underlying PRF. However, it is 1780 possible to use other functions in the same construct to provide a 1781 different KDF function that may be more appropriate in the 1782 constrained world. Specifically, one can use AES-CBC-MAC as the PRF 1783 for the expand step, but not for the extract step. When using a good 1784 random shared secret of the correct length, the extract step can be 1785 skipped. The extract cannot be skipped if the secret is not 1786 uniformly random, for example if it is the result of an ECDH key 1787 agreement step. 1789 The algorithms defined in this document are found in Table 10. 1791 +-------------+-------------+----------+----------------------------+ 1792 | name | hash | Skip | context | 1793 | | | extract | | 1794 +-------------+-------------+----------+----------------------------+ 1795 | HKDF | SHA-256 | no | XXX | 1796 | SHA-256 | | | | 1797 | | | | | 1798 | HKDF | SHA-512 | no | XXX | 1799 | SHA-512 | | | | 1800 | | | | | 1801 | HKDF AES- | AES-CBC-128 | yes | HKDF using AES-MAC as the | 1802 | MAC-128 | | | PRF w/ 128-bit key | 1803 | | | | | 1804 | HKDF AES- | AES-CBC-128 | yes | HKDF using AES-MAC as the | 1805 | MAC-256 | | | PRF w/ 256-bit key | 1806 +-------------+-------------+----------+----------------------------+ 1808 Table 10: HKDF algorithms 1810 +------+-------+------+-------------+ 1811 | name | label | type | description | 1812 +------+-------+------+-------------+ 1813 | salt | -20 | bstr | Random salt | 1814 +------+-------+------+-------------+ 1816 Table 11: HKDF Algorithm Parameters 1818 11.2. Context Information Structure 1820 The context information structure is used to ensure that the derived 1821 keying material is "bound" to the context of the transaction. The 1822 context information structure used here is based on that defined in 1823 [SP800-56A]. By using CBOR for the encoding of the context 1824 information structure, we automatically get the same type of type and 1825 length separation of fields that is obtained by the use of ASN.1. 1826 This means that there is no need to encode the lengths for the base 1827 elements as it is done by the JOSE encoding. [CREF8] 1829 The context information structure refers to PartyU and PartyV as the 1830 two parties which are doing the key derivation. Unless the 1831 application protocol defines differently, we assign PartyU to the 1832 entity that is creating the message and PartyV to the entity that is 1833 receiving the message. By doing this association, different keys 1834 will be derived for each direction as the context information is 1835 different in each direction. 1837 Application protocols are free to define the roles differently. For 1838 example, they could assign the PartyU role to the entity that 1839 initiates the connection and allow directly sending multiple messages 1840 over the connection in both directions without changing the role 1841 information. 1843 The use of a transaction identifier, either in one of the 1844 supplemental fields or as the salt if one is using HKDF, ensures that 1845 a unique key is generated for each set of transactions. Combining 1846 nonce fields with the transaction identifier provides a method so 1847 that a different key is used for each message in each direction. 1849 The context structure is built from information that is known to both 1850 entities. Some of the information is known only to the two entities, 1851 some is implied based on the application and some is explicitly 1852 transported as part of the message. The information that can be 1853 carried in the message, parameters have been defined and can be found 1854 in Table 12. These parameters are designed to be placed in the 1855 unprotected bucket of the recipient structure. (They do not need to 1856 be in the protected bucket since they already are included in the 1857 cryptographic computation by virtue of being included in the context 1858 structure.) 1860 We encode the context specific information using a CBOR array type. 1861 The fields in the array are: 1863 AlgorithmID This field indicates the algorithm for which the key 1864 material will be used. This field is required to be present and 1865 is a copy of the algorithm identifier in the message. The field 1866 exists in the context information so that if the same environment 1867 is used for different algorithms, then completely different keys 1868 will be generated each of those algorithms. (This practice means 1869 if algorithm A is broken and thus can is easier to find, the key 1870 derived for algorithm B will not be the same as the key for 1871 algorithm B.) 1873 PartyUInfo This field holds information about party U. The 1874 PartyUInfo is encoded as a CBOR structure. The elements of 1875 PartyUInfo are encoded in the order presented, however if the 1876 element does not exist no element is placed in the array. The 1877 elements of the PartyUInfo array are: 1879 identity This contains the identity information for party U. The 1880 identities can be assigned in one of two manners. Firstly, a 1881 protocol can assign identities based on roles. For example, 1882 the roles of "client" and "server" may be assigned to different 1883 entities in the protocol. Each entity would then use the 1884 correct label for the data they send or receive. The second 1885 way is for a protocol to assign identities is to use a name 1886 based on a naming system (i.e. DNS, X.509 names). 1888 We define an algorithm parameter 'PartyU identity' that can be 1889 used to carry identity information in the message. However, 1890 identity information is often known as part of the protocol and 1891 can thus be inferred rather than made explicit. If identity 1892 information is carried in the message, applications SHOULD have 1893 a way of validating the supplied identity information. The 1894 identity information does not need to be specified and can be 1895 left as absent. 1896 The identity value supplied will be integrity checked as part 1897 of the key derivation process. If the identity string is 1898 wrong, then the wrong key will be created. 1900 nonce This contains a one time nonce value. The nonce can either 1901 be implicit from the protocol or carried as a value in the 1902 unprotected headers. 1903 We define an algorithm parameter 'PartyU nonce' that can be 1904 used to carry this value in the message However, the nonce 1905 value could be determined by the application and the value 1906 determined from elsewhere. 1907 This item is optional and can be absent. 1909 other This contains other information that is defined by the 1910 protocol. 1911 This item is optional and can be absent. 1913 PartyVInfo M00TODO: Copy down from PartyUInfo when that text is 1914 ready. 1916 SuppPubInfo This field contains public information that is mutually 1917 known to both parties. 1919 keyDataLength This is set to the number of bits of the desired 1920 output value. (This practice means if algorithm A can use two 1921 different key lengths, the key derived for longer key size will 1922 not contain the key for shorter key size as a prefix.) 1924 protected This field contains the protected parameter field. 1926 other The field other is for free form data defined by the 1927 application. An example is that an application could defined 1928 two different strings to be placed here to generate different 1929 keys for a data stream vs a control stream. This field is 1930 optional and will only be present if the application defines a 1931 structure for this information. Applications that define this 1932 SHOULD use CBOR to encode the data so that types and lengths 1933 are correctly include. 1935 SuppPrivInfo This field contains private information that is 1936 mutually known information. An example of this information would 1937 be a pre-existing shared secret. The field is optional and will 1938 only be present if the application defines a structure for this 1939 information. Applications that define this SHOULD use CBOR to 1940 encode the data so that types and lengths are correctly include. 1942 +---------------+-------+-----------+-------------------------------+ 1943 | name | label | type | description | 1944 +---------------+-------+-----------+-------------------------------+ 1945 | PartyU | -21 | bstr | Party U identity Information | 1946 | identity | | | | 1947 | | | | | 1948 | PartyU nonce | -22 | bstr / | Party U provided nonce | 1949 | | | int | | 1950 | | | | | 1951 | PartyU other | -23 | bstr | Party U other provided | 1952 | | | | information | 1953 | | | | | 1954 | PartyV | -24 | bstr | Party V identity Information | 1955 | identity | | | | 1956 | | | | | 1957 | PartyV nonce | -25 | bstr / | Party V provided nonce | 1958 | | | int | | 1959 | | | | | 1960 | PartyV other | -26 | bstr | Party V other provided | 1961 | | | | information | 1962 +---------------+-------+-----------+-------------------------------+ 1964 Table 12: Context Algorithm Parameters 1966 Text from here to start of next section to be removed 1967 COSE_KDF_Context = [ 1968 AlgorithmID : int / tstr, 1969 PartyUInfo : [ 1970 ? nonce : bstr / int, 1971 ? identity : bstr, 1972 ? other : bstr 1973 ], 1974 PartyVInfo : [ 1975 ? nonce : bstr, 1976 ? identity : bstr / tstr, 1977 ? other : bstr 1978 ], 1979 SuppPubInfo : [ 1980 keyDataLength : uint, 1981 protected : bstr, 1982 ? other : bstr 1983 ], 1984 ? SuppPrivInfo : bstr 1985 ] 1987 12. Recipient Algorithm Classes 1989 Recipient algorithms can be defined into a number of different 1990 classes. COSE has the ability to support many classes of recipient 1991 algorithms. In this section, a number of classes are listed and then 1992 a set of algorithms are specified for each of the classes. The names 1993 of the recipient algorithm classes used here are the same as are 1994 defined in [RFC7516]. Other specifications use different terms for 1995 the recipient algorithm classes or do not support some of our 1996 recipient algorithm classes. 1998 12.1. Direct Encryption 2000 The direct encryption class algorithms share a secret between the 2001 sender and the recipient that is used either directly or after 2002 manipulation as the content key. When direct encryption mode is 2003 used, it MUST be the only mode used on the message. 2005 The COSE_encrypt structure for the recipient is organized as follows: 2007 o The 'protected' field MUST be a zero length item if it is not used 2008 in the computation of the content key. 2010 o The 'alg' parameter MUST be present. 2012 o A parameter identifying the shared secret SHOULD be present. 2014 o The 'ciphertext' field MUST be a zero length item. 2016 o The 'recipients' field MUST be absent. 2018 12.1.1. Direct Key 2020 This recipient algorithm is the simplest, the supplied key is 2021 directly used as the key for the next layer down in the message. 2022 There are no algorithm parameters defined for this algorithm. The 2023 algorithm identifier value is assigned in Table 13. 2025 When this algorithm is used, the protected field MUST be zero length. 2026 The key type MUST be 'Symmetric'. 2028 +--------+-------+-------------------+ 2029 | name | value | description | 2030 +--------+-------+-------------------+ 2031 | direct | -6 | Direct use of CEK | 2032 +--------+-------+-------------------+ 2034 Table 13: Direct Key 2036 12.1.1.1. Security Considerations 2038 This recipient algorithm has several potential problems that need to 2039 be considered: 2041 o These keys need to have some method to be regularly updated over 2042 time. All of the content encryption algorithms specified in this 2043 document have limits on how many times a key can be used without 2044 significant loss of security. 2046 o These keys need to be dedicated to a single algorithm. There have 2047 been a number of attacks developed over time when a single key is 2048 used for multiple different algorithms. One example of this is 2049 the use of a single key both for CBC encryption mode and CBC-MAC 2050 authentication mode. 2052 o Breaking one message means all messages are broken. If an 2053 adversary succeeds in determining the key for a single message, 2054 then the key for all messages is also determined. 2056 12.1.2. Direct Key with KDF 2058 These recipient algorithms take a common shared secret between the 2059 two parties and applies the HKDF function (Section 11.1) using the 2060 context structure defined in Section 11.2 to transform the shared 2061 secret into the necessary key. Either the 'salt' parameter of HKDF 2062 or the partyU 'nonce' parameter of the context structure MUST be 2063 present. This parameter can be generated either randomly or 2064 deterministically. The requirement is that it be a unique value for 2065 the key pair in question. 2067 If the salt/nonce value is generated randomly, then it is suggested 2068 that the length of the random value be the same length as the hash 2069 function underlying HKDF. While there is no way to guarantee that it 2070 will be unique, there is a high probability that it will be unique. 2071 If the salt/nonce value is generated deterministically, it can be 2072 guaranteed to be unique and thus there is no length requirement. 2074 A new IV must be used if the same key is used in more than one 2075 message. The IV can be modified in a predictable manner, a random 2076 manner or an unpredictable manner. One unpredictable manner that can 2077 be used is to use the HKDF function to generate the IV. If HKDF is 2078 used for generating the IV, the algorithm identifier is set to "IV- 2079 GENERATION". 2081 When these algorithms are used, the key type MUST be 'symmetric'. 2083 The set of algorithms defined in this document can be found in 2084 Table 14. 2086 +---------------------+-------+-------------+-----------------------+ 2087 | name | value | KDF | description | 2088 +---------------------+-------+-------------+-----------------------+ 2089 | direct+HKDF-SHA-256 | * | HKDF | Shared secret w/ HKDF | 2090 | | | SHA-256 | and SHA-256 | 2091 | | | | | 2092 | direct+HKDF-SHA-512 | * | HKDF | Shared secret w/ HKDF | 2093 | | | SHA-512 | and SHA-512 | 2094 | | | | | 2095 | direct+HKDF-AES-128 | * | HKDF AES- | Shared secret w/ AES- | 2096 | | | MAC-128 | MAC 128-bit key | 2097 | | | | | 2098 | direct+HKDF-AES-256 | * | HKDF AES- | Shared secret w/ AES- | 2099 | | | MAC-256 | MAC 256-bit key | 2100 +---------------------+-------+-------------+-----------------------+ 2102 Table 14: Direct Key 2104 12.1.2.1. Security Considerations 2106 The shared secret needs to have some method to be regularly updated 2107 over time. The shared secret forms the basis of trust. Although not 2108 used directly, it should still be subject to scheduled rotation. 2110 12.2. Key Wrapping 2112 In key wrapping mode, the CEK is randomly generated and that key is 2113 then encrypted by a shared secret between the sender and the 2114 recipient. All of the currently defined key wrapping algorithms for 2115 JOSE (and thus for COSE) are AE algorithms. Key wrapping mode is 2116 considered to be superior to direct encryption if the system has any 2117 capability for doing random key generation. This is because the 2118 shared key is used to wrap random data rather than data has some 2119 degree of organization and may in fact be repeating the same content. 2121 The COSE_encrypt structure for the recipient is organized as follows: 2123 o The 'protected' field MUST be absent if the key wrap algorithm is 2124 an AE algorithm. 2126 o The 'recipients' field is normally absent, but can be used. 2127 Applications MUST deal with a recipients field present, not being 2128 able to decrypt that recipient is an acceptable way of dealing 2129 with it. Failing to process the message is not an acceptable way 2130 of dealing with it. 2132 o The plain text to be encrypted is the key from next layer down 2133 (usually the content layer). 2135 o At a minimum, the 'unprotected' field MUST contain the 'alg' 2136 parameter and SHOULD contain a parameter identifying the shared 2137 secret. 2139 12.2.1. AES Key Wrapping 2141 The AES Key Wrapping algorithm is defined in [RFC3394]. This 2142 algorithm uses an AES key to wrap a value that is a multiple of 64 2143 bits. As such, it can be used to wrap a key for any of the content 2144 encryption algorithms defined in this document. The algorithm 2145 requires a single fixed parameter, the initial value. This is fixed 2146 to the value specified in Section 2.2.3.1 of [RFC3394]. There are no 2147 public parameters that vary on a per invocation basis. 2149 Keys may be obtained either from a key structure or from a recipient 2150 structure. If the key obtained from a key structure, the key type 2151 MUST be 'Symmetric'. Implementations encrypting and decrrypting MUST 2152 validate that the key type, key length and algorithm are correct and 2153 appropriate for the entities involved. 2155 +--------+-------+----------+-----------------------------+ 2156 | name | value | key size | description | 2157 +--------+-------+----------+-----------------------------+ 2158 | A128KW | -3 | 128 | AES Key Wrap w/ 128-bit key | 2159 | | | | | 2160 | A192KW | -4 | 192 | AES Key Wrap w/ 192-bit key | 2161 | | | | | 2162 | A256KW | -5 | 256 | AES Key Wrap w/ 256-bit key | 2163 +--------+-------+----------+-----------------------------+ 2165 Table 15: AES Key Wrap Algorithm Values 2167 12.2.1.1. Security Considerations for AES-KW 2169 The shared secret need to have some method to be regularly updated 2170 over time. The shared secret is forming the basis of trust, although 2171 not used directly it should still be subject to scheduled rotation. 2173 12.3. Key Encryption 2175 Key Encryption mode is also called key transport mode in some 2176 standards. Key Encryption mode differs from Key Wrap mode in that it 2177 uses an asymmetric encryption algorithm rather than a symmetric 2178 encryption algorithm to protect the key. This document defines one 2179 Key Encryption mode algorithm. 2181 When using a key encryption algorithm, the COSE_encrypt structure for 2182 the recipient is organized as follows: 2184 o The 'protected' field MUST be absent. 2186 o The plain text to be encrypted is the key from next layer down 2187 (usually the content layer). 2189 o At a minimum, the 'unprotected' field MUST contain the 'alg' 2190 parameter and SHOULD contain a parameter identifying the 2191 asymmetric key. 2193 12.4. Direct Key Agreement 2195 The 'direct key agreement' class of recipient algorithms uses a key 2196 agreement method to create a shared secret. A KDF is then applied to 2197 the shared secret to derive a key to be used in protecting the data. 2198 This key is normally used as a CEK or MAC key, but could be used for 2199 other purposes if more than two layers are in use (see Appendix B). 2201 The most commonly used key agreement algorithm used is Diffie- 2202 Hellman, but other variants exist. Since COSE is designed for a 2203 store and forward environment rather than an on-line environment, 2204 many of the DH variants cannot be used as the receiver of the message 2205 cannot provide any key material. One side-effect of this is that 2206 perfect forward security is not achievable. A static key will always 2207 be used for the receiver of the COSE message. 2209 Two variants of DH that are easily supported are: 2211 - Ephemeral-Static DH: where the sender of the message creates a 2212 one time DH key and uses a static key for the recipient. The use 2213 of the ephemeral sender key means that no additional random input 2214 is needed as this is randomly generated for each message. 2216 Static-Static DH: where a static key is used for both the sender 2217 and the recipient. The use of static keys allows for recipient to 2218 get a weak version of data origination for the message. When 2219 static-static key agreement is used, then some piece of unique 2220 data is required to ensure that a different key is created for 2221 each message. 2223 In this specification, both variants are specified. This has been 2224 done to provide the weak data origination option for use with MAC 2225 operations. 2227 When direct key agreement mode is used, there MUST be only one 2228 recipient in the message. This method creates the key directly and 2229 that makes it difficult to mix with additional recipients. If 2230 multiple recipients are needed, then the version with key wrap needs 2231 to be used. 2233 The COSE_encrypt structure for the recipient is organized as follows: 2235 o The 'protected' field MUST be absent. 2237 o At a minimum, the 'unprotected' field MUST contain the 'alg' 2238 parameter and SHOULD contain a parameter identifying the 2239 recipient's asymmetric key. 2241 o The 'unprotected' field MUST contain the 'epk' parameter. 2243 12.4.1. ECDH 2245 The basic mathematics for Elliptic Curve Diffie-Hellman can be found 2246 in [RFC6090]. 2248 ECDH is parameterized by the following: 2250 o Curve Type/Curve: The curve selected controls not only the size of 2251 the shared secret, but the mathematics for computing the shared 2252 secret. The curve selected also controls how a point in the curve 2253 is represented and what happens for the identity points on the 2254 curve. In this specification, we allow for a number of different 2255 curves to be used. The curves are defined in Table 19. 2256 Since the only the math is changed by changing the curve, the 2257 curve is not fixed for any of the algorithm identifiers we define. 2258 Instead, it is defined by the points used. 2260 o Ephemeral-static or static-static: The key agreement process may 2261 be done using either a static or an ephemeral key at the sender's 2262 side. When using ephemeral keys, the sender MUST generate a new 2263 ephemeral key for every key agreement operation. The ephemeral 2264 key is placed in the 'ephemeral key' parameter and MUST be present 2265 for all algorithm identifiers that use ephemeral keys. When using 2266 static keys, the sender MUST either generate a new random value 2267 placed in either in the KDF parameters or the context structure. 2268 For the KDF functions used, this means either in the 'salt' 2269 parameter for HKDF (Table 11) or in the 'PartyU nonce' parameter 2270 for the context structure (Table 12) MUST be present. (Both may 2271 be present if desired.) The value in the parameter MUST be unique 2272 for the key pair being used. It is acceptable to use a global 2273 counter that is incremented for every static-static operation and 2274 use the resulting value. When using static keys, the static key 2275 needs to be identified to the recipient. The static key can be 2276 identified either by providing the key ('static key') or by 2277 providing a key identifier for the static key ('static key id'). 2278 Both of these parameters are defined in Table 17 2280 o Key derivation algorithm: The result of an ECDH key agreement 2281 process does not provide a uniformly random secret. As such, it 2282 needs to be run through a KDF in order to produce a usable key. 2283 Processing the secret through a KDF also allows for the 2284 introduction of both context material, how the key is going to be 2285 used, and one time material in the even to of a static-static key 2286 agreement. 2288 o Key Wrap algorithm: The key wrap algorithm can be 'none' if the 2289 result of the KDF is going to be used as the key directly. This 2290 option, along with static-static, should be used if knowledge 2291 about the sender is desired. If 'none' is used, then the content 2292 layer encryption algorithm size is value fed to the context 2293 structure. Support is also provided for any of the key wrap 2294 algorithms defined in Section 12.2.1. If one of these options is 2295 used, the input key size to the key wrap algorithm is the value 2296 fed into the context structure as the key size. 2298 The set of direct ECDH algorithms defined in this document are found 2299 in Table 16. 2301 +-------------+------+-------+----------------+--------+------------+ 2302 | name | valu | KDF | Ephemeral- | Key | descriptio | 2303 | | e | | Static | Wrap | n | 2304 +-------------+------+-------+----------------+--------+------------+ 2305 | ECDH-ES + | 50 | HKDF | yes | none | ECDH ES w/ | 2306 | HKDF-256 | | - SHA | | | HKDF - | 2307 | | | -256 | | | generate | 2308 | | | | | | key | 2309 | | | | | | directly | 2310 | | | | | | | 2311 | ECDH-ES + | 51 | HKDF | yes | none | ECDH ES w/ | 2312 | HKDF-512 | | - SHA | | | HKDF - | 2313 | | | -256 | | | generate | 2314 | | | | | | key | 2315 | | | | | | directly | 2316 | | | | | | | 2317 | ECDH-SS + | 52 | HKDF | no | none | ECDH ES w/ | 2318 | HKDF-256 | | - SHA | | | HKDF - | 2319 | | | -256 | | | generate | 2320 | | | | | | key | 2321 | | | | | | directly | 2322 | | | | | | | 2323 | ECDH-SS + | 53 | HKDF | no | none | ECDH ES w/ | 2324 | HKDF-512 | | - SHA | | | HKDF - | 2325 | | | -256 | | | generate | 2326 | | | | | | key | 2327 | | | | | | directly | 2328 | | | | | | | 2329 | ECDH- | 54 | HKDF | yes | A128KW | ECDH ES w/ | 2330 | ES+A128KW | | - SHA | | | Concat KDF | 2331 | | | -256 | | | and AES | 2332 | | | | | | Key wrap | 2333 | | | | | | w/ 128 bit | 2334 | | | | | | key | 2335 | | | | | | | 2336 | ECDH- | 55 | HKDF | yes | A192KW | ECDH ES w/ | 2337 | ES+A192KW | | - SHA | | | Concat KDF | 2338 | | | -256 | | | and AES | 2339 | | | | | | Key wrap | 2340 | | | | | | w/ 192 bit | 2341 | | | | | | key | 2342 | | | | | | | 2343 | ECDH- | 56 | HKDF | yes | A256KW | ECDH ES w/ | 2344 | ES+A256KW | | - SHA | | | Concat KDF | 2345 | | | -256 | | | and AES | 2346 | | | | | | Key wrap | 2347 | | | | | | w/ 256 bit | 2348 | | | | | | key | 2349 | | | | | | | 2350 | ECDH- | 57 | HKDF | no | A128KW | ECDH SS w/ | 2351 | SS+A128KW | | - SHA | | | Concat KDF | 2352 | | | -256 | | | and AES | 2353 | | | | | | Key wrap | 2354 | | | | | | w/ 128 bit | 2355 | | | | | | key | 2356 | | | | | | | 2357 | ECDH- | 58 | HKDF | no | A192KW | ECDH SS w/ | 2358 | SS+A192KW | | - SHA | | | Concat KDF | 2359 | | | -256 | | | and AES | 2360 | | | | | | Key wrap | 2361 | | | | | | w/ 192 bit | 2362 | | | | | | key | 2363 | | | | | | | 2364 | ECDH- | 59 | HKDF | no | A256KW | ECDH SS w/ | 2365 | SS+A256KW | | - SHA | | | Concat KDF | 2366 | | | -256 | | | and AES | 2367 | | | | | | Key wrap | 2368 | | | | | | w/ 256 bit | 2369 | | | | | | key | 2370 +-------------+------+-------+----------------+--------+------------+ 2372 Table 16: ECDH Algorithm Values 2374 +-----------+-------+----------+-----------+------------------------+ 2375 | name | label | type | algorithm | description | 2376 +-----------+-------+----------+-----------+------------------------+ 2377 | ephemeral | -1 | COSE_Key | ECDH-ES | Ephemeral Public key | 2378 | key | | | | for the sender | 2379 | | | | | | 2380 | static | -2 | COSE_Key | ECDH-ES | Static Public key for | 2381 | key | | | | the sender | 2382 | | | | | | 2383 | static | -3 | bstr | ECDH-SS | Static Public key | 2384 | key id | | | | identifier for the | 2385 | | | | | sender | 2386 +-----------+-------+----------+-----------+------------------------+ 2388 Table 17: ECDH Algorithm Parameters 2390 This document defines these algorithms to be used with the curves 2391 P-256, P-384, P-521. Implementations MUST verify that the key type 2392 and curve are correct. Different curves are restricted to different 2393 key types. Implementations MUST verify that the curve and algorithm 2394 are appropriate for the entities involved. 2396 12.5. Key Agreement with KDF 2398 Key Agreement with Key Wrapping uses a randomly generated CEK. The 2399 CEK is then encrypted using a Key Wrapping algorithm and a key 2400 derived from the shared secret computed by the key agreement 2401 algorithm. 2403 The COSE_encrypt structure for the recipient is organized as follows: 2405 o The 'protected' field is fed into the KDF context structure. 2407 o The plain text to be encrypted is the key from next layer down 2408 (usually the content layer). 2410 o The 'alg' parameter MUST be present in the layer. 2412 o A parameter identifying the recipient's key SHOULD be present. A 2413 parameter identifying the sender's key SHOULD be present. 2415 12.5.1. ECDH 2417 These algorithms are defined in Table 16. 2419 13. Keys 2421 The COSE_Key object defines a way to hold a single key object. It is 2422 still required that the members of individual key types be defined. 2423 This section of the document is where we define an initial set of 2424 members for specific key types. 2426 For each of the key types, we define both public and private members. 2427 The public members are what is transmitted to others for their usage. 2428 We define private members mainly for the purpose of archival of keys 2429 by individuals. However, there are some circumstances in which 2430 private keys may be distributed by various entities in a protocol. 2431 Examples include: entities that have poor random number generation, 2432 centralized key creation for multi-cast type operations, and 2433 protocols in which a shared secret is used as a bearer token for 2434 authorization purposes. 2436 Key types are identified by the 'kty' member of the COSE_Key object. 2437 In this document, we define four values for the member: 2439 +-----------+-------+--------------------------------------------+ 2440 | name | value | description | 2441 +-----------+-------+--------------------------------------------+ 2442 | EC2 | 2 | Elliptic Curve Keys w/ X,Y Coordinate pair | 2443 | | | | 2444 | Symmetric | 4 | Symmetric Keys | 2445 | | | | 2446 | Reserved | 0 | This value is reserved | 2447 +-----------+-------+--------------------------------------------+ 2449 Table 18: Key Type Values 2451 13.1. Elliptic Curve Keys 2453 Two different key structures could be defined for Elliptic Curve 2454 keys. One version uses both an x and a y coordinate, potentially 2455 with point compression. This is the traditional EC point 2456 representation that is used in [RFC5480]. The other version uses 2457 only the x coordinate as the y coordinate is either to be recomputed 2458 or not needed for the key agreement operation. Currently no 2459 algorithms are defined using this key structure. 2461 +-------+----------+-------+------------------------------------+ 2462 | name | key type | value | description | 2463 +-------+----------+-------+------------------------------------+ 2464 | P-256 | EC2 | 1 | NIST P-256 also known as secp256r1 | 2465 | | | | | 2466 | P-384 | EC2 | 2 | NIST P-384 also known as secp384r1 | 2467 | | | | | 2468 | P-521 | EC2 | 3 | NIST P-521 also known as secp521r1 | 2469 +-------+----------+-------+------------------------------------+ 2471 Table 19: EC Curves 2473 13.1.1. Double Coordinate Curves 2475 The traditional way of sending EC curves has been to send either both 2476 the x and y coordinates, or the x coordinate and a sign bit for the y 2477 coordinate. The latter encoding has not been recommended in the IETF 2478 due to potential IPR issues. However, for operations in constrained 2479 environments, the ability to shrink a message by not sending the y 2480 coordinate is potentially useful. 2482 For EC keys with both coordinates, the 'kty' member is set to 2 2483 (EC2). The key parameters defined in this section are summarized in 2484 Table 20. The members that are defined for this key type are: 2486 crv contains an identifier of the curve to be used with the key. 2487 The curves defined in this document for this key type can be found 2488 in Table 19. Other curves may be registered in the future and 2489 private curves can be used as well. 2491 x contains the x coordinate for the EC point. The integer is 2492 converted to an octet string as defined in [SEC1]. Zero octets 2493 MUST NOT be removed from the front of the octet string. 2495 y contains either the sign bit or the value of y coordinate for the 2496 EC point. When encoding the value y, the integer is converted to 2497 an octet string (as defined in [SEC1]) and encoded as a CBOR bstr. 2498 Leading zero octets MUST be preserved. When encoding the sign of 2499 y, the expression 'y > 0' is evaluated and encoded a CBOR boolean. 2501 d contains the private key. 2503 For public keys, it is REQUIRED that 'crv', 'x' and 'y' be present in 2504 the structure. For private keys, it is REQUIRED that 'crv' and 'd' 2505 be present in the structure. For private keys, it is RECOMMENDED 2506 that 'x' and 'y' also be present, but they can be recomputed from the 2507 required elements and omitting them saves on space. 2509 +------+-------+-------+---------+----------------------------------+ 2510 | name | key | value | type | description | 2511 | | type | | | | 2512 +------+-------+-------+---------+----------------------------------+ 2513 | crv | 2 | -1 | int / | EC Curve identifier - Taken from | 2514 | | | | tstr | the COSE General Registry | 2515 | | | | | | 2516 | x | 2 | -2 | bstr | X Coordinate | 2517 | | | | | | 2518 | y | 2 | -3 | bstr / | Y Coordinate | 2519 | | | | bool | | 2520 | | | | | | 2521 | d | 2 | -4 | bstr | Private key | 2522 +------+-------+-------+---------+----------------------------------+ 2524 Table 20: EC Key Parameters 2526 13.2. Symmetric Keys 2528 Occasionally it is required that a symmetric key be transported 2529 between entities. This key structure allows for that to happen. 2531 For symmetric keys, the 'kty' member is set to 3 (Symmetric). The 2532 member that is defined for this key type is: 2534 k contains the value of the key. 2536 This key structure contains only private key information, care must 2537 be taken that it is never transmitted accidentally. For public keys, 2538 there are no required fields. For private keys, it is REQUIRED that 2539 'k' be present in the structure. 2541 +------+----------+-------+------+-------------+ 2542 | name | key type | value | type | description | 2543 +------+----------+-------+------+-------------+ 2544 | k | 4 | -1 | bstr | Key Value | 2545 +------+----------+-------+------+-------------+ 2547 Table 21: Symmetric Key Parameters 2549 14. CBOR Encoder Restrictions 2551 There has been an attempt to limit the number of places where the 2552 document needs to impose restrictions on how the CBOR Encoder needs 2553 to work. We have managed to narrow it down to the following 2554 restrictions: 2556 o The restriction applies to the encoding the Sig_structure, the 2557 Enc_structure, and the MAC_structure. 2559 o The rules for Canonical CBOR (Section 3.9 of RFC 7049) MUST be 2560 used in these locations. The main rule that needs to be enforced 2561 is that all lengths in these structures MUST be encoded such that 2562 they are encoded using definite lengths and the minimum length 2563 encoding is used. 2565 o All parsers used SHOULD fail on both parsing and generation if the 2566 same label is used twice as a key for the same map. 2568 15. IANA Considerations 2570 15.1. CBOR Tag assignment 2572 It is requested that IANA assign the following tags from the "Concise 2573 Binary Object Representation (CBOR) Tags" registry. It is requested 2574 that the tags be assigned in the 24 to 255 value range. 2576 The tags to be assigned are: 2578 +-----------+-----------------------+-------------------------------+ 2579 | Tag Value | Data Item | Semantics | 2580 +-----------+-----------------------+-------------------------------+ 2581 | TBD1 | COSE_Sign | COSE Signed Data Object | 2582 | | | | 2583 | TBD2 | COSE_enveloped | COSE Enveloped Data Object | 2584 | | | | 2585 | TBD3 | COSE_encryptData | COSE Encrypted Data Object | 2586 | | | | 2587 | TBD4 | COSE_Mac | COSE Mac-ed Data Object | 2588 | | | | 2589 | TBD5 | COSE_Key, COSE_KeySet | COSE Key or COSE Key Set | 2590 | | | Object | 2591 +-----------+-----------------------+-------------------------------+ 2593 15.2. COSE Header Parameter Registry 2595 It is requested that IANA create a new registry entitled "COSE Header 2596 Parameters". The registery is to be created as Expert Review 2597 Required. 2599 The columns of the registry are: 2601 name The name is present to make it easier to refer to and discuss 2602 the registration entry. The value is not used in the protocol. 2603 Names are to be unique in the table. 2605 label This is the value used for the label. The label can be either 2606 an integer or a string. Registration in the table is based on the 2607 value of the label requested. Integer values between 1 and 255 2608 and strings of length 1 are designated as Standards Track Document 2609 required. Integer values from 256 to 65535 and strings of length 2610 2 are designated as Specification Required. Integer values of 2611 greater than 65535 and strings of length greater than 2 are 2612 designated as first come, first served. Integer values in the 2613 range -1 to -65536 are delegated to the "COSE Header Algorithm 2614 Label" registry. Integer values beyond -65536 are marked as 2615 private use. 2617 value This contains the CBOR type for the value portion of the 2618 label. 2620 value registry This contains a pointer to the registry used to 2621 contain values where the set is limited. 2623 description This contains a brief description of the header field. 2625 specification This contains a pointer to the specification defining 2626 the header field (where public). 2628 The initial contents of the registry can be found in Table 1. The 2629 specification column for all rows in that table should be this 2630 document. 2632 Additionally, the label of 0 is to be marked as 'Reserved'. 2634 15.3. COSE Header Algorithm Label Table 2636 It is requested that IANA create a new registry entitled "COSE Header 2637 Algorithm Labels". The registery is to be created as Expert Review 2638 Required. 2640 The columns of the registry are: 2642 name The name is present to make it easier to refer to and discuss 2643 the registration entry. The value is not used in the protocol. 2645 algorithm The algorithm(s) that this registry entry is used for. 2646 This value is taken from the "COSE Algorithm Value" registry. 2647 Multiple algorithms can be specified in this entry. For the 2648 table, the algorithm, label pair MUST be unique. 2650 label This is the value used for the label. The label is an integer 2651 in the range of -1 to -65536. 2653 value This contains the CBOR type for the value portion of the 2654 label. 2656 value registry This contains a pointer to the registry used to 2657 contain values where the set is limited. 2659 description This contains a brief description of the header field. 2661 specification This contains a pointer to the specification defining 2662 the header field (where public). 2664 The initial contents of the registry can be found in Table 11, 2665 Table 12, and Table 17. The specification column for all rows in 2666 that table should be this document. 2668 15.4. COSE Algorithm Registry 2670 It is requested that IANA create a new registry entitled "COSE 2671 Algorithm Registry". The registery is to be created as Expert Review 2672 Required. 2674 The columns of the registry are: 2676 value The value to be used to identify this algorithm. Algorithm 2677 values MUST be unique. The value can be a positive integer, a 2678 negative integer or a string. Integer values between 0 and 255 2679 and strings of length 1 are designated as Standards Track Document 2680 required. Integer values from 256 to 65535 and strings of length 2681 2 are designated as Specification Required. Integer values of 2682 greater than 65535 and strings of length greater than 2 are 2683 designated as first come, first served. Integer values in the 2684 range -1 to -65536 are delegated to the "COSE Header Algorithm 2685 Label" registry. Integer values beyond -65536 are marked as 2686 private use. 2688 description A short description of the algorithm. 2690 specification A document where the algorithm is defined (if publicly 2691 available). 2693 The initial contents of the registry can be found in Table 8, 2694 Table 7, Table 9, Table 4, Table 5, Table 6, Table 13, Table 14, 2695 Table 15, and Table 16. The specification column for all rows in 2696 that table should be this document. 2698 15.5. COSE Key Common Parameter Registry 2700 It is requested that IANA create a new registry entitled "COSE Key 2701 Common Parameter" Registry. The registery is to be created as Expert 2702 Review Required. 2704 The columns of the registry are: 2706 name This is a descriptive name that enables easier reference to the 2707 item. It is not used in the encoding. 2709 label The value to be used to identify this algorithm. Key map 2710 labels MUST be unique. The label can be a positive integer, a 2711 negative integer or a string. Integer values between 0 and 255 2712 and strings of length 1 are designated as Standards Track Document 2713 required. Integer values from 256 to 65535 and strings of length 2714 2 are designated as Specification Required. Integer values of 2715 greater than 65535 and strings of length greater than 2 are 2716 designated as first come, first served. Integer values in the 2717 range -1 to -65536 are used for key parameters specific to a 2718 single algorithm delegated to the "COSE Key Parameter Label" 2719 registry. Integer values beyond -65536 are marked as private use. 2721 CBOR Type This field contains the CBOR type for the field 2722 registry This field denotes the registry that values come from, if 2723 one exists. 2725 description This field contains a brief description for the field 2727 specification This contains a pointer to the public specification 2728 for the field if one exists 2730 This registry will be initially populated by the values in 2731 Section 7.1. The specification column for all of these entries will 2732 be this document. 2734 15.6. COSE Key Type Parameter Registry 2736 It is requested that IANA create a new registry "COSE Key Type 2737 Parameters". The registery is to be created as Expert Review 2738 Required. 2740 The columns of the table are: 2742 key type This field contains a descriptive string of a key type. 2743 This should be a value that is in the COSE General Values table 2744 and is placed in the 'kty' field of a COSE Key structure. 2746 name This is a descriptive name that enables easier reference to the 2747 item. It is not used in the encoding. 2749 label The label is to be unique for every value of key type. The 2750 range of values is from -256 to -1. Labels are expected to be 2751 reused for different keys. 2753 CBOR type This field contains the CBOR type for the field 2755 description This field contains a brief description for the field 2757 specification This contains a pointer to the public specification 2758 for the field if one exists 2760 This registry will be initially populated by the values in Table 20 2761 and Table 21. The specification column for all of these entries will 2762 be this document. 2764 15.7. COSE Elliptic Curve Registry 2766 It is requested that IANA create a new registry "COSE Elliptic Curve 2767 Parameters". The registery is to be created as Expert Review 2768 Required. 2770 The columns of the table are: 2772 name This is a descriptive name that enables easier reference to the 2773 item. It is not used in the encoding. 2775 value This is the value used to identify the curve. These values 2776 MUST be unique. The integer values from -256 to 255 are 2777 designated as Standards Track Document Required. The integer 2778 values from 256 to 65535 and -65536 to -257 are designated as 2779 Specification Required. Integer values over 65535 are designated 2780 as first come, first served. Integer values less than -65536 are 2781 marked as private use. 2783 key type This designates the key type(s) that can be used with this 2784 curve. 2786 description This field contains a brief description of the curve. 2788 specification This contains a pointer to the public specification 2789 for the curve if one exists. 2791 This registry will be initially populated by the values in Table 18. 2792 The specification column for all of these entries will be this 2793 document. 2795 15.8. Media Type Registrations 2797 15.8.1. COSE Security Message 2799 This section registers the "application/cose" and "application/ 2800 cose+cbor" media types in the "Media Types" registry. [CREF9] These 2801 media types are used to indicate that the content is a COSE_MSG. 2802 [CREF10] 2804 Type name: application 2806 Subtype name: cose 2808 Required parameters: N/A 2810 Optional parameters: N/A 2812 Encoding considerations: binary 2814 Security considerations: See the Security Considerations section 2815 of RFC TBD. 2817 Interoperability considerations: N/A 2818 Published specification: RFC TBD 2820 Applications that use this media type: To be identified 2822 Fragment identifier considerations: N/A 2824 Additional information: 2826 * Magic number(s): N/A 2828 * File extension(s): cbor 2830 * Macintosh file type code(s): N/A 2832 Person & email address to contact for further information: 2833 iesg@ietf.org 2835 Intended usage: COMMON 2837 Restrictions on usage: N/A 2839 Author: Jim Schaad, ietf@augustcellars.com 2841 Change Controller: IESG 2843 Provisional registration? No 2845 Type name: application 2847 Subtype name: cose+cbor 2849 Required parameters: N/A 2851 Optional parameters: N/A 2853 Encoding considerations: binary 2855 Security considerations: See the Security Considerations section 2856 of RFC TBD. 2858 Interoperability considerations: N/A 2860 Published specification: RFC TBD 2862 Applications that use this media type: To be identified 2864 Fragment identifier considerations: N/A 2865 Additional information: 2867 * Magic number(s): N/A 2869 * File extension(s): cbor 2871 * Macintosh file type code(s): N/A 2873 Person & email address to contact for further information: 2874 iesg@ietf.org 2876 Intended usage: COMMON 2878 Restrictions on usage: N/A 2880 Author: Jim Schaad, ietf@augustcellars.com 2882 Change Controller: IESG 2884 Provisional registration? No 2886 15.8.2. COSE Key media type 2888 This section registers the "application/cose-key+cbor" and 2889 "application/cose-key-set+cbor" media types in the "Media Types" 2890 registry. These media types are used to indicate, respectively, that 2891 content is a COSE_Key or COSE_KeySet object. 2893 Type name: application 2895 Subtype name: cose-key+cbor 2897 Required parameters: N/A 2899 Optional parameters: N/A 2901 Encoding considerations: binary 2903 Security considerations: See the Security Considerations section 2904 of RFC TBD. 2906 Interoperability considerations: N/A 2908 Published specification: RFC TBD 2910 Applications that use this media type: To be identified 2912 Fragment identifier considerations: N/A 2913 Additional information: 2915 * Magic number(s): N/A 2917 * File extension(s): cbor 2919 * Macintosh file type code(s): N/A 2921 Person & email address to contact for further information: 2922 iesg@ietf.org 2924 Intended usage: COMMON 2926 Restrictions on usage: N/A 2928 Author: Jim Schaad, ietf@augustcellars.com 2930 Change Controller: IESG 2932 Provisional registration? No 2934 Type name: application 2936 Subtype name: cose-key-set+cbor 2938 Required parameters: N/A 2940 Optional parameters: N/A 2942 Encoding considerations: binary 2944 Security considerations: See the Security Considerations section 2945 of RFC TBD. 2947 Interoperability considerations: N/A 2949 Published specification: RFC TBD 2951 Applications that use this media type: To be identified 2953 Fragment identifier considerations: N/A 2955 Additional information: 2957 * Magic number(s): N/A 2959 * File extension(s): cbor 2960 * Macintosh file type code(s): N/A 2962 Person & email address to contact for further information: 2963 iesg@ietf.org 2965 Intended usage: COMMON 2967 Restrictions on usage: N/A 2969 Author: Jim Schaad, ietf@augustcellars.com 2971 Change Controller: IESG 2973 Provisional registration? No 2975 15.9. CoAP Content Format Registrations 2977 This section registers a set of content formats for CoAP. ID 2978 assignment in the 24-255 range is requested. 2980 +--------------------------+----------+-------+-----------------+ 2981 | Media Type | Encoding | ID | Reference | 2982 +--------------------------+----------+-------+-----------------+ 2983 | application/cose | | TBD10 | [This Document] | 2984 | | | | | 2985 | application/cose-key | | TBD11 | [This Document] | 2986 | | | | | 2987 | application/cose-key-set | | TBD12 | [This Document | 2988 +--------------------------+----------+-------+-----------------+ 2990 16. Security Considerations 2992 There are security considerations: 2994 1. Protect private keys. 2996 2. MAC messages with more than one recipient means one cannot figure 2997 out which party sent the message. 2999 3. Use of a direct key with other recipient structures hands the key 3000 to the other recipients. 3002 4. Use of direct ECDH direct encryption is easy for people to leak 3003 information on if there are other recipients in the message. 3005 5. Considerations about protected vs unprotected header fields. 3007 6. Need to verify that: 1) the kty field of the key matches the key 3008 and algorithm being used, 2) the kty field needs to be included 3009 in the trust decision as well as the other key fields, and 3) the 3010 algorithm is included in the trust decision. 3012 17. References 3014 17.1. Normative References 3016 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3017 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 3018 RFC2119, March 1997, 3019 . 3021 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 3022 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 3023 October 2013, . 3025 17.2. Informative References 3027 [AES-GCM] Dworkin, M., "NIST Special Publication 800-38D: 3028 Recommendation for Block Cipher Modes of Operation: 3029 Galois/Counter Mode (GCM) and GMAC.", Nov 2007. 3031 [DSS] U.S. National Institute of Standards and Technology, 3032 "Digital Signature Standard (DSS)", July 2013. 3034 [I-D.greevenbosch-appsawg-cbor-cddl] 3035 Vigano, C. and H. Birkholz, "CBOR data definition language 3036 (CDDL): a notational convention to express CBOR data 3037 structures", draft-greevenbosch-appsawg-cbor-cddl-07 (work 3038 in progress), October 2015. 3040 [MAC] NiST, N., "FIPS PUB 113: Computer Data Authentication", 3041 May 1985. 3043 [MultiPrimeRSA] 3044 Hinek, M. and D. Cheriton, "On the Security of Multi-prime 3045 RSA", June 2006. 3047 [PVSig] Brown, D. and D. Johnson, "Formal Security Proofs for a 3048 Signature Scheme with Partial Message Recover", February 3049 2000. 3051 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 3052 Hashing for Message Authentication", RFC 2104, DOI 3053 10.17487/RFC2104, February 1997, 3054 . 3056 [RFC2633] Ramsdell, B., Ed., "S/MIME Version 3 Message 3057 Specification", RFC 2633, DOI 10.17487/RFC2633, June 1999, 3058 . 3060 [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography 3061 Specification Version 2.0", RFC 2898, DOI 10.17487/ 3062 RFC2898, September 2000, 3063 . 3065 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 3066 (AES) Key Wrap Algorithm", RFC 3394, DOI 10.17487/RFC3394, 3067 September 2002, . 3069 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 3070 Standards (PKCS) #1: RSA Cryptography Specifications 3071 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 3072 2003, . 3074 [RFC3610] Whiting, D., Housley, R., and N. Ferguson, "Counter with 3075 CBC-MAC (CCM)", RFC 3610, DOI 10.17487/RFC3610, September 3076 2003, . 3078 [RFC4231] Nystrom, M., "Identifiers and Test Vectors for HMAC-SHA- 3079 224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512", RFC 3080 4231, DOI 10.17487/RFC4231, December 2005, 3081 . 3083 [RFC4262] Santesson, S., "X.509 Certificate Extension for Secure/ 3084 Multipurpose Internet Mail Extensions (S/MIME) 3085 Capabilities", RFC 4262, DOI 10.17487/RFC4262, December 3086 2005, . 3088 [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, 3089 "Elliptic Curve Cryptography Subject Public Key 3090 Information", RFC 5480, DOI 10.17487/RFC5480, March 2009, 3091 . 3093 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 3094 RFC 5652, DOI 10.17487/RFC5652, September 2009, 3095 . 3097 [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet 3098 Mail Extensions (S/MIME) Version 3.2 Message 3099 Specification", RFC 5751, DOI 10.17487/RFC5751, January 3100 2010, . 3102 [RFC5752] Turner, S. and J. Schaad, "Multiple Signatures in 3103 Cryptographic Message Syntax (CMS)", RFC 5752, DOI 3104 10.17487/RFC5752, January 2010, 3105 . 3107 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 3108 Key Derivation Function (HKDF)", RFC 5869, DOI 10.17487/ 3109 RFC5869, May 2010, 3110 . 3112 [RFC5990] Randall, J., Kaliski, B., Brainard, J., and S. Turner, 3113 "Use of the RSA-KEM Key Transport Algorithm in the 3114 Cryptographic Message Syntax (CMS)", RFC 5990, DOI 3115 10.17487/RFC5990, September 2010, 3116 . 3118 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 3119 Curve Cryptography Algorithms", RFC 6090, DOI 10.17487/ 3120 RFC6090, February 2011, 3121 . 3123 [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations 3124 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 3125 RFC 6151, DOI 10.17487/RFC6151, March 2011, 3126 . 3128 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 3129 Algorithm (DSA) and Elliptic Curve Digital Signature 3130 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 3131 2013, . 3133 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3134 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 3135 2014, . 3137 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 3138 Application Protocol (CoAP)", RFC 7252, DOI 10.17487/ 3139 RFC7252, June 2014, 3140 . 3142 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 3143 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 3144 2015, . 3146 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 3147 RFC 7516, DOI 10.17487/RFC7516, May 2015, 3148 . 3150 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/ 3151 RFC7517, May 2015, 3152 . 3154 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, DOI 3155 10.17487/RFC7518, May 2015, 3156 . 3158 [RFC7539] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF 3159 Protocols", RFC 7539, DOI 10.17487/RFC7539, May 2015, 3160 . 3162 [SEC1] Standards for Efficient Cryptography Group, "SEC 1: 3163 Elliptic Curve Cryptography", May 2009. 3165 [SP800-56A] 3166 Barker, E., Chen, L., Roginsky, A., and M. Smid, "NIST 3167 Special Publication 800-56A: Recommendation for Pair-Wise 3168 Key Establishment Schemes Using Discrete Logarithm 3169 Cryptography", May 2013. 3171 Appendix A. CDDL Grammar 3173 For people who prefer using a formal language to describe the syntax 3174 of the CBOR, in this section a CDDL grammar is given that corresponds 3175 to [I-D.greevenbosch-appsawg-cbor-cddl]. This grammar is 3176 informational. In the event of differences between this grammar and 3177 the prose, the prose is considered to be authoritative. 3179 The collected CDDL can be extracted from the XML version of this 3180 document via the following XPath expression below. (Depending on the 3181 XPath evaluator one is using, it may be necessary to deal with > 3182 as an entity.) 3184 //artwork[@type='CDDL']/text() 3186 ; This is define to make the tool quieter 3187 Internal_Types = Sig_structure / Enc_structure / MAC_structure / 3188 COSE_KDF_Context 3190 Appendix B. Three Levels of Recipient Information 3192 All of the currently defined recipient algorithms classes only use 3193 two levels of the COSE_Encrypt structure. The first level is the 3194 message content and the second level is the content key encryption. 3195 However, if one uses a recipient algorithm such as RSA-KEM (see 3196 Appendix A of RSA-KEM [RFC5990], then it make sense to have three 3197 levels of the COSE_Encrypt structure. 3199 These levels would be: 3201 o Level 0: The content encryption level. This level contains the 3202 payload of the message. 3204 o Level 1: The encryption of the CEK by a KEK. 3206 o Level 2: The encryption of a long random secret using an RSA key 3207 and a key derivation function to convert that secret into the KEK. 3209 This is an example of what a triple layer message would look like. 3210 The message has the following layers: 3212 o Level 0: Has a content encrypted with AES-GCM using a 128-bit key. 3214 o Level 1: Uses the AES Key wrap algorithm with a 128-bit key. 3216 o Level 2: Uses ECDH Ephemeral-Static direct to generate the level 1 3217 key. 3219 In effect this example is a decomposed version of using the ECDH- 3220 ES+A128KW algorithm. 3222 Size of binary file is 216 bytes 3223 998( [ 3224 h'a10101', 3225 { 3226 5: h'02d1f7e6f26c43d4868d87ce' 3227 }, 3228 h'64f84d913ba60a76070a9a48f26e97e863e285295a44320878caceb0763a3 3229 34806857c67', 3230 [ 3231 [ 3232 h'', 3233 { 3234 1: -3 3235 }, 3236 h'5a15dbf5b282ecb31a6074ee3815c252405dd7583e078188', 3237 [ 3238 [ 3239 h'', 3240 { 3241 1: 50, 3242 4: h'6d65726961646f632e6272616e64796275636b406275636b 3243 6c616e642e6578616d706c65', 3244 -1: { 3245 1: 2, 3246 -1: 1, 3247 -2: h'b2add44368ea6d641f9ca9af308b4079aeb519f11e9b8 3248 a55a600b21233e86e68', 3249 -3: h'1a2cf118b9ee6895c8f415b686d4ca1cef362d4a7630a 3250 31ef6019c0c56d33de0' 3251 } 3252 }, 3253 h'' 3254 ] 3255 ] 3256 ] 3257 ] 3258 ]) 3260 Appendix C. Examples 3262 The examples can be found at https://github.com/cose-wg/Examples. 3263 The file names in each section correspond the same file names in the 3264 repository. I am currently still in the process of getting the 3265 examples up there along with some control information for people to 3266 be able to check and reproduce the examples. 3268 Examples may have some features that are in question but not yet 3269 incorporated in the document. 3271 To make it easier to read, the examples are presented using the 3272 CBOR's diagnostic notation rather than a binary dump. A ruby based 3273 tool exists to convert between a number of formats. This tool can be 3274 installed with the command line: 3276 gem install cbor-diag 3278 The diagnostic notation can be converted into binary files using the 3279 following command line: 3281 diag2cbor < inputfile > outputfile 3283 The examples can be extracted from the XML version of this document 3284 via an XPath expression as all of the artwork is tagged with the 3285 attribute type='CBORdiag'. 3287 C.1. Examples of MAC messages 3289 C.1.1. Shared Secret Direct MAC 3291 This example users the following: 3293 o MAC: AES-CMAC, 256-bit key, truncated to 64 bits 3295 o Recipient class: direct shared secret 3297 o File name: Mac-04 3299 Size of binary file is 73 bytes 3300 996( [ 3301 h'a1016f4145532d434d41432d3235362f3634', 3302 { 3303 }, 3304 h'546869732069732074686520636f6e74656e742e', 3305 h'd9afa663dd740848', 3306 [ 3307 [ 3308 h'', 3309 { 3310 1: -6, 3311 4: h'6f75722d736563726574' 3312 }, 3313 h'' 3314 ] 3315 ] 3316 ]) 3318 C.1.2. ECDH Direct MAC 3320 This example uses the following: 3322 o MAC: HMAC w/SHA-256, 256-bit key 3324 o Recipient class: ECDH key agreement, two static keys, HKDF w/ 3325 context structure 3327 Size of binary file is 217 bytes 3328 996( [ 3329 h'a10104', 3330 { 3331 }, 3332 h'546869732069732074686520636f6e74656e742e', 3333 h'2ba937ca03d76c3dbad30cfcbaeef586f9c0f9ba616ad67e9205d38576ad9 3334 930', 3335 [ 3336 [ 3337 h'', 3338 { 3339 1: 52, 3340 4: h'6d65726961646f632e6272616e64796275636b406275636b6c61 3341 6e642e6578616d706c65', 3342 -3: h'706572656772696e2e746f6f6b407475636b626f726f7567682 3343 e6578616d706c65', 3344 "apu": h'4d8553e7e74f3c6a3a9dd3ef286a8195cbf8a23d19558ccf 3345 ec7d34b824f42d92bd06bd2c7f0271f0214e141fb779ae2856abf585a58368b01 3346 7e7f2a9e5ce4db5' 3347 }, 3348 h'' 3349 ] 3350 ] 3351 ]) 3353 C.1.3. Wrapped MAC 3355 This example uses the following: 3357 o MAC: AES-MAC, 128-bit key, truncated to 64 bits 3359 o Recipient class: AES keywrap w/ a pre-shared 256-bit key 3361 Size of binary file is 124 bytes 3362 996( [ 3363 h'a1016e4145532d3132382d4d41432d3634', 3364 { 3365 }, 3366 h'546869732069732074686520636f6e74656e742e', 3367 h'6d1fa77b2dd9146a', 3368 [ 3369 [ 3370 h'', 3371 { 3372 1: -5, 3373 4: h'30313863306165352d346439622d343731622d626664362d6565 3374 66333134626337303337' 3375 }, 3376 h'711ab0dc2fc4585dce27effa6781c8093eba906f227b6eb0' 3377 ] 3378 ] 3379 ]) 3381 C.1.4. Multi-recipient MAC message 3383 This example uses the following: 3385 o MAC: HMAC w/ SHA-256, 128-bit key 3387 o Recipient class: Uses three different methods 3389 1. ECDH Ephemeral-Static, Curve P-521, AES-Key Wrap w/ 128-bit 3390 key 3392 2. AES-Key Wrap w/ 256-bit key 3394 Size of binary file is 374 bytes 3395 996( [ 3396 h'a10104', 3397 { 3398 }, 3399 h'546869732069732074686520636f6e74656e742e', 3400 h'7aaa6e74546873061f0a7de21ff0c0658d401a68da738dd893748651983ce 3401 1d0', 3402 [ 3403 [ 3404 h'', 3405 { 3406 1: 55, 3407 4: h'62696c626f2e62616767696e7340686f626269746f6e2e657861 3408 6d706c65', 3409 -1: { 3410 1: 2, 3411 -1: 3, 3412 -2: h'43b12669acac3fd27898ffba0bcd2e6c366d53bc4db71f909 3413 a759304acfb5e18cdc7ba0b13ff8c7636271a6924b1ac63c02688075b55ef2d61 3414 3574e7dc242f79c3', 3415 -3: h'812dd694f4ef32b11014d74010a954689c6b6e8785b333d1a 3416 b44f22b9d1091ae8fc8ae40b687e5cfbe7ee6f8b47918a07bb04e9f5b1a51a334 3417 a16bc09777434113' 3418 } 3419 }, 3420 h'f20ad9c96134f3c6be4f75e7101c0ecc5efa071ff20a87fd1ac285109 3421 41ee0376573e2b384b56b99' 3422 ], 3423 [ 3424 h'', 3425 { 3426 1: -5, 3427 4: h'30313863306165352d346439622d343731622d626664362d6565 3428 66333134626337303337' 3429 }, 3430 h'0b2c7cfce04e98276342d6476a7723c090dfdd15f9a518e7736549e99 3431 8370695e6d6a83b4ae507bb' 3432 ] 3433 ] 3434 ]) 3436 C.2. Examples of Encrypted Messages 3438 C.2.1. Direct ECDH 3440 This example uses the following: 3442 o CEK: AES-GCM w/ 128-bit key 3443 o Recipient class: ECDH Ephemeral-Static, Curve P-256 3445 Size of binary file is 184 bytes 3447 998( [ 3448 h'a10101', 3449 { 3450 5: h'c9cf4df2fe6c632bf7886413' 3451 }, 3452 h'45fce2814311024d3a479e7d3eed063850f3f0b9f3f948677e3ae9869bcf9 3453 ff4e1763812', 3454 [ 3455 [ 3456 h'', 3457 { 3458 1: 50, 3459 4: h'6d65726961646f632e6272616e64796275636b406275636b6c61 3460 6e642e6578616d706c65', 3461 -1: { 3462 1: 2, 3463 -1: 1, 3464 -2: h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf05 3465 4e1c7b4d91d6280', 3466 -3: h'f01400b089867804b8e9fc96c3932161f1934f4223069170d 3467 924b7e03bf822bb' 3468 } 3469 }, 3470 h'' 3471 ] 3472 ] 3473 ]) 3475 C.2.2. Direct plus Key Derivation 3477 This example uses the following: 3479 o CEK: AES-CCM w/128-bit key, truncate the tag to 64 bits 3481 o Recipient class: Use HKDF on a shared secret with the following 3482 implicit fields as part of the context. 3484 * APU identity: "lighting-client" 3486 * APV identity: "lighting-server" 3488 * Supplementary Public Other: "Encryption Example 02" 3490 Size of binary file is 97 bytes 3491 998( [ 3492 h'a1010a', 3493 { 3494 5: h'89f52f65a1c580933b5261a7' 3495 }, 3496 h'7b9dcfa42c4e1d3182c402dc18ef8b5637de4fb62cf1dd156ea6e6e0', 3497 [ 3498 [ 3499 h'', 3500 { 3501 1: "dir+kdf", 3502 4: h'6f75722d736563726574', 3503 -20: h'61616262636364646565666667676868' 3504 }, 3505 h'' 3506 ] 3507 ] 3508 ]) 3510 C.3. Examples of Signed Message 3512 C.3.1. Single Signature 3514 This example uses the following: 3516 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256-1 3518 Size of binary file is 105 bytes 3520 999( [ 3521 h'', 3522 { 3523 }, 3524 h'546869732069732074686520636f6e74656e742e', 3525 [ 3526 [ 3527 h'a10126', 3528 { 3529 4: h'3131' 3530 }, 3531 h'4358e9e92b46d45134548b6e3b4eae3d2f801bce85236c7aab42968ad 3532 8e3e92400873ed761735222a6d1f442c4bb3a3151946b16900048572455e65451 3533 d89aaba7' 3534 ] 3535 ] 3536 ]) 3538 C.3.2. Multiple Signers 3540 This example uses the following: 3542 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256-1 3544 o Signature Algorithm: ECDSA w/ SHA-512, Curve P-521 3546 Size of binary file is 277 bytes 3548 999( [ 3549 h'', 3550 { 3551 }, 3552 h'546869732069732074686520636f6e74656e742e', 3553 [ 3554 [ 3555 h'a10126', 3556 { 3557 4: h'3131' 3558 }, 3559 h'0dc1c5e62719d8f3cce1468b7c881eee6a8088b46bf836ae956dd38fe 3560 931991900823ea760648f2425b96c39e23ddc4b7faed56d4a9bd0f3752cfdc628 3561 254ed0f2' 3562 ], 3563 [ 3564 h'', 3565 { 3566 1: -9, 3567 4: h'62696c626f2e62616767696e7340686f626269746f6e2e657861 3568 6d706c65' 3569 }, 3570 h'012ce5b1dfe8b5aa6eaa09a54c58a84ad0900e4fdf2759ec22d1c861c 3571 ccd75c7e1c4025a2da35e512fc2874d6ac8fd862d09ad07ed2deac297b897561e 3572 04a8d42476011eb209c016416b4247b4d1475c398d35c4ac24d1c9fadda7eefe2 3573 857e25a500d29aea539e58e8ca7737fe450d4e87ed3f78e637c12bbd213e78ba8 3574 3a55f7e89934' 3575 ] 3576 ] 3577 ]) 3579 C.4. COSE Keys 3581 C.4.1. Public Keys 3583 This is an example of a COSE Key set. This example includes the 3584 public keys for all of the previous examples. 3586 In order the keys are: 3588 o An EC key with a kid of "meriadoc.brandybuck@buckland.example" 3590 o An EC key with a kid of "peregrin.took@tuckborough.example" 3592 o An EC key with a kid of "bilbo.baggins@hobbiton.example" 3594 o An EC key with a kid of "11" 3596 Size of binary file is 481 bytes 3598 [ 3599 { 3600 -1: 1, 3601 -2: h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de4 3602 39c08551d', 3603 -3: h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eec 3604 d0084d19c', 3605 1: 2, 3606 2: h'6d65726961646f632e6272616e64796275636b406275636b6c616e64 3607 2e6578616d706c65' 3608 }, 3609 { 3610 -1: 3, 3611 -2: h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737b 3612 f5de7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620 3613 085e5c8f42ad', 3614 -3: h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e 3615 247e60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f 3616 3fe1ea1d9475', 3617 1: 2, 3618 2: h'62696c626f2e62616767696e7340686f626269746f6e2e6578616d70 3619 6c65' 3620 }, 3621 { 3622 -1: 1, 3623 -2: h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b 3624 4d91d6280', 3625 -3: h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e 3626 03bf822bb', 3627 1: 2, 3628 2: h'706572656772696e2e746f6f6b407475636b626f726f7567682e6578 3629 616d706c65' 3630 }, 3631 { 3632 -1: 1, 3633 -2: h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a8 3634 6d6a09eff', 3635 -3: h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed2 3636 8bbfc117e', 3637 1: 2, 3638 2: h'3131' 3639 } 3640 ] 3642 C.4.2. Private Keys 3644 This is an example of a COSE Key set. This example includes the 3645 private keys for all of the previous examples. 3647 In order the keys are: 3649 o An EC key with a kid of "meriadoc.brandybuck@buckland.example" 3651 o A shared-secret key with a kid of "our-secret" 3653 o An EC key with a kid of "peregrin.took@tuckborough.example" 3655 o A shared-secret key with a kid of "018c0ae5-4d9b-471b- 3656 bfd6-eef314bc7037" 3658 o An EC key with a kid of "bilbo.baggins@hobbiton.example" 3660 o An EC key with a kid of "11" 3662 Size of binary file is 782 bytes 3664 [ 3665 { 3666 1: 2, 3667 2: h'6d65726961646f632e6272616e64796275636b406275636b6c616e64 3668 2e6578616d706c65', 3669 -1: 1, 3670 -2: h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de4 3671 39c08551d', 3672 -3: h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eec 3673 d0084d19c', 3674 -4: h'aff907c99f9ad3aae6c4cdf21122bce2bd68b5283e6907154ad9118 3675 40fa208cf' 3676 }, 3677 { 3678 1: 4, 3679 2: h'6f75722d736563726574', 3680 -1: h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dce 3681 a6c427188' 3682 }, 3683 { 3684 1: 2, 3685 2: h'62696c626f2e62616767696e7340686f626269746f6e2e6578616d70 3686 6c65', 3687 -1: 3, 3688 -2: h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737b 3689 f5de7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620 3690 085e5c8f42ad', 3691 -3: h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e 3692 247e60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f 3693 3fe1ea1d9475', 3694 -4: h'00085138ddabf5ca975f5860f91a08e91d6d5f9a76ad4018766a476 3695 680b55cd339e8ab6c72b5facdb2a2a50ac25bd086647dd3e2e6e99e84ca2c3609 3696 fdf177feb26d' 3697 }, 3698 { 3699 1: 2, 3700 -1: 1, 3701 2: h'706572656772696e2e746f6f6b407475636b626f726f7567682e6578 3702 616d706c65', 3703 -2: h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b 3704 4d91d6280', 3705 -3: h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e 3706 03bf822bb', 3707 -4: h'02d1f7e6f26c43d4868d87ceb2353161740aacf1f7163647984b522 3708 a848df1c3' 3709 }, 3710 { 3711 1: 4, 3712 2: h'30313863306165352d346439622d343731622d626664362d65656633 3713 3134626337303337', 3714 -1: h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dce 3715 a6c427188' 3716 }, 3717 { 3718 1: 2, 3719 2: h'3131', 3720 -1: 1, 3721 -2: h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a8 3722 6d6a09eff', 3723 -3: h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed2 3724 8bbfc117e', 3725 -4: h'57c92077664146e876760c9520d054aa93c3afb04e306705db60903 3726 08507b4d3' 3727 } 3728 ] 3730 Appendix D. Document Updates 3732 D.1. Version -06 to -07 3734 o Editorial Changes 3736 o Make new IANA registries be Expert Review 3738 D.2. Version -05 to -06 3740 o Remove new CFRG Elliptical Curve key agreement algorithms. 3742 o Remove RSA algorithms 3744 o Define a creation time and sequence number for discussions. 3746 o Remove message type field from all structures. 3748 o Define CBOR tagging for all structures with IANA registrations. 3750 D.3. Version -04 to -05 3752 o Removed the jku, x5c, x5t, x5t#S256, x5u, and jwk headers. 3754 o Add enveloped data vs encrypted data structures. 3756 o Add counter signature parameter. 3758 D.4. Version -03 to -04 3760 o Change top level from map to array. 3762 o Eliminate the term "key management" from the document. 3764 o Point to content registries for the 'content type' attribute 3766 o Push protected field into the KDF functions for recipients. 3768 o Remove password based recipient information. 3770 o Create EC Curve Registry. 3772 D.5. Version -02 to -03 3774 o Make a pass over all of the algorithm text. 3776 o Alter the CDDL so that Keys and KeySets are top level items and 3777 the key examples validate. 3779 o Add sample key structures. 3781 o Expand text on dealing with Externally Supplied Data. 3783 o Update the examples to match some of the renumbering of fields. 3785 D.6. Version -02 to -03 3787 o Add a set of straw man proposals for algorithms. It is possible/ 3788 expected that this text will be moved to a new document. 3790 o Add a set of straw man proposals for key structures. It is 3791 possible/expected that this text will be moved to a new document. 3793 o Provide guidance on use of externally supplied authenticated data. 3795 o Add external authenticated data to signing structure. 3797 D.7. Version -01 to -2 3799 o Add first pass of algorithm information 3801 o Add direct key derivation example. 3803 D.8. Version -00 to -01 3805 o Add note on where the document is being maintained and 3806 contributing notes. 3808 o Put in proposal on MTI algorithms. 3810 o Changed to use labels rather than keys when talking about what 3811 indexes a map. 3813 o Moved nonce/IV to be a common header item. 3815 o Expand section to discuss the common set of labels used in 3816 COSE_Key maps. 3818 o Start marking element 0 in registries as reserved. 3820 o Update examples. 3822 Editorial Comments 3824 [CREF1] JLS: Need to check this list for correctness before publishing. 3826 [CREF2] JLS: I have not gone through the document to determine what 3827 needs to be here yet. We mostly want to grab terms that are 3828 used in unusual ways or are not generally understood. 3830 [CREF3] JLS: It would be possible to extend this section to talk about 3831 those decisions that an application needs to think about rather 3832 than just talking about MTI algorithms. 3834 [CREF4] JLS: A completest version of this grammar would list the options 3835 available in the protected and unprotected headers. Do we want 3836 to head that direction? 3838 [CREF5] Hannes: Ensure that the list of examples only includes items 3839 that are implemented in this specification. Check the other 3840 places where such lists occur and ensure that they also follow 3841 this rule. 3843 [CREF6] JLS: Don't talk about items which we do not define in this 3844 specification. 3846 [CREF7] JLS: We can really simplify the grammar for COSE_Key to be just 3847 the kty (the one required field) and the generic item. The 3848 reason to do this is that it makes things simpler. The reason 3849 not to do this says that we really need to add a lot more items 3850 so that a grammar check can be done that is more tightly 3851 enforced. 3853 [CREF8] Ilari: Look to see if we need to be clearer about how the fields 3854 defined in the table are transported and thus why they have 3855 labels. 3857 [CREF9] JLS: Should we register both or just the cose+cbor one? 3859 [CREF10] JLS: Should we create the equivalent of the smime-type 3860 parameter to identify the inner content type? 3862 Author's Address 3864 Jim Schaad 3865 August Cellars 3867 Email: ietf@augustcellars.com