idnits 2.17.1 draft-ietf-cose-msg-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 457 has weird spacing: '...otected conta...' == Line 470 has weird spacing: '...otected conta...' == Line 658 has weird spacing: '...sg_type ident...' == Line 661 has weird spacing: '...otected conta...' == Line 669 has weird spacing: '...otected conta...' == (18 more instances...) -- The document date (July 20, 2015) is 3202 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 21 == Missing Reference: 'CREF1' is mentioned on line 3294, but not defined == Missing Reference: 'CREF2' is mentioned on line 3296, but not defined == Missing Reference: 'CREF3' is mentioned on line 3300, but not defined == Missing Reference: 'CREF4' is mentioned on line 3304, but not defined == Missing Reference: 'CREF5' is mentioned on line 3311, but not defined == Missing Reference: 'CREF6' is mentioned on line 3314, but not defined == Missing Reference: 'CREF7' is mentioned on line 3316, but not defined == Missing Reference: 'CREF8' is mentioned on line 3320, but not defined == Missing Reference: 'CREF9' is mentioned on line 3325, but not defined == Missing Reference: 'CREF10' is mentioned on line 3329, but not defined == Missing Reference: 'CREF11' is mentioned on line 3331, but not defined == Missing Reference: 'CREF12' is mentioned on line 3334, but not defined == Missing Reference: 'CREF13' is mentioned on line 3337, but not defined == Missing Reference: 'CREF14' is mentioned on line 3339, but not defined == Missing Reference: 'CREF15' is mentioned on line 3341, but not defined == Missing Reference: 'CREF16' is mentioned on line 3343, but not defined == Missing Reference: 'TBD' is mentioned on line 1155, but not defined == Missing Reference: 'CREF17' is mentioned on line 3350, but not defined == Missing Reference: 'CREF18' is mentioned on line 3357, but not defined == Missing Reference: 'CREF19' is mentioned on line 3361, but not defined == Missing Reference: 'CREF20' is mentioned on line 3365, but not defined == Missing Reference: 'CREF21' is mentioned on line 3370, but not defined == Missing Reference: 'CREF22' is mentioned on line 3372, but not defined == Missing Reference: 'CREF23' is mentioned on line 3374, but not defined == Missing Reference: 'CREF24' is mentioned on line 3385, but not defined == Missing Reference: 'CREF25' is mentioned on line 3390, but not defined == Missing Reference: 'CREF26' is mentioned on line 3393, but not defined == Missing Reference: 'CREF27' is mentioned on line 3396, but not defined == Missing Reference: 'CREF28' is mentioned on line 3399, but not defined == Missing Reference: 'CREF29' is mentioned on line 3402, but not defined == Missing Reference: 'CREF30' is mentioned on line 3404, but not defined == Missing Reference: 'CREF31' is mentioned on line 3406, but not defined == Missing Reference: 'CREF32' is mentioned on line 3409, but not defined ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-11) exists of draft-greevenbosch-appsawg-cbor-cddl-05 == Outdated reference: A later version (-11) exists of draft-irtf-cfrg-curves-02 -- Obsolete informational reference (is this intentional?): RFC 2633 (Obsoleted by RFC 3851) -- 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) Summary: 2 errors (**), 0 flaws (~~), 42 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 COSE Working Group J. Schaad 3 Internet-Draft August Cellars 4 Intended status: Informational July 20, 2015 5 Expires: January 21, 2016 7 CBOR Encoded Message Syntax 8 draft-ietf-cose-msg-02 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 how to do signatures, message 16 authentication codes and encryption using this data format. 18 Contributing to this document 20 The source for this draft is being maintained in GitHub. Suggested 21 changes should be submitted as pull requests at [1]. Instructions 22 are on that page as well. Editorial changes can be managed in 23 GitHub, but any substantial issues need to be discussed on the COSE 24 mailing list. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on January 21, 2016. 43 Copyright Notice 45 Copyright (c) 2015 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 61 1.1. Design changes from JOSE . . . . . . . . . . . . . . . . 4 62 1.2. Requirements Terminology . . . . . . . . . . . . . . . . 5 63 1.3. CBOR Grammar . . . . . . . . . . . . . . . . . . . . . . 5 64 1.4. CBOR Related Terminology . . . . . . . . . . . . . . . . 6 65 1.5. Document Terminology . . . . . . . . . . . . . . . . . . 6 66 1.6. Mandatory to Implement Algorithms . . . . . . . . . . . . 6 67 2. The COSE_MSG structure . . . . . . . . . . . . . . . . . . . 7 68 3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 10 69 3.1. COSE Headers . . . . . . . . . . . . . . . . . . . . . . 11 70 4. Signing Structure . . . . . . . . . . . . . . . . . . . . . . 14 71 5. Encryption object . . . . . . . . . . . . . . . . . . . . . . 17 72 5.1. Key Management Methods . . . . . . . . . . . . . . . . . 18 73 5.2. Encryption Algorithm for AEAD algorithms . . . . . . . . 19 74 5.3. Encryption algorithm for AE algorithms . . . . . . . . . 20 75 6. MAC objects . . . . . . . . . . . . . . . . . . . . . . . . . 21 76 7. Key Structure . . . . . . . . . . . . . . . . . . . . . . . . 22 77 7.1. COSE Key Map Labels . . . . . . . . . . . . . . . . . . . 23 78 8. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 26 79 8.1. ECDSA . . . . . . . . . . . . . . . . . . . . . . . . . . 27 80 8.1.1. Security Considerations . . . . . . . . . . . . . . . 28 81 8.2. RSASSA-PSS . . . . . . . . . . . . . . . . . . . . . . . 28 82 8.2.1. Security Considerations . . . . . . . . . . . . . . . 29 83 9. Message Authentication (MAC) Algorithms . . . . . . . . . . . 29 84 9.1. Hash-based Message Authentication Codes (HMAC) . . . . . 29 85 9.1.1. Security Considerations . . . . . . . . . . . . . . . 30 86 9.2. AES Message Authentication Code (AES-MAC) . . . . . . . . 30 87 10. Content Encryption Algorithms . . . . . . . . . . . . . . . . 30 88 10.1. AES GCM . . . . . . . . . . . . . . . . . . . . . . . . 30 89 10.2. AES CCM . . . . . . . . . . . . . . . . . . . . . . . . 31 90 10.2.1. Security Considerations . . . . . . . . . . . . . . 33 91 11. Key Derivation Functions (KDF) . . . . . . . . . . . . . . . 34 92 11.1. HMAC-based Extract-and-Expand Key Derivation Function 93 (HKDF) . . . . . . . . . . . . . . . . . . . . . . . . . 34 94 11.2. Context Information Structure . . . . . . . . . . . . . 35 95 12. Key Management Algorithms . . . . . . . . . . . . . . . . . . 38 96 12.1. Direct Encryption . . . . . . . . . . . . . . . . . . . 39 97 12.1.1. Direct Key . . . . . . . . . . . . . . . . . . . . . 39 98 12.2. Key Wrapping . . . . . . . . . . . . . . . . . . . . . . 40 99 12.2.1. AES Key Wrapping . . . . . . . . . . . . . . . . . . 40 100 12.3. Key Encryption . . . . . . . . . . . . . . . . . . . . . 41 101 12.3.1. RSA OAEP . . . . . . . . . . . . . . . . . . . . . . 41 102 12.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 42 103 12.4.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 43 104 12.5. Key Agreement with KDF . . . . . . . . . . . . . . . . . 46 105 12.5.1. ECDH ES + HKDF . . . . . . . . . . . . . . . . . . . 46 106 12.6. Password . . . . . . . . . . . . . . . . . . . . . . . . 47 107 12.6.1. PBES2 . . . . . . . . . . . . . . . . . . . . . . . 47 108 13. Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 109 13.1. Elliptic Curve Keys . . . . . . . . . . . . . . . . . . 48 110 13.1.1. Single Coordinate Curves . . . . . . . . . . . . . . 48 111 13.1.2. Double Coordinate Curves . . . . . . . . . . . . . . 49 112 13.2. RSA Keys . . . . . . . . . . . . . . . . . . . . . . . . 50 113 13.3. Symmetric Keys . . . . . . . . . . . . . . . . . . . . . 51 114 14. CBOR Encoder Restrictions . . . . . . . . . . . . . . . . . . 52 115 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 52 116 15.1. CBOR Tag assignment . . . . . . . . . . . . . . . . . . 52 117 15.2. COSE Object Labels Registry . . . . . . . . . . . . . . 52 118 15.3. COSE Header Label Table . . . . . . . . . . . . . . . . 53 119 15.4. COSE Header Algorithm Label Table . . . . . . . . . . . 53 120 15.5. COSE Algorithm Registry . . . . . . . . . . . . . . . . 54 121 15.6. COSE Key Map Registry . . . . . . . . . . . . . . . . . 55 122 15.7. COSE Key Parameter Registry . . . . . . . . . . . . . . 56 123 15.8. Media Type Registration . . . . . . . . . . . . . . . . 56 124 15.8.1. COSE Security Message . . . . . . . . . . . . . . . 56 125 15.8.2. COSE Key media type . . . . . . . . . . . . . . . . 58 126 16. Security Considerations . . . . . . . . . . . . . . . . . . . 60 127 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 60 128 17.1. Normative References . . . . . . . . . . . . . . . . . . 60 129 17.2. Informative References . . . . . . . . . . . . . . . . . 61 130 Appendix A. AEAD and AE algorithms . . . . . . . . . . . . . . . 63 131 Appendix B. Three Levels of Recipient Information . . . . . . . 64 132 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 65 133 C.1. Examples of MAC messages . . . . . . . . . . . . . . . . 66 134 C.1.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 66 135 C.1.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 66 136 C.1.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 67 137 C.1.4. Multi-recipient MAC message . . . . . . . . . . . . . 68 138 C.2. Examples of Encrypted Messages . . . . . . . . . . . . . 69 139 C.2.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 69 140 C.2.2. Direct plus Key Derivation . . . . . . . . . . . . . 70 141 C.3. Examples of Signed Message . . . . . . . . . . . . . . . 71 142 C.3.1. Single Signature . . . . . . . . . . . . . . . . . . 71 143 C.3.2. Multiple Signers . . . . . . . . . . . . . . . . . . 72 145 Appendix D. COSE Header Algorithm Label Table . . . . . . . . . 72 146 Appendix E. Document Updates . . . . . . . . . . . . . . . . . . 73 147 E.1. Version -01 to -02 . . . . . . . . . . . . . . . . . . . 73 148 E.2. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 73 149 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 76 151 1. Introduction 153 There has been an increased focus on the small, constrained devices 154 that make up the Internet of Things (IOT). One of the standards that 155 has come of of this process is the Concise Binary Object 156 Representation (CBOR). CBOR extended the data model of the 157 JavaScript Object Notation (JSON) by allowing for binary data among 158 other changes. CBOR is being adopted by several of the IETF working 159 groups dealing with the IOT world as their encoding of data 160 structures. CBOR was designed specifically to be both small in terms 161 of messages transport and implementation size as well having a schema 162 free decoder. A need exists to provide basic message security 163 services for IOT and using CBOR as the message encoding format makes 164 sense. 166 The JOSE working group produced a set of documents 167 [RFC7515][RFC7516][RFC7517][RFC7518] that defined how to perform 168 encryption, signatures and message authentication (MAC) operations 169 for JavaScript Object Notation (JSON) documents and then to encode 170 the results using the JSON format [RFC7159]. This document does the 171 same work for use with the Concise Binary Object Representation 172 (CBOR) [RFC7049] document format. While there is a strong attempt to 173 keep the flavor of the original JOSE documents, two considerations 174 are taken into account: 176 o CBOR has capabilities that are not present in JSON and should be 177 used. One example of this is the fact that CBOR has a method of 178 encoding binary directly without first converting it into a base64 179 encoded string. 181 o The author did not always agree with some of the decisions made by 182 the JOSE working group. Many of these decisions have been re- 183 examined, and where it seems to the author to be superior or 184 simpler, replaced. 186 1.1. Design changes from JOSE 188 o Define a top level message structure so that encrypted, signed and 189 MACed messages can easily identified and still have a consistent 190 view. 192 o Signed messages separate the concept of protected and unprotected 193 attributes that are for the content and the signature. 195 o Key management has been made to be more uniform. All key 196 management techniques are represented as a recipient rather than 197 only have some of them be so. 199 o MAC messages are separated from signed messages. 201 o MAC messages have the ability to do key management on the MAC 202 authentication key. 204 o Use binary encodings for binary data rather than base64url 205 encodings. 207 o Combine the authentication tag for encryption algorithms with the 208 ciphertext. 210 o Remove the flattened mode of encoding. Forcing the use of an 211 array of recipients at all times forces the message size to be two 212 bytes larger, but one gets a corresponding decrease in the 213 implementation size that should compensate for this. [CREF1] 215 1.2. Requirements Terminology 217 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 218 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 219 "OPTIONAL" in this document are to be interpreted as described in 220 [RFC2119]. 222 When the words appear in lower case, their natural language meaning 223 is used. 225 1.3. CBOR Grammar 227 There currently is no standard CBOR grammar available for use by 228 specifications. While we describe the CBOR structures in prose, they 229 are agumented in the text by the use of the CBOR Data Definition 230 Language (CDDL) [I-D.greevenbosch-appsawg-cbor-cddl]. The use of 231 CDDL is intended to be explanitory. In the event of a conflict 232 between the text and the CDDL grammar, the text is authorative. 233 (Problems may be introduced at a later point because the CDDL grammar 234 is not yet fixed.) 236 CDDL productions that together define the grammar are interspersed in 237 the document like this: 239 start = COSE_MSG 241 The collected CDDL can be extracted from the XML version of this 242 document via the following XPath expression below. (Depending on the 243 XPath evaluator one is using, it may be necessary to deal with > 244 as an entity.) 246 //artwork[@type='CDDL']/text() 248 1.4. CBOR Related Terminology 250 In JSON, maps are called objects and only have one kind of map key: a 251 string. In COSE, we use both strings and integers (both negative and 252 non-negative integers) as map keys, as well as data items to identify 253 specific choices. The integers (both positive and negative) are used 254 for compactness of encoding and easy comparison. (Generally, in this 255 document the value zero is going to be reserved and not used.) Since 256 the work "key" is mainly used in its other meaning, as a 257 cryptographic key, we use the term "label" for this usage of either 258 an integer or a string to identify map keys and choice data items. 260 The CDLL grammar that defines a type that represents a label is given 261 below: 263 label = int / tstr 265 1.5. Document Terminology 267 In this document we use the following terminology: [CREF2] 269 Byte is a synonym for octet. 271 Key management is used as a term to describe how a key at level n is 272 obtained from level n+1 in encrypted and MACed messages. The term is 273 also used to discuss key life cycle management, this document does 274 not discuss key life cycle operations. 276 1.6. Mandatory to Implement Algorithms 278 One of the issues that needs to be addressed is a requirement that a 279 standard specify a set of algorithms that are required to be 280 implemented. [CREF3] This is done to promote interoperability as it 281 provides a minimal set of algorithms that all devices can be sure 282 will exist at both ends. However, we have elected not to specify a 283 set of mandatory algorithms in this document. 285 It is expected that COSE is going to be used in a wide variety of 286 applications and on a wide variety of devices. Many of the 287 constrained devices are going to be setup to used a small fixed set 288 of algorithms, and this set of algorithms may not match those 289 available on a device. We therefore have deferred to the application 290 protocols the decision of what to specify for mandatory algorithms. 292 Since the set of algorithms in an environment of constrained devices 293 may depend on what the set of devices are and how long they have been 294 in operation, we want to highlight that application protocols will 295 need to specify some type of discovery method of algorithm 296 capabilities. The discovery method may be as simple as requiring 297 preconfiguration of the set of algorithms to providing a discovery 298 method built into the protocol. S/MIME provided a number of 299 different ways to approach the problem: 301 o Advertising in the message (S/MIME capabilities) [RFC5751]. 303 o Advertising in the certificate (capabilities extension) [RFC4262] 305 o Minimum requirements for the S/MIME which have been updated over 306 time [RFC2633][RFC5751] 308 2. The COSE_MSG structure 310 The COSE_MSG structure is a top level CBOR object that corresponds to 311 the DataContent type in the Cryptographic Message Syntax (CMS) 312 [RFC5652]. This structure allows for a top level message to be sent 313 that could be any of the different security services. The security 314 service is identified within the message. 316 The COSE_Tagged_MSG CBOR type takes the COSE_MSG and prepends a CBOR 317 tag of TBD1 to the encoding of COSE_MSG. By having both a tagged and 318 untagged version of the COSE_MSG structure, it becomes easy to either 319 use COSE_MSG as a top level object or embedded in another object. 320 The tagged version allows for a method of placing the COSE_MSG 321 structure into a choice, using a consistent tag value to determine 322 that this is a COSE object. 324 The existence of the COSE_MSG and COSE_Tagged_MSG CBOR data types are 325 not intended to prevent protocols from using the individual security 326 primitives directly. Where only a single service is required, that 327 structure can be used directly. 329 Each of the top-level security objects use a CBOR map as the base 330 structure. Items in the map at the top level are identified by a 331 label. The type of the value associated with the label is determined 332 by the definition of the label. 334 The set of labels present in a security object is not restricted to 335 those defined in this document. However, it is not recommended that 336 additional fields be added to a structure unless this is going to be 337 done in a closed environment. When new fields need to be added, it 338 is recommended that a new message type be created so that processing 339 of the field can be ensured. Using an older structure with a new 340 field means that any security properties of the new field will not be 341 enforced. Before a new field is added at the outer level, strong 342 consideration needs to be given to defining a new header field and 343 placing it into the protected headers. Applications should make a 344 determination if non-standardized fields are going to be permitted. 345 It is suggested that libraries allow for an option to fail parsing if 346 non-standardized fields exist, this is especially true if they do not 347 allow for access to the fields in other ways. 349 A label 'msg_type' is defined to distinguish between the different 350 structures when they appear as part of a COSE_MSG object. [CREF4] 351 [CREF5] 353 0 - Reserved. 355 1 - Signed Message. 357 2 - Encrypted Message 359 3 - Authenticated Message (MACed message) 361 Implementations MUST be prepared to find an integer under this label 362 that does not correspond to the values 1 to 3. If this is found then 363 the client MUST stop attempting to parse the structure and fail. The 364 value of 0 is reserved and not to be used. If the value of 0 is 365 found, then clients MUST fail processing the structure. 366 Implementations need to recognize that the set of values might be 367 extended at a later date, but they should not provide a security 368 service based on guesses of what is there. 370 NOTE: Is there any reason to allow for a marker of a COSE_Key 371 structure and allow it to be a COSE_MSG? Doing so does allow for a 372 security risk, but may simplify the code. [CREF6] 374 The CDDL grammar that corresponds to the above is: 376 COSE_MSG = COSE_Sign / 377 COSE_encrypt / 378 COSE_mac 380 COSE_Tagged_MSG = #6.999(COSE_MSG) ; Replace 999 with TBD1 382 ; msg_type values 383 msg_type_reserved=0 384 msg_type_signed=1 385 msg_type_encrypted=2 386 msg_type_mac=3 388 The top level of each of the COSE message structures are encoded as 389 maps. We use an integer to distinguish between the different 390 security message types. By searching for the integer under the label 391 identified by msg_type (which is in turn an integer), one can 392 determine which security message is being used and thus what syntax 393 is for the rest of the elements in the map. 395 +-------------+--------+--------------------------------------------+ 396 | name | number | comments | 397 +-------------+--------+--------------------------------------------+ 398 | msg_type | 1 | Occurs only in top level messages | 399 | | | | 400 | protected | 2 | Occurs in all structures | 401 | | | | 402 | unprotected | 3 | Occurs in all structures | 403 | | | | 404 | payload | 4 | Contains the content of the structure | 405 | | | | 406 | signatures | 5 | For COSE_Sign - array of signatures | 407 | | | | 408 | signature | 6 | For COSE_signature only | 409 | | | | 410 | ciphertext | 4 | TODO: Should we reuse the same as payload | 411 | | | or not? | 412 | | | | 413 | recipients | 9 | For COSE_encrypt and COSE_mac | 414 | | | | 415 | tag | 10 | For COSE_mac only | 416 +-------------+--------+--------------------------------------------+ 418 Table 1: COSE Map Labels 420 The CDDL grammar that provides the label values is: 422 ; message_labels 423 msg_type=1 424 protected=2 425 unprotected=3 426 payload=4 427 signatures=5 428 signature=6 429 ciphertext=4 430 recipients=9 431 tag=10 433 3. Header Parameters 435 The structure of COSE has been designed to have two buckets of 436 information that are not considered to be part of the payload itself, 437 but are used for holding information about algorithms, keys, or 438 evaluation hints for the processing of the layer. These two buckets 439 are available for use in all of the structures in this document 440 except for keys. While these buckets can be present, they may not 441 all be usable in all instances. For example, while the protected 442 bucket is present for recipient structures, most of the algorithms 443 that are used for recipients do not provide the necessary 444 functionality to provide the needed protection and thus the element 445 is not used. 447 Both buckets are implemented as CBOR maps. The map key is a 'label' 448 (Section 1.4). The value portion is dependent on the definition for 449 the label. Both maps use the same set of label/value pairs. The 450 integer range for labels has been divided into several sections with 451 a standard range, a private range, and a range that is dependent on 452 the algorithm selected. The defined labels can be found in the 'COSE 453 Header Labels' IANA registry (Section 15.3. 455 Two buckets are provided for each layer: [CREF7] 457 protected contains attributes about the layer that are to be 458 cryptographically protected. This bucket MUST NOT be used if it 459 is not going to be included in a cryptographic computation. This 460 bucket is encoded in the message as a binary object. This value 461 is obtained by CBOR encoding the protected map and wrapping it in 462 a bstr object. This wrapping allows for the encoding of the 463 protected map to be transported with a greater chance that it will 464 not be altered in transit. (Badly behaved intermediates could 465 decode and re-encode, but this will result in a failure to verify 466 unless the re-encoded byte string is identical to the decoded byte 467 string.) This finesses the problem of all parties needing to be 468 able to do a common connical encoding. 470 unprotected contains attributes about the layer that are not 471 cryptographically protected. 473 Both of the buckets are optional and are omitted if there are no 474 items contained in the map. The CDDL fragment that describes the two 475 buckets is: 477 header_map = {+ label => any } 479 Headers = ( 480 ? protected => bstr, 481 ? unprotected => header_map 482 ) 484 3.1. COSE Headers 486 The set of header fields defined in this document are: 488 alg This field is used to indicate the algorithm used for the 489 security processing. This field MUST be present at each level of 490 a signed, encrypted or authenticated message. This field using 491 the integer '1' for the label. The value is taken from the 'COSE 492 Algorithm Registry' (see Section 15.4). 494 crit This field is used to ensure that applications will take 495 appropriate action based on the values found. The field is used 496 to indicate which protected header labels an application that is 497 processing a message is required to understand. This field uses 498 the integer '2' for the label. The value is an array of COSE 499 Header Labels. When present, this MUST be placed in the protected 500 header bucket. 502 * Integer labels in the range of 0 to 10 SHOULD be omitted. 504 * Integer labels in the range -1 to -255 can be omitted as they 505 are algorithm dependent. If an application can correctly 506 process an algorithm, it can be assumed that it will correctly 507 process all of the parameters associated with that algorithm. 508 (The algorithm range is -1 to -65536, it is assumed that the 509 higher end will deal with more optional algorithm specific 510 items.) 512 The header values indicated by 'crit' can be processed by either 513 the security library code or by an application using a security 514 library, the only requirement is that the field is processed. 516 cty This field is used to indicate the content type of the data in 517 the payload or ciphertext fields. The field uses the integer of 518 '3' for the label. The value can be either an integer or a 519 string. [CREF8] Integers are from the XXXXX[CREF9] IANA registry 520 table. Strings are from the IANA 'mime-content types' registry. 521 Applications SHOULD provide this field if the content structure is 522 potentially ambiguous. 524 kid This field one of the ways that can be used to find the key to 525 be used. This value can be matched against the 'kid' field in a 526 COSE_Key structure. Applications MUST NOT assume that 'kid' 527 values are unique. There may be more than one key with the same 528 'kid' value, it may be required that all of the keys need to be 529 checked to find the correct one. This field uses the integer 530 value of '4' for the label. The value of field is the CBOR 'bstr' 531 type. The internal structure of 'kid' is not defined and 532 generally cannot be relied on by applications. Key identifier 533 values are hints about which key to use, they are not directly a 534 security critical field, for this reason they can normally be 535 placed in the unprotected headers bucket. 537 nonce This field holds either a nonce or Initialization Vector 538 value. This value can be used either as a counter value for a 539 protocol or as an IV for an algorithm. TODO: Talk about zero 540 extending the value in some cases. [CREF10] 542 This table contains a list of all of the generic header parameters 543 defined in document. In the table is the data value type to be used 544 for CBOR as well as the integer value that can be used as a 545 replacement for the name in order to further decrease the size of the 546 sent item. 548 +----------+-------+----------+-------------+-----------------------+ 549 | name | label | value | registry | description | 550 +----------+-------+----------+-------------+-----------------------+ 551 | alg | 1 | int / | COSE | Integers are taken | 552 | | | tstr | Algorithm | from table --POINT TO | 553 | | | | Registry | REGISTRY-- | 554 | | | | | | 555 | crit | 2 | [+ | COSE Header | integer values are | 556 | | | label] | Label | from -- POINT TO | 557 | | | | Registry | REGISTRY -- | 558 | | | | | | 559 | cty | 3 | tstr / | media-types | Value is either a | 560 | | | int | registry | media-type or an | 561 | | | | | integer from the | 562 | | | | | media-type registry | 563 | | | | | | 564 | jku | * | tstr | | URL to COSE key | 565 | | | | | object | 566 | | | | | | 567 | jwk | * | COSE_Key | | contains a COSE key | 568 | | | | | not a JWK key | 569 | | | | | | 570 | kid | 4 | bstr | | key identifier | 571 | | | | | | 572 | nonce | 5 | bstr | | Nonce or | 573 | | | | | Initialization Vector | 574 | | | | | (IV) | 575 | | | | | | 576 | x5c | * | bstr* | | X.509 Certificate | 577 | | | | | Chain | 578 | | | | | | 579 | x5t | * | bstr | | SHA-1 thumbprint of | 580 | | | | | key | 581 | | | | | | 582 | x5t#S256 | * | bstr | | SHA-256 thumbprint of | 583 | | | | | key | 584 | | | | | | 585 | x5u | * | tstr | | URL for X.509 | 586 | | | | | certificate | 587 | | | | | | 588 | zip | * | int / | | Integers are taken | 589 | | | tstr | | from the table | 590 | | | | | --POINT TO REGISTRY-- | 591 +----------+-------+----------+-------------+-----------------------+ 593 Table 2: Header Labels 595 OPEN ISSUES: 597 1. Which of the following items do we want to have standardized in 598 this document: jku, jwk, x5c, x5t, x5t#S256, x5u, zip 600 2. I am currently torn on the question "Should epk and iv/nonce be 601 algorithm specific or generic headers?" They are really specific 602 to an algorithm and can potentially be defined in different ways 603 for different algorithms. As an example, it would make sense to 604 defined nonce for CCM and GCM modes that can have the leading 605 zero bytes stripped, while for other algorithms this might be 606 undesirable. 608 3. We might want to define some additional items. What are they? A 609 possible example would be a sequence number as this might be 610 common. On the other hand, this is the type of things that is 611 frequently used as the nonce in some places and thus should not 612 be used in the same way. Other items might be challenge/response 613 fields for freshness as these are likely to be common. 615 4. Signing Structure 617 The signature structure allows for one or more signatures to be 618 applied to a message payload. There are provisions for attributes 619 about the content and attributes about the signature to be carried 620 along with the signature itself. These attributes may be 621 authenticated by the signature, or just present. Examples of 622 attributes about the content would be the type of content, when the 623 content was created, and who created the content. Examples of 624 attributes about the signature would be the algorithm and key used to 625 create the signature, when the signature was created, and counter- 626 signatures. 628 When more than one signature is present, the successful validation of 629 one signature associated with a given signer is usually treated as a 630 successful signature by that signer. However, there are some 631 application environments where other rules are needed. An 632 application that employs a rule other than one valid signature for 633 each signer must specify those rules. Also, where simple matching of 634 the signer identifier is not sufficient to determine whether the 635 signatures were generated by the same signer, the application 636 specification must describe how to determine which signatures were 637 generated by the same signer. Support of different communities of 638 recipients is the primary reason that signers choose to include more 639 than one signature. For example, the COSE_Sign structure might 640 include signatures generated with the RSA signature algorithm and 641 with the Elliptic Curve Digital Signature Algorithm (ECDSA) signature 642 algorithm. This allows recipients to verify the signature associated 643 with one algorithm or the other. (The original source of this text 644 is [RFC5652].) More detailed information on multiple signature 645 evaluation can be found in [RFC5752]. 647 The CDDL grammar for a signature message is: 649 COSE_Sign = { 650 msg_type => msg_type_signed, 651 Headers, 652 ? payload => bstr, 653 signatures => [+ COSE_signature] 654 } 656 The fields is the structure have the following semantics: 658 msg_type identifies this as providing the signed security service. 659 The value MUST be msg_type_signed (1). 661 protected contains attributes about the payload that are to be 662 protected by the signature. An example of such an attribute would 663 be the content type ('cty') attribute. The content is a CBOR map 664 of attributes that is encoded to a byte stream. This field MUST 665 NOT contain attributes about the signature, even if those 666 attributes are common across multiple signatures. The labels in 667 this map are typically taken from Table 2. [CREF11] 669 unprotected contains attributes about the payload that are not 670 protected by the signature. An example of such an attribute would 671 be the content type ('cty') attribute. This field MUST NOT 672 contain attributes about a signature, even if the attributes are 673 common across multiple signatures. The labels in this map are 674 typically taken from Table 2. [CREF12] 676 payload contains the serialized content to be signed. If the 677 payload is not present in the message, the application is required 678 to supply the payload separately. The payload is wrapped in a 679 bstr to ensure that it is transported without changes. If the 680 payload is transported separately, it is the responsibility of the 681 application to ensure that it will be transported without changes. 683 signatures is an array of signature items. Each of these items uses 684 the COSE_signature structure for its representation. 686 We use the values in Table 1 as the labels in the COSE_Sign map. 687 While other labels can be present in the map, it is not generally a 688 recommended practice. The other labels can be either of integer or 689 string type, use of other types SHOULD be treated as an error. 691 The CDDL grammar structure for a signature is: 693 COSE_signature = { 694 Headers, 695 signature => bstr 696 } 698 The fields in the structure have the following semantics: 700 protected contains additional information to be authenticated by the 701 signature. The field holds data about the signature operation. 702 The field MUST NOT hold attributes about the payload being signed. 703 The content is a CBOR map of attributes that is encoded to a byte 704 stream. At least one of protected and unprotected MUST be 705 present. 707 unprotected contains attributes about the signature that are not 708 protected by the signature. This field MUST NOT contain 709 attributes about the payload being signed. At least one of 710 protected and unprotected MUST be present. 712 signature contains the computed signature value. 714 The COSE structure used to create the byte stream to be signed uses 715 the following CDDL grammar structure: 717 Sig_structure = [ 718 body_protected: bstr, 719 sign_protected: bstr, 720 payload: bstr 721 ] 723 How to compute a signature: 725 1. Create a Sig_structure object and populate it with the 726 appropriate fields. For body_protected and sign_protected, if 727 the fields are not present in their corresponding maps, an bstr 728 of length zero is used. 730 2. Create the value ToBeSigned by encoding the Sig_structure to a 731 byte string. 733 3. Call the signature creation algorithm passing in K (the key to 734 sign with), alg (the algorithm to sign with) and ToBeSigned (the 735 value to sign). 737 4. Place the resulting signature value in the 'signature' field of 738 the map. 740 How to verify a signature: 742 1. Create a Sig_structure object and populate it with the 743 appropriate fields. For body_protected and sign_protected, if 744 the fields are not present in their corresponding maps, an bstr 745 of length zero is used. 747 2. Create the value ToBeSigned by encoding the Sig_structure to a 748 byte string. 750 3. Call the signature verification algorithm passing in K (the key 751 to verify with), alg (the algorithm to sign with), ToBeSigned 752 (the value to sign), and sig (the signature to be verified). 754 In addition to performing the signature verification, one must also 755 perform the appropriate checks to ensure that the key is correctly 756 paired with the signing identity and that the appropriate 757 authorization is done. 759 5. Encryption object 761 In this section we describe the structure and methods to be used when 762 doing an encryption in COSE. In COSE, we use the same techniques and 763 structures for encrypting both the plain text and the keys used to 764 protect the text. This is different from the approach used by both 765 [RFC5652] and [RFC7516] where different structures are used for the 766 plain text and for the different key management techniques. 768 One of the byproducts of using the same technique for encrypting and 769 encoding both the content and the keys using the various key 770 management techniques, is a requirement that all of the key 771 management techniques use an Authenticated Encryption (AE) algorithm. 772 (For the purpose of this document we use a slightly loose definition 773 of AE algorithms.) When encrypting the plain text, it is normal to 774 use an Authenticated Encryption with Additional Data (AEAD) 775 algorithm. For key management, either AE or AEAD algorithms can be 776 used. See Appendix A for more details about the different types of 777 algorithms. [CREF13] 779 The CDDL grammar structure for encryption is: 781 COSE_encrypt = { 782 msg_type=>msg_type_encrypted, 783 COSE_encrypt_fields 784 } 786 COSE_encrypt_fields = ( 787 Headers, 788 ? ciphertext => bstr, 789 ? recipients => [+{COSE_encrypt_fields}] 790 ) 792 Description of the fields: 794 msg_type identifies this as providing the encrypted security 795 service. The value MUST be msg_type_encrypted (2). 797 protected contains the information about the plain text or 798 encryption process that is to be integrity protected. The field 799 is encoded in CBOR as a 'bstr'. The contents of the protected 800 field is a CBOR map of the protected data names and values. The 801 map is CBOR encoded before placing it into the bstr. Only values 802 associated with the current cipher text are to be placed in this 803 location even if the value would apply to multiple recipient 804 structures. 806 unprotected contains information about the plain text that is not 807 integrity protected. Only values associated with the current 808 cipher text are to be placed in this location even if the value 809 would apply to multiple recipient structures. 811 ciphertext contains the encrypted plain text. If the ciphertext is 812 to be transported independently of the control information about 813 the encryption process (i.e. detached content) then the field is 814 omitted. 816 recipients contains the recipient information. It is required that 817 at least one recipient MUST be present for the content encryption 818 layer. 820 5.1. Key Management Methods 822 A typical encrypted message consists of an encrypted content and an 823 encrypted CEK for one or more recipients. The content-encryption key 824 is encrypted for each recipient. The details of this encryption 825 depends on the key management technique used, but the six generally 826 techniques are: 828 none: The CEK is the same as as the identified previously 829 distributed symmetric key. 831 symmetric key-encryption keys: The CEK is encrypted using a 832 previously distributed symmetric key-encryption key. 834 key agreement: the recipient's public key and a sender's private key 835 are used to generate a pairwise symmetric key, then the CEK is 836 either the derived key or encrypted by the derived key. 838 key transport: the CEK is encrypted in the recipient's public key 840 passwords: the CEK is encrypted in a key-encryption key that is 841 derived from a password or other shared secret value. 843 Section 12 provides details on a number of different key management 844 algorithms and discusses which elements need to be present for each 845 of the key management techniques. 847 5.2. Encryption Algorithm for AEAD algorithms 849 The encryption algorithm for AEAD algorithms is fairly simple. In 850 order to get a consistent encoding of the data to be authenticated, 851 the Enc_structure is used to have canonical form of the AAD. 853 Enc_structure = [ 854 protected: bstr, 855 external_aad: bstr 856 ] 858 1. Copy the protected header field from the message to be sent. 860 2. If the application has supplied external additional authenticated 861 data to be included in the computation, then it is placed in the 862 'external_aad' field. If no data was supplied, then a zero 863 length binary value is used. 865 3. Encode the Enc_structure using a CBOR Canonical encoding 866 Section 14 to get the AAD value. 868 4. Determine the encryption key. This step is dependent on the key 869 management method being used: For: 871 No Recipients: The key to be used is determined by the algorithm 872 and key at the current level. 874 Direct and Direct Key Agreement: The key is determined by the 875 key and algorithm in the recipient structure. The encryption 876 algorithm and size of the key to be used are inputs into the 877 KDF used for the recipient. (For direct, the KDF can be 878 thought of as the identity operation.) 880 Other: The key is randomly generated. 882 5. Call the encryption algorithm with K (the encryption key to use), 883 P (the plain text) and AAD (the additional authenticated data). 884 Place the returned cipher text into the 'ciphertext' field of the 885 structure. 887 6. For recipients of the message, recursively perform the encryption 888 algorithm for that recipient using the encryption key as the 889 plain text. 891 5.3. Encryption algorithm for AE algorithms 893 1. Verify that the 'protected' field is absent. 895 2. Verify that there was no external additional authenticated data 896 supplied for this operation. 898 3. Determine the encryption key. This step is dependent on the key 899 management method being used: For: 901 No Recipients: The key to be used is determined by the algorithm 902 and key at the current level. 904 Direct and Direct Key Agreement: The key is determined by the 905 key and algorithm in the recipient structure. The encryption 906 algorithm and size of the key to be used are inputs into the 907 KDF used for the recipient. (For direct, the KDF can be 908 thought of as the identity operation.) 910 Other: The key is randomly generated. 912 4. Call the encryption algorithm with K (the encryption key to use) 913 and the P (the plain text). Place the returned cipher text into 914 the 'ciphertext' field of the structure. 916 5. For recipients of the message, recursively perform the encryption 917 algorithm for that recipient using the encryption key as the 918 plain text. 920 6. MAC objects 922 In this section we describe the structure and methods to be used when 923 doing MAC authentication in COSE. JOSE used a variant of the 924 signature structure for doing MAC operations and it is restricted to 925 using a single pre-shared secret to do the authentication. [CREF14] 926 This document allows for the use of all of the same methods of key 927 management as are allowed for encryption. 929 When using MAC operations, there are two modes in which it can be 930 used. The first is just a check that the content has not been 931 changed since the MAC was computed. Any of the key management 932 methods can be used for this purpose. The second mode is to both 933 check that the content has not been changed since the MAC was 934 computed, and to use key management to verify who sent it. The key 935 management modes that support this are ones that either use a pre- 936 shared secret, or do static-static key agreement. In both of these 937 cases the entity MACing the message can be validated by a key 938 binding. (The binding of identity assumes that there are only two 939 parties involved and you did not send the message yourself.) 941 COSE_mac = { 942 msg_type=>msg_type_mac, 943 Headers, 944 ? payload => bstr, 945 tag => bstr, 946 recipients => [+{COSE_encrypt_fields}] 947 } 949 Field descriptions: 951 msg_type identifies this as providing the encrypted security 952 service. The value MUST be msg_type_mac (3). 954 protected contains attributes about the payload that are to be 955 protected by the MAC. An example of such an attribute would be 956 the content type ('cty') attribute. The content is a CBOR map of 957 attributes that is encoded to a byte stream. This field MUST NOT 958 contain attributes about the recipient, even if those attributes 959 are common across multiple recipients. At least one of protected 960 and unprotected MUST be present. 962 unprotected contains attributes about the payload that are not 963 protected by the MAC. An example of such an attribute would be 964 the content type ('cty') attribute. This field MUST NOT contain 965 attributes about a recipient, even if the attributes are common 966 across multiple recipients. At least one of protected and 967 unprotected MUST be present. 969 payload contains the serialized content to be MACed. If the payload 970 is not present in the message, the application is required to 971 supply the payload separately. The payload is wrapped in a bstr 972 to ensure that it is transported without changes, if the payload 973 is transported separately it is the responsibility of the 974 application to ensure that it will be transported without changes. 976 tag contains the MAC value. 978 recipients contains the recipient information. See the description 979 under COSE_Encryption for more info. 981 MAC_structure = [ 982 protected: bstr, 983 external_aad: bstr, 984 payload: bstr 985 ] 987 How to compute a MAC: 989 1. Create a MAC_structure and copy the protected and payload 990 elements from the COSE_mac structure. 992 2. If the application has supplied external authenticated data, 993 encode it as a binary value and place in the MAC_structure. If 994 there is no external authenticated data, then use a zero length 995 'bstr'. 997 3. Encode the MAC_structure using a canonical CBOR encoder. The 998 resulting bytes is the value to compute the MAC on. 1000 4. Compute the MAC and place the result in the 'tag' field of the 1001 COSE_mac structure. 1003 5. Encrypt and encode the MAC key for each recipient of the message. 1005 7. Key Structure 1007 There are only a few changes between JOSE and COSE for how keys are 1008 formatted. As with JOSE, COSE uses a map to contain the elements of 1009 a key. Those values, which in JOSE are base64url encoded because 1010 they are binary values, are encoded as bstr values in COSE. 1012 For COSE we use the same set of fields that were defined in 1013 [RFC7517]. [CREF15] [CREF16] 1014 COSE_Key = { 1015 kty => tstr / int, 1016 ? key_ops => [+ tstr / int ], 1017 ? alg => tstr / int, 1018 ? kid => bstr, 1019 * label => values 1020 } 1022 COSE_KeySet = [+COSE_Key] 1024 The element "kty" is a required element in a COSE_Key map. All other 1025 elements are optional and not all of the elements listed in [RFC7517] 1026 or [RFC7518] have been listed here even though they can all appear in 1027 a COSE_Key map. 1029 7.1. COSE Key Map Labels 1031 This document defines a set of common map elements for a COSE Key 1032 object. Table 3 provides a summary of the elements defined in this 1033 section. There are also a set of map elements that are defined for a 1034 specific key type. Key specific elements can be found in Section 13. 1036 +----------+-------+-------------+------------+---------------------+ 1037 | name | label | CBOR type | registry | description | 1038 +----------+-------+-------------+------------+---------------------+ 1039 | kty | 1 | tstr / int | COSE | Identification of | 1040 | | | | General | the key type | 1041 | | | | Values | | 1042 | | | | | | 1043 | key_ops | 4 | [* | | Restrict set of | 1044 | | | (tstr/int)] | | permissible | 1045 | | | | | operations | 1046 | | | | | | 1047 | alg | 3 | tstr / int | COSE | Key usage | 1048 | | | | Algorithm | restriction to this | 1049 | | | | Values | algorithm | 1050 | | | | | | 1051 | kid | 2 | bstr | | Key Identification | 1052 | | | | | value - match to | 1053 | | | | | kid in message | 1054 | | | | | | 1055 | x5u | * | tstr | | | 1056 | | | | | | 1057 | x5c | * | bstr* | | | 1058 | | | | | | 1059 | x5t | * | bstr | | | 1060 | | | | | | 1061 | x5t#S256 | * | bstr | | | 1062 | | | | | | 1063 | use | * | tstr | | deprecated - don't | 1064 | | | | | use | 1065 +----------+-------+-------------+------------+---------------------+ 1067 Table 3: Key Map Labels 1069 kty: This field is used to identify the family of keys for this 1070 structure, and thus the set of fields to be found. The set of 1071 values can be found in Table 19. 1073 alg: This field is used to restrict the algorithms that are to be 1074 used with this key. If this field is present in the key 1075 structure, the application MUST verify that this algorithm matches 1076 the algorithm for which the key is being used. If the algorthms 1077 do not match, then this key object MUST NOT be used to perform the 1078 cryptographic operation. Note that the same key can be in a 1079 different key structure with a different or no algorithm 1080 specified, however this is considered to be a poor security 1081 practice. 1083 kid: This field is used to give an identifier for a key. The 1084 identifier is not structured and can be anything from a user 1085 provided string to a value computed on the public portion of the 1086 key. This field is intended for matching against a 'kid' field in 1087 a message in order to filter down the set of keys that need to be 1088 checked. 1090 key_ops: This field is defined to restrict the set of operations 1091 that a key is to be used for. The value of the field is an array 1092 of values from Table 4. 1094 Only the 'kty' field MUST be present in a key object. All other 1095 members may be omitted if their behavior is not needed. 1097 +---------+-------+-------------------------------------------------+ 1098 | name | value | description | 1099 +---------+-------+-------------------------------------------------+ 1100 | sign | 1 | The key is used to create signatures. Requires | 1101 | | | private key fields. | 1102 | | | | 1103 | verify | 2 | The key is used for verification of signatures. | 1104 | | | | 1105 | encrypt | 3 | The key is used for key transport encryption. | 1106 | | | | 1107 | decrypt | 4 | The key is used for key transport decryption. | 1108 | | | Requires private key fields. | 1109 | | | | 1110 | wrap | 5 | The key is used for key wrapping. | 1111 | key | | | 1112 | | | | 1113 | unwrap | 6 | The key is used for key unwrapping. Requires | 1114 | key | | private key fields. | 1115 | | | | 1116 | key | 7 | The key is used for key agreement. | 1117 | agree | | | 1118 +---------+-------+-------------------------------------------------+ 1120 Table 4: Key Operation Values 1122 The following provides a CDDL fragment which duplicates the 1123 assignment labels from Table 3 and Table 4. 1125 ;key_labels 1126 key_kty=1 1127 key_kid=2 1128 key_alg=3 1129 key_ops=4 1131 ;key_ops values 1132 key_ops_sign=1 1133 key_ops_verify=2 1134 key_ops_encrypt=3 1135 key_ops_decrypt=4 1136 key_ops_wrap=5 1137 key_ops_unwrap=6 1138 key_ops_agree=7 1140 8. Signature Algorithms 1142 There are two basic signature algorithm structures that can be used. 1143 The first is the common signature with appendix. In this structure, 1144 the message content is processed and a signature is produced, the 1145 signature is called the appendix. This is the message structure used 1146 by our common algorithms such as ECDSA and RSASSA-PSS. (In fact two 1147 of the letters in RSASSA-PSS are signature appendix.) The basic 1148 structure becomes: 1150 signature = Sign(message content, key) 1152 valid = Verification(message content, key, signature) 1154 The second is a signature with message recovery. (An example of such 1155 an algorithm is [TBD].) In this structure, the message content is 1156 processed, but part of is included in the siguature. Moving bytes of 1157 the message content into the signature allows for an effectively 1158 smaller signature, the signature size is still potentially large, but 1159 the message content is shrunk. This has implications for systems 1160 implementing these algoritms and for applications that use them. The 1161 first is that the message content is not fully available until after 1162 a signature has been validated. Until that point the part of the 1163 message contained inside of the signature is unrecoverable. The 1164 second is that the security analysis of the strength of the signature 1165 is very much based on the structure of the message content. Messages 1166 which are highly predictable require additional randomness to be 1167 supplied as part of the signature process, in the worst case it 1168 because the same as doing a singature with appendix. Thirdly, in the 1169 event that multple signatures are applied to a message, all of the 1170 signature algorithms are going to be required to consume the same 1171 number of bytes of message content. 1173 signature, message sent = Sign(message content, key) 1175 valid, message content = Verification(message sent, key, signature) 1177 At this time, only signatures with appendixes are defined for use 1178 with COSE, however considerable interest has been expressed in using 1179 a signature with message recovery algorithm due to the effective size 1180 reduction that is possible. Implementations will need to keep this 1181 in mind for later possible integration. 1183 8.1. ECDSA 1185 ECDSA [DSS] defines a signature algorithm using ECC. 1187 The security strength of the signature is no greater than the minimum 1188 of the security strength associated with the bit length of the key 1189 and the security strength of the hash function. When a hash function 1190 is used that has greater security than is provided by the length of 1191 the key, the signature algorithm uses the leftmost keyLength bits of 1192 the hash function output. 1194 +-------+-------+---------+------------------+ 1195 | name | value | hash | description | 1196 +-------+-------+---------+------------------+ 1197 | ES256 | -7 | SHA-256 | ECDSA w/ SHA-256 | 1198 | | | | | 1199 | ES384 | -8 | SHA-384 | ECDSA w/ SHA-384 | 1200 | | | | | 1201 | ES512 | -9 | SHA-512 | ECDSA w/ SHA-512 | 1202 +-------+-------+---------+------------------+ 1204 Table 5: ECDSA Algorithm Values 1206 In order to promote interoperability, it is suggested that SHA-256 be 1207 used only with keys of length 256, SHA-384 be used only with keys of 1208 length 384 and SHA-512 be used only with keys of length 521. This is 1209 aligned with the recommendation in Section 4 of [RFC5480]. 1211 The signature algorithm results in a pair of integers (R, S). These 1212 integers will be of the same order as length of the key used for the 1213 signature process. The signature is encoded by converting the 1214 integers into byte strings of the same length as the key size. The 1215 length is rounded up to the nearest byte and is left padded with zero 1216 bits to get to the correct length. The two integers are then 1217 concatenated together to form a byte string that is the resulting 1218 signature. 1220 Using the function defined in [RFC3447] the signature is: 1221 Signature = I2OSP(R, n) | I2OSP(S, n) 1222 where n = ceiling(key_length / 8) 1224 8.1.1. Security Considerations 1226 On of the issues that needs to be discussed is substitution attacks. 1227 There are two different things that can potentially be substituted in 1228 this algorithm. Both of these attacks are current theoretical only. 1230 The first substitution attack is changing the curve used to validate 1231 the signature, the only requirement is that the order of the key 1232 match the length of R and S. It is theoretically possible to use a 1233 different curve and get a different result. We current do not have 1234 any way to deal with this version of the attack except to restrict 1235 the overall set of curves that can be used. 1237 The second substitution attack is to change the hash function that is 1238 used to verify the signature. This attack can be mitigated by 1239 including the signature algorithm identifier in the data to be 1240 signed. 1242 8.2. RSASSA-PSS 1244 The RSASSA-PSS signature algorithm is defined in [RFC3447]. 1246 The RSASSA-PSS signature algorithm is parametized with a hash 1247 function, a mask generation function and a salt length (sLen). For 1248 this specification, the mask generation function is fixed to be MGF1 1249 as defined in [RFC3447]. It has been recommended that the same hash 1250 function be used for hashing the data as well as in the mask 1251 generation function, for this specification we following this 1252 recommendation. The salt length is the same length as the hash 1253 function output. 1255 Three algorithms are defined in this document. These algorithms are: 1257 PS256: This uses the hash algorithm SHA-256 for signature 1258 processing. The value used for this algorithm is -10. The key 1259 type used for this algorithm is 'RSA'. 1261 PS384: This uses the hash algorithm SHA-384 for signature 1262 processing. The value used for this algorithm is "PS384". The 1263 key type used for this algorithm is 'RSA'. 1265 PS512: This uses the hash algorithm SHA-512 for signature 1266 processing. The value used for this algorithm is -11. The key 1267 type used for this algorithm is 'RSA'. 1269 There are no algorithm parameters defined for these signature 1270 algorithms. A summary of the algorithm definitions can be found in 1271 Table 6. 1273 +-------+-------+---------+-------------+-----------------------+ 1274 | name | value | hash | salt length | description | 1275 +-------+-------+---------+-------------+-----------------------+ 1276 | PS256 | -10 | SHA-256 | 32 | RSASSA-PSS w/ SHA-256 | 1277 | | | | | | 1278 | PS384 | * | SHA-384 | 48 | RSASSA-PSS w/ SHA-384 | 1279 | | | | | | 1280 | PS512 | -11 | SHA-512 | 64 | RSASSA-PSS w/ SHA-512 | 1281 +-------+-------+---------+-------------+-----------------------+ 1283 Table 6: RSA Algorithm Values 1285 8.2.1. Security Considerations 1287 Key size. is there a MUST for 2048? or do we need to specify a 1288 minimum here? 1290 9. Message Authentication (MAC) Algorithms 1292 Message Authentication Codes (MACs) provide data authentication and 1293 integrity protection. They provide either no or very limited data 1294 origination. (One cannot, for example, be used to prove the identity 1295 of the sender to a third party.) 1297 MAC algorithms can be based on either a block cipher algorithm (i.e. 1298 AES-MAC) or a hash algorithm (i.e. HMAC). This document defines a 1299 MAC algorithm for each of these two constructions. 1301 9.1. Hash-based Message Authentication Codes (HMAC) 1303 The Hash-base Message Authentication Code algorithm (HMAC) 1304 [RFC2104][RFC4231] was designed, in part, to deal with the birthday 1305 attacks on straight hash functions. The algorithm was also designed 1306 to all for new hash algorithms to be directly plugged in without 1307 changes to the hash function. The HMAC design process has been 1308 vindicated as, while the security of hash algorithms such as MD5 has 1309 decreased over time, the security of HMAC combined with MD5 has not 1310 yet been shown to be compromised [RFC6151]. 1312 For use in constrained environments, we define a set of HMAC 1313 algorithms that are truncated. There are currently no known issues 1314 when truncating, however the security strength of the message tag is 1315 correspondingly reduced in strength. When truncating, the left most 1316 tag length bits are kept and transmitted. 1318 +-----------+-------+---------+--------+----------------------------+ 1319 | name | value | Hash | Length | description | 1320 +-----------+-------+---------+--------+----------------------------+ 1321 | HMAC | * | SHA-256 | 64 | HMAC w/ SHA-256 truncated | 1322 | 256/64 | | | | to 8 bytes | 1323 | | | | | | 1324 | HMAC | 4 | SHA-256 | 256 | HMAC w/ SHA-256 | 1325 | 256/256 | | | | | 1326 | | | | | | 1327 | HMAC | 5 | SHA-384 | 384 | HMAC w/ SHA-384 | 1328 | 384/384 | | | | | 1329 | | | | | | 1330 | HMAC | 6 | SHA-512 | 512 | HMAC w/ SHA-512 | 1331 | 512/512 | | | | | 1332 +-----------+-------+---------+--------+----------------------------+ 1334 Table 7: HMAC Algorithm Values 1336 9.1.1. Security Considerations 1338 TBD. 1340 9.2. AES Message Authentication Code (AES-MAC) 1342 There are a set of different algorithms that we can specify here. 1343 Which should it be? 1345 AES-MAC - Use standard CBC mode 1347 AES-CMAC - RFC 4493 - has improved security over AES-CBC. The 1348 padding is different from CBC mode and requires one extra AES 1349 block encryption step plus and xor operation. 1351 10. Content Encryption Algorithms 1353 10.1. AES GCM 1354 +---------+-------+-----------------------------+ 1355 | name | value | description | 1356 +---------+-------+-----------------------------+ 1357 | A128GCM | 1 | AES-GCM mode w/ 128-bit key | 1358 | | | | 1359 | A192GCM | 2 | AES-GCM mode w/ 192-bit key | 1360 | | | | 1361 | A256GCM | 3 | AES-GCM mode w/ 256-bit key | 1362 +---------+-------+-----------------------------+ 1364 Table 8: Algorithm Value for AES-GCM 1366 10.2. AES CCM 1368 Counter with CBC-MAC (CCM) is a generic authentication encryption 1369 block cipher mode defined in [RFC3610]. The CCM mode is combined 1370 with the AES block encryption algorithm to define a commonly used 1371 content encryption algorithm used in constrainted devices. 1373 The CCM mode has two parameter choices. The first choice is M, the 1374 size of the authentication field. The choice of the value for M 1375 involves a trade-off between message expansion and the probably that 1376 an attacker can undetecably modify a message. The second choice is 1377 L, the size of the length field. This value requires a trade-off 1378 between the maximum message size and the size of the Nonce. 1380 It is unfortunate that the specification for CCM specified L and M as 1381 a count of bytes rather than a count of bits. This leads to possible 1382 misunderstandings where AES-CCM-8 is frequently used to refer to a 1383 version of CCM mode where the size of the authentication is 64-bits 1384 and not 8-bits. These values have traditionally been specified as 1385 bit counts rather than byte counts. This document will follow the 1386 tradition of using bit counts so that it is easier to compare the 1387 different algorithms presented in this document. 1389 We define a matrix of algorithms in this document over the values of 1390 L and M. Constrained devices are usually operating in situations 1391 where they use short messages and want to avoid doing key management 1392 operations. This favors smaller values of M and larger values of L. 1393 Less constrained devices do will want to be able to user larger 1394 messages and are more willing to generate new keys for every 1395 operation. This favors larger values of M and smaller values of L. 1396 (The use of a large nonce means that random generation of both the 1397 key and the nonce will decrease the chances of repeating the pair on 1398 two different messages.) 1400 The following values are used for L: 1402 16-bits (2) limits messages to 2^16 bytes in length. The nonce 1403 length is 13 bytes allowing for 2^(13*8) possible values of the 1404 nonce without repeating. 1406 64-bits (8) limits messages to 2^64 byes in length. The nonce 1407 length is 7 bytes allowing for 2^56 possible values of the nonce 1408 without repeating. 1410 The following values are used for M: 1412 64-bits (8) produces a 64-bit authentication tag. This implies that 1413 there is a 1 in 2^64 chance that an modified message will 1414 authenticate. 1416 128-bits (16) produces a 128-bit authentication tag. This implies 1417 that there is a 1 in 2^128 chance that an modified message will 1418 authenticate. 1420 +--------------------+--------+----+-----+-----+--------------------+ 1421 | name | value | L | M | k | description | 1422 +--------------------+--------+----+-----+-----+--------------------+ 1423 | AES-CCM-16-64-128 | A281C | 16 | 64 | 128 | AES-CCM mode | 1424 | | | | | | 128-bit key, | 1425 | | | | | | 64-bit tag, | 1426 | | | | | | 13-byte nonce | 1427 | | | | | | | 1428 | AES-CCM-16-64-192 | A282C | 16 | 64 | 192 | AES-CCM mode | 1429 | | | | | | 192-bit key, | 1430 | | | | | | 64-bit tag, | 1431 | | | | | | 13-byte nonce | 1432 | | | | | | | 1433 | AES-CCM-16-64-256 | A283C | 16 | 64 | 256 | AES-CCM mode | 1434 | | | | | | 256-bit key, | 1435 | | | | | | 64-bit tag, | 1436 | | | | | | 13-byte nonce | 1437 | | | | | | | 1438 | AES-CCM-64-64-128 | A881C | 64 | 64 | 128 | AES-CCM mode | 1439 | | | | | | 128-bit key, | 1440 | | | | | | 64-bit tag, 7-byte | 1441 | | | | | | nonce | 1442 | | | | | | | 1443 | AES-CCM-64-64-192 | A882C | 64 | 64 | 192 | AES-CCM mode | 1444 | | | | | | 192-bit key, | 1445 | | | | | | 64-bit tag, 7-byte | 1446 | | | | | | nonce | 1447 | | | | | | | 1448 | AES-CCM-64-64-256 | A883C | 64 | 64 | 256 | AES-CCM mode | 1449 | | | | | | 256-bit key, | 1450 | | | | | | 64-bit tag, 7-byte | 1451 | | | | | | nonce | 1452 | | | | | | | 1453 | AES-CCM-16-128-128 | A2161C | 16 | 128 | 128 | AES-CCM mode | 1454 | | | | | | 128-bit key, | 1455 | | | | | | 128-bit tag, | 1456 | | | | | | 13-byte nonce | 1457 | | | | | | | 1458 | AES-CCM-16-128-192 | A2162C | 16 | 128 | 192 | AES-CCM mode | 1459 | | | | | | 192-bit key, | 1460 | | | | | | 128-bit tag, | 1461 | | | | | | 13-byte nonce | 1462 | | | | | | | 1463 | AES-CCM-16-128-256 | A2163C | 16 | 128 | 256 | AES-CCM mode | 1464 | | | | | | 256-bit key, | 1465 | | | | | | 128-bit tag, | 1466 | | | | | | 13-byte nonce | 1467 | | | | | | | 1468 | AES-CCM-64-128-128 | A8161C | 64 | 128 | 128 | AES-CCM mode | 1469 | | | | | | 128-bit key, | 1470 | | | | | | 128-bit tag, | 1471 | | | | | | 7-byte nonce | 1472 | | | | | | | 1473 | AES-CCM-64-128-192 | A8162C | 64 | 128 | 192 | AES-CCM mode | 1474 | | | | | | 192-bit key, | 1475 | | | | | | 128-bit tag, | 1476 | | | | | | 7-byte nonce | 1477 | | | | | | | 1478 | AES-CCM-64-128-256 | A8163C | 64 | 128 | 256 | AES-CCM mode | 1479 | | | | | | 256-bit key, | 1480 | | | | | | 128-bit tag, | 1481 | | | | | | 7-byte nonce | 1482 +--------------------+--------+----+-----+-----+--------------------+ 1484 Table 9: Algorithm Values for AES-CCM 1486 M00TODO: Make a determination of which ones get 1-, 2- or 3-byte 1487 identifiers. I.e. which ones are going to be popular. 1489 10.2.1. Security Considerations 1491 When using AES-CCM the following restrictions MUST be enforced: 1493 o The key and nonce pair MUST be unique for every message encrypted. 1495 o The total number of times the AES block cipher is used MUST NOT 1496 exceed 2^61 operations. This limitation is the sum of times the 1497 block cipher is used in computing the MAC value and in performing 1498 stream encryption operations. An explicit check is required only 1499 in environments where it is expected that it might be exceeded. 1501 [RFC3610] additionally calls out one other consideration of note. It 1502 is possible to do a pre-computation attack against the algorithm in 1503 cases where the portions encryption content is highly predictable. 1504 This reduces the security of the key size by half. Ways to deal with 1505 this attack include adding a random portion to the nonce value and/or 1506 increasing the key size used. Using a portion of the nonce for a 1507 random value will decrease the number of messages that a single key 1508 can be used for. Increasing the key size may require more resources 1509 in the constrained device. See sections 5 and 10 of [RFC3610] for 1510 more information. 1512 11. Key Derivation Functions (KDF) 1514 11.1. HMAC-based Extract-and-Expand Key Derivation Function (HKDF) 1516 See [RFC5869]. 1518 Inputs: 1520 secret - a shared value that is secret. Secrets may be either 1521 previously shared or derived from operations like a DH key 1522 agreement. 1524 salt - an optional public value that is used to change the 1525 generation process. If specified, the salt is carried using the 1526 'salt' algorithm parameter. While [RFC5869] suggests that the 1527 length of the salt be the same as the length of the underlying 1528 hash value, any amount of salt will improve the security as 1529 different key values will be generated. The 'salt' parameter is 1530 encoded as a binary string. This parameter is protected by being 1531 included in the key computation and does not need to be separately 1532 authenticated. 1534 length - the number of bytes of output that need to be generated. 1536 context information 1538 hash function - The underlying hash function to be used in the 1539 HKDF algorithm. The hash function is encoded into the HKDF 1540 algorithm selection. 1542 +----------+---------+---------+ 1543 | name | hash | context | 1544 +----------+---------+---------+ 1545 | HKDF-256 | SHA-256 | XXX | 1546 | | | | 1547 | HKDF-512 | SHA-512 | XXX | 1548 +----------+---------+---------+ 1550 Table 10: HKDF algorithms 1552 +------+-------+------+-------------+ 1553 | name | label | type | description | 1554 +------+-------+------+-------------+ 1555 | salt | -20 | bstr | Random salt | 1556 +------+-------+------+-------------+ 1558 Table 11: HKDF parameters 1560 11.2. Context Information Structure 1562 The context information structure is used to ensure that the derived 1563 keying material is "bound" to the context of the transaction. The 1564 context information structure used here is based on that defined in 1565 [SP800-56A]. By using CBOR for the encoding of the context 1566 information structure, we automatically get the same type of type and 1567 length separation of fields that is obtained by the use of ASN.1. 1568 This means that there is no need to encode the lengths for the base 1569 elements as it is done by the CBOR encoding. 1571 The context information structure refers to PartyU and PartyV as the 1572 two parties which are doing the key derivation. Unless the 1573 application protocol defines differently, we assign PartyU to the 1574 entity that is creating the message and PartyV to the entity that is 1575 receiving the message. This is because we are assuming a set of 1576 stand alone store and forward messaging processes. 1578 Application protocols are free to define the roles differently. For 1579 example, they could assign the PartyU role to the entity that 1580 initiates the connection and allow directly sending multiple messages 1581 over the line without changing the role information. 1583 We encode the context specific information using a CBOR array type. 1584 The fields in the array are: 1586 AlgorithmID This field indicates the algorithm for which the key 1587 material will be used. This field is required to be present and 1588 is a copy of the algorithm identifier in the message. The field 1589 exists in the context information so that if the same environment 1590 is used for different algorithms, then completely different keys 1591 will be generated each of those algorithms. (This practice means 1592 if algorithm A uses a shorter key than algorithm B and thus can be 1593 found easier, the key derived for algorithm B will not contain the 1594 key for algorithm A as a prefix.) [CREF17] 1596 PartyUInfo This field holds information about party U. The 1597 ParytUInfo structure is divided into three pieces: 1599 identity This contains the identity information for party U. The 1600 identities can be assigned in one of two manners. Firstly, a 1601 protocol can assign identities based on roles. For example, 1602 the roles of "client" and "server" may be assigned to different 1603 entities in the protocol. Each entity would then use the 1604 correct label for the data they they send or receive. The 1605 second way is for a protocol to assign identities is to use a 1606 name based on a naming system (i.e. DNS, X.509 names). 1607 We define an algorithm parameter 'PartyU identity' that can be 1608 used to carry identity information in the message. However, 1609 identity information is often known as part of the protocol and 1610 can thus be inferred rather than made explicit. If identity 1611 information is carried in the message, applications SHOULD have 1612 a way of validating the supplied identity information. The 1613 identity information does not need to be specified and can be 1614 left as absent. 1615 The identity value supplied will be validated as part of the 1616 key derivation process. If the identity string is wrong, then 1617 the wrong key will be created. 1619 nonce This contains a one time nonce value. The nonce can either 1620 be implicit from the protocol or carried as a value in the 1621 unprotected headers. [CREF18] 1622 We define an algorithm parameter 'PartyU nonce' that can be 1623 used to carry this value in the message However, the nonce 1624 value could be determined by the application and the value 1625 determined from elsewhere. 1626 This item is optional and can be absent. 1628 other This contains other information that is defined by the 1629 protocol. 1630 This item is optional and can be absent. 1632 PartyVInfo M00TODO: Copy down from PartyUInfo when that text is 1633 ready. 1635 SuppPubInfo This field contains public information that is mutually 1636 known to both parties. 1638 keyDataLength This is set to the number of bits of the desired 1639 output value. 1641 other The field other is for free form data defined by the 1642 application. An example is that an application could defined 1643 two different strings to be placed here to generate different 1644 keys for a data stream vs a control stream. This field is 1645 optional and will only be present if the application defines a 1646 structure for this information. Applications that define this 1647 SHOULD use CBOR to encode the data so that types and lengths 1648 are correctly include. 1650 SuppPrivInfo This field contains private information that is 1651 mutually known information. An example of this information would 1652 be a pre-existing shared secret. The field is optional and will 1653 only be present if the application defines a structure for this 1654 information. Applications that define this SHOULD use CBOR to 1655 encode the data so that types and lengths are correctly include. 1657 COSE_KDF_Context = [ 1658 AlgorithmID : int / tstr, 1659 PartyUInfo : [ 1660 ? nonce : bstr / int, 1661 ? identity : bstr, 1662 ? other : bstr 1663 ], 1664 PartyVInfo : [ 1665 ? nonce : bstr, 1666 ? identity : bstr / tstr, 1667 ? other : bstr 1668 ], 1669 SuppPubInfo : [ 1670 keyDataLength : uint, 1671 ? other : bstr 1672 ], 1673 ? SuppPrivInfo : bstr 1674 ] 1675 +---------------+-------+-----------+-------------------------------+ 1676 | name | label | type | description | 1677 +---------------+-------+-----------+-------------------------------+ 1678 | PartyU | -21 | bstr | Party U identity Information | 1679 | identity | | | | 1680 | | | | | 1681 | PartyU nonce | -22 | bstr / | Party U provided nonce | 1682 | | | int | | 1683 | | | | | 1684 | PartyU other | -23 | bstr | Party U other provided | 1685 | | | | information | 1686 | | | | | 1687 | PartyV | -24 | bstr | Party V identity Information | 1688 | identity | | | | 1689 | | | | | 1690 | PartyV nonce | -25 | bstr / | Party V provided nonce | 1691 | | | int | | 1692 | | | | | 1693 | PartyV other | -26 | bstr | Party V other provided | 1694 | | | | information | 1695 +---------------+-------+-----------+-------------------------------+ 1697 Table 12: Context Algorithm Parameters 1699 12. Key Management Algorithms 1701 There are a number of different key management methods that can be 1702 used in the COSE encryption system. In this section we will discuss 1703 each of the key management methods, what fields need to be specified, 1704 and which algorithms are defined in this document to deal with each 1705 of them. 1707 The names of the key management methods used here are the same as are 1708 defined in [RFC7517]. Other specifications use different terms for 1709 the key management methods or do not support some of the key 1710 management methods. 1712 At the moment we do not have any key management methods that allow 1713 for the use of protected headers. This may be changed in the future 1714 if, for example, the AES-GCM Key wrap method defined in [RFC7518] 1715 were extended to allow for authenticated data. In that event, the 1716 use of the 'protected' field, which is current forbidden below, would 1717 be permitted. 1719 12.1. Direct Encryption 1721 In direct encryption mode, a shared secret between the sender and the 1722 recipient is used as the key. [CREF19] When direct encryption mode 1723 is used, it MUST be the only mode used on the message. It is a 1724 massive security leak to have both direct encryption and a different 1725 key management mode on the same message. 1727 For JOSE, direct encryption key management is the only key management 1728 method allowed for doing MACed messages. In COSE, all of the key 1729 management methods can be used for MACed messages. 1731 The COSE_encrypt structure for the recipient is organized as follows: 1733 o The 'protected', 'ciphertext' and 'recipients' fields MUST be 1734 absent. 1736 o At a minimum, the 'unprotected' field MUST contain the 'alg' 1737 parameter and SHOULD contain a parameter identifying the shared 1738 secret. 1740 12.1.1. Direct Key 1742 We define two key agreement algorithms that function as direct key 1743 algorithms. These algorithms are: 1745 Direct: This key management technique is the simplest method, the 1746 supplied key is directly used as the key for the next layer down 1747 in the message. There are no algorithm parameters defined for 1748 this key management methods. 1750 Direct KDF: This key managment takes a common shared secret between 1751 the two parties and applies the HKDF function (Section 11.1) using 1752 the context structure defined in Section 11.2 to transform the 1753 shared secret into the necessary key. Either the 'salt' parameter 1754 of HKDF or the partyU 'nonce' parameter of the context structure 1755 MUST be present. This parameter can be generated either randomly 1756 or deterministically, the requirement is that it be a unique value 1757 for the key pair in question. 1758 If the salt/nonce value is generated randomly, then it is 1759 suggested that the length of the random value be the same length 1760 as the hash function underlying HKDF, i.e 256-bits. While there 1761 is no way to guarantee that it will be unique, there is a high 1762 probability that it will be unique. If the salt/nonce value is 1763 generated deterministically, it can be guaranteed to be unique and 1764 thus there is no length requirement. 1766 +------------+-------+--------------+----------------------+ 1767 | name | value | KDF | description | 1768 +------------+-------+--------------+----------------------+ 1769 | direct | -6 | N/A | Direct use of CEK | 1770 | | | | | 1771 | direct+KDF | * | HKDF SHA-256 | Shared secret w/ KDF | 1772 +------------+-------+--------------+----------------------+ 1774 Table 13: Direct Key 1776 12.1.1.1. Security Considerations 1778 Lifetime, Length, Compromise 1780 12.2. Key Wrapping 1782 In key wrapping mode, the CEK is randomly generated and that key is 1783 then encrypted by a shared secret between the sender and the 1784 recipient. All of the currently defined key wrapping algorithms for 1785 JOSE (and thus for COSE) are AE algorithms. Key wrapping mode is 1786 considered to be superior to direct encryption if the system has any 1787 capability for doing random key generation. This is because the 1788 shared key is used to wrap random data rather than data has some 1789 degree of organization and may in fact be repeating the same content. 1791 The COSE_encrypt structure for the recipient is organized as follows: 1793 o The 'protected' field MUST be absent if the key wrap algorithm is 1794 an AE algorithm. 1796 o The 'recipients' field is normally absent, but can be used. 1797 Applications MUST deal with a recipients field present, not being 1798 able to decrypt that recipient is an acceptable way of dealing 1799 with it. Failing to process the message is not an acceptable way 1800 of dealing with it. 1802 o The plain text to be encrypted is the key from next layer down 1803 (usually the content layer). 1805 o At a minimum, the 'unprotected' field MUST contain the 'alg' 1806 parameter and SHOULD contain a parameter identifying the shared 1807 secret. 1809 12.2.1. AES Key Wrapping 1811 The AES Key Wrapping algorithm is defined in [RFC3394]. This 1812 algorithm uses an AES key to wrap a value that is a multiple of 1813 64-bits, as such it can be used to wrap a key for any of the content 1814 encryption algorithms defined in this document. [CREF20] The 1815 algorithm requires a single fixed parameter, the initial value. This 1816 is fixed to the value specified in Section 2.2.3.1 of [RFC3394]. 1817 There are no public parameters that vary on a per invocation basis. 1819 +--------+-------+----------+-----------------------------+ 1820 | name | value | key size | description | 1821 +--------+-------+----------+-----------------------------+ 1822 | A128KW | -3 | 128 | AES Key Wrap w/ 128-bit key | 1823 | | | | | 1824 | A192KW | -4 | 192 | AES Key Wrap w/ 192-bit key | 1825 | | | | | 1826 | A256KW | -5 | 256 | AES Key Wrap w/ 256-bit key | 1827 +--------+-------+----------+-----------------------------+ 1829 Table 14: AES Key Wrap Algorithm Values 1831 12.2.1.1. Security Considerations for AES-KW 1833 There are no specific security considerations for this algorithm. 1835 12.3. Key Encryption 1837 Key Encryption mode is also called key transport mode in some 1838 standards. Key Encryption mode differs from Key Wrap mode in that it 1839 uses an asymmetric encryption algorithm rather than a symmetric 1840 encryption algorithm to protect the key. The only current Key 1841 Encryption mode algorithm supported is RSAES-OAEP. 1843 The COSE_encrypt structure for the recipient is organized as follows: 1845 o The 'protected' field MUST be absent. 1847 o The plain text to be encrypted is the key from next layer down 1848 (usually the content layer). 1850 o At a minimum, the 'unprotected' field MUST contain the 'alg' 1851 parameter and SHOULD contain a parameter identifying the 1852 asymmetric key. 1854 12.3.1. RSA OAEP 1855 +----------+-------+-----------------------+ 1856 | name | value | description | 1857 +----------+-------+-----------------------+ 1858 | RSA-OAEP | -2 | RSAES OAEP w/ SHA-256 | 1859 +----------+-------+-----------------------+ 1861 Table 15: RSA OAEP Algorithm Values 1863 12.3.1.1. Security Considerations for RSA OAEP 1865 A key size of 2048 bits or larger MUST be used with this algorithm. 1866 This key size corresponds roughly to the same strength as provided by 1867 a 128-bit symmetric encryption algorithm. 1869 It is highly recommended that checks on the key length be done before 1870 starting a decryption operation. One potential denial of service 1871 operation is to provide encrypted objects using either abnormally 1872 long or oddly sized RSA modulus values. Implementations SHOULD be 1873 able to encrypt and decrypt with modulus between 2048 and 16K bits in 1874 length.[CREF21] Applications can impose additional restrictions on 1875 the length of the modulus. 1877 12.4. Direct Key Agreement 1879 When using the 'Direct Key Agreement' key managment method, the two 1880 parties use a key agreement method to create a shared secret. A KDF 1881 is then applied to the shared secret to derive a key to be used in 1882 protecting the data. This key is normally used as a CEK or MAC key, 1883 but could be used for other purposes if more than two layers are in 1884 use (see Appendix B). 1886 The most commonly used key agreement algorithm used is Diffie- 1887 Hellman, but other variants exist. Since COSE is designed for a 1888 store and forward environment rather than an on-line environment, 1889 many of the DH variants cannot be used as the receiver of the message 1890 cannot provide any key material. One side-effect of this is that 1891 perfect forward security is not achievable, a static key will always 1892 be used for the receiver of the COSE message. 1894 Two variants of DH that are easily supported are: 1896 Ephemeral-Static DH: where the sender of the message creates a one 1897 time DH key and uses a static key for the recipient. The use of 1898 the ephemeral sender key means that no additional random input is 1899 needed as this is randomly generated for each message. 1901 Static-Static DH: where a static key is used for both the sender 1902 and the recipient. The use of static keys allows for recipient to 1903 get a weak version of data origination for the message. When 1904 static-static key agreement is used, then some piece of unique 1905 data is require to ensure that a different key is created for each 1906 message 1908 In this specification, both variants are specified. This has been 1909 done to provide the weak data origination option for use with MAC 1910 operations. 1912 When direct key agreement mode is used, it MUST be the only key 1913 management mode used on the message and there MUST be only one 1914 recipient. This method creates the key directly and that makes it 1915 difficult to mix with additional recipients. If multiple recipients 1916 are needed, then the version with key wrap (Section 12.5.1) needs to 1917 be used. 1919 The COSE_encrypt structure for the recipient is organized as follows: 1921 o The 'protected' field MUST be absent. 1923 o At a minimum, the 'unprotected' field MUST contain the 'alg' 1924 parameter and SHOULD contain a parameter identifying the 1925 recipient's asymmetric key. 1927 o The 'unprotected' field MUST contain the 'epk' parameter. 1929 12.4.1. ECDH 1931 NOTE: Curves 25519 and Goldilocks are elements at risk. 1933 We define one set of key agreement algorithms structured around 1934 Elliptic Curves Diffie-Hellman problem. [CREF22] We define both an 1935 ephemeral-static and a static-static version of these algorithms. We 1936 allow for multiple curves to be used, it needs to be noted that the 1937 math required for the curves as well as the point representation is 1938 going to be different. [CREF23] 1940 We setup to use two different curve structures for the ECDH 1941 algorithms. 1943 Weierstrass Curves: These are the ones one is used to seeing from 1944 NIST. We define three NIST curves for use with this document. 1945 These curves are P-256, P-384 and P-512. (The mathematics can be 1946 found in [RFC6090].) For these curves, the key type 'EC2' is used 1947 (Section 13.1.2). 1949 Montgomery Curves: These curves are Curve25519 and Goldilocks. 1950 (The mathematics can be found in [I-D.irtf-cfrg-curves].) For 1951 these curves, the key type 'EC1' is used (Section 13.1.1). 1953 As shown in Table 16 we define two ECDH algorithm identifiers for EC 1954 direct key agreement. These identifiers are: 1956 ECDH-ES: This algorithm does a key agreement operation using a 1957 static key for the recipient and an ephemeral key for the sender. 1958 The ephemeral key MUST be generated fresh for every message. The 1959 HKDF function (Section 11.1) is used with the context structure in 1960 Section 11.2 to transform the key agreement secret into the 1961 necessary key. Since the ephemeral key is generated freshly, the 1962 'salt' parameter of HKDF is not needed and can be absent. 1963 One new algorithm parameter is defined for use with this 1964 algorithm. This parameter is: 1966 ephemeral key: This parameter is used to hold and transport the 1967 ephemeral key generated by the sender of the message. This 1968 parameter has a label of -1 and a type of COSE_Key. This 1969 parameter can be placed in the unprotected bucket, if it is 1970 changed then the correct key will not be able to be generated. 1972 The parameter is summarized in Table 17. 1974 ECDH-SS: This algorithm does a key agreement operation using two 1975 static keys, one for the recipient and one for the sender. The 1976 HKDF function (Section 11.1) is used with the context structure in 1977 Section 11.2 to transform the key agreement secret into the 1978 necessary key. Either the 'salt' parameter of HKDF or the partyU 1979 'nonce' parameter of the context structure MUST be present. This 1980 parameter can be generated either randomly or deterministically, 1981 the requirement is that it be a unique value for the key pair in 1982 question. 1983 If the salt/nonce value is generated randomly, then it is 1984 suggested that the length of the random value be the same length 1985 as the hash function underlying HKDF, i.e 256-bits. While there 1986 is no way to guarantee that it will be unique, there is a high 1987 probability that it will be unique. If the salt/nonce value is 1988 generated deterministically, it can be guaranteed to be unique and 1989 thus there is no length requirement. 1990 Two new algorithm parameters are defined for use with this 1991 algorithm. These parameters are: 1993 static key: This parameter is used to hold and transport the 1994 static key used by the sender of the message. This parameter 1995 has the label of -2 and a type of COSE_Key. The parameter can 1996 be placed in the unprotected bucket, if it is changed then the 1997 correct key will not be able to be generated. If the data 1998 origination service is desired, then the message recipient 1999 needs to validate that the key in this field is associated with 2000 the sender. 2002 static key identifier: This parameter is used to hold a reference 2003 to the static key used by the sender of the message. The value 2004 is expected to match the 'kid' member of a COSE_Key structure 2005 published by the sender. The value in this field cannot be 2006 assumed to uniquely identify a single key, multiple keys may 2007 need to be found and tested. Not all of the keys identified by 2008 a kid value may be associated with the sender of the message. 2009 If the data origination service is desired, then the message 2010 recipient needs to validate that the key in this field is 2011 associated with the sender. 2013 These parameters are summarized in Table 17. 2015 +---------+---------+--------------+--------------------------------+ 2016 | name | value | KDF | description | 2017 +---------+---------+--------------+--------------------------------+ 2018 | ECDH-ES | ECDH-ES | HKDF - | ECDH ES w/ HKDF - generate key | 2019 | | | SHA-256 | directly | 2020 | | | | | 2021 | ECDH-SS | ECDH-SS | HKDF - | ECDH SS w/ HKDF - generate key | 2022 | | | SHA-256 | directly | 2023 +---------+---------+--------------+--------------------------------+ 2025 Table 16: ECDH Algorithm Values 2027 +-----------+-------+----------+-----------+------------------------+ 2028 | name | label | type | algorithm | description | 2029 +-----------+-------+----------+-----------+------------------------+ 2030 | ephemeral | -1 | COSE_Key | ECDH-ES | Ephemeral Public key | 2031 | key | | | | for the sender | 2032 | | | | | | 2033 | static | -2 | COSE_Key | ECDH-ES | Static Public key for | 2034 | key | | | | the sender | 2035 | | | | | | 2036 | static | -3 | bstr | ECDH-SS | Static Public key | 2037 | key id | | | | identifier for the | 2038 | | | | | sender | 2039 +-----------+-------+----------+-----------+------------------------+ 2041 Table 17: ECDH Algorithm Parameters 2043 M00TODO: Talk about curves and point formats. 2045 +------------+----------+-------+-------------------------------+ 2046 | name | key type | value | description | 2047 +------------+----------+-------+-------------------------------+ 2048 | P-256 | EC2 | 1 | NIST P-256 also known as .... | 2049 | | | | | 2050 | P-384 | EC2 | 2 | NIST P-384 also known as .... | 2051 | | | | | 2052 | P-521 | EC2 | 3 | NIST P-512 also known as .... | 2053 | | | | | 2054 | Curve25519 | EC1 | 1 | Provide reference | 2055 | | | | | 2056 | Goldilocks | EC1 | 2 | Provide reference | 2057 +------------+----------+-------+-------------------------------+ 2059 Table 18: EC Curves 2061 12.5. Key Agreement with KDF 2063 Key Agreement with Key Wrapping uses a randomly generated CEK. The 2064 CEK is then encrypted using a Key Wrapping algorithm and a key 2065 derived from the shared secret computed by the key agreement 2066 algorithm. 2068 The COSE_encrypt structure for the recipient is organized as follows: 2070 o The 'protected' field MUST be absent if the key wrap algorithm is 2071 an AE algorithm. [CREF24] 2073 o The plain text to be encrypted is the key from next layer down 2074 (usually the content layer). 2076 o At a minimum, the 'unprotected' field MUST contain the 'alg' 2077 parameter, a parameter identifying the recipient asymmetric key, 2078 and a parameter with the sender's asymmetric public key. 2080 12.5.1. ECDH ES + HKDF 2081 +----------------+-------+----------+-------------------------------+ 2082 | name | value | KDF | description | 2083 +----------------+-------+----------+-------------------------------+ 2084 | ECDH-ES+A128KW | * | HKDF - | ECDH ES w/ Concat KDF and AES | 2085 | | | SHA-256 | Key wrap w/ 128 bit key | 2086 | | | | | 2087 | ECDH-ES+A192KW | * | HKDF - | ECDH ES w/ Concat KDF and AES | 2088 | | | SHA-256 | Key wrap w/ 192 bit key | 2089 | | | | | 2090 | ECDH-ES+A256KW | * | HKDF - | ECDH ES w/ Concat KDF and AES | 2091 | | | SHA-256 | Key wrap w/ 256 bit key | 2092 +----------------+-------+----------+-------------------------------+ 2094 12.6. Password 2096 [CREF25] 2098 12.6.1. PBES2 2100 +--------------------+-------+--------------------------------------+ 2101 | name | value | description | 2102 +--------------------+-------+--------------------------------------+ 2103 | PBES2-HS256+A128KW | * | PBES2 w/ HMAC SHA-256 and AES Key | 2104 | | | wrap w/ 128 bit key | 2105 | | | | 2106 | PBES2-HS384+A192KW | * | PBES2 w/ HMAC SHA-384 and AES Key | 2107 | | | wrap w/ 192 bit key | 2108 | | | | 2109 | PBES2-HS512+A256KW | * | PBES2 w/ HMAC SHA-512 and AES Key | 2110 | | | wrap w/ 256 bit key | 2111 +--------------------+-------+--------------------------------------+ 2113 13. Keys 2115 The COSE_Key object defines a way to hold a single key object, it is 2116 still required that the members of individual key types be defined. 2117 This section of the document is where we define an initial set of 2118 members for specific key types. 2120 For each of the key types, we define both public and private members. 2121 The public members are what is transmitted to others for their usage. 2122 We define private members mainly for the purpose of archival of keys 2123 by individuals. However, there are some circumstances where private 2124 keys may be distributed by various entities in a protocol. Examples 2125 include: Entities which have poor random number generation. 2126 Centralized key creation for multi-cast type operations. Protocols 2127 where a shared secret is used as a bearer token for authorization 2128 purposes. 2130 Keys are identified by the 'kty' member of the COSE_Key object. In 2131 this document we define four values for the member. 2133 +-----------+-------+--------------------------------------------+ 2134 | name | value | description | 2135 +-----------+-------+--------------------------------------------+ 2136 | EC1 | 1 | Elliptic Curve Keys w/ X Coordinate only | 2137 | | | | 2138 | EC2 | 2 | Elliptic Curve Keys w/ X,Y Coordinate pair | 2139 | | | | 2140 | RSA | 3 | RSA Keys | 2141 | | | | 2142 | Symmetric | 4 | Symmetric Keys | 2143 +-----------+-------+--------------------------------------------+ 2145 Table 19: Key Type Values 2147 13.1. Elliptic Curve Keys 2149 Two different key structures are being defined for Elliptic Curve 2150 keys. One version uses both an x and a y coordinate, potentially 2151 with point compression. This is the traditional EC point 2152 representation that is used in [RFC5480]. The other version uses 2153 only the x coordinate as the y coordinate is either to be recomputed 2154 or not needed for the key agreement operation. An example of this is 2155 Curve25519 [I-D.irtf-cfrg-curves]. 2157 13.1.1. Single Coordinate Curves 2159 NOTE: This section represents at risk work depending on the ability 2160 to get good references for Curve25519 and Goldilocks. 2162 New versions of ECC have been targeted at variants where only a 2163 single value of the EC Point need to be transmitted. This work is 2164 currently going on in the IRTF CFRG group. 2166 For EC keys with both coordinates, the 'kty' member is set to 1 2167 (EC1). The members that are defined for this key type are: 2169 crv contains an identifier of the curve to be used with the key. 2170 [CREF26] The curves defined in this document for this key type can 2171 be found in Table 18. Other curves may be registered in the 2172 future and private curves can be used as well. 2174 x contains the x coordinate for the EC point. The integer is 2175 converted to an octet string use ???. Note that the octet string 2176 represents a little-endian encoding of x. [CREF27] 2178 d contains the private key. 2180 For public keys, it is REQUIRED that 'crv' and 'x' be present in the 2181 structure. For private keys, it is REQUIRED that 'crv' and 'd' be 2182 present in the structure. It is RECOMMENDED that 'x' also be 2183 present, but it can be recomputed from the required elements and 2184 omitting it saves on space. 2186 +------+-------+-------+--------+-----------------------------------+ 2187 | name | key | value | type | description | 2188 | | type | | | | 2189 +------+-------+-------+--------+-----------------------------------+ 2190 | crv | 1 | -1 | int / | EC Curve identifier - Taken from | 2191 | | | | tstr | the COSE General Registry | 2192 | | | | | | 2193 | x | 1 | -2 | bstr | X Coordinate | 2194 | | | | | | 2195 | d | 1 | -4 | bstr | Private key | 2196 +------+-------+-------+--------+-----------------------------------+ 2198 Table 20: EC Key Parameters 2200 13.1.2. Double Coordinate Curves 2202 The traditional way of sending EC curves has been to send either both 2203 the x and y coordinates, or the x coordinate and a sign bit for the y 2204 coordinate. The latter encoding has not been recommend in the IETF 2205 due to potential IPR issues with Certicom. However, for operations 2206 in constrained environments, the ability to shrink a message by not 2207 sending the y coordinate is potentially useful. 2209 For EC keys with both coordinates, the 'kty' member is set to 2 2210 (EC2). The members that are defined for this key type are: 2212 crv contains an identifier of the curve to be used with the key. 2213 The curves defined in this document for this key type can be found 2214 in Table 18. Other curves may be registered in the future and 2215 private curves can be used as well. 2217 x contains the x coordinate for the EC point. The integer is 2218 converted to an octet string as defined in [SEC1]. Zero octets 2219 MUST NOT be removed from the front of the octet string. [CREF28] 2221 y contains either the sign bit or the value of y coordinate for the 2222 EC point. For the value, the integer is converted to an octet 2223 string as defined in [SEC1]. Zero octets MUST NOT be removed from 2224 the front of the octet string. For the sign bit, the value is 2225 true if the value of y is positive. 2227 d contains the private key. 2229 For public keys, it is REQUIRED that 'crv', 'x' and 'y' be present in 2230 the structure. For private keys, it is REQUIRED that 'crv' and 'd' 2231 be present in the structure. It is RECOMMENDED that 'x' and 'y' also 2232 be present, but they can be recomputed from the required elements and 2233 omitting them saves on space. 2235 +------+-------+-------+---------+----------------------------------+ 2236 | name | key | value | type | description | 2237 | | type | | | | 2238 +------+-------+-------+---------+----------------------------------+ 2239 | crv | 2 | -1 | int / | EC Curve identifier - Taken from | 2240 | | | | tstr | the COSE General Registry | 2241 | | | | | | 2242 | x | 2 | -2 | bstr | X Coordinate | 2243 | | | | | | 2244 | y | 2 | -3 | bstr / | Y Coordinate | 2245 | | | | bool | | 2246 | | | | | | 2247 | d | 2 | -4 | bstr | Private key | 2248 +------+-------+-------+---------+----------------------------------+ 2250 Table 21: EC Key Parameters 2252 13.2. RSA Keys 2253 +-------+----------+-------+-------+----------------------------+ 2254 | name | key type | value | type | description | 2255 +-------+----------+-------+-------+----------------------------+ 2256 | n | 3 | -1 | bstr | Modulus Parameter | 2257 | | | | | | 2258 | e | 3 | -2 | int | Exponent Parameter | 2259 | | | | | | 2260 | d | 3 | -3 | bstr | Private Exponent Parameter | 2261 | | | | | | 2262 | p | 3 | -4 | bstr | First Prime Factor | 2263 | | | | | | 2264 | q | 3 | -5 | bstr | Second Prime Factor | 2265 | | | | | | 2266 | dp | 3 | -6 | bstr | First Factor CRT Exponent | 2267 | | | | | | 2268 | dq | 3 | -7 | bstr | Second Factor CRT Exponent | 2269 | | | | | | 2270 | qi | 3 | -8 | bstr | First CRT Coefficient | 2271 | | | | | | 2272 | other | 3 | -9 | array | Other Primes Info | 2273 | | | | | | 2274 | r | 3 | -10 | bstr | Prime Factor | 2275 | | | | | | 2276 | d | 3 | -11 | bstr | Factor CRT Exponent | 2277 | | | | | | 2278 | t | 3 | -12 | bstr | Factor CRT Coefficient | 2279 +-------+----------+-------+-------+----------------------------+ 2281 Table 22: RSA Key Parameters 2283 13.3. Symmetric Keys 2285 Occasionally it is required that a symmetric key be transported 2286 between entities. This key structure allows for that to happen. 2288 For symmetric keys, the 'kty' member is set to 3 (Symmetric). The 2289 member that is defined for this key type is: 2291 k contains the value of the key. 2293 This key structure contains only private key information, care must 2294 be taken that it is never transmitted accidentally. For public keys, 2295 there are no required fields. For private keys, it is REQUIRED that 2296 'k' be present in the structure. 2298 +------+----------+-------+------+-------------+ 2299 | name | key type | value | type | description | 2300 +------+----------+-------+------+-------------+ 2301 | k | 4 | -1 | bstr | Key Value | 2302 +------+----------+-------+------+-------------+ 2304 Table 23: Symmetric Key Parameters 2306 14. CBOR Encoder Restrictions 2308 There as been an attempt to limit the number of places where the 2309 document needs to impose restrictions on how the CBOR Encoder needs 2310 to work. We have managed to narrow it down to the following 2311 restrictions: 2313 o The restriction applies to the encoding the Sig_structure, the 2314 Enc_structure, and the MAC_structure. 2316 o The rules for Canonical CBOR (Section 3.9 of RFC 7049) MUST be 2317 used in these locations. The main rule that needs to be enforced 2318 is that all lengths in these structures MUST be encoded such that 2319 they are encoded using definite lengths and the minimum length 2320 encoding is used. 2322 o All parsers used SHOULD fail on both parsing and generation if the 2323 same label is used twice as a key for the same map. 2325 15. IANA Considerations 2327 15.1. CBOR Tag assignment 2329 It is requested that IANA assign a new tag from the "Concise Binary 2330 Object Representation (CBOR) Tags" registry. It is requested that 2331 the tag be assigned in the 0 to 23 value range. 2333 Tag Value: TBD1 2335 Data Item: COSE_Msg 2337 Semantics: COSE security message. 2339 15.2. COSE Object Labels Registry 2341 It is requested that IANA create a new registry entitled "COSE Object 2342 Labels Registry". [CREF29] 2344 This table is initially populated by the table in Table 1. 2346 15.3. COSE Header Label Table 2348 It is requested that IANA create a new registry entitled "COSE Header 2349 Labels". 2351 The columns of the registry are: 2353 name The name is present to make it easier to refer to and discuss 2354 the registration entry. The value is not used in the protocol. 2355 Names are to be unique in the table. 2357 label This is the value used for the label. The label can be either 2358 an integer or a string. Registration in the table is based on the 2359 value of the label requested. Integer values between 1 and 255 2360 and strings of length 1 are designated as Standards Track Document 2361 required. Integer values from 256 to 65535 and strings of length 2362 2 are designated as Specification Required. Integer values of 2363 greater than 65535 and strings of length greater than 2 are 2364 designated as first come first server. Integer values in the 2365 range -1 to -65536 are delegated to the "COSE Header Algorithm 2366 Label" registry. Integer values beyond -65536 are marked as 2367 private use. 2369 value This contains the CBOR type for the value portion of the 2370 label. 2372 value registry This contains a pointer to the registry used to 2373 contain values where the set is limited. 2375 description This contains a brief description of the header field. 2377 specification This contains a pointer to the specification defining 2378 the header field (where public). 2380 The initial contents of the registry can be found in Table 2. The 2381 specification column for all rows in that table should be this 2382 document. 2384 Additionally, the label of 0 is to be marked as 'Reserved'. 2386 15.4. COSE Header Algorithm Label Table 2388 It is requested that IANA create a new registry entitled "COSE Header 2389 Algorithm Labels". 2391 The columns of the registry are: 2393 name The name is present to make it easier to refer to and discuss 2394 the registration entry. The value is not used in the protocol. 2396 algorithm The algorithm(s) that this registry entry is used for. 2397 This value is taken from the "COSE Algorithm Value" registry. 2398 Multiple algorithms can be specified in this entry. For the 2399 table, the algorithm, label pair MUST be unique. 2401 label This is the value used for the label. The label is an integer 2402 in the range of -1 to -65536. 2404 value This contains the CBOR type for the value portion of the 2405 label. 2407 value registry This contains a pointer to the registry used to 2408 contain values where the set is limited. 2410 description This contains a brief description of the header field. 2412 specification This contains a pointer to the specification defining 2413 the header field (where public). 2415 The initial contents of the registry can be found in: Table 11, 2416 Table 12, Table 17, and Appendix D. The specification column for all 2417 rows in that table should be this document. 2419 15.5. COSE Algorithm Registry 2421 It is requested that IANA create a new registry entitled "COSE 2422 Algorithm Registry". 2424 The columns of the registry are: 2426 value The value to be used to identify this algorithm. Algorithm 2427 values MUST be unique. The value can be a positive integer, a 2428 negative integer or a string. Integer values between 0 and 255 2429 and strings of length 1 are designated as Standards Track Document 2430 required. Integer values from 256 to 65535 and strings of length 2431 2 are designated as Specification Required. Integer values of 2432 greater than 65535 and strings of length greater than 2 are 2433 designated as first come first server. Integer values in the 2434 range -1 to -65536 are delegated to the "COSE Header Algorithm 2435 Label" registry. Integer values beyond -65536 are marked as 2436 private use. 2438 description A short description of the algorithm. 2440 specification A document where the algorithm is defined (if publicly 2441 available). 2443 The initial contents of the registry can be found in the following: 2444 Table 9, Table 8, Table 5, Table 7, Table 13, Table 14, Table 15. 2445 The specification column for all rows in that table should be this 2446 document. 2448 15.6. COSE Key Map Registry 2450 It is requested that IANA create a new registry entitled "COSE Key 2451 Map Registry". 2453 The columns of the registry are: 2455 name This is a descriptive name that enables easier reference to the 2456 item. It is not used in the encoding. 2458 label The value to be used to identify this algorithm. Key map 2459 labels MUST be unique. The label can be a positive integer, a 2460 negative integer or a string. Integer values between 0 and 255 2461 and strings of length 1 are designated as Standards Track Document 2462 required. Integer values from 256 to 65535 and strings of length 2463 2 are designated as Specification Required. Integer values of 2464 greater than 65535 and strings of length greater than 2 are 2465 designated as first come first server. Integer values in the 2466 range -1 to -65536 are used for key parameters specific to a 2467 single algorithm delegated to the "COSE Key Parameter Label" 2468 registry. Integer values beyond -65536 are marked as private use. 2470 CBOR Type This field contains the CBOR type for the field 2472 registry This field denotes the registry that values come from, if 2473 one exists. 2475 description This field contains a brief description for the field 2477 specification This contains a pointer to the public specification 2478 for the field if one exists 2480 This registry will be initially populated by the values in 2481 Section 7.1. The specification column for all of these entries will 2482 be this document. 2484 15.7. COSE Key Parameter Registry 2486 It is requested that IANA create a new registry "COSE Key 2487 Parameters". 2489 The columns of the table are: 2491 key type This field contains a descriptive string of a key type. 2492 This should be a value that is in the COSE General Values table 2493 and is placed in the 'kty' field of a COSE Key structure. 2495 name This is a descriptive name that enables easier reference to the 2496 item. It is not used in the encoding. 2498 label The label is to be unique for every value of key type. The 2499 range of values is from -256 to -1. Labels are expected to be 2500 reused for different keys. 2502 CBOR type This field contains the CBOR type for the field 2504 description This field contains a brief description for the field 2506 specification This contains a pointer to the public specification 2507 for the field if one exists 2509 This registry will be initially populated by the values in Table 20, 2510 Table 21, Table 22, and Table 23. The specification column for all 2511 of these entries will be this document. 2513 15.8. Media Type Registration 2515 15.8.1. COSE Security Message 2517 This section registers the "application/cose" and "application/ 2518 cose+cbor" media types in the "Media Types" registry. [CREF30] These 2519 media types are used to indicate that the content is a COSE_MSG. 2521 Type name: application 2523 Subtype name: cose 2525 Required parameters: N/A 2527 Optional parameters: N/A 2529 Encoding considerations: binary 2530 Security considerations: See the Security Considerations section 2531 of RFC TBD. 2533 Interoperability considerations: N/A 2535 Published specification: RFC TBD 2537 Applications that use this media type: To be identified 2539 Fragment identifier considerations: N/A 2541 Additional information: 2543 * Magic number(s): N/A 2545 * File extension(s): cbor 2547 * Macintosh file type code(s): N/A 2549 Person & email address to contact for further information: 2550 iesg@ietf.org 2552 Intended usage: COMMON 2554 Restrictions on usage: N/A 2556 Author: Jim Schaad, ietf@augustcellars.com 2558 Change Controller: IESG 2560 Provisional registration? No 2562 Type name: application 2564 Subtype name: cose+cbor 2566 Required parameters: N/A 2568 Optional parameters: N/A 2570 Encoding considerations: binary 2572 Security considerations: See the Security Considerations section 2573 of RFC TBD. 2575 Interoperability considerations: N/A 2577 Published specification: RFC TBD 2578 Applications that use this media type: To be identified 2580 Fragment identifier considerations: N/A 2582 Additional information: 2584 * Magic number(s): N/A 2586 * File extension(s): cbor 2588 * Macintosh file type code(s): N/A 2590 Person & email address to contact for further information: 2591 iesg@ietf.org 2593 Intended usage: COMMON 2595 Restrictions on usage: N/A 2597 Author: Jim Schaad, ietf@augustcellars.com 2599 Change Controller: IESG 2601 Provisional registration? No 2603 15.8.2. COSE Key media type 2605 This section registers the "application/cose+json" and "application/ 2606 cose-set+json" media types in the "Media Types" registry. These 2607 media types are used to indicate, respectively, that content is a 2608 COSE_Key or COSE_KeySet object. 2610 Type name: application 2612 Subtype name: cose-key+cbor 2614 Required parameters: N/A 2616 Optional parameters: N/A 2618 Encoding considerations: binary 2620 Security considerations: See the Security Considerations section 2621 of RFC TBD. 2623 Interoperability considerations: N/A 2625 Published specification: RFC TBD 2626 Applications that use this media type: To be identified 2628 Fragment identifier considerations: N/A 2630 Additional information: 2632 * Magic number(s): N/A 2634 * File extension(s): cbor 2636 * Macintosh file type code(s): N/A 2638 Person & email address to contact for further information: 2639 iesg@ietf.org 2641 Intended usage: COMMON 2643 Restrictions on usage: N/A 2645 Author: Jim Schaad, ietf@augustcellars.com 2647 Change Controller: IESG 2649 Provisional registration? No 2651 Type name: application 2653 Subtype name: cose-key-set+cbor 2655 Required parameters: N/A 2657 Optional parameters: N/A 2659 Encoding considerations: binary 2661 Security considerations: See the Security Considerations section 2662 of RFC TBD. 2664 Interoperability considerations: N/A 2666 Published specification: RFC TBD 2668 Applications that use this media type: To be identified 2670 Fragment identifier considerations: N/A 2672 Additional information: 2674 * Magic number(s): N/A 2676 * File extension(s): cbor 2678 * Macintosh file type code(s): N/A 2680 Person & email address to contact for further information: 2681 iesg@ietf.org 2683 Intended usage: COMMON 2685 Restrictions on usage: N/A 2687 Author: Jim Schaad, ietf@augustcellars.com 2689 Change Controller: IESG 2691 Provisional registration? No 2693 16. Security Considerations 2695 There are security considerations: 2697 1. Protect private keys 2699 2. MAC messages with more than one recipient means one cannot figure 2700 out who sent the message 2702 3. Use of direct key with other recipient structures hands the key 2703 to other recipients. 2705 4. Use of direct ECDH direct encryption is easy for people to leak 2706 information on if there are other recipients in the message. 2708 5. Considerations about protected vs unprotected header fields. 2710 17. References 2712 17.1. Normative References 2714 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2715 Requirement Levels", BCP 14, RFC 2119, March 1997. 2717 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2718 Representation (CBOR)", RFC 7049, October 2013. 2720 17.2. Informative References 2722 [AES-GCM] Dworkin, M., "NIST Special Publication 800-38D: 2723 Recommendation for Block Cipher Modes of Operation: 2724 Galois/Counter Mode (GCM) and GMAC.", Nov 2007. 2726 [DSS] U.S. National Institute of Standards and Technology, 2727 "Digital Signature Standard (DSS)", July 2013. 2729 [I-D.greevenbosch-appsawg-cbor-cddl] 2730 Vigano, C., Birkholz, H., and R. Sun, "CBOR data 2731 definition language: a notational convention to express 2732 CBOR data structures.", draft-greevenbosch-appsawg-cbor- 2733 cddl-05 (work in progress), March 2015. 2735 [I-D.irtf-cfrg-curves] 2736 Langley, A. and R. Salz, "Elliptic Curves for Security", 2737 draft-irtf-cfrg-curves-02 (work in progress), March 2015. 2739 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 2740 McGrew, D., Foley, J., and K. Paterson, "Authenticated 2741 Encryption with AES-CBC and HMAC-SHA", draft-mcgrew-aead- 2742 aes-cbc-hmac-sha2-05 (work in progress), July 2014. 2744 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 2745 Hashing for Message Authentication", RFC 2104, February 2746 1997. 2748 [RFC2633] Ramsdell, B., "S/MIME Version 3 Message Specification", 2749 RFC 2633, June 1999. 2751 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 2752 (AES) Key Wrap Algorithm", RFC 3394, September 2002. 2754 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 2755 Standards (PKCS) #1: RSA Cryptography Specifications 2756 Version 2.1", RFC 3447, February 2003. 2758 [RFC3610] Whiting, D., Housley, R., and N. Ferguson, "Counter with 2759 CBC-MAC (CCM)", RFC 3610, September 2003. 2761 [RFC4231] Nystrom, M., "Identifiers and Test Vectors for HMAC-SHA- 2762 224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512", RFC 2763 4231, December 2005. 2765 [RFC4262] Santesson, S., "X.509 Certificate Extension for Secure/ 2766 Multipurpose Internet Mail Extensions (S/MIME) 2767 Capabilities", RFC 4262, December 2005. 2769 [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, 2770 "Elliptic Curve Cryptography Subject Public Key 2771 Information", RFC 5480, March 2009. 2773 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 2774 RFC 5652, September 2009. 2776 [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet 2777 Mail Extensions (S/MIME) Version 3.2 Message 2778 Specification", RFC 5751, January 2010. 2780 [RFC5752] Turner, S. and J. Schaad, "Multiple Signatures in 2781 Cryptographic Message Syntax (CMS)", RFC 5752, January 2782 2010. 2784 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 2785 Key Derivation Function (HKDF)", RFC 5869, May 2010. 2787 [RFC5990] Randall, J., Kaliski, B., Brainard, J., and S. Turner, 2788 "Use of the RSA-KEM Key Transport Algorithm in the 2789 Cryptographic Message Syntax (CMS)", RFC 5990, September 2790 2010. 2792 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 2793 Curve Cryptography Algorithms", RFC 6090, February 2011. 2795 [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations 2796 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 2797 RFC 6151, March 2011. 2799 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 2800 Interchange Format", RFC 7159, March 2014. 2802 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2803 Signature (JWS)", RFC 7515, May 2015. 2805 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 2806 RFC 7516, May 2015. 2808 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, May 2015. 2810 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, May 2811 2015. 2813 [SEC1] Standards for Efficient Cryptography Group, "SEC 1: 2814 Elliptic Curve Cryptography", May 2009. 2816 [SP800-56A] 2817 Barker, E., Chen, L., Roginsky, A., and M. Smid, "NIST 2818 Special Publication 800-56A: Recommendation for Pair-Wise 2819 Key Establishment Schemes Using Discrete Logarithm 2820 Cryptography", May 2013. 2822 Appendix A. AEAD and AE algorithms 2824 The set of encryption algorithms that can be used with this 2825 specification is restricted to authenticated encryption (AE) and 2826 authenticated encryption with additional data (AEAD) algorithms. 2827 This means that there is a strong check that the data decrypted by 2828 the recipient is the same as what was encrypted by the sender. 2829 Encryption modes such as counter have no check on this at all. The 2830 CBC encryption mode had a weak check that the data is correct, given 2831 a random key and random data, the CBC padding check will pass one out 2832 of 256 times. There have been several times that a normal encryption 2833 mode has been combined with an integrity check to provide a content 2834 encryption mode that does provide the necessary authentication. AES- 2835 GCM [AES-GCM], AES-CCM [RFC3610], AES-CBC-HMAC 2836 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] are examples of these composite 2837 modes. 2839 PKCS v1.5 RSA key transport does not qualify as an AE algorithm. 2840 There are only three bytes in the encoding that can be checked as 2841 having decrypted correctly, the rest of the content can only be 2842 probabilistically checked as having decrypted correctly. For this 2843 reason, PKCS v1.5 RSA key transport MUST NOT be used with this 2844 specification. RSA-OAEP was designed to have the necessary checks 2845 that that content correctly decrypted and does qualify as an AE 2846 algorithm. 2848 When dealing with authenticated encryption algorithms, there is 2849 always some type of value that needs to be checked to see if the 2850 authentication level has passed. This authentication value may be: 2852 o A separately generated tag computed by both the encrypter and 2853 decrypter and then compared by the decryptor. This tag value may 2854 be either placed at the end of the cipher text (the decision we 2855 made) or kept separately (the decision made by the JOSE working 2856 group). This is the approach followed by AES-GCM [AES-GCM] and 2857 AES-CCM [RFC3610]. 2859 o A fixed value that is part of the encoded plain text. This is the 2860 approach followed by the AES key wrap algorithm [RFC3394]. 2862 o A computed value is included as part of the encoded plain text. 2863 The computed value is then checked by the decryptor using the same 2864 computation path. This is the approach followed by RSAES-OAEP 2865 [RFC3447]. 2867 Appendix B. Three Levels of Recipient Information 2869 All of the currently defined Key Management methods only use two 2870 levels of the COSE_Encrypt structure. The first level is the message 2871 content and the second level is the content key encryption. However, 2872 if one uses a key management technique such as RSA-KEM (see 2873 Appendix A of RSA-KEM [RFC5990], then it make sense to have three 2874 levels of the COSE_Encrypt structure. 2876 These levels would be: 2878 o Level 0: The content encryption level. This level contains the 2879 payload of the message. 2881 o Level 1: The encryption of the CEK by a KEK. 2883 o Level 2: The encryption of a long random secret using an RSA key 2884 and a key derivation function to convert that secret into the KEK. 2886 This is an example of what a triple layer message would look like. 2887 The message has the following layers: 2889 o Level 0: Has a content encrypted with AES-GCM using a 128-bit key. 2891 o Level 1: Uses the AES Key wrap algorithm with a 128-bit key. 2893 o Level 3: Uses ECDH Ephemeral-Static direct to generate the level 1 2894 key. 2896 In effect this example is a decomposed version of using the ECDH- 2897 ES+A128KW algorithm. 2899 { 2900 1: 2, 2901 2: h'a10101', 2902 3: { 2903 -1: h'02d1f7e6f26c43d4868d87ce' 2904 }, 2905 4: h'64f84d913ba60a76070a9a48f26e97e863e285295a44320878caceb076 2906 3a334806857c67', 2907 9: [ 2908 { 2909 3: { 2910 1: -3 2911 }, 2912 4: h'5a15dbf5b282ecb31a6074ee3815c252405dd7583e078188', 2913 9: [ 2914 { 2915 3: { 2916 1: "ECDH-ES", 2917 5: h'6d65726961646f632e6272616e64796275636b406275636b 2918 6c616e642e6578616d706c65', 2919 4: { 2920 1: 1, 2921 -1: 4, 2922 -2: h'b2add44368ea6d641f9ca9af308b4079aeb519f11e9b8 2923 a55a600b21233e86e68', 2924 -3: h'1a2cf118b9ee6895c8f415b686d4ca1cef362d4a7630a 2925 31ef6019c0c56d33de0' 2926 } 2927 } 2928 } 2929 ] 2930 } 2931 ] 2932 } 2934 Appendix C. Examples 2936 The examples can be found at https://github.com/cose-wg/Examples. I 2937 am currently still in the process of getting the examples up there 2938 along with some control information for people to be able to check 2939 and reproduce the examples. 2941 Examples may have some features that are in questions but not yet 2942 incorporated in the document. 2944 To make it easier to read, the examples are presented using the 2945 CBOR's diagnostic notation rather than a binary dump. [CREF31] Using 2946 the Ruby based CBOR diagnostic tools at ????, the diagnostic notation 2947 can be converted into binary files using the following command line: 2948 (install command is?...) 2950 diag2cbor < inputfile > outputfile 2952 The examples can be extracted from the XML version of this docuent 2953 via an XPath expression as all of the artwork is tagged with the 2954 attribute type='CBORdiag'. 2956 C.1. Examples of MAC messages 2958 C.1.1. Shared Secret Direct MAC 2960 This example users the following: 2962 o MAC: AES-CMAC, 256-bit key, trucated to 64 bits 2964 o Key management: direct shared secret 2966 o File name: Mac-04 2968 { 2969 1: 3, 2970 2: h'a1016f4145532d434d41432d3235362f3634', 2971 4: h'546869732069732074686520636f6e74656e742e', 2972 10: h'd9afa663dd740848', 2973 9: [ 2974 { 2975 3: { 2976 1: -6, 2977 5: h'6f75722d736563726574' 2978 } 2979 } 2980 ] 2981 } 2983 C.1.2. ECDH Direct MAC 2985 This example uses the following: 2987 o MAC: HMAC w/SHA-256, 256-bit key [CREF32] 2989 o Key management: ECDH key agreement, two static keys, HKDF w/ 2990 context structure 2992 { 2993 1: 3, 2994 2: h'a10104', 2995 4: h'546869732069732074686520636f6e74656e742e', 2996 10: h'2ba937ca03d76c3dbad30cfcbaeef586f9c0f9ba616ad67e9205d3857 2997 6ad9930', 2998 9: [ 2999 { 3000 3: { 3001 1: "ECDH-SS", 3002 5: h'6d65726961646f632e6272616e64796275636b406275636b6c61 3003 6e642e6578616d706c65', 3004 "spk": { 3005 "kid": "peregrin.took@tuckborough.example" 3006 }, 3007 "apu": h'4d8553e7e74f3c6a3a9dd3ef286a8195cbf8a23d19558ccf 3008 ec7d34b824f42d92bd06bd2c7f0271f0214e141fb779ae2856abf585a58368b01 3009 7e7f2a9e5ce4db5' 3010 } 3011 } 3012 ] 3013 } 3015 C.1.3. Wrapped MAC 3017 This example uses the following: 3019 o MAC: AES-MAC, 128-bit key, truncated to 64 bits 3021 o Key management: AES keywrap w/ a pre-shared 256-bit key 3023 { 3024 1: 3, 3025 2: h'a1016e4145532d3132382d4d41432d3634', 3026 4: h'546869732069732074686520636f6e74656e742e', 3027 10: h'6d1fa77b2dd9146a', 3028 9: [ 3029 { 3030 3: { 3031 1: -5, 3032 5: h'30313863306165352d346439622d343731622d626664362d6565 3033 66333134626337303337' 3034 }, 3035 4: h'711ab0dc2fc4585dce27effa6781c8093eba906f227b6eb0' 3036 } 3037 ] 3038 } 3040 C.1.4. Multi-recipient MAC message 3042 This example uses the following: 3044 o MAC: HMAC w/ SHA-256, 128-bit key 3046 o Key management: Uses three different methods 3048 1. ECDH Ephemeral-Static, Curve P-521, AES-Key Wrap w/ 128-bit 3049 key 3051 2. RSA-OAEP w/ SHA-256 3053 3. AES-Key Wrap w/ 256-bit key 3055 { 3056 1: 3, 3057 2: h'a10104', 3058 4: h'546869732069732074686520636f6e74656e742e', 3059 10: h'7aaa6e74546873061f0a7de21ff0c0658d401a68da738dd8937486519 3060 83ce1d0', 3061 9: [ 3062 { 3063 3: { 3064 1: "ECDH-ES+A128KW", 3065 5: h'62696c626f2e62616767696e7340686f626269746f6e2e657861 3066 6d706c65', 3067 4: { 3068 1: 1, 3069 -1: 5, 3070 -2: h'43b12669acac3fd27898ffba0bcd2e6c366d53bc4db71f909 3071 a759304acfb5e18cdc7ba0b13ff8c7636271a6924b1ac63c02688075b55ef2d61 3072 3574e7dc242f79c3', 3073 -3: h'812dd694f4ef32b11014d74010a954689c6b6e8785b333d1a 3074 b44f22b9d1091ae8fc8ae40b687e5cfbe7ee6f8b47918a07bb04e9f5b1a51a334 3075 a16bc09777434113' 3076 } 3077 }, 3078 4: h'1b120c848c7f2f8943e402cbdbdb58efb281753af4169c70d0126c 3079 0d16436277160821790ef4fe3f' 3080 }, 3081 { 3082 3: { 3083 1: -2, 3084 5: h'62696c626f2e62616767696e7340686f626269746f6e2e657861 3085 6d706c65' 3086 }, 3087 4: h'46c4f88069b650909a891e84013614cd58a3668f88fa18f3852940 3089 a20b35098591d3aacf91c125a2595cda7bee75a490579f0e2f20fd6bc956623bf 3090 de3029c318f82c426dac3463b261c981ab18b72fe9409412e5c7f2d8f2b5abaf7 3091 80df6a282db033b3a863fa957408b81741878f466dcc437006ca21407181a016c 3092 a608ca8208bd3c5a1ddc828531e30b89a67ec6bb97b0c3c3c92036c0cb84aa0f0 3093 ce8c3e4a215d173bfa668f116ca9f1177505afb7629a9b0b5e096e81d37900e06 3094 f561a32b6bc993fc6d0cb5d4bb81b74e6ffb0958dac7227c2eb8856303d989f93 3095 b4a051830706a4c44e8314ec846022eab727e16ada628f12ee7978855550249cc 3096 b58' 3097 }, 3098 { 3099 3: { 3100 1: -5, 3101 5: h'30313863306165352d346439622d343731622d626664362d6565 3102 66333134626337303337' 3103 }, 3104 4: h'0b2c7cfce04e98276342d6476a7723c090dfdd15f9a518e7736549 3105 e998370695e6d6a83b4ae507bb' 3106 } 3107 ] 3108 } 3110 C.2. Examples of Encrypted Messages 3112 C.2.1. Direct ECDH 3114 This example uses the following: 3116 o CEK: AES-GCM w/ 128-bit key 3118 o Key managment: ECDH Ephemeral-Static, Curve P-256 3119 { 3120 1: 2, 3121 2: h'a10101', 3122 3: { 3123 -1: h'c9cf4df2fe6c632bf7886413' 3124 }, 3125 4: h'45fce2814311024d3a479e7d3eed063850f3f0b9f3f948677e3ae9869b 3126 cf9ff4e1763812', 3127 9: [ 3128 { 3129 3: { 3130 1: "ECDH-ES", 3131 5: h'6d65726961646f632e6272616e64796275636b406275636b6c61 3132 6e642e6578616d706c65', 3133 4: { 3134 1: 1, 3135 -1: 4, 3136 -2: h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf05 3137 4e1c7b4d91d6280', 3138 -3: h'f01400b089867804b8e9fc96c3932161f1934f4223069170d 3139 924b7e03bf822bb' 3140 } 3141 } 3142 } 3143 ] 3144 } 3146 C.2.2. Direct plus Key Derivation 3148 This example uses the following: 3150 o CEK: AES-CCM w/128-bit key, trucate the tag to 64-bits 3152 o Key managment: Use HKDF on a shared secret with the following 3153 implicit fields as part of the context. 3155 * APU identity: "lighting-client" 3157 * APV identity: "lighting-server" 3159 * Supplimentary Public Other: "Encryption Example 02" 3161 { 3162 1: 2, 3163 2: h'a1016e4145532d43434d2d3132382f3634', 3164 3: { 3165 -1: h'8f2720f78dce2737ae61a4fa' 3166 }, 3167 4: h'0159973c5d790041cf54be80412b3d12a7be30f6b64193d3bb51dfec', 3168 9: [ 3169 { 3170 3: { 3171 1: "dir+kdf", 3172 5: h'6f75722d736563726574', 3173 -10: h'61616262636364646565666667676868' 3174 } 3175 } 3176 ] 3177 } 3179 C.3. Examples of Signed Message 3181 C.3.1. Single Signature 3183 This example uses the following: 3185 o Signature Algorithm: RSA-PSS w/ SHA-384, MGF-1 3187 { 3188 1: 1, 3189 4: h'546869732069732074686520636f6e74656e742e', 3190 5: [ 3191 { 3192 2: h'a20165505333383405581e62696c626f2e62616767696e7340686f 3193 626269746f6e2e6578616d706c65', 3194 6: h'1b22515f96fd798a331c7b156e90bfea7f558ec6de840e05a8e5f4 3195 b7be44ea1451c48517da7fd216c6143898673c232a96937ebcfb88264a58f5995 3196 82d89cf8a4f20ef35fbfcfd2aad46ad8b99ea6425367afd898de1b712d558b0d2 3197 49d6d180d0b1fb7256140ec3553556f3b5b95a49931a75998dfc23ca905efc7d8 3198 e04deeb92d5936c0824e535aa344396f73913d8a65de0010600270ae5df7f5c8d 3199 52ae525a7642d4c4ff9e219acaa52fd933df003be36b9e3c77ced37129d66745e 3200 2a42baa3d0b3f2675cd51ae8a64fd024d126be5396c91b9236fb5f8548d09881b 3201 b5d40a61c0d342bed9fe8058f36b8722b9e8465dc3b8bfa4f2fd138ce186b73e4 3202 082' 3203 } 3204 ] 3205 } 3207 C.3.2. Multiple Signers 3209 This example uses the following: 3211 o Signature Algorithm: RSA-PSS w/ SHA-256, MGF-1 3213 o Signature Algorithm: ECDSA w/ SHA-512, Curve P-521 3215 { 3216 1: 1, 3217 4: h'546869732069732074686520636f6e74656e742e', 3218 5: [ 3219 { 3220 2: h'a10129', 3221 3: { 3222 5: h'62696c626f2e62616767696e7340686f626269746f6e2e657861 3223 6d706c65' 3224 }, 3225 6: h'028947ac3521f66f2506013007e2cd7b0cb09a209e76ab5b95f751 3226 eb63f5730f1672a282419c49b9653d742577fb6a6cea9ab2e1d4d5d9e786e2240 3227 4760663cc74a1c2c90160af92628e1ebbc3eeba552f757054b691ab17271396b7 3228 ff2d86c100b94a2fce0438c0b50ca70bcdd3074a0f8dc40c2e44e9b26e9093287 3229 b7245ee13171b28ea0f3e291c2cca64aa17f7094aee2be02b5fe5cd2cf343e18c 3230 eec0c763cb76a128df9a9cbfc37b835f6467d98d74505eee1dccc9e6ebf2405ea 3231 1329b41a33eeb13f1bbef3a272e42b3df96cdaea9016663e31ddff4603eb66a88 3232 5c583b53977c1fb9707550717d7387f84616a6670e27d4007b08879109aaf3720 3233 f33' 3234 }, 3235 { 3236 3: { 3237 1: -9, 3238 5: h'62696c626f2e62616767696e7340686f626269746f6e2e657861 3239 6d706c65' 3240 }, 3241 6: h'0195345953742c6725352a13cdc55402c895133525c9a3b16bb47d 3242 02ca5f57f8a34aebf47298c602a8feb1dd71d1936886f21029a4142abf38c3aa3 3243 94b3597c2f35c01987c801edc7022c8fddacbf25bc8794b9ffb7cb27f9f346ba4 3244 4db6f5c9b60406530f62b378c5da3e7e2259327f4e55f48271873496497724492 3245 d90ba67a4b65112' 3246 } 3247 ] 3248 } 3250 Appendix D. COSE Header Algorithm Label Table 3252 This section disappears when we make a decision on password based key 3253 management. 3255 +------+-----------+-------+-----------+-------------+ 3256 | name | algorithm | label | CBOR type | description | 3257 +------+-----------+-------+-----------+-------------+ 3258 | p2c | PBE | -1 | int | | 3259 | | | | | | 3260 | p2s | PBE | -2 | bstr | | 3261 +------+-----------+-------+-----------+-------------+ 3263 Appendix E. Document Updates 3265 E.1. Version -01 to -02 3267 o Add a set of straw man proposals for algorithms. It is possible/ 3268 expected that this text will be moved to a new document. 3270 o Add a set of straw man proposals for key structures. It is 3271 possible/expected that this text will be moved to a new document. 3273 E.2. Version -00 to -01 3275 o Add note on where the document is being maintained and 3276 contributing notes. 3278 o Put in proposal on MTI algorithms. 3280 o Changed to use labels rather than keys when talking about what 3281 indexes a map. 3283 o Moved nonce/IV to be a common header item. 3285 o Expand section to discuss the common set of labels used in 3286 COSE_Key maps. 3288 o Start marking element 0 in registries as reserved. 3290 o Update examples. 3292 Editorial Comments 3294 [CREF1] JLS: Need to check this list for correctness before publishing. 3296 [CREF2] JLS: I have not gone through the document to determine what 3297 needs to be here yet. We mostly want to grab terms which are 3298 used in unusual ways or are not generally understood. 3300 [CREF3] JLS: It would be possible to extend this section to talk about 3301 those decisions which an application needs to think about rather 3302 than just talking about MTI algoithms. 3304 [CREF4] JLS: I have moved msg_type into the individual structures. 3305 However, they would not be necessary in the cases where a) the 3306 security service is known and b) security libraries can setup to 3307 take individual structures. Should they be moved back to just 3308 appearing if used in a COSE_MSG rather than on the individual 3309 structure? 3311 [CREF5] JLS: Should we create an IANA registries for the values of 3312 msg_type? 3314 [CREF6] JLS: OPEN ISSUE 3316 [CREF7] JLS: A completest version of this grammar would list the options 3317 available in the protected and unprotected headers. Do we want 3318 to head that direction? 3320 [CREF8] JLS: After looking at this, I am wondering if the type for this 3321 should be: [int int]/[int tstr] so that we can keep the major/ 3322 minor difference of media-types. This does cost a couple of 3323 bytes in the message. 3325 [CREF9] JLS: Need to figure out how we are going to go about creating 3326 this registry -or are we going to modify the current mime- 3327 content table? 3329 [CREF10] JLS: Open to do. 3331 [CREF11] JLS: Should be able to move much of this text into the headers 3332 section and just do a refer to that text from here. 3334 [CREF12] JLS: Should be able to move much of this text into the headers 3335 section and just do a refer to that text from here. 3337 [CREF13] Ilari: I don't follow/understand this text 3339 [CREF14] JLS: Should this sentence be removed? 3341 [CREF15] JLS: Do we remove this line and just define them ourselves? 3343 [CREF16] JLS: We can really simplify the grammar for COSE_Key to be just 3344 the kty (the one required field) and the generic item. The 3345 reason to do this is that it makes things simpler. The reason 3346 not to do this says that we really need to add a lot more items 3347 so that a grammar check can be done that is more tightly 3348 enforced. 3350 [CREF17] JLS: Unless key material is being derived for multiple items 3351 (i.e both a key and an IV) this will be the COSE algorithm 3352 value. Even then it might still be the COSE algorithm value, 3353 it is just a requirement for a new algorithm. Do we want to 3354 have the ability to derive both the key and a partial IV for 3355 CCM? 3357 [CREF18] JLS: I need to get a better justification for this item. It 3358 has to do with generating new keys for each message in a series 3359 of messages that have the same salt value. 3361 [CREF19] JLS: It would be reasonable to support a shared-secret + KDF 3362 that is not PBE for when one has good randomness in the shared- 3363 secret. 3365 [CREF20] JLS: Do we also want to document the use of RFC 5649 as well? 3366 It allows for other sizes of keys that might be used for HMAC - 3367 i.e. a 200 bit key. The algorithm exists, but I do not 3368 personally know of any standard uses of it. 3370 [CREF21] JLS: Is this range we want to specify? 3372 [CREF22] JLS: Does anybody need pure DH? 3374 [CREF23] JLS: This could just as easily be done by specifying two 3375 different set of algorithm identifiers, one for each of the key 3376 formats. I don't believe that we need to set things up by 3377 having two different sets of algorithm identifiers for the 3378 different keys as the structure of what is represented is going 3379 to be the same, just the math and point formats are going to be 3380 different. The other "difference" is the question of how the 3381 octet string of the shared secret is defined. However, since 3382 we don't need to specify either in this document we can defer 3383 both of them into their respective documents. 3385 [CREF24] JLS: It would be possible to include the protected field in the 3386 KDF rather than the key wrap algorithm if we wanted to. This 3387 would provide the same level of security, it would not be 3388 possible to get the same key if they are different. 3390 [CREF25] JLS: Do we want/need to support this? JOSE did it mainly to 3391 support the encryption of private keys. 3393 [CREF26] JLS: Do we create a registry for curves? Is is the same 3394 registry for both EC1 and EC2? 3396 [CREF27] JLS: Should we use the integer encoding for x and d instead of 3397 bstr? 3399 [CREF28] JLS: Should we use the integer encoding for x, y and d instead 3400 of bstr? 3402 [CREF29] JLS: Finish the registration process. 3404 [CREF30] JLS: Should we register both or just the cose+cbor one? 3406 [CREF31] JLS: Do we want to keep this as diagnostic notation or should 3407 we switch to having "binary" examples instead? 3409 [CREF32] JLS: Need to examine how this is worked out. In this case the 3410 length of the key to be used is implicit rather than explicit. 3411 This needs to be the case because a direct key could be any 3412 length, however it means that when the key is derived, there is 3413 currently nothing to state how long the derived key needs to 3414 be. 3416 Author's Address 3418 Jim Schaad 3419 August Cellars 3421 Email: ietf@augustcellars.com