idnits 2.17.1 draft-ietf-cose-msg-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 709 has weird spacing: '...otected is de...' == Line 711 has weird spacing: '...otected is de...' == Line 713 has weird spacing: '...payload conta...' == Line 728 has weird spacing: '...natures is an...' == Line 742 has weird spacing: '...otected is de...' == (27 more instances...) == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: o Applications MUST not generate messages with the same label used twice as a key in a single map. Applications MUST not parse and process messages with the same label used twice as a key in a single map. Applications can enforce the parse and process requirement by using parsers that will fail the parse step or by using parsers that will pass all keys to the application and the application can perform the check for duplicate keys. -- The document date (December 16, 2015) is 3047 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'CREF1' is mentioned on line 4459, but not defined == Missing Reference: 'CREF2' is mentioned on line 4461, but not defined == Missing Reference: 'CREF3' is mentioned on line 4465, but not defined == Missing Reference: 'CREF4' is mentioned on line 4470, but not defined == Missing Reference: 'CREF5' is mentioned on line 4472, but not defined ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-11) exists of draft-greevenbosch-appsawg-cbor-cddl-07 -- Obsolete informational reference (is this intentional?): RFC 2633 (Obsoleted by RFC 3851) -- Obsolete informational reference (is this intentional?): RFC 2898 (Obsoleted by RFC 8018) -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) -- Obsolete informational reference (is this intentional?): RFC 5751 (Obsoleted by RFC 8551) -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) -- Obsolete informational reference (is this intentional?): RFC 7539 (Obsoleted by RFC 8439) Summary: 1 error (**), 0 flaws (~~), 14 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 December 16, 2015 5 Expires: June 18, 2016 7 CBOR Encoded Message Syntax 8 draft-ietf-cose-msg-09 10 Abstract 12 Concise Binary Object Representation (CBOR) is data format designed 13 for small code size and small message size. There is a need for the 14 ability to have the basic security services defined for this data 15 format. This document specifies procesing for signatures, message 16 authentication codes, and encryption using CBOR. This document also 17 specifies a represention for cryptographic keys using CBOR. 19 Contributing to this document 21 The source for this draft is being maintained in GitHub. Suggested 22 changes should be submitted as pull requests at . Instructions are on that page as well. 24 Editorial changes can be managed in GitHub, but any substantial 25 issues need to be discussed on the COSE mailing list. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on June 18, 2016. 44 Copyright Notice 46 Copyright (c) 2015 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 62 1.1. Design changes from JOSE . . . . . . . . . . . . . . . . 5 63 1.2. Requirements Terminology . . . . . . . . . . . . . . . . 6 64 1.3. CBOR Grammar . . . . . . . . . . . . . . . . . . . . . . 6 65 1.4. CBOR Related Terminology . . . . . . . . . . . . . . . . 7 66 1.5. Document Terminology . . . . . . . . . . . . . . . . . . 7 67 2. Basic COSE Structure . . . . . . . . . . . . . . . . . . . . 8 68 3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 10 69 3.1. Common COSE Headers Parameters . . . . . . . . . . . . . 11 70 4. Signing Objects . . . . . . . . . . . . . . . . . . . . . . . 15 71 4.1. Signing with One or More Signers . . . . . . . . . . . . 15 72 4.2. Signing with One Signer . . . . . . . . . . . . . . . . . 17 73 4.3. Externally Supplied Data . . . . . . . . . . . . . . . . 18 74 4.4. Signing and Verification Process . . . . . . . . . . . . 18 75 4.5. Computing Counter Signatures . . . . . . . . . . . . . . 20 76 5. Encryption Objects . . . . . . . . . . . . . . . . . . . . . 21 77 5.1. Enveloped COSE Structure . . . . . . . . . . . . . . . . 21 78 5.1.1. Recipient Algorithm Classes . . . . . . . . . . . . . 23 79 5.2. Encrypted COSE structure . . . . . . . . . . . . . . . . 23 80 5.3. Encryption Algorithm for AEAD algorithms . . . . . . . . 24 81 5.4. Encryption algorithm for AE algorithms . . . . . . . . . 25 82 6. MAC Objects . . . . . . . . . . . . . . . . . . . . . . . . . 26 83 6.1. MAC Message with Recipients . . . . . . . . . . . . . . . 26 84 6.2. MAC Messages with Implicit Key . . . . . . . . . . . . . 27 85 6.3. How to compute a MAC . . . . . . . . . . . . . . . . . . 28 86 7. Key Structure . . . . . . . . . . . . . . . . . . . . . . . . 29 87 7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 30 88 8. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 32 89 8.1. ECDSA . . . . . . . . . . . . . . . . . . . . . . . . . . 33 90 8.1.1. Security Considerations . . . . . . . . . . . . . . . 35 91 9. Message Authentication (MAC) Algorithms . . . . . . . . . . . 36 92 9.1. Hash-based Message Authentication Codes (HMAC) . . . . . 36 93 9.1.1. Security Considerations . . . . . . . . . . . . . . . 37 94 9.2. AES Message Authentication Code (AES-CBC-MAC) . . . . . . 38 95 9.2.1. Security Considerations . . . . . . . . . . . . . . . 39 96 10. Content Encryption Algorithms . . . . . . . . . . . . . . . . 39 97 10.1. AES GCM . . . . . . . . . . . . . . . . . . . . . . . . 40 98 10.1.1. Security Considerations . . . . . . . . . . . . . . 41 99 10.2. AES CCM . . . . . . . . . . . . . . . . . . . . . . . . 41 100 10.2.1. Security Considerations . . . . . . . . . . . . . . 44 101 10.3. ChaCha20 and Poly1305 . . . . . . . . . . . . . . . . . 44 102 10.3.1. Security Considerations . . . . . . . . . . . . . . 45 103 11. Key Derivation Functions (KDF) . . . . . . . . . . . . . . . 45 104 11.1. HMAC-based Extract-and-Expand Key Derivation Function 105 (HKDF) . . . . . . . . . . . . . . . . . . . . . . . . . 46 106 11.2. Context Information Structure . . . . . . . . . . . . . 48 107 12. Recipient Algorithm Classes . . . . . . . . . . . . . . . . . 52 108 12.1. Direct Encryption . . . . . . . . . . . . . . . . . . . 52 109 12.1.1. Direct Key . . . . . . . . . . . . . . . . . . . . . 53 110 12.1.2. Direct Key with KDF . . . . . . . . . . . . . . . . 53 111 12.2. Key Wrapping . . . . . . . . . . . . . . . . . . . . . . 55 112 12.2.1. AES Key Wrapping . . . . . . . . . . . . . . . . . . 56 113 12.3. Key Encryption . . . . . . . . . . . . . . . . . . . . . 57 114 12.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 57 115 12.4.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 58 116 12.5. Key Agreement with KDF . . . . . . . . . . . . . . . . . 61 117 12.5.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 62 118 13. Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 119 13.1. Elliptic Curve Keys . . . . . . . . . . . . . . . . . . 63 120 13.1.1. Double Coordinate Curves . . . . . . . . . . . . . . 63 121 13.2. Symmetric Keys . . . . . . . . . . . . . . . . . . . . . 65 122 14. CBOR Encoder Restrictions . . . . . . . . . . . . . . . . . . 65 123 15. Application Profiling Considerations . . . . . . . . . . . . 66 124 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 67 125 16.1. CBOR Tag assignment . . . . . . . . . . . . . . . . . . 67 126 16.2. COSE Header Parameter Registry . . . . . . . . . . . . . 67 127 16.3. COSE Header Algorithm Label Table . . . . . . . . . . . 68 128 16.4. COSE Algorithm Registry . . . . . . . . . . . . . . . . 69 129 16.5. COSE Key Common Parameter Registry . . . . . . . . . . . 69 130 16.6. COSE Key Type Parameter Registry . . . . . . . . . . . . 70 131 16.7. COSE Elliptic Curve Registry . . . . . . . . . . . . . . 71 132 16.8. Media Type Registrations . . . . . . . . . . . . . . . . 71 133 16.8.1. COSE Security Message . . . . . . . . . . . . . . . 71 134 16.8.2. COSE Key media type . . . . . . . . . . . . . . . . 72 135 16.9. CoAP Content Format Registrations . . . . . . . . . . . 74 136 16.10. Expert Review Instructions . . . . . . . . . . . . . . . 75 137 17. Security Considerations . . . . . . . . . . . . . . . . . . . 76 138 18. References . . . . . . . . . . . . . . . . . . . . . . . . . 77 139 18.1. Normative References . . . . . . . . . . . . . . . . . . 77 140 18.2. Informative References . . . . . . . . . . . . . . . . . 77 141 Appendix A. Three Levels of Recipient Information . . . . . . . 80 142 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 81 143 B.1. Examples of MAC messages . . . . . . . . . . . . . . . . 82 144 B.1.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 82 145 B.1.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 83 146 B.1.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 84 147 B.1.4. Multi-recipient MAC message . . . . . . . . . . . . . 85 148 B.2. Examples of Encrypted Messages . . . . . . . . . . . . . 86 149 B.2.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 87 150 B.2.2. Direct plus Key Derivation . . . . . . . . . . . . . 87 151 B.2.3. Counter Signature on Encrypted Content . . . . . . . 88 152 B.2.4. Encrypted Content w/ Implicit Recipient . . . . . . . 89 153 B.2.5. Encrypted Content w/ Implicit Recipient and Partial 154 IV . . . . . . . . . . . . . . . . . . . . . . . . . 90 155 B.3. Examples of Signed Message . . . . . . . . . . . . . . . 90 156 B.3.1. Single Signature . . . . . . . . . . . . . . . . . . 90 157 B.3.2. Multiple Signers . . . . . . . . . . . . . . . . . . 91 158 B.3.3. Counter Signature . . . . . . . . . . . . . . . . . . 92 159 B.4. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 92 160 B.4.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 92 161 B.4.2. Private Keys . . . . . . . . . . . . . . . . . . . . 94 162 Appendix C. Document Updates . . . . . . . . . . . . . . . . . . 96 163 C.1. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 96 164 C.2. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 97 165 C.3. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 97 166 C.4. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 97 167 C.5. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 97 168 C.6. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 97 169 C.7. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 98 170 C.8. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 98 171 C.9. Version -01 to -2 . . . . . . . . . . . . . . . . . . . . 98 172 C.10. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 98 173 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 99 175 1. Introduction 177 There has been an increased focus on the small, constrained devices 178 that make up the Internet of Things (IOT). One of the standards that 179 has come out of this process is the Concise Binary Object 180 Representation (CBOR). CBOR extended the data model of the 181 JavaScript Object Notation (JSON) by allowing for binary data among 182 other changes. CBOR is being adopted by several of the IETF working 183 groups dealing with the IOT world as their encoding of data 184 structures. CBOR was designed specifically to be both small in terms 185 of messages transport and implementation size as well having a schema 186 free decoder. A need exists to provide basic message security 187 services for IOT and using CBOR as the message encoding format makes 188 sense. 190 The JOSE working group produced a set of documents 191 [RFC7515][RFC7516][RFC7517][RFC7518] using JSON [RFC7159] that 192 specified how to process encryption, signatures and message 193 authentication (MAC) operations, and how to encode keys using JSON. 194 This document does the same work for use with the CBOR [RFC7049] 195 document format. While there is a strong attempt to keep the flavor 196 of the original JOSE documents, two considerations are taken into 197 account: 199 o CBOR has capabilities that are not present in JSON and should be 200 used. One example of this is the fact that CBOR has a method of 201 encoding binary directly without first converting it into a base64 202 encoded string. 204 o COSE is not a direct copy of the JOSE specification. In the 205 process of creating COSE, decisions that were made for JOSE were 206 re-examined. In many cases different results were decided on as 207 the criteria were not always the same as for JOSE. 209 1.1. Design changes from JOSE 211 o Define a top level message structure so that encrypted, signed and 212 MACed messages can easily identified and still have a consistent 213 view. 215 o Signed messages separate the concept of protected and unprotected 216 parameters that are for the content and the signature. 218 o Recipient processing has been made more uniform. A recipient 219 structure is required for all recipients rather than only for 220 some. 222 o MAC messages are separated from signed messages. 224 o MAC messages have the ability to use all recipient algorithms on 225 the MAC authentication key. 227 o Use binary encodings for binary data rather than base64url 228 encodings. 230 o Combine the authentication tag for encryption algorithms with the 231 ciphertext. 233 o Remove the flattened mode of encoding. Forcing the use of an 234 array of recipients at all times forces the message size to be two 235 bytes larger, but one gets a corresponding decrease in the 236 implementation size that should compensate for this. [CREF1] 238 1.2. Requirements Terminology 240 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 241 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 242 "OPTIONAL" in this document are to be interpreted as described in 243 [RFC2119]. 245 When the words appear in lower case, their natural language meaning 246 is used. 248 1.3. CBOR Grammar 250 There currently is no standard CBOR grammar available for use by 251 specifications. We therefore describe the CBOR structures in prose. 253 The document was developed by first working on the grammar and then 254 developing the prose to go with it. An artifact of this is that the 255 prose was written using the primitive type strings defined by CDDL. 256 In this specification, the following primitive types are used: 258 any - non-specific value that permits all CBOR values to be placed 259 here. 261 bool - a boolean value (true: major type 7, value 21; false: major 262 type 7, value 20). 264 bstr - byte string (major type 2). 266 int - an unsigned integer or a negative integer. 268 nil - a null value (major type 7, value 22). 270 nint - a negative integer (major type 1). 272 tstr - a UTF-8 text string (major type 3). 274 uint - an unsigned integer (major type 0). 276 There is a version of a CBOR grammar in the CBOR Data Definition 277 Language (CDDL) [I-D.greevenbosch-appsawg-cbor-cddl]. Since CDDL has 278 not be published as an RFC, this grammar may not work with the final 279 version of CDDL when it is published. For those people who prefer 280 using a formal language to describe the syntax of the CBOR, an 281 informational version of the CBOR grammar is interweaved into the 282 text as well. The CDDL grammar is informational, the prose 283 description is normative. 285 The collected CDDL can be extracted from the XML version of this 286 document via the following XPath expression below. (Depending on the 287 XPath evaluator one is using, it may be necessary to deal with > 288 as an entity.) 290 //artwork[@type='CDDL']/text() 292 CDDL expects the initial non-terminal symbol to be the first symbol 293 in the file. For this reason the first fragment of CDDL is presented 294 here. 296 start = COSE_Messages / COSE_Key / COSE_KeySet / Internal_Types 298 ; This is define to make the tool quieter 299 Internal_Types = Sig_structure / Enc_structure / MAC_structure / 300 COSE_KDF_Context 302 The non-terminal Internal_Types is defined for dealing with the 303 automated validation tools used during the writing of this document. 304 It references those non-terminals that are used for security 305 computations. 307 1.4. CBOR Related Terminology 309 In JSON, maps are called objects and only have one kind of map key: a 310 string. In COSE, we use both strings and integers (both negative and 311 unsigned integers) as map keys. The integers are used for 312 compactness of encoding and easy comparison. (Generally, in this 313 document the value zero is going to be reserved and not used.) Since 314 the work "key" is mainly used in its other meaning, as a 315 cryptographic key, we use the term "label" for this usage as a map 316 keys. 318 A CDDL grammar fragment is defined that defines the non-terminals 319 'label' as in the previous paragraph and 'values' which permits any 320 value to be used. 322 label = int / tstr 323 values = any 325 1.5. Document Terminology 327 In this document we use the following terminology: [CREF2] 329 Byte is a synonym for octet. 331 Constrained Application Protocol (CoAP) is a specialized web transfer 332 protocol for use in constrained systems. It is defined in [RFC7252]. 334 Key management is used as a term to describe how a key at level n is 335 obtained from level n+1 in encrypted and MACed messages. The term is 336 also used to discuss key life cycle management, this document does 337 not discuss key life cycle operations. 339 2. Basic COSE Structure 341 The COSE Message structure is designed so that there can be a large 342 amount of common code when parsing and processing the different 343 security messages. All of the message structures are built on a CBOR 344 array type. The first three elements of the array contains the same 345 basic information. 347 1. The set of protected header parameters wrapped in a bstr. 349 2. The set of unprotected header parameters as a map. 351 3. The content of the message. The content is either the plain text 352 or the encrypted text as appropriate. (The content may be 353 absent, but the location is still used.) 355 Elements after this point are dependent on the specific message type. 357 Identification of which message is present is done by one of three 358 methods: 360 o The specific message type is known from the context in which it is 361 placed. This may be defined by a marker in the containing 362 structure or by restrictions specified by the application 363 protocol. 365 o The message type is identified by a CBOR tag. This document 366 defines a CBOR tag for each of the message structures. 368 o When a COSE object is carried in a media type of application/cose, 369 the optional parameter 'cose-type' can be used to identify the 370 embedded object. The parameter is OPTIONAL if the tagged version 371 of the structure is used. The parameter is REQUIRED if the 372 untagged version of the structure is used. The value to use with 373 the parameter for each of the structures can be found in Table 1. 375 +---------+----------------+-----------------+----------------------+ 376 | Tag | cose-type | Data Item | Semantics | 377 | Value | | | | 378 +---------+----------------+-----------------+----------------------+ 379 | TBD1 | cose-sign | COSE_Sign | COSE Signed Data | 380 | | | | Object | 381 | | | | | 382 | TBD7 | cose-sign1 | COSE_Sign1 | COSE Single Signer | 383 | | | | Data Object | 384 | | | | | 385 | TBD2 | cose-enveloped | COSE_Enveloped | COSE Enveloped Data | 386 | | | | Object | 387 | | | | | 388 | TBD3 | cose-encrypted | COSE_Encrypted | COSE Encrypted Data | 389 | | | | Object | 390 | | | | | 391 | TBD4 | cose-mac | COSE_Mac | COSE Mac-ed Data | 392 | | | | Object | 393 | | | | | 394 | TBD6 | cose-mac0 | COSE_Mac0 | COSE Mac w/o | 395 | | | | Recipients Object | 396 | | | | | 397 | TBD5 | N/A | COSE_Key, | COSE Key or COSE Key | 398 | | | COSE_KeySet | Set Object | 399 +---------+----------------+-----------------+----------------------+ 401 Table 1: COSE Object Identification 403 The following CDDL fragment identifies all of the top level messages 404 defined in this document. Separate non-terminals are defined for the 405 tagged and the untagged versions of the messages for the convenience 406 of applications. 408 COSE_Messages = COSE_Untagged_Message / COSE_Tagged_Message 410 COSE_Untagged_Message = COSE_Sign / COSE_Sign1 / 411 COSE_Enveloped / 412 COSE_Encrypted / 413 COSE_Mac / COSE_Mac0 415 COSE_Tagged_Message = COSE_Sign_Tagged / COSE_Sign1_Tagged / 416 COSE_Enveloped_Tagged / 417 COSE_Encrypted_Tagged / 418 COSE_Mac_Tagged / COSE_Mac0_Tagged 420 3. Header Parameters 422 The structure of COSE has been designed to have two buckets of 423 information that are not considered to be part of the payload itself, 424 but are used for holding information about content, algorithms, keys, 425 or evaluation hints for the processing of the layer. These two 426 buckets are available for use in all of the structures in this 427 document except for keys. While these buckets can be present, they 428 may not all be usable in all instances. For example, while the 429 protected bucket is defined as part of recipient structures, most of 430 the algorithms that are used for recipients do not provide the 431 necessary functionality to provide the needed protection and thus the 432 bucket should not be used. 434 Both buckets are implemented as CBOR maps. The map key is a 'label' 435 (Section 1.4). The value portion is dependent on the definition for 436 the label. Both maps use the same set of label/value pairs. The 437 integer and string values for labels has been divided into several 438 sections with a standard range, a private range, and a range that is 439 dependent on the algorithm selected. The defined labels can be found 440 in the 'COSE Header Parameters' IANA registry (Section 16.2). 442 Two buckets are provided for each layer: 444 protected: Contains parameters about the current layer that are to 445 be cryptographically protected. This bucket MUST be empty if it 446 is not going to be included in a cryptographic computation. This 447 bucket is encoded in the message as a binary object. This value 448 is obtained by CBOR encoding the protected map and wrapping it in 449 a bstr object. Senders SHOULD encode an empty protected map as a 450 zero length binary object (it is shorter). Recipients MUST accept 451 both a zero length binary value and a zero length map encoded in 452 the binary value. The wrapping allows for the encoding of the 453 protected map to be transported with a greater chance that it will 454 not be altered in transit. (Badly behaved intermediates could 455 decode and re-encode, but this will result in a failure to verify 456 unless the re-encoded byte string is identical to the decoded byte 457 string.) This finesses the problem of all parties needing to be 458 able to do a common canonical encoding. 460 unprotected: Contains parameters about the current layer that are 461 not cryptographically protected. 463 Only parameters that deal with the current layer are to be placed at 464 that layer. As an example of this, the parameter 'content type' 465 describes the content of the message being carried in the message. 466 As such, this parameter is placed only in the content layer and is 467 not placed in the recipient or signature layers. In principle, one 468 should be able to process any given layer without reference to any 469 other layer. (The only data that should need to cross layers is the 470 cryptographic key.) 472 The buckets are present in all of the security objects defined in 473 this document. The fields in order are the 'protected' bucket (as a 474 CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map' 475 type). The presence of both buckets is required. The parameters 476 that go into the buckets come from the IANA "COSE Header Parameters" 477 (Section 16.2). Some common parameters are defined in the next 478 section, but a number of parameters are defined throughout this 479 document. 481 The following CDDL fragment represents the two header buckets. A 482 group Headers is defined in CDDL which represents the two buckets in 483 which attributes are placed. This group is used to provide these two 484 fields consistently in all locations. A type is also defined which 485 represents the map of header values. It uses forward references to a 486 group definition of headers for generic and algorithms. 488 Headers = ( 489 protected : bstr, ; Contains a header_map 490 unprotected : header_map 491 ) 493 header_map = { 494 Generic_Headers, 495 ; Algorithm_Headers, 496 + label => values 497 } 499 3.1. Common COSE Headers Parameters 501 This section defines a set of common header parameters. A summary of 502 those parameters can be found in Table 2. This table should be 503 consulted to determine the value of label used as well as the type of 504 the value. 506 The set of header parameters defined in this section are: 508 alg This parameter is used to indicate the algorithm used for the 509 security processing. This parameter MUST be present at each level 510 of a signed, encrypted or authenticated message. When the 511 algorithm supports authenticating extenral data, this parameter 512 MUST be in the protected header bucket. The value is taken from 513 the 'COSE Algorithm Registry' (see Section 16.4). 515 crit This parameter is used to ensure that applications will take 516 appropriate action based on the values found. The parameter is 517 used to indicate which protected header labels an application that 518 is processing a message is required to understand. When present, 519 this parameter MUST be placed in the protected header bucket. 521 * Integer labels in the range of 0 to 10 SHOULD be omitted. 523 * Integer labels in the range -1 to -255 can be omitted as they 524 are algorithm dependent. If an application can correctly 525 process an algorithm, it can be assumed that it will correctly 526 process all of the parameters associated with that algorithm. 527 (The algorithm range is -1 to -65536, it is assumed that the 528 higher end will deal with more optional algorithm specific 529 items.) 531 The header parameter values indicated by 'crit' can be processed 532 by either the security library code or by an application using a 533 security library, the only requirement is that the parameter is 534 processed. If the 'crit' value list includes a value for which 535 the parameter is not in the protected bucket, this is a fatal 536 error in processing the message. 538 content type This parameter is used to indicate the content type of 539 the data in the payload or ciphertext fields. Integers are from 540 the 'CoAP Content-Formats' IANA registry table. Strings are from 541 the IANA 'Media Types' registry. Applications SHOULD provide this 542 parameter if the content structure is potentially ambiguous. 544 kid This parameter one of the ways that can be used to find the key 545 to be used. The value of this parameter is matched against the 546 'kid' member in a COSE_Key structure. Applications MUST NOT 547 assume that 'kid' values are unique. There may be more than one 548 key with the same 'kid' value, it may be required that all of the 549 keys need to be checked to find the correct one. The internal 550 structure of 'kid' values is not defined and generally cannot be 551 relied on by applications. Key identifier values are hints about 552 which key to use. They are not directly a security critical 553 field. For this reason, they can be placed in the unprotected 554 headers bucket. 556 Initialization Vector This parameter holds the Initialization Vector 557 (IV) value. For some symmetric encryption algorithms this may be 558 referred to as a nonce. As the IV is authenticated by encryption 559 process, it can be placed in the unprotected header bucket. 561 Partial Initialization Vector This parameter holds a part of the IV 562 value. When using the COSE_Encrypted structure, frequently a 563 portion of the IV is part of the context associated with the key 564 value. This field is used to carry the portion of the IV that 565 changes for each message. As the IV is authenticated by the 566 encryption process, this value can be placed in the unprotected 567 header bucket. 568 The final IV is generated by concatenating the fixed portion of 569 the IV, a zero string and the changing portion of the IV. The 570 length of the zero string is computed by taking the required IV 571 length and subtracting the lengths of the fixed and changing IV 572 portions. 574 counter signature This parameter holds a counter signature value. 575 Counter signatures provide a method of having a second party sign 576 some data. The counter signature can occur as an unprotected 577 attribute in any of the following structures: COSE_Sign, 578 COSE_Sign1, COSE_Signature, COSE_Enveloped, COSE_recipient, 579 COSE_Encrypted, COSE_Mac and COSE_Mac0. These structures all have 580 the same basic structure so that a consistent calculation of the 581 counter signature can be computed. Details on computing counter 582 signatures are found in Section 4.5. 584 operation time This parameter provides the time the content 585 cryptographic operation is performed. For signatures and 586 recipient structures, this would be the time that the signature or 587 recipient key object was created. For content structures, this 588 would be the time that the content structure was created. The 589 unsigned integer value is the number of seconds, excluding leap 590 seconds, after midnight UTC, January 1, 1970. The field is 591 primarily intended to be to be used for countersignatures, however 592 it can additionally be used for replay detection as well. 594 +----------+-------+---------------+----------------+---------------+ 595 | name | label | value type | value registry | description | 596 +----------+-------+---------------+----------------+---------------+ 597 | alg | 1 | int / tstr | COSE Algorithm | Integers are | 598 | | | | Registry | taken from | 599 | | | | | table --POINT | 600 | | | | | TO REGISTRY-- | 601 | | | | | | 602 | crit | 2 | [+ label] | COSE Header | integer | 603 | | | | Label Registry | values are | 604 | | | | | from -- | 605 | | | | | POINT TO | 606 | | | | | REGISTRY -- | 607 | | | | | | 608 | content | 3 | tstr / int | CoAP Content- | Value is | 609 | type | | | Formats or | either a | 610 | | | | Media Types | Media Type or | 611 | | | | registry | an integer | 612 | | | | | from the CoAP | 613 | | | | | Content | 614 | | | | | Format | 615 | | | | | registry | 616 | | | | | | 617 | kid | 4 | bstr | | key | 618 | | | | | identifier | 619 | | | | | | 620 | IV | 5 | bstr | | Full Initiali | 621 | | | | | zation Vector | 622 | | | | | | 623 | Partial | 6 | bstr | | Partial Initi | 624 | IV | | | | alization | 625 | | | | | Vector | 626 | | | | | | 627 | counter | 7 | COSE_Signatur | | CBOR encoded | 628 | signatur | | e | | signature | 629 | e | | | | structure | 630 | | | | | | 631 | operatio | 8 | uint | | Time the COSE | 632 | n time | | | | structure was | 633 | | | | | created | 634 +----------+-------+---------------+----------------+---------------+ 636 Table 2: Common Header Parameters 638 The CDDL fragment that represents the set of headers defined in this 639 section is given below. Each of the headers is tagged as optional 640 because they do not need to be in every map, headers required in 641 specific maps are discussed above. 643 Generic_Headers = ( 644 ? 1 => int / tstr, ; algorithm identifier 645 ? 2 => [+label], ; criticality 646 ? 3 => tstr / int, ; content type 647 ? 4 => bstr, ; key identifier 648 ? 5 => bstr, ; IV 649 ? 6 => bstr, ; Partial IV 650 ? 7 => COSE_Signature, ; Counter signature 651 ? 8 => uint ; Operation time 652 ) 654 4. Signing Objects 656 COSE supports two different signature structures. COSE_Sign allows 657 for one or more signers to be applied to a single content. 658 COSE_Sign1 is restricted to a single signer. 660 4.1. Signing with One or More Signers 662 The signature structure allows for one or more signatures to be 663 applied to a message payload. There are provisions for parameters 664 about the content and parameters about the signature to be carried 665 along with the signature itself. These parameters may be 666 authenticated by the signature, or just present. Examples of 667 parameters about the content would be the type of content, when the 668 content was created, and who created the content. [CREF3] Examples 669 of parameters about the signature would be the algorithm and key used 670 to create the signature, when the signature was created, and counter- 671 signatures. 673 When more than one signature is present, the successful validation of 674 one signature associated with a given signer is usually treated as a 675 successful signature by that signer. However, there are some 676 application environments where other rules are needed. An 677 application that employs a rule other than one valid signature for 678 each signer must specify those rules. Also, where simple matching of 679 the signer identifier is not sufficient to determine whether the 680 signatures were generated by the same signer, the application 681 specification must describe how to determine which signatures were 682 generated by the same signer. Support of different communities of 683 recipients is the primary reason that signers choose to include more 684 than one signature. For example, the COSE_Sign structure might 685 include signatures generated with the RSA signature algorithm and 686 with the Elliptic Curve Digital Signature Algorithm (ECDSA) signature 687 algorithm. This allows recipients to verify the signature associated 688 with one algorithm or the other. (The original source of this text 689 is [RFC5652].) More detailed information on multiple signature 690 evaluation can be found in [RFC5752]. 692 The signature structure can be encoded either with or without a tag 693 depending on the context it will be used in. The signature structure 694 is identified by the CBOR tag TBD1. The CDDL fragment that 695 represents this is. 697 COSE_Sign_Tagged = #6.991(COSE_Sign) ; Replace 991 with TBD1 699 A COSE Signing Message is divided into two parts. The CBOR object 700 that carries the body and information about the body is called the 701 COSE_Sign structure. The CBOR object that carries the signature and 702 information about the signature is called the COSE_Signature 703 structure. Examples of COSE Signing Messages can be found in 704 Appendix B.3. 706 The COSE_Sign structure is a CBOR array. The fields of the array in 707 order are: 709 protected is described in Section 3. 711 unprotected is described in Section 3. 713 payload contains the serialized content to be signed. If the 714 payload is not present in the message, the application is required 715 to supply the payload separately. The payload is wrapped in a 716 bstr to ensure that it is transported without changes. If the 717 payload is transported separately, then a nil CBOR object is 718 placed in this location and it is the responsibility of the 719 application to ensure that it will be transported without changes. 721 Note: When a signature with message recovery algorithm is used 722 (Section 8), the maximum number of bytes that can be recovered is 723 the length of the payload. The size of the payload is reduced by 724 the number of bytes that will be recovered. If all of the bytes 725 of the payload are consumed, then the payload is encoded as a zero 726 length binary string rather than as being absent. 728 signatures is an array of signatures. Each signature is represented 729 as a COSE_Signature structure. 731 The CDDL fragment which represents the above text for COSE_Sign 732 follows. 734 COSE_Sign = [ 735 Headers, 736 payload : bstr / nil, 737 signatures : [+ COSE_Signature] 738 ] 739 The COSE_Signature structure is a CBOR array. The fields of the 740 array in order are: 742 protected is described in Section 3. 744 unprotected is described in Section 3. 746 signature contains the computed signature value. The type of the 747 field is a bstr. 749 The CDDL fragment which represents the above text for COSE_Signature 750 follows. 752 COSE_Signature = [ 753 Headers, 754 signature : bstr 755 ] 757 4.2. Signing with One Signer 759 The signature structure can be encoded either with or without a tag 760 depending on the context it will be used in. The signature structure 761 is identified by the CBOR tag TBD7. The CDDL fragment that 762 represents this is: 764 COSE_Sign1_Tagged = #6.997(COSE_Sign1) ; Replace 997 with TBD7 766 The COSE_Sign1 structure is a CBOR array. The fields of the array in 767 order are: 769 protected is described in Section 3. 771 unprotected is described in Section 3. 773 payload is described in Section 4.1. 775 signature contains the computed signature value. The type of the 776 field is a bstr. 778 The CDDL fragment which represents the above text for COSE_Sign1 779 follows. 781 COSE_Sign1 = [ 782 Headers, 783 payload : bstr / nil, 784 signature : bstr 785 ] 787 4.3. Externally Supplied Data 789 One of the features that we supply in the COSE document is the 790 ability for applications to provide additional data to be 791 authenticated as part of the security, but that is not carried as 792 part of the COSE object. The primary reason for supporting this can 793 be seen by looking at the CoAP message structure [RFC7252] where the 794 facility exists for options to be carried before the payload. An 795 example of data that can be placed in this location would be CoAP 796 options for transaction ids and nonces to check for replay 797 protection. If the data is in the options section, then it is 798 available for routers to help in performing the replay detection and 799 prevention. However, it may also be desired to protect these values 800 so that they cannot be modified in transit. This is the purpose of 801 the externally supplied data field. 803 This document describes the process for using a byte array of 804 externally supplied authenticated data, however the method of 805 constructing the byte array is a function of the application. 806 Applications that use this feature need to define how the externally 807 supplied authenticated data is to be constructed. Such a 808 construction needs to take into account the following issues: 810 o If multiple items are included, care needs to be taken that data 811 cannot bleed between the items. This is usually addressed by 812 making fields fixed width and/or encoding the length of the field. 813 Using options from CoAP [RFC7252] as an example, these fields use 814 a TLV structure so they can be concatenated without any problems. 816 o If multiple items are included, a defined order for the items 817 needs to be defined. Using options from CoAP as an example, an 818 application could state that the fields are to be ordered by the 819 option number. 821 4.4. Signing and Verification Process 823 In order to create a signature, a consistent byte stream is needed in 824 order to process. This algorithm takes in the body information 825 (COSE_Sign), the signer information (COSE_Signer), and the 826 application data (External). A CBOR array is used to construct the 827 byte stream to be processed. The fields of the array in order are: 829 1. A text string identifying the context that this signature is 830 being used in. The context string is: 832 "Signature" for signatures using the COSE_Signature structure. 834 "Signature1" for signatures using the COSE_Sign1 structure. 836 "CounterSignature" for signatures used as counter signature 837 attributes. 839 2. The protected attributes from the body structure encoded in a 840 bstr type. 842 3. The protected attributes from the signer structure encoded in a 843 bstr type. This field is omitted for the COSE_Sign1 signature 844 structure. 846 4. The protected attributes from the application encoded in a bstr 847 type. If this field is not supplied, it defaults to a zero 848 length binary string. 850 5. The payload to be signed encoded in a bstr type. The payload is 851 placed here independent of how it is transported. 853 The CDDL fragment which describes the above text is. 855 Sig_structure = [ 856 context: "Signature" / "Signature1" / "CounterSignature", 857 body_protected: bstr, 858 ? sign_protected: bstr, 859 external_aad: bstr, 860 payload: bstr 861 ] 863 How to compute a signature: 865 1. Create a Sig_structure and populate it with the appropriate 866 fields. For body_protected and sign_protected, if the map is 867 empty, a bstr of length zero is used. 869 2. If the application has supplied external additional authenticated 870 data to be included in the computation, then it is placed in the 871 third field. If no data was supplied, then a zero length binary 872 string is used. 874 3. Create the value ToBeSigned by encoding the Sig_structure to a 875 byte string. 877 4. Call the signature creation algorithm passing in K (the key to 878 sign with), alg (the algorithm to sign with) and ToBeSigned (the 879 value to sign). 881 5. Place the resulting signature value in the 'signature' field of 882 the map. 884 How to verify a signature: 886 1. Create a Sig_structure object and populate it with the 887 appropriate fields. For body_protected and sign_protected, if 888 the map is empty, a bstr of length zero is used. 890 2. If the application has supplied external additional authenticated 891 data to be included in the computation, then it is placed in the 892 third field. If no data was supplied, then a zero length binary 893 string is used. 895 3. Create the value ToBeSigned by encoding the Sig_structure to a 896 byte string. 898 4. Call the signature verification algorithm passing in K (the key 899 to verify with), alg (the algorithm used sign with), ToBeSigned 900 (the value to sign), and sig (the signature to be verified). 902 In addition to performing the signature verification, one must also 903 perform the appropriate checks to ensure that the key is correctly 904 paired with the signing identity and that the appropriate 905 authorization is done. 907 4.5. Computing Counter Signatures 909 Counter signatures provide a method of having a different signature 910 occur on some piece of content. This is normally used to provide a 911 signature on a signature allowing for a proof that a signature 912 existed at a given time (i.e. a Timestamp). In this document we 913 allow for counter signatures to exist in a greater number of 914 environments. As an example, it is possible to place a counter 915 signature in the unprotected attributes of a COSE_Enveloped object. 916 This would allow for an intermediary to either verify that the 917 encrypted byte stream has not been modified, without being able to 918 decrypt it. Or for the intermediary to assert that an encrypted byte 919 stream either existed at a given time or passed through it in terms 920 of routing (i.e. a proxy signature). 922 An example of a proxy signature on a signature can be found in 923 Appendix B.3.3. An example of a proxy signature on an encryption 924 object can be found in Appendix B.2.3. 926 The creation and validation of counter signatures over the different 927 items relies on the fact that the structure all of our objects have 928 the same structure. The elements are a set of protected attributes, 929 a set of unprotected attributes and a body in that order. This means 930 that the Sig_structure can be used for in a uniform manner to get the 931 byte stream for processing a signature. If the counter signature is 932 going to be computed over a COSE_Enveloped structure, the 933 body_protected and payload items can be mapped into the Sig_structure 934 in the same manner as from the COSE_Sign structure. 936 It should be noted that only signature algorithm with appendix (see 937 Section 8) should be used for counter signatures. This is because 938 the body should be able to be processed without having to evaluate 939 the countersignature, and this is not possible for signature schemes 940 with message recovery. 942 5. Encryption Objects 944 COSE supports two different encryption structures. COSE_Enveloped is 945 used when the key needs to be explicitly identified. This structure 946 supports the use of recipient structures to allow for random content 947 encryption keys to be used. COSE_Encrypted is used when a recipient 948 structure is not needed because the key to be used is known 949 implicitly. 951 5.1. Enveloped COSE Structure 953 The enveloped structure allows for one or more recipients of a 954 message. There are provisions for parameters about the content and 955 parameters about the recipient information to be carried in the 956 message. The parameters associated with the content can be 957 authenticated by the content encryption algorithm. The parameters 958 associated with the recipient can be authenticated by the recipient 959 algorithm (when the algorithm supports it). Examples of parameters 960 about the content are the type of the content, when the content was 961 created, and the content encryption algorithm. Examples of 962 parameters about the recipient are the recipient's key identifier, 963 the recipient encryption algorithm. [CREF4] 965 In COSE, the same techniques and structures are used for encrypting 966 both the plain text and the keys used to protect the text. This is 967 different from the approach used by both [RFC5652] and [RFC7516] 968 where different structures are used for the content layer and for the 969 recipient layer. Two structures are defined COSE_Enveloped to hold 970 the encrypted content and COSE_recipient to hold the encrypted keys 971 for recipients. Examples of encrypted messages can be found in 972 Appendix B.2. 974 The COSE Enveloped structure can be encoded either with or without a 975 tag depending on the context it will be used in. The COSE Enveloped 976 structure is identified by the CBOR tag TBD2. The CDDL fragment that 977 represents this is. 979 COSE_Enveloped_Tagged = #6.992(COSE_Enveloped) ; Replace 992 with TBD2 980 The COSE_Enveloped structure is a CBOR array. The fields of the 981 array in order are: 983 protected is described in Section 3. 985 unprotected is described in Section 3. 987 ciphertext contains the encrypted plain text encoded as a bstr. If 988 the ciphertext is to be transported independently of the control 989 information about the encryption process (i.e. detached content) 990 then the field is encoded as a null object. 992 recipients contains an array of recipient information structures. 993 The type for the recipient information structure is a 994 COSE_recipient. 996 The CDDL fragment that corresponds to the above text is: 998 COSE_Enveloped = [ 999 Headers, 1000 ciphertext: bstr / nil, 1001 recipients: [+COSE_recipient] 1002 ] 1004 The COSE_recipient structure is a CBOR array. The fields of the 1005 array in order are: 1007 protected is described in Section 3. 1009 unprotected is described in Section 3. 1011 ciphertext contains the encrypted key encoded as a bstr. If there 1012 is not an encrypted key, then this field is encoded as a nil 1013 value. 1015 recipients contains an array of recipient information structures. 1016 The type for the recipient information structure is a 1017 COSE_recipient. If there are no recipient information structures, 1018 this element is absent. 1020 The CDDL fragment that corresponds to the above text for 1021 COSE_recipient is: 1023 COSE_recipient = [ 1024 Headers, 1025 ciphertext: bstr / nil, 1026 ? recipients: [+COSE_recipient] 1027 ] 1029 5.1.1. Recipient Algorithm Classes 1031 A typical encrypted message consists of an encrypted content and an 1032 encrypted CEK for one or more recipients. The CEK is encrypted for 1033 each recipient, using a key specific to that recipient. The details 1034 of this encryption depends on which class the recipient algorithm 1035 falls into. Specific details on each of the classes can be found in 1036 Section 12. A short summary of the five recipient algorithm classes 1037 is: 1039 direct: The CEK is the same as the identified previously distributed 1040 symmetric key or derived from a previously distributed secret. No 1041 CEK is transported in the message. 1043 symmetric key-encryption keys: The CEK is encrypted using a 1044 previously distributed symmetric KEK. 1046 key agreement: The recipient's public key and a sender's private key 1047 are used to generate a pairwise secret, a KDF is applied to derive 1048 a key, and then the CEK is either the derived key or encrypted by 1049 the derived key. 1051 key transport: The CEK is encrypted with the recipient's public key. 1053 passwords: The CEK is encrypted in a KEK that is derived from a 1054 password. 1056 5.2. Encrypted COSE structure 1058 The encrypted structure does not have the ability to specify 1059 recipients of the message. The structure assumes that the recipient 1060 of the object will already know the identity of the key to be used in 1061 order to decrypt the message. If a key needs to be identified to the 1062 recipient, the enveloped structure ought to be used. 1064 The structure defined to hold an encrypted message is COSE_Encrypted. 1065 Examples of encrypted messages can be found in Appendix B.2. 1067 The COSE_Encrypted structure can be encoded either with or without a 1068 tag depending on the context it will be used in. The COSE_Encrypted 1069 structure is identified by the CBOR tag TBD3. The CDDL fragment that 1070 represents this is. 1072 COSE_Encrypted_Tagged = #6.993(COSE_Encrypted) ; Replace 993 with TBD3 1074 The COSE_Enveloped structure is a CBOR array. The fields of the 1075 array in order are: 1077 protected is described in Section 3. 1079 unprotected is described in Section 3. 1081 ciphertext contains the encrypted plain text. If the ciphertext is 1082 to be transported independently of the control information about 1083 the encryption process (i.e. detached content) then the field is 1084 encoded as a null value. 1086 The CDDL fragment for COSE_Encrypted that corresponds to the above 1087 text is: 1089 COSE_Encrypted = [ 1090 Headers, 1091 ciphertext: bstr / nil, 1092 ] 1094 5.3. Encryption Algorithm for AEAD algorithms 1096 The encryption algorithm for AEAD algorithms is fairly simple. 1098 1. Create a CBOR array (Enc_structure) to encode the authenticated 1099 data. 1101 2. Place a context string in the form of a tstr in the first 1102 location to identify the data and location being encoded. The 1103 strings defined are: 1105 "Encrypted" for the the content encryption of an encrypted data 1106 structure. 1108 "Enveloped" for the first level of an enveloped data structure 1109 (i.e. for content encryption). 1111 "Env_Recipient" for a recipient encoding to be placed in an 1112 enveloped data structure. 1114 "Mac_Recipient" for a recipient encoding to be placed in a MAC 1115 message structure. 1117 3. Copy the protected header field from the message to be sent to 1118 the second location in the Enc_structure. 1120 4. If the application has supplied external additional authenticated 1121 data to be included in the computation, then it is placed in the 1122 third location ('external_aad' field) of the Enc_structure. If 1123 no data was supplied, then a zero length binary value is used. 1125 (See Section 4.3 for application guidance on constructing this 1126 field.) 1128 5. Encode the Enc_structure using a CBOR Canonical encoding 1129 Section 14 to get the AAD value. 1131 6. Determine the encryption key. This step is dependent on the 1132 class of recipient algorithm being used. For: 1134 No Recipients: The key to be used is determined by the algorithm 1135 and key at the current level. 1137 Direct and Direct Key Agreement: The key is determined by the 1138 key and algorithm in the recipient structure. The encryption 1139 algorithm and size of the key to be used are inputs into the 1140 KDF used for the recipient. (For direct, the KDF can be 1141 thought of as the identity operation.) 1143 Other: The key is randomly generated. 1145 7. Call the encryption algorithm with K (the encryption key to use), 1146 P (the plain text) and AAD (the additional authenticated data). 1147 Place the returned cipher text into the 'ciphertext' field of the 1148 structure. 1150 8. For recipients of the message, recursively perform the encryption 1151 algorithm for that recipient using the encryption key as the 1152 plain text. 1154 The CDDL fragment which defines the Enc_structure used for the 1155 authenticated data structure is: 1157 Enc_structure = [ 1158 context : "Enveloped" / "Encrypted" / "Env_Recipient" / 1159 "Mac_Recipient", 1160 protected: bstr, 1161 external_aad: bstr 1162 ] 1164 5.4. Encryption algorithm for AE algorithms 1166 1. Verify that the 'protected' field is absent. 1168 2. Verify that there was no external additional authenticated data 1169 supplied for this operation. 1171 3. Determine the encryption key. This step is dependent on the 1172 class of recipient algorithm being used. For: 1174 No Recipients: The key to be used is determined by the algorithm 1175 and key at the current level. 1177 Direct and Direct Key Agreement: The key is determined by the 1178 key and algorithm in the recipient structure. The encryption 1179 algorithm and size of the key to be used are inputs into the 1180 KDF used for the recipient. (For direct, the KDF can be 1181 thought of as the identity operation.) 1183 Other: The key is randomly generated. 1185 4. Call the encryption algorithm with K (the encryption key to use) 1186 and the P (the plain text). Place the returned cipher text into 1187 the 'ciphertext' field of the structure. 1189 5. For recipients of the message, recursively perform the encryption 1190 algorithm for that recipient using the encryption key as the 1191 plain text. 1193 6. MAC Objects 1195 COSE supports two different MAC structures. COSE_MAC is used when 1196 the key needs to be explicitly identified. The structure supports 1197 the use of recipient structures to allow for random content 1198 encryption keys to be used. COSE_MAC0 is used when the a recipient 1199 structure is not needed because the key to be used is implicitly 1200 known. 1202 6.1. MAC Message with Recipients 1204 In this section we describe the structure and methods to be used when 1205 doing MAC authentication in COSE. This document allows for the use 1206 of all of the same classes of recipient algorithms as are allowed for 1207 encryption. 1209 When using MAC operations, there are two modes in which it can be 1210 used. The first is just a check that the content has not been 1211 changed since the MAC was computed. Any class of recipient algorithm 1212 can be used for this purpose. The second mode is to both check that 1213 the content has not been changed since the MAC was computed, and to 1214 use the recipient algorithm to verify who sent it. The classes of 1215 recipient algorithms that support this are those that use a pre- 1216 shared secret or do static-static key agreement (without the key wrap 1217 step). In both of these cases, the entity hat created and sent the 1218 message MAC can be validated. (The knowledge of sender assumes that 1219 there are only two parties involved and you did not send the message 1220 yourself.) 1221 The MAC message uses two structures, the COSE_Mac structure defined 1222 in this section for carrying the body and the COSE_recipient 1223 structure (Section 5.1) to hold the key used for the MAC computation. 1224 Examples of MAC messages can be found in Appendix B.1. 1226 The MAC structure can be encoded either withor without a tag 1227 depending on the context it will be used in. The MAC truture is 1228 identified by the CBOR tag TBD4. The CDDL fragment that represents 1229 this is: 1231 COSE_Mac_Tagged = #6.994(COSE_Mac) ; Replace 994 with TBD4 1233 The COSE_Mac structure is a CBOR array. The fields of the array in 1234 order are: 1236 protected is described in Section 3. 1238 unprotected is described in Section 3. 1240 payload contains the serialized content to be MACed. If the payload 1241 is not present in the message, the application is required to 1242 supply the payload separately. The payload is wrapped in a bstr 1243 to ensure that it is transported without changes. If the payload 1244 is transported separately, then a null CBOR object is placed in 1245 this location and it is the responsibility of the application to 1246 ensure that it will be transported without changes. 1248 tag contains the MAC value. 1250 recipients contains the recipient information. See the description 1251 under COSE_Encryption for more info. 1253 The CDDL fragment which represents the above text for COSE_Mac 1254 follows. 1256 COSE_Mac = [ 1257 Headers, 1258 payload: bstr / nil, 1259 tag: bstr, 1260 recipients: [+COSE_recipient] 1261 ] 1263 6.2. MAC Messages with Implicit Key 1265 In this section we describe the structure and methods to be used when 1266 doing MAC authentication for those cases where the recipient is 1267 implicitly known. 1269 The MAC message uses the COSE_Mac0 structure defined in this section 1270 for carrying the body. 1272 The MAC structure can be encoded either withor without a tag 1273 depending on the context it will be used in. The MAC structure is 1274 identified by the CBOR tag TBD6. The CDDL fragment that represents 1275 this is: 1277 COSE_Mac0_Tagged = #6.996(COSE_Mac0) ; Replace 996 with TBD6 1279 The COSE_Mac0 structure is a CBOR array. The fields of the array in 1280 order are: 1282 protected is described in Section 3. 1284 unprotected is described in Section 3. 1286 payload contains the serialized content to be MACed. If the payload 1287 is not present in the message, the application is required to 1288 supply the payload separately. The payload is wrapped in a bstr 1289 to ensure that it is transported without changes. If the payload 1290 is transported separately, then a null CBOR object is placed in 1291 this location and it is the responsibility of the application to 1292 ensure that it will be transported without changes. 1294 tag contains the MAC value. 1296 The CDDL fragment which corresponds to the above text is: 1298 COSE_Mac0 = [ 1299 Headers, 1300 payload: bstr / nil, 1301 tag: bstr, 1302 ] 1304 6.3. How to compute a MAC 1306 In order to get a consistent encoding of the data to be 1307 authenticated, the MAC_structure is used to have a canonical form. 1308 The MAC_structure is a CBOR array. The fields of the MAC_structure 1309 in order are: 1311 1. A text string that identifies the structure that is being 1312 encoded. This string is "MAC" for the COSE_Mac structure. This 1313 string is "MAC0" for the COSE_Mac0 structure. 1315 2. The protected attributes from the COSE_MAC structure. If there 1316 are no protected attributes, a zero length binary string is to be 1317 encoded. 1319 3. If the application has supplied external authenticated data, 1320 encode it as a binary value and place in the MAC_structure. If 1321 there is no external authenticated data, then use a zero length 1322 'bstr'. (See Section 4.3 for application guidance on 1323 constructing this field.) 1325 4. The payload to be MAC-ed encoded in a bstr type. The payload is 1326 placed here independent of how it is transported. 1328 The CDDL fragment that corresponds to the above text is: 1330 MAC_structure = [ 1331 context: "MAC" / "MAC0", 1332 protected: bstr, 1333 external_aad: bstr, 1334 payload: bstr 1335 ] 1337 The steps to compute a MAC are: 1339 1. Create a MAC_structure and fill in the fields. 1341 2. Encode the MAC_structure using a canonical CBOR encoder. The 1342 resulting bytes is the value to compute the MAC on. 1344 3. Compute the MAC and place the result in the 'tag' field of the 1345 COSE_Mac structure. 1347 4. Encrypt and encode the MAC key for each recipient of the message. 1349 7. Key Structure 1351 A COSE Key structure is built on a CBOR map object. The set of 1352 common parameters that can appear in a COSE Key can be found in the 1353 IANA registry 'COSE Key Common Parameter Registry' (Section 16.5). 1354 Additional parameters defined for specific key types can be found in 1355 the IANA registry 'COSE Key Type Parameters' (Section 16.6). 1357 A COSE Key Set uses a CBOR array object as its underlying type. The 1358 values of the array elements are COSE Keys. A Key Set MUST have at 1359 least one element in the array. 1361 The element "kty" is a required element in a COSE_Key map. 1363 The CDDL grammar describing a COSE_Key and COSE_KeySet is: 1365 COSE_Key = { 1366 key_kty => tstr / int, 1367 ? key_ops => [+ (tstr / int) ], 1368 ? key_alg => tstr / int, 1369 ? key_kid => bstr, 1370 * label => values 1371 } 1373 COSE_KeySet = [+COSE_Key] 1375 7.1. COSE Key Common Parameters 1377 This document defines a set of common parameters for a COSE Key 1378 object. Table 3 provides a summary of the parameters defined in this 1379 section. There are also a set of parameters that are defined for a 1380 specific key type. Key type specific parameters can be found in 1381 Section 13. 1383 +---------+-------+-------------+-------------+---------------------+ 1384 | name | label | CBOR type | registry | description | 1385 +---------+-------+-------------+-------------+---------------------+ 1386 | kty | 1 | tstr / int | COSE | Identification of | 1387 | | | | General | the key type | 1388 | | | | Values | | 1389 | | | | | | 1390 | key_ops | 4 | [* | | Restrict set of | 1391 | | | (tstr/int)] | | permissible | 1392 | | | | | operations | 1393 | | | | | | 1394 | alg | 3 | tstr / int | COSE | Key usage | 1395 | | | | Algorithm | restriction to this | 1396 | | | | Values | algorithm | 1397 | | | | | | 1398 | kid | 2 | bstr | | Key Identification | 1399 | | | | | value - match to | 1400 | | | | | kid in message | 1401 | | | | | | 1402 | use | * | tstr | | deprecated - don't | 1403 | | | | | use | 1404 +---------+-------+-------------+-------------+---------------------+ 1406 Table 3: Key Map Labels 1408 kty: This parameter is used to identify the family of keys for this 1409 structure, and thus the set of key type specific parameters to be 1410 found. The set of values defined in this document can be found in 1411 Table 19. This parameter MUST be present in a key object. 1412 Implementations MUST verify that the key type is appropriate for 1413 the algorithm being processed. The key type MUST be included as 1414 part of a trust decision process. 1416 alg: This parameter is used to restrict the algorithms that are to 1417 be used with this key. If this parameter is present in the key 1418 structure, the application MUST verify that this algorithm matches 1419 the algorithm for which the key is being used. If the algorithms 1420 do not match, then this key object MUST NOT be used to perform the 1421 cryptographic operation. Note that the same key can be in a 1422 different key structure with a different or no algorithm 1423 specified, however this is considered to be a poor security 1424 practice. 1426 kid: This parameter is used to give an identifier for a key. The 1427 identifier is not structured and can be anything from a user 1428 provided string to a value computed on the public portion of the 1429 key. This field is intended for matching against a 'kid' 1430 parameter in a message in order to filter down the set of keys 1431 that need to be checked. 1433 key_ops: This parameter is defined to restrict the set of operations 1434 that a key is to be used for. The value of the field is an array 1435 of values from Table 4. 1437 +---------+-------+-------------------------------------------------+ 1438 | name | value | description | 1439 +---------+-------+-------------------------------------------------+ 1440 | sign | 1 | The key is used to create signatures. Requires | 1441 | | | private key fields. | 1442 | | | | 1443 | verify | 2 | The key is used for verification of signatures. | 1444 | | | | 1445 | encrypt | 3 | The key is used for key transport encryption. | 1446 | | | | 1447 | decrypt | 4 | The key is used for key transport decryption. | 1448 | | | Requires private key fields. | 1449 | | | | 1450 | wrap | 5 | The key is used for key wrapping. | 1451 | key | | | 1452 | | | | 1453 | unwrap | 6 | The key is used for key unwrapping. Requires | 1454 | key | | private key fields. | 1455 | | | | 1456 | derive | 7 | The key is used for deriving keys. | 1457 | key | | | 1458 | | | | 1459 | derive | 8 | The key is used for deriving bits. | 1460 | bits | | | 1461 +---------+-------+-------------------------------------------------+ 1463 Table 4: Key Operation Values 1465 The following provides a CDDL fragment which duplicates the 1466 assignment labels from Table 3. 1468 ;key_labels 1469 key_kty=1 1470 key_kid=2 1471 key_alg=3 1472 key_ops=4 1474 8. Signature Algorithms 1476 There are two basic signature algorithm structures that can be used. 1477 The first is the common signature with appendix. In this structure, 1478 the message content is processed and a signature is produced, the 1479 signature is called the appendix. This is the message structure used 1480 by our common algorithms such as ECDSA and RSASSA-PSS. (In fact the 1481 SSA in RSASSA-PSS stands for Signature Scheme with Appendix.) The 1482 basic structure becomes: 1484 signature = Sign(message content, key) 1486 valid = Verification(message content, key, signature) 1488 The second is a signature with message recovery. (An example of such 1489 an algorithm is [PVSig].) In this structure, the message content is 1490 processed, but part of it is included in the signature. Moving bytes 1491 of the message content into the signature allows for an effectively 1492 smaller signature, the signature size is still potentially large, but 1493 the message content is shrunk. This has implications for systems 1494 implementing these algorithms and for applications that use them. 1495 The first is that the message content is not fully available until 1496 after a signature has been validated. Until that point the part of 1497 the message contained inside of the signature is unrecoverable. The 1498 second is that the security analysis of the strength of the signature 1499 is very much based on the structure of the message content. Messages 1500 which are highly predictable require additional randomness to be 1501 supplied as part of the signature process. In the worst case, it 1502 becomes the same as doing a signature with appendix. Thirdly, in the 1503 event that multiple signatures are applied to a message, all of the 1504 signature algorithms are going to be required to consume the same 1505 number of bytes of message content. 1507 signature, message sent = Sign(message content, key) 1509 valid, message content = Verification(message sent, key, signature) 1511 At this time, only signatures with appendixes are defined for use 1512 with COSE, however considerable interest has been expressed in using 1513 a signature with message recovery algorithm due to the effective size 1514 reduction that is possible. Implementations will need to keep this 1515 in mind for later possible integration. 1517 8.1. ECDSA 1519 ECDSA [DSS] defines a signature algorithm using ECC. 1521 The ECDSA signature algorithm is parameterized with a hash function 1522 (h). In the event that the length of the hash function output is 1523 greater than the group of the key, the left-most bytes of the hash 1524 output are used. 1526 The algorithms defined in this document can be found in Table 5. 1528 +-------+-------+---------+------------------+ 1529 | name | value | hash | description | 1530 +-------+-------+---------+------------------+ 1531 | ES256 | -7 | SHA-256 | ECDSA w/ SHA-256 | 1532 | | | | | 1533 | ES384 | -8 | SHA-384 | ECDSA w/ SHA-384 | 1534 | | | | | 1535 | ES512 | -9 | SHA-512 | ECDSA w/ SHA-512 | 1536 +-------+-------+---------+------------------+ 1538 Table 5: ECDSA Algorithm Values 1540 This document defines ECDSA to work only with the curves P-256, P-384 1541 and P-521. This document requires that the curves be encoded using 1542 the 'EC2' key type. Implementations need to check that the key type 1543 and curve are correct when creating and verifying a signature. Other 1544 documents can defined it to work with other curves and points in the 1545 future. 1547 In order to promote interoperability, it is suggested that SHA-256 be 1548 used only with curve P-256, SHA-384 be used only with curve P-384 and 1549 SHA-512 be used with curve P-521. This is aligned with the 1550 recommendation in Section 4 of [RFC5480]. 1552 The signature algorithm results in a pair of integers (R, S). These 1553 integers will be of the same order as length of the key used for the 1554 signature process. The signature is encoded by converting the 1555 integers into byte strings of the same length as the key size. The 1556 length is rounded up to the nearest byte and is left padded with zero 1557 bits to get to the correct length. The two integers are then 1558 concatenated together to form a byte string that is the resulting 1559 signature. 1561 Using the function defined in [RFC3447] the signature is: 1562 Signature = I2OSP(R, n) | I2OSP(S, n) 1563 where n = ceiling(key_length / 8) 1565 When using a COSE key for this algorithm, the following checks are 1566 made: 1568 o The 'kty' field MUST be present and it MUST be 'EC2'. 1570 o If the 'alg' field present, it MUST match the ECDSA signature 1571 algorithm being used. 1573 o If the 'key_ops' field is present, it MUST include 'sign' when 1574 creating an ECDSA signature. 1576 o If the 'key_ops' field is present, it MUST include 'verify' when 1577 verifying an ECDSA signature. 1579 8.1.1. Security Considerations 1581 The security strength of the signature is no greater than the minimum 1582 of the security strength associated with the bit length of the key 1583 and the security strength of the hash function. 1585 System which have poor random number generation can leak their keys 1586 by signing two different messages with the same value 'k' (the per- 1587 message random value). [RFC6979] provides a method to deal with this 1588 problem by making 'k' be deterministic based on the message content 1589 rather than randomly generated. Applications that specify ECDSA 1590 should evaluate the ability to get good random number generation and 1591 require this when it is not possible. 1593 Note: Use of this technique a good idea even when good random number 1594 generation exists. Doing so both reduces the possibility of having 1595 the same value of 'k' in two signature operations, but allows for 1596 reproducible signature values which helps testing. 1598 There are two substitution attacks that can theoretically be mounted 1599 against the ECDSA signature algorithm. 1601 o Changing the curve used to validate the signature: If one changes 1602 the curve used to validate the signature, then potentially one 1603 could have a two messages with the same signature each computed 1604 under a different curve. The only requirement on the new curve is 1605 that its order be the same as the old one and it be acceptable to 1606 the client. An example would be to change from using the curve 1607 secp256r1 (aka P-256) to using secp256k1. (Both are 256 bit 1608 curves.) We current do not have any way to deal with this version 1609 of the attack except to restrict the overall set of curves that 1610 can be used. 1612 o Change the hash function used to validate the signature: If one 1613 has either two different hash functions of the same length, or one 1614 can truncate a hash function down, then one could potentially find 1615 collisions between the hash functions rather than within a single 1616 hash function. (For example, truncating SHA-512 to 256 bits might 1617 collide with a SHA-256 bit hash value.) This attack can be 1618 mitigated by including the signature algorithm identifier in the 1619 data to be signed. 1621 9. Message Authentication (MAC) Algorithms 1623 Message Authentication Codes (MACs) provide data authentication and 1624 integrity protection. They provide either no or very limited data 1625 origination. (One cannot, for example, be used to prove the identity 1626 of the sender to a third party.) 1628 MACs use the same basic structure as signature with appendix 1629 algorithms. The message content is processed and an authentication 1630 code is produced. The authentication code is frequently called a 1631 tag. The basic structure becomes: 1633 tag = MAC_Create(message content, key) 1635 valid = MAC_Verify(message content, key, tag) 1637 MAC algorithms can be based on either a block cipher algorithm (i.e. 1638 AES-MAC) or a hash algorithm (i.e. HMAC). This document defines a 1639 MAC algorithm for each of these two constructions. 1641 9.1. Hash-based Message Authentication Codes (HMAC) 1643 The Hash-base Message Authentication Code algorithm (HMAC) 1644 [RFC2104][RFC4231] was designed to deal with length extension 1645 attacks. The algorithm was also designed to allow for new hash 1646 algorithms to be directly plugged in without changes to the hash 1647 function. The HMAC design process has been vindicated as, while the 1648 security of hash algorithms such as MD5 has decreased over time, the 1649 security of HMAC combined with MD5 has not yet been shown to be 1650 compromised [RFC6151]. 1652 The HMAC algorithm is parameterized by an inner and outer padding, a 1653 hash function (h) and an authentication tag value length. For this 1654 specification, the inner and outer padding are fixed to the values 1655 set in [RFC2104]. The length of the authentication tag corresponds 1656 to the difficulty of producing a forgery. For use in constrained 1657 environments, we define a set of HMAC algorithms that are truncated. 1658 There are currently no known issues when truncating, however the 1659 security strength of the message tag is correspondingly reduced in 1660 strength. When truncating, the left-most tag length bits are kept 1661 and transmitted. 1663 The algorithm defined in this document can be found in Table 6. 1665 +-----------+-------+---------+--------+----------------------------+ 1666 | name | value | Hash | Length | description | 1667 +-----------+-------+---------+--------+----------------------------+ 1668 | HMAC | * | SHA-256 | 64 | HMAC w/ SHA-256 truncated | 1669 | 256/64 | | | | to 64 bits | 1670 | | | | | | 1671 | HMAC | 4 | SHA-256 | 256 | HMAC w/ SHA-256 | 1672 | 256/256 | | | | | 1673 | | | | | | 1674 | HMAC | 5 | SHA-384 | 384 | HMAC w/ SHA-384 | 1675 | 384/384 | | | | | 1676 | | | | | | 1677 | HMAC | 6 | SHA-512 | 512 | HMAC w/ SHA-512 | 1678 | 512/512 | | | | | 1679 +-----------+-------+---------+--------+----------------------------+ 1681 Table 6: HMAC Algorithm Values 1683 Some recipient algorithms carry the key while others derive a key 1684 from secret data. For those algorithms that carry the key (i.e. 1685 RSA-OAEP and AES-KeyWrap), the size of the HMAC key SHOULD be the 1686 same size as the underlying hash function. For those algorithms that 1687 derive the key, the derived key MUST be the same size as the 1688 underlying hash function. 1690 When using a COSE key for this algorithm, the following checks are 1691 made: 1693 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 1695 o If the 'alg' field present, it MUST match the HMAC algorithm being 1696 used. 1698 o If the 'key_ops' field is present, it MUST include 'sign' when 1699 creating an HMAC authentication tag. 1701 o If the 'key_ops' field is present, it MUST include 'verify' when 1702 verifying an HMAC authentication tag. 1704 Implementations creating and validating MAC values MUST validate that 1705 the key type, key length, and algorithm are correct and appropriate 1706 for the entities involved. 1708 9.1.1. Security Considerations 1710 HMAC has proved to be resistant to attack even when used with 1711 weakening hash algorithms. The current best method appears to be a 1712 brute force attack on the key. This means that key size is going to 1713 be directly related to the security of an HMAC operation. 1715 9.2. AES Message Authentication Code (AES-CBC-MAC) 1717 AES-CBC-MAC is defined in [MAC]. 1719 AES-CBC-MAC is parameterized by the key length, the authentication 1720 tag length and the IV used. For all of these algorithms, the IV is 1721 fixed to all zeros. We provide an array of algorithms for various 1722 key lengths and tag lengths. The algorithms defined in this document 1723 are found in Table 7. 1725 +-------------+-------+----------+----------+-----------------------+ 1726 | name | value | key | tag | description | 1727 | | | length | length | | 1728 +-------------+-------+----------+----------+-----------------------+ 1729 | AES-MAC | * | 128 | 64 | AES-MAC 128 bit key, | 1730 | 128/64 | | | | 64-bit tag | 1731 | | | | | | 1732 | AES-MAC | * | 256 | 64 | AES-MAC 256 bit key, | 1733 | 256/64 | | | | 64-bit tag | 1734 | | | | | | 1735 | AES-MAC | * | 128 | 128 | AES-MAC 128 bit key, | 1736 | 128/128 | | | | 128-bit tag | 1737 | | | | | | 1738 | AES-MAC | * | 256 | 128 | AES-MAC 256 bit key, | 1739 | 256/128 | | | | 128-bit tag | 1740 +-------------+-------+----------+----------+-----------------------+ 1742 Table 7: AES-MAC Algorithm Values 1744 Keys may be obtained either from a key structure or from a recipient 1745 structure. Implementations creating and validating MAC values MUST 1746 validate that the key type, key length and algorithm are correct and 1747 appropriate for the entities involved. 1749 When using a COSE key for this algorithm, the following checks are 1750 made: 1752 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 1754 o If the 'alg' field present, it MUST match the AES-MAC algorithm 1755 being used. 1757 o If the 'key_ops' field is present, it MUST include 'sign' when 1758 creating an AES-MAC authentication tag. 1760 o If the 'key_ops' field is present, it MUST include 'verify' when 1761 verifying an AES-MAC authentication tag. 1763 9.2.1. Security Considerations 1765 A number of attacks exist against CBC-MAC that need to be considered. 1767 o A single key must only be used for messages of a fixed and known 1768 length. If this is not the case, an attacker will be able to 1769 generate a message with a valid tag given two message, tag pairs. 1770 This can be addressed by using different keys for different length 1771 messages. (CMAC mode also addresses this issue.) 1773 o If the same key is used for both encryption and authentication 1774 operations, using CBC modes an attacker can produce messages with 1775 a valid authentication code. 1777 o If the IV can be modified, then messages can be forged. This is 1778 addressed by fixing the IV to all zeros. 1780 10. Content Encryption Algorithms 1782 Content Encryption Algorithms provide data confidentiality for 1783 potentially large blocks of data using a symmetric key. They provide 1784 integrity on the data that was encrypted, however they provide either 1785 no or very limited data origination. (One cannot, for example, be 1786 used to prove the identity of the sender to a third party.) The 1787 ability to provide data origination is linked to how the symmetric 1788 key is obtained. 1790 We restrict the set of legal content encryption algorithms to those 1791 that support authentication both of the content and additional data. 1792 The encryption process will generate some type of authentication 1793 value, but that value may be either explicit or implicit in terms of 1794 the algorithm definition. For simplicity sake, the authentication 1795 code will normally be defined as being appended to the cipher text 1796 stream. The basic structure becomes: 1798 ciphertext = Encrypt(message content, key, additional data) 1800 valid, message content = Decrypt(cipher text, key, additional data) 1802 Most AEAD algorithms are logically defined as returning the message 1803 content only if the decryption is valid. Many but not all 1804 implementations will follow this convention. The message content 1805 MUST NOT be used if the decryption does not validate. 1807 10.1. AES GCM 1809 The GCM mode is a generic authenticated encryption block cipher mode 1810 defined in [AES-GCM]. The GCM mode is combined with the AES block 1811 encryption algorithm to define an AEAD cipher. 1813 The GCM mode is parameterized with by the size of the authentication 1814 tag and the size of the nonce. This document fixes the size of the 1815 nonce at 96-bits. The size of the authentication tag is limited to a 1816 small set of values. For this document however, the size of the 1817 authentication tag is fixed at 128 bits. 1819 The set of algorithms defined in this document are in Table 8. 1821 +---------+-------+------------------------------------------+ 1822 | name | value | description | 1823 +---------+-------+------------------------------------------+ 1824 | A128GCM | 1 | AES-GCM mode w/ 128-bit key, 128-bit tag | 1825 | | | | 1826 | A192GCM | 2 | AES-GCM mode w/ 192-bit key, 128-bit tag | 1827 | | | | 1828 | A256GCM | 3 | AES-GCM mode w/ 256-bit key, 128-bit tag | 1829 +---------+-------+------------------------------------------+ 1831 Table 8: Algorithm Value for AES-GCM 1833 Keys may be obtained either from a key structure or from a recipient 1834 structure. Implementations encrypting and decrypting MUST validate 1835 that the key type, key length and algorithm are correct and 1836 appropriate for the entities involved. 1838 When using a COSE key for this algorithm, the following checks are 1839 made: 1841 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 1843 o If the 'alg' field present, it MUST match the AES-GCM algorithm 1844 being used. 1846 o If the 'key_ops' field is present, it MUST include 'encrypt' or 1847 'key wrap' when encrypting. 1849 o If the 'key_ops' field is present, it MUST include 'decrypt' or 1850 'key unwrap' when decrypting. 1852 10.1.1. Security Considerations 1854 When using AES-CCM, the following restrictions MUST be enforced: 1856 o The key and nonce pair MUST be unique for every message encrypted. 1858 o The total amount of data encrypted MUST NOT exceed 2^39 - 256 1859 bits. An explicit check is required only in environments where it 1860 is expected that it might be exceeded. 1862 Consideration was given to supporting smaller tag values, the 1863 constrained community would desire tag sizes in the 64-bit range. 1864 Doing show drastically changes both the maximum messages size 1865 (generally not an issue) and the number of times that a key can be 1866 used. Given that CCM is the usual mode for constrained environments 1867 restricted modes are not supported. 1869 10.2. AES CCM 1871 Counter with CBC-MAC (CCM) is a generic authentication encryption 1872 block cipher mode defined in [RFC3610]. The CCM mode is combined 1873 with the AES block encryption algorithm to define a commonly used 1874 content encryption algorithm used in constrained devices. 1876 The CCM mode has two parameter choices. The first choice is M, the 1877 size of the authentication field. The choice of the value for M 1878 involves a trade-off between message expansion and the probably that 1879 an attacker can undetectably modify a message. The second choice is 1880 L, the size of the length field. This value requires a trade-off 1881 between the maximum message size and the size of the Nonce. 1883 It is unfortunate that the specification for CCM specified L and M as 1884 a count of bytes rather than a count of bits. This leads to possible 1885 misunderstandings where AES-CCM-8 is frequently used to refer to a 1886 version of CCM mode where the size of the authentication is 64 bits 1887 and not 8 bits. These values have traditionally been specified as 1888 bit counts rather than byte counts. This document will follow the 1889 tradition of using bit counts so that it is easier to compare the 1890 different algorithms presented in this document. 1892 We define a matrix of algorithms in this document over the values of 1893 L and M. Constrained devices are usually operating in situations 1894 where they use short messages and want to avoid doing recipient 1895 specific cryptographic operations. This favors smaller values of M 1896 and larger values of L. Less constrained devices do will want to be 1897 able to user larger messages and are more willing to generate new 1898 keys for every operation. This favors larger values of M and smaller 1899 values of L. (The use of a large nonce means that random generation 1900 of both the key and the nonce will decrease the chances of repeating 1901 the pair on two different messages.) 1903 The following values are used for L: 1905 16 bits (2) limits messages to 2^16 bytes (64 KiB) in length. This 1906 sufficiently long for messages in the constrained world. The 1907 nonce length is 13 bytes allowing for 2^(13*8) possible values of 1908 the nonce without repeating. 1910 64 bits (8) limits messages to 2^64 bytes in length. The nonce 1911 length is 7 bytes allowing for 2^56 possible values of the nonce 1912 without repeating. 1914 The following values are used for M: 1916 64 bits (8) produces a 64-bit authentication tag. This implies that 1917 there is a 1 in 2^64 chance that a modified message will 1918 authenticate. 1920 128 bits (16) produces a 128-bit authentication tag. This implies 1921 that there is a 1 in 2^128 chance that a modified message will 1922 authenticate. 1924 +--------------------+-------+----+-----+-----+---------------------+ 1925 | name | value | L | M | k | description | 1926 +--------------------+-------+----+-----+-----+---------------------+ 1927 | AES-CCM-16-64-128 | 10 | 16 | 64 | 128 | AES-CCM mode | 1928 | | | | | | 128-bit key, 64-bit | 1929 | | | | | | tag, 13-byte nonce | 1930 | | | | | | | 1931 | AES-CCM-16-64-256 | 11 | 16 | 64 | 256 | AES-CCM mode | 1932 | | | | | | 256-bit key, 64-bit | 1933 | | | | | | tag, 13-byte nonce | 1934 | | | | | | | 1935 | AES-CCM-64-64-128 | 30 | 64 | 64 | 128 | AES-CCM mode | 1936 | | | | | | 128-bit key, 64-bit | 1937 | | | | | | tag, 7-byte nonce | 1938 | | | | | | | 1939 | AES-CCM-64-64-256 | 31 | 64 | 64 | 256 | AES-CCM mode | 1940 | | | | | | 256-bit key, 64-bit | 1941 | | | | | | tag, 7-byte nonce | 1942 | | | | | | | 1943 | AES-CCM-16-128-128 | 12 | 16 | 128 | 128 | AES-CCM mode | 1944 | | | | | | 128-bit key, | 1945 | | | | | | 128-bit tag, | 1946 | | | | | | 13-byte nonce | 1947 | | | | | | | 1948 | AES-CCM-16-128-256 | 13 | 16 | 128 | 256 | AES-CCM mode | 1949 | | | | | | 256-bit key, | 1950 | | | | | | 128-bit tag, | 1951 | | | | | | 13-byte nonce | 1952 | | | | | | | 1953 | AES-CCM-64-128-128 | 32 | 64 | 128 | 128 | AES-CCM mode | 1954 | | | | | | 128-bit key, | 1955 | | | | | | 128-bit tag, 7-byte | 1956 | | | | | | nonce | 1957 | | | | | | | 1958 | AES-CCM-64-128-256 | 33 | 64 | 128 | 256 | AES-CCM mode | 1959 | | | | | | 256-bit key, | 1960 | | | | | | 128-bit tag, 7-byte | 1961 | | | | | | nonce | 1962 +--------------------+-------+----+-----+-----+---------------------+ 1964 Table 9: Algorithm Values for AES-CCM 1966 Keys may be obtained either from a key structure or from a recipient 1967 structure. Implementations encrypting and decrypting MUST validate 1968 that the key type, key length and algorithm are correct and 1969 appropriate for the entities involved. 1971 When using a COSE key for this algorithm, the following checks are 1972 made: 1974 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 1976 o If the 'alg' field present, it MUST match the AES-CCM algorithm 1977 being used. 1979 o If the 'key_ops' field is present, it MUST include 'encrypt' or 1980 'key wrap' when encrypting. 1982 o If the 'key_ops' field is present, it MUST include 'decrypt' or 1983 'key unwrap' when decrypting. 1985 10.2.1. Security Considerations 1987 When using AES-CCM, the following restrictions MUST be enforced: 1989 o The key and nonce pair MUST be unique for every message encrypted. 1991 o The total number of times the AES block cipher is used MUST NOT 1992 exceed 2^61 operations. This limitation is the sum of times the 1993 block cipher is used in computing the MAC value and in performing 1994 stream encryption operations. An explicit check is required only 1995 in environments where it is expected that it might be exceeded. 1997 [RFC3610] additionally calls out one other consideration of note. It 1998 is possible to do a pre-computation attack against the algorithm in 1999 cases where the portions encryption content is highly predictable. 2000 This reduces the security of the key size by half. Ways to deal with 2001 this attack include adding a random portion to the nonce value and/or 2002 increasing the key size used. Using a portion of the nonce for a 2003 random value will decrease the number of messages that a single key 2004 can be used for. Increasing the key size may require more resources 2005 in the constrained device. See sections 5 and 10 of [RFC3610] for 2006 more information. 2008 10.3. ChaCha20 and Poly1305 2010 ChaCha20 and Poly1305 combined together is a new AEAD mode that is 2011 defined in [RFC7539]. This is a new algorithm defined to be a cipher 2012 that is not AES and thus would not suffer from any future weaknesses 2013 found in AES. These cryptographic functions are designed to be fast 2014 in software-only implementations. 2016 The ChaCha20/Poly1305 AEAD construction defined in [RFC7539] has no 2017 parameterization. It takes a 256-bit key and a 96-bit nonce as well 2018 as the plain text and additional data as inputs and produces the 2019 cipher text as an option. We define one algorithm identifier for 2020 this algorithm in Table 10. 2022 +-------------------+-------+---------------------------------------+ 2023 | name | value | description | 2024 +-------------------+-------+---------------------------------------+ 2025 | ChaCha20/Poly1305 | 24 | ChaCha20/Poly1305 w/ 256-bit key, | 2026 | | | 128-bit tag | 2027 +-------------------+-------+---------------------------------------+ 2029 Table 10: Algorithm Value for AES-GCM 2031 Keys may be obtained either from a key structure or from a recipient 2032 structure. Implementations encrypting and decrypting MUST validate 2033 that the key type, key length and algorithm are correct and 2034 appropriate for the entities involved. 2036 When using a COSE key for this algorithm, the following checks are 2037 made: 2039 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2041 o If the 'alg' field present, it MUST match the ChaCha algorithm 2042 being used. 2044 o If the 'key_ops' field is present, it MUST include 'encrypt' or 2045 'key wrap' when encrypting. 2047 o If the 'key_ops' field is present, it MUST include 'decrypt' or 2048 'key unwrap' when decrypting. 2050 10.3.1. Security Considerations 2052 The pair of key, nonce MUST be unique for every invocation of the 2053 algorithm. Nonce counters are considered to be an acceptable way of 2054 ensuring that they are unique. 2056 11. Key Derivation Functions (KDF) 2058 Key Derivation Functions (KDFs) are used to take some secret value 2059 and generate a different one. The original secret values come in 2060 three basic flavors: 2062 o Secrets that are uniformly random: This is the type of secret 2063 which is created by a good random number generator. 2065 o Secrets that are not uniformly random: This is type of secret 2066 which is created by operations like key agreement. 2068 o Secrets that are not random: This is the type of secret that 2069 people generate for things like passwords. 2071 General KDF functions work well with the first type of secret, can do 2072 reasonable well with the second type of secret and generally do 2073 poorly with the last type of secret. None of the KDF functions in 2074 this section are designed to deal with the type of secrets that are 2075 used for passwords. Functions like PBSE2 [RFC2898] need to be used 2076 for that type of secret. 2078 Many functions are going to handle the first two type of secrets 2079 differently. The KDF function defined in Section 11.1 can use 2080 different underlying constructions if the secret is uniformly random 2081 than if the secret is not uniformly random. This is reflected in the 2082 set of algorithms defined for HKDF. 2084 When using KDF functions, one component that is generally included is 2085 context information. Context information is used to allow for 2086 different keying information to be derived from the same secret. The 2087 use of context based keying material is considered to be a good 2088 security practice. This document defines a single context structure 2089 and a single KDF function. 2091 11.1. HMAC-based Extract-and-Expand Key Derivation Function (HKDF) 2093 The HKDF key derivation algorithm is defined in [RFC5869]. 2095 The HKDF algorithm takes these inputs: 2097 secret - a shared value that is secret. Secrets may be either 2098 previously shared or derived from operations like a DH key 2099 agreement. 2101 salt - an optional public value that is used to change the 2102 generation process. If specified, the salt is carried using the 2103 'salt' algorithm parameter. While [RFC5869] suggests that the 2104 length of the salt be the same as the length of the underlying 2105 hash value, any amount of salt will improve the security as 2106 different key values will be generated. A parameter to carry the 2107 salt is defined in Table 12. This parameter is protected by being 2108 included in the key computation and does not need to be separately 2109 authenticated. 2111 length - the number of bytes of output that need to be generated. 2113 context information - Information that describes the context in 2114 which the resulting value will be used. Making this information 2115 specific to the context that the material is going to be used 2116 ensures that the resulting material will always be unique. The 2117 context structure used is encoded into the algorithm identifier. 2119 PRF - The underlying pseudo-random function to be used in the HKDF 2120 algorithm. The PRF is encoded into the HKDF algorithm selection. 2122 HKDF is defined to use HMAC as the underlying PRF. However, it is 2123 possible to use other functions in the same construct to provide a 2124 different KDF function that may be more appropriate in the 2125 constrained world. Specifically, one can use AES-CBC-MAC as the PRF 2126 for the expand step, but not for the extract step. When using a good 2127 random shared secret of the correct length, the extract step can be 2128 skipped. The extract cannot be skipped if the secret is not 2129 uniformly random, for example if it is the result of an ECDH key 2130 agreement step. 2132 The algorithms defined in this document are found in Table 11. 2134 +-------------+-------------+----------+----------------------------+ 2135 | name | PRF | Skip | context | 2136 | | | extract | | 2137 +-------------+-------------+----------+----------------------------+ 2138 | HKDF | HMAC with | no | HKDF using HMAC SHA-256 as | 2139 | SHA-256 | SHA-256 | | the PRF | 2140 | | | | | 2141 | HKDF | HMAC with | no | HKDF using HMAC SHA-512 as | 2142 | SHA-512 | SHA-512 | | the PRF | 2143 | | | | | 2144 | HKDF AES- | AES-CBC-128 | yes | HKDF using AES-MAC as the | 2145 | MAC-128 | | | PRF w/ 128-bit key | 2146 | | | | | 2147 | HKDF AES- | AES-CBC-256 | yes | HKDF using AES-MAC as the | 2148 | MAC-256 | | | PRF w/ 256-bit key | 2149 +-------------+-------------+----------+----------------------------+ 2151 Table 11: HKDF algorithms 2153 +------+-------+------+-------------+ 2154 | name | label | type | description | 2155 +------+-------+------+-------------+ 2156 | salt | -20 | bstr | Random salt | 2157 +------+-------+------+-------------+ 2159 Table 12: HKDF Algorithm Parameters 2161 11.2. Context Information Structure 2163 The context information structure is used to ensure that the derived 2164 keying material is "bound" to the context of the transaction. The 2165 context information structure used here is based on that defined in 2166 [SP800-56A]. By using CBOR for the encoding of the context 2167 information structure, we automatically get the same type and length 2168 separation of fields that is obtained by the use of ASN.1. This 2169 means that there is no need to encode the lengths for the base 2170 elements as it is done by the encoding used in JOSE (Section 4.6.2 of 2171 [RFC7518]). [CREF5] 2173 The context information structure refers to PartyU and PartyV as the 2174 two parties which are doing the key derivation. Unless the 2175 application protocol defines differently, we assign PartyU to the 2176 entity that is creating the message and PartyV to the entity that is 2177 receiving the message. By doing this association, different keys 2178 will be derived for each direction as the context information is 2179 different in each direction. 2181 Application protocols are free to define the roles differently. For 2182 example, they could assign the PartyU role to the entity that 2183 initiates the connection and allow directly sending multiple messages 2184 over the connection in both directions without changing the role 2185 information. It is still reommended that different keys be derived 2186 in each direction to avoid reflection problems. 2188 The context structure is built from information that is known to both 2189 entities. This information can be obtained from a variety of 2190 sources: 2192 o Fields can be define by the application. This is commonly used to 2193 assign names to parties. 2195 o Fields can be defined by usage of the output. Examples of this 2196 are the algorithm and key size that are being generated. 2198 o Fields can be defined by parameters from the message. We define a 2199 set of parameters in Table 13 which can be used to carry the 2200 values associated with the context structure. Examples of this 2201 are identities and nonce values. These parameters are designed to 2202 be placed in the unprotected bucket of the recipient structure. 2203 (They do not need to be in the protected bucket since they already 2204 are included in the cryptographic computation by virtue of being 2205 included in the context structure.) 2207 We define a CBOR object to hold the context information. This object 2208 is referred to as CBOR_KDF_Context. The object is based on a CBOR 2209 array type. The fields in the array are: 2211 AlgorithmID This field indicates the algorithm for which the key 2212 material will be used. This field is required to be present and 2213 is a copy of the algorithm identifier in the message. The field 2214 exists in the context information so that if the same environment 2215 is used for different algorithms, then completely different keys 2216 will be generated each of those algorithms. (This practice means 2217 if algorithm A is broken and thus can is easier to find, the key 2218 derived for algorithm B will not be the same as the key for 2219 algorithm B.) 2221 PartyUInfo This field holds information about party U. The 2222 PartyUInfo is encoded as a CBOR structure. The elements of 2223 PartyUInfo are encoded in the order presented, however if the 2224 element does not exist no element is placed in the array. The 2225 elements of the PartyUInfo array are: 2227 identity This contains the identity information for party U. The 2228 identities can be assigned in one of two manners. Firstly, a 2229 protocol can assign identities based on roles. For example, 2230 the roles of "client" and "server" may be assigned to different 2231 entities in the protocol. Each entity would then use the 2232 correct label for the data they send or receive. The second 2233 way is for a protocol to assign identities is to use a name 2234 based on a naming system (i.e. DNS, X.509 names). 2235 We define an algorithm parameter 'PartyU identity' that can be 2236 used to carry identity information in the message. However, 2237 identity information is often known as part of the protocol and 2238 can thus be inferred rather than made explicit. If identity 2239 information is carried in the message, applications SHOULD have 2240 a way of validating the supplied identity information. The 2241 identity information does not need to be specified and can be 2242 left as absent. 2244 nonce This contains a one time nonce value. The nonce can either 2245 be implicit from the protocol or carried as a value in the 2246 unprotected headers. 2247 We define an algorithm parameter 'PartyU nonce' that can be 2248 used to carry this value in the message However, the nonce 2249 value could be determined by the application and the value 2250 determined from elsewhere. 2251 This item is optional and can be absent. 2253 other This contains other information that is defined by the 2254 protocol. 2256 This item is optional and can be absent. 2258 PartyVInfo This field holds information about party V. The 2259 PartyVInfo is encoded as a CBOR structure. For store and forward 2260 environments, the party V information may be minimal or even 2261 absent. The elements of PartyVInfo are encoded in the order 2262 presented, however if the element does not exist no element is 2263 placed in the array. The elements of the PartyVInfo array are: 2265 identity This contains the identity information for party V. The 2266 identities can be assigned in one of two manners. Firstly, a 2267 protocol can assign identities based on roles. For example, 2268 the roles of "client" and "server" may be assigned to different 2269 entities in the protocol. Each entity would then use the 2270 correct label for the data they send or receive. The second 2271 way is for a protocol to assign identities is to use a name 2272 based on a naming system (i.e. DNS, X.509 names). 2273 We define an algorithm parameter 'PartyU identity' that can be 2274 used to carry identity information in the message. However, 2275 identity information is often known as part of the protocol and 2276 can thus be inferred rather than made explicit. If identity 2277 information is carried in the message, applications SHOULD have 2278 a way of validating the supplied identity information. The 2279 identity information does not need to be specified and can be 2280 left as absent. 2282 nonce This contains a one time nonce value. The nonce can either 2283 be implicit from the protocol or carried as a value in the 2284 unprotected headers. 2285 We define an algorithm parameter 'PartyU nonce' that can be 2286 used to carry this value in the message However, the nonce 2287 value could be determined by the application and the value 2288 determined from elsewhere. 2289 This item is optional and can be absent. 2291 other This contains other information that is defined by the 2292 protocol. 2293 This item is optional and can be absent. 2295 SuppPubInfo This field contains public information that is mutually 2296 known to both parties. 2298 keyDataLength This is set to the number of bits of the desired 2299 output value. (This practice means if algorithm A can use two 2300 different key lengths, the key derived for longer key size will 2301 not contain the key for shorter key size as a prefix.) 2303 protected This field contains the protected parameter field. 2305 other The field other is for free form data defined by the 2306 application. An example is that an application could defined 2307 two different strings to be placed here to generate different 2308 keys for a data stream vs a control stream. This field is 2309 optional and will only be present if the application defines a 2310 structure for this information. Applications that define this 2311 SHOULD use CBOR to encode the data so that types and lengths 2312 are correctly include. 2314 SuppPrivInfo This field contains private information that is 2315 mutually known information. An example of this information would 2316 be a pre-existing shared secret. The field is optional and will 2317 only be present if the application defines a structure for this 2318 information. Applications that define this SHOULD use CBOR to 2319 encode the data so that types and lengths are correctly included. 2321 +---------------+-------+-----------+-------------------------------+ 2322 | name | label | type | description | 2323 +---------------+-------+-----------+-------------------------------+ 2324 | PartyU | -21 | bstr | Party U identity Information | 2325 | identity | | | | 2326 | | | | | 2327 | PartyU nonce | -22 | bstr / | Party U provided nonce | 2328 | | | int | | 2329 | | | | | 2330 | PartyU other | -23 | bstr | Party U other provided | 2331 | | | | information | 2332 | | | | | 2333 | PartyV | -24 | bstr | Party V identity Information | 2334 | identity | | | | 2335 | | | | | 2336 | PartyV nonce | -25 | bstr / | Party V provided nonce | 2337 | | | int | | 2338 | | | | | 2339 | PartyV other | -26 | bstr | Party V other provided | 2340 | | | | information | 2341 +---------------+-------+-----------+-------------------------------+ 2343 Table 13: Context Algorithm Parameters 2345 The following CDDL fragment corresponds to the text above. 2347 COSE_KDF_Context = [ 2348 AlgorithmID : int / tstr, 2349 PartyUInfo : [ 2350 ? nonce : bstr / int, 2351 ? identity : bstr, 2352 ? other : bstr, 2353 ], 2354 PartyVInfo : [ 2355 ? nonce : bstr, 2356 ? identity : bstr / tstr, 2357 ? other : bstr 2358 ], 2359 SuppPubInfo : [ 2360 keyDataLength : uint, 2361 protected : bstr, 2362 ? other : bstr 2363 ], 2364 ? SuppPrivInfo : bstr 2365 ] 2367 12. Recipient Algorithm Classes 2369 Recipient algorithms can be defined into a number of different 2370 classes. COSE has the ability to support many classes of recipient 2371 algorithms. In this section, a number of classes are listed and then 2372 a set of algorithms are specified for each of the classes. The names 2373 of the recipient algorithm classes used here are the same as are 2374 defined in [RFC7516]. Other specifications use different terms for 2375 the recipient algorithm classes or do not support some of our 2376 recipient algorithm classes. 2378 12.1. Direct Encryption 2380 The direct encryption class algorithms share a secret between the 2381 sender and the recipient that is used either directly or after 2382 manipulation as the content key. When direct encryption mode is 2383 used, it MUST be the only mode used on the message. 2385 The COSE_Enveloped structure for the recipient is organized as 2386 follows: 2388 o The 'protected' field MUST be a zero length item unless it is used 2389 in the computation of the content key. 2391 o The 'alg' parameter MUST be present. 2393 o A parameter identifying the shared secret SHOULD be present. 2395 o The 'ciphertext' field MUST be a zero length item. 2397 o The 'recipients' field MUST be absent. 2399 12.1.1. Direct Key 2401 This recipient algorithm is the simplest, the identified key is 2402 directly used as the key for the next layer down in the message. 2403 There are no algorithm parameters defined for this algorithm. The 2404 algorithm identifier value is assigned in Table 14. 2406 When this algorithm is used, the protected field MUST be zero length. 2407 The key type MUST be 'Symmetric'. 2409 +--------+-------+-------------------+ 2410 | name | value | description | 2411 +--------+-------+-------------------+ 2412 | direct | -6 | Direct use of CEK | 2413 +--------+-------+-------------------+ 2415 Table 14: Direct Key 2417 12.1.1.1. Security Considerations 2419 This recipient algorithm has several potential problems that need to 2420 be considered: 2422 o These keys need to have some method to be regularly updated over 2423 time. All of the content encryption algorithms specified in this 2424 document have limits on how many times a key can be used without 2425 significant loss of security. 2427 o These keys need to be dedicated to a single algorithm. There have 2428 been a number of attacks developed over time when a single key is 2429 used for multiple different algorithms. One example of this is 2430 the use of a single key both for CBC encryption mode and CBC-MAC 2431 authentication mode. 2433 o Breaking one message means all messages are broken. If an 2434 adversary succeeds in determining the key for a single message, 2435 then the key for all messages is also determined. 2437 12.1.2. Direct Key with KDF 2439 These recipient algorithms take a common shared secret between the 2440 two parties and applies the HKDF function (Section 11.1) using the 2441 context structure defined in Section 11.2 to transform the shared 2442 secret into the necessary key. The 'protected' field can be of non- 2443 zero length. The 'protected' field is copied into the 2444 SuppPubInfo.protected field of the context structure. Either the 2445 'salt' parameter of HKDF or the partyU 'nonce' parameter of the 2446 context structure MUST be present. The salt/nonce parameter can be 2447 generated either randomly or deterministically. The requirement is 2448 that it be a unique value for the key pair in question. 2450 If the salt/nonce value is generated randomly, then it is suggested 2451 that the length of the random value be the same length as the hash 2452 function underlying HKDF. While there is no way to guarantee that it 2453 will be unique, there is a high probability that it will be unique. 2454 If the salt/nonce value is generated deterministically, it can be 2455 guaranteed to be unique and thus there is no length requirement. 2457 A new IV must be used if the same key is used in more than one 2458 message. The IV can be modified in a predictable manner, a random 2459 manner or an unpredictable manner. One unpredictable manner that can 2460 be used is to use the HKDF function to generate the IV. If HKDF is 2461 used for generating the IV, the algorithm identifier is set to "IV- 2462 GENERATION". 2464 When these algorithms are used, the key type MUST be 'symmetric'. 2466 The set of algorithms defined in this document can be found in 2467 Table 15. 2469 +---------------------+-------+-------------+-----------------------+ 2470 | name | value | KDF | description | 2471 +---------------------+-------+-------------+-----------------------+ 2472 | direct+HKDF-SHA-256 | * | HKDF | Shared secret w/ HKDF | 2473 | | | SHA-256 | and SHA-256 | 2474 | | | | | 2475 | direct+HKDF-SHA-512 | * | HKDF | Shared secret w/ HKDF | 2476 | | | SHA-512 | and SHA-512 | 2477 | | | | | 2478 | direct+HKDF-AES-128 | * | HKDF AES- | Shared secret w/ AES- | 2479 | | | MAC-128 | MAC 128-bit key | 2480 | | | | | 2481 | direct+HKDF-AES-256 | * | HKDF AES- | Shared secret w/ AES- | 2482 | | | MAC-256 | MAC 256-bit key | 2483 +---------------------+-------+-------------+-----------------------+ 2485 Table 15: Direct Key 2487 When using a COSE key for this algorithm, the following checks are 2488 made: 2490 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2492 o If the 'alg' field present, it MUST match the KDF algorithm being 2493 used. 2495 o If the 'key_ops' field is present, it MUST include 'deriveKey or 2496 'deriveBits'. 2498 12.1.2.1. Security Considerations 2500 The shared secret needs to have some method to be regularly updated 2501 over time. The shared secret forms the basis of trust. Although not 2502 used directly, it should still be subject to scheduled rotation. 2504 12.2. Key Wrapping 2506 In key wrapping mode, the CEK is randomly generated and that key is 2507 then encrypted by a shared secret between the sender and the 2508 recipient. All of the currently defined key wrapping algorithms for 2509 COSE are AE algorithms. Key wrapping mode is considered to be 2510 superior to direct encryption if the system has any capability for 2511 doing random key generation. This is because the shared key is used 2512 to wrap random data rather than data has some degree of organization 2513 and may in fact be repeating the same content. The use of Key 2514 Wrapping loses the weak data origination that is provided by the 2515 direct encryption algorithms. 2517 The COSE_Enveloped structure for the recipient is organized as 2518 follows: 2520 o The 'protected' field MUST be absent if the key wrap algorithm is 2521 an AE algorithm. 2523 o The 'recipients' field is normally absent, but can be used. 2524 Applications MUST deal with a recipients field present, not being 2525 able to decrypt that recipient is an acceptable way of dealing 2526 with it. Failing to process the message is not an acceptable way 2527 of dealing with it. 2529 o The plain text to be encrypted is the key from next layer down 2530 (usually the content layer). 2532 o At a minimum, the 'unprotected' field MUST contain the 'alg' 2533 parameter and SHOULD contain a parameter identifying the shared 2534 secret. 2536 12.2.1. AES Key Wrapping 2538 The AES Key Wrapping algorithm is defined in [RFC3394]. This 2539 algorithm uses an AES key to wrap a value that is a multiple of 64 2540 bits. As such, it can be used to wrap a key for any of the content 2541 encryption algorithms defined in this document. The algorithm 2542 requires a single fixed parameter, the initial value. This is fixed 2543 to the value specified in Section 2.2.3.1 of [RFC3394]. There are no 2544 public parameters that vary on a per invocation basis. 2546 Keys may be obtained either from a key structure or from a recipient 2547 structure. If the key obtained from a key structure, the key type 2548 MUST be 'Symmetric'. Implementations encrypting and decrypting MUST 2549 validate that the key type, key length and algorithm are correct and 2550 appropriate for the entities involved. 2552 When using a COSE key for this algorithm, the following checks are 2553 made: 2555 o The 'kty' field MUST be present and it MUST be 'Symmetric'. 2557 o If the 'alg' field present, it MUST match the AES Key Wrap 2558 algorithm being used. 2560 o If the 'key_ops' field is present, it MUST include 'encrypt' or 2561 'key wrap' when encrypting. 2563 o If the 'key_ops' field is present, it MUST include 'decrypt' or 2564 'key unwrap' when decrypting. 2566 +--------+-------+----------+-----------------------------+ 2567 | name | value | key size | description | 2568 +--------+-------+----------+-----------------------------+ 2569 | A128KW | -3 | 128 | AES Key Wrap w/ 128-bit key | 2570 | | | | | 2571 | A192KW | -4 | 192 | AES Key Wrap w/ 192-bit key | 2572 | | | | | 2573 | A256KW | -5 | 256 | AES Key Wrap w/ 256-bit key | 2574 +--------+-------+----------+-----------------------------+ 2576 Table 16: AES Key Wrap Algorithm Values 2578 12.2.1.1. Security Considerations for AES-KW 2580 The shared secret need to have some method to be regularly updated 2581 over time. The shared secret is the basis of trust. 2583 12.3. Key Encryption 2585 Key Encryption mode is also called key transport mode in some 2586 standards. Key Encryption mode differs from Key Wrap mode in that it 2587 uses an asymmetric encryption algorithm rather than a symmetric 2588 encryption algorithm to protect the key. This document defines one 2589 Key Encryption mode algorithm. 2591 When using a key encryption algorithm, the COSE_Enveloped structure 2592 for the recipient is organized as follows: 2594 o The 'protected' field MUST be absent. 2596 o The plain text to be encrypted is the key from next layer down 2597 (usually the content layer). 2599 o At a minimum, the 'unprotected' field MUST contain the 'alg' 2600 parameter and SHOULD contain a parameter identifying the 2601 asymmetric key. 2603 12.4. Direct Key Agreement 2605 The 'direct key agreement' class of recipient algorithms uses a key 2606 agreement method to create a shared secret. A KDF is then applied to 2607 the shared secret to derive a key to be used in protecting the data. 2608 This key is normally used as a CEK or MAC key, but could be used for 2609 other purposes if more than two layers are in use (see Appendix A). 2611 The most commonly used key agreement algorithm used is Diffie- 2612 Hellman, but other variants exist. Since COSE is designed for a 2613 store and forward environment rather than an on-line environment, 2614 many of the DH variants cannot be used as the receiver of the message 2615 cannot provide any key material. One side-effect of this is that 2616 perfect forward secrecy (see [RFC4949]) is not achievable. A static 2617 key will always be used for the receiver of the COSE message. 2619 Two variants of DH that are easily supported are: 2621 Ephemeral-Static DH: where the sender of the message creates a one 2622 time DH key and uses a static key for the recipient. The use of 2623 the ephemeral sender key means that no additional random input is 2624 needed as this is randomly generated for each message. 2626 Static-Static DH: where a static key is used for both the sender 2627 and the recipient. The use of static keys allows for recipient to 2628 get a weak version of data origination for the message. When 2629 static-static key agreement is used, then some piece of unique 2630 data is required to ensure that a different key is created for 2631 each message. 2633 In this specification, both variants are specified. This has been 2634 done to provide the weak data origination option for use with MAC 2635 operations. 2637 When direct key agreement mode is used, there MUST be only one 2638 recipient in the message. This method creates the key directly and 2639 that makes it difficult to mix with additional recipients. If 2640 multiple recipients are needed, then the version with key wrap needs 2641 to be used. 2643 The COSE_Enveloped structure for the recipient is organized as 2644 follows: 2646 o The 'protected' field MUST be absent. 2648 o At a minimum, the 'unprotected' field MUST contain the 'alg' 2649 parameter and SHOULD contain a parameter identifying the 2650 recipient's asymmetric key. 2652 o The 'unprotected' field MUST contain the 'epk' parameter. 2654 12.4.1. ECDH 2656 The basic mathematics for Elliptic Curve Diffie-Hellman can be found 2657 in [RFC6090]. 2659 ECDH is parameterized by the following: 2661 o Curve Type/Curve: The curve selected controls not only the size of 2662 the shared secret, but the mathematics for computing the shared 2663 secret. The curve selected also controls how a point in the curve 2664 is represented and what happens for the identity points on the 2665 curve. In this specification, we allow for a number of different 2666 curves to be used. A set of curves are defined in Table 20. 2667 Since the only the math is changed by changing the curve, the 2668 curve is not fixed for any of the algorithm identifiers we define. 2669 Instead, it is defined by the points used. 2671 o Ephemeral-static or static-static: The key agreement process may 2672 be done using either a static or an ephemeral key for the sender's 2673 side. When using ephemeral keys, the sender MUST generate a new 2674 ephemeral key for every key agreement operation. The ephemeral 2675 key is placed in the 'ephemeral key' parameter and MUST be present 2676 for all algorithm identifiers that use ephemeral keys. When using 2677 static keys, the sender MUST either generate a new random value or 2678 otherwise create a unique value to be placed in either in the KDF 2679 parameters or the context structure. For the KDF functions used, 2680 this means either in the 'salt' parameter for HKDF (Table 12) or 2681 in the 'PartyU nonce' parameter for the context structure 2682 (Table 13) MUST be present. (Both may be present if desired.) 2683 The value in the parameter MUST be unique for the key pair being 2684 used. It is acceptable to use a global counter that is 2685 incremented for every static-static operation and use the 2686 resulting value. When using static keys, the static key needs to 2687 be identified to the recipient. The static key can be identified 2688 either by providing the key ('static key') or by providing a key 2689 identifier for the static key ('static key id'). Both of these 2690 parameters are defined in Table 18 2692 o Key derivation algorithm: The result of an ECDH key agreement 2693 process does not provide a uniformly random secret. As such, it 2694 needs to be run through a KDF in order to produce a usable key. 2695 Processing the secret through a KDF also allows for the 2696 introduction of both context material, how the key is going to be 2697 used, and one time material in the even to of a static-static key 2698 agreement. 2700 o Key Wrap algorithm: A key wrap algorithm of 'none' means that the 2701 result of the KDF is going to be used as the key directly. This 2702 option, along with static-static, should be used if knowledge 2703 about the sender is desired. If 'none' is used, then the content 2704 layer encryption algorithm size is value fed to the context 2705 structure. Support is also provided for any of the key wrap 2706 algorithms defined in Section 12.2.1. If one of these options is 2707 used, the input key size to the key wrap algorithm is the value 2708 fed into the context structure as the key size. 2710 The set of direct ECDH algorithms defined in this document are found 2711 in Table 17. 2713 +-----------+------+--------+----------------+--------+-------------+ 2714 | name | valu | KDF | Ephemeral- | Key | description | 2715 | | e | | Static | Wrap | | 2716 +-----------+------+--------+----------------+--------+-------------+ 2717 | ECDH-ES + | 50 | HKDF - | yes | none | ECDH ES w/ | 2718 | HKDF-256 | | SHA-25 | | | HKDF - | 2719 | | | 6 | | | generate | 2720 | | | | | | key | 2721 | | | | | | directly | 2722 | | | | | | | 2723 | ECDH-ES + | 51 | HKDF - | yes | none | ECDH ES w/ | 2724 | HKDF-512 | | SHA-25 | | | HKDF - | 2725 | | | 6 | | | generate | 2726 | | | | | | key | 2727 | | | | | | directly | 2728 | | | | | | | 2729 | ECDH-SS + | 52 | HKDF - | no | none | ECDH ES w/ | 2730 | HKDF-256 | | SHA-25 | | | HKDF - | 2731 | | | 6 | | | generate | 2732 | | | | | | key | 2733 | | | | | | directly | 2734 | | | | | | | 2735 | ECDH-SS + | 53 | HKDF - | no | none | ECDH ES w/ | 2736 | HKDF-512 | | SHA-25 | | | HKDF - | 2737 | | | 6 | | | generate | 2738 | | | | | | key | 2739 | | | | | | directly | 2740 | | | | | | | 2741 | ECDH-ES + | 54 | HKDF - | yes | A128KW | ECDH ES w/ | 2742 | A128KW | | SHA-25 | | | Concat KDF | 2743 | | | 6 | | | and AES Key | 2744 | | | | | | wrap w/ 128 | 2745 | | | | | | bit key | 2746 | | | | | | | 2747 | ECDH- | 55 | HKDF - | yes | A192KW | ECDH ES w/ | 2748 | ES+A192KW | | SHA-25 | | | Concat KDF | 2749 | | | 6 | | | and AES Key | 2750 | | | | | | wrap w/ 192 | 2751 | | | | | | bit key | 2752 | | | | | | | 2753 | ECDH-ES + | 56 | HKDF - | yes | A256KW | ECDH ES w/ | 2754 | A256KW | | SHA-25 | | | Concat KDF | 2755 | | | 6 | | | and AES Key | 2756 | | | | | | wrap w/ 256 | 2757 | | | | | | bit key | 2758 | | | | | | | 2759 | ECDH-SS + | 57 | HKDF - | no | A128KW | ECDH SS w/ | 2760 | A128KW | | SHA-25 | | | Concat KDF | 2761 | | | 6 | | | and AES Key | 2762 | | | | | | wrap w/ 128 | 2763 | | | | | | bit key | 2764 | | | | | | | 2765 | ECDH-SS + | 58 | HKDF - | no | A192KW | ECDH SS w/ | 2766 | A192KW | | SHA-25 | | | Concat KDF | 2767 | | | 6 | | | and AES Key | 2768 | | | | | | wrap w/ 192 | 2769 | | | | | | bit key | 2770 | | | | | | | 2771 | ECDH-SS + | 59 | HKDF - | no | A256KW | ECDH SS w/ | 2772 | A256KW | | SHA-25 | | | Concat KDF | 2773 | | | 6 | | | and AES Key | 2774 | | | | | | wrap w/ 256 | 2775 | | | | | | bit key | 2776 +-----------+------+--------+----------------+--------+-------------+ 2778 Table 17: ECDH Algorithm Values 2780 +-----------+-------+----------+-----------+------------------------+ 2781 | name | label | type | algorithm | description | 2782 +-----------+-------+----------+-----------+------------------------+ 2783 | ephemeral | -1 | COSE_Key | ECDH-ES | Ephemeral Public key | 2784 | key | | | | for the sender | 2785 | | | | | | 2786 | static | -2 | COSE_Key | ECDH-ES | Static Public key for | 2787 | key | | | | the sender | 2788 | | | | | | 2789 | static | -3 | bstr | ECDH-SS | Static Public key | 2790 | key id | | | | identifier for the | 2791 | | | | | sender | 2792 +-----------+-------+----------+-----------+------------------------+ 2794 Table 18: ECDH Algorithm Parameters 2796 This document defines these algorithms to be used with the curves 2797 P-256, P-384, P-521. Implementations MUST verify that the key type 2798 and curve are correct. Different curves are restricted to different 2799 key types. Implementations MUST verify that the curve and algorithm 2800 are appropriate for the entities involved. 2802 When using a COSE key for this algorithm, the following checks are 2803 made: 2805 o The 'kty' field MUST be present and it MUST be 'EC2'. 2807 o If the 'alg' field present, it MUST match the Key Agreement 2808 algorithm being used. 2810 o If the 'key_ops' field is present, it MUST include 'derive key' or 2811 'derive bits' for the private key. 2813 o If the 'key_ops' field is present, it MUST be empty for the public 2814 key. 2816 12.5. Key Agreement with KDF 2818 Key Agreement with Key Wrapping uses a randomly generated CEK. The 2819 CEK is then encrypted using a Key Wrapping algorithm and a key 2820 derived from the shared secret computed by the key agreement 2821 algorithm. 2823 The COSE_Enveloped structure for the recipient is organized as 2824 follows: 2826 o The 'protected' field is fed into the KDF context structure. 2828 o The plain text to be encrypted is the key from next layer down 2829 (usually the content layer). 2831 o The 'alg' parameter MUST be present in the layer. 2833 o A parameter identifying the recipient's key SHOULD be present. A 2834 parameter identifying the sender's key SHOULD be present. 2836 12.5.1. ECDH 2838 These algorithms are defined in Table 17. 2840 When using a COSE key for this algorithm, the following checks are 2841 made: 2843 o The 'kty' field MUST be present and it MUST be 'EC2'. 2845 o If the 'alg' field present, it MUST match the Key Agreement 2846 algorithm being used. 2848 o If the 'key_ops' field is present, it MUST include 'derive key' or 2849 'derive bits' for the private key. 2851 o If the 'key_ops' field is present, it MUST be empty for the public 2852 key. 2854 13. Keys 2856 The COSE_Key object defines a way to hold a single key object. It is 2857 still required that the members of individual key types be defined. 2858 This section of the document is where we define an initial set of 2859 members for specific key types. 2861 For each of the key types, we define both public and private members. 2862 The public members are what is transmitted to others for their usage. 2863 We define private members mainly for the purpose of archival of keys 2864 by individuals. However, there are some circumstances in which 2865 private keys may be distributed by various entities in a protocol. 2866 Examples include: entities that have poor random number generation, 2867 centralized key creation for multi-cast type operations, and 2868 protocols in which a shared secret is used as a bearer token for 2869 authorization purposes. 2871 Key types are identified by the 'kty' member of the COSE_Key object. 2872 In this document, we define four values for the member: 2874 +-----------+-------+--------------------------------------------+ 2875 | name | value | description | 2876 +-----------+-------+--------------------------------------------+ 2877 | EC2 | 2 | Elliptic Curve Keys w/ X,Y Coordinate pair | 2878 | | | | 2879 | Symmetric | 4 | Symmetric Keys | 2880 | | | | 2881 | Reserved | 0 | This value is reserved | 2882 +-----------+-------+--------------------------------------------+ 2884 Table 19: Key Type Values 2886 13.1. Elliptic Curve Keys 2888 Two different key structures could be defined for Elliptic Curve 2889 keys. One version uses both an x and a y coordinate, potentially 2890 with point compression. This is the traditional EC point 2891 representation that is used in [RFC5480]. The other version uses 2892 only the x coordinate as the y coordinate is either to be recomputed 2893 or not needed for the key agreement operation. Currently no 2894 algorithms are defined using this key structure. 2896 +-------+----------+-------+------------------------------------+ 2897 | name | key type | value | description | 2898 +-------+----------+-------+------------------------------------+ 2899 | P-256 | EC2 | 1 | NIST P-256 also known as secp256r1 | 2900 | | | | | 2901 | P-384 | EC2 | 2 | NIST P-384 also known as secp384r1 | 2902 | | | | | 2903 | P-521 | EC2 | 3 | NIST P-521 also known as secp521r1 | 2904 +-------+----------+-------+------------------------------------+ 2906 Table 20: EC Curves 2908 13.1.1. Double Coordinate Curves 2910 The traditional way of sending EC curves has been to send either both 2911 the x and y coordinates, or the x coordinate and a sign bit for the y 2912 coordinate. The latter encoding has not been recommended in the IETF 2913 due to potential IPR issues. However, for operations in constrained 2914 environments, the ability to shrink a message by not sending the y 2915 coordinate is potentially useful. 2917 For EC keys with both coordinates, the 'kty' member is set to 2 2918 (EC2). The key parameters defined in this section are summarized in 2919 Table 21. The members that are defined for this key type are: 2921 crv contains an identifier of the curve to be used with the key. 2922 The curves defined in this document for this key type can be found 2923 in Table 20. Other curves may be registered in the future and 2924 private curves can be used as well. 2926 x contains the x coordinate for the EC point. The integer is 2927 converted to an octet string as defined in [SEC1]. Leading zero 2928 octets MUST be preserved. 2930 y contains either the sign bit or the value of y coordinate for the 2931 EC point. When encoding the value y, the integer is converted to 2932 an octet string (as defined in [SEC1]) and encoded as a CBOR bstr. 2933 Leading zero octets MUST be preserved. The compressed point 2934 encoding is also supported. Compute the sign bit as laid out in 2935 the Elliptic-Curve-Point-to-Octet-String Conversion function of 2936 [SEC1]. If the sign bit is zero, then encode y as a CBOR false 2937 value, otherwise encode y as a CBOR true value. The encoding of 2938 the infinity point is not supported. 2940 d contains the private key. 2942 For public keys, it is REQUIRED that 'crv', 'x' and 'y' be present in 2943 the structure. For private keys, it is REQUIRED that 'crv' and 'd' 2944 be present in the structure. For private keys, it is RECOMMENDED 2945 that 'x' and 'y' also be present, but they can be recomputed from the 2946 required elements and omitting them saves on space. 2948 +------+-------+-------+---------+----------------------------------+ 2949 | name | key | value | type | description | 2950 | | type | | | | 2951 +------+-------+-------+---------+----------------------------------+ 2952 | crv | 2 | -1 | int / | EC Curve identifier - Taken from | 2953 | | | | tstr | the COSE General Registry | 2954 | | | | | | 2955 | x | 2 | -2 | bstr | X Coordinate | 2956 | | | | | | 2957 | y | 2 | -3 | bstr / | Y Coordinate | 2958 | | | | bool | | 2959 | | | | | | 2960 | d | 2 | -4 | bstr | Private key | 2961 +------+-------+-------+---------+----------------------------------+ 2963 Table 21: EC Key Parameters 2965 13.2. Symmetric Keys 2967 Occasionally it is required that a symmetric key be transported 2968 between entities. This key structure allows for that to happen. 2970 For symmetric keys, the 'kty' member is set to 3 (Symmetric). The 2971 member that is defined for this key type is: 2973 k contains the value of the key. 2975 This key structure contains only private key information, care must 2976 be taken that it is never transmitted accidentally. For public keys, 2977 there are no required fields. For private keys, it is REQUIRED that 2978 'k' be present in the structure. 2980 +------+----------+-------+------+-------------+ 2981 | name | key type | value | type | description | 2982 +------+----------+-------+------+-------------+ 2983 | k | 4 | -1 | bstr | Key Value | 2984 +------+----------+-------+------+-------------+ 2986 Table 22: Symmetric Key Parameters 2988 14. CBOR Encoder Restrictions 2990 There has been an attempt to limit the number of places where the 2991 document needs to impose restrictions on how the CBOR Encoder needs 2992 to work. We have managed to narrow it down to the following 2993 restrictions: 2995 o The restriction applies to the encoding the Sig_structure, the 2996 Enc_structure, and the MAC_structure. 2998 o The rules for Canonical CBOR (Section 3.9 of RFC 7049) MUST be 2999 used in these locations. The main rule that needs to be enforced 3000 is that all lengths in these structures MUST be encoded such that 3001 they are encoded using definite lengths and the minimum length 3002 encoding is used. 3004 o Applications MUST not generate messages with the same label used 3005 twice as a key in a single map. Applications MUST not parse and 3006 process messages with the same label used twice as a key in a 3007 single map. Applications can enforce the parse and process 3008 requirement by using parsers that will fail the parse step or by 3009 using parsers that will pass all keys to the application and the 3010 application can perform the check for duplicate keys. 3012 15. Application Profiling Considerations 3014 This document is designed to provide a set of security services, but 3015 not to provide implementation requirements for specific usage. The 3016 interoperability requirements are provided for how each of the 3017 individual services are used and how the algorithms are to be used 3018 for interoperability. The requirements about which algorithms and 3019 which services are needed is deferred to each application. 3021 Applications are therefore intended to profile the usage of this 3022 document. This section provides a set of guidelines and topics that 3023 applications need to consider when using this document. 3025 o Applications need to determine the set of messages defined in this 3026 document that it will be using. The set of messages corresponds 3027 fairly directly to the set of security services that are needed 3028 and to the security levels needed. 3030 o Applications may define new header parameters for a specific 3031 purpose. Applications will often times select specific header 3032 parameters to use or not to use. For example, an application 3033 would normally state a preference for using either the IV or the 3034 partial IV parameter. If the partial IV parameter is specified, 3035 then the application would also need to define how the fixed 3036 portion of the IV would be determined. 3038 o When applications use externally defined authenticated data, they 3039 need to define how that data is to be defined. This document 3040 assumes that the data will be provided as a byte stream. More 3041 information can be found in Section 4.3. 3043 o Applications need to determine the set of security algorithms that 3044 are to be used. When selecting the algorithms to be used as the 3045 mandatory to implement set, consideration should be given to 3046 choosing different types of algorithms when two are chosen for a 3047 specific purpose. An example of this would be choosing HMAC- 3048 SHA512 and AES-CMAC as different MAC algorithms, the construction 3049 is vastly different between these two algorithms. This means that 3050 a weakening of one algorithm would be unlikely to lead to a 3051 weakening of the other algorithms. Of course, these algorithms do 3052 not provide the same level of security and thus may not be 3053 comparable for the desired security functionality. 3055 o Applications may need to provide some type of negotiation or 3056 discovery method if multiple algorithms or message structures are 3057 permitted. The method can be as simple as requiring 3058 preconfiguration of the set of algorithms to providing a discovery 3059 method built into the protocol. S/MIME provided a number of 3060 different ways to approach the problem that applications could 3061 follow: 3063 * Advertising in the message (S/MIME capabilities) [RFC5751]. 3065 * Advertising in the certificate (capabilities extension) 3066 [RFC4262]. 3068 * Minimum requirements for the S/MIME, which have been updated 3069 over time [RFC2633][RFC5751]. 3071 16. IANA Considerations 3073 16.1. CBOR Tag assignment 3075 It is requested that IANA assign the following tags from the "Concise 3076 Binary Object Representation (CBOR) Tags" registry. It is requested 3077 that the tags be assigned in the 24 to 255 value range. 3079 The tags to be assigned are in table Table 1. 3081 16.2. COSE Header Parameter Registry 3083 It is requested that IANA create a new registry entitled "COSE Header 3084 Parameters". The registery is to be created as Expert Review 3085 Required. Expert review guidelines are provided in Section 16.10 3087 The columns of the registry are: 3089 name The name is present to make it easier to refer to and discuss 3090 the registration entry. The value is not used in the protocol. 3091 Names are to be unique in the table. 3093 label This is the value used for the label. The label can be either 3094 an integer or a string. Registration in the table is based on the 3095 value of the label requested. Integer values between 1 and 255 3096 and strings of length 1 are designated as Standards Track Document 3097 required. Integer values from 256 to 65535 and strings of length 3098 2 are designated as Specification Required. Integer values of 3099 greater than 65535 and strings of length greater than 2 are 3100 designated as first come, first served. Integer values in the 3101 range -1 to -65536 are delegated to the "COSE Header Algorithm 3102 Label" registry. Integer values beyond -65536 are marked as 3103 private use. 3105 value This contains the CBOR type for the value portion of the 3106 label. 3108 value registry This contains a pointer to the registry used to 3109 contain values where the set is limited. 3111 description This contains a brief description of the header field. 3113 specification This contains a pointer to the specification defining 3114 the header field (where public). 3116 The initial contents of the registry can be found in Table 2. The 3117 specification column for all rows in that table should be this 3118 document. 3120 Additionally, the label of 0 is to be marked as 'Reserved'. 3122 16.3. COSE Header Algorithm Label Table 3124 It is requested that IANA create a new registry entitled "COSE Header 3125 Algorithm Labels". The registery is to be created as Expert Review 3126 Required. Expert review guidelines are provided in Section 16.10 3128 The columns of the registry are: 3130 name The name is present to make it easier to refer to and discuss 3131 the registration entry. The value is not used in the protocol. 3133 algorithm The algorithm(s) that this registry entry is used for. 3134 This value is taken from the "COSE Algorithm Value" registry. 3135 Multiple algorithms can be specified in this entry. For the 3136 table, the algorithm, label pair MUST be unique. 3138 label This is the value used for the label. The label is an integer 3139 in the range of -1 to -65536. 3141 value This contains the CBOR type for the value portion of the 3142 label. 3144 value registry This contains a pointer to the registry used to 3145 contain values where the set is limited. 3147 description This contains a brief description of the header field. 3149 specification This contains a pointer to the specification defining 3150 the header field (where public). 3152 The initial contents of the registry can be found in Table 12, 3153 Table 13, and Table 18. The specification column for all rows in 3154 that table should be this document. 3156 16.4. COSE Algorithm Registry 3158 It is requested that IANA create a new registry entitled "COSE 3159 Algorithm Registry". The registery is to be created as Expert Review 3160 Required. Expert review guidelines are provided in Section 16.10 3162 The columns of the registry are: 3164 value The value to be used to identify this algorithm. Algorithm 3165 values MUST be unique. The value can be a positive integer, a 3166 negative integer or a string. Integer values between -256 and 255 3167 and strings of length 1 are designated as Standards Track Document 3168 required. Integer values from -65536 to 65535 and strings of 3169 length 2 are designated as Specification Required. Integer values 3170 of greater than 65535 and strings of length greater than 2 are 3171 designated as first come, first served. Integer values beyond 3172 -65536 are marked as private use. 3174 description A short description of the algorithm. 3176 specification A document where the algorithm is defined (if publicly 3177 available). 3179 The initial contents of the registry can be found in Table 9, 3180 Table 8, Table 10, Table 5, Table 6, Table 7, Table 14, Table 15, 3181 Table 16, and Table 17. The specification column for all rows in 3182 that table should be this document. 3184 16.5. COSE Key Common Parameter Registry 3186 It is requested that IANA create a new registry entitled "COSE Key 3187 Common Parameter" Registry. The registery is to be created as Expert 3188 Review Required. Expert review guidelines are provided in 3189 Section 16.10 3191 The columns of the registry are: 3193 name This is a descriptive name that enables easier reference to the 3194 item. It is not used in the encoding. 3196 label The value to be used to identify this algorithm. Key map 3197 labels MUST be unique. The label can be a positive integer, a 3198 negative integer or a string. Integer values between 0 and 255 3199 and strings of length 1 are designated as Standards Track Document 3200 required. Integer values from 256 to 65535 and strings of length 3201 2 are designated as Specification Required. Integer values of 3202 greater than 65535 and strings of length greater than 2 are 3203 designated as first come, first served. Integer values in the 3204 range -1 to -65536 are used for key parameters specific to a 3205 single algorithm delegated to the "COSE Key Type Parameter Label" 3206 registry. Integer values beyond -65536 are marked as private use. 3208 CBOR Type This field contains the CBOR type for the field 3210 registry This field denotes the registry that values come from, if 3211 one exists. 3213 description This field contains a brief description for the field 3215 specification This contains a pointer to the public specification 3216 for the field if one exists 3218 This registry will be initially populated by the values in 3219 Section 7.1. The specification column for all of these entries will 3220 be this document. 3222 16.6. COSE Key Type Parameter Registry 3224 It is requested that IANA create a new registry "COSE Key Type 3225 Parameters". The registery is to be created as Expert Review 3226 Required. Expert review guidelines are provided in Section 16.10 3228 The columns of the table are: 3230 key type This field contains a descriptive string of a key type. 3231 This should be a value that is in the COSE General Values table 3232 and is placed in the 'kty' field of a COSE Key structure. 3234 name This is a descriptive name that enables easier reference to the 3235 item. It is not used in the encoding. 3237 label The label is to be unique for every value of key type. The 3238 range of values is from -256 to -1. Labels are expected to be 3239 reused for different keys. 3241 CBOR type This field contains the CBOR type for the field 3243 description This field contains a brief description for the field 3245 specification This contains a pointer to the public specification 3246 for the field if one exists 3248 This registry will be initially populated by the values in Table 21 3249 and Table 22. The specification column for all of these entries will 3250 be this document. 3252 16.7. COSE Elliptic Curve Registry 3254 It is requested that IANA create a new registry "COSE Elliptic Curve 3255 Parameters". The registery is to be created as Expert Review 3256 Required. Expert review guidelines are provided in Section 16.10 3258 The columns of the table are: 3260 name This is a descriptive name that enables easier reference to the 3261 item. It is not used in the encoding. 3263 value This is the value used to identify the curve. These values 3264 MUST be unique. The integer values from -256 to 255 are 3265 designated as Standards Track Document Required. The integer 3266 values from 256 to 65535 and -65536 to -257 are designated as 3267 Specification Required. Integer values over 65535 are designated 3268 as first come, first served. Integer values less than -65536 are 3269 marked as private use. 3271 key type This designates the key type(s) that can be used with this 3272 curve. 3274 description This field contains a brief description of the curve. 3276 specification This contains a pointer to the public specification 3277 for the curve if one exists. 3279 This registry will be initially populated by the values in Table 19. 3280 The specification column for all of these entries will be this 3281 document. 3283 16.8. Media Type Registrations 3285 16.8.1. COSE Security Message 3287 This section registers the "application/cose" media type in the 3288 "Media Types" registry. These media types are used to indicate that 3289 the content is a COSE_MSG. 3291 Type name: application 3293 Subtype name: cose 3295 Required parameters: N/A 3297 Optional parameters: cose-type 3299 Encoding considerations: binary 3300 Security considerations: See the Security Considerations section 3301 of RFC TBD. 3303 Interoperability considerations: N/A 3305 Published specification: RFC TBD 3307 Applications that use this media type: To be identified 3309 Fragment identifier considerations: N/A 3311 Additional information: 3313 * Magic number(s): N/A 3315 * File extension(s): cbor 3317 * Macintosh file type code(s): N/A 3319 Person & email address to contact for further information: 3320 iesg@ietf.org 3322 Intended usage: COMMON 3324 Restrictions on usage: N/A 3326 Author: Jim Schaad, ietf@augustcellars.com 3328 Change Controller: IESG 3330 Provisional registration? No 3332 16.8.2. COSE Key media type 3334 This section registers the "application/cose-key+cbor" and 3335 "application/cose-key-set+cbor" media types in the "Media Types" 3336 registry. These media types are used to indicate, respectively, that 3337 content is a COSE_Key or COSE_KeySet object. 3339 Type name: application 3341 Subtype name: cose-key+cbor 3343 Required parameters: N/A 3345 Optional parameters: N/A 3347 Encoding considerations: binary 3348 Security considerations: See the Security Considerations section 3349 of RFC TBD. 3351 Interoperability considerations: N/A 3353 Published specification: RFC TBD 3355 Applications that use this media type: To be identified 3357 Fragment identifier considerations: N/A 3359 Additional information: 3361 * Magic number(s): N/A 3363 * File extension(s): cbor 3365 * Macintosh file type code(s): N/A 3367 Person & email address to contact for further information: 3368 iesg@ietf.org 3370 Intended usage: COMMON 3372 Restrictions on usage: N/A 3374 Author: Jim Schaad, ietf@augustcellars.com 3376 Change Controller: IESG 3378 Provisional registration? No 3380 Type name: application 3382 Subtype name: cose-key-set+cbor 3384 Required parameters: N/A 3386 Optional parameters: N/A 3388 Encoding considerations: binary 3390 Security considerations: See the Security Considerations section 3391 of RFC TBD. 3393 Interoperability considerations: N/A 3395 Published specification: RFC TBD 3396 Applications that use this media type: To be identified 3398 Fragment identifier considerations: N/A 3400 Additional information: 3402 * Magic number(s): N/A 3404 * File extension(s): cbor 3406 * Macintosh file type code(s): N/A 3408 Person & email address to contact for further information: 3409 iesg@ietf.org 3411 Intended usage: COMMON 3413 Restrictions on usage: N/A 3415 Author: Jim Schaad, ietf@augustcellars.com 3417 Change Controller: IESG 3419 Provisional registration? No 3421 16.9. CoAP Content Format Registrations 3423 This section registers a set of content formats for CoAP. ID 3424 assignment in the 24-255 range is requested. 3426 +----------------------------------+----------+-------+-------------+ 3427 | Media Type | Encoding | ID | Reference | 3428 +----------------------------------+----------+-------+-------------+ 3429 | application/cose; cose-type | | TBD10 | [This | 3430 | ="cose-sign" | | | Document] | 3431 | | | | | 3432 | application/cose; cose-type | | TBD11 | [This | 3433 | ="cose-sign1" | | | Document] | 3434 | | | | | 3435 | application/cose; cose-type | | TBD12 | [This | 3436 | ="cose-enveloped" | | | Document] | 3437 | | | | | 3438 | application/cose; cose-type | | TBD13 | [This | 3439 | ="cose-encrypted" | | | Document] | 3440 | | | | | 3441 | application/cose; cose-type | | TBD14 | [This | 3442 | ="cose-mac" | | | Document] | 3443 | | | | | 3444 | application/cose; cose-type | | TBD15 | [This | 3445 | ="cose-mac0" | | | Document] | 3446 | | | | | 3447 | application/cose-key | | TBD16 | [This | 3448 | | | | Document] | 3449 | | | | | 3450 | application/cose-key-set | | TBD17 | [This | 3451 | | | | Document | 3452 +----------------------------------+----------+-------+-------------+ 3454 16.10. Expert Review Instructions 3456 All of the IANA registries established in this document are defined 3457 as expert review. This section gives some general guidelines for 3458 what the experts should be looking for, but they are being designated 3459 as experts for a reason so they should be given substantial latitude. 3461 Expert reviewers should take into consideration the following points: 3463 o Point squatting should be discouraged. Reviewers are encouraged 3464 to get sufficient information for registration requests to ensure 3465 that the usage is not going to duplicate one that is already 3466 registered and that the point is likely to be used in deployments. 3467 The zones tagged as private use are intended for testing purposes 3468 and closed environments, code points in other ranges should not be 3469 assigned for testing. 3471 o Specifications are required for the standards track range of point 3472 assignment. Specifications should exist for specification 3473 required ranges, but early assignment before a specification is 3474 available is considered to be permissible. Specifications are 3475 needed for the first-come, first-serve range if they are expected 3476 to be used outside of closed environments in an inoperable way. 3477 When specifications are not provided, the description provided 3478 needs to have sufficient information to identify what point is 3479 being used for. 3481 o Experts should take into account the expected usage of fields when 3482 approving point assignment. The fact that there is a range for 3483 standards track documents does not mean that a standards track 3484 document cannot have points assigned outside of that range. Some 3485 of the ranges are restricted in range, items which are not 3486 expected to be common or are not expected to be used in restricted 3487 environments should be assigned to values which will encode to 3488 longer byte strings. 3490 o When algorithms are registered, vanity registrations should be 3491 discouraged. One way to do this is to require applications to 3492 provide additional documentation on security analysis of 3493 algorithms. Another thing that should be considered is to request 3494 for an opinion on the algorithm from the Cryptographic Forum 3495 Research Group. Algorithms which do not meet the security 3496 requirements of the community and the messages structures should 3497 not be registered. 3499 17. Security Considerations 3501 There are security considerations: 3503 1. Protect private keys. 3505 2. MAC messages with more than one recipient means one cannot figure 3506 out which party sent the message. 3508 3. Use of a direct key with other recipient structures hands the key 3509 to the other recipients. 3511 4. Use of direct ECDH direct encryption is easy for people to leak 3512 information on if there are other recipients in the message. 3514 5. Considerations about protected vs unprotected header fields. WHy 3515 the algorithm parameter needs to be protected. 3517 6. Need to verify that: 1) the kty field of the key matches the key 3518 and algorithm being used, 2) the kty field needs to be included 3519 in the trust decision as well as the other key fields, and 3) the 3520 algorithm is included in the trust decision. 3522 18. References 3524 18.1. Normative References 3526 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3527 Requirement Levels", BCP 14, RFC 2119, 3528 DOI 10.17487/RFC2119, March 1997, 3529 . 3531 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 3532 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 3533 October 2013, . 3535 18.2. Informative References 3537 [AES-GCM] Dworkin, M., "NIST Special Publication 800-38D: 3538 Recommendation for Block Cipher Modes of Operation: 3539 Galois/Counter Mode (GCM) and GMAC.", Nov 2007. 3541 [DSS] U.S. National Institute of Standards and Technology, 3542 "Digital Signature Standard (DSS)", July 2013. 3544 [I-D.greevenbosch-appsawg-cbor-cddl] 3545 Vigano, C. and H. Birkholz, "CBOR data definition language 3546 (CDDL): a notational convention to express CBOR data 3547 structures", draft-greevenbosch-appsawg-cbor-cddl-07 (work 3548 in progress), October 2015. 3550 [MAC] NiST, N., "FIPS PUB 113: Computer Data Authentication", 3551 May 1985. 3553 [PVSig] Brown, D. and D. Johnson, "Formal Security Proofs for a 3554 Signature Scheme with Partial Message Recover", February 3555 2000. 3557 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 3558 Hashing for Message Authentication", RFC 2104, 3559 DOI 10.17487/RFC2104, February 1997, 3560 . 3562 [RFC2633] Ramsdell, B., Ed., "S/MIME Version 3 Message 3563 Specification", RFC 2633, DOI 10.17487/RFC2633, June 1999, 3564 . 3566 [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography 3567 Specification Version 2.0", RFC 2898, 3568 DOI 10.17487/RFC2898, September 2000, 3569 . 3571 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 3572 (AES) Key Wrap Algorithm", RFC 3394, DOI 10.17487/RFC3394, 3573 September 2002, . 3575 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 3576 Standards (PKCS) #1: RSA Cryptography Specifications 3577 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 3578 2003, . 3580 [RFC3610] Whiting, D., Housley, R., and N. Ferguson, "Counter with 3581 CBC-MAC (CCM)", RFC 3610, DOI 10.17487/RFC3610, September 3582 2003, . 3584 [RFC4231] Nystrom, M., "Identifiers and Test Vectors for HMAC-SHA- 3585 224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512", 3586 RFC 4231, DOI 10.17487/RFC4231, December 2005, 3587 . 3589 [RFC4262] Santesson, S., "X.509 Certificate Extension for Secure/ 3590 Multipurpose Internet Mail Extensions (S/MIME) 3591 Capabilities", RFC 4262, DOI 10.17487/RFC4262, December 3592 2005, . 3594 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 3595 FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, 3596 . 3598 [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, 3599 "Elliptic Curve Cryptography Subject Public Key 3600 Information", RFC 5480, DOI 10.17487/RFC5480, March 2009, 3601 . 3603 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 3604 RFC 5652, DOI 10.17487/RFC5652, September 2009, 3605 . 3607 [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet 3608 Mail Extensions (S/MIME) Version 3.2 Message 3609 Specification", RFC 5751, DOI 10.17487/RFC5751, January 3610 2010, . 3612 [RFC5752] Turner, S. and J. Schaad, "Multiple Signatures in 3613 Cryptographic Message Syntax (CMS)", RFC 5752, 3614 DOI 10.17487/RFC5752, January 2010, 3615 . 3617 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 3618 Key Derivation Function (HKDF)", RFC 5869, 3619 DOI 10.17487/RFC5869, May 2010, 3620 . 3622 [RFC5990] Randall, J., Kaliski, B., Brainard, J., and S. Turner, 3623 "Use of the RSA-KEM Key Transport Algorithm in the 3624 Cryptographic Message Syntax (CMS)", RFC 5990, 3625 DOI 10.17487/RFC5990, September 2010, 3626 . 3628 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 3629 Curve Cryptography Algorithms", RFC 6090, 3630 DOI 10.17487/RFC6090, February 2011, 3631 . 3633 [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations 3634 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 3635 RFC 6151, DOI 10.17487/RFC6151, March 2011, 3636 . 3638 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 3639 Algorithm (DSA) and Elliptic Curve Digital Signature 3640 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 3641 2013, . 3643 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3644 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 3645 2014, . 3647 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 3648 Application Protocol (CoAP)", RFC 7252, 3649 DOI 10.17487/RFC7252, June 2014, 3650 . 3652 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 3653 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 3654 2015, . 3656 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 3657 RFC 7516, DOI 10.17487/RFC7516, May 2015, 3658 . 3660 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 3661 DOI 10.17487/RFC7517, May 2015, 3662 . 3664 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 3665 DOI 10.17487/RFC7518, May 2015, 3666 . 3668 [RFC7539] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF 3669 Protocols", RFC 7539, DOI 10.17487/RFC7539, May 2015, 3670 . 3672 [SEC1] Standards for Efficient Cryptography Group, "SEC 1: 3673 Elliptic Curve Cryptography", May 2009. 3675 [SP800-56A] 3676 Barker, E., Chen, L., Roginsky, A., and M. Smid, "NIST 3677 Special Publication 800-56A: Recommendation for Pair-Wise 3678 Key Establishment Schemes Using Discrete Logarithm 3679 Cryptography", May 2013. 3681 Appendix A. Three Levels of Recipient Information 3683 All of the currently defined recipient algorithms classes only use 3684 two levels of the COSE_Encrypt structure. The first level is the 3685 message content and the second level is the content key encryption. 3686 However, if one uses a recipient algorithm such as RSA-KEM (see 3687 Appendix A of RSA-KEM [RFC5990], then it make sense to have three 3688 levels of the COSE_Encrypt structure. 3690 These levels would be: 3692 o Level 0: The content encryption level. This level contains the 3693 payload of the message. 3695 o Level 1: The encryption of the CEK by a KEK. 3697 o Level 2: The encryption of a long random secret using an RSA key 3698 and a key derivation function to convert that secret into the KEK. 3700 This is an example of what a triple layer message would look like. 3701 The message has the following layers: 3703 o Level 0: Has a content encrypted with AES-GCM using a 128-bit key. 3705 o Level 1: Uses the AES Key wrap algorithm with a 128-bit key. 3707 o Level 2: Uses ECDH Ephemeral-Static direct to generate the level 1 3708 key. 3710 In effect this example is a decomposed version of using the ECDH- 3711 ES+A128KW algorithm. 3713 Size of binary file is 216 bytes 3715 992( 3716 [ 3717 / protected / h'a10101' / { 3718 \ alg \ 1:1 \ AES-GCM 128 \ 3719 } / , 3720 / unprotected / { 3721 / iv / 5:h'02d1f7e6f26c43d4868d87ce' 3722 }, 3723 / ciphertext / h'64f84d913ba60a76070a9a48f26e97e863e28529bf9be9d 3724 e3bea1788f681200d875242f6', 3725 / recipients / [ 3726 [ 3727 / protected / h'', 3728 / unprotected / { 3729 / alg / 1:-3 / A128KW / 3730 }, 3731 / ciphertext / h'5a15dbf5b282ecb31a6074ee3815c252405dd7583e0 3732 78188', 3733 / recipients / [ 3734 [ 3735 / protected / h'', 3736 / unprotected / { 3737 / alg / 1:50 / ECDH-ES + HKDF-256 /, 3738 / kid / 4:'meriadoc.brandybuck@buckland.example', 3739 / ephemeral / -1:{ 3740 / kty / 1:2, 3741 / crv / -1:1, 3742 / x / -2:h'b2add44368ea6d641f9ca9af308b4079aeb519f11 3743 e9b8a55a600b21233e86e68', 3744 / y / -3:h'1a2cf118b9ee6895c8f415b686d4ca1cef362d4a7 3745 630a31ef6019c0c56d33de0' 3746 } 3747 }, 3748 / ciphertext / h'' 3749 ] 3750 ] 3751 ] 3752 ] 3753 ] 3754 ) 3756 Appendix B. Examples 3758 The examples can be found at https://github.com/cose-wg/Examples. 3759 The file names in each section correspond the same file names in the 3760 repository. I am currently still in the process of getting the 3761 examples up there along with some control information for people to 3762 be able to check and reproduce the examples. 3764 Examples may have some features that are in question but not yet 3765 incorporated in the document. 3767 To make it easier to read, the examples are presented using the 3768 CBOR's diagnostic notation rather than a binary dump. A ruby based 3769 tool exists to convert between a number of formats. This tool can be 3770 installed with the command line: 3772 gem install cbor-diag 3774 The diagnostic notation can be converted into binary files using the 3775 following command line: 3777 diag2cbor < inputfile > outputfile 3779 The examples can be extracted from the XML version of this document 3780 via an XPath expression as all of the artwork is tagged with the 3781 attribute type='CBORdiag'. 3783 B.1. Examples of MAC messages 3785 B.1.1. Shared Secret Direct MAC 3787 This example users the following: 3789 o MAC: AES-CMAC, 256-bit key, truncated to 64 bits 3791 o Recipient class: direct shared secret 3793 o File name: Mac-04 3795 Size of binary file is 73 bytes 3796 994( 3797 [ 3798 / protected / h'a1016f4145532d434d41432d3235362f3634' / { 3799 \ alg \ 1:"AES-CMAC-256//64" 3800 } / , 3801 / unprotected / {}, 3802 / payload / 'This is the content.', 3803 / tag / h'5924501e17f6e852', 3804 / recipients / [ 3805 [ 3806 / protected / h'', 3807 / unprotected / { 3808 / alg / 1:-6 / direct /, 3809 / kid / 4:'our-secret' 3810 }, 3811 / ciphertext / h'' 3812 ] 3813 ] 3814 ] 3815 ) 3817 B.1.2. ECDH Direct MAC 3819 This example uses the following: 3821 o MAC: HMAC w/SHA-256, 256-bit key 3823 o Recipient class: ECDH key agreement, two static keys, HKDF w/ 3824 context structure 3826 Size of binary file is 217 bytes 3827 994( 3828 [ 3829 / protected / h'a10104' / { 3830 \ alg \ 1:4 \ HMAC 256//256 \ 3831 } / , 3832 / unprotected / {}, 3833 / payload / 'This is the content.', 3834 / tag / h'fc672c2bc7e9e811a0ec6173bdadfe3f11d71a1fc04164feea711b 3835 330c2b2478', 3836 / recipients / [ 3837 [ 3838 / protected / h'', 3839 / unprotected / { 3840 / alg / 1:52 / ECDH-SS + HKDF-256 /, 3841 / kid / 4:'meriadoc.brandybuck@buckland.example', 3842 / static kid / -3:'peregrin.took@tuckborough.example', 3843 "apu":h'4d8553e7e74f3c6a3a9dd3ef286a8195cbf8a23d19558ccfec 3844 7d34b824f42d92bd06bd2c7f0271f0214e141fb779ae2856abf585a58368b017e7f2 3845 a9e5ce4db5' 3846 }, 3847 / ciphertext / h'' 3848 ] 3849 ] 3850 ] 3851 ) 3853 B.1.3. Wrapped MAC 3855 This example uses the following: 3857 o MAC: AES-MAC, 128-bit key, truncated to 64 bits 3859 o Recipient class: AES keywrap w/ a pre-shared 256-bit key 3861 Size of binary file is 124 bytes 3862 994( 3863 [ 3864 / protected / h'a1016e4145532d3132382d4d41432d3634' / { 3865 \ alg \ 1:"AES-128-MAC-64" 3866 } / , 3867 / unprotected / {}, 3868 / payload / 'This is the content.', 3869 / tag / h'f65bc4e5ed133779', 3870 / recipients / [ 3871 [ 3872 / protected / h'', 3873 / unprotected / { 3874 / alg / 1:-5 / A256KW /, 3875 / kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037' 3876 }, 3877 / ciphertext / h'711ab0dc2fc4585dce27effa6781c8093eba906f227 3878 b6eb0' 3879 ] 3880 ] 3881 ] 3882 ) 3884 B.1.4. Multi-recipient MAC message 3886 This example uses the following: 3888 o MAC: HMAC w/ SHA-256, 128-bit key 3890 o Recipient class: Uses three different methods 3892 1. ECDH Ephemeral-Static, Curve P-521, AES-Key Wrap w/ 128-bit 3893 key 3895 2. AES-Key Wrap w/ 256-bit key 3897 Size of binary file is 374 bytes 3898 994( 3899 [ 3900 / protected / h'a10104' / { 3901 \ alg \ 1:4 \ HMAC 256//256 \ 3902 } / , 3903 / unprotected / {}, 3904 / payload / 'This is the content.', 3905 / tag / h'a25bff1b6251926c3b3314d9802831e9101fee82f11bec87ce622a 3906 5c10292bce', 3907 / recipients / [ 3908 [ 3909 / protected / h'', 3910 / unprotected / { 3911 / alg / 1:54 / ECHD-ES+A128KW /, 3912 / kid / 4:'bilbo.baggins@hobbiton.example', 3913 -1:{ 3914 1:2, 3915 -1:3, 3916 -2:h'43b12669acac3fd27898ffba0bcd2e6c366d53bc4db71f909a7 3917 59304acfb5e18cdc7ba0b13ff8c7636271a6924b1ac63c02688075b55ef2d613574e 3918 7dc242f79c3', 3919 -3:h'812dd694f4ef32b11014d74010a954689c6b6e8785b333d1ab4 3920 4f22b9d1091ae8fc8ae40b687e5cfbe7ee6f8b47918a07bb04e9f5b1a51a334a16bc 3921 09777434113' 3922 } 3923 }, 3924 / ciphertext / h'70306cbce4b28f40cb7574b6928b5318c965b28a4e8 3925 a892d71ddbab944fe68799baec290899623b1' 3926 ], 3927 [ 3928 / protected / h'', 3929 / unprotected / { 3930 / alg / 1:-5 / A256KW /, 3931 / kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037' 3932 }, 3933 / ciphertext / h'0b2c7cfce04e98276342d6476a7723c090dfdd15f9a 3934 518e7736549e998370695e6d6a83b4ae507bb' 3935 ] 3936 ] 3937 ] 3938 ) 3940 B.2. Examples of Encrypted Messages 3941 B.2.1. Direct ECDH 3943 This example uses the following: 3945 o CEK: AES-GCM w/ 128-bit key 3947 o Recipient class: ECDH Ephemeral-Static, Curve P-256 3949 Size of binary file is 184 bytes 3951 992( 3952 [ 3953 / protected / h'a10101' / { 3954 \ alg \ 1:1 \ AES-GCM 128 \ 3955 } / , 3956 / unprotected / { 3957 / iv / 5:h'c9cf4df2fe6c632bf7886413' 3958 }, 3959 / ciphertext / h'45fce2814311024d3a479e7d3eed063850f3f0b9ce550fb 3960 62f23a0d5151c8049bed5802a', 3961 / recipients / [ 3962 [ 3963 / protected / h'', 3964 / unprotected / { 3965 / alg / 1:50 / ECDH-ES + HKDF-256 /, 3966 / kid / 4:'meriadoc.brandybuck@buckland.example', 3967 / ephemeral / -1:{ 3968 / kty / 1:2, 3969 / crv / -1:1, 3970 / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf 3971 bf054e1c7b4d91d6280', 3972 / y / -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069 3973 170d924b7e03bf822bb' 3974 } 3975 }, 3976 / ciphertext / h'' 3977 ] 3978 ] 3979 ] 3980 ) 3982 B.2.2. Direct plus Key Derivation 3984 This example uses the following: 3986 o CEK: AES-CCM w/128-bit key, truncate the tag to 64 bits 3987 o Recipient class: Use HKDF on a shared secret with the following 3988 implicit fields as part of the context. 3990 * APU identity: "lighting-client" 3992 * APV identity: "lighting-server" 3994 * Supplementary Public Other: "Encryption Example 02" 3996 Size of binary file is 97 bytes 3998 992( 3999 [ 4000 / protected / h'a1010a' / { 4001 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 4002 } / , 4003 / unprotected / { 4004 / iv / 5:h'89f52f65a1c580933b5261a7' 4005 }, 4006 / ciphertext / h'5e70f2058526d70d29c155015c5723a3f9c15a13a6a9f4c 4007 ece341510', 4008 / recipients / [ 4009 [ 4010 / protected / h'', 4011 / unprotected / { 4012 / alg / 1:"dir+kdf", 4013 / kid / 4:'our-secret', 4014 -20:'aabbccddeeffgghh' 4015 }, 4016 / ciphertext / h'' 4017 ] 4018 ] 4019 ] 4020 ) 4022 B.2.3. Counter Signature on Encrypted Content 4024 This example uses the following: 4026 o CEK: AES-GCM w/ 128-bit key 4028 o Recipient class: ECDH Ephemeral-Static, Curve P-256 4030 Size of binary file is 357 bytes 4031 992( 4032 [ 4033 / protected / h'a10101' / { 4034 \ alg \ 1:1 \ AES-GCM 128 \ 4035 } / , 4036 / unprotected / { 4037 / iv / 5:h'c9cf4df2fe6c632bf7886413', 4038 / countersign / 7:[ 4039 / protected / h'', 4040 / unprotected / { 4041 / alg / 1:-9 / ES512 /, 4042 / kid / 4:'bilbo.baggins@hobbiton.example' 4043 }, 4044 / signature / h'00aa98cbfd382610a375d046a275f30266e8d0faacb9 4045 069fde06e37825ae7825419c474f416ded0c8e3e7b55bff68f2a704135bdf99186f6 4046 6659461c8cf929cc7fb300e4ec6cac6be6f18d92cd319dccfc354d78cbdf2b1cf293 4047 c9d8f82449feeb4f25a24b80a08c2ddbae8507b3da7c4c869ef7c20a82e3d7b9b54f 4048 031a76fcebca1fcb' 4049 ] 4050 }, 4051 / ciphertext / h'45fce2814311024d3a479e7d3eed063850f3f0b9ce550fb 4052 62f23a0d5151c8049bed5802a', 4053 / recipients / [ 4054 [ 4055 / protected / h'', 4056 / unprotected / { 4057 / alg / 1:50 / ECDH-ES + HKDF-256 /, 4058 / kid / 4:'meriadoc.brandybuck@buckland.example', 4059 / ephemeral / -1:{ 4060 / kty / 1:2, 4061 / crv / -1:1, 4062 / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf 4063 bf054e1c7b4d91d6280', 4064 / y / -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069 4065 170d924b7e03bf822bb' 4066 } 4067 }, 4068 / ciphertext / h'' 4069 ] 4070 ] 4071 ] 4072 ) 4074 B.2.4. Encrypted Content w/ Implicit Recipient 4076 This example uses the following: 4078 o CEK: AES-CCM w/ 128-bit key and a 64-bit tag 4079 Size of binary file is 53 bytes 4081 993( 4082 [ 4083 / protected / h'a1010a' / { 4084 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 4085 } / , 4086 / unprotected / { 4087 / iv / 5:h'89f52f65a1c580933b5261a7' 4088 }, 4089 / ciphertext / h'16c4b98fe85c8e2eed1f990ef40ce02cd54aa3195d43ed6 4090 18a9df43e' 4091 ] 4092 ) 4094 B.2.5. Encrypted Content w/ Implicit Recipient and Partial IV 4096 This example uses the following: 4098 o CEK: AES-CCM w/ 128-bit key and a 64-bit tag 4100 o Prefix for IV is 89F52F65A1C580933B52 4102 Size of binary file is 43 bytes 4104 993( 4105 [ 4106 / protected / h'a1010a' / { 4107 \ alg \ 1:10 \ AES-CCM-16-64-128 \ 4108 } / , 4109 / unprotected / { 4110 / partial iv / 6:h'61a7' 4111 }, 4112 / ciphertext / h'2b2dd3406aa1e83b488d32d6852bfad387a5199c6fcc3d6 4113 c6bbff5e2' 4114 ] 4115 ) 4117 B.3. Examples of Signed Message 4119 B.3.1. Single Signature 4121 This example uses the following: 4123 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256-1 4125 Size of binary file is 106 bytes 4126 991( 4127 [ 4128 / protected / h'', 4129 / unprotected / {}, 4130 / payload / 'This is the content.', 4131 / signatures / [ 4132 [ 4133 / protected / h'a10126' / { 4134 \ alg \ 1:-7 \ ES256 \ 4135 } / , 4136 / unprotected / { 4137 / kid / 4:'11' 4138 }, 4139 / signature / h'00eae868ecc176883766c5dc5ba5b8dca25dab3c2e56 4140 a551ce5705b793914348e100d702a242d4f6428a2b6ce0bae311a1be41f3c0333ed3 4141 d892e4d07af86f338a89' 4142 ] 4143 ] 4144 ] 4145 ) 4147 B.3.2. Multiple Signers 4149 This example uses the following: 4151 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256-1 4153 o Signature Algorithm: ECDSA w/ SHA-512, Curve P-521 4155 Size of binary file is 276 bytes 4156 991( 4157 [ 4158 / protected / h'', 4159 / unprotected / {}, 4160 / payload / 'This is the content.', 4161 / signatures / [ 4162 [ 4163 / protected / h'a10126' / { 4164 \ alg \ 1:-7 \ ES256 \ 4165 } / , 4166 / unprotected / { 4167 / kid / 4:'11' 4168 }, 4169 / signature / h'0dc1c5e62719d8f3cce1468b7c881eee6a8088b46bf8 4170 36ae956dd38fe93199193571f290e9a471cbcb3bbfd6f35ce9b22bd100621bcdbf2f 4171 8ba16c19d86e9306' 4172 ], 4173 [ 4174 / protected / h'', 4175 / unprotected / { 4176 / alg / 1:-9 / ES512 /, 4177 / kid / 4:'bilbo.baggins@hobbiton.example' 4178 }, 4179 / signature / h'012ce5b1dfe8b5aa6eaa09a54c58a84ad0900e4fdf27 4180 59ec22d1c861cccd75c7e1c4025a2da35e512fc2874d6ac8fd862d09ad07ed2deac2 4181 97b897561e04a8d4247601bb1af26e0fce66df949d0de84627280129c9110f2ab241 4182 217cf151b3a147215cfddc31ea02569ac927b43b6f67418e694b92a69a3363a3c1c0 4183 0149c41c4722471c' 4184 ] 4185 ] 4186 ] 4187 ) 4189 B.3.3. Counter Signature 4191 This example uses the following: 4193 o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256-1 4195 B.4. COSE Keys 4197 B.4.1. Public Keys 4199 This is an example of a COSE Key set. This example includes the 4200 public keys for all of the previous examples. 4202 In order the keys are: 4204 o An EC key with a kid of "meriadoc.brandybuck@buckland.example" 4206 o An EC key with a kid of "peregrin.took@tuckborough.example" 4208 o An EC key with a kid of "bilbo.baggins@hobbiton.example" 4210 o An EC key with a kid of "11" 4212 Size of binary file is 481 bytes 4214 [ 4215 { 4216 / crv / -1:1, 4217 / x / -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108d 4218 e439c08551d', 4219 / y / -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9e 4220 ecd0084d19c', 4221 / kty / 1:2, 4222 / kid / 2:'meriadoc.brandybuck@buckland.example' 4223 }, 4224 { 4225 / crv / -1:3, 4226 / x / -2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c73 4227 7bf5de7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f24576200 4228 85e5c8f42ad', 4229 / y / -3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a08937 4230 7e247e60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3 4231 fe1ea1d9475', 4232 / kty / 1:2, 4233 / kid / 2:'bilbo.baggins@hobbiton.example' 4234 }, 4235 { 4236 / crv / -1:1, 4237 / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c 4238 7b4d91d6280', 4239 / y / -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b 4240 7e03bf822bb', 4241 / kty / 1:2, 4242 / kid / 2:'peregrin.took@tuckborough.example' 4243 }, 4244 { 4245 / crv / -1:1, 4246 / x / -2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219 4247 a86d6a09eff', 4248 / y / -3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6e 4249 d28bbfc117e', 4250 / kty / 1:2, 4251 / kid / 2:'11' 4252 } 4253 ] 4255 B.4.2. Private Keys 4257 This is an example of a COSE Key set. This example includes the 4258 private keys for all of the previous examples. 4260 In order the keys are: 4262 o An EC key with a kid of "meriadoc.brandybuck@buckland.example" 4264 o A shared-secret key with a kid of "our-secret" 4266 o An EC key with a kid of "peregrin.took@tuckborough.example" 4268 o A shared-secret key with a kid of "018c0ae5-4d9b-471b- 4269 bfd6-eef314bc7037" 4271 o An EC key with a kid of "bilbo.baggins@hobbiton.example" 4273 o An EC key with a kid of "11" 4275 Size of binary file is 816 bytes 4277 [ 4278 { 4279 / kty / 1:2, 4280 / kid / 2:'meriadoc.brandybuck@buckland.example', 4281 / crv / -1:1, 4282 / x / -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108d 4283 e439c08551d', 4284 / y / -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9e 4285 ecd0084d19c', 4286 / d / -4:h'aff907c99f9ad3aae6c4cdf21122bce2bd68b5283e6907154ad91 4287 1840fa208cf' 4288 }, 4289 { 4290 / kty / 1:4, 4291 / kid / 2:'our-secret', 4292 / k / -1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76d 4293 cea6c427188' 4294 }, 4295 { 4296 / kty / 1:2, 4297 / kid / 2:'bilbo.baggins@hobbiton.example', 4298 / crv / -1:3, 4299 / x / -2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c73 4300 7bf5de7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f24576200 4301 85e5c8f42ad', 4302 / y / -3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a08937 4303 7e247e60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3 4304 fe1ea1d9475', 4305 / d / -4:h'00085138ddabf5ca975f5860f91a08e91d6d5f9a76ad4018766a4 4306 76680b55cd339e8ab6c72b5facdb2a2a50ac25bd086647dd3e2e6e99e84ca2c3609f 4307 df177feb26d' 4308 }, 4309 { 4310 / kty / 1:4, 4311 / kid / 2:'our-secret2', 4312 / k / -1:h'849b5786457c1491be3a76dcea6c4271' 4313 }, 4314 { 4315 / kty / 1:2, 4316 / crv / -1:1, 4317 / kid / 2:'peregrin.took@tuckborough.example', 4318 / x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c 4319 7b4d91d6280', 4320 / y / -3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b 4321 7e03bf822bb', 4322 / d / -4:h'02d1f7e6f26c43d4868d87ceb2353161740aacf1f7163647984b5 4323 22a848df1c3' 4324 }, 4325 { 4326 / kty / 1:4, 4327 / kid / 2:'018c0ae5-4d9b-471b-bfd6-eef314bc7037', 4328 / k / -1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76d 4329 cea6c427188' 4330 }, 4331 { 4332 / kty / 1:2, 4333 / kid / 2:'11', 4334 / crv / -1:1, 4335 / x / -2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219 4336 a86d6a09eff', 4337 / y / -3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6e 4338 d28bbfc117e', 4339 / d / -4:h'57c92077664146e876760c9520d054aa93c3afb04e306705db609 4340 0308507b4d3' 4341 } 4342 ] 4344 Appendix C. Document Updates 4346 C.1. Version -08 to -09 4348 o Integrate CDDL syntax into the text 4350 o Define Expert review guidelines 4352 o Expand application profiling guidelines 4354 o Expand text around Partial IV 4356 o Creation time becomes Operation time 4357 o Add tagging for all structures so that they cannot be moved 4359 o Add optional parameter to cose media type 4361 o Add single signature and mac structures 4363 C.2. Version -07 to -08 4365 o Redefine sequence number into a the Partial IV. 4367 C.3. Version -06 to -07 4369 o Editorial Changes 4371 o Make new IANA registries be Expert Review 4373 C.4. Version -05 to -06 4375 o Remove new CFRG Elliptical Curve key agreement algorithms. 4377 o Remove RSA algorithms 4379 o Define a creation time and sequence number for discussions. 4381 o Remove message type field from all structures. 4383 o Define CBOR tagging for all structures with IANA registrations. 4385 C.5. Version -04 to -05 4387 o Removed the jku, x5c, x5t, x5t#S256, x5u, and jwk headers. 4389 o Add enveloped data vs encrypted data structures. 4391 o Add counter signature parameter. 4393 C.6. Version -03 to -04 4395 o Change top level from map to array. 4397 o Eliminate the term "key management" from the document. 4399 o Point to content registries for the 'content type' attribute 4401 o Push protected field into the KDF functions for recipients. 4403 o Remove password based recipient information. 4405 o Create EC Curve Registry. 4407 C.7. Version -02 to -03 4409 o Make a pass over all of the algorithm text. 4411 o Alter the CDDL so that Keys and KeySets are top level items and 4412 the key examples validate. 4414 o Add sample key structures. 4416 o Expand text on dealing with Externally Supplied Data. 4418 o Update the examples to match some of the renumbering of fields. 4420 C.8. Version -02 to -03 4422 o Add a set of straw man proposals for algorithms. It is possible/ 4423 expected that this text will be moved to a new document. 4425 o Add a set of straw man proposals for key structures. It is 4426 possible/expected that this text will be moved to a new document. 4428 o Provide guidance on use of externally supplied authenticated data. 4430 o Add external authenticated data to signing structure. 4432 C.9. Version -01 to -2 4434 o Add first pass of algorithm information 4436 o Add direct key derivation example. 4438 C.10. Version -00 to -01 4440 o Add note on where the document is being maintained and 4441 contributing notes. 4443 o Put in proposal on MTI algorithms. 4445 o Changed to use labels rather than keys when talking about what 4446 indexes a map. 4448 o Moved nonce/IV to be a common header item. 4450 o Expand section to discuss the common set of labels used in 4451 COSE_Key maps. 4453 o Start marking element 0 in registries as reserved. 4455 o Update examples. 4457 Editorial Comments 4459 [CREF1] JLS: Need to check this list for correctness before publishing. 4461 [CREF2] JLS: I have not gone through the document to determine what 4462 needs to be here yet. We mostly want to grab terms that are 4463 used in unusual ways or are not generally understood. 4465 [CREF3] Hannes: Ensure that the list of examples only includes items 4466 that are implemented in this specification. Check the other 4467 places where such lists occur and ensure that they also follow 4468 this rule. 4470 [CREF4] JLS: Restrict to the set of supported parameters. 4472 [CREF5] Ilari: Look to see if we need to be clearer about how the fields 4473 defined in the table are transported and thus why they have 4474 labels. 4476 Author's Address 4478 Jim Schaad 4479 August Cellars 4481 Email: ietf@augustcellars.com