--- 1/draft-ietf-cose-rfc8152bis-struct-01.txt 2019-03-11 12:15:21.342618968 -0700 +++ 2/draft-ietf-cose-rfc8152bis-struct-02.txt 2019-03-11 12:15:21.514623177 -0700 @@ -1,19 +1,19 @@ COSE Working Group J. Schaad Internet-Draft August Cellars -Obsoletes: 8152 (if approved) February 14, 2019 +Obsoletes: 8152 (if approved) March 11, 2019 Intended status: Standards Track -Expires: August 18, 2019 +Expires: September 12, 2019 - CBOR Object Signing and Encryption (COSE) - Structures and Process - draft-ietf-cose-rfc8152bis-struct-01 + CBOR CBOR Object Signing and Encryption (COSE): Structures and Process + draft-ietf-cose-rfc8152bis-struct-02 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 @@ -38,21 +38,21 @@ 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 August 18, 2019. + This Internet-Draft will expire on September 12, 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 @@ -110,57 +110,59 @@ 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 + 17.2. Java Script Version . . . . . . . . . . . . . . . . . . 53 + 17.3. Python Version . . . . . . . . . . . . . . . . . . . . . 54 + 17.4. COSE Testing Library . . . . . . . . . . . . . . . . . . 54 18. References . . . . . . . . . . . . . . . . . . . . . . . . . 54 18.1. Normative References . . . . . . . . . . . . . . . . . . 54 - 18.2. Informative References . . . . . . . . . . . . . . . . . 55 + 18.2. Informative References . . . . . . . . . . . . . . . . . 56 Appendix A. Guidelines for External Data Authentication of - 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 + Algorithms . . . . . . . . . . . . . . . . . . . . . 58 + A.1. Algorithm Identification . . . . . . . . . . . . . . . . 58 + A.2. Counter Signature without Headers . . . . . . . . . . . . 61 + Appendix B. Two Layers of Recipient Information . . . . . . . . 62 + Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 64 + C.1. Examples of Signed Messages . . . . . . . . . . . . . . . 65 + C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 65 + C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 66 + C.1.3. Counter Signature . . . . . . . . . . . . . . . . . . 67 + C.1.4. 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. Counter Signature on Encrypted Content . . . . . . . 72 + C.3.4. Encrypted Content with External Data . . . . . . . . 74 + C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 74 + C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 74 + C.4.2. Encrypted Message with a Partial IV . . . . . . . . . 75 + C.5. Examples of MACed Messages . . . . . . . . . . . . . . . 75 + C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 75 + C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 76 + C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 77 + C.5.4. Multi-Recipient MACed Message . . . . . . . . . . . . 78 + C.6. Examples of MAC0 Messages . . . . . . . . . . . . . . . . 79 + C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 79 + C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 80 + C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 80 + C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 81 + Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 83 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 84 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 @@ -241,21 +243,25 @@ 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. Changes from RFC8152 - TBD + o Split the orignal document into this document and + [I-D.ietf-cose-rfc8152bis-algs]. + + o Add some text describing why there is no digest structure defined + by COSE. 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.4. CBOR Grammar @@ -907,25 +913,25 @@ the same on both sides. Using options from CoAP might give a problem if the same relative numbering is kept. An intermediate node could insert or remove an option, changing how the relative number is done. An application would need to specify that the relative number must be re-encoded to be relative only to the options that are in the external data. 4.4. Signing and Verification Process In order to create a signature, a well-defined byte string is needed. - The Sig_struture is used to create the canonical form. This signing + The Sig_structure is used to create the canonical form. This signing and verification process takes in the body information (COSE_Sign or COSE_Sign1), the signer information (COSE_Signature), and the application data (external source). A Sig_structure is a CBOR array. - The fields of the Sig_struture in order are: + The fields of the Sig_structure in order are: 1. A text string identifying the context of the signature. The context string is: "Signature" for signatures using the COSE_Signature structure. "Signature1" for signatures using the COSE_Sign1 structure. "CounterSignature" for signatures used as counter signature attributes. @@ -2413,53 +2419,87 @@ 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 + Coverage: The C version currently does not have full countersign + support. THe other two versions do. 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 +17.2. Java Script Version + + Implementation Location: https://github.com/erdtman/cose-js + + Primary Maintainer: Samuel Erdtman + + Languages: JavaScript + + Cryptography: TBD + + Coverage: Full Encrypt, Signature and MAC objects are supported. + + Testing: Basic testing against the common example library. + + Licensing: Apache License 2.0 + +17.3. Python Version + + Implementation Location: https://github.com/TimothyClaeys/COSE- + PYTHON + + Primary Maintainer: Timothy Claeys + + Languages: Python + + Cryptography: pyecdsak, crypto python libraries + + Coverage: TBD + + Testing: Basic testing plus running against the common example + library. + + Licensing: BSD 3-Clause License + +17.4. 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. + dealing with counter signatures, and ECDH with Curve24459 and + Goldilocks are missing. Licensing: Public Domain 18. References 18.1. Normative References [COAP.Formats] IANA, "CoAP Content-Formats", . [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.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. + Encryption (COSE)", draft-ietf-cose-rfc8152bis-algs-01 + (work in progress), February 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, .