--- 1/draft-ietf-cose-rfc8152bis-struct-00.txt 2019-02-14 19:13:31.383438427 -0800 +++ 2/draft-ietf-cose-rfc8152bis-struct-01.txt 2019-02-14 19:13:31.531442047 -0800 @@ -1,32 +1,32 @@ COSE Working Group J. Schaad Internet-Draft August Cellars -Obsoletes: 8152 (if approved) January 21, 2019 +Obsoletes: 8152 (if approved) February 14, 2019 Intended status: Standards Track -Expires: July 25, 2019 +Expires: August 18, 2019 CBOR Object Signing and Encryption (COSE) - Structures and Process - draft-ietf-cose-rfc8152bis-struct-00 + draft-ietf-cose-rfc8152bis-struct-01 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 represent cryptographic keys using CBOR. - This document along with [I-D.schaad-cose-rfc8152bis-algs] obsoletes + This document along with [I-D.ietf-cose-rfc8152bis-algs] obsoletes RFC8152. Contributing to this document The source for this draft is being maintained in GitHub. Suggested changes should be submitted as pull requests at . Instructions are on that page as well. Editorial changes can be managed in GitHub, but any substantial issues need to be discussed on the COSE mailing list. @@ -38,149 +38,152 @@ 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 July 25, 2019. + This Internet-Draft will expire on August 18, 2019. Copyright Notice Copyright (c) 2019 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Design Changes from JOSE . . . . . . . . . . . . . . . . 5 - 1.2. Requirements Terminology . . . . . . . . . . . . . . . . 6 - 1.3. CBOR Grammar . . . . . . . . . . . . . . . . . . . . . . 6 - 1.4. CBOR-Related Terminology . . . . . . . . . . . . . . . . 7 - 1.5. Document Terminology . . . . . . . . . . . . . . . . . . 8 + 1.2. Changes from RFC8152 . . . . . . . . . . . . . . . . . . 6 + 1.3. Requirements Terminology . . . . . . . . . . . . . . . . 6 + 1.4. CBOR Grammar . . . . . . . . . . . . . . . . . . . . . . 6 + 1.5. CBOR-Related Terminology . . . . . . . . . . . . . . . . 7 + 1.6. Document Terminology . . . . . . . . . . . . . . . . . . 8 2. Basic COSE Structure . . . . . . . . . . . . . . . . . . . . 8 - 3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 10 - 3.1. Common COSE Headers Parameters . . . . . . . . . . . . . 12 - 4. Signing Objects . . . . . . . . . . . . . . . . . . . . . . . 16 - 4.1. Signing with One or More Signers . . . . . . . . . . . . 16 - 4.2. Signing with One Signer . . . . . . . . . . . . . . . . . 18 - 4.3. Externally Supplied Data . . . . . . . . . . . . . . . . 19 - 4.4. Signing and Verification Process . . . . . . . . . . . . 20 - 4.5. Computing Counter Signatures . . . . . . . . . . . . . . 21 - 5. Encryption Objects . . . . . . . . . . . . . . . . . . . . . 22 - 5.1. Enveloped COSE Structure . . . . . . . . . . . . . . . . 22 - 5.1.1. Content Key Distribution Methods . . . . . . . . . . 24 - 5.2. Single Recipient Encrypted . . . . . . . . . . . . . . . 24 - 5.3. How to Encrypt and Decrypt for AEAD Algorithms . . . . . 25 - 5.4. How to Encrypt and Decrypt for AE Algorithms . . . . . . 27 - 6. MAC Objects . . . . . . . . . . . . . . . . . . . . . . . . . 29 - 6.1. MACed Message with Recipients . . . . . . . . . . . . . . 29 - 6.2. MACed Messages with Implicit Key . . . . . . . . . . . . 30 - 6.3. How to Compute and Verify a MAC . . . . . . . . . . . . . 31 - 7. Key Objects . . . . . . . . . . . . . . . . . . . . . . . . . 32 - 7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 33 - 8. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 36 - 9. Message Authentication Code (MAC) Algorithms . . . . . . . . 37 - 10. Content Encryption Algorithms . . . . . . . . . . . . . . . . 38 - 11. Key Derivation Functions (KDFs) . . . . . . . . . . . . . . . 38 - 12. Content Key Distribution Methods . . . . . . . . . . . . . . 39 - 12.1. Direct Encryption . . . . . . . . . . . . . . . . . . . 39 - 12.2. Key Wrap . . . . . . . . . . . . . . . . . . . . . . . . 40 - 12.3. Key Transport . . . . . . . . . . . . . . . . . . . . . 40 - 12.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 41 - 12.5. Key Agreement with Key Wrap . . . . . . . . . . . . . . 42 - 13. CBOR Encoder Restrictions . . . . . . . . . . . . . . . . . . 42 - 14. Application Profiling Considerations . . . . . . . . . . . . 43 - 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44 - 15.1. CBOR Tag Assignment . . . . . . . . . . . . . . . . . . 44 - 15.2. COSE Header Parameters Registry . . . . . . . . . . . . 44 - 15.3. COSE Header Algorithm Parameters Registry . . . . . . . 44 - 15.4. COSE Key Common Parameters Registry . . . . . . . . . . 45 - 15.5. Media Type Registrations . . . . . . . . . . . . . . . . 45 - 15.5.1. COSE Security Message . . . . . . . . . . . . . . . 45 - 15.5.2. COSE Key Media Type . . . . . . . . . . . . . . . . 46 - 15.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 48 - 15.7. Expert Review Instructions . . . . . . . . . . . . . . . 48 - 16. Security Considerations . . . . . . . . . . . . . . . . . . . 49 - 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 51 - 17.1. Normative References . . . . . . . . . . . . . . . . . . 51 - 17.2. Informative References . . . . . . . . . . . . . . . . . 52 + 3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 11 + 3.1. Common COSE Headers Parameters . . . . . . . . . . . . . 13 + 4. Signing Objects . . . . . . . . . . . . . . . . . . . . . . . 17 + 4.1. Signing with One or More Signers . . . . . . . . . . . . 17 + 4.2. Signing with One Signer . . . . . . . . . . . . . . . . . 19 + 4.3. Externally Supplied Data . . . . . . . . . . . . . . . . 20 + 4.4. Signing and Verification Process . . . . . . . . . . . . 21 + 4.5. Computing Counter Signatures . . . . . . . . . . . . . . 22 + 5. Encryption Objects . . . . . . . . . . . . . . . . . . . . . 23 + 5.1. Enveloped COSE Structure . . . . . . . . . . . . . . . . 23 + 5.1.1. Content Key Distribution Methods . . . . . . . . . . 25 + 5.2. Single Recipient Encrypted . . . . . . . . . . . . . . . 25 + 5.3. How to Encrypt and Decrypt for AEAD Algorithms . . . . . 26 + 5.4. How to Encrypt and Decrypt for AE Algorithms . . . . . . 28 + 6. MAC Objects . . . . . . . . . . . . . . . . . . . . . . . . . 30 + 6.1. MACed Message with Recipients . . . . . . . . . . . . . . 30 + 6.2. MACed Messages with Implicit Key . . . . . . . . . . . . 31 + 6.3. How to Compute and Verify a MAC . . . . . . . . . . . . . 32 + 7. Key Objects . . . . . . . . . . . . . . . . . . . . . . . . . 33 + 7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 34 + 8. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 37 + 9. Message Authentication Code (MAC) Algorithms . . . . . . . . 38 + 10. Content Encryption Algorithms . . . . . . . . . . . . . . . . 39 + 11. Key Derivation Functions (KDFs) . . . . . . . . . . . . . . . 39 + 12. Content Key Distribution Methods . . . . . . . . . . . . . . 40 + 12.1. Direct Encryption . . . . . . . . . . . . . . . . . . . 40 + 12.2. Key Wrap . . . . . . . . . . . . . . . . . . . . . . . . 41 + 12.3. Key Transport . . . . . . . . . . . . . . . . . . . . . 41 + 12.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 42 + 12.5. Key Agreement with Key Wrap . . . . . . . . . . . . . . 43 + 13. CBOR Encoder Restrictions . . . . . . . . . . . . . . . . . . 43 + 14. Application Profiling Considerations . . . . . . . . . . . . 44 + 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 45 + 15.1. CBOR Tag Assignment . . . . . . . . . . . . . . . . . . 45 + 15.2. COSE Header Parameters Registry . . . . . . . . . . . . 45 + 15.3. COSE Header Algorithm Parameters Registry . . . . . . . 45 + 15.4. COSE Key Common Parameters Registry . . . . . . . . . . 46 + 15.5. Media Type Registrations . . . . . . . . . . . . . . . . 46 + 15.5.1. COSE Security Message . . . . . . . . . . . . . . . 46 + 15.5.2. COSE Key Media Type . . . . . . . . . . . . . . . . 47 + 15.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 49 + 15.7. Expert Review Instructions . . . . . . . . . . . . . . . 49 + 16. Security Considerations . . . . . . . . . . . . . . . . . . . 50 + 17. Implementation Status . . . . . . . . . . . . . . . . . . . . 52 + 17.1. Author's Versions . . . . . . . . . . . . . . . . . . . 52 + 17.2. COSE Testing Library . . . . . . . . . . . . . . . . . . 53 + 18. References . . . . . . . . . . . . . . . . . . . . . . . . . 54 + 18.1. Normative References . . . . . . . . . . . . . . . . . . 54 + 18.2. Informative References . . . . . . . . . . . . . . . . . 55 Appendix A. Guidelines for External Data Authentication of - Algorithms . . . . . . . . . . . . . . . . . . . . . 55 - A.1. Algorithm Identification . . . . . . . . . . . . . . . . 55 - A.2. Counter Signature without Headers . . . . . . . . . . . . 58 - Appendix B. Two Layers of Recipient Information . . . . . . . . 59 - Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 60 - C.1. Examples of Signed Messages . . . . . . . . . . . . . . . 61 - C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 61 - C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 62 - C.1.3. Counter Signature . . . . . . . . . . . . . . . . . . 63 - C.1.4. Signature with Criticality . . . . . . . . . . . . . 64 - C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 65 - C.2.1. Single ECDSA Signature . . . . . . . . . . . . . . . 65 - C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 66 - C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 66 - C.3.2. Direct Plus Key Derivation . . . . . . . . . . . . . 67 - C.3.3. Counter Signature on Encrypted Content . . . . . . . 68 - C.3.4. Encrypted Content with External Data . . . . . . . . 70 - C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 70 - C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 70 - C.4.2. Encrypted Message with a Partial IV . . . . . . . . . 71 - C.5. Examples of MACed Messages . . . . . . . . . . . . . . . 71 - C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 71 - C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 72 - C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 73 - C.5.4. Multi-Recipient MACed Message . . . . . . . . . . . . 74 - - C.6. Examples of MAC0 Messages . . . . . . . . . . . . . . . . 75 - C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 75 - C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 76 - C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 76 - C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 77 - Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 79 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 80 + Algorithms . . . . . . . . . . . . . . . . . . . . . 57 + A.1. Algorithm Identification . . . . . . . . . . . . . . . . 57 + A.2. Counter Signature without Headers . . . . . . . . . . . . 60 + Appendix B. Two Layers of Recipient Information . . . . . . . . 61 + Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 63 + C.1. Examples of Signed Messages . . . . . . . . . . . . . . . 64 + C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 64 + C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 65 + C.1.3. Counter Signature . . . . . . . . . . . . . . . . . . 66 + C.1.4. 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. Counter Signature on Encrypted Content . . . . . . . 71 + C.3.4. Encrypted Content with External Data . . . . . . . . 73 + 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)" [RFC7049]. CBOR extended the data model of the JavaScript Object Notation (JSON) [RFC8259] 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 data structures. CBOR was designed specifically to be both small in terms of messages transport and implementation size and be a schema-free decoder. A need exists to provide message security services for IoT, and using CBOR as the message-encoding format makes sense. The JOSE working group produced a set of documents [RFC7515] [RFC7516] [RFC7517] [RFC7518] using JSON that specified how to process encryption, signatures, and Message Authentication Code (MAC) operations and how to encode keys using JSON. This document along - with [I-D.schaad-cose-rfc8152bis-algs] defines the CBOR Object - Signing and Encryption (COSE) standard, which does the same thing for - the CBOR encoding format. While there is a strong attempt to keep - the flavor of the original JSON Object Signing and Encryption (JOSE) + with [I-D.ietf-cose-rfc8152bis-algs] defines the CBOR Object Signing + and Encryption (COSE) standard, which does the same thing for the + CBOR encoding format. While there is a strong attempt to keep the + flavor of the original JSON Object Signing and Encryption (JOSE) documents, two considerations are taken into account: o CBOR has capabilities that are not present in JSON and are appropriate to use. One example of this is the fact that CBOR has a method of encoding binary directly without first converting it into a base64-encoded string. o COSE is not a direct copy of the JOSE specification. In the process of creating COSE, decisions that were made for JOSE were re-examined. In many cases, different results were decided on as @@ -195,21 +198,21 @@ keys. o The procedures used to compute build the inputs to the cryptographic functions required for each of the structures. o A starting set of attributes that apply to the different security objects. This document does not contain the rules and procedures for using specific cryptographic algorithms. Details on specific algorithms - can be found in [I-D.schaad-cose-rfc8152bis-algs] and [RFC8230]. + can be found in [I-D.ietf-cose-rfc8152bis-algs] and [RFC8230]. Details for additional algorithms are expected to be defined in future documents. One feature that is present in CMS [RFC5652] 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 document as different protocols will want to include a different set of fields as part of the structure. While an algorithm identifier and the digesst 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 @@ -236,29 +239,33 @@ o Use binary encodings for binary data rather than base64url encodings. o Combine the authentication tag for encryption algorithms with the ciphertext. o The set of cryptographic algorithms has been expanded in some directions and trimmed in others. -1.2. Requirements Terminology +1.2. Changes from RFC8152 + + TBD + +1.3. Requirements Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. -1.3. CBOR Grammar +1.4. CBOR Grammar There was not a standard CBOR grammar available when COSE was originally written. For that reason the CBOR structures defined here are described in prose. Since that time CBOR Data Definition Language (CDDL) [I-D.ietf-cbor-cddl] has been published as an RFC. The CBOR grammar presented in this document is compatible with CDDL. The document was developed by first working on the grammar and then developing the prose to go with it. An artifact of this is that the prose was written using the primitive type strings defined by CBOR @@ -310,21 +317,21 @@ ; This is defined to make the tool quieter: Internal_Types = Sig_structure / Enc_structure / MAC_structure / COSE_KDF_Context The non-terminal Internal_Types is defined for dealing with the automated validation tools used during the writing of this document. It references those non-terminals that are used for security computations but are not emitted for transport. -1.4. CBOR-Related Terminology +1.5. CBOR-Related Terminology In JSON, maps are called objects and only have one kind of map key: a string. In COSE, we use strings, negative integers, and unsigned integers as map keys. The integers are used for compactness of encoding and easy comparison. The inclusion of 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. @@ -332,21 +339,21 @@ integer 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.5. Document Terminology +1.6. Document Terminology In this document, we use the following terminology: Byte is a synonym for octet. Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use in constrained systems. It is defined in [RFC7252]. Authenticated Encryption (AE) [RFC5116] algorithms are those encryption algorithms that provide an authentication check of the @@ -475,21 +482,21 @@ but are used for holding information about content, algorithms, keys, or evaluation hints for the processing of the layer. These two buckets are available for use in all of the structures except for keys. While these buckets are present, they may not all be usable in all instances. For example, while the protected bucket is defined as part of the recipient structure, some of the algorithms used for recipient structures do not provide for authenticated data. If this is the case, the protected bucket is left empty. Both buckets are implemented as CBOR maps. The map key is a 'label' - (Section 1.4). The value portion is dependent on the definition for + (Section 1.5). The value portion is dependent on the definition for the label. Both maps use the same set of label/value pairs. The integer and string values for labels have been divided into several sections including a standard range, a private range, and a range that is dependent on the algorithm selected. The defined labels can be found in the "COSE Header Parameters" IANA registry (Section 15.2). Two buckets are provided for each layer: protected: Contains parameters about the current layer that are @@ -563,21 +570,21 @@ This section defines a set of common header parameters. A summary of these parameters can be found in Table 3. This table should be consulted to determine the value of label and the type of the value. The set of header parameters defined in this section are: alg: This parameter is used to indicate the algorithm used for the security processing. This parameter MUST be authenticated where the ability to do so exists. This support is provided by AEAD - algorithms or construction (COSE_Sign, COSE_Sign0, COSE_Mac, and + algorithms or construction (COSE_Sign, COSE_Sign1, COSE_Mac, and COSE_Mac0). This authentication can be done either by placing the parameter in the protected header bucket or as part of the externally supplied data. The value is taken from the "COSE Algorithms" registry (see [COSE.Algorithms]). crit: The parameter is used to indicate which protected header labels an application that is processing a message is required to understand. Parameters defined in this document do not need to be included as they should be understood by all implementations. When present, this parameter MUST be placed in the protected @@ -877,21 +884,21 @@ This document describes the process for using a byte array of externally supplied authenticated data; the method of constructing the byte array is a function of the application. Applications that use this feature need to define how the externally supplied authenticated data is to be constructed. Such a construction needs to take into account the following issues: o If multiple items are included, applications need to ensure that the same byte string cannot produced if there are different - inputs. This could occur by appending the strings 'AB' and 'CDE' + inputs. This would occur by appending the strings 'AB' and 'CDE' or by appending the strings 'ABC' and 'DE'. This is usually addressed by making fields a fixed width and/or encoding the length of the field as part of the output. Using options from CoAP [RFC7252] as an example, these fields use a TLV structure so they can be concatenated without any problems. o If multiple items are included, an order for the items needs to be defined. Using options from CoAP as an example, an application could state that the fields are to be ordered by the option number. @@ -1230,22 +1237,21 @@ and key at the current layer. Examples are key transport keys (Section 12.3), key wrap keys (Section 12.2), or pre-shared secrets. Direct Encryption and Direct Key Agreement: The key is determined by the key and algorithm in the recipient structure. The encryption algorithm and size of the key to be used are inputs into the KDF used for the recipient. (For direct, the KDF can be thought of as the identity operation.) Examples of these algorithms are found in Sections !!! DIRECT- - KDF !!! and !!! ECDH !!! of - [I-D.schaad-cose-rfc8152bis-algs]. + KDF !!! and !!! ECDH !!! of [I-D.ietf-cose-rfc8152bis-algs]. Other: The key is randomly or pseudorandomly generated. 4. Call the encryption algorithm with K (the encryption key), P (the plaintext), and AAD. Place the returned ciphertext into the 'ciphertext' field of the structure. 5. For recipients of the message, recursively perform the encryption algorithm for that recipient, using K (the encryption key) as the plaintext. @@ -1550,21 +1556,21 @@ } COSE_KeySet = [+COSE_Key] 7.1. COSE Key Common Parameters This document defines a set of common parameters for a COSE Key object. Table 4 provides a summary of the parameters defined in this section. There are also parameters that are defined for specific key types. Key-type-specific parameters can be found in - [I-D.schaad-cose-rfc8152bis-algs]. + [I-D.ietf-cose-rfc8152bis-algs]. +---------+-------+----------------+------------+-------------------+ | Name | Label | CBOR Type | Value | Description | | | | | Registry | | +---------+-------+----------------+------------+-------------------+ | kty | 1 | tstr / int | COSE Key | Identification of | | | | | Types | the key type | | | | | | | | kid | 2 | bstr | | Key | | | | | | identification | @@ -1781,22 +1787,22 @@ o Secrets that are not random: This is the type of secret that people generate for things like passwords. General KDFs work well with the first type of secret, can do reasonably well with the second type of secret, and generally do poorly with the last type of secret. Functions like PBES2 [RFC8018] need to be used for non-random secrets. The same KDF can be set up to deal with the first two types of secrets in a different way. The KDF defined in !!! HDKF !!! (section - XXXX of [I-D.schaad-cose-rfc8152bis-algs]) is such a function. This - is reflected in the set of algorithms defined around the HMAC-based + XXXX of [I-D.ietf-cose-rfc8152bis-algs]) is such a function. This is + reflected in the set of algorithms defined around the HMAC-based Extract-and-Expand Key Derivation Function (HKDF). When using KDFs, one component that is included is context information. Context information is used to allow for different keying information to be derived from the same secret. The use of context-based keying material is considered to be a good security practice. 12. Content Key Distribution Methods @@ -1858,22 +1864,22 @@ o At a minimum, the 'unprotected' field MUST contain the 'alg' parameter and SHOULD contain a parameter identifying the shared secret. 12.3. Key Transport Key transport mode is also called key encryption mode in some standards. Key transport mode differs from key wrap mode in that it uses an asymmetric encryption algorithm rather than a symmetric - encryption algorithm to protect the key. This document does not - define any key transport mode algorithms. + encryption algorithm to protect the key. A set of key transport + algorithms are defined in [RFC8230]. When using a key transport algorithm, the COSE_Encrypt structure for the recipient is organized as follows: o The 'protected' field MUST be absent. o The plaintext to be encrypted is the key from the next layer down (usually the content layer). o At a minimum, the 'unprotected' field MUST contain the 'alg' @@ -2367,23 +2373,99 @@ analysis of encrypted messages based on the length of the message. This specification does not provide for a uniform method of providing padding as part of the message structure. An observer can distinguish between two different strings (for example, 'YES' and 'NO') based on the length for all of the content encryption algorithms that are defined in this document. This means that it is up to the applications to document how content padding is to be done in order to prevent or discourage such analysis. (For example, the strings could be defined as 'YES' and 'NO '.) -17. References +17. Implementation Status -17.1. Normative References + This section records the status of known implementations of the + protocol defined by this specification at the time of posting of this + Internet-Draft, and is based on a proposal described in [RFC7942]. + The description of implementations in this section is intended to + assist the IETF in its decision processes in progressing drafts to + RFCs. Please note that the listing of any individual implementation + here does not imply endorsement by the IETF. Furthermore, no effort + has been spent to verify the information presented here that was + supplied by IETF contributors. This is not intended as, and must not + be construed to be, a catalog of available implementations or their + features. Readers are advised to note that other implementations may + exist. + + According to [RFC7942], "this will allow reviewers and working groups + to assign due consideration to documents that have the benefit of + running code, which may serve as evidence of valuable experimentation + and feedback that have made the implemented protocols more mature. + It is up to the individual working groups to use this information as + they see fit". + +17.1. Author's Versions + + There are three different implementations that have been created by + the author of the document both to create the examples that are + included in the document and to validate the structures and + methodology used in the design of COSE. + + Implementation Location: https://github.com/cose-wg + + Primary Maintainer: Jim Schaad + + Languages: There are three different languages that are currently + supported: Java, C# and C. + + Cryptography: The Java and C# libraries use Bouncy Castle to + provide the required cryptography. The C version uses OPENSSL + Version 1.0 for the cryptography. + + Coverage: The libraries currently do not have full support for + counter signatures of either variety. They do have support to + allow for implicit algorithm support as they allow for the + application to set attributes that are not to be sent in the + message. + + Testing: All of the examples in the example library are generated + by the C# library and then validated using the Java and C + libraries. All three libraries have tests to allow for the + creating of the same messages that are in the example library + followed by validating them. These are not compared against the + example library. The Java and C# libraries have unit testing + included. Not all of the MUST statements in the document have + been implemented as part of the libraries. One such statement is + the requirement that unique labels be present. + + Licensing: Revised BSD License + +17.2. COSE Testing Library + + Implementation Location: https://github.com/cose-wg/Examples + + Primary Maintainer: Jim Schaad + + Description: A set of tests for the COSE library is provided as + part of the implementation effort. Both success and fail tests + have been provided. All of the examples in this document are part + of this example set. + + Coverage: An attempt has been made to have test cases for every + message type and algorithm in the document. Currently examples + dealing with counter signatures, EdDSA, and ECDH with Curve24459 + and Goldilocks are missing. + + Licensing: Public Domain + +18. References + +18.1. Normative References [COAP.Formats] IANA, "CoAP Content-Formats", . [COSE.Algorithms] IANA, "COSE Algorithms", . @@ -2397,50 +2479,50 @@ IANA, "COSE Key Types", . [DSS] National Institute of Standards and Technology, "Digital Signature Standard (DSS)", FIPS PUB 186-4, DOI 10.6028/NIST.FIPS.186-4, July 2013, . - [I-D.schaad-cose-rfc8152bis-algs] - Schaad, J., "CBOR Algoritms for Object Signing and - Encryption (COSE)", draft-schaad-cose-rfc8152bis-algs-01 - (work in progress), December 2018. + [I-D.ietf-cose-rfc8152bis-algs] + Schaad, J., "CBOR Algorithms for Object Signing and + Encryption (COSE)", draft-ietf-cose-rfc8152bis-algs-00 + (work in progress), January 2019. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, October 2013, . [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital Signature Algorithm (EdDSA)", RFC 8032, DOI 10.17487/RFC8032, January 2017, - . + . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . -17.2. Informative References +18.2. Informative References [I-D.ietf-cbor-cddl] Birkholz, H., Vigano, C., and C. Bormann, "Concise data definition language (CDDL): a notational convention to express CBOR and JSON data structures", draft-ietf-cbor- - cddl-06 (work in progress), November 2018. + cddl-07 (work in progress), February 2019. [I-D.ietf-core-object-security] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, "Object Security for Constrained RESTful Environments (OSCORE)", draft-ietf-core-object-security-15 (work in progress), August 2018. [PVSig] Brown, D. and D. Johnson, "Formal Security Proofs for a Signature Scheme with Partial Message Recovery", DOI 10.1007/3-540-45353-9_11, LNCS Volume 2020, June 2000. @@ -2501,20 +2583,25 @@ . [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015, . [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, DOI 10.17487/RFC7518, May 2015, . + [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running + Code: The Implementation Status Section", BCP 205, + RFC 7942, DOI 10.17487/RFC7942, July 2016, + . + [RFC8018] Moriarty, K., Ed., Kaliski, B., and A. Rusch, "PKCS #5: Password-Based Cryptography Specification Version 2.1", RFC 8018, DOI 10.17487/RFC8018, January 2017, . [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, .