idnits 2.17.1 draft-ietf-cose-msg-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 8 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 616 has weird spacing: '...otected is de...' == Line 618 has weird spacing: '...otected is de...' == Line 620 has weird spacing: '...payload conta...' == Line 628 has weird spacing: '...natures is an...' == Line 634 has weird spacing: '...otected is de...' == (19 more instances...) -- The document date (October 17, 2015) is 3111 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'CREF1' is mentioned on line 3780, but not defined == Missing Reference: 'CREF2' is mentioned on line 3782, but not defined == Missing Reference: 'CREF3' is mentioned on line 3786, but not defined == Missing Reference: 'CREF4' is mentioned on line 3790, but not defined == Missing Reference: 'CREF5' is mentioned on line 3794, but not defined == Missing Reference: 'CREF6' is mentioned on line 3799, but not defined == Missing Reference: 'CREF7' is mentioned on line 3806, but not defined == Missing Reference: 'CREF8' is mentioned on line 3810, but not defined == Missing Reference: 'CREF9' is mentioned on line 3812, but not defined == Unused Reference: 'MultiPrimeRSA' is defined on line 3033, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-11) exists of draft-greevenbosch-appsawg-cbor-cddl-05 -- Obsolete informational reference (is this intentional?): RFC 2633 (Obsoleted by RFC 3851) -- Obsolete informational reference (is this intentional?): RFC 2898 (Obsoleted by RFC 8018) -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) -- Obsolete informational reference (is this intentional?): RFC 5751 (Obsoleted by RFC 8551) -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) -- Obsolete informational reference (is this intentional?): RFC 7539 (Obsoleted by RFC 8439) Summary: 2 errors (**), 0 flaws (~~), 18 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 COSE Working Group J. Schaad 3 Internet-Draft August Cellars 4 Intended status: Informational October 17, 2015 5 Expires: April 19, 2016 7 CBOR Encoded Message Syntax 8 draft-ietf-cose-msg-06 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 . Instructions are on that page as well. 23 Editorial changes can be managed in GitHub, but any substantial 24 issues need to be discussed on the COSE 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 April 19, 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 . . . . . . . . . . . . . . . . 5 62 1.2. Requirements Terminology . . . . . . . . . . . . . . . . 5 63 1.3. CBOR Grammar . . . . . . . . . . . . . . . . . . . . . . 6 64 1.4. CBOR Related Terminology . . . . . . . . . . . . . . . . 6 65 1.5. Document Terminology . . . . . . . . . . . . . . . . . . 7 66 1.6. Mandatory to Implement Algorithms . . . . . . . . . . . . 7 67 2. Basic COSE Structure . . . . . . . . . . . . . . . . . . . . 8 68 3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 8 69 3.1. Common COSE Headers Parameters . . . . . . . . . . . . . 10 70 4. Signing Structure . . . . . . . . . . . . . . . . . . . . . . 13 71 4.1. Externally Supplied Data . . . . . . . . . . . . . . . . 15 72 4.2. Signing and Verification Process . . . . . . . . . . . . 15 73 4.3. Computing Counter Signatures . . . . . . . . . . . . . . 17 74 5. Encryption objects . . . . . . . . . . . . . . . . . . . . . 18 75 5.1. Enveloped COSE structure . . . . . . . . . . . . . . . . 18 76 5.1.1. Recipient Algorithm Classes . . . . . . . . . . . . . 19 77 5.2. Encrypted COSE structure . . . . . . . . . . . . . . . . 20 78 5.3. Encryption Algorithm for AEAD algorithms . . . . . . . . 20 79 5.4. Encryption algorithm for AE algorithms . . . . . . . . . 21 80 6. MAC objects . . . . . . . . . . . . . . . . . . . . . . . . . 22 81 6.1. How to compute a MAC . . . . . . . . . . . . . . . . . . 23 82 7. Key Structure . . . . . . . . . . . . . . . . . . . . . . . . 24 83 7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 24 84 8. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 27 85 8.1. ECDSA . . . . . . . . . . . . . . . . . . . . . . . . . . 28 86 8.1.1. Security Considerations . . . . . . . . . . . . . . . 29 87 9. Message Authentication (MAC) Algorithms . . . . . . . . . . . 30 88 9.1. Hash-based Message Authentication Codes (HMAC) . . . . . 30 89 9.1.1. Security Considerations . . . . . . . . . . . . . . . 31 90 9.2. AES Message Authentication Code (AES-CBC-MAC) . . . . . . 32 91 9.2.1. Security Considerations . . . . . . . . . . . . . . . 32 92 10. Content Encryption Algorithms . . . . . . . . . . . . . . . . 33 93 10.1. AES GCM . . . . . . . . . . . . . . . . . . . . . . . . 33 94 10.1.1. Security Considerations . . . . . . . . . . . . . . 34 95 10.2. AES CCM . . . . . . . . . . . . . . . . . . . . . . . . 34 96 10.2.1. Security Considerations . . . . . . . . . . . . . . 37 97 10.3. ChaCha20 and Poly1305 . . . . . . . . . . . . . . . . . 37 98 10.3.1. Security Considerations . . . . . . . . . . . . . . 38 99 11. Key Derivation Functions (KDF) . . . . . . . . . . . . . . . 38 100 11.1. HMAC-based Extract-and-Expand Key Derivation Function 101 (HKDF) . . . . . . . . . . . . . . . . . . . . . . . . . 39 102 11.2. Context Information Structure . . . . . . . . . . . . . 40 103 12. Recipient Algorithm Classes . . . . . . . . . . . . . . . . . 44 104 12.1. Direct Encryption . . . . . . . . . . . . . . . . . . . 44 105 12.1.1. Direct Key . . . . . . . . . . . . . . . . . . . . . 45 106 12.1.2. Direct Key with KDF . . . . . . . . . . . . . . . . 45 107 12.2. Key Wrapping . . . . . . . . . . . . . . . . . . . . . . 47 108 12.2.1. AES Key Wrapping . . . . . . . . . . . . . . . . . . 47 109 12.3. Key Encryption . . . . . . . . . . . . . . . . . . . . . 48 110 12.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 48 111 12.4.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 49 112 12.5. Key Agreement with KDF . . . . . . . . . . . . . . . . . 53 113 12.5.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 53 114 13. Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 115 13.1. Elliptic Curve Keys . . . . . . . . . . . . . . . . . . 54 116 13.1.1. Double Coordinate Curves . . . . . . . . . . . . . . 54 117 13.2. Symmetric Keys . . . . . . . . . . . . . . . . . . . . . 55 118 14. CBOR Encoder Restrictions . . . . . . . . . . . . . . . . . . 56 119 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 56 120 15.1. CBOR Tag assignment . . . . . . . . . . . . . . . . . . 56 121 15.2. COSE Header Parameter Registry . . . . . . . . . . . . . 57 122 15.3. COSE Header Algorithm Label Table . . . . . . . . . . . 58 123 15.4. COSE Algorithm Registry . . . . . . . . . . . . . . . . 58 124 15.5. COSE Key Common Parameter Registry . . . . . . . . . . . 59 125 15.6. COSE Key Type Parameter Registry . . . . . . . . . . . . 60 126 15.7. COSE Elliptic Curve Registry . . . . . . . . . . . . . . 60 127 15.8. Media Type Registrations . . . . . . . . . . . . . . . . 61 128 15.8.1. COSE Security Message . . . . . . . . . . . . . . . 61 129 15.8.2. COSE Key media type . . . . . . . . . . . . . . . . 63 130 15.9. CoAP Content Format Registrations . . . . . . . . . . . 65 131 16. Security Considerations . . . . . . . . . . . . . . . . . . . 65 132 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 66 133 17.1. Normative References . . . . . . . . . . . . . . . . . . 66 134 17.2. Informative References . . . . . . . . . . . . . . . . . 66 135 Appendix A. CDDL Grammar . . . . . . . . . . . . . . . . . . . . 68 136 Appendix B. Three Levels of Recipient Information . . . . . . . 69 137 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 70 138 C.1. Examples of MAC messages . . . . . . . . . . . . . . . . 71 139 C.1.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 71 140 C.1.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 72 141 C.1.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 73 142 C.1.4. Multi-recipient MAC message . . . . . . . . . . . . . 74 143 C.2. Examples of Encrypted Messages . . . . . . . . . . . . . 75 144 C.2.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 75 145 C.2.2. Direct plus Key Derivation . . . . . . . . . . . . . 76 146 C.3. Examples of Signed Message . . . . . . . . . . . . . . . 77 147 C.3.1. Single Signature . . . . . . . . . . . . . . . . . . 77 148 C.3.2. Multiple Signers . . . . . . . . . . . . . . . . . . 78 149 C.4. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 78 150 C.4.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 78 151 C.4.2. Private Keys . . . . . . . . . . . . . . . . . . . . 81 152 Appendix D. Document Updates . . . . . . . . . . . . . . . . . . 82 153 D.1. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 82 154 D.2. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 83 155 D.3. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 83 156 D.4. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 83 157 D.5. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 83 158 D.6. Version -01 to -2 . . . . . . . . . . . . . . . . . . . . 84 159 D.7. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 84 160 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 85 162 1. Introduction 164 There has been an increased focus on the small, constrained devices 165 that make up the Internet of Things (IOT). One of the standards that 166 has come out of this process is the Concise Binary Object 167 Representation (CBOR). CBOR extended the data model of the 168 JavaScript Object Notation (JSON) by allowing for binary data among 169 other changes. CBOR is being adopted by several of the IETF working 170 groups dealing with the IOT world as their encoding of data 171 structures. CBOR was designed specifically to be both small in terms 172 of messages transport and implementation size as well having a schema 173 free decoder. A need exists to provide basic message security 174 services for IOT and using CBOR as the message encoding format makes 175 sense. 177 The JOSE working group produced a set of documents 178 [RFC7515][RFC7516][RFC7517][RFC7518] that defined how to perform 179 encryption, signatures and message authentication (MAC) operations 180 for JSON documents and then to encode the results using the JSON 181 format [RFC7159]. This document does the same work for use with the 182 CBOR [RFC7049] document format. While there is a strong attempt to 183 keep the flavor of the original JOSE documents, two considerations 184 are taken into account: 186 o CBOR has capabilities that are not present in JSON and should be 187 used. One example of this is the fact that CBOR has a method of 188 encoding binary directly without first converting it into a base64 189 encoded string. 191 o COSE is not a direct copy of the JOSE specification. In the 192 process of creating COSE, decisions that were made for JOSE were 193 re-examined. In many cases different results were decided on as 194 the criteria were not always the same as for JOSE. 196 1.1. Design changes from JOSE 198 o Define a top level message structure so that encrypted, signed and 199 MACed messages can easily identified and still have a consistent 200 view. 202 o Signed messages separate the concept of protected and unprotected 203 parameters that are for the content and the signature. 205 o Recipient processing has been made more uniform. A recipient 206 structure is required for all recipients rather than only for 207 some. 209 o MAC messages are separated from signed messages. 211 o MAC messages have the ability to do use all recipient algorithms 212 on the MAC authentication key. 214 o Use binary encodings for binary data rather than base64url 215 encodings. 217 o Combine the authentication tag for encryption algorithms with the 218 ciphertext. 220 o Remove the flattened mode of encoding. Forcing the use of an 221 array of recipients at all times forces the message size to be two 222 bytes larger, but one gets a corresponding decrease in the 223 implementation size that should compensate for this. [CREF1] 225 1.2. Requirements Terminology 227 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 228 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 229 "OPTIONAL" in this document are to be interpreted as described in 230 [RFC2119]. 232 When the words appear in lower case, their natural language meaning 233 is used. 235 1.3. CBOR Grammar 237 There currently is no standard CBOR grammar available for use by 238 specifications. We therefore describe the CBOR structures in prose. 239 There is a version of a CBOR grammar in the CBOR Data Definition 240 Language (CDDL) [I-D.greevenbosch-appsawg-cbor-cddl]. An 241 informational version of the CBOR grammar that reflects what is in 242 the prose can be found in Appendix A. CDDL has not been fixed, so 243 this grammar may will only work with the version of CDDL at the time 244 of publishing. 246 The document was developed by first working on the grammar and then 247 developing the prose to go with it. An artifact of this is that the 248 prose was written using the primitive type strings defined by early 249 versions CDDL. In this specification the following primitive types 250 are used: 252 bstr - byte string (major type 2). 254 int - an unsigned integer or a negative integer. 256 nil - a null value (major type 7, value 22). 258 nint - a negative integer (major type 1). 260 tstr - a UTF-8 text string (major type 3). 262 uint - an unsigned integer (major type 0). 264 Text from here to start of next section to be removed 266 NOTE: For the purposes of review, we are currently interlacing the 267 CDDL grammar into the text of document. This is being done for 268 simplicity of comparison of the grammar against the prose. The 269 grammar will be removed to an appendix during WGLC. 271 start = COSE_Untagged_Message / COSE_Tagged_Message / 272 COSE_Key / COSE_KeySet 274 1.4. CBOR Related Terminology 276 In JSON, maps are called objects and only have one kind of map key: a 277 string. In COSE, we use both strings and integers (both negative and 278 non-negative integers) as map keys, as well as data items to identify 279 specific choices. The integers (both positive and negative) are used 280 for compactness of encoding and easy comparison. (Generally, in this 281 document the value zero is going to be reserved and not used.) Since 282 the work "key" is mainly used in its other meaning, as a 283 cryptographic key, we use the term "label" for this usage of either 284 an integer or a string to identify map keys and choose data items. 286 Text from here to start of next section to be removed 288 label = int / tstr 289 values = any 291 1.5. Document Terminology 293 In this document we use the following terminology: [CREF2] 295 Byte is a synonym for octet. 297 Key management is used as a term to describe how a key at level n is 298 obtained from level n+1 in encrypted and MACed messages. The term is 299 also used to discuss key life cycle management, this document does 300 not discuss key life cycle operations. 302 1.6. Mandatory to Implement Algorithms 304 One of the issues that needs to be addressed is a requirement that a 305 standard specify a set of algorithms that are required to be 306 implemented. [CREF3] This is done to promote interoperability as it 307 provides a minimal set of algorithms that all devices can be sure 308 will exist at both ends. However, we have elected not to specify a 309 set of mandatory algorithms in this document. 311 It is expected that COSE is going to be used in a wide variety of 312 applications and on a wide variety of devices. Many of the 313 constrained devices are going to be setup to use a small fixed set of 314 algorithms, and this set of algorithms may not match those available 315 on a device. We therefore have deferred to the application protocols 316 the decision of what to specify for mandatory algorithms. 318 Since the set of algorithms in an environment of constrained devices 319 may depend on what the set of devices are and how long they have been 320 in operation, we want to highlight that application protocols will 321 need to specify some type of discovery method of algorithm 322 capabilities. The discovery method may be as simple as requiring 323 preconfiguration of the set of algorithms to providing a discovery 324 method built into the protocol. S/MIME provided a number of 325 different ways to approach the problem: 327 o Advertising in the message (S/MIME capabilities) [RFC5751]. 329 o Advertising in the certificate (capabilities extension) [RFC4262] 331 o Minimum requirements for the S/MIME which have been updated over 332 time [RFC2633][RFC5751] 334 2. Basic COSE Structure 336 The COSE Message structure is designed so that there can be a large 337 amount of common code when parsing and processing the different 338 security messages. All of the message structures are built on a CBOR 339 array type. The first three elements of the array contains the same 340 basic information. The first element is a set of protected header 341 information. The second element is a set of unprotected header 342 information. The third element is the content of the message (either 343 as plain text or encrypted). Elements after this point are dependent 344 on the specific message type. 346 Identification of which message is present is done by one of two 347 methods: 349 o The specific message type is known from the context in which it is 350 placed. This may be defined by a marker in the containing 351 structure or by restrictions specified by the application 352 protocol. 354 o The message type is identified by a CBOR tag. This document 355 defines a CBOR tag for each of the message structures. 357 Text from here to start of next section to be removed 359 COSE_Untagged_Message = COSE_Sign / 360 COSE_enveloped / 361 COSE_encryptData / 362 COSE_Mac 364 COSE_Tagged_Message = COSE_Sign_Tagged / 365 COSE_Enveloped_Tagged / 366 COSE_EncryptedData_Tagged / 367 COSE_Mac_Tagged 369 3. Header Parameters 371 The structure of COSE has been designed to have two buckets of 372 information that are not considered to be part of the payload itself, 373 but are used for holding information about content, algorithms, keys, 374 or evaluation hints for the processing of the layer. These two 375 buckets are available for use in all of the structures in this 376 document except for keys. While these buckets can be present, they 377 may not all be usable in all instances. For example, while the 378 protected bucket is defined as part of recipient structures, most of 379 the algorithms that are used for recipients do not provide the 380 necessary functionality to provide the needed protection and thus the 381 bucket should not be used. 383 Both buckets are implemented as CBOR maps. The map key is a 'label' 384 (Section 1.4). The value portion is dependent on the definition for 385 the label. Both maps use the same set of label/value pairs. The 386 integer and string values for labels has been divided into several 387 sections with a standard range, a private range, and a range that is 388 dependent on the algorithm selected. The defined labels can be found 389 in the 'COSE Header Parameters' IANA registry (Section 15.2). 391 Two buckets are provided for each layer: 393 protected: Contains parameters about the current layer that are to 394 be cryptographically protected. This bucket MUST be empty if it 395 is not going to be included in a cryptographic computation. This 396 bucket is encoded in the message as a binary object. This value 397 is obtained by CBOR encoding the protected map and wrapping it in 398 a bstr object. Senders SHOULD encode an empty protected map as a 399 zero length binary object (it is shorter). Recipients MUST accept 400 both a zero length binary value and a zero length map encoded in 401 the binary value. The wrapping allows for the encoding of the 402 protected map to be transported with a greater chance that it will 403 not be altered in transit. (Badly behaved intermediates could 404 decode and re-encode, but this will result in a failure to verify 405 unless the re-encoded byte string is identical to the decoded byte 406 string.) This finesses the problem of all parties needing to be 407 able to do a common canonical encoding. 409 unprotected: Contains parameters about the current layer that are 410 not cryptographically protected. 412 Only parameters that deal with the current layer are to be placed at 413 that layer. As an example of this, the parameter 'content type' 414 describes the content of the message being carried in the message. 415 As such this parameter is placed only in the content layer and is not 416 placed in the recipient or signature layers. In principle, one 417 should be able to process any given layer without reference to any 418 other layer. (The only data that should need to cross layers is the 419 cryptographic key.) 421 The buckets are present in all of the security objects defined in 422 this document. The fields in order are the 'protected' bucket (as a 423 CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map' 424 type). The presence of both buckets is required. The parameters 425 that go into the buckets come from the IANA "COSE Header Parameters" 426 (Section 15.2). Some common parameters are defined in the next 427 section, but a number of parameters are defined throughout this 428 document. 430 Text from here to start of next section to be removed [CREF4] 432 header_map = {+ label => any } 434 Headers = ( 435 protected : bstr, ; Contains a header_map 436 unprotected : header_map 437 ) 439 3.1. Common COSE Headers Parameters 441 This section defines a set of common header parameters. A summary of 442 those parameters can be found in Table 1. This table should be 443 consulted to determine the value of label used as well as the type of 444 the value. 446 The set of header parameters defined in this section are: 448 alg This parameter is used to indicate the algorithm used for the 449 security processing. This parameter MUST be present at each level 450 of a signed, encrypted or authenticated message. The value is 451 taken from the 'COSE Algorithm Registry' (see Section 15.4). 453 crit This parameter is used to ensure that applications will take 454 appropriate action based on the values found. The parameter is 455 used to indicate which protected header labels an application that 456 is processing a message is required to understand. The value is 457 an array of COSE Header Labels. When present, this parameter MUST 458 be placed in the protected header bucket. 460 * Integer labels in the range of 0 to 10 SHOULD be omitted. 462 * Integer labels in the range -1 to -255 can be omitted as they 463 are algorithm dependent. If an application can correctly 464 process an algorithm, it can be assumed that it will correctly 465 process all of the parameters associated with that algorithm. 466 (The algorithm range is -1 to -65536, it is assumed that the 467 higher end will deal with more optional algorithm specific 468 items.) 470 The header parameter values indicated by 'crit' can be processed 471 by either the security library code or by an application using a 472 security library, the only requirement is that the parameter is 473 processed. If the 'crit' value list includes a value for which 474 the parameter is not in the protected bucket, this is a fatal 475 error in processing the message. 477 content type This parameter is used to indicate the content type of 478 the data in the payload or ciphertext fields. Integers are from 479 the 'CoAP Content-Formats' IANA registry table. Strings are from 480 the IANA 'Media Types' registry. Applications SHOULD provide this 481 parameter if the content structure is potentially ambiguous. 483 kid This parameter one of the ways that can be used to find the key 484 to be used. The value of this parameter is matched against the 485 'kid' member in a COSE_Key structure. Applications MUST NOT 486 assume that 'kid' values are unique. There may be more than one 487 key with the same 'kid' value, it may be required that all of the 488 keys need to be checked to find the correct one. The internal 489 structure of 'kid' values is not defined and generally cannot be 490 relied on by applications. Key identifier values are hints about 491 which key to use, they are not directly a security critical field, 492 for this reason they can be placed in the unprotected headers 493 bucket. 495 nonce This parameter holds either a nonce or Initialization Vector 496 value. The value can be used either as a counter value for a 497 protocol or as an IV for an algorithm. 499 counter signature This parameter holds a counter signature value. 500 Counter signatures provide a method of having a second party sign 501 some data, the counter signature can occur as an unprotected 502 attribute in any of the following structures: COSE_Sign, 503 COSE_signature, COSE_enveloped, COSE_recipient, 504 COSE_encryptedData, COSE_mac. These structures all have the same 505 basic structure so that a consistent calculation of the counter 506 signature can be computed. Details on computing counter 507 signatures are found in Section 4.3. 509 creation time This parameter provides the time the content was 510 created. For signatures and recipient structures, this would be 511 the time that the signature or recipient key object was created. 512 For content structures, this would be the time that the content 513 was created. The unsigned integer value is the number of seconds, 514 excluding leap seconds; after midnight UTC, January 1, 1970. 516 sequence number This parameter provides a counter field. The use of 517 this parameter is application specific. 519 +----------+-------+---------------+----------------+---------------+ 520 | name | label | value type | value registry | description | 521 +----------+-------+---------------+----------------+---------------+ 522 | alg | 1 | int / tstr | COSE Algorithm | Integers are | 523 | | | | Registry | taken from | 524 | | | | | table --POINT | 525 | | | | | TO REGISTRY-- | 526 | | | | | | 527 | crit | 2 | [+ label] | COSE Header | integer | 528 | | | | Label Registry | values are | 529 | | | | | from -- | 530 | | | | | POINT TO | 531 | | | | | REGISTRY -- | 532 | | | | | | 533 | content | 3 | tstr / int | CoAP Content- | Value is | 534 | type | | | Formats or | either a | 535 | | | | Media Types | Media Type or | 536 | | | | registry | an integer | 537 | | | | | from the CoAP | 538 | | | | | Content | 539 | | | | | Format | 540 | | | | | registry | 541 | | | | | | 542 | kid | 4 | bstr | | key | 543 | | | | | identifier | 544 | | | | | | 545 | nonce | 5 | bstr | | Nonce or Init | 546 | | | | | ialization | 547 | | | | | Vector (IV) | 548 | | | | | | 549 | counter | 6 | COSE_signatur | | CBOR encoded | 550 | signatur | | e | | signature | 551 | e | | | | structure | 552 | | | | | | 553 | creation | * | uint | | Time the | 554 | time | | | | content was | 555 | | | | | created | 556 | | | | | | 557 | sequence | * | uint | | Application | 558 | number | | | | specific | 559 | | | | | Integer value | 560 +----------+-------+---------------+----------------+---------------+ 562 Table 1: Common Header Parameters 564 OPEN ISSUES: 566 1. I am currently torn on the question "Should epk and iv/nonce be 567 algorithm specific or generic headers?" They are really specific 568 to an algorithm and can potentially be defined in different ways 569 for different algorithms. As an example, it would make sense to 570 defined nonce for CCM and GCM modes that can have the leading 571 zero bytes stripped, while for other algorithms this might be 572 undesirable. 574 2. We might want to define some additional items. What are they? A 575 possible example would be a sequence number as this might be 576 common. On the other hand, this is the type of things that is 577 frequently used as the nonce in some places and thus should not 578 be used in the same way. Other items might be challenge/response 579 fields for freshness as these are likely to be common. 581 4. Signing Structure 583 The signature structure allows for one or more signatures to be 584 applied to a message payload. There are provisions for parameters 585 about the content and parameters about the signature to be carried 586 along with the signature itself. These parameters may be 587 authenticated by the signature, or just present. Examples of 588 parameters about the content would be the type of content, when the 589 content was created, and who created the content. [CREF5] Examples 590 of parameters about the signature would be the algorithm and key used 591 to create the signature, when the signature was created, and counter- 592 signatures. 594 When more than one signature is present, the successful validation of 595 one signature associated with a given signer is usually treated as a 596 successful signature by that signer. However, there are some 597 application environments where other rules are needed. An 598 application that employs a rule other than one valid signature for 599 each signer must specify those rules. Also, where simple matching of 600 the signer identifier is not sufficient to determine whether the 601 signatures were generated by the same signer, the application 602 specification must describe how to determine which signatures were 603 generated by the same signer. Support of different communities of 604 recipients is the primary reason that signers choose to include more 605 than one signature. For example, the COSE_Sign structure might 606 include signatures generated with the RSA signature algorithm and 607 with the Elliptic Curve Digital Signature Algorithm (ECDSA) signature 608 algorithm. This allows recipients to verify the signature associated 609 with one algorithm or the other. (The original source of this text 610 is [RFC5652].) More detailed information on multiple signature 611 evaluation can be found in [RFC5752]. 613 The COSE_Sign structure is a CBOR array. The fields of the array in 614 order are: 616 protected is described in Section 3. 618 unprotected is described in Section 3. 620 payload contains the serialized content to be signed. If the 621 payload is not present in the message, the application is required 622 to supply the payload separately. The payload is wrapped in a 623 bstr to ensure that it is transported without changes. If the 624 payload is transported separately, then a nil CBOR object is 625 placed in this location and it is the responsibility of the 626 application to ensure that it will be transported without changes. 628 signatures is an array of signature items. Each of these items uses 629 the COSE_signature structure for its representation. 631 The COSE_signature structure is a CBOR array. The fields of the 632 array in order are: 634 protected is described in Section 3. 636 unprotected is described in Section 3. 638 signature contains the computed signature value. The type of the 639 field is a bstr. 641 Text from here to start of next section to be removed 643 COSE_Sign_Tagged = #6.999(COSE_Sign) ; Replace 999 with TBD1 645 COSE_Sign = [ 646 Headers, 647 payload : bstr / nil, 648 signatures : [+ COSE_signature] 649 ] 651 COSE_signature = [ 652 Headers, 653 signature : bstr 654 ] 656 4.1. Externally Supplied Data 658 One of the features that we supply in the COSE document is the 659 ability for applications to provide additional data to be 660 authenticated as part of the security, but that is not carried as 661 part of the COSE object. The primary reason for supporting this can 662 be seen by looking at the CoAP message structure [RFC7252] where the 663 facility exists for options to be carried before the payload. An 664 example of data that can be placed in this location would be 665 transaction ids and nonces to check for replay protection. If the 666 data is in the options section, then it is available for routers to 667 help in performing the replay detection and prevention. However, it 668 may also be desired to protect these values so that they cannot be 669 modified in transit. This is the purpose of the externally supplied 670 data field. 672 This document describes the process for using a byte array of 673 externally supplied authenticated data, however the method of 674 constructing the byte array is a function of the application. 675 Applications which use this feature need to define how the externally 676 supplied authenticated data is to be constructed. Such a 677 construction needs to take into account the following issues: 679 o If multiple items are included, care needs to be taken that data 680 cannot bleed between the items. This is usually addressed by 681 making fields fixed width and/or encoding the length of the field. 682 Using options from CoAP as an example, these fields use a TLV 683 structure so they can be concatenated without any problems. 685 o If multiple items are included, a defined order for the items 686 needs to be defined. Using options from CoAP as an example, an 687 application could state that the fields are to be ordered by the 688 option number. 690 4.2. Signing and Verification Process 692 In order to create a signature, a consistent byte stream is needed in 693 order to process. This document uses a CBOR array to construct the 694 byte stream to be processed. The fields of the array in order are: 696 1. The body protected attributes. This is a bstr type containing 697 the protected attributes of the body. 699 2. The signature protected attributes. This is a bstr type 700 containing the protected attributes of the signature. 702 3. The external protected attributes. This is a bstr type 703 containing the protected attributes external to the 704 COSE_Signature structure. 706 4. The payload to be signed. The payload is encoded in a bstr. The 707 payload is placed here independent of how it is transported. 709 How to compute a signature: 711 1. Create a CBOR array and populate it with the appropriate fields. 712 For body_protected and sign_protected, if the fields are not 713 present in their corresponding maps, a bstr of length zero is 714 used. 716 2. If the application has supplied external additional authenticated 717 data to be included in the computation, then it is placed in the 718 third field. If no data was supplied, then a zero length binary 719 value is used. 721 3. Create the value ToBeSigned by encoding the Sig_structure to a 722 byte string. 724 4. Call the signature creation algorithm passing in K (the key to 725 sign with), alg (the algorithm to sign with) and ToBeSigned (the 726 value to sign). 728 5. Place the resulting signature value in the 'signature' field of 729 the map. 731 How to verify a signature: 733 1. Create a Sig_structure object and populate it with the 734 appropriate fields. For body_protected and sign_protected, if 735 the fields are not present in their corresponding maps, a bstr of 736 length zero is used. 738 2. If the application has supplied external additional authenticated 739 data to be included in the computation, then it is placed in the 740 third field. If no data was supplied, then a zero length binary 741 value is used. 743 3. Create the value ToBeSigned by encoding the Sig_structure to a 744 byte string. 746 4. Call the signature verification algorithm passing in K (the key 747 to verify with), alg (the algorithm to sign with), ToBeSigned 748 (the value to sign), and sig (the signature to be verified). 750 In addition to performing the signature verification, one must also 751 perform the appropriate checks to ensure that the key is correctly 752 paired with the signing identity and that the appropriate 753 authorization is done. 755 Text from here to start of next section to be removed 757 The COSE structure used to create the byte stream to be signed uses 758 the following CDDL grammar structure: 760 Sig_structure = [ 761 body_protected: bstr, 762 sign_protected: bstr, 763 external_aad: bstr, 764 payload: bstr 765 ] 767 4.3. Computing Counter Signatures 769 Counter signatures provide a method of having a different signature 770 occur on some piece of content. This is normally used to provide a 771 signature on a signature allowing for a proof that a signature 772 existed at a given time. In this document we allow for counter 773 signatures to exist in a greater number of environments. A counter 774 signature can exist, for example, on a COSE_encryptedData object and 775 allow for a signature to be present on the encrypted content of a 776 message. 778 The creation and validation of counter signatures over the different 779 items relies on the fact that the structure all of our objects have 780 the same structure. The first element may be a message type, this is 781 followed by a set of protected attributes, a set of unprotected 782 attributes and a body in that order. This means that the 783 Sig_structure can be used for in a uniform manner to get the byte 784 stream for processing a signature. If the counter signature is going 785 to be computed over a COSE_encryptedData structure, the 786 body_protected and payload items can be mapped into the Sig_structure 787 in the same manner as from the COSE_Sign structure. 789 While one can create a counter signature for a COSE_Sign structure, 790 there is not much of a point to doing so. It is equivalent to create 791 a new COSE_signature structure and placing it in the signatures 792 array. It is strongly suggested that it not be done, but it is not 793 banned. 795 5. Encryption objects 797 COSE supports two different encryption structures. OOSE_enveloped is 798 used when the key needs to be explicitly identified. This structure 799 supports the use of recipient structures to allow for random content 800 encryption keys to be used. COSE_encrypted is used when a recipient 801 structure is not needed because the key to be used is known 802 implicitly. 804 5.1. Enveloped COSE structure 806 The enveloped structure allows for one or more recipients of a 807 message. There are provisions for parameters about the content and 808 parameters about the recipient information to be carried in the 809 message. The parameters associated with the content can be 810 authenticated by the content encryption algorithm. The parameters 811 associated with the recipient can be authenticated by the recipient 812 algorithm (when the algorithm supports it). Examples of parameters 813 about the content are the type of the content, when the content was 814 created, and the content encryption algorithm. Examples of 815 parameters about the recipient are the recipient's key identifier, 816 the recipient encryption algorithm. 818 In COSE, the same techniques and structures for encrypting both the 819 plain text and the keys used to protect the text. This is different 820 from the approach used by both [RFC5652] and [RFC7516] where 821 different structures are used for the content layer and for the 822 recipient layer. 824 The COSE_encrypt structure is a CBOR array. The fields of the array 825 in order are: 827 protected is described in Section 3. 829 unprotected is described in Section 3. 831 ciphertext contains the encrypted plain text encoded as a bstr. If 832 the ciphertext is to be transported independently of the control 833 information about the encryption process (i.e. detached content) 834 then the field is encoded as a null object. 836 recipients contains an array of recipient information structures. 837 The type for the recipient information structure is a 838 COSE_recipient. 840 The COSE_recipient structure is a CBOR array. The fields of the 841 array in order are: 843 protected is described in Section 3. 845 unprotected is described in Section 3. 847 ciphertext contains the encrypted key encoded as a bstr. If there 848 is not an encrypted key, then this field is encoded as a nil type. 850 recipients contains an array of recipient information structures. 851 The type for the recipient information structure is a 852 COSE_recipient. If there are no recipient information structures, 853 this element is absent. 855 Text from here to start of next section to be removed 857 COSE_Enveloped_Tagged = #6.998(COSE_enveloped) ; Replace 998 with TBD32 859 COSE_enveloped = [ 860 COSE_encrypt_fields 861 recipients: [+COSE_recipient] 862 ] 864 COSE_encrypt_fields = ( 865 Headers, 866 ciphertext: bstr / nil, 867 ) 869 COSE_recipient = [ 870 COSE_encrypt_fields 871 ? recipients: [+COSE_recipient] 872 ] 874 5.1.1. Recipient Algorithm Classes 876 A typical encrypted message consists of an encrypted content and an 877 encrypted CEK for one or more recipients. The content-encryption key 878 is encrypted for each recipient, using a key specific to that 879 recipient. The details of this encryption depends on which class the 880 recipient algorithm falls into. Specific details on each of the 881 classes can be found in Section 12. A short summary of the six 882 recipient algorithm classes is: 884 none: The CEK is the same as the identified previously distributed 885 symmetric key or derived from a previously distributed secret. 887 symmetric key-encryption keys: The CEK is encrypted using a 888 previously distributed symmetric key-encryption key. 890 key agreement: the recipient's public key and a sender's private key 891 are used to generate a pairwise secret, a KDF is applied to derive 892 a key, and then the CEK is either the derived key or encrypted by 893 the derived key. 895 key transport: the CEK is encrypted in the recipient's public key 897 passwords: the CEK is encrypted in a key-encryption key that is 898 derived from a password. 900 5.2. Encrypted COSE structure 902 The encrypted structure does not have the ability to specify 903 recipients of the message. The structure assumes that the recipient 904 of the object will already know the identity of the key to be used in 905 order to decrypt the message. If a key needs to be identified to the 906 recipient, the enveloped structure is used. 908 The CDDL grammar structure for encrypted data is: 910 COSE_EncryptedData_Tagged = #6.997(COSE_encryptData) ; Replace 997 with TBD3 912 COSE_encryptData = [ 913 COSE_encrypt_fields 914 ] 916 The COSE_encryptedData structure is a CBOR array. The fields of the 917 array in order are: 919 protected is described in Section 3. 921 unprotected is described in Section 3. 923 ciphertext contains the encrypted plain text. If the ciphertext is 924 to be transported independently of the control information about 925 the encryption process (i.e. detached content) then the field is 926 encoded as a null object. 928 5.3. Encryption Algorithm for AEAD algorithms 930 The encryption algorithm for AEAD algorithms is fairly simple. In 931 order to get a consistent encoding of the data to be authenticated, 932 the Enc_structure is used to have canonical form of the AAD. 934 1. Copy the protected header field from the message to be sent. 936 2. If the application has supplied external additional authenticated 937 data to be included in the computation, then it is placed in the 938 'external_aad' field. If no data was supplied, then a zero 939 length binary value is used. (See Section 4.1 for application 940 guidance on constructing this field.) 942 3. Encode the Enc_structure using a CBOR Canonical encoding 943 Section 14 to get the AAD value. 945 4. Determine the encryption key. This step is dependent on the 946 class of recipient algorithm being used. For: 948 No Recipients: The key to be used is determined by the algorithm 949 and key at the current level. 951 Direct and Direct Key Agreement: The key is determined by the 952 key and algorithm in the recipient structure. The encryption 953 algorithm and size of the key to be used are inputs into the 954 KDF used for the recipient. (For direct, the KDF can be 955 thought of as the identity operation.) 957 Other: The key is randomly generated. 959 5. Call the encryption algorithm with K (the encryption key to use), 960 P (the plain text) and AAD (the additional authenticated data). 961 Place the returned cipher text into the 'ciphertext' field of the 962 structure. 964 6. For recipients of the message, recursively perform the encryption 965 algorithm for that recipient using the encryption key as the 966 plain text. 968 Text from here to start of next section to be removed 970 Enc_structure = [ 971 protected: bstr, 972 external_aad: bstr 973 ] 975 5.4. Encryption algorithm for AE algorithms 977 1. Verify that the 'protected' field is absent. 979 2. Verify that there was no external additional authenticated data 980 supplied for this operation. 982 3. Determine the encryption key. This step is dependent on the 983 class of recipient algorithm being used. For: 985 No Recipients: The key to be used is determined by the algorithm 986 and key at the current level. 988 Direct and Direct Key Agreement: The key is determined by the 989 key and algorithm in the recipient structure. The encryption 990 algorithm and size of the key to be used are inputs into the 991 KDF used for the recipient. (For direct, the KDF can be 992 thought of as the identity operation.) 994 Other: The key is randomly generated. 996 4. Call the encryption algorithm with K (the encryption key to use) 997 and the P (the plain text). Place the returned cipher text into 998 the 'ciphertext' field of the structure. 1000 5. For recipients of the message, recursively perform the encryption 1001 algorithm for that recipient using the encryption key as the 1002 plain text. 1004 6. MAC objects 1006 In this section we describe the structure and methods to be used when 1007 doing MAC authentication in COSE. This document allows for the use 1008 of all of the same classes of recipient algorithms as are allowed for 1009 encryption. 1011 When using MAC operations, there are two modes in which it can be 1012 used. The first is just a check that the content has not been 1013 changed since the MAC was computed. Any class of recipient algorithm 1014 can be used for this purpose. The second mode is to both check that 1015 the content has not been changed since the MAC was computed, and to 1016 use recipient algorithm to verify who sent it. The classes of 1017 recipient algorithms that support this are those that use a pre- 1018 shared secret or do static-static key agreement (without the key wrap 1019 step). In both of these cases the entity MACing the message can be 1020 validated by a key binding. (The binding of identity assumes that 1021 there are only two parties involved and you did not send the message 1022 yourself.) 1024 The COSE_Mac structure is a CBOR array. The fields of the array in 1025 order are: 1027 protected is described in Section 3. 1029 unprotected is described in Section 3. 1031 payload contains the serialized content to be MACed. If the payload 1032 is not present in the message, the application is required to 1033 supply the payload separately. The payload is wrapped in a bstr 1034 to ensure that it is transported without changes. If the payload 1035 is transported separately, then a null CBOR object is placed in 1036 this location and it is the responsibility of the application to 1037 ensure that it will be transported without changes. 1039 tag contains the MAC value. 1041 recipients contains the recipient information. See the description 1042 under COSE_Encryption for more info. 1044 Text from here to start of next section to be removed 1046 COSE_Mac_Tagged = #6.996(COSE_Mac) ; Replace 996 with TBD4 1048 COSE_Mac = [ 1049 Headers, 1050 payload: bstr / nil, 1051 tag: bstr, 1052 recipients: [+COSE_recipient] 1053 ] 1055 6.1. How to compute a MAC 1057 How to compute a MAC: 1059 1. Create a MAC_structure and copy the protected and payload fields 1060 from the COSE_Mac structure. 1062 2. If the application has supplied external authenticated data, 1063 encode it as a binary value and place in the MAC_structure. If 1064 there is no external authenticated data, then use a zero length 1065 'bstr'. (See Section 4.1 for application guidance on 1066 constructing this field.) 1068 3. Encode the MAC_structure using a canonical CBOR encoder. The 1069 resulting bytes is the value to compute the MAC on. 1071 4. Compute the MAC and place the result in the 'tag' field of the 1072 COSE_Mac structure. 1074 5. Encrypt and encode the MAC key for each recipient of the message. 1076 Text from here to start of next section to be removed 1077 MAC_structure = [ 1078 protected: bstr, 1079 external_aad: bstr, 1080 payload: bstr 1081 ] 1083 7. Key Structure 1085 A COSE Key structure is built on a CBOR map object. The set of 1086 common parameters that can appear in a COSE Key can be found in the 1087 IANA registry 'COSE Key Common Parameter Registry' (Section 15.5). 1088 Additional parameters defined for specific key types can be found in 1089 the IANA registry 'COSE Key Type Parameters' (Section 15.6). 1091 A COSE Key Set uses a CBOR array object as its underlying type. The 1092 values of the array elements are COSE Keys. A Key Set MUST have at 1093 least one element in the array. 1095 The element "kty" is a required element in a COSE_Key map. 1097 Text from here to start of next section to be removed 1099 The CDDL grammar describing a COSE_Key and COSE_KeySet is: [CREF6] 1101 COSE_Key = { 1102 key_kty => tstr / int, 1103 ? key_ops => [+ (tstr / int) ], 1104 ? key_alg => tstr / int, 1105 ? key_kid => bstr, 1106 * label => values 1107 } 1109 COSE_KeySet = [+COSE_Key] 1111 7.1. COSE Key Common Parameters 1113 This document defines a set of common parameters for a COSE Key 1114 object. Table 2 provides a summary of the parameters defined in this 1115 section. There are also a set of parameters that are defined for a 1116 specific key type. Key type specific parameters can be found in 1117 Section 13. 1119 +---------+-------+-------------+-------------+---------------------+ 1120 | name | label | CBOR type | registry | description | 1121 +---------+-------+-------------+-------------+---------------------+ 1122 | kty | 1 | tstr / int | COSE | Identification of | 1123 | | | | General | the key type | 1124 | | | | Values | | 1125 | | | | | | 1126 | key_ops | 4 | [* | | Restrict set of | 1127 | | | (tstr/int)] | | permissible | 1128 | | | | | operations | 1129 | | | | | | 1130 | alg | 3 | tstr / int | COSE | Key usage | 1131 | | | | Algorithm | restriction to this | 1132 | | | | Values | algorithm | 1133 | | | | | | 1134 | kid | 2 | bstr | | Key Identification | 1135 | | | | | value - match to | 1136 | | | | | kid in message | 1137 | | | | | | 1138 | use | * | tstr | | deprecated - don't | 1139 | | | | | use | 1140 +---------+-------+-------------+-------------+---------------------+ 1142 Table 2: Key Map Labels 1144 kty: This parameter is used to identify the family of keys for this 1145 structure, and thus the set of key type specific parameters to be 1146 found. The set of values can be found in Table 18. This 1147 parameter MUST be present in a key object. Implementations MUST 1148 verify that the key type is appropriate for the algorithm being 1149 processed. The key type MUST be included as part of a trust 1150 decision process. 1152 alg: This parameter is used to restrict the algorithms that are to 1153 be used with this key. If this parameter is present in the key 1154 structure, the application MUST verify that this algorithm matches 1155 the algorithm for which the key is being used. If the algorithms 1156 do not match, then this key object MUST NOT be used to perform the 1157 cryptographic operation. Note that the same key can be in a 1158 different key structure with a different or no algorithm 1159 specified, however this is considered to be a poor security 1160 practice. 1162 kid: This parameter is used to give an identifier for a key. The 1163 identifier is not structured and can be anything from a user 1164 provided string to a value computed on the public portion of the 1165 key. This field is intended for matching against a 'kid' 1166 parameter in a message in order to filter down the set of keys 1167 that need to be checked. 1169 key_ops: This parameter is defined to restrict the set of operations 1170 that a key is to be used for. The value of the field is an array 1171 of values from Table 3. 1173 +---------+-------+-------------------------------------------------+ 1174 | name | value | description | 1175 +---------+-------+-------------------------------------------------+ 1176 | sign | 1 | The key is used to create signatures. Requires | 1177 | | | private key fields. | 1178 | | | | 1179 | verify | 2 | The key is used for verification of signatures. | 1180 | | | | 1181 | encrypt | 3 | The key is used for key transport encryption. | 1182 | | | | 1183 | decrypt | 4 | The key is used for key transport decryption. | 1184 | | | Requires private key fields. | 1185 | | | | 1186 | wrap | 5 | The key is used for key wrapping. | 1187 | key | | | 1188 | | | | 1189 | unwrap | 6 | The key is used for key unwrapping. Requires | 1190 | key | | private key fields. | 1191 | | | | 1192 | key | 7 | The key is used for key agreement. | 1193 | agree | | | 1194 +---------+-------+-------------------------------------------------+ 1196 Table 3: Key Operation Values 1198 Text from here to start of next section to be removed 1200 The following provides a CDDL fragment which duplicates the 1201 assignment labels from Table 2 and Table 3. 1203 ;key_labels 1204 key_kty=1 1205 key_kid=2 1206 key_alg=3 1207 key_ops=4 1209 ;key_ops values 1210 key_ops_sign=1 1211 key_ops_verify=2 1212 key_ops_encrypt=3 1213 key_ops_decrypt=4 1214 key_ops_wrap=5 1215 key_ops_unwrap=6 1216 key_ops_agree=7 1218 8. Signature Algorithms 1220 There are two basic signature algorithm structures that can be used. 1221 The first is the common signature with appendix. In this structure, 1222 the message content is processed and a signature is produced, the 1223 signature is called the appendix. This is the message structure used 1224 by our common algorithms such as ECDSA and RSASSA-PSS. (In fact the 1225 SSA in RSASSA-PSS stands for Signature Scheme with Appendix.) The 1226 basic structure becomes: 1228 signature = Sign(message content, key) 1230 valid = Verification(message content, key, signature) 1232 The second is a signature with message recovery. (An example of such 1233 an algorithm is [PVSig].) In this structure, the message content is 1234 processed, but part of is included in the signature. Moving bytes of 1235 the message content into the signature allows for an effectively 1236 smaller signature, the signature size is still potentially large, but 1237 the message content is shrunk. This has implications for systems 1238 implementing these algorithms and for applications that use them. 1239 The first is that the message content is not fully available until 1240 after a signature has been validated. Until that point the part of 1241 the message contained inside of the signature is unrecoverable. The 1242 second is that the security analysis of the strength of the signature 1243 is very much based on the structure of the message content. Messages 1244 which are highly predictable require additional randomness to be 1245 supplied as part of the signature process, in the worst case it 1246 becomes the same as doing a signature with appendix. Thirdly, in the 1247 event that multiple signatures are applied to a message, all of the 1248 signature algorithms are going to be required to consume the same 1249 number of bytes of message content. 1251 signature, message sent = Sign(message content, key) 1253 valid, message content = Verification(message sent, key, signature) 1255 At this time, only signatures with appendixes are defined for use 1256 with COSE, however considerable interest has been expressed in using 1257 a signature with message recovery algorithm due to the effective size 1258 reduction that is possible. Implementations will need to keep this 1259 in mind for later possible integration. 1261 8.1. ECDSA 1263 ECDSA [DSS] defines a signature algorithm using ECC. 1265 The ECDSA signature algorithm is parameterized with a hash function 1266 (h). In the event that the length of the hash function output is 1267 greater than group of the key, the left most bytes of the hash output 1268 are used. 1270 The algorithms defined in this document can be found in Table 4. 1272 +-------+-------+---------+------------------+ 1273 | name | value | hash | description | 1274 +-------+-------+---------+------------------+ 1275 | ES256 | -7 | SHA-256 | ECDSA w/ SHA-256 | 1276 | | | | | 1277 | ES384 | -8 | SHA-384 | ECDSA w/ SHA-384 | 1278 | | | | | 1279 | ES512 | -9 | SHA-512 | ECDSA w/ SHA-512 | 1280 +-------+-------+---------+------------------+ 1282 Table 4: ECDSA Algorithm Values 1284 This document defines ECDSA to work only with the curves P-256, P-384 1285 and P-521. This document requires that the curves be encoded using 1286 the 'EC2' key type. Implementations need to check that the key type 1287 and curve are correct when creating and verifying a signature. Other 1288 documents can defined it to work with other curves and points in the 1289 future. 1291 In order to promote interoperability, it is suggested that SHA-256 be 1292 used only with curve P-256, SHA-384 be used only with curve P-384 and 1293 SHA-512 be used with curve P-521. This is aligned with the 1294 recommendation in Section 4 of [RFC5480]. 1296 The signature algorithm results in a pair of integers (R, S). These 1297 integers will be of the same order as length of the key used for the 1298 signature process. The signature is encoded by converting the 1299 integers into byte strings of the same length as the key size. The 1300 length is rounded up to the nearest byte and is left padded with zero 1301 bits to get to the correct length. The two integers are then 1302 concatenated together to form a byte string that is the resulting 1303 signature. 1305 Using the function defined in [RFC3447] the signature is: 1306 Signature = I2OSP(R, n) | I2OSP(S, n) 1307 where n = ceiling(key_length / 8) 1309 8.1.1. Security Considerations 1311 The security strength of the signature is no greater than the minimum 1312 of the security strength associated with the bit length of the key 1313 and the security strength of the hash function. 1315 System which have poor random number generation can leak their keys 1316 by signing two different messages with the same value of 'k'. 1317 [RFC6979] provides a method to deal with this problem by making 'k' 1318 be deterministic based on the message content rather than randomly 1319 generated. Applications which specify ECDSA should evaluate the 1320 ability to get good random number generation and require this when it 1321 is not possible. Note: Use of this technique a good idea even when 1322 good random number generation exists. Doing so both reduces the 1323 possibility of having the same value of 'k' in two signature 1324 operations, but allows for reproducible signature values which helps 1325 testing. 1327 There are two substitution that can theoretically be mounted against 1328 the ECDSA signature algorithm. 1330 o Changing the curve used to validate the signature: If one changes 1331 the curve used to validate the signature, then potentially one 1332 could have a two messages with the same signature each computed 1333 under a different curve. The only requirement on the new curve is 1334 that its order be the same as the old one and it be acceptable to 1335 the client. An example would be to change from using the curve 1336 secp256r1 (aka P-256) to using secp256k1. (Both are 256 bit 1337 curves.) We current do not have any way to deal with this version 1338 of the attack except to restrict the overall set of curves that 1339 can be used. 1341 o Change the hash function used to validate the signature: If one 1342 has either two different hash functions of the same length, or one 1343 can truncate a hash function down, then one could potentially find 1344 collisions between the hash functions rather than within a single 1345 hash function. (For example, truncating SHA-512 to 256 bits might 1346 collide with a SHA-256 bit hash value.) This attack can be 1347 mitigated by including the signature algorithm identifier in the 1348 data to be signed. 1350 9. Message Authentication (MAC) Algorithms 1352 Message Authentication Codes (MACs) provide data authentication and 1353 integrity protection. They provide either no or very limited data 1354 origination. (One cannot, for example, be used to prove the identity 1355 of the sender to a third party.) 1357 MACs are designed in the same basic structure as signature with 1358 appendix algorithms. The message content is processed and an 1359 authentication code is produced, the authentication code is 1360 frequently called a tag. The basic structure becomes: 1362 tag = MAC_Create(message content, key) 1364 valid = MAC_Verify(message content, key, tag) 1366 MAC algorithms can be based on either a block cipher algorithm (i.e. 1367 AES-MAC) or a hash algorithm (i.e. HMAC). This document defines a 1368 MAC algorithm for each of these two constructions. 1370 9.1. Hash-based Message Authentication Codes (HMAC) 1372 The Hash-base Message Authentication Code algorithm (HMAC) 1373 [RFC2104][RFC4231] was designed to deal with length extension 1374 attacks. The algorithm was also designed to allow for new hash 1375 algorithms to be directly plugged in without changes to the hash 1376 function. The HMAC design process has been vindicated as, while the 1377 security of hash algorithms such as MD5 has decreased over time, the 1378 security of HMAC combined with MD5 has not yet been shown to be 1379 compromised [RFC6151]. 1381 The HMAC algorithm is parameterized by an inner and outer padding, a 1382 hash function (h) and an authentication tag value length. For this 1383 specification, the inner and outer padding are fixed to the values 1384 set in [RFC2104]. The length of the authentication tag corresponds 1385 to the difficulty of producing a forgery. For use in constrained 1386 environments, we define a set of HMAC algorithms that are truncated. 1388 There are currently no known issues when truncating, however the 1389 security strength of the message tag is correspondingly reduced in 1390 strength. When truncating, the left most tag length bits are kept 1391 and transmitted. 1393 The algorithm defined in this document can be found in Table 5. 1395 +-----------+-------+---------+--------+----------------------------+ 1396 | name | value | Hash | Length | description | 1397 +-----------+-------+---------+--------+----------------------------+ 1398 | HMAC | * | SHA-256 | 64 | HMAC w/ SHA-256 truncated | 1399 | 256/64 | | | | to 64 bits | 1400 | | | | | | 1401 | HMAC | 4 | SHA-256 | 256 | HMAC w/ SHA-256 | 1402 | 256/256 | | | | | 1403 | | | | | | 1404 | HMAC | 5 | SHA-384 | 384 | HMAC w/ SHA-384 | 1405 | 384/384 | | | | | 1406 | | | | | | 1407 | HMAC | 6 | SHA-512 | 512 | HMAC w/ SHA-512 | 1408 | 512/512 | | | | | 1409 +-----------+-------+---------+--------+----------------------------+ 1411 Table 5: HMAC Algorithm Values 1413 Some recipient algorithms carry the key while others derive a key 1414 from secret data. For those algorithms which carry the key (i.e. 1415 RSA-OAEP and AES-KeyWrap), the size of the HMAC key SHOULD be the 1416 same size as the underlying hash function. For those algorithms 1417 which derive the key, the derived key MUST be the same size as the 1418 underlying hash function. 1420 If the key obtained from a key structure, the key type MUST be 1421 'Symmetric'. Implementations creating and validating MAC values MUST 1422 validate that the key type, key length and algorithm are correct and 1423 appropriate for the entities involved. 1425 9.1.1. Security Considerations 1427 HMAC has proved to be resistant even when used with weakening hash 1428 algorithms. The current best method appears to be a brute force 1429 attack on the key. This means that key size is going to be directly 1430 related to the security of an HMAC operation. 1432 9.2. AES Message Authentication Code (AES-CBC-MAC) 1434 AES-CBC-MAC is defined in [MAC]. 1436 AES-CBC-MAC is parameterized by the key length, the authentication 1437 tag length and the IV used. For all of these algorithms, the IV is 1438 fixed to all zeros. We provide an array of algorithms for various 1439 key lengths and tag lengths. The algorithms defined in this document 1440 are found in Table 6. 1442 +-------------+-------+----------+----------+-----------------------+ 1443 | name | value | key | tag | description | 1444 | | | length | length | | 1445 +-------------+-------+----------+----------+-----------------------+ 1446 | AES-MAC | * | 128 | 64 | AES-MAC 128 bit key, | 1447 | 128/64 | | | | 64-bit tag | 1448 | | | | | | 1449 | AES-MAC | * | 256 | 64 | AES-MAC 256 bit key, | 1450 | 256/64 | | | | 64-bit tag | 1451 | | | | | | 1452 | AES-MAC | * | 128 | 128 | AES-MAC 128 bit key, | 1453 | 128/128 | | | | 128-bit tag | 1454 | | | | | | 1455 | AES-MAC | * | 256 | 128 | AES-MAC 256 bit key, | 1456 | 256/128 | | | | 128-bit tag | 1457 +-------------+-------+----------+----------+-----------------------+ 1459 Table 6: AES-MAC Algorithm Values 1461 Keys may be obtained either from a key structure or from a recipient 1462 structure. If the key obtained from a key structure, the key type 1463 MUST be 'Symmetric'. Implementations creating and validating MAC 1464 values MUST validate that the key type, key length and algorithm are 1465 correct and appropriate for the entities involved. 1467 9.2.1. Security Considerations 1469 A number of attacks exist against CBC-MAC that need to be considered. 1471 o A single key must only be used for messages of a fixed and known 1472 length. If this is not the case, an attacker will be able to 1473 generate a message with a valid tag given two message, tag pairs. 1474 This can be addressed by using different keys for different length 1475 messages. (CMAC mode also addresses this issue.) 1477 o If the same key is used for both encryption and authentication 1478 operations, using CBC modes an attacker can produce messages with 1479 a valid authentication code. 1481 o If the IV can be modified, then messages can be forged. This is 1482 addressed by fixing the IV to all zeros. 1484 10. Content Encryption Algorithms 1486 Content Encryption Algorithms provide data confidentiality for 1487 potentially large blocks of data using a symmetric key. They provide 1488 either no or very limited data origination. (One cannot, for 1489 example, be used to prove the identity of the sender to a third 1490 party.) The ability to provide data origination is linked to how the 1491 symmetric key is obtained. 1493 We restrict the set of legal content encryption algorithms to those 1494 which support authentication both of the content and additional data. 1495 The encryption process will generate some type of authentication 1496 value, but that value may be either explicit or implicit in terms of 1497 the algorithm definition. For simplicity sake, the authentication 1498 code will normally be defined as being appended to the cipher text 1499 stream. The basic structure becomes: 1501 ciphertext = Encrypt(message content, key, additional data) 1503 valid, message content = Decrypt(cipher text, key, additional data) 1505 Most AEAD algorithms are logically defined as returning the message 1506 content only if the decryption is valid. Many but not all 1507 implementations will follow this convention. The message content 1508 MUST NOT be used if the decryption does not validate. 1510 10.1. AES GCM 1512 The GCM mode is a generic authenticated encryption block cipher mode 1513 defined in [AES-GCM]. The GCM mode is combined with the AES block 1514 encryption algorithm to define an AEAD cipher. 1516 The GCM mode is parameterized with by the size of the authentication 1517 tag. The size of the authentication tag is limited to a small set of 1518 values. For this document however, the size of the authentication 1519 tag is fixed at 128-bits. 1521 The set of algorithms defined in this document are in Table 7. 1523 +---------+-------+-----------------------------+ 1524 | name | value | description | 1525 +---------+-------+-----------------------------+ 1526 | A128GCM | 1 | AES-GCM mode w/ 128-bit key | 1527 | | | | 1528 | A192GCM | 2 | AES-GCM mode w/ 192-bit key | 1529 | | | | 1530 | A256GCM | 3 | AES-GCM mode w/ 256-bit key | 1531 +---------+-------+-----------------------------+ 1533 Table 7: Algorithm Value for AES-GCM 1535 Keys may be obtained either from a key structure or from a recipient 1536 structure. If the key obtained from a key structure, the key type 1537 MUST be 'Symmetric'. Implementations creating and validating MAC 1538 values MUST validate that the key type, key length and algorithm are 1539 correct and appropriate for the entities involved. 1541 10.1.1. Security Considerations 1543 When using AES-CCM the following restrictions MUST be enforced: 1545 o The key and nonce pair MUST be unique for every message encrypted. 1547 o The total amount of data encrypted MUST NOT exceed 2^39 - 256 1548 bits. An explicit check is required only in environments where it 1549 is expected that it might be exceeded. 1551 10.2. AES CCM 1553 Counter with CBC-MAC (CCM) is a generic authentication encryption 1554 block cipher mode defined in [RFC3610]. The CCM mode is combined 1555 with the AES block encryption algorithm to define a commonly used 1556 content encryption algorithm used in constrained devices. 1558 The CCM mode has two parameter choices. The first choice is M, the 1559 size of the authentication field. The choice of the value for M 1560 involves a trade-off between message expansion and the probably that 1561 an attacker can undetectably modify a message. The second choice is 1562 L, the size of the length field. This value requires a trade-off 1563 between the maximum message size and the size of the Nonce. 1565 It is unfortunate that the specification for CCM specified L and M as 1566 a count of bytes rather than a count of bits. This leads to possible 1567 misunderstandings where AES-CCM-8 is frequently used to refer to a 1568 version of CCM mode where the size of the authentication is 64-bits 1569 and not 8-bits. These values have traditionally been specified as 1570 bit counts rather than byte counts. This document will follow the 1571 tradition of using bit counts so that it is easier to compare the 1572 different algorithms presented in this document. 1574 We define a matrix of algorithms in this document over the values of 1575 L and M. Constrained devices are usually operating in situations 1576 where they use short messages and want to avoid doing recipient 1577 specific cryptographic operations. This favors smaller values of M 1578 and larger values of L. Less constrained devices do will want to be 1579 able to user larger messages and are more willing to generate new 1580 keys for every operation. This favors larger values of M and smaller 1581 values of L. (The use of a large nonce means that random generation 1582 of both the key and the nonce will decrease the chances of repeating 1583 the pair on two different messages.) 1585 The following values are used for L: 1587 16-bits (2) limits messages to 2^16 bytes (64 KiB) in length. This 1588 sufficiently long for messages in the constrained world. The 1589 nonce length is 13 bytes allowing for 2^(13*8) possible values of 1590 the nonce without repeating. 1592 64-bits (8) limits messages to 2^64 bytes in length. The nonce 1593 length is 7 bytes allowing for 2^56 possible values of the nonce 1594 without repeating. 1596 The following values are used for M: 1598 64-bits (8) produces a 64-bit authentication tag. This implies that 1599 there is a 1 in 2^64 chance that a modified message will 1600 authenticate. 1602 128-bits (16) produces a 128-bit authentication tag. This implies 1603 that there is a 1 in 2^128 chance that a modified message will 1604 authenticate. 1606 +--------------------+-------+----+-----+-----+---------------------+ 1607 | name | value | L | M | k | description | 1608 +--------------------+-------+----+-----+-----+---------------------+ 1609 | AES-CCM-16-64-128 | 10 | 16 | 64 | 128 | AES-CCM mode | 1610 | | | | | | 128-bit key, 64-bit | 1611 | | | | | | tag, 13-byte nonce | 1612 | | | | | | | 1613 | AES-CCM-16-64-256 | 11 | 16 | 64 | 256 | AES-CCM mode | 1614 | | | | | | 256-bit key, 64-bit | 1615 | | | | | | tag, 13-byte nonce | 1616 | | | | | | | 1617 | AES-CCM-64-64-128 | 30 | 64 | 64 | 128 | AES-CCM mode | 1618 | | | | | | 128-bit key, 64-bit | 1619 | | | | | | tag, 7-byte nonce | 1620 | | | | | | | 1621 | AES-CCM-64-64-256 | 31 | 64 | 64 | 256 | AES-CCM mode | 1622 | | | | | | 256-bit key, 64-bit | 1623 | | | | | | tag, 7-byte nonce | 1624 | | | | | | | 1625 | AES-CCM-16-128-128 | 12 | 16 | 128 | 128 | AES-CCM mode | 1626 | | | | | | 128-bit key, | 1627 | | | | | | 128-bit tag, | 1628 | | | | | | 13-byte nonce | 1629 | | | | | | | 1630 | AES-CCM-16-128-256 | 13 | 16 | 128 | 256 | AES-CCM mode | 1631 | | | | | | 256-bit key, | 1632 | | | | | | 128-bit tag, | 1633 | | | | | | 13-byte nonce | 1634 | | | | | | | 1635 | AES-CCM-64-128-128 | 32 | 64 | 128 | 128 | AES-CCM mode | 1636 | | | | | | 128-bit key, | 1637 | | | | | | 128-bit tag, 7-byte | 1638 | | | | | | nonce | 1639 | | | | | | | 1640 | AES-CCM-64-128-256 | 33 | 64 | 128 | 256 | AES-CCM mode | 1641 | | | | | | 256-bit key, | 1642 | | | | | | 128-bit tag, 7-byte | 1643 | | | | | | nonce | 1644 +--------------------+-------+----+-----+-----+---------------------+ 1646 Table 8: Algorithm Values for AES-CCM 1648 Keys may be obtained either from a key structure or from a recipient 1649 structure. If the key obtained from a key structure, the key type 1650 MUST be 'Symmetric'. Implementations creating and validating MAC 1651 values MUST validate that the key type, key length and algorithm are 1652 correct and appropriate for the entities involved. 1654 10.2.1. Security Considerations 1656 When using AES-CCM the following restrictions MUST be enforced: 1658 o The key and nonce pair MUST be unique for every message encrypted. 1660 o The total number of times the AES block cipher is used MUST NOT 1661 exceed 2^61 operations. This limitation is the sum of times the 1662 block cipher is used in computing the MAC value and in performing 1663 stream encryption operations. An explicit check is required only 1664 in environments where it is expected that it might be exceeded. 1666 [RFC3610] additionally calls out one other consideration of note. It 1667 is possible to do a pre-computation attack against the algorithm in 1668 cases where the portions encryption content is highly predictable. 1669 This reduces the security of the key size by half. Ways to deal with 1670 this attack include adding a random portion to the nonce value and/or 1671 increasing the key size used. Using a portion of the nonce for a 1672 random value will decrease the number of messages that a single key 1673 can be used for. Increasing the key size may require more resources 1674 in the constrained device. See sections 5 and 10 of [RFC3610] for 1675 more information. 1677 10.3. ChaCha20 and Poly1305 1679 ChaCha20 and Poly1305 combined together is a new AEAD mode that is 1680 defined in [RFC7539]. This is a new algorithm defined to be a cipher 1681 which is not AES and thus would not suffer from any future weaknesses 1682 found in AES. These cryptographic functions are designed to be fast 1683 in software only implementations. 1685 The ChaCha20/Poly1305 AEAD construction defined in [RFC7539] has no 1686 parameterization. It takes a 256-bit key and a 96-bit nonce as well 1687 as the plain text and additional data as inputs and produces the 1688 cipher text as an option. We define one algorithm identifier for 1689 this algorithm in Table 9. 1691 +-------------------+-------+----------------------------------+ 1692 | name | value | description | 1693 +-------------------+-------+----------------------------------+ 1694 | ChaCha20/Poly1305 | 11 | ChaCha20/Poly1305 w/ 256-bit key | 1695 +-------------------+-------+----------------------------------+ 1697 Table 9: Algorithm Value for AES-GCM 1699 Keys may be obtained either from a key structure or from a recipient 1700 structure. If the key obtained from a key structure, the key type 1701 MUST be 'Symmetric'. Implementations creating and validating MAC 1702 values MUST validate that the key type, key length and algorithm are 1703 correct and appropriate for the entities involved. 1705 10.3.1. Security Considerations 1707 The pair of key, nonce MUST be unique for every invocation of the 1708 algorithm. Nonce counters are considered to be an acceptable way of 1709 ensuring that they are unique. 1711 11. Key Derivation Functions (KDF) 1713 Key Derivation Functions (KDFs) are used to take some secret value 1714 and generate a different one. The original secret values come in 1715 three basic flavors: 1717 o Secrets which are uniformly random: This is the type of secret 1718 which is created by a good random number generator. 1720 o Secrets which are not uniformly random: This is type of secret 1721 which is created by operations like key agreement. 1723 o Secrets which are not random: This is the type of secret that 1724 people generate for things like passwords. 1726 General KDF functions work well with the first type of secret, can do 1727 reasonable well with the second type of secret and generally do 1728 poorly with the last type of secret. None of the KDF functions in 1729 this section are designed to deal with the type of secrets that are 1730 used for passwords. Functions like PBSE2 [RFC2898] need to be used 1731 for that type of secret. 1733 Many functions are going to handle the first two type of secrets 1734 differently. The KDF function defined in Section 11.1 can use 1735 different underlying constructions if the secret is uniformly random 1736 than if the secret is not uniformly random. This is reflected in the 1737 set of algorithms defined for HKDF. 1739 When using KDF functions, one component that is generally included is 1740 context information. Context information is used to allow for 1741 different keying information to be derived from the same secret. The 1742 use of context based keying material is considered to be a good 1743 security practice. This document defines a single context structure 1744 and a single KDF function. 1746 11.1. HMAC-based Extract-and-Expand Key Derivation Function (HKDF) 1748 The HKDF key derivation algorithm is defined in [RFC5869]. 1750 The HKDF algorithm is defined to take a number of inputs. These 1751 inputs are: 1753 secret - a shared value that is secret. Secrets may be either 1754 previously shared or derived from operations like a DH key 1755 agreement. 1757 salt - an optional public value that is used to change the 1758 generation process. If specified, the salt is carried using the 1759 'salt' algorithm parameter. While [RFC5869] suggests that the 1760 length of the salt be the same as the length of the underlying 1761 hash value, any amount of salt will improve the security as 1762 different key values will be generated. A parameter to carry the 1763 salt is defined in Table 11. This parameter is protected by being 1764 included in the key computation and does not need to be separately 1765 authenticated. 1767 length - the number of bytes of output that need to be generated. 1769 context information - Information that describes the context in 1770 which the resulting value will be used. Making this information 1771 specific to the context that the material is going to be used 1772 ensures that the resulting material will always be unique. The 1773 context structure used is encoded into the algorithm identifier. 1775 hash function - The underlying hash function to be used in the 1776 HKDF algorithm. The hash function is encoded into the HKDF 1777 algorithm selection. 1779 HKDF is defined to use HMAC as the underlying PRF. However, it is 1780 possible to use other functions in the same construct to provide a 1781 different KDF function that may be more appropriate in the 1782 constrained world. Specifically, one can use AES-CBC-MAC as the PRF 1783 for the expand step, but not for the extract step. When using a good 1784 random shared secret of the correct length, the extract step can be 1785 skipped. The extract cannot be skipped if the secret is not 1786 uniformly random, for example if it is the result of an ECDH key 1787 agreement step. 1789 The algorithms defined in this document are found in Table 10 1790 +-------------+-------------+----------+----------------------------+ 1791 | name | hash | Skip | context | 1792 | | | extract | | 1793 +-------------+-------------+----------+----------------------------+ 1794 | HKDF | SHA-256 | no | XXX | 1795 | SHA-256 | | | | 1796 | | | | | 1797 | HKDF | SHA-512 | no | XXX | 1798 | SHA-512 | | | | 1799 | | | | | 1800 | HKDF AES- | AES-CBC-128 | yes | HKDF using AES-MAC as the | 1801 | MAC-128 | | | PRF w/ 128-bit key | 1802 | | | | | 1803 | HKDF AES- | AES-CBC-128 | yes | HKDF using AES-MAC as the | 1804 | MAC-256 | | | PRF w/ 256-bit key | 1805 +-------------+-------------+----------+----------------------------+ 1807 Table 10: HKDF algorithms 1809 +------+-------+------+-------------+ 1810 | name | label | type | description | 1811 +------+-------+------+-------------+ 1812 | salt | -20 | bstr | Random salt | 1813 +------+-------+------+-------------+ 1815 Table 11: HKDF Algorithm Parameters 1817 11.2. Context Information Structure 1819 The context information structure is used to ensure that the derived 1820 keying material is "bound" to the context of the transaction. The 1821 context information structure used here is based on that defined in 1822 [SP800-56A]. By using CBOR for the encoding of the context 1823 information structure, we automatically get the same type of type and 1824 length separation of fields that is obtained by the use of ASN.1. 1825 This means that there is no need to encode the lengths for the base 1826 elements as it is done by the JOSE encoding. [CREF7] 1828 The context information structure refers to PartyU and PartyV as the 1829 two parties which are doing the key derivation. Unless the 1830 application protocol defines differently, we assign PartyU to the 1831 entity that is creating the message and PartyV to the entity that is 1832 receiving the message. By doing this association, different keys 1833 will be derived for each direction as the context information is 1834 different in each direction. 1836 Application protocols are free to define the roles differently. For 1837 example, they could assign the PartyU role to the entity that 1838 initiates the connection and allow directly sending multiple messages 1839 over the connection in both directions without changing the role 1840 information. 1842 The use of a transaction identifier, either in one of the 1843 supplemental fields or as the salt if one is using HKDF, ensures that 1844 a unique key is generated for each set of transactions. Combining 1845 nonce fields with the transaction identifier provides a method so 1846 that a different key is used for each message in each direction. 1848 The context structure is built from information that is known to both 1849 entities. Some of the information is known only to the two entities, 1850 some is implied based on the application and some is explicitly 1851 transported as part of the message. The information that can be 1852 carried in the message, parameters have been defined and can be found 1853 in Table 12. These parameters are designed to be placed in the 1854 unprotected bucket of the recipient structure. (They do not need to 1855 be in the protected bucket since they already are included in the 1856 cryptographic computation by virtue of being included in the context 1857 structure.) 1859 We encode the context specific information using a CBOR array type. 1860 The fields in the array are: 1862 AlgorithmID This field indicates the algorithm for which the key 1863 material will be used. This field is required to be present and 1864 is a copy of the algorithm identifier in the message. The field 1865 exists in the context information so that if the same environment 1866 is used for different algorithms, then completely different keys 1867 will be generated each of those algorithms. (This practice means 1868 if algorithm A is broken and thus can is easier to find, the key 1869 derived for algorithm B will not be the same as the key for 1870 algorithm B.) 1872 PartyUInfo This field holds information about party U. The 1873 PartyUInfo is encoded as a CBOR structure. The elements of 1874 PartyUInfo are encoded in the order presented, however if the 1875 element does not exist no element is placed in the array. The 1876 elements of the PartyUInfo array are: 1878 identity This contains the identity information for party U. The 1879 identities can be assigned in one of two manners. Firstly, a 1880 protocol can assign identities based on roles. For example, 1881 the roles of "client" and "server" may be assigned to different 1882 entities in the protocol. Each entity would then use the 1883 correct label for the data they send or receive. The second 1884 way is for a protocol to assign identities is to use a name 1885 based on a naming system (i.e. DNS, X.509 names). 1887 We define an algorithm parameter 'PartyU identity' that can be 1888 used to carry identity information in the message. However, 1889 identity information is often known as part of the protocol and 1890 can thus be inferred rather than made explicit. If identity 1891 information is carried in the message, applications SHOULD have 1892 a way of validating the supplied identity information. The 1893 identity information does not need to be specified and can be 1894 left as absent. 1895 The identity value supplied will be integrity checked as part 1896 of the key derivation process. If the identity string is 1897 wrong, then the wrong key will be created. 1899 nonce This contains a one time nonce value. The nonce can either 1900 be implicit from the protocol or carried as a value in the 1901 unprotected headers. 1902 We define an algorithm parameter 'PartyU nonce' that can be 1903 used to carry this value in the message However, the nonce 1904 value could be determined by the application and the value 1905 determined from elsewhere. 1906 This item is optional and can be absent. 1908 other This contains other information that is defined by the 1909 protocol. 1910 This item is optional and can be absent. 1912 PartyVInfo M00TODO: Copy down from PartyUInfo when that text is 1913 ready. 1915 SuppPubInfo This field contains public information that is mutually 1916 known to both parties. 1918 keyDataLength This is set to the number of bits of the desired 1919 output value. (This practice means if algorithm A can use two 1920 different key lengths, the key derived for longer key size will 1921 not contain the key for shorter key size as a prefix.) 1923 protected This field contains the protected parameter field. 1925 other The field other is for free form data defined by the 1926 application. An example is that an application could defined 1927 two different strings to be placed here to generate different 1928 keys for a data stream vs a control stream. This field is 1929 optional and will only be present if the application defines a 1930 structure for this information. Applications that define this 1931 SHOULD use CBOR to encode the data so that types and lengths 1932 are correctly include. 1934 SuppPrivInfo This field contains private information that is 1935 mutually known information. An example of this information would 1936 be a pre-existing shared secret. The field is optional and will 1937 only be present if the application defines a structure for this 1938 information. Applications that define this SHOULD use CBOR to 1939 encode the data so that types and lengths are correctly include. 1941 +---------------+-------+-----------+-------------------------------+ 1942 | name | label | type | description | 1943 +---------------+-------+-----------+-------------------------------+ 1944 | PartyU | -21 | bstr | Party U identity Information | 1945 | identity | | | | 1946 | | | | | 1947 | PartyU nonce | -22 | bstr / | Party U provided nonce | 1948 | | | int | | 1949 | | | | | 1950 | PartyU other | -23 | bstr | Party U other provided | 1951 | | | | information | 1952 | | | | | 1953 | PartyV | -24 | bstr | Party V identity Information | 1954 | identity | | | | 1955 | | | | | 1956 | PartyV nonce | -25 | bstr / | Party V provided nonce | 1957 | | | int | | 1958 | | | | | 1959 | PartyV other | -26 | bstr | Party V other provided | 1960 | | | | information | 1961 +---------------+-------+-----------+-------------------------------+ 1963 Table 12: Context Algorithm Parameters 1965 Text from here to start of next section to be removed 1966 COSE_KDF_Context = [ 1967 AlgorithmID : int / tstr, 1968 PartyUInfo : [ 1969 ? nonce : bstr / int, 1970 ? identity : bstr, 1971 ? other : bstr 1972 ], 1973 PartyVInfo : [ 1974 ? nonce : bstr, 1975 ? identity : bstr / tstr, 1976 ? other : bstr 1977 ], 1978 SuppPubInfo : [ 1979 keyDataLength : uint, 1980 protected : bstr, 1981 ? other : bstr 1982 ], 1983 ? SuppPrivInfo : bstr 1984 ] 1986 12. Recipient Algorithm Classes 1988 Recipient algorithms can be defined into a number of different 1989 classes. COSE has the ability to support many classes of recipient 1990 algorithms. In this section, a number of classes are listed and then 1991 a set of algorithms are specified for each of the classes. The names 1992 of the recipient algorithm classes used here are the same as are 1993 defined in [RFC7517]. Other specifications use different terms for 1994 the recipient algorithm classes or do not support some of our 1995 recipient algorithm classes. 1997 12.1. Direct Encryption 1999 The direct encryption class algorithms share a secret between the 2000 sender and the recipient that is used either directly or after 2001 manipulation as the content key. When direct encryption mode is 2002 used, it MUST be the only mode used on the message. 2004 The COSE_encrypt structure for the recipient is organized as follows: 2006 o The 'protected' field MUST be a zero length item if it is not used 2007 in the computation of the content key. 2009 o The 'alg' parameter MUST be present. 2011 o A parameter identifying the shared secret SHOULD be present. 2013 o The 'ciphertext' field MUST be a zero length item. 2015 o The 'recipients' field MUST be absent. 2017 12.1.1. Direct Key 2019 This recipient algorithm is the simplest, the supplied key is 2020 directly used as the key for the next layer down in the message. 2021 There are no algorithm parameters defined for this algorithm. The 2022 algorithm identifier value is assigned in Table 13. 2024 When this algorithm is used, the protected field MUST be zero length. 2025 The key type MUST be 'Symmetric'. 2027 +--------+-------+-------------------+ 2028 | name | value | description | 2029 +--------+-------+-------------------+ 2030 | direct | -6 | Direct use of CEK | 2031 +--------+-------+-------------------+ 2033 Table 13: Direct Key 2035 12.1.1.1. Security Considerations 2037 This recipient algorithm has several potential problems that need to 2038 be considered: 2040 o These keys need to have some method to be regularly updated over 2041 time. All of the content encryption algorithms specified in this 2042 document have limits on how many times a key can be used without 2043 significant loss of security. 2045 o These keys need to be dedicated to a single algorithm. There have 2046 been a number of attacks developed over time when a single key is 2047 used for multiple different algorithms. One example of this is 2048 the use of a single key both for CBC encryption mode and CBC-MAC 2049 authentication mode. 2051 o Breaking one message means all messages are broken. If an 2052 adversary succeeds in determining the key for a single message, 2053 then the key for all messages is also determined. 2055 12.1.2. Direct Key with KDF 2057 These recipient algorithms take a common shared secret between the 2058 two parties and applies the HKDF function (Section 11.1) using the 2059 context structure defined in Section 11.2 to transform the shared 2060 secret into the necessary key. Either the 'salt' parameter of HKDF 2061 or the partyU 'nonce' parameter of the context structure MUST be 2062 present. This parameter can be generated either randomly or 2063 deterministically, the requirement is that it be a unique value for 2064 the key pair in question. 2066 If the salt/nonce value is generated randomly, then it is suggested 2067 that the length of the random value be the same length as the hash 2068 function underlying HKDF. While there is no way to guarantee that it 2069 will be unique, there is a high probability that it will be unique. 2070 If the salt/nonce value is generated deterministically, it can be 2071 guaranteed to be unique and thus there is no length requirement. 2073 A new IV must be used if the same key is used in more than one 2074 message. The IV can be modified in a predictable manner, a random 2075 manner or an unpredictable manner. One unpredictable manner that can 2076 be used is to use the HKDF function to generate the IV. If HKDF is 2077 used for generating the IV, the algorithm identifier is set to "IV- 2078 GENERATION". 2080 When these algorithms are used, the key type MUST be 'symmetric'. 2082 The set of algorithms defined in this document can be found in 2083 Table 14. 2085 +---------------------+-------+-------------+-----------------------+ 2086 | name | value | KDF | description | 2087 +---------------------+-------+-------------+-----------------------+ 2088 | direct+HKDF-SHA-256 | * | HKDF | Shared secret w/ HKDF | 2089 | | | SHA-256 | and SHA-256 | 2090 | | | | | 2091 | direct+HKDF-SHA-512 | * | HKDF | Shared secret w/ HKDF | 2092 | | | SHA-512 | and SHA-512 | 2093 | | | | | 2094 | direct+HKDF-AES-128 | * | HKDF AES- | Shared secret w/ AES- | 2095 | | | MAC-128 | MAC 128-bit key | 2096 | | | | | 2097 | direct+HKDF-AES-256 | * | HKDF AES- | Shared secret w/ AES- | 2098 | | | MAC-256 | MAC 256-bit key | 2099 +---------------------+-------+-------------+-----------------------+ 2101 Table 14: Direct Key 2103 12.1.2.1. Security Considerations 2105 The shared secret need to have some method to be regularly updated 2106 over time. The shared secret is forming the basis of trust, although 2107 not used directly it should still be subject to scheduled rotation. 2109 12.2. Key Wrapping 2111 In key wrapping mode, the CEK is randomly generated and that key is 2112 then encrypted by a shared secret between the sender and the 2113 recipient. All of the currently defined key wrapping algorithms for 2114 JOSE (and thus for COSE) are AE algorithms. Key wrapping mode is 2115 considered to be superior to direct encryption if the system has any 2116 capability for doing random key generation. This is because the 2117 shared key is used to wrap random data rather than data has some 2118 degree of organization and may in fact be repeating the same content. 2120 The COSE_encrypt structure for the recipient is organized as follows: 2122 o The 'protected' field MUST be absent if the key wrap algorithm is 2123 an AE algorithm. 2125 o The 'recipients' field is normally absent, but can be used. 2126 Applications MUST deal with a recipients field present, not being 2127 able to decrypt that recipient is an acceptable way of dealing 2128 with it. Failing to process the message is not an acceptable way 2129 of dealing with it. 2131 o The plain text to be encrypted is the key from next layer down 2132 (usually the content layer). 2134 o At a minimum, the 'unprotected' field MUST contain the 'alg' 2135 parameter and SHOULD contain a parameter identifying the shared 2136 secret. 2138 12.2.1. AES Key Wrapping 2140 The AES Key Wrapping algorithm is defined in [RFC3394]. This 2141 algorithm uses an AES key to wrap a value that is a multiple of 2142 64-bits, as such it can be used to wrap a key for any of the content 2143 encryption algorithms defined in this document. The algorithm 2144 requires a single fixed parameter, the initial value. This is fixed 2145 to the value specified in Section 2.2.3.1 of [RFC3394]. There are no 2146 public parameters that vary on a per invocation basis. 2148 Keys may be obtained either from a key structure or from a recipient 2149 structure. If the key obtained from a key structure, the key type 2150 MUST be 'Symmetric'. Implementations creating and validating MAC 2151 values MUST validate that the key type, key length and algorithm are 2152 correct and appropriate for the entities involved. 2154 +--------+-------+----------+-----------------------------+ 2155 | name | value | key size | description | 2156 +--------+-------+----------+-----------------------------+ 2157 | A128KW | -3 | 128 | AES Key Wrap w/ 128-bit key | 2158 | | | | | 2159 | A192KW | -4 | 192 | AES Key Wrap w/ 192-bit key | 2160 | | | | | 2161 | A256KW | -5 | 256 | AES Key Wrap w/ 256-bit key | 2162 +--------+-------+----------+-----------------------------+ 2164 Table 15: AES Key Wrap Algorithm Values 2166 12.2.1.1. Security Considerations for AES-KW 2168 The shared secret need to have some method to be regularly updated 2169 over time. The shared secret is forming the basis of trust, although 2170 not used directly it should still be subject to scheduled rotation. 2172 12.3. Key Encryption 2174 Key Encryption mode is also called key transport mode in some 2175 standards. Key Encryption mode differs from Key Wrap mode in that it 2176 uses an asymmetric encryption algorithm rather than a symmetric 2177 encryption algorithm to protect the key. This document defines one 2178 Key Encryption mode algorithm. 2180 When using a key encryption algorithm, the COSE_encrypt structure for 2181 the recipient is organized as follows: 2183 o The 'protected' field MUST be absent. 2185 o The plain text to be encrypted is the key from next layer down 2186 (usually the content layer). 2188 o At a minimum, the 'unprotected' field MUST contain the 'alg' 2189 parameter and SHOULD contain a parameter identifying the 2190 asymmetric key. 2192 12.4. Direct Key Agreement 2194 The 'direct key agreement' class of recipient algorithms uses a key 2195 agreement method to create a shared secret. A KDF is then applied to 2196 the shared secret to derive a key to be used in protecting the data. 2197 This key is normally used as a CEK or MAC key, but could be used for 2198 other purposes if more than two layers are in use (see Appendix B). 2200 The most commonly used key agreement algorithm used is Diffie- 2201 Hellman, but other variants exist. Since COSE is designed for a 2202 store and forward environment rather than an on-line environment, 2203 many of the DH variants cannot be used as the receiver of the message 2204 cannot provide any key material. One side-effect of this is that 2205 perfect forward security is not achievable, a static key will always 2206 be used for the receiver of the COSE message. 2208 Two variants of DH that are easily supported are: 2210 - Ephemeral-Static DH: where the sender of the message creates a 2211 one time DH key and uses a static key for the recipient. The use 2212 of the ephemeral sender key means that no additional random input 2213 is needed as this is randomly generated for each message. 2215 Static-Static DH: where a static key is used for both the sender 2216 and the recipient. The use of static keys allows for recipient to 2217 get a weak version of data origination for the message. When 2218 static-static key agreement is used, then some piece of unique 2219 data is require to ensure that a different key is created for each 2220 message 2222 In this specification, both variants are specified. This has been 2223 done to provide the weak data origination option for use with MAC 2224 operations. 2226 When direct key agreement mode is used, there MUST be only one 2227 recipient in the message. This method creates the key directly and 2228 that makes it difficult to mix with additional recipients. If 2229 multiple recipients are needed, then the version with key wrap needs 2230 to be used. 2232 The COSE_encrypt structure for the recipient is organized as follows: 2234 o The 'protected' field MUST be absent. 2236 o At a minimum, the 'unprotected' field MUST contain the 'alg' 2237 parameter and SHOULD contain a parameter identifying the 2238 recipient's asymmetric key. 2240 o The 'unprotected' field MUST contain the 'epk' parameter. 2242 12.4.1. ECDH 2244 The basic mathematics for Elliptic Curve Diffie-Hellman can be found 2245 in [RFC6090]. 2247 ECDH is parameterized by the following: 2249 o Curve Type/Curve: The curve selected controls not only the size of 2250 the shared secret, but the mathematics for computing the shared 2251 secret. The curve selected also controls how a point in the curve 2252 is represented and what happens for the identity points on the 2253 curve. In this specification we allow for a number of different 2254 curves to be used. The curves are defined in Table 19. 2255 Since the only the math is changed by changing the curve, the 2256 curve is not fixed for any of the algorithm identifiers we define, 2257 instead it is defined by the points used. 2259 o Ephemeral-static or static-static: The key agreement process may 2260 be done using either a static or an ephemeral key at the sender's 2261 side. When using ephemeral keys, the sender MUST generate a new 2262 ephemeral key for every key agreement operation. The ephemeral 2263 key is placed in the 'ephemeral key' parameter and MUST be present 2264 for all algorithm identifiers which use ephemeral keys. When 2265 using static keys, the sender MUST either generate a new random 2266 value placed in either in the KDF parameters or the context 2267 structure. For the KDF functions used, this means either in the 2268 'salt' parameter for HKDF (Table 11) or in the 'PartyU nonce' 2269 parameter for the context structure (Table 12) MUST be present. 2270 (Both may be present if desired.) The value in the parameter MUST 2271 be unique for the key pair being used. It is acceptable to use a 2272 global counter which is incremented for every static-static 2273 operation and use the resulting value. When using static keys, 2274 the static key needs to be identified to the recipient. The 2275 static key can be identified either by providing the key ('static 2276 key') or by providing a key identifier for the static key ('static 2277 key id'). Both of these parameters are defined in Table 17 2279 o Key derivation algorithm: The result of an ECDH key agreement 2280 process does not provide a uniformly random secret, as such it 2281 needs to be run through a KDF in order to produce a usable key. 2282 Processing the secret through a KDF also allows for the 2283 introduction of both context material, how the key is going to be 2284 used, and one time material in the even to of a static-static key 2285 agreement. 2287 o Key Wrap algorithm: The key wrap algorithm can be 'none' if the 2288 result of the KDF is going to be used as the key directly. This 2289 option, along with static-static, should be used if knowledge 2290 about the sender is desired. If 'none' is used then the content 2291 layer encryption algorithm size is value fed to the context 2292 structure. Support is also provided for any of the key wrap 2293 algorithms defined in Section 12.2.1. If one of these options is 2294 used, the input key size to the key wrap algorithm is the value 2295 fed into the context structure as the key size. 2297 The set of algorithms direct ECDH defined in this document are found 2298 in Table 16. 2300 +-------------+------+-------+----------------+--------+------------+ 2301 | name | valu | KDF | Ephemeral- | Key | descriptio | 2302 | | e | | Static | Wrap | n | 2303 +-------------+------+-------+----------------+--------+------------+ 2304 | ECDH-ES + | 50 | HKDF | yes | none | ECDH ES w/ | 2305 | HKDF-256 | | - SHA | | | HKDF - | 2306 | | | -256 | | | generate | 2307 | | | | | | key | 2308 | | | | | | directly | 2309 | | | | | | | 2310 | ECDH-ES + | 51 | HKDF | yes | none | ECDH ES w/ | 2311 | HKDF-512 | | - SHA | | | HKDF - | 2312 | | | -256 | | | generate | 2313 | | | | | | key | 2314 | | | | | | directly | 2315 | | | | | | | 2316 | ECDH-SS + | 52 | HKDF | no | none | ECDH ES w/ | 2317 | HKDF-256 | | - SHA | | | HKDF - | 2318 | | | -256 | | | generate | 2319 | | | | | | key | 2320 | | | | | | directly | 2321 | | | | | | | 2322 | ECDH-SS + | 53 | HKDF | no | none | ECDH ES w/ | 2323 | HKDF-512 | | - SHA | | | HKDF - | 2324 | | | -256 | | | generate | 2325 | | | | | | key | 2326 | | | | | | directly | 2327 | | | | | | | 2328 | ECDH- | 54 | HKDF | yes | A128KW | ECDH ES w/ | 2329 | ES+A128KW | | - SHA | | | Concat KDF | 2330 | | | -256 | | | and AES | 2331 | | | | | | Key wrap | 2332 | | | | | | w/ 128 bit | 2333 | | | | | | key | 2334 | | | | | | | 2335 | ECDH- | 55 | HKDF | yes | A192KW | ECDH ES w/ | 2336 | ES+A192KW | | - SHA | | | Concat KDF | 2337 | | | -256 | | | and AES | 2338 | | | | | | Key wrap | 2339 | | | | | | w/ 192 bit | 2340 | | | | | | key | 2341 | | | | | | | 2342 | ECDH- | 56 | HKDF | yes | A256KW | ECDH ES w/ | 2343 | ES+A256KW | | - SHA | | | Concat KDF | 2344 | | | -256 | | | and AES | 2345 | | | | | | Key wrap | 2346 | | | | | | w/ 256 bit | 2347 | | | | | | key | 2348 | | | | | | | 2349 | ECDH- | 57 | HKDF | no | A128KW | ECDH SS w/ | 2350 | SS+A128KW | | - SHA | | | Concat KDF | 2351 | | | -256 | | | and AES | 2352 | | | | | | Key wrap | 2353 | | | | | | w/ 128 bit | 2354 | | | | | | key | 2355 | | | | | | | 2356 | ECDH- | 58 | HKDF | no | A192KW | ECDH SS w/ | 2357 | SS+A192KW | | - SHA | | | Concat KDF | 2358 | | | -256 | | | and AES | 2359 | | | | | | Key wrap | 2360 | | | | | | w/ 192 bit | 2361 | | | | | | key | 2362 | | | | | | | 2363 | ECDH- | 59 | HKDF | no | A256KW | ECDH SS w/ | 2364 | SS+A256KW | | - SHA | | | Concat KDF | 2365 | | | -256 | | | and AES | 2366 | | | | | | Key wrap | 2367 | | | | | | w/ 256 bit | 2368 | | | | | | key | 2369 +-------------+------+-------+----------------+--------+------------+ 2371 Table 16: ECDH Algorithm Values 2373 +-----------+-------+----------+-----------+------------------------+ 2374 | name | label | type | algorithm | description | 2375 +-----------+-------+----------+-----------+------------------------+ 2376 | ephemeral | -1 | COSE_Key | ECDH-ES | Ephemeral Public key | 2377 | key | | | | for the sender | 2378 | | | | | | 2379 | static | -2 | COSE_Key | ECDH-ES | Static Public key for | 2380 | key | | | | the sender | 2381 | | | | | | 2382 | static | -3 | bstr | ECDH-SS | Static Public key | 2383 | key id | | | | identifier for the | 2384 | | | | | sender | 2385 +-----------+-------+----------+-----------+------------------------+ 2387 Table 17: ECDH Algorithm Parameters 2389 This document defines these algorithms to be used with the curves 2390 P-256, P-384, P-521. Implementations MUST verify that the key type 2391 and curve are correct, different curves are restricted to different 2392 key types. Implementations MUST verify that the curve and algorithm 2393 are appropriate for the entities involved. 2395 12.5. Key Agreement with KDF 2397 Key Agreement with Key Wrapping uses a randomly generated CEK. The 2398 CEK is then encrypted using a Key Wrapping algorithm and a key 2399 derived from the shared secret computed by the key agreement 2400 algorithm. 2402 The COSE_encrypt structure for the recipient is organized as follows: 2404 o The 'protected' field is fed into the KDF context structure. 2406 o The plain text to be encrypted is the key from next layer down 2407 (usually the content layer). 2409 o The 'alg' parameter MUST be present in the layer. 2411 o A parameter identifying the recipient's key SHOULD be present. A 2412 parameter identifying the sender's key SHOULD be present. 2414 12.5.1. ECDH 2416 These algorithms are defined in Table 16. 2418 13. Keys 2420 The COSE_Key object defines a way to hold a single key object, it is 2421 still required that the members of individual key types be defined. 2422 This section of the document is where we define an initial set of 2423 members for specific key types. 2425 For each of the key types, we define both public and private members. 2426 The public members are what is transmitted to others for their usage. 2427 We define private members mainly for the purpose of archival of keys 2428 by individuals. However, there are some circumstances where private 2429 keys may be distributed by various entities in a protocol. Examples 2430 include: Entities which have poor random number generation. 2431 Centralized key creation for multi-cast type operations. Protocols 2432 where a shared secret is used as a bearer token for authorization 2433 purposes. 2435 Key types are identified by the 'kty' member of the COSE_Key object. 2436 In this document we define four values for the member. 2438 +-----------+-------+--------------------------------------------+ 2439 | name | value | description | 2440 +-----------+-------+--------------------------------------------+ 2441 | EC2 | 2 | Elliptic Curve Keys w/ X,Y Coordinate pair | 2442 | | | | 2443 | Symmetric | 4 | Symmetric Keys | 2444 | | | | 2445 | Reserved | 0 | This value is reserved | 2446 +-----------+-------+--------------------------------------------+ 2448 Table 18: Key Type Values 2450 13.1. Elliptic Curve Keys 2452 Two different key structures could be defined for Elliptic Curve 2453 keys. One version uses both an x and a y coordinate, potentially 2454 with point compression. This is the traditional EC point 2455 representation that is used in [RFC5480]. The other version uses 2456 only the x coordinate as the y coordinate is either to be recomputed 2457 or not needed for the key agreement operation Currently no algorithms 2458 are defined using this key structure. 2460 +-------+----------+-------+------------------------------------+ 2461 | name | key type | value | description | 2462 +-------+----------+-------+------------------------------------+ 2463 | P-256 | EC2 | 1 | NIST P-256 also known as secp256r1 | 2464 | | | | | 2465 | P-384 | EC2 | 2 | NIST P-384 also known as secp384r1 | 2466 | | | | | 2467 | P-521 | EC2 | 3 | NIST P-521 also known as secp521r1 | 2468 +-------+----------+-------+------------------------------------+ 2470 Table 19: EC Curves 2472 13.1.1. Double Coordinate Curves 2474 The traditional way of sending EC curves has been to send either both 2475 the x and y coordinates, or the x coordinate and a sign bit for the y 2476 coordinate. The latter encoding has not been recommended in the IETF 2477 due to potential IPR issues. However, for operations in constrained 2478 environments, the ability to shrink a message by not sending the y 2479 coordinate is potentially useful. 2481 For EC keys with both coordinates, the 'kty' member is set to 2 2482 (EC2). The key parameters defined in this section are summarized in 2483 Table 20. The members that are defined for this key type are: 2485 crv contains an identifier of the curve to be used with the key. 2486 The curves defined in this document for this key type can be found 2487 in Table 19. Other curves may be registered in the future and 2488 private curves can be used as well. 2490 x contains the x coordinate for the EC point. The integer is 2491 converted to an octet string as defined in [SEC1]. Zero octets 2492 MUST NOT be removed from the front of the octet string. 2494 y contains either the sign bit or the value of y coordinate for the 2495 EC point. For the value, the integer is converted to an octet 2496 string as defined in [SEC1]. Zero octets MUST NOT be removed from 2497 the front of the octet string. For the sign bit, the value is 2498 true if the value of y is positive. 2500 d contains the private key. 2502 For public keys, it is REQUIRED that 'crv', 'x' and 'y' be present in 2503 the structure. For private keys, it is REQUIRED that 'crv' and 'd' 2504 be present in the structure. For private keys, it is RECOMMENDED 2505 that 'x' and 'y' also be present, but they can be recomputed from the 2506 required elements and omitting them saves on space. 2508 +------+-------+-------+---------+----------------------------------+ 2509 | name | key | value | type | description | 2510 | | type | | | | 2511 +------+-------+-------+---------+----------------------------------+ 2512 | crv | 2 | -1 | int / | EC Curve identifier - Taken from | 2513 | | | | tstr | the COSE General Registry | 2514 | | | | | | 2515 | x | 2 | -2 | bstr | X Coordinate | 2516 | | | | | | 2517 | y | 2 | -3 | bstr / | Y Coordinate | 2518 | | | | bool | | 2519 | | | | | | 2520 | d | 2 | -4 | bstr | Private key | 2521 +------+-------+-------+---------+----------------------------------+ 2523 Table 20: EC Key Parameters 2525 13.2. Symmetric Keys 2527 Occasionally it is required that a symmetric key be transported 2528 between entities. This key structure allows for that to happen. 2530 For symmetric keys, the 'kty' member is set to 3 (Symmetric). The 2531 member that is defined for this key type is: 2533 k contains the value of the key. 2535 This key structure contains only private key information, care must 2536 be taken that it is never transmitted accidentally. For public keys, 2537 there are no required fields. For private keys, it is REQUIRED that 2538 'k' be present in the structure. 2540 +------+----------+-------+------+-------------+ 2541 | name | key type | value | type | description | 2542 +------+----------+-------+------+-------------+ 2543 | k | 4 | -1 | bstr | Key Value | 2544 +------+----------+-------+------+-------------+ 2546 Table 21: Symmetric Key Parameters 2548 14. CBOR Encoder Restrictions 2550 There has been an attempt to limit the number of places where the 2551 document needs to impose restrictions on how the CBOR Encoder needs 2552 to work. We have managed to narrow it down to the following 2553 restrictions: 2555 o The restriction applies to the encoding the Sig_structure, the 2556 Enc_structure, and the MAC_structure. 2558 o The rules for Canonical CBOR (Section 3.9 of RFC 7049) MUST be 2559 used in these locations. The main rule that needs to be enforced 2560 is that all lengths in these structures MUST be encoded such that 2561 they are encoded using definite lengths and the minimum length 2562 encoding is used. 2564 o All parsers used SHOULD fail on both parsing and generation if the 2565 same label is used twice as a key for the same map. 2567 15. IANA Considerations 2569 15.1. CBOR Tag assignment 2571 It is requested that IANA assign the following tags from the "Concise 2572 Binary Object Representation (CBOR) Tags" registry. It is requested 2573 that the tags be assigned in the 24 to 255 value range. 2575 The tags to be assigned are: 2577 +-----------+-----------------------+-------------------------------+ 2578 | Tag Value | Data Item | Semantics | 2579 +-----------+-----------------------+-------------------------------+ 2580 | TBD1 | COSE_Sign | COSE Signed Data Object | 2581 | | | | 2582 | TBD2 | COSE_enveloped | COSE Enveloped Data Object | 2583 | | | | 2584 | TBD3 | COSE_encryptData | COSE Encrypted Data Object | 2585 | | | | 2586 | TBD4 | COSE_Mac | COSE Mac-ed Data Object | 2587 | | | | 2588 | TBD5 | COSE_Key, COSE_KeySet | COSE Key or COSE Key Set | 2589 | | | Object | 2590 +-----------+-----------------------+-------------------------------+ 2592 15.2. COSE Header Parameter Registry 2594 It is requested that IANA create a new registry entitled "COSE Header 2595 Parameters". 2597 The columns of the registry are: 2599 name The name is present to make it easier to refer to and discuss 2600 the registration entry. The value is not used in the protocol. 2601 Names are to be unique in the table. 2603 label This is the value used for the label. The label can be either 2604 an integer or a string. Registration in the table is based on the 2605 value of the label requested. Integer values between 1 and 255 2606 and strings of length 1 are designated as Standards Track Document 2607 required. Integer values from 256 to 65535 and strings of length 2608 2 are designated as Specification Required. Integer values of 2609 greater than 65535 and strings of length greater than 2 are 2610 designated as first come first server. Integer values in the 2611 range -1 to -65536 are delegated to the "COSE Header Algorithm 2612 Label" registry. Integer values beyond -65536 are marked as 2613 private use. 2615 value This contains the CBOR type for the value portion of the 2616 label. 2618 value registry This contains a pointer to the registry used to 2619 contain values where the set is limited. 2621 description This contains a brief description of the header field. 2623 specification This contains a pointer to the specification defining 2624 the header field (where public). 2626 The initial contents of the registry can be found in Table 1. The 2627 specification column for all rows in that table should be this 2628 document. 2630 Additionally, the label of 0 is to be marked as 'Reserved'. 2632 15.3. COSE Header Algorithm Label Table 2634 It is requested that IANA create a new registry entitled "COSE Header 2635 Algorithm Labels". 2637 The columns of the registry are: 2639 name The name is present to make it easier to refer to and discuss 2640 the registration entry. The value is not used in the protocol. 2642 algorithm The algorithm(s) that this registry entry is used for. 2643 This value is taken from the "COSE Algorithm Value" registry. 2644 Multiple algorithms can be specified in this entry. For the 2645 table, the algorithm, label pair MUST be unique. 2647 label This is the value used for the label. The label is an integer 2648 in the range of -1 to -65536. 2650 value This contains the CBOR type for the value portion of the 2651 label. 2653 value registry This contains a pointer to the registry used to 2654 contain values where the set is limited. 2656 description This contains a brief description of the header field. 2658 specification This contains a pointer to the specification defining 2659 the header field (where public). 2661 The initial contents of the registry can be found in: Table 11, 2662 Table 12, Table 17. The specification column for all rows in that 2663 table should be this document. 2665 15.4. COSE Algorithm Registry 2667 It is requested that IANA create a new registry entitled "COSE 2668 Algorithm Registry". 2670 The columns of the registry are: 2672 value The value to be used to identify this algorithm. Algorithm 2673 values MUST be unique. The value can be a positive integer, a 2674 negative integer or a string. Integer values between 0 and 255 2675 and strings of length 1 are designated as Standards Track Document 2676 required. Integer values from 256 to 65535 and strings of length 2677 2 are designated as Specification Required. Integer values of 2678 greater than 65535 and strings of length greater than 2 are 2679 designated as first come first server. Integer values in the 2680 range -1 to -65536 are delegated to the "COSE Header Algorithm 2681 Label" registry. Integer values beyond -65536 are marked as 2682 private use. 2684 description A short description of the algorithm. 2686 specification A document where the algorithm is defined (if publicly 2687 available). 2689 The initial contents of the registry can be found in the following: 2690 Table 8, Table 7, Table 9, Table 4, Table 5, Table 6, Table 13, 2691 Table 14, Table 15, Table 16. The specification column for all rows 2692 in that table should be this document. 2694 15.5. COSE Key Common Parameter Registry 2696 It is requested that IANA create a new registry entitled "COSE Key 2697 Common Parameter" Registry. 2699 The columns of the registry are: 2701 name This is a descriptive name that enables easier reference to the 2702 item. It is not used in the encoding. 2704 label The value to be used to identify this algorithm. Key map 2705 labels MUST be unique. The label can be a positive integer, a 2706 negative integer or a string. Integer values between 0 and 255 2707 and strings of length 1 are designated as Standards Track Document 2708 required. Integer values from 256 to 65535 and strings of length 2709 2 are designated as Specification Required. Integer values of 2710 greater than 65535 and strings of length greater than 2 are 2711 designated as first come first server. Integer values in the 2712 range -1 to -65536 are used for key parameters specific to a 2713 single algorithm delegated to the "COSE Key Parameter Label" 2714 registry. Integer values beyond -65536 are marked as private use. 2716 CBOR Type This field contains the CBOR type for the field 2718 registry This field denotes the registry that values come from, if 2719 one exists. 2721 description This field contains a brief description for the field 2722 specification This contains a pointer to the public specification 2723 for the field if one exists 2725 This registry will be initially populated by the values in 2726 Section 7.1. The specification column for all of these entries will 2727 be this document. 2729 15.6. COSE Key Type Parameter Registry 2731 It is requested that IANA create a new registry "COSE Key Type 2732 Parameters". 2734 The columns of the table are: 2736 key type This field contains a descriptive string of a key type. 2737 This should be a value that is in the COSE General Values table 2738 and is placed in the 'kty' field of a COSE Key structure. 2740 name This is a descriptive name that enables easier reference to the 2741 item. It is not used in the encoding. 2743 label The label is to be unique for every value of key type. The 2744 range of values is from -256 to -1. Labels are expected to be 2745 reused for different keys. 2747 CBOR type This field contains the CBOR type for the field 2749 description This field contains a brief description for the field 2751 specification This contains a pointer to the public specification 2752 for the field if one exists 2754 This registry will be initially populated by the values in Table 20, 2755 and Table 21. The specification column for all of these entries will 2756 be this document. 2758 15.7. COSE Elliptic Curve Registry 2760 It is requested that IANA create a new registry "COSE Elliptic Curve 2761 Parameters". 2763 The columns of the table are: 2765 name This is a descriptive name that enables easier reference to the 2766 item. It is not used in the encoding. 2768 value This is the value used to identify the curve. These values 2769 MUST be unique. The integer values from -256 to 255 are 2770 designated as Standards Track Document Required. The integer 2771 values from 256 to 65535 and -65536 to -257 are designated as 2772 Specification Required. Integer values over 65535 are designated 2773 as first come first serve. Integer values less than -65536 are 2774 marked as private use. 2776 key type This designates the key type(s) that can be used with this 2777 curve. 2779 description This field contains a brief description of the curve. 2781 specification This contains a pointer to the public specification 2782 for the curve if one exists. 2784 This registry will be initially populated by the values in Table 18. 2785 The specification column for all of these entries will be this 2786 document. 2788 15.8. Media Type Registrations 2790 15.8.1. COSE Security Message 2792 This section registers the "application/cose" and "application/ 2793 cose+cbor" media types in the "Media Types" registry. [CREF8] These 2794 media types are used to indicate that the content is a COSE_MSG. 2795 [CREF9] 2797 Type name: application 2799 Subtype name: cose 2801 Required parameters: N/A 2803 Optional parameters: N/A 2805 Encoding considerations: binary 2807 Security considerations: See the Security Considerations section 2808 of RFC TBD. 2810 Interoperability considerations: N/A 2812 Published specification: RFC TBD 2814 Applications that use this media type: To be identified 2816 Fragment identifier considerations: N/A 2817 Additional information: 2819 * Magic number(s): N/A 2821 * File extension(s): cbor 2823 * Macintosh file type code(s): N/A 2825 Person & email address to contact for further information: 2826 iesg@ietf.org 2828 Intended usage: COMMON 2830 Restrictions on usage: N/A 2832 Author: Jim Schaad, ietf@augustcellars.com 2834 Change Controller: IESG 2836 Provisional registration? No 2838 Type name: application 2840 Subtype name: cose+cbor 2842 Required parameters: N/A 2844 Optional parameters: N/A 2846 Encoding considerations: binary 2848 Security considerations: See the Security Considerations section 2849 of RFC TBD. 2851 Interoperability considerations: N/A 2853 Published specification: RFC TBD 2855 Applications that use this media type: To be identified 2857 Fragment identifier considerations: N/A 2859 Additional information: 2861 * Magic number(s): N/A 2863 * File extension(s): cbor 2864 * Macintosh file type code(s): N/A 2866 Person & email address to contact for further information: 2867 iesg@ietf.org 2869 Intended usage: COMMON 2871 Restrictions on usage: N/A 2873 Author: Jim Schaad, ietf@augustcellars.com 2875 Change Controller: IESG 2877 Provisional registration? No 2879 15.8.2. COSE Key media type 2881 This section registers the "application/cose+json" and "application/ 2882 cose-set+json" media types in the "Media Types" registry. These 2883 media types are used to indicate, respectively, that content is a 2884 COSE_Key or COSE_KeySet object. 2886 Type name: application 2888 Subtype name: cose-key+cbor 2890 Required parameters: N/A 2892 Optional parameters: N/A 2894 Encoding considerations: binary 2896 Security considerations: See the Security Considerations section 2897 of RFC TBD. 2899 Interoperability considerations: N/A 2901 Published specification: RFC TBD 2903 Applications that use this media type: To be identified 2905 Fragment identifier considerations: N/A 2907 Additional information: 2909 * Magic number(s): N/A 2911 * File extension(s): cbor 2912 * Macintosh file type code(s): N/A 2914 Person & email address to contact for further information: 2915 iesg@ietf.org 2917 Intended usage: COMMON 2919 Restrictions on usage: N/A 2921 Author: Jim Schaad, ietf@augustcellars.com 2923 Change Controller: IESG 2925 Provisional registration? No 2927 Type name: application 2929 Subtype name: cose-key-set+cbor 2931 Required parameters: N/A 2933 Optional parameters: N/A 2935 Encoding considerations: binary 2937 Security considerations: See the Security Considerations section 2938 of RFC TBD. 2940 Interoperability considerations: N/A 2942 Published specification: RFC TBD 2944 Applications that use this media type: To be identified 2946 Fragment identifier considerations: N/A 2948 Additional information: 2950 * Magic number(s): N/A 2952 * File extension(s): cbor 2954 * Macintosh file type code(s): N/A 2956 Person & email address to contact for further information: 2957 iesg@ietf.org 2959 Intended usage: COMMON 2960 Restrictions on usage: N/A 2962 Author: Jim Schaad, ietf@augustcellars.com 2964 Change Controller: IESG 2966 Provisional registration? No 2968 15.9. CoAP Content Format Registrations 2970 This section registers a set of content formats for CoAP. ID 2971 assignment in the 24-255 range requested. 2973 +--------------------------+----------+-------+-----------------+ 2974 | Media Type | Encoding | ID | Reference | 2975 +--------------------------+----------+-------+-----------------+ 2976 | application/cose | | TBD10 | [This Document] | 2977 | | | | | 2978 | application/cose-key | | TBD11 | [This Document] | 2979 | | | | | 2980 | application/cose-key-set | | TBD12 | [This Document | 2981 +--------------------------+----------+-------+-----------------+ 2983 16. Security Considerations 2985 There are security considerations: 2987 1. Protect private keys 2989 2. MAC messages with more than one recipient means one cannot figure 2990 out who sent the message 2992 3. Use of direct key with other recipient structures hands the key 2993 to other recipients. 2995 4. Use of direct ECDH direct encryption is easy for people to leak 2996 information on if there are other recipients in the message. 2998 5. Considerations about protected vs unprotected header fields. 3000 6. Need to verify that: 1) the kty field of the key matches the key 3001 and algorithm being used. 2) the kty field needs to be included 3002 in the trust decision as well as the other key fields. 3) the 3003 algorithm be included in the trust decision. 3005 17. References 3007 17.1. Normative References 3009 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3010 Requirement Levels", BCP 14, RFC 2119, March 1997. 3012 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 3013 Representation (CBOR)", RFC 7049, October 2013. 3015 17.2. Informative References 3017 [AES-GCM] Dworkin, M., "NIST Special Publication 800-38D: 3018 Recommendation for Block Cipher Modes of Operation: 3019 Galois/Counter Mode (GCM) and GMAC.", Nov 2007. 3021 [DSS] U.S. National Institute of Standards and Technology, 3022 "Digital Signature Standard (DSS)", July 2013. 3024 [I-D.greevenbosch-appsawg-cbor-cddl] 3025 Vigano, C., Birkholz, H., and R. Sun, "CBOR data 3026 definition language: a notational convention to express 3027 CBOR data structures.", draft-greevenbosch-appsawg-cbor- 3028 cddl-05 (work in progress), March 2015. 3030 [MAC] NiST, N., "FIPS PUB 113: Computer Data Authentication", 3031 May 1985. 3033 [MultiPrimeRSA] 3034 Hinek, M. and D. Cheriton, "On the Security of Multi-prime 3035 RSA", June 2006. 3037 [PVSig] Brown, D. and D. Johnson, "Formal Security Proofs for a 3038 Signature Scheme with Partial Message Recover", February 3039 2000. 3041 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 3042 Hashing for Message Authentication", RFC 2104, February 3043 1997. 3045 [RFC2633] Ramsdell, B., "S/MIME Version 3 Message Specification", 3046 RFC 2633, June 1999. 3048 [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography 3049 Specification Version 2.0", RFC 2898, DOI 10.17487/ 3050 RFC2898, September 2000, 3051 . 3053 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 3054 (AES) Key Wrap Algorithm", RFC 3394, September 2002. 3056 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 3057 Standards (PKCS) #1: RSA Cryptography Specifications 3058 Version 2.1", RFC 3447, February 2003. 3060 [RFC3610] Whiting, D., Housley, R., and N. Ferguson, "Counter with 3061 CBC-MAC (CCM)", RFC 3610, September 2003. 3063 [RFC4231] Nystrom, M., "Identifiers and Test Vectors for HMAC-SHA- 3064 224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512", RFC 3065 4231, December 2005. 3067 [RFC4262] Santesson, S., "X.509 Certificate Extension for Secure/ 3068 Multipurpose Internet Mail Extensions (S/MIME) 3069 Capabilities", RFC 4262, December 2005. 3071 [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, 3072 "Elliptic Curve Cryptography Subject Public Key 3073 Information", RFC 5480, March 2009. 3075 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 3076 RFC 5652, September 2009. 3078 [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet 3079 Mail Extensions (S/MIME) Version 3.2 Message 3080 Specification", RFC 5751, January 2010. 3082 [RFC5752] Turner, S. and J. Schaad, "Multiple Signatures in 3083 Cryptographic Message Syntax (CMS)", RFC 5752, January 3084 2010. 3086 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 3087 Key Derivation Function (HKDF)", RFC 5869, May 2010. 3089 [RFC5990] Randall, J., Kaliski, B., Brainard, J., and S. Turner, 3090 "Use of the RSA-KEM Key Transport Algorithm in the 3091 Cryptographic Message Syntax (CMS)", RFC 5990, September 3092 2010. 3094 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 3095 Curve Cryptography Algorithms", RFC 6090, February 2011. 3097 [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations 3098 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 3099 RFC 6151, March 2011. 3101 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 3102 Algorithm (DSA) and Elliptic Curve Digital Signature 3103 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 3104 2013, . 3106 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 3107 Interchange Format", RFC 7159, March 2014. 3109 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 3110 Application Protocol (CoAP)", RFC 7252, DOI 10.17487/ 3111 RFC7252, June 2014, 3112 . 3114 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 3115 Signature (JWS)", RFC 7515, May 2015. 3117 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 3118 RFC 7516, May 2015. 3120 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, May 2015. 3122 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, May 3123 2015. 3125 [RFC7539] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF 3126 Protocols", RFC 7539, DOI 10.17487/RFC7539, May 2015, 3127 . 3129 [SEC1] Standards for Efficient Cryptography Group, "SEC 1: 3130 Elliptic Curve Cryptography", May 2009. 3132 [SP800-56A] 3133 Barker, E., Chen, L., Roginsky, A., and M. Smid, "NIST 3134 Special Publication 800-56A: Recommendation for Pair-Wise 3135 Key Establishment Schemes Using Discrete Logarithm 3136 Cryptography", May 2013. 3138 Appendix A. CDDL Grammar 3140 For people who prefer using a formal language to describe the syntax 3141 of the CBOR, in this section a CDDL grammar is given that corresponds 3142 to [I-D.greevenbosch-appsawg-cbor-cddl]. This grammar is 3143 informational, in the event of differences between this grammar and 3144 the prose, the prose is considered to be authoritative. 3146 The collected CDDL can be extracted from the XML version of this 3147 document via the following XPath expression below. (Depending on the 3148 XPath evaluator one is using, it may be necessary to deal with > 3149 as an entity.) 3151 //artwork[@type='CDDL']/text() 3153 Appendix B. Three Levels of Recipient Information 3155 All of the currently defined recipient algorithms classes only use 3156 two levels of the COSE_Encrypt structure. The first level is the 3157 message content and the second level is the content key encryption. 3158 However, if one uses a recipient algorithm such as RSA-KEM (see 3159 Appendix A of RSA-KEM [RFC5990], then it make sense to have three 3160 levels of the COSE_Encrypt structure. 3162 These levels would be: 3164 o Level 0: The content encryption level. This level contains the 3165 payload of the message. 3167 o Level 1: The encryption of the CEK by a KEK. 3169 o Level 2: The encryption of a long random secret using an RSA key 3170 and a key derivation function to convert that secret into the KEK. 3172 This is an example of what a triple layer message would look like. 3173 The message has the following layers: 3175 o Level 0: Has a content encrypted with AES-GCM using a 128-bit key. 3177 o Level 1: Uses the AES Key wrap algorithm with a 128-bit key. 3179 o Level 2: Uses ECDH Ephemeral-Static direct to generate the level 1 3180 key. 3182 In effect this example is a decomposed version of using the ECDH- 3183 ES+A128KW algorithm. 3185 Size of binary file is 216 bytes 3186 998( [ 3187 h'a10101', 3188 { 3189 5: h'02d1f7e6f26c43d4868d87ce' 3190 }, 3191 h'64f84d913ba60a76070a9a48f26e97e863e285295a44320878caceb0763a3 3192 34806857c67', 3193 [ 3194 [ 3195 h'', 3196 { 3197 1: -3 3198 }, 3199 h'5a15dbf5b282ecb31a6074ee3815c252405dd7583e078188', 3200 [ 3201 [ 3202 h'', 3203 { 3204 1: 50, 3205 4: h'6d65726961646f632e6272616e64796275636b406275636b 3206 6c616e642e6578616d706c65', 3207 -1: { 3208 1: 2, 3209 -1: 1, 3210 -2: h'b2add44368ea6d641f9ca9af308b4079aeb519f11e9b8 3211 a55a600b21233e86e68', 3212 -3: h'1a2cf118b9ee6895c8f415b686d4ca1cef362d4a7630a 3213 31ef6019c0c56d33de0' 3214 } 3215 }, 3216 h'' 3217 ] 3218 ] 3219 ] 3220 ] 3221 ]) 3223 Appendix C. Examples 3225 The examples can be found at https://github.com/cose-wg/Examples. 3226 The file names in each section correspond the same file names in the 3227 repository. I am currently still in the process of getting the 3228 examples up there along with some control information for people to 3229 be able to check and reproduce the examples. 3231 Examples may have some features that are in questions but not yet 3232 incorporated in the document. 3234 To make it easier to read, the examples are presented using the 3235 CBOR's diagnostic notation rather than a binary dump. A ruby based 3236 tool exists to convert between a number of formats. This tool can be 3237 installed with the command line: 3239 gem install cbor-diag 3241 The diagnostic notation can be converted into binary files using the 3242 following command line: 3244 diag2cbor < inputfile > outputfile 3246 The examples can be extracted from the XML version of this document 3247 via an XPath expression as all of the artwork is tagged with the 3248 attribute type='CBORdiag'. 3250 C.1. Examples of MAC messages 3252 C.1.1. Shared Secret Direct MAC 3254 This example users the following: 3256 o MAC: AES-CMAC, 256-bit key, truncated to 64 bits 3258 o Recipient class: direct shared secret 3260 o File name: Mac-04 3262 Size of binary file is 73 bytes 3263 996( [ 3264 h'a1016f4145532d434d41432d3235362f3634', 3265 { 3266 }, 3267 h'546869732069732074686520636f6e74656e742e', 3268 h'd9afa663dd740848', 3269 [ 3270 [ 3271 h'', 3272 { 3273 1: -6, 3274 4: h'6f75722d736563726574' 3275 }, 3276 h'' 3277 ] 3278 ] 3279 ]) 3281 C.1.2. ECDH Direct MAC 3283 This example uses the following: 3285 o MAC: HMAC w/SHA-256, 256-bit key 3287 o Recipient class: ECDH key agreement, two static keys, HKDF w/ 3288 context structure 3290 Size of binary file is 217 bytes 3291 996( [ 3292 h'a10104', 3293 { 3294 }, 3295 h'546869732069732074686520636f6e74656e742e', 3296 h'2ba937ca03d76c3dbad30cfcbaeef586f9c0f9ba616ad67e9205d38576ad9 3297 930', 3298 [ 3299 [ 3300 h'', 3301 { 3302 1: 52, 3303 4: h'6d65726961646f632e6272616e64796275636b406275636b6c61 3304 6e642e6578616d706c65', 3305 -3: h'706572656772696e2e746f6f6b407475636b626f726f7567682 3306 e6578616d706c65', 3307 "apu": h'4d8553e7e74f3c6a3a9dd3ef286a8195cbf8a23d19558ccf 3308 ec7d34b824f42d92bd06bd2c7f0271f0214e141fb779ae2856abf585a58368b01 3309 7e7f2a9e5ce4db5' 3310 }, 3311 h'' 3312 ] 3313 ] 3314 ]) 3316 C.1.3. Wrapped MAC 3318 This example uses the following: 3320 o MAC: AES-MAC, 128-bit key, truncated to 64 bits 3322 o Recipient class: AES keywrap w/ a pre-shared 256-bit key 3324 Size of binary file is 124 bytes 3325 996( [ 3326 h'a1016e4145532d3132382d4d41432d3634', 3327 { 3328 }, 3329 h'546869732069732074686520636f6e74656e742e', 3330 h'6d1fa77b2dd9146a', 3331 [ 3332 [ 3333 h'', 3334 { 3335 1: -5, 3336 4: h'30313863306165352d346439622d343731622d626664362d6565 3337 66333134626337303337' 3338 }, 3339 h'711ab0dc2fc4585dce27effa6781c8093eba906f227b6eb0' 3340 ] 3341 ] 3342 ]) 3344 C.1.4. Multi-recipient MAC message 3346 This example uses the following: 3348 o MAC: HMAC w/ SHA-256, 128-bit key 3350 o Recipient class: Uses three different methods 3352 1. ECDH Ephemeral-Static, Curve P-521, AES-Key Wrap w/ 128-bit 3353 key 3355 2. AES-Key Wrap w/ 256-bit key 3357 Size of binary file is 374 bytes 3358 996( [ 3359 h'a10104', 3360 { 3361 }, 3362 h'546869732069732074686520636f6e74656e742e', 3363 h'7aaa6e74546873061f0a7de21ff0c0658d401a68da738dd893748651983ce 3364 1d0', 3365 [ 3366 [ 3367 h'', 3368 { 3369 1: 55, 3370 4: h'62696c626f2e62616767696e7340686f626269746f6e2e657861 3371 6d706c65', 3372 -1: { 3373 1: 2, 3374 -1: 3, 3375 -2: h'43b12669acac3fd27898ffba0bcd2e6c366d53bc4db71f909 3376 a759304acfb5e18cdc7ba0b13ff8c7636271a6924b1ac63c02688075b55ef2d61 3377 3574e7dc242f79c3', 3378 -3: h'812dd694f4ef32b11014d74010a954689c6b6e8785b333d1a 3379 b44f22b9d1091ae8fc8ae40b687e5cfbe7ee6f8b47918a07bb04e9f5b1a51a334 3380 a16bc09777434113' 3381 } 3382 }, 3383 h'f20ad9c96134f3c6be4f75e7101c0ecc5efa071ff20a87fd1ac285109 3384 41ee0376573e2b384b56b99' 3385 ], 3386 [ 3387 h'', 3388 { 3389 1: -5, 3390 4: h'30313863306165352d346439622d343731622d626664362d6565 3391 66333134626337303337' 3392 }, 3393 h'0b2c7cfce04e98276342d6476a7723c090dfdd15f9a518e7736549e99 3394 8370695e6d6a83b4ae507bb' 3395 ] 3396 ] 3397 ]) 3399 C.2. Examples of Encrypted Messages 3401 C.2.1. Direct ECDH 3403 This example uses the following: 3405 o CEK: AES-GCM w/ 128-bit key 3406 o Recipient class: ECDH Ephemeral-Static, Curve P-256 3408 Size of binary file is 184 bytes 3410 998( [ 3411 h'a10101', 3412 { 3413 5: h'c9cf4df2fe6c632bf7886413' 3414 }, 3415 h'45fce2814311024d3a479e7d3eed063850f3f0b9f3f948677e3ae9869bcf9 3416 ff4e1763812', 3417 [ 3418 [ 3419 h'', 3420 { 3421 1: 50, 3422 4: h'6d65726961646f632e6272616e64796275636b406275636b6c61 3423 6e642e6578616d706c65', 3424 -1: { 3425 1: 2, 3426 -1: 1, 3427 -2: h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf05 3428 4e1c7b4d91d6280', 3429 -3: h'f01400b089867804b8e9fc96c3932161f1934f4223069170d 3430 924b7e03bf822bb' 3431 } 3432 }, 3433 h'' 3434 ] 3435 ] 3436 ]) 3438 C.2.2. Direct plus Key Derivation 3440 This example uses the following: 3442 o CEK: AES-CCM w/128-bit key, truncate the tag to 64-bits 3444 o Recipient class: Use HKDF on a shared secret with the following 3445 implicit fields as part of the context. 3447 * APU identity: "lighting-client" 3449 * APV identity: "lighting-server" 3451 * Supplementary Public Other: "Encryption Example 02" 3453 Size of binary file is 97 bytes 3454 998( [ 3455 h'a1010a', 3456 { 3457 5: h'89f52f65a1c580933b5261a7' 3458 }, 3459 h'7b9dcfa42c4e1d3182c402dc18ef8b5637de4fb62cf1dd156ea6e6e0', 3460 [ 3461 [ 3462 h'', 3463 { 3464 1: "dir+kdf", 3465 4: h'6f75722d736563726574', 3466 -20: h'61616262636364646565666667676868' 3467 }, 3468 h'' 3469 ] 3470 ] 3471 ]) 3473 C.3. Examples of Signed Message 3475 C.3.1. Single Signature 3477 This example uses the following: 3479 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256-1 3481 Size of binary file is 105 bytes 3483 999( [ 3484 h'', 3485 { 3486 }, 3487 h'546869732069732074686520636f6e74656e742e', 3488 [ 3489 [ 3490 h'a10126', 3491 { 3492 4: h'3131' 3493 }, 3494 h'4358e9e92b46d45134548b6e3b4eae3d2f801bce85236c7aab42968ad 3495 8e3e92400873ed761735222a6d1f442c4bb3a3151946b16900048572455e65451 3496 d89aaba7' 3497 ] 3498 ] 3499 ]) 3501 C.3.2. Multiple Signers 3503 This example uses the following: 3505 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256-1 3507 o Signature Algorithm: ECDSA w/ SHA-512, Curve P-521 3509 Size of binary file is 277 bytes 3511 999( [ 3512 h'', 3513 { 3514 }, 3515 h'546869732069732074686520636f6e74656e742e', 3516 [ 3517 [ 3518 h'a10126', 3519 { 3520 4: h'3131' 3521 }, 3522 h'0dc1c5e62719d8f3cce1468b7c881eee6a8088b46bf836ae956dd38fe 3523 931991900823ea760648f2425b96c39e23ddc4b7faed56d4a9bd0f3752cfdc628 3524 254ed0f2' 3525 ], 3526 [ 3527 h'', 3528 { 3529 1: -9, 3530 4: h'62696c626f2e62616767696e7340686f626269746f6e2e657861 3531 6d706c65' 3532 }, 3533 h'012ce5b1dfe8b5aa6eaa09a54c58a84ad0900e4fdf2759ec22d1c861c 3534 ccd75c7e1c4025a2da35e512fc2874d6ac8fd862d09ad07ed2deac297b897561e 3535 04a8d42476011eb209c016416b4247b4d1475c398d35c4ac24d1c9fadda7eefe2 3536 857e25a500d29aea539e58e8ca7737fe450d4e87ed3f78e637c12bbd213e78ba8 3537 3a55f7e89934' 3538 ] 3539 ] 3540 ]) 3542 C.4. COSE Keys 3544 C.4.1. Public Keys 3546 This is an example of a COSE Key set. This example includes the 3547 public keys for all of the previous examples. 3549 In order the keys are: 3551 o An EC key with a kid of "meriadoc.brandybuck@buckland.example" 3553 o An EC key with a kid of "peregrin.took@tuckborough.example" 3555 o An EC key with a kid of "bilbo.baggins@hobbiton.example" 3557 o An EC key with a kid of "11" 3559 Size of binary file is 481 bytes 3561 [ 3562 { 3563 -1: 1, 3564 -2: h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de4 3565 39c08551d', 3566 -3: h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eec 3567 d0084d19c', 3568 1: 2, 3569 2: h'6d65726961646f632e6272616e64796275636b406275636b6c616e64 3570 2e6578616d706c65' 3571 }, 3572 { 3573 -1: 3, 3574 -2: h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737b 3575 f5de7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620 3576 085e5c8f42ad', 3577 -3: h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e 3578 247e60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f 3579 3fe1ea1d9475', 3580 1: 2, 3581 2: h'62696c626f2e62616767696e7340686f626269746f6e2e6578616d70 3582 6c65' 3583 }, 3584 { 3585 -1: 1, 3586 -2: h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b 3587 4d91d6280', 3588 -3: h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e 3589 03bf822bb', 3590 1: 2, 3591 2: h'706572656772696e2e746f6f6b407475636b626f726f7567682e6578 3592 616d706c65' 3593 }, 3594 { 3595 -1: 1, 3596 -2: h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a8 3597 6d6a09eff', 3598 -3: h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed2 3599 8bbfc117e', 3600 1: 2, 3601 2: h'3131' 3602 } 3603 ] 3605 C.4.2. Private Keys 3607 This is an example of a COSE Key set. This example includes the 3608 private keys for all of the previous examples. 3610 In order the keys are: 3612 o An EC key with a kid of "meriadoc.brandybuck@buckland.example" 3614 o A shared-secret key with a kid of "our-secret" 3616 o An EC key with a kid of "peregrin.took@tuckborough.example" 3618 o A shared-secret key with a kid of "018c0ae5-4d9b-471b- 3619 bfd6-eef314bc7037" 3621 o An EC key with a kid of "bilbo.baggins@hobbiton.example" 3623 o An EC key with a kid of "11" 3625 Size of binary file is 782 bytes 3627 [ 3628 { 3629 1: 2, 3630 2: h'6d65726961646f632e6272616e64796275636b406275636b6c616e64 3631 2e6578616d706c65', 3632 -1: 1, 3633 -2: h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de4 3634 39c08551d', 3635 -3: h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eec 3636 d0084d19c', 3637 -4: h'aff907c99f9ad3aae6c4cdf21122bce2bd68b5283e6907154ad9118 3638 40fa208cf' 3639 }, 3640 { 3641 1: 4, 3642 2: h'6f75722d736563726574', 3643 -1: h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dce 3644 a6c427188' 3645 }, 3646 { 3647 1: 2, 3648 2: h'62696c626f2e62616767696e7340686f626269746f6e2e6578616d70 3649 6c65', 3650 -1: 3, 3651 -2: h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737b 3652 f5de7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620 3653 085e5c8f42ad', 3654 -3: h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e 3655 247e60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f 3656 3fe1ea1d9475', 3657 -4: h'00085138ddabf5ca975f5860f91a08e91d6d5f9a76ad4018766a476 3658 680b55cd339e8ab6c72b5facdb2a2a50ac25bd086647dd3e2e6e99e84ca2c3609 3659 fdf177feb26d' 3660 }, 3661 { 3662 1: 2, 3663 -1: 1, 3664 2: h'706572656772696e2e746f6f6b407475636b626f726f7567682e6578 3665 616d706c65', 3666 -2: h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b 3667 4d91d6280', 3668 -3: h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e 3669 03bf822bb', 3670 -4: h'02d1f7e6f26c43d4868d87ceb2353161740aacf1f7163647984b522 3671 a848df1c3' 3672 }, 3673 { 3674 1: 4, 3675 2: h'30313863306165352d346439622d343731622d626664362d65656633 3676 3134626337303337', 3677 -1: h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dce 3678 a6c427188' 3679 }, 3680 { 3681 1: 2, 3682 2: h'3131', 3683 -1: 1, 3684 -2: h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a8 3685 6d6a09eff', 3686 -3: h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed2 3687 8bbfc117e', 3688 -4: h'57c92077664146e876760c9520d054aa93c3afb04e306705db60903 3689 08507b4d3' 3690 } 3691 ] 3693 Appendix D. Document Updates 3695 D.1. Version -05 to -06 3697 o Remove new CFRG Elliptical Curve key agreement algorithms. 3699 o Remove RSA algorithms 3700 o Define a creation time and sequence number for discussions. 3702 o Remove message type field from all structures. 3704 o Define CBOR tagging for all structures with IANA registrations. 3706 D.2. Version -04 to -05 3708 o Removed the jku, x5c, x5t, x5t#S256, x5u, and jwk headers. 3710 o Add enveloped data vs encrypted data structures. 3712 o Add counter signature parameter. 3714 D.3. Version -03 to -04 3716 o Change top level from map to array. 3718 o Eliminate the term "key management" from the document. 3720 o Point to content registries for the 'content type' attribute 3722 o Push protected field into the KDF functions for recipients. 3724 o Remove password based recipient information. 3726 o Create EC Curve Registry. 3728 D.4. Version -02 to -03 3730 o Make a pass over all of the algorithm text. 3732 o Alter the CDDL so that Keys and KeySets are top level items and 3733 the key examples validate. 3735 o Add sample key structures. 3737 o Expand text on dealing with Externally Supplied Data. 3739 o Update the examples to match some of the renumbering of fields. 3741 D.5. Version -02 to -03 3743 o Add a set of straw man proposals for algorithms. It is possible/ 3744 expected that this text will be moved to a new document. 3746 o Add a set of straw man proposals for key structures. It is 3747 possible/expected that this text will be moved to a new document. 3749 o Provide guidance on use of externally supplied authenticated data. 3751 o Add external authenticated data to signing structure. 3753 D.6. Version -01 to -2 3755 o Add first pass of algorithm information 3757 o Add direct key derivation example. 3759 D.7. Version -00 to -01 3761 o Add note on where the document is being maintained and 3762 contributing notes. 3764 o Put in proposal on MTI algorithms. 3766 o Changed to use labels rather than keys when talking about what 3767 indexes a map. 3769 o Moved nonce/IV to be a common header item. 3771 o Expand section to discuss the common set of labels used in 3772 COSE_Key maps. 3774 o Start marking element 0 in registries as reserved. 3776 o Update examples. 3778 Editorial Comments 3780 [CREF1] JLS: Need to check this list for correctness before publishing. 3782 [CREF2] JLS: I have not gone through the document to determine what 3783 needs to be here yet. We mostly want to grab terms which are 3784 used in unusual ways or are not generally understood. 3786 [CREF3] JLS: It would be possible to extend this section to talk about 3787 those decisions which an application needs to think about rather 3788 than just talking about MTI algorithms. 3790 [CREF4] JLS: A completest version of this grammar would list the options 3791 available in the protected and unprotected headers. Do we want 3792 to head that direction? 3794 [CREF5] Hannes: Ensure that the list of examples only includes items 3795 which are implemented in this specification. Check the other 3796 places where such lists occur and ensure that they also follow 3797 this rule. 3799 [CREF6] JLS: We can really simplify the grammar for COSE_Key to be just 3800 the kty (the one required field) and the generic item. The 3801 reason to do this is that it makes things simpler. The reason 3802 not to do this says that we really need to add a lot more items 3803 so that a grammar check can be done that is more tightly 3804 enforced. 3806 [CREF7] Ilari: Look to see if we need to be clearer about how the fields 3807 defined in the table are transported and thus why they have 3808 labels. 3810 [CREF8] JLS: Should we register both or just the cose+cbor one? 3812 [CREF9] JLS: Should we create the equivalent of the smime-type parameter 3813 to identify the inner content type? 3815 Author's Address 3817 Jim Schaad 3818 August Cellars 3820 Email: ietf@augustcellars.com