draft-ietf-cose-rfc8152bis-struct-01.txt   draft-ietf-cose-rfc8152bis-struct-02.txt 
COSE Working Group J. Schaad COSE Working Group J. Schaad
Internet-Draft August Cellars Internet-Draft August Cellars
Obsoletes: 8152 (if approved) February 14, 2019 Obsoletes: 8152 (if approved) March 11, 2019
Intended status: Standards Track Intended status: Standards Track
Expires: August 18, 2019 Expires: September 12, 2019
CBOR Object Signing and Encryption (COSE) - Structures and Process CBOR CBOR Object Signing and Encryption (COSE): Structures and Process
draft-ietf-cose-rfc8152bis-struct-01 draft-ietf-cose-rfc8152bis-struct-02
Abstract Abstract
Concise Binary Object Representation (CBOR) is a data format designed Concise Binary Object Representation (CBOR) is a data format designed
for small code size and small message size. There is a need for the 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. ability to have basic security services defined for this data format.
This document defines the CBOR Object Signing and Encryption (COSE) This document defines the CBOR Object Signing and Encryption (COSE)
protocol. This specification describes how to create and process protocol. This specification describes how to create and process
signatures, message authentication codes, and encryption using CBOR signatures, message authentication codes, and encryption using CBOR
for serialization. This specification additionally describes how to for serialization. This specification additionally describes how to
skipping to change at page 1, line 49 skipping to change at page 1, line 49
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." 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 Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 3, line 26 skipping to change at page 3, line 26
15.3. COSE Header Algorithm Parameters Registry . . . . . . . 45 15.3. COSE Header Algorithm Parameters Registry . . . . . . . 45
15.4. COSE Key Common Parameters Registry . . . . . . . . . . 46 15.4. COSE Key Common Parameters Registry . . . . . . . . . . 46
15.5. Media Type Registrations . . . . . . . . . . . . . . . . 46 15.5. Media Type Registrations . . . . . . . . . . . . . . . . 46
15.5.1. COSE Security Message . . . . . . . . . . . . . . . 46 15.5.1. COSE Security Message . . . . . . . . . . . . . . . 46
15.5.2. COSE Key Media Type . . . . . . . . . . . . . . . . 47 15.5.2. COSE Key Media Type . . . . . . . . . . . . . . . . 47
15.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 49 15.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 49
15.7. Expert Review Instructions . . . . . . . . . . . . . . . 49 15.7. Expert Review Instructions . . . . . . . . . . . . . . . 49
16. Security Considerations . . . . . . . . . . . . . . . . . . . 50 16. Security Considerations . . . . . . . . . . . . . . . . . . . 50
17. Implementation Status . . . . . . . . . . . . . . . . . . . . 52 17. Implementation Status . . . . . . . . . . . . . . . . . . . . 52
17.1. Author's Versions . . . . . . . . . . . . . . . . . . . 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. References . . . . . . . . . . . . . . . . . . . . . . . . . 54
18.1. Normative 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 Appendix A. Guidelines for External Data Authentication of
Algorithms . . . . . . . . . . . . . . . . . . . . . 57 Algorithms . . . . . . . . . . . . . . . . . . . . . 58
A.1. Algorithm Identification . . . . . . . . . . . . . . . . 57 A.1. Algorithm Identification . . . . . . . . . . . . . . . . 58
A.2. Counter Signature without Headers . . . . . . . . . . . . 60 A.2. Counter Signature without Headers . . . . . . . . . . . . 61
Appendix B. Two Layers of Recipient Information . . . . . . . . 61 Appendix B. Two Layers of Recipient Information . . . . . . . . 62
Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 63 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 64
C.1. Examples of Signed Messages . . . . . . . . . . . . . . . 64 C.1. Examples of Signed Messages . . . . . . . . . . . . . . . 65
C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 64 C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 65
C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 65 C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 66
C.1.3. Counter Signature . . . . . . . . . . . . . . . . . . 66 C.1.3. Counter Signature . . . . . . . . . . . . . . . . . . 67
C.1.4. Signature with Criticality . . . . . . . . . . . . . 67 C.1.4. Signature with Criticality . . . . . . . . . . . . . 68
C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 68 C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 69
C.2.1. Single ECDSA Signature . . . . . . . . . . . . . . . 68 C.2.1. Single ECDSA Signature . . . . . . . . . . . . . . . 69
C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 69 C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 70
C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 69 C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 70
C.3.2. Direct Plus Key Derivation . . . . . . . . . . . . . 70 C.3.2. Direct Plus Key Derivation . . . . . . . . . . . . . 71
C.3.3. Counter Signature on Encrypted Content . . . . . . . 71 C.3.3. Counter Signature on Encrypted Content . . . . . . . 72
C.3.4. Encrypted Content with External Data . . . . . . . . 73 C.3.4. Encrypted Content with External Data . . . . . . . . 74
C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 73 C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 74
C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 73 C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 74
C.4.2. Encrypted Message with a Partial IV . . . . . . . . . 74 C.4.2. Encrypted Message with a Partial IV . . . . . . . . . 75
C.5. Examples of MACed Messages . . . . . . . . . . . . . . . 74 C.5. Examples of MACed Messages . . . . . . . . . . . . . . . 75
C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 74 C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 75
C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 75 C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 76
C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 76 C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 77
C.5.4. Multi-Recipient MACed Message . . . . . . . . . . . . 77 C.5.4. Multi-Recipient MACed Message . . . . . . . . . . . . 78
C.6. Examples of MAC0 Messages . . . . . . . . . . . . . . . . 78 C.6. Examples of MAC0 Messages . . . . . . . . . . . . . . . . 79
C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 78 C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 79
C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 79 C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 80
C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 79 C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 80
C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 80 C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 81
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 82 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 83
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 83 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 84
1. Introduction 1. Introduction
There has been an increased focus on small, constrained devices that There has been an increased focus on small, constrained devices that
make up the Internet of Things (IoT). One of the standards that has make up the Internet of Things (IoT). One of the standards that has
come out of this process is "Concise Binary Object Representation come out of this process is "Concise Binary Object Representation
(CBOR)" [RFC7049]. CBOR extended the data model of the JavaScript (CBOR)" [RFC7049]. CBOR extended the data model of the JavaScript
Object Notation (JSON) [RFC8259] by allowing for binary data, among Object Notation (JSON) [RFC8259] by allowing for binary data, among
other changes. CBOR has been adopted by several of the IETF working other changes. CBOR has been adopted by several of the IETF working
groups dealing with the IoT world as their encoding of data groups dealing with the IoT world as their encoding of data
skipping to change at page 6, line 13 skipping to change at page 6, line 16
encodings. encodings.
o Combine the authentication tag for encryption algorithms with the o Combine the authentication tag for encryption algorithms with the
ciphertext. ciphertext.
o The set of cryptographic algorithms has been expanded in some o The set of cryptographic algorithms has been expanded in some
directions and trimmed in others. directions and trimmed in others.
1.2. Changes from RFC8152 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 1.3. Requirements Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
1.4. CBOR Grammar 1.4. CBOR Grammar
skipping to change at page 21, line 10 skipping to change at page 21, line 10
the same on both sides. Using options from CoAP might give a the same on both sides. Using options from CoAP might give a
problem if the same relative numbering is kept. An intermediate problem if the same relative numbering is kept. An intermediate
node could insert or remove an option, changing how the relative node could insert or remove an option, changing how the relative
number is done. An application would need to specify that the number is done. An application would need to specify that the
relative number must be re-encoded to be relative only to the relative number must be re-encoded to be relative only to the
options that are in the external data. options that are in the external data.
4.4. Signing and Verification Process 4.4. Signing and Verification Process
In order to create a signature, a well-defined byte string is needed. 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 and verification process takes in the body information (COSE_Sign or
COSE_Sign1), the signer information (COSE_Signature), and the COSE_Sign1), the signer information (COSE_Signature), and the
application data (external source). A Sig_structure is a CBOR array. 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 1. A text string identifying the context of the signature. The
context string is: context string is:
"Signature" for signatures using the COSE_Signature structure. "Signature" for signatures using the COSE_Signature structure.
"Signature1" for signatures using the COSE_Sign1 structure. "Signature1" for signatures using the COSE_Sign1 structure.
"CounterSignature" for signatures used as counter signature "CounterSignature" for signatures used as counter signature
attributes. attributes.
skipping to change at page 53, line 16 skipping to change at page 53, line 16
Primary Maintainer: Jim Schaad Primary Maintainer: Jim Schaad
Languages: There are three different languages that are currently Languages: There are three different languages that are currently
supported: Java, C# and C. supported: Java, C# and C.
Cryptography: The Java and C# libraries use Bouncy Castle to Cryptography: The Java and C# libraries use Bouncy Castle to
provide the required cryptography. The C version uses OPENSSL provide the required cryptography. The C version uses OPENSSL
Version 1.0 for the cryptography. Version 1.0 for the cryptography.
Coverage: The libraries currently do not have full support for Coverage: The C version currently does not have full countersign
counter signatures of either variety. They do have support to support. THe other two versions do. They do have support to
allow for implicit algorithm support as they allow for the allow for implicit algorithm support as they allow for the
application to set attributes that are not to be sent in the application to set attributes that are not to be sent in the
message. message.
Testing: All of the examples in the example library are generated Testing: All of the examples in the example library are generated
by the C# library and then validated using the Java and C by the C# library and then validated using the Java and C
libraries. All three libraries have tests to allow for the libraries. All three libraries have tests to allow for the
creating of the same messages that are in the example library creating of the same messages that are in the example library
followed by validating them. These are not compared against the followed by validating them. These are not compared against the
example library. The Java and C# libraries have unit testing example library. The Java and C# libraries have unit testing
included. Not all of the MUST statements in the document have included. Not all of the MUST statements in the document have
been implemented as part of the libraries. One such statement is been implemented as part of the libraries. One such statement is
the requirement that unique labels be present. the requirement that unique labels be present.
Licensing: Revised BSD License 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 Implementation Location: https://github.com/cose-wg/Examples
Primary Maintainer: Jim Schaad Primary Maintainer: Jim Schaad
Description: A set of tests for the COSE library is provided as Description: A set of tests for the COSE library is provided as
part of the implementation effort. Both success and fail tests part of the implementation effort. Both success and fail tests
have been provided. All of the examples in this document are part have been provided. All of the examples in this document are part
of this example set. of this example set.
Coverage: An attempt has been made to have test cases for every Coverage: An attempt has been made to have test cases for every
message type and algorithm in the document. Currently examples message type and algorithm in the document. Currently examples
dealing with counter signatures, EdDSA, and ECDH with Curve24459 dealing with counter signatures, and ECDH with Curve24459 and
and Goldilocks are missing. Goldilocks are missing.
Licensing: Public Domain Licensing: Public Domain
18. References 18. References
18.1. Normative References 18.1. Normative References
[COAP.Formats] [COAP.Formats]
IANA, "CoAP Content-Formats", IANA, "CoAP Content-Formats",
<https://www.iana.org/assignments/core-parameters/ <https://www.iana.org/assignments/core-parameters/
skipping to change at page 54, line 37 skipping to change at page 55, line 28
cose.xhtml#algorithms>. cose.xhtml#algorithms>.
[DSS] National Institute of Standards and Technology, "Digital [DSS] National Institute of Standards and Technology, "Digital
Signature Standard (DSS)", FIPS PUB 186-4, Signature Standard (DSS)", FIPS PUB 186-4,
DOI 10.6028/NIST.FIPS.186-4, July 2013, DOI 10.6028/NIST.FIPS.186-4, July 2013,
<http://nvlpubs.nist.gov/nistpubs/FIPS/ <http://nvlpubs.nist.gov/nistpubs/FIPS/
NIST.FIPS.186-4.pdf>. NIST.FIPS.186-4.pdf>.
[I-D.ietf-cose-rfc8152bis-algs] [I-D.ietf-cose-rfc8152bis-algs]
Schaad, J., "CBOR Algorithms for Object Signing and Schaad, J., "CBOR Algorithms for Object Signing and
Encryption (COSE)", draft-ietf-cose-rfc8152bis-algs-00 Encryption (COSE)", draft-ietf-cose-rfc8152bis-algs-01
(work in progress), January 2019. (work in progress), February 2019.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
October 2013, <https://www.rfc-editor.org/info/rfc7049>. October 2013, <https://www.rfc-editor.org/info/rfc7049>.
 End of changes. 14 change blocks. 
49 lines changed or deleted 89 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/