--- 1/draft-ietf-cose-rfc8152bis-struct-14.txt 2021-02-01 07:13:47.130711979 -0800 +++ 2/draft-ietf-cose-rfc8152bis-struct-15.txt 2021-02-01 07:13:47.418719310 -0800 @@ -1,19 +1,19 @@ COSE Working Group J. Schaad Internet-Draft August Cellars -Obsoletes: 8152 (if approved) 24 September 2020 +Obsoletes: 8152 (if approved) 1 February 2021 Intended status: Standards Track -Expires: 28 March 2021 +Expires: 5 August 2021 CBOR Object Signing and Encryption (COSE): Structures and Process - draft-ietf-cose-rfc8152bis-struct-14 + draft-ietf-cose-rfc8152bis-struct-15 Abstract Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. There is a need for the ability to have basic security services defined for this data format. This document defines the CBOR Object Signing and Encryption (COSE) protocol. This specification describes how to create and process signatures, message authentication codes, and encryption using CBOR for serialization. This specification additionally describes how to @@ -39,25 +39,25 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on 28 March 2021. + This Internet-Draft will expire on 5 August 2021. Copyright Notice - Copyright (c) 2020 IETF Trust and the persons identified as the + Copyright (c) 2021 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. @@ -89,75 +89,75 @@ 6.1. MACed Message with Recipients . . . . . . . . . . . . . . 31 6.2. MACed Messages with Implicit Key . . . . . . . . . . . . 32 6.3. How to Compute and Verify a MAC . . . . . . . . . . . . . 33 7. Key Objects . . . . . . . . . . . . . . . . . . . . . . . . . 34 7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 35 8. Taxonomy of Algorithms used by COSE . . . . . . . . . . . . . 37 8.1. Signature Algorithms . . . . . . . . . . . . . . . . . . 38 8.2. Message Authentication Code (MAC) Algorithms . . . . . . 40 8.3. Content Encryption Algorithms . . . . . . . . . . . . . . 40 8.4. Key Derivation Functions (KDFs) . . . . . . . . . . . . . 41 - 8.5. Content Key Distribution Methods . . . . . . . . . . . . 42 + 8.5. Content Key Distribution Methods . . . . . . . . . . . . 41 8.5.1. Direct Encryption . . . . . . . . . . . . . . . . . . 42 8.5.2. Key Wrap . . . . . . . . . . . . . . . . . . . . . . 42 8.5.3. Key Transport . . . . . . . . . . . . . . . . . . . . 43 8.5.4. Direct Key Agreement . . . . . . . . . . . . . . . . 43 8.5.5. Key Agreement with Key Wrap . . . . . . . . . . . . . 44 9. CBOR Encoding Restrictions . . . . . . . . . . . . . . . . . 45 10. Application Profiling Considerations . . . . . . . . . . . . 45 - 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 + 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46 11.1. COSE Header Parameters Registry . . . . . . . . . . . . 47 11.2. COSE Key Common Parameters Registry . . . . . . . . . . 47 11.3. Media Type Registrations . . . . . . . . . . . . . . . . 47 11.3.1. COSE Security Message . . . . . . . . . . . . . . . 47 11.3.2. COSE Key Media Type . . . . . . . . . . . . . . . . 48 11.4. CoAP Content-Formats Registry . . . . . . . . . . . . . 50 11.5. CBOR Tags Registry . . . . . . . . . . . . . . . . . . . 50 - 11.6. Expert Review Instructions . . . . . . . . . . . . . . . 50 - 12. Security Considerations . . . . . . . . . . . . . . . . . . . 51 + 11.6. Expert Review Instructions . . . . . . . . . . . . . . . 51 + 12. Security Considerations . . . . . . . . . . . . . . . . . . . 52 13. Implementation Status . . . . . . . . . . . . . . . . . . . . 53 13.1. Author's Versions . . . . . . . . . . . . . . . . . . . 54 - 13.2. JavaScript Version . . . . . . . . . . . . . . . . . . . 54 + 13.2. JavaScript Version . . . . . . . . . . . . . . . . . . . 55 13.3. Python Version . . . . . . . . . . . . . . . . . . . . . 55 13.4. COSE Testing Library . . . . . . . . . . . . . . . . . . 55 - 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 55 - 14.1. Normative References . . . . . . . . . . . . . . . . . . 55 + 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 56 + 14.1. Normative References . . . . . . . . . . . . . . . . . . 56 14.2. Informative References . . . . . . . . . . . . . . . . . 56 Appendix A. Guidelines for External Data Authentication of Algorithms . . . . . . . . . . . . . . . . . . . . . . . 60 Appendix B. Two Layers of Recipient Information . . . . . . . . 63 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 65 - C.1. Examples of Signed Messages . . . . . . . . . . . . . . . 65 - C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 65 - C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 66 - C.1.3. Signature with Criticality . . . . . . . . . . . . . 67 - C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 68 - C.2.1. Single ECDSA Signature . . . . . . . . . . . . . . . 68 - C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 69 - C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 69 - C.3.2. Direct Plus Key Derivation . . . . . . . . . . . . . 70 - C.3.3. Encrypted Content with External Data . . . . . . . . 71 - C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 72 - C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 72 - C.4.2. Encrypted Message with a Partial IV . . . . . . . . . 73 - C.5. Examples of MACed Messages . . . . . . . . . . . . . . . 73 - C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 73 - C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 74 - C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 75 - C.5.4. Multi-Recipient MACed Message . . . . . . . . . . . . 76 - C.6. Examples of MAC0 Messages . . . . . . . . . . . . . . . . 77 - C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 77 - C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 78 - C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 78 - C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 79 - Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 81 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 82 + C.1. Examples of Signed Messages . . . . . . . . . . . . . . . 66 + C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 66 + C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 67 + C.1.3. Signature with Criticality . . . . . . . . . . . . . 68 + C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 69 + C.2.1. Single ECDSA Signature . . . . . . . . . . . . . . . 69 + C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 70 + C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 70 + C.3.2. Direct Plus Key Derivation . . . . . . . . . . . . . 71 + C.3.3. Encrypted Content with External Data . . . . . . . . 72 + C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 73 + C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 73 + C.4.2. Encrypted Message with a Partial IV . . . . . . . . . 74 + C.5. Examples of MACed Messages . . . . . . . . . . . . . . . 74 + C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 74 + C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 75 + C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 76 + C.5.4. Multi-Recipient MACed Message . . . . . . . . . . . . 77 + C.6. Examples of MAC0 Messages . . . . . . . . . . . . . . . . 78 + C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 78 + C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 79 + C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 79 + C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 80 + Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 82 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 83 1. Introduction There has been an increased focus on small, constrained devices that make up the Internet of Things (IoT). One of the standards that has come out of this process is "Concise Binary Object Representation (CBOR)" [I-D.ietf-cbor-7049bis]. CBOR extended the data model of the JavaScript Object Notation (JSON) [STD90] by allowing for binary data, among other changes. CBOR has been adopted by several of the IETF working groups dealing with the IoT world as their encoding of @@ -205,39 +205,39 @@ specific cryptographic algorithms. Details on specific algorithms can be found in [I-D.ietf-cose-rfc8152bis-algs] and [RFC8230]. Details for additional algorithms are expected to be defined in future documents. COSE was initially designed as part of a solution to provide security to Constrained RESTful Environments (CoRE), and this is done using [RFC8613] and [I-D.ietf-core-groupcomm-bis]. However, COSE is not restricted to just these cases and can be used in any place where one would consider either JOSE or CMS [RFC5652] for the purpose of - providing security services. The use of COSE, like JOSE and CMS, is - only for use in store and forward or offline protocols. The use of - COSE in online protocols needing encryption, require that an online - key establishment process be done before sending objects back and - forth. Any application which uses COSE for security services first - needs to determine what security services are required and then - select the appropriate COSE structures and cryptographic algorithms - based on those needs. Section 10 provides additional information on - what applications need to specify when using COSE. + providing security services. COSE, like JOSE and CMS, is only for + use in store and forward or offline protocols. The use of COSE in + online protocols needing encryption, require that an online key + establishment process be done before sending objects back and forth. + Any application which uses COSE for security services first needs to + determine what security services are required and then select the + appropriate COSE structures and cryptographic algorithms based on + those needs. Section 10 provides additional information on what + applications need to specify when using COSE. One feature that is present in CMS that is not present in this standard is a digest structure. This omission is deliberate. It is better for the structure to be defined in each protocol as different protocols will want to include a different set of fields as part of the structure. While an algorithm identifier and the digest value are going to be common to all applications, the two values may not always be adjacent as the algorithm could be defined once with multiple values. Applications may additionally want to define - additional data fields as part of the structure. A one such + additional data fields as part of the structure. One such application-specific element would be to include a URI or other pointer to where the data that is being hashed can be obtained. [I-D.ietf-cose-hash-algs] contains one such possible structure along with defining a set of digest algorithms. During the process of advancing COSE to Internet Standard, it was noticed the description of the security properties of countersignatures was incorrect for the COSE_Sign1 structure. Since the security properties that were described, those of a true countersignature, were those that the working group desired, the @@ -373,24 +373,24 @@ In JSON, maps are called objects and only have one kind of map key: a text string. In COSE, we use text strings, negative integers, and unsigned integers as map keys. The integers are used for compactness of encoding and easy comparison. The inclusion of text strings allows for an additional range of short encoded values to be used as well. Since the word "key" is mainly used in its other meaning, as a cryptographic key, we use the term "label" for this usage as a map key. - The presence a label that is neither a a text string or an integer, - in a CBOR map, is an error. Applications can either fail processing - or process messages by ignoring incorrect labels; however, they MUST - NOT create messages with incorrect labels. + The presence a label that is neither a text string or an integer, in + a CBOR map, is an error. Applications can either fail processing or + process messages by ignoring incorrect labels; however, they MUST NOT + create messages with incorrect labels. A CDDL grammar fragment defines the non-terminal 'label', as in the previous paragraph, and 'values', which permits any value to be used. label = int / tstr values = any 1.6. Document Terminology In this document, we use the following terminology: @@ -443,25 +443,25 @@ (i.e. transported separately from the COSE structure), but the location is still used. The content is wrapped in a bstr when present and is a nil value when detached. Elements after this point are dependent on the specific message type. COSE messages are built using the concept of layers to separate different types of cryptographic concepts. As an example of how this works, consider the COSE_Encrypt message (Section 5.1). This message type is broken into two layers: the content layer and the recipient - layer. The content layer contains the plaintext is encrypted and - information about the encrypted message. The recipient layer contins - the content encryption key (CEK) is encrypted and information about - how it is encrypted for each recipient. A single layer version of - the encryption message COSE_Encrypt0 (Section 5.2) is provided for + layer. The content layer contains the encrypted plaintext and + information about the encrypted message. The recipient layer + contains the encrypted content encryption key (CEK) and information + about how it is encrypted for each recipient. A single layer version + of the encryption message COSE_Encrypt0 (Section 5.2) is provided for cases where the CEK is pre-shared. Identification of which type of message has been presented is done by the following methods: 1. The specific message type is known from the context. This may be defined by a marker in the containing structure or by restrictions specified by the application protocol. 2. The message type is identified by a CBOR tag. Messages with a @@ -801,21 +801,21 @@ converted structure will fail signature validation. 4.1. Signing with One or More Signers The COSE_Sign structure allows for one or more signatures to be applied to a message payload. Header parameters relating to the content and header parameters relating to the signature are carried along with the signature itself. These header parameters may be authenticated by the signature, or just present. An example of a header parameter about the content is the content type header - parameter. An examples of a header parameter about the signature + parameter. An example of a header parameter about the signature would be the algorithm and key used to create the signature. RFC 5652 indicates that: | When more than one signature is present, the successful validation | of one signature associated with a given signer is usually treated | as a successful signature by that signer. However, there are some | application environments where other rules are needed. An | application that employs a rule other than one valid signature for | each signer must specify those rules. Also, where simple matching @@ -1758,49 +1758,49 @@ implementing these algorithms and for applications that use them. The first is that the message content is not fully available until after a signature has been validated. Until that point, the part of the message contained inside of the signature is unrecoverable. The second is that the security analysis of the strength of the signature can be very much dependent on the structure of the message content. Finally, in the event that multiple signatures are applied to a message, all of the signature algorithms are going to be required to consume the same bytes of message content. This means that the mixing of the signature with message recovery and signature with - appendix schemes in a single message is not supported, and if a - recovery signature scheme is used. + appendix schemes in a single message is not supported. The signature functions for this scheme are: signature, message sent = Sign(message content, key) valid, message content = Verification(message sent, key, signature) + No message recovery signature algorithms have been formally defined for COSE yet, and given the new constraints arising from this schemes, while some of these issues have already been identified there is a high probability that additional issues will arise when integrating message recovery signature algorithms. The first algorithm defined is going to need to make decisions about these - issues and those decisions re likely to be binding on any further + issues and those decisions are likely to be binding on any further algorithms defined. We use the following terms below: message content bytes: The byte provided by the application to be signed. to-be-signed bytes: The byte string passed into the signature algorithm. recovered bytes: The bytes recovered during the signature verification process. - Some of the issue2 that have already been identified are: + Some of the issues that have already been identified are: * The to-be-signed bytes are not the same as the message content bytes. This is because we build a larger to-be-signed message during the signature processing. The recovered bytes length may exceed the message content length, but not the length of the to- be-signed bytes. This may lead to privacy considerations if, for example, the externally supplied data contains confidential information. * There may be difficulties in determining where the recovered bytes @@ -2065,23 +2064,23 @@ 9. CBOR Encoding Restrictions This document limits the restrictions it imposes on how the CBOR Encoder needs to work. It has been narrowed down to the following restrictions: * The restriction applies to the encoding of the Sig_structure, the Enc_structure, and the MAC_structure. - * Encoding MUST be done using definite lengths and values MUST be - the minimum possible length. This means that the integer 1 is - encoded as "0x01" and not "0x1801". + * Encoding MUST be done using definite lengths and the value's + length MUST be the minimum possible length. This means that the + integer 1 is encoded as "0x01" and not "0x1801". * 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. 10. Application Profiling Considerations @@ -2123,21 +2122,21 @@ are to be used. When selecting the algorithms to be used as the mandatory-to-implement set, consideration should be given to choosing different types of algorithms when two are chosen for a specific purpose. An example of this would be choosing HMAC- SHA512 and AES-CMAC as different MAC algorithms; the construction is vastly different between these two algorithms. This means that a weakening of one algorithm would be unlikely to lead to a weakening of the other algorithms. Of course, these algorithms do not provide the same level of security and thus may not be comparable for the desired security functionality. Additional - guidence can be found in [BCP201]. + guidance can be found in [BCP201]. * Applications may need to provide some type of negotiation or discovery method if multiple algorithms or message structures are permitted. The method can be as simple as requiring pre- configuration of the set of algorithms to providing a discovery method built into the protocol. S/MIME provided a number of different ways to approach the problem that applications could follow: - Advertising in the message (S/MIME capabilities) [RFC5751]. @@ -2145,36 +2144,46 @@ - Advertising in the certificate (capabilities extension) [RFC4262]. - Minimum requirements for the S/MIME, which have been updated over time [RFC2633] [RFC5751] (note that [RFC2633] has been obsoleted by [RFC5751]). 11. IANA Considerations The registries and registrations listed below were created during - processing of RFC 8152 [RFC8152]. The majority of the actions are to - update the references to point to this document. + processing of RFC 8152 [RFC8152]. The majority of the following + actions are to update the references to point to this document. + + Note that while [I-D.ietf-cose-rfc8152bis-algs] also updates the + registries and registrations originally established by [RFC8152], the + requested updates are mutually exclusive. The updates requested in + this document do not conflict or overlap with the updates requested + in [I-D.ietf-cose-rfc8152bis-algs], and vice versa. 11.1. COSE Header Parameters Registry IANA created a registry titled "COSE Header Parameters" as part of processing [RFC8152]. IANA is requested to update the reference for - all entries, except "counter signature" and "CounterSignature0", in - the table from [RFC8152] to this document. The reference for - "counter signature" and "CounterSignature0" are to be left alone. + this registry from [RFC8152] to this document. IANA is also + requested to update the reference for all entries, except "counter + signature" and "CounterSignature0", in the table from [RFC8152] to + this document. The reference for "counter signature" and + "CounterSignature0" are to be left as-is. 11.2. COSE Key Common Parameters Registry IANA created a registry titled "COSE Key Common Parameters" as part of the processing of [RFC8152]. IANA is requested to update the - reference for entries in the table from [RFC8152] to this document. + reference for this registry from [RFC8152] to this document. IANA is + also requested to update the reference for entries in the table from + [RFC8152] to this document. 11.3. Media Type Registrations 11.3.1. COSE Security Message This section registers the 'application/cose' media type in the "Media Types" registry. These media types are used to indicate that the content is a COSE message. Type name: application @@ -2573,33 +2581,33 @@ 14.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [I-D.ietf-cbor-7049bis] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", Work in Progress, Internet-Draft, - draft-ietf-cbor-7049bis-14, 16 June 2020, - . + draft-ietf-cbor-7049bis-16, 30 September 2020, + . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [I-D.ietf-cose-rfc8152bis-algs] Schaad, J., "CBOR Object Signing and Encryption (COSE): Initial Algorithms", Work in Progress, Internet-Draft, - draft-ietf-cose-rfc8152bis-algs-11, 1 July 2020, + draft-ietf-cose-rfc8152bis-algs-12, 24 September 2020, . + algs-12>. 14.2. Informative References [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", RFC 8152, DOI 10.17487/RFC8152, July 2017, . [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and @@ -2718,22 +2726,22 @@ Schaad, J., "CBOR Object Signing and Encryption (COSE): Hash Algorithms", Work in Progress, Internet-Draft, draft- ietf-cose-hash-algs-09, 14 September 2020, . [I-D.ietf-core-groupcomm-bis] Dijk, E., Wang, C., and M. Tiloca, "Group Communication for the Constrained Application Protocol (CoAP)", Work in Progress, Internet-Draft, draft-ietf-core-groupcomm-bis- - 01, 13 July 2020, . + 02, 2 November 2020, . [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, "Object Security for Constrained RESTful Environments (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, . [I-D.irtf-cfrg-argon2] Biryukov, A., Dinu, D., Khovratovich, D., and S. Josefsson, "The memory-hard Argon2 password hash and proof-of-work function", Work in Progress, Internet-Draft,