draft-ietf-cose-rfc8152bis-struct-00.txt   draft-ietf-cose-rfc8152bis-struct-01.txt 
COSE Working Group J. Schaad COSE Working Group J. Schaad
Internet-Draft August Cellars Internet-Draft August Cellars
Obsoletes: 8152 (if approved) January 21, 2019 Obsoletes: 8152 (if approved) February 14, 2019
Intended status: Standards Track Intended status: Standards Track
Expires: July 25, 2019 Expires: August 18, 2019
CBOR Object Signing and Encryption (COSE) - Structures and Process CBOR Object Signing and Encryption (COSE) - Structures and Process
draft-ietf-cose-rfc8152bis-struct-00 draft-ietf-cose-rfc8152bis-struct-01
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
represent cryptographic keys using CBOR. 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. RFC8152.
Contributing to this document Contributing to this document
The source for this draft is being maintained in GitHub. Suggested The source for this draft is being maintained in GitHub. Suggested
changes should be submitted as pull requests at <https://github.com/ changes should be submitted as pull requests at <https://github.com/
cose-wg/cose-rfc8152bis>. Instructions are on that page as well. cose-wg/cose-rfc8152bis>. Instructions are on that page as well.
Editorial changes can be managed in GitHub, but any substantial Editorial changes can be managed in GitHub, but any substantial
issues need to be discussed on the COSE mailing list. issues need to be discussed on the COSE mailing list.
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 July 25, 2019. This Internet-Draft will expire on August 18, 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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Design Changes from JOSE . . . . . . . . . . . . . . . . 5 1.1. Design Changes from JOSE . . . . . . . . . . . . . . . . 5
1.2. Requirements Terminology . . . . . . . . . . . . . . . . 6 1.2. Changes from RFC8152 . . . . . . . . . . . . . . . . . . 6
1.3. CBOR Grammar . . . . . . . . . . . . . . . . . . . . . . 6 1.3. Requirements Terminology . . . . . . . . . . . . . . . . 6
1.4. CBOR-Related Terminology . . . . . . . . . . . . . . . . 7 1.4. CBOR Grammar . . . . . . . . . . . . . . . . . . . . . . 6
1.5. Document Terminology . . . . . . . . . . . . . . . . . . 8 1.5. CBOR-Related Terminology . . . . . . . . . . . . . . . . 7
1.6. Document Terminology . . . . . . . . . . . . . . . . . . 8
2. Basic COSE Structure . . . . . . . . . . . . . . . . . . . . 8 2. Basic COSE Structure . . . . . . . . . . . . . . . . . . . . 8
3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 10 3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 11
3.1. Common COSE Headers Parameters . . . . . . . . . . . . . 12 3.1. Common COSE Headers Parameters . . . . . . . . . . . . . 13
4. Signing Objects . . . . . . . . . . . . . . . . . . . . . . . 16 4. Signing Objects . . . . . . . . . . . . . . . . . . . . . . . 17
4.1. Signing with One or More Signers . . . . . . . . . . . . 16 4.1. Signing with One or More Signers . . . . . . . . . . . . 17
4.2. Signing with One Signer . . . . . . . . . . . . . . . . . 18 4.2. Signing with One Signer . . . . . . . . . . . . . . . . . 19
4.3. Externally Supplied Data . . . . . . . . . . . . . . . . 19 4.3. Externally Supplied Data . . . . . . . . . . . . . . . . 20
4.4. Signing and Verification Process . . . . . . . . . . . . 20 4.4. Signing and Verification Process . . . . . . . . . . . . 21
4.5. Computing Counter Signatures . . . . . . . . . . . . . . 21 4.5. Computing Counter Signatures . . . . . . . . . . . . . . 22
5. Encryption Objects . . . . . . . . . . . . . . . . . . . . . 22 5. Encryption Objects . . . . . . . . . . . . . . . . . . . . . 23
5.1. Enveloped COSE Structure . . . . . . . . . . . . . . . . 22 5.1. Enveloped COSE Structure . . . . . . . . . . . . . . . . 23
5.1.1. Content Key Distribution Methods . . . . . . . . . . 24 5.1.1. Content Key Distribution Methods . . . . . . . . . . 25
5.2. Single Recipient Encrypted . . . . . . . . . . . . . . . 24 5.2. Single Recipient Encrypted . . . . . . . . . . . . . . . 25
5.3. How to Encrypt and Decrypt for AEAD Algorithms . . . . . 25 5.3. How to Encrypt and Decrypt for AEAD Algorithms . . . . . 26
5.4. How to Encrypt and Decrypt for AE Algorithms . . . . . . 27 5.4. How to Encrypt and Decrypt for AE Algorithms . . . . . . 28
6. MAC Objects . . . . . . . . . . . . . . . . . . . . . . . . . 29 6. MAC Objects . . . . . . . . . . . . . . . . . . . . . . . . . 30
6.1. MACed Message with Recipients . . . . . . . . . . . . . . 29 6.1. MACed Message with Recipients . . . . . . . . . . . . . . 30
6.2. MACed Messages with Implicit Key . . . . . . . . . . . . 30 6.2. MACed Messages with Implicit Key . . . . . . . . . . . . 31
6.3. How to Compute and Verify a MAC . . . . . . . . . . . . . 31 6.3. How to Compute and Verify a MAC . . . . . . . . . . . . . 32
7. Key Objects . . . . . . . . . . . . . . . . . . . . . . . . . 32 7. Key Objects . . . . . . . . . . . . . . . . . . . . . . . . . 33
7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 33 7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 34
8. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 36 8. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 37
9. Message Authentication Code (MAC) Algorithms . . . . . . . . 37 9. Message Authentication Code (MAC) Algorithms . . . . . . . . 38
10. Content Encryption Algorithms . . . . . . . . . . . . . . . . 38 10. Content Encryption Algorithms . . . . . . . . . . . . . . . . 39
11. Key Derivation Functions (KDFs) . . . . . . . . . . . . . . . 38 11. Key Derivation Functions (KDFs) . . . . . . . . . . . . . . . 39
12. Content Key Distribution Methods . . . . . . . . . . . . . . 39 12. Content Key Distribution Methods . . . . . . . . . . . . . . 40
12.1. Direct Encryption . . . . . . . . . . . . . . . . . . . 39 12.1. Direct Encryption . . . . . . . . . . . . . . . . . . . 40
12.2. Key Wrap . . . . . . . . . . . . . . . . . . . . . . . . 40 12.2. Key Wrap . . . . . . . . . . . . . . . . . . . . . . . . 41
12.3. Key Transport . . . . . . . . . . . . . . . . . . . . . 40 12.3. Key Transport . . . . . . . . . . . . . . . . . . . . . 41
12.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 41 12.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 42
12.5. Key Agreement with Key Wrap . . . . . . . . . . . . . . 42 12.5. Key Agreement with Key Wrap . . . . . . . . . . . . . . 43
13. CBOR Encoder Restrictions . . . . . . . . . . . . . . . . . . 42 13. CBOR Encoder Restrictions . . . . . . . . . . . . . . . . . . 43
14. Application Profiling Considerations . . . . . . . . . . . . 43 14. Application Profiling Considerations . . . . . . . . . . . . 44
15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 45
15.1. CBOR Tag Assignment . . . . . . . . . . . . . . . . . . 44 15.1. CBOR Tag Assignment . . . . . . . . . . . . . . . . . . 45
15.2. COSE Header Parameters Registry . . . . . . . . . . . . 44 15.2. COSE Header Parameters Registry . . . . . . . . . . . . 45
15.3. COSE Header Algorithm Parameters Registry . . . . . . . 44 15.3. COSE Header Algorithm Parameters Registry . . . . . . . 45
15.4. COSE Key Common Parameters Registry . . . . . . . . . . 45 15.4. COSE Key Common Parameters Registry . . . . . . . . . . 46
15.5. Media Type Registrations . . . . . . . . . . . . . . . . 45 15.5. Media Type Registrations . . . . . . . . . . . . . . . . 46
15.5.1. COSE Security Message . . . . . . . . . . . . . . . 45 15.5.1. COSE Security Message . . . . . . . . . . . . . . . 46
15.5.2. COSE Key Media Type . . . . . . . . . . . . . . . . 46 15.5.2. COSE Key Media Type . . . . . . . . . . . . . . . . 47
15.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 48 15.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 49
15.7. Expert Review Instructions . . . . . . . . . . . . . . . 48 15.7. Expert Review Instructions . . . . . . . . . . . . . . . 49
16. Security Considerations . . . . . . . . . . . . . . . . . . . 49 16. Security Considerations . . . . . . . . . . . . . . . . . . . 50
17. References . . . . . . . . . . . . . . . . . . . . . . . . . 51 17. Implementation Status . . . . . . . . . . . . . . . . . . . . 52
17.1. Normative References . . . . . . . . . . . . . . . . . . 51 17.1. Author's Versions . . . . . . . . . . . . . . . . . . . 52
17.2. Informative References . . . . . . . . . . . . . . . . . 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 Appendix A. Guidelines for External Data Authentication of
Algorithms . . . . . . . . . . . . . . . . . . . . . 55 Algorithms . . . . . . . . . . . . . . . . . . . . . 57
A.1. Algorithm Identification . . . . . . . . . . . . . . . . 55 A.1. Algorithm Identification . . . . . . . . . . . . . . . . 57
A.2. Counter Signature without Headers . . . . . . . . . . . . 58 A.2. Counter Signature without Headers . . . . . . . . . . . . 60
Appendix B. Two Layers of Recipient Information . . . . . . . . 59 Appendix B. Two Layers of Recipient Information . . . . . . . . 61
Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 60 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 63
C.1. Examples of Signed Messages . . . . . . . . . . . . . . . 61 C.1. Examples of Signed Messages . . . . . . . . . . . . . . . 64
C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 61 C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 64
C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 62 C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 65
C.1.3. Counter Signature . . . . . . . . . . . . . . . . . . 63 C.1.3. Counter Signature . . . . . . . . . . . . . . . . . . 66
C.1.4. Signature with Criticality . . . . . . . . . . . . . 64 C.1.4. Signature with Criticality . . . . . . . . . . . . . 67
C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 65 C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 68
C.2.1. Single ECDSA Signature . . . . . . . . . . . . . . . 65 C.2.1. Single ECDSA Signature . . . . . . . . . . . . . . . 68
C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 66 C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 69
C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 66 C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 69
C.3.2. Direct Plus Key Derivation . . . . . . . . . . . . . 67 C.3.2. Direct Plus Key Derivation . . . . . . . . . . . . . 70
C.3.3. Counter Signature on Encrypted Content . . . . . . . 68 C.3.3. Counter Signature on Encrypted Content . . . . . . . 71
C.3.4. Encrypted Content with External Data . . . . . . . . 70 C.3.4. Encrypted Content with External Data . . . . . . . . 73
C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 70 C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 73
C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 70 C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 73
C.4.2. Encrypted Message with a Partial IV . . . . . . . . . 71 C.4.2. Encrypted Message with a Partial IV . . . . . . . . . 74
C.5. Examples of MACed Messages . . . . . . . . . . . . . . . 71 C.5. Examples of MACed Messages . . . . . . . . . . . . . . . 74
C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 71 C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 74
C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 72 C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 75
C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 73 C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 76
C.5.4. Multi-Recipient MACed Message . . . . . . . . . . . . 74 C.5.4. Multi-Recipient MACed Message . . . . . . . . . . . . 77
C.6. Examples of MAC0 Messages . . . . . . . . . . . . . . . . 78
C.6. Examples of MAC0 Messages . . . . . . . . . . . . . . . . 75 C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 78
C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 75 C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 79
C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 76 C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 79
C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 76 C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 80
C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 77 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 82
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 79 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 83
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 80
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
structures. CBOR was designed specifically to be both small in terms structures. CBOR was designed specifically to be both small in terms
of messages transport and implementation size and be a schema-free of messages transport and implementation size and be a schema-free
decoder. A need exists to provide message security services for IoT, decoder. A need exists to provide message security services for IoT,
and using CBOR as the message-encoding format makes sense. and using CBOR as the message-encoding format makes sense.
The JOSE working group produced a set of documents [RFC7515] The JOSE working group produced a set of documents [RFC7515]
[RFC7516] [RFC7517] [RFC7518] using JSON that specified how to [RFC7516] [RFC7517] [RFC7518] using JSON that specified how to
process encryption, signatures, and Message Authentication Code (MAC) process encryption, signatures, and Message Authentication Code (MAC)
operations and how to encode keys using JSON. This document along operations and how to encode keys using JSON. This document along
with [I-D.schaad-cose-rfc8152bis-algs] defines the CBOR Object with [I-D.ietf-cose-rfc8152bis-algs] defines the CBOR Object Signing
Signing and Encryption (COSE) standard, which does the same thing for and Encryption (COSE) standard, which does the same thing for the
the CBOR encoding format. While there is a strong attempt to keep CBOR encoding format. While there is a strong attempt to keep the
the flavor of the original JSON Object Signing and Encryption (JOSE) flavor of the original JSON Object Signing and Encryption (JOSE)
documents, two considerations are taken into account: documents, two considerations are taken into account:
o CBOR has capabilities that are not present in JSON and are 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 appropriate to use. One example of this is the fact that CBOR has
a method of encoding binary directly without first converting it a method of encoding binary directly without first converting it
into a base64-encoded string. into a base64-encoded string.
o COSE is not a direct copy of the JOSE specification. In the o COSE is not a direct copy of the JOSE specification. In the
process of creating COSE, decisions that were made for JOSE were process of creating COSE, decisions that were made for JOSE were
re-examined. In many cases, different results were decided on as re-examined. In many cases, different results were decided on as
skipping to change at page 5, line 15 skipping to change at page 5, line 19
keys. keys.
o The procedures used to compute build the inputs to the o The procedures used to compute build the inputs to the
cryptographic functions required for each of the structures. cryptographic functions required for each of the structures.
o A starting set of attributes that apply to the different security o A starting set of attributes that apply to the different security
objects. objects.
This document does not contain the rules and procedures for using This document does not contain the rules and procedures for using
specific cryptographic algorithms. Details on specific algorithms 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 Details for additional algorithms are expected to be defined in
future documents. future documents.
One feature that is present in CMS [RFC5652] that is not present in One feature that is present in CMS [RFC5652] that is not present in
this standard is a digest structure. This omission is deliberate. this standard is a digest structure. This omission is deliberate.
It is better for the structure to be defined in each document as 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 different protocols will want to include a different set of fields as
part of the structure. While an algorithm identifier and the digesst part of the structure. While an algorithm identifier and the digesst
value are going to be common to all applications, the two values may 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 not always be adjacent as the algorithm could be defined once with
skipping to change at page 6, line 8 skipping to change at page 6, line 11
o Use binary encodings for binary data rather than base64url o Use binary encodings for binary data rather than base64url
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. Requirements Terminology 1.2. Changes from RFC8152
TBD
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.3. CBOR Grammar 1.4. CBOR Grammar
There was not a standard CBOR grammar available when COSE was There was not a standard CBOR grammar available when COSE was
originally written. For that reason the CBOR structures defined here originally written. For that reason the CBOR structures defined here
are described in prose. Since that time CBOR Data Definition are described in prose. Since that time CBOR Data Definition
Language (CDDL) [I-D.ietf-cbor-cddl] has been published as an RFC. 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 CBOR grammar presented in this document is compatible with CDDL.
The document was developed by first working on the grammar and then 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 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 prose was written using the primitive type strings defined by CBOR
skipping to change at page 7, line 34 skipping to change at page 7, line 41
; This is defined to make the tool quieter: ; This is defined to make the tool quieter:
Internal_Types = Sig_structure / Enc_structure / MAC_structure / Internal_Types = Sig_structure / Enc_structure / MAC_structure /
COSE_KDF_Context COSE_KDF_Context
The non-terminal Internal_Types is defined for dealing with the The non-terminal Internal_Types is defined for dealing with the
automated validation tools used during the writing of this document. automated validation tools used during the writing of this document.
It references those non-terminals that are used for security It references those non-terminals that are used for security
computations but are not emitted for transport. 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 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 string. In COSE, we use strings, negative integers, and unsigned
integers as map keys. The integers are used for compactness of integers as map keys. The integers are used for compactness of
encoding and easy comparison. The inclusion of strings allows for an encoding and easy comparison. The inclusion of strings allows for an
additional range of short encoded values to be used as well. Since additional range of short encoded values to be used as well. Since
the word "key" is mainly used in its other meaning, as a 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 cryptographic key, we use the term "label" for this usage as a map
key. key.
skipping to change at page 8, line 8 skipping to change at page 8, line 16
integer is an error. Applications can either fail processing or integer is an error. Applications can either fail processing or
process messages by ignoring incorrect labels; however, they MUST NOT process messages by ignoring incorrect labels; however, they MUST NOT
create messages with incorrect labels. create messages with incorrect labels.
A CDDL grammar fragment defines the non-terminal 'label', as in the A CDDL grammar fragment defines the non-terminal 'label', as in the
previous paragraph, and 'values', which permits any value to be used. previous paragraph, and 'values', which permits any value to be used.
label = int / tstr label = int / tstr
values = any values = any
1.5. Document Terminology 1.6. Document Terminology
In this document, we use the following terminology: In this document, we use the following terminology:
Byte is a synonym for octet. Byte is a synonym for octet.
Constrained Application Protocol (CoAP) is a specialized web transfer Constrained Application Protocol (CoAP) is a specialized web transfer
protocol for use in constrained systems. It is defined in [RFC7252]. protocol for use in constrained systems. It is defined in [RFC7252].
Authenticated Encryption (AE) [RFC5116] algorithms are those Authenticated Encryption (AE) [RFC5116] algorithms are those
encryption algorithms that provide an authentication check of the encryption algorithms that provide an authentication check of the
skipping to change at page 11, line 6 skipping to change at page 11, line 29
but are used for holding information about content, algorithms, keys, but are used for holding information about content, algorithms, keys,
or evaluation hints for the processing of the layer. These two or evaluation hints for the processing of the layer. These two
buckets are available for use in all of the structures except for 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 keys. While these buckets are present, they may not all be usable in
all instances. For example, while the protected bucket is defined as all instances. For example, while the protected bucket is defined as
part of the recipient structure, some of the algorithms used for part of the recipient structure, some of the algorithms used for
recipient structures do not provide for authenticated data. If this recipient structures do not provide for authenticated data. If this
is the case, the protected bucket is left empty. is the case, the protected bucket is left empty.
Both buckets are implemented as CBOR maps. The map key is a 'label' 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 the label. Both maps use the same set of label/value pairs. The
integer and string values for labels have been divided into several integer and string values for labels have been divided into several
sections including a standard range, a private range, and a range sections including a standard range, a private range, and a range
that is dependent on the algorithm selected. The defined labels can that is dependent on the algorithm selected. The defined labels can
be found in the "COSE Header Parameters" IANA registry be found in the "COSE Header Parameters" IANA registry
(Section 15.2). (Section 15.2).
Two buckets are provided for each layer: Two buckets are provided for each layer:
protected: Contains parameters about the current layer that are protected: Contains parameters about the current layer that are
skipping to change at page 12, line 45 skipping to change at page 13, line 28
This section defines a set of common header parameters. A summary of This section defines a set of common header parameters. A summary of
these parameters can be found in Table 3. This table should be 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. consulted to determine the value of label and the type of the value.
The set of header parameters defined in this section are: The set of header parameters defined in this section are:
alg: This parameter is used to indicate the algorithm used for the alg: This parameter is used to indicate the algorithm used for the
security processing. This parameter MUST be authenticated where security processing. This parameter MUST be authenticated where
the ability to do so exists. This support is provided by AEAD 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 COSE_Mac0). This authentication can be done either by placing the
parameter in the protected header bucket or as part of the parameter in the protected header bucket or as part of the
externally supplied data. The value is taken from the "COSE externally supplied data. The value is taken from the "COSE
Algorithms" registry (see [COSE.Algorithms]). Algorithms" registry (see [COSE.Algorithms]).
crit: The parameter is used to indicate which protected header crit: The parameter is used to indicate which protected header
labels an application that is processing a message is required to labels an application that is processing a message is required to
understand. Parameters defined in this document do not need to be understand. Parameters defined in this document do not need to be
included as they should be understood by all implementations. included as they should be understood by all implementations.
When present, this parameter MUST be placed in the protected When present, this parameter MUST be placed in the protected
skipping to change at page 19, line 36 skipping to change at page 20, line 36
This document describes the process for using a byte array of This document describes the process for using a byte array of
externally supplied authenticated data; the method of constructing externally supplied authenticated data; the method of constructing
the byte array is a function of the application. Applications that the byte array is a function of the application. Applications that
use this feature need to define how the externally supplied use this feature need to define how the externally supplied
authenticated data is to be constructed. Such a construction needs authenticated data is to be constructed. Such a construction needs
to take into account the following issues: to take into account the following issues:
o If multiple items are included, applications need to ensure that o If multiple items are included, applications need to ensure that
the same byte string cannot produced if there are different 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 or by appending the strings 'ABC' and 'DE'. This is usually
addressed by making fields a fixed width and/or encoding the addressed by making fields a fixed width and/or encoding the
length of the field as part of the output. Using options from length of the field as part of the output. Using options from
CoAP [RFC7252] as an example, these fields use a TLV structure so CoAP [RFC7252] as an example, these fields use a TLV structure so
they can be concatenated without any problems. they can be concatenated without any problems.
o If multiple items are included, an order for the items needs to be o If multiple items are included, an order for the items needs to be
defined. Using options from CoAP as an example, an application defined. Using options from CoAP as an example, an application
could state that the fields are to be ordered by the option could state that the fields are to be ordered by the option
number. number.
skipping to change at page 27, line 6 skipping to change at page 28, line 6
and key at the current layer. Examples are key transport keys and key at the current layer. Examples are key transport keys
(Section 12.3), key wrap keys (Section 12.2), or pre-shared (Section 12.3), key wrap keys (Section 12.2), or pre-shared
secrets. secrets.
Direct Encryption and Direct Key Agreement: The key is Direct Encryption and Direct Key Agreement: The key is
determined by the key and algorithm in the recipient determined by the key and algorithm in the recipient
structure. The encryption algorithm and size of the key to be structure. The encryption algorithm and size of the key to be
used are inputs into the KDF used for the recipient. (For used are inputs into the KDF used for the recipient. (For
direct, the KDF can be thought of as the identity operation.) direct, the KDF can be thought of as the identity operation.)
Examples of these algorithms are found in Sections !!! DIRECT- Examples of these algorithms are found in Sections !!! DIRECT-
KDF !!! and !!! ECDH !!! of KDF !!! and !!! ECDH !!! of [I-D.ietf-cose-rfc8152bis-algs].
[I-D.schaad-cose-rfc8152bis-algs].
Other: The key is randomly or pseudorandomly generated. Other: The key is randomly or pseudorandomly generated.
4. Call the encryption algorithm with K (the encryption key), P (the 4. Call the encryption algorithm with K (the encryption key), P (the
plaintext), and AAD. Place the returned ciphertext into the plaintext), and AAD. Place the returned ciphertext into the
'ciphertext' field of the structure. 'ciphertext' field of the structure.
5. For recipients of the message, recursively perform the encryption 5. For recipients of the message, recursively perform the encryption
algorithm for that recipient, using K (the encryption key) as the algorithm for that recipient, using K (the encryption key) as the
plaintext. plaintext.
skipping to change at page 33, line 39 skipping to change at page 34, line 39
} }
COSE_KeySet = [+COSE_Key] COSE_KeySet = [+COSE_Key]
7.1. COSE Key Common Parameters 7.1. COSE Key Common Parameters
This document defines a set of common parameters for a COSE Key This document defines a set of common parameters for a COSE Key
object. Table 4 provides a summary of the parameters defined in this object. Table 4 provides a summary of the parameters defined in this
section. There are also parameters that are defined for specific key section. There are also parameters that are defined for specific key
types. Key-type-specific parameters can be found in 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 | | Name | Label | CBOR Type | Value | Description |
| | | | Registry | | | | | | Registry | |
+---------+-------+----------------+------------+-------------------+ +---------+-------+----------------+------------+-------------------+
| kty | 1 | tstr / int | COSE Key | Identification of | | kty | 1 | tstr / int | COSE Key | Identification of |
| | | | Types | the key type | | | | | Types | the key type |
| | | | | | | | | | | |
| kid | 2 | bstr | | Key | | kid | 2 | bstr | | Key |
| | | | | identification | | | | | | identification |
skipping to change at page 39, line 9 skipping to change at page 40, line 9
o Secrets that are not random: This is the type of secret that o Secrets that are not random: This is the type of secret that
people generate for things like passwords. people generate for things like passwords.
General KDFs work well with the first type of secret, can do General KDFs work well with the first type of secret, can do
reasonably well with the second type of secret, and generally do reasonably well with the second type of secret, and generally do
poorly with the last type of secret. Functions like PBES2 [RFC8018] poorly with the last type of secret. Functions like PBES2 [RFC8018]
need to be used for non-random secrets. need to be used for non-random secrets.
The same KDF can be set up to deal with the first two types of 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 secrets in a different way. The KDF defined in !!! HDKF !!! (section
XXXX of [I-D.schaad-cose-rfc8152bis-algs]) is such a function. This XXXX of [I-D.ietf-cose-rfc8152bis-algs]) is such a function. This is
is reflected in the set of algorithms defined around the HMAC-based reflected in the set of algorithms defined around the HMAC-based
Extract-and-Expand Key Derivation Function (HKDF). Extract-and-Expand Key Derivation Function (HKDF).
When using KDFs, one component that is included is context When using KDFs, one component that is included is context
information. Context information is used to allow for different information. Context information is used to allow for different
keying information to be derived from the same secret. The use of keying information to be derived from the same secret. The use of
context-based keying material is considered to be a good security context-based keying material is considered to be a good security
practice. practice.
12. Content Key Distribution Methods 12. Content Key Distribution Methods
skipping to change at page 40, line 41 skipping to change at page 41, line 41
o At a minimum, the 'unprotected' field MUST contain the 'alg' o At a minimum, the 'unprotected' field MUST contain the 'alg'
parameter and SHOULD contain a parameter identifying the shared parameter and SHOULD contain a parameter identifying the shared
secret. secret.
12.3. Key Transport 12.3. Key Transport
Key transport mode is also called key encryption mode in some Key transport mode is also called key encryption mode in some
standards. Key transport mode differs from key wrap mode in that it standards. Key transport mode differs from key wrap mode in that it
uses an asymmetric encryption algorithm rather than a symmetric uses an asymmetric encryption algorithm rather than a symmetric
encryption algorithm to protect the key. This document does not encryption algorithm to protect the key. A set of key transport
define any key transport mode algorithms. algorithms are defined in [RFC8230].
When using a key transport algorithm, the COSE_Encrypt structure for When using a key transport algorithm, the COSE_Encrypt structure for
the recipient is organized as follows: the recipient is organized as follows:
o The 'protected' field MUST be absent. o The 'protected' field MUST be absent.
o The plaintext to be encrypted is the key from the next layer down o The plaintext to be encrypted is the key from the next layer down
(usually the content layer). (usually the content layer).
o At a minimum, the 'unprotected' field MUST contain the 'alg' o At a minimum, the 'unprotected' field MUST contain the 'alg'
skipping to change at page 51, line 24 skipping to change at page 52, line 24
analysis of encrypted messages based on the length of the message. analysis of encrypted messages based on the length of the message.
This specification does not provide for a uniform method of providing This specification does not provide for a uniform method of providing
padding as part of the message structure. An observer can padding as part of the message structure. An observer can
distinguish between two different strings (for example, 'YES' and distinguish between two different strings (for example, 'YES' and
'NO') based on the length for all of the content encryption 'NO') based on the length for all of the content encryption
algorithms that are defined in this document. This means that it is 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 up to the applications to document how content padding is to be done
in order to prevent or discourage such analysis. (For example, the in order to prevent or discourage such analysis. (For example, the
strings could be defined as 'YES' and 'NO '.) 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] [COAP.Formats]
IANA, "CoAP Content-Formats", IANA, "CoAP Content-Formats",
<https://www.iana.org/assignments/core-parameters/ <https://www.iana.org/assignments/core-parameters/
core-parameters.xhtml#content-formats>. core-parameters.xhtml#content-formats>.
[COSE.Algorithms] [COSE.Algorithms]
IANA, "COSE Algorithms", IANA, "COSE Algorithms",
<https://www.iana.org/assignments/cose/ <https://www.iana.org/assignments/cose/
cose.xhtml#algorithms>. cose.xhtml#algorithms>.
skipping to change at page 52, line 11 skipping to change at page 54, line 35
IANA, "COSE Key Types", IANA, "COSE Key Types",
<https://www.iana.org/assignments/cose/ <https://www.iana.org/assignments/cose/
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.schaad-cose-rfc8152bis-algs] [I-D.ietf-cose-rfc8152bis-algs]
Schaad, J., "CBOR Algoritms for Object Signing and Schaad, J., "CBOR Algorithms for Object Signing and
Encryption (COSE)", draft-schaad-cose-rfc8152bis-algs-01 Encryption (COSE)", draft-ietf-cose-rfc8152bis-algs-00
(work in progress), December 2018. (work in progress), January 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>.
[RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital
Signature Algorithm (EdDSA)", RFC 8032, Signature Algorithm (EdDSA)", RFC 8032,
DOI 10.17487/RFC8032, January 2017, DOI 10.17487/RFC8032, January 2017,
<http://www.rfc-editor.org/info/rfc8032>. <https://www.rfc-editor.org/info/rfc8032>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
17.2. Informative References 18.2. Informative References
[I-D.ietf-cbor-cddl] [I-D.ietf-cbor-cddl]
Birkholz, H., Vigano, C., and C. Bormann, "Concise data Birkholz, H., Vigano, C., and C. Bormann, "Concise data
definition language (CDDL): a notational convention to definition language (CDDL): a notational convention to
express CBOR and JSON data structures", draft-ietf-cbor- 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] [I-D.ietf-core-object-security]
Selander, G., Mattsson, J., Palombini, F., and L. Seitz, Selander, G., Mattsson, J., Palombini, F., and L. Seitz,
"Object Security for Constrained RESTful Environments "Object Security for Constrained RESTful Environments
(OSCORE)", draft-ietf-core-object-security-15 (work in (OSCORE)", draft-ietf-core-object-security-15 (work in
progress), August 2018. progress), August 2018.
[PVSig] Brown, D. and D. Johnson, "Formal Security Proofs for a [PVSig] Brown, D. and D. Johnson, "Formal Security Proofs for a
Signature Scheme with Partial Message Recovery", Signature Scheme with Partial Message Recovery",
DOI 10.1007/3-540-45353-9_11, LNCS Volume 2020, June 2000. DOI 10.1007/3-540-45353-9_11, LNCS Volume 2020, June 2000.
skipping to change at page 54, line 21 skipping to change at page 56, line 42
<https://www.rfc-editor.org/info/rfc7516>. <https://www.rfc-editor.org/info/rfc7516>.
[RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517,
DOI 10.17487/RFC7517, May 2015, DOI 10.17487/RFC7517, May 2015,
<https://www.rfc-editor.org/info/rfc7517>. <https://www.rfc-editor.org/info/rfc7517>.
[RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,
DOI 10.17487/RFC7518, May 2015, DOI 10.17487/RFC7518, May 2015,
<https://www.rfc-editor.org/info/rfc7518>. <https://www.rfc-editor.org/info/rfc7518>.
[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,
<https://www.rfc-editor.org/info/rfc7942>.
[RFC8018] Moriarty, K., Ed., Kaliski, B., and A. Rusch, "PKCS #5: [RFC8018] Moriarty, K., Ed., Kaliski, B., and A. Rusch, "PKCS #5:
Password-Based Cryptography Specification Version 2.1", Password-Based Cryptography Specification Version 2.1",
RFC 8018, DOI 10.17487/RFC8018, January 2017, RFC 8018, DOI 10.17487/RFC8018, January 2017,
<https://www.rfc-editor.org/info/rfc8018>. <https://www.rfc-editor.org/info/rfc8018>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26, Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017, RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>. <https://www.rfc-editor.org/info/rfc8126>.
 End of changes. 28 change blocks. 
116 lines changed or deleted 203 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/