draft-ietf-cose-rfc8152bis-struct-07.txt   draft-ietf-cose-rfc8152bis-struct-08.txt 
COSE Working Group J. Schaad COSE Working Group J. Schaad
Internet-Draft August Cellars Internet-Draft August Cellars
Obsoletes: 8152 (if approved) 17 November 2019 Obsoletes: 8152 (if approved) 9 March 2020
Intended status: Standards Track Intended status: Standards Track
Expires: 20 May 2020 Expires: 10 September 2020
CBOR Object Signing and Encryption (COSE): Structures and Process CBOR Object Signing and Encryption (COSE): Structures and Process
draft-ietf-cose-rfc8152bis-struct-07 draft-ietf-cose-rfc8152bis-struct-08
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 2, line 4 skipping to change at page 2, line 4
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 20 May 2020. This Internet-Draft will expire on 10 September 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2020 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 (https://trustee.ietf.org/ Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components and restrictions with respect to this document. Code Components
extracted from this document must include Simplified BSD License text extracted from this document must include Simplified BSD License text
as described in Section 4.e of the Trust Legal Provisions and are as described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Simplified BSD License. provided without warranty as 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. Requirements Terminology . . . . . . . . . . . . . . . . 5
1.2. Changes from RFC8152 . . . . . . . . . . . . . . . . . . 6 1.2. Changes from RFC8152 . . . . . . . . . . . . . . . . . . 5
1.3. Requirements Terminology . . . . . . . . . . . . . . . . 6 1.3. Design Changes from JOSE . . . . . . . . . . . . . . . . 6
1.4. CBOR Grammar . . . . . . . . . . . . . . . . . . . . . . 6 1.4. CBOR Grammar . . . . . . . . . . . . . . . . . . . . . . 6
1.5. CBOR-Related Terminology . . . . . . . . . . . . . . . . 8 1.5. CBOR-Related Terminology . . . . . . . . . . . . . . . . 8
1.6. Document Terminology . . . . . . . . . . . . . . . . . . 8 1.6. Document Terminology . . . . . . . . . . . . . . . . . . 8
2. Basic COSE Structure . . . . . . . . . . . . . . . . . . . . 9 2. Basic COSE Structure . . . . . . . . . . . . . . . . . . . . 9
3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 13 3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 13
3.1. Common COSE Headers Parameters . . . . . . . . . . . . . 14 3.1. Common COSE Header Parameters . . . . . . . . . . . . . . 15
4. Signing Objects . . . . . . . . . . . . . . . . . . . . . . . 18 4. Signing Objects . . . . . . . . . . . . . . . . . . . . . . . 18
4.1. Signing with One or More Signers . . . . . . . . . . . . 18 4.1. Signing with One or More Signers . . . . . . . . . . . . 18
4.2. Signing with One Signer . . . . . . . . . . . . . . . . . 20 4.2. Signing with One Signer . . . . . . . . . . . . . . . . . 20
4.3. Externally Supplied Data . . . . . . . . . . . . . . . . 21 4.3. Externally Supplied Data . . . . . . . . . . . . . . . . 21
4.4. Signing and Verification Process . . . . . . . . . . . . 22 4.4. Signing and Verification Process . . . . . . . . . . . . 22
5. Counter Signatures . . . . . . . . . . . . . . . . . . . . . 24 5. Counter Signatures . . . . . . . . . . . . . . . . . . . . . 24
5.1. Full Countersignatures . . . . . . . . . . . . . . . . . 24 5.1. Full Countersignatures . . . . . . . . . . . . . . . . . 24
5.2. Abbreviated Countersignatures . . . . . . . . . . . . . . 25 5.2. Abbreviated Countersignatures . . . . . . . . . . . . . . 25
6. Encryption Objects . . . . . . . . . . . . . . . . . . . . . 26 6. Encryption Objects . . . . . . . . . . . . . . . . . . . . . 26
6.1. Enveloped COSE Structure . . . . . . . . . . . . . . . . 26 6.1. Enveloped COSE Structure . . . . . . . . . . . . . . . . 26
skipping to change at page 3, line 10 skipping to change at page 3, line 10
7.2. MACed Messages with Implicit Key . . . . . . . . . . . . 34 7.2. MACed Messages with Implicit Key . . . . . . . . . . . . 34
7.3. How to Compute and Verify a MAC . . . . . . . . . . . . . 35 7.3. How to Compute and Verify a MAC . . . . . . . . . . . . . 35
8. Key Objects . . . . . . . . . . . . . . . . . . . . . . . . . 36 8. Key Objects . . . . . . . . . . . . . . . . . . . . . . . . . 36
8.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 37 8.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 37
9. Taxonomy of Algorithms used by COSE . . . . . . . . . . . . . 39 9. Taxonomy of Algorithms used by COSE . . . . . . . . . . . . . 39
9.1. Signature Algorithms . . . . . . . . . . . . . . . . . . 40 9.1. Signature Algorithms . . . . . . . . . . . . . . . . . . 40
9.2. Message Authentication Code (MAC) Algorithms . . . . . . 41 9.2. Message Authentication Code (MAC) Algorithms . . . . . . 41
9.3. Content Encryption Algorithms . . . . . . . . . . . . . . 41 9.3. Content Encryption Algorithms . . . . . . . . . . . . . . 41
9.4. Key Derivation Functions (KDFs) . . . . . . . . . . . . . 42 9.4. Key Derivation Functions (KDFs) . . . . . . . . . . . . . 42
9.5. Content Key Distribution Methods . . . . . . . . . . . . 42 9.5. Content Key Distribution Methods . . . . . . . . . . . . 43
9.5.1. Direct Encryption . . . . . . . . . . . . . . . . . . 43 9.5.1. Direct Encryption . . . . . . . . . . . . . . . . . . 43
9.5.2. Key Wrap . . . . . . . . . . . . . . . . . . . . . . 43 9.5.2. Key Wrap . . . . . . . . . . . . . . . . . . . . . . 43
9.5.3. Key Transport . . . . . . . . . . . . . . . . . . . . 44 9.5.3. Key Transport . . . . . . . . . . . . . . . . . . . . 44
9.5.4. Direct Key Agreement . . . . . . . . . . . . . . . . 44 9.5.4. Direct Key Agreement . . . . . . . . . . . . . . . . 44
9.5.5. Key Agreement with Key Wrap . . . . . . . . . . . . . 45 9.5.5. Key Agreement with Key Wrap . . . . . . . . . . . . . 45
10. CBOR Encoding Restrictions . . . . . . . . . . . . . . . . . 46 10. CBOR Encoding Restrictions . . . . . . . . . . . . . . . . . 46
11. Application Profiling Considerations . . . . . . . . . . . . 46 11. Application Profiling Considerations . . . . . . . . . . . . 46
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48
12.1. CBOR Tag Assignment . . . . . . . . . . . . . . . . . . 48 12.1. CBOR Tag Assignment . . . . . . . . . . . . . . . . . . 48
12.2. COSE Header Parameters Registry . . . . . . . . . . . . 48 12.2. COSE Header Parameters Registry . . . . . . . . . . . . 48
12.3. COSE Header Algorithm Parameters Registry . . . . . . . 48 12.3. COSE Header Algorithm Parameters Registry . . . . . . . 48
12.4. COSE Key Common Parameters Registry . . . . . . . . . . 48 12.4. COSE Key Common Parameters Registry . . . . . . . . . . 48
12.5. Media Type Registrations . . . . . . . . . . . . . . . . 49 12.5. Media Type Registrations . . . . . . . . . . . . . . . . 49
12.5.1. COSE Security Message . . . . . . . . . . . . . . . 49 12.5.1. COSE Security Message . . . . . . . . . . . . . . . 49
12.5.2. COSE Key Media Type . . . . . . . . . . . . . . . . 50 12.5.2. COSE Key Media Type . . . . . . . . . . . . . . . . 50
12.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 52 12.6. CoAP Content-Formats Registry . . . . . . . . . . . . . 52
13. Security Considerations . . . . . . . . . . . . . . . . . . . 52 13. Security Considerations . . . . . . . . . . . . . . . . . . . 52
14. Implementation Status . . . . . . . . . . . . . . . . . . . . 54 14. Implementation Status . . . . . . . . . . . . . . . . . . . . 54
skipping to change at page 3, line 40 skipping to change at page 3, line 40
14.2. JavaScript Version . . . . . . . . . . . . . . . . . . . 55 14.2. JavaScript Version . . . . . . . . . . . . . . . . . . . 55
14.3. Python Version . . . . . . . . . . . . . . . . . . . . . 55 14.3. Python Version . . . . . . . . . . . . . . . . . . . . . 55
14.4. COSE Testing Library . . . . . . . . . . . . . . . . . . 56 14.4. COSE Testing Library . . . . . . . . . . . . . . . . . . 56
15. References . . . . . . . . . . . . . . . . . . . . . . . . . 56 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 56
15.1. Normative References . . . . . . . . . . . . . . . . . . 56 15.1. Normative References . . . . . . . . . . . . . . . . . . 56
15.2. Informative References . . . . . . . . . . . . . . . . . 57 15.2. Informative References . . . . . . . . . . . . . . . . . 57
Appendix A. Guidelines for External Data Authentication of Appendix A. Guidelines for External Data Authentication of
Algorithms . . . . . . . . . . . . . . . . . . . . . . . 60 Algorithms . . . . . . . . . . . . . . . . . . . . . . . 60
Appendix B. Two Layers of Recipient Information . . . . . . . . 63 Appendix B. Two Layers of Recipient Information . . . . . . . . 63
Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 65 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 65
C.1. Examples of Signed Messages . . . . . . . . . . . . . . . 65 C.1. Examples of Signed Messages . . . . . . . . . . . . . . . 66
C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 65 C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 66
C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 66 C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 67
C.1.3. Counter Signature . . . . . . . . . . . . . . . . . . 67 C.1.3. Counter Signature . . . . . . . . . . . . . . . . . . 68
C.1.4. Signature with Criticality . . . . . . . . . . . . . 68 C.1.4. Signature with Criticality . . . . . . . . . . . . . 69
C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 69 C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 70
C.2.1. Single ECDSA Signature . . . . . . . . . . . . . . . 69 C.2.1. Single ECDSA Signature . . . . . . . . . . . . . . . 70
C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 70 C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 71
C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 70 C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 71
C.3.2. Direct Plus Key Derivation . . . . . . . . . . . . . 71 C.3.2. Direct Plus Key Derivation . . . . . . . . . . . . . 72
C.3.3. Counter Signature on Encrypted Content . . . . . . . 72 C.3.3. Counter Signature on Encrypted Content . . . . . . . 73
C.3.4. Encrypted Content with External Data . . . . . . . . 73 C.3.4. Encrypted Content with External Data . . . . . . . . 74
C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 74 C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 75
C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 74 C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 75
C.4.2. Encrypted Message with a Partial IV . . . . . . . . . 75 C.4.2. Encrypted Message with a Partial IV . . . . . . . . . 76
C.5. Examples of MACed Messages . . . . . . . . . . . . . . . 75 C.5. Examples of MACed Messages . . . . . . . . . . . . . . . 76
C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 75 C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 76
C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 76 C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 77
C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 77 C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 78
C.5.4. Multi-Recipient MACed Message . . . . . . . . . . . . 78 C.5.4. Multi-Recipient MACed Message . . . . . . . . . . . . 79
C.6. Examples of MAC0 Messages . . . . . . . . . . . . . . . . 79 C.6. Examples of MAC0 Messages . . . . . . . . . . . . . . . . 80
C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 79 C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 80
C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 80 C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 81
C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 80 C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 81
C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 81 C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 82
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 83 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 84
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 84 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 85
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 4, line 46 skipping to change at page 4, line 46
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.ietf-cose-rfc8152bis-algs] defines the CBOR Object Signing with [I-D.ietf-cose-rfc8152bis-algs] defines the CBOR Object Signing
and Encryption (COSE) standard, which does the same thing for the and Encryption (COSE) standard, which does the same thing for the
CBOR encoding format. While there is a strong attempt to keep the CBOR encoding format. While there is a strong attempt to keep 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:
* CBOR has capabilities that are not present in JSON and are * 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 text string.
* COSE is not a direct copy of the JOSE specification. In the * 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
the criteria were not always the same. the criteria were not always the same.
This document contains: This document contains:
* The description of the structure for the CBOR objects which are * The description of the structure for the CBOR objects which are
transmitted over the wire. Two objects are defined for transmitted over the wire. Two objects are defined for
skipping to change at page 5, line 29 skipping to change at page 5, line 29
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.ietf-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 digest
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
multiple values. Applications may additionally want to define multiple values. Applications may additionally want to define
additional data fields as part of the stucture. A common structure additional data fields as part of the structure. A common structure
is going to include a URI or other pointer to where the data that is is going to include a URI or other pointer to where the data that is
being hashed is kept, allowing this to be application specific. being hashed is kept, allowing this to be application specific.
1.1. Design Changes from JOSE 1.1. 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.2. Changes from RFC8152
* Split the original document into this document and
[I-D.ietf-cose-rfc8152bis-algs].
* Add some text describing why there is no digest structure defined
by COSE.
* Rearrange the text around counter signatures and define a CBOR Tag
for a standalone countersignature.
* Text clarifications and changes in terminology.
1.3. Design Changes from JOSE
* Define a single top message structure so that encrypted, signed, * Define a single top message structure so that encrypted, signed,
and MACed messages can easily be identified and still have a and MACed messages can easily be identified and still have a
consistent view. consistent view.
* Signed messages distinguish between the protected and unprotected * Signed messages distinguish between the protected and unprotected
parameters that relate to the content from those that relate to header parameters that relate to the content from those that
the signature. relate to the signature.
* MACed messages are separated from signed messages. * MACed messages are separated from signed messages.
* MACed messages have the ability to use the same set of recipient * MACed messages have the ability to use the same set of recipient
algorithms as enveloped messages for obtaining the MAC algorithms as enveloped messages for obtaining the MAC
authentication key. authentication key.
* Use binary encodings for binary data rather than base64url * Use binary encodings for binary data rather than base64url
encodings. encodings.
* Combine the authentication tag for encryption algorithms with the * Combine the authentication tag for encryption algorithms with the
ciphertext. ciphertext.
* The set of cryptographic algorithms has been expanded in some * 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
* Split the orignal document into this document and
[I-D.ietf-cose-rfc8152bis-algs].
* Add some text describing why there is no digest structure defined
by COSE.
* Rearrange the text around counter signatures and define a CBOR Tag
for a standalone countersignature.
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 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 data objects defined
are described in prose. Since that time CBOR Data Definition here are described in prose. Since that time CBOR Data Definition
Language (CDDL) [RFC8610] has been published as an RFC. The CBOR Language (CDDL) [RFC8610] has been published as an RFC. The CBOR
grammar presented in this document is compatible with CDDL. 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
Data Definition Language (CDDL) [RFC8610]. In this specification, Data Definition Language (CDDL) [RFC8610]. In this specification,
the following primitive types are used: the following primitive types are used:
any -- non-specific value that permits all CBOR values to be any -- non-specific value that permits all CBOR values to be
skipping to change at page 8, line 4 skipping to change at page 8, line 9
//sourcecode[@type='CDDL']/text() //sourcecode[@type='CDDL']/text()
CDDL expects the initial non-terminal symbol to be the first symbol CDDL expects the initial non-terminal symbol to be the first symbol
in the file. For this reason, the first fragment of CDDL is in the file. For this reason, the first fragment of CDDL is
presented here. presented here.
start = COSE_Messages / COSE_Key / COSE_KeySet / Internal_Types start = COSE_Messages / COSE_Key / COSE_KeySet / Internal_Types
; 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
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.5. 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 text string. In COSE, we use text strings, negative integers, and
integers as map keys. The integers are used for compactness of unsigned integers as map keys. The integers are used for compactness
encoding and easy comparison. The inclusion of strings allows for an of encoding and easy comparison. The inclusion of text strings
additional range of short encoded values to be used as well. Since allows for an additional range of short encoded values to be used as
the word "key" is mainly used in its other meaning, as a 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 cryptographic key, we use the term "label" for this usage as a map
key. key.
The presence of a label in a COSE map that is not a string or an The presence of a label in a CBOR map that is not a text string or an
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
skipping to change at page 9, line 6 skipping to change at page 9, line 12
Authenticated Encryption with Associated Data (AEAD) [RFC5116] Authenticated Encryption with Associated Data (AEAD) [RFC5116]
algorithms provide the same content authentication service as AE algorithms provide the same content authentication service as AE
algorithms, but they additionally provide for authentication of non- algorithms, but they additionally provide for authentication of non-
encrypted data as well. encrypted data as well.
Context is used throughout the document to represent information that Context is used throughout the document to represent information that
is not part of the COSE message. Information which is part of the is not part of the COSE message. Information which is part of the
context can come from several different sources including: Protocol context can come from several different sources including: Protocol
interactions, associated key structures and program configuration. interactions, associated key structures and program configuration.
The context to use can be implicit, identified using the 'kid The context to use can be implicit, identified using the 'kid
context' header field defined in [RFC8613], or identified by a context' header parameter defined in [RFC8613], or identified by a
protocol specific identifier. Context should generally be included protocol specific identifier. Context should generally be included
in the cryptographic configuration, for more details see Section 4.3. in the cryptographic configuration, for more details see Section 4.3.
The term 'byte string' is used for sequences of bytes, while the term
'text string' is used for sequences of characters.
2. Basic COSE Structure 2. Basic COSE Structure
The COSE object structure is designed so that there can be a large The COSE object structure is designed so that there can be a large
amount of common code when parsing and processing the different types amount of common code when parsing and processing the different types
of security messages. All of the message structures are built on the of security messages. All of the message structures are built on the
CBOR array type. The first three elements of the array always CBOR array type. The first three elements of the array always
contain the same information: contain the same information:
1. The set of protected header parameters wrapped in a bstr. 1. The protected header parameters encoded and wrapped in a bstr.
2. The set of unprotected header parameters as a map. 2. The unprotected header parameters as a map.
3. The content of the message. The content is either the plaintext 3. The content of the message. The content is either the plaintext
or the ciphertext as appropriate. The content may be detached or the ciphertext as appropriate. The content may be detached
(i.e. transported separately from the COSE structure), but the (i.e. transported separately from the COSE structure), but the
location is still used. The content is wrapped in a bstr when location is still used. The content is wrapped in a bstr when
present and is a nil value when detached. present and is a nil value when detached.
Elements after this point are dependent on the specific message type. Elements after this point are dependent on the specific message type.
COSE messages are built using the concept of layers to separate COSE messages are built using the concept of layers to separate
skipping to change at page 13, line 21 skipping to change at page 13, line 21
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.5). 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 text string values for labels have been divided into
sections including a standard range, a private range, and a range several sections including a standard range, a private range, and a
that is dependent on the algorithm selected. The defined labels can range that is dependent on the algorithm selected. The defined
be found in the "COSE Header Parameters" IANA registry labels can be found in the "COSE Header Parameters" IANA registry
(Section 12.2). (Section 12.2).
The two buckets are: The two buckets are:
protected: Contains parameters about the current layer that are protected: Contains parameters about the current layer that are
cryptographically protected. This bucket MUST be empty if it is cryptographically protected. This bucket MUST be empty if it is
not going to be included in a cryptographic computation. This not going to be included in a cryptographic computation. This
bucket is encoded in the message as a binary object. This value bucket is encoded in the message as a binary object. This value
is obtained by CBOR encoding the protected map and wrapping it in is obtained by CBOR encoding the protected map and wrapping it in
a bstr object. Senders SHOULD encode a zero-length map as a zero- a bstr object. Senders SHOULD encode a zero-length map as a zero-
skipping to change at page 14, line 5 skipping to change at page 14, line 5
protected map to be transported with a greater chance that it will protected map to be transported with a greater chance that it will
not be altered in transit. (Badly behaved intermediates could not be altered in transit. (Badly behaved intermediates could
decode and re-encode, but this will result in a failure to verify decode and re-encode, but this will result in a failure to verify
unless the re-encoded byte string is identical to the decoded byte unless the re-encoded byte string is identical to the decoded byte
string.) This avoids the problem of all parties needing to be string.) This avoids the problem of all parties needing to be
able to do a common canonical encoding. able to do a common canonical encoding.
unprotected: Contains parameters about the current layer that are unprotected: Contains parameters about the current layer that are
not cryptographically protected. not cryptographically protected.
Only parameters that deal with the current layer are to be placed at Only header parameters that deal with the current layer are to be
that layer. As an example of this, the parameter 'content type' placed at that layer. As an example of this, the header parameter
describes the content of the message being carried in the message. 'content type' describes the content of the message being carried in
As such, this parameter is placed only in the content layer and is the message. As such, this header parameter is placed only in the
not placed in the recipient or signature layers. In principle, one content layer and is not placed in the recipient or signature layers.
should be able to process any given layer without reference to any In principle, one should be able to process any given layer without
other layer. With the exception of the COSE_Sign structure, the only reference to any other layer. With the exception of the COSE_Sign
data that needs to cross layers is the cryptographic key. structure, the only data that needs to cross layers is the
cryptographic key.
The buckets are present in all of the security objects defined in The buckets are present in all of the security objects defined in
this document. The fields in order are the 'protected' bucket (as a this document. The fields in order are the 'protected' bucket (as a
CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map' CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map'
type). The presence of both buckets is required. The parameters type). The presence of both buckets is required. The header
that go into the buckets come from the IANA "COSE Header Parameters" parameters that go into the buckets come from the IANA "COSE Header
registry (Section 12.2). Some common parameters are defined in the Parameters" registry (Section 12.2). Some common header parameters
next section. are defined in the next section.
Labels in each of the maps MUST be unique. When processing messages, Labels in each of the maps MUST be unique. When processing messages,
if a label appears multiple times, the message MUST be rejected as if a label appears multiple times, the message MUST be rejected as
malformed. Applications SHOULD verify that the same label does not malformed. Applications SHOULD verify that the same label does not
occur in both the protected and unprotected headers. If the message occur in both the protected and unprotected header parameters. If
is not rejected as malformed, attributes MUST be obtained from the the message is not rejected as malformed, attributes MUST be obtained
protected bucket before they are obtained from the unprotected from the protected bucket before they are obtained from the
bucket. unprotected bucket.
The following CDDL fragment represents the two header buckets. A The following CDDL fragment represents the two header parameter
group "Headers" is defined in CDDL that represents the two buckets in buckets. A group "Headers" is defined in CDDL that represents the
which attributes are placed. This group is used to provide these two two buckets in which attributes are placed. This group is used to
fields consistently in all locations. A type is also defined that provide these two fields consistently in all locations. A type is
represents the map of common headers. also defined that represents the map of common header parameters.
Headers = ( Headers = (
protected : empty_or_serialized_map, protected : empty_or_serialized_map,
unprotected : header_map unprotected : header_map
) )
header_map = { header_map = {
Generic_Headers, Generic_Headers,
* label => values * label => values
} }
empty_or_serialized_map = bstr .cbor header_map / bstr .size 0 empty_or_serialized_map = bstr .cbor header_map / bstr .size 0
3.1. Common COSE Headers Parameters 3.1. Common COSE Header Parameters
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 header parameters can be found in Table 3. This table should
consulted to determine the value of label and the type of the value. be 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 header parameter is used to indicate the algorithm used
security processing. This parameter MUST be authenticated where for the security processing. This header parameter MUST be
the ability to do so exists. This support is provided by AEAD authenticated where the ability to do so exists. This support is
algorithms or construction (COSE_Sign, COSE_Sign1, COSE_Mac, and provided by AEAD algorithms or construction (COSE_Sign,
COSE_Mac0). This authentication can be done either by placing the COSE_Sign1, COSE_Mac, and COSE_Mac0). This authentication can be
parameter in the protected header bucket or as part of the done either by placing the header parameter in the protected
externally supplied data. The value is taken from the "COSE header parameter bucket or as part of the externally supplied
Algorithms" registry (see [COSE.Algorithms]). data. The value is taken from the "COSE Algorithms" registry (see
[COSE.Algorithms]).
crit: The parameter is used to indicate which protected header crit: This header parameter is used to indicate which protected
labels an application that is processing a message is required to header parameters an application that is processing a message is
understand. Parameters defined in this document do not need to be required to understand. Header parameters defined in this
included as they should be understood by all implementations. document do not need to be included as they should be understood
When present, this parameter MUST be placed in the protected by all implementations. When present, this the 'crit' header
header bucket. The array MUST have at least one value in it. parameter MUST be placed in the protected header parameter bucket.
The array MUST have at least one value in it.
Not all labels need to be included in the 'crit' parameter. The Not all header parameter labels need to be included in the 'crit'
rules for deciding which header labels are placed in the array header parameter. The rules for deciding which header parameters
are: are placed in the array are:
* Integer labels in the range of 0 to 7 SHOULD be omitted. * Integer labels in the range of 0 to 7 SHOULD be omitted.
* Integer labels in the range -1 to -128 can be omitted as they * Integer labels in the range -1 to -128 can be omitted as they
are algorithm dependent. If an application can correctly are algorithm dependent. If an application can correctly
process an algorithm, it can be assumed that it will correctly process an algorithm, it can be assumed that it will correctly
process all of the common parameters associated with that process all of the common header parameters associated with
algorithm. Integer labels in the range -129 to -65536 SHOULD that algorithm. Integer labels in the range -129 to -65536
be included as these would be less common parameters that might SHOULD be included as these would be less common header
not be generally supported. parameters that might not be generally supported.
* Labels for parameters required for an application MAY be * Labels for header parameters required for an application MAY be
omitted. Applications should have a statement if the label can omitted. Applications should have a statement if the label can
be omitted. be omitted.
The header parameter values indicated by 'crit' can be processed The header parameters indicated by 'crit' can be processed by
by either the security library code or an application using a either the security library code or an application using a
security library; the only requirement is that the parameter is security library; the only requirement is that the header
processed. If the 'crit' value list includes a value for which parameter is processed. If the 'crit' value list includes a label
the parameter is not in the protected bucket, this is a fatal for which the header parameter is not in the protected header
error in processing the message. parameters bucket, this is a fatal error in processing the
message.
content type: This parameter is used to indicate the content type of
the data in the payload or ciphertext fields. Integers are from
the "CoAP Content-Formats" IANA registry table [COAP.Formats].
Text values following the syntax of "<type-name>/<subtype-name>"
where <type-name> and <subtype-name> are defined in Section 4.2 of
[RFC6838]. Leading and trailing whitespace is also omitted. content type: This header parameter is used to indicate the content
Textual content values along with parameters and subparameters can type of the data in the payload or ciphertext fields. Integers
be located using the IANA "Media Types" registry. Applications are from the "CoAP Content-Formats" IANA registry table
SHOULD provide this parameter if the content structure is [COAP.Formats]. Text values following the syntax of "<type-
potentially ambiguous. name>/<subtype-name>" where <type-name> and <subtype-name> are
defined in Section 4.2 of [RFC6838]. Leading and trailing
whitespace is also omitted. Textual content values along with
parameters and subparameters can be located using the IANA "Media
Types" registry. Applications SHOULD provide this header
parameter if the content structure is potentially ambiguous.
kid: This parameter identifies one piece of data that can be used as kid: This header parameter identifies one piece of data that can be
input to find the needed cryptographic key. The value of this used as input to find the needed cryptographic key. The value of
parameter can be matched against the 'kid' member in a COSE_Key this header parameter can be matched against the 'kid' member in a
structure. Other methods of key distribution can define an COSE_Key structure. Other methods of key distribution can define
equivalent field to be matched. Applications MUST NOT assume that an equivalent field to be matched. Applications MUST NOT assume
'kid' values are unique. There may be more than one key with the that 'kid' values are unique. There may be more than one key with
same 'kid' value, so all of the keys associated with this 'kid' the same 'kid' value, so all of the keys associated with this
may need to be checked. The internal structure of 'kid' values is 'kid' may need to be checked. The internal structure of 'kid'
not defined and cannot be relied on by applications. Key values is not defined and cannot be relied on by applications.
identifier values are hints about which key to use. This is not a Key identifier values are hints about which key to use. This is
security-critical field. For this reason, it can be placed in the not a security-critical field. For this reason, it can be placed
unprotected headers bucket. in the unprotected header parameters bucket.
IV: This parameter holds the Initialization Vector (IV) value. For IV: This header parameter holds the Initialization Vector (IV)
some symmetric encryption algorithms, this may be referred to as a value. For some symmetric encryption algorithms, this may be
nonce. The IV can be placed in the unprotected header as referred to as a nonce. The IV can be placed in the unprotected
modifying the IV will cause the decryption to yield plaintext that bucket as modifying the IV will cause the decryption to yield
is readily detectable as garbled. plaintext that is readily detectable as garbled.
Partial IV: This parameter holds a part of the IV value. When using Partial IV: This header parameter holds a part of the IV value.
the COSE_Encrypt0 structure, a portion of the IV can be part of When using the COSE_Encrypt0 structure, a portion of the IV can be
the context associated with the key (Context IV) while a portion part of the context associated with the key (Context IV) while a
can be changed with each message (Parital IV). This field is used portion can be changed with each message (Partial IV). This field
to carry a value that causes the IV to be changed for each is used to carry a value that causes the IV to be changed for each
message. The Parital IV can be placed in the unprotected header message. The Partial IV can be placed in the unprotected bucket
as modifying the value will cause the decryption to yield as modifying the value will cause the decryption to yield
plaintext that is readily detectable as garbled. The plaintext that is readily detectable as garbled. The
'Initialization Vector' and 'Partial Initialization Vector' 'Initialization Vector' and 'Partial Initialization Vector' header
parameters MUST NOT both be present in the same security layer. parameters MUST NOT both be present in the same security layer.
The message IV is generated by the following steps: The message IV is generated by the following steps:
1. Left-pad the Partial IV with zeros to the length of IV. 1. Left-pad the Partial IV with zeros to the length of IV.
2. XOR the padded Partial IV with the context IV. 2. XOR the padded Partial IV with the context IV.
counter signature: This parameter holds one or more counter counter signature: This header parameter holds one or more counter
signature values. Counter signatures provide a method of having a signature values. Counter signatures provide a method of having a
second party sign some data. The counter signature parameter can second party sign some data. The counter signature header
occur as an unprotected attribute in any of the following parameter can occur as an unprotected attribute in any of the
structures: COSE_Sign1, COSE_Signature, COSE_Encrypt, following structures: COSE_Sign1, COSE_Signature, COSE_Encrypt,
COSE_recipient, COSE_Encrypt0, COSE_Mac, and COSE_Mac0. These COSE_recipient, COSE_Encrypt0, COSE_Mac, and COSE_Mac0. These
structures all have the same beginning elements, so that a structures all have the same beginning elements, so that a
consistent calculation of the counter signature can be computed. consistent calculation of the counter signature can be computed.
Details on counter signatures are found in Section 5. Details on counter signatures are found in Section 5.
+---------+-----+----------------+-----------------+----------------+ +---------+-----+----------------+-----------------+----------------+
| Name |Label| Value Type | Value Registry | Description | | Name |Label| Value Type | Value Registry | Description |
+=========+=====+================+=================+================+ +=========+=====+================+=================+================+
| alg | 1 | int / tstr | COSE Algorithms | Cryptographic | | alg | 1 | int / tstr | COSE Algorithms | Cryptographic |
| | | | registry |algorithm to use| | | | | registry |algorithm to use|
+---------+-----+----------------+-----------------+----------------+ +---------+-----+----------------+-----------------+----------------+
| crit | 2 | [+ label] | COSE Header |Critical headers| | crit | 2 | [+ label] | COSE Header |Critical header |
| | | | Parameters |to be understood| | | | | Parameters |parameters to be|
| | | | registry | | | | | | registry | understood |
+---------+-----+----------------+-----------------+----------------+ +---------+-----+----------------+-----------------+----------------+
| content | 3 | tstr / uint | CoAP Content- |Content type of | | content | 3 | tstr / uint | CoAP Content- |Content type of |
| type | | |Formats or Media | the payload | | type | | |Formats or Media | the payload |
| | | |Types registries | | | | | |Types registries | |
+---------+-----+----------------+-----------------+----------------+ +---------+-----+----------------+-----------------+----------------+
| kid | 4 | bstr | | Key identifier | | kid | 4 | bstr | | Key identifier |
+---------+-----+----------------+-----------------+----------------+ +---------+-----+----------------+-----------------+----------------+
| IV | 5 | bstr | | Full | | IV | 5 | bstr | | Full |
| | | | | Initialization | | | | | | Initialization |
| | | | | Vector | | | | | | Vector |
skipping to change at page 17, line 39 skipping to change at page 17, line 50
| IV | | | | Initialization | | IV | | | | Initialization |
| | | | | Vector | | | | | | Vector |
+---------+-----+----------------+-----------------+----------------+ +---------+-----+----------------+-----------------+----------------+
| counter | 7 |COSE_Signature /| | CBOR-encoded | | counter | 7 |COSE_Signature /| | CBOR-encoded |
|signature| | [+ | | signature | |signature| | [+ | | signature |
| | |COSE_Signature ]| | structure | | | |COSE_Signature ]| | structure |
+---------+-----+----------------+-----------------+----------------+ +---------+-----+----------------+-----------------+----------------+
Table 3: Common Header Parameters Table 3: Common Header Parameters
The CDDL fragment that represents the set of headers defined in this The CDDL fragment that represents the set of header parameters
section is given below. Each of the headers is tagged as optional defined in this section is given below. Each of the header
because they do not need to be in every map; headers required in parameters is tagged as optional because they do not need to be in
specific maps are discussed above. every map; header parameters required in specific maps are discussed
above.
Generic_Headers = ( Generic_Headers = (
? 1 => int / tstr, ; algorithm identifier ? 1 => int / tstr, ; algorithm identifier
? 2 => [+label], ; criticality ? 2 => [+label], ; criticality
? 3 => tstr / int, ; content type ? 3 => tstr / int, ; content type
? 4 => bstr, ; key identifier ? 4 => bstr, ; key identifier
? 5 => bstr, ; IV ? 5 => bstr, ; IV
? 6 => bstr, ; Partial IV ? 6 => bstr, ; Partial IV
? 7 => COSE_Signature / [+COSE_Signature] ; Counter signature ? 7 => COSE_Signature / [+COSE_Signature] ; Counter signature
) )
skipping to change at page 18, line 27 skipping to change at page 18, line 29
COSE supports two different signature structures. COSE_Sign allows COSE supports two different signature structures. COSE_Sign allows
for one or more signatures to be applied to the same content. for one or more signatures to be applied to the same content.
COSE_Sign1 is restricted to a single signer. The structures cannot COSE_Sign1 is restricted to a single signer. The structures cannot
be converted between each other; as the signature computation be converted between each other; as the signature computation
includes a parameter identifying which structure is being used, the includes a parameter identifying which structure is being used, the
converted structure will fail signature validation. converted structure will fail signature validation.
4.1. Signing with One or More Signers 4.1. Signing with One or More Signers
The COSE_Sign structure allows for one or more signatures to be The COSE_Sign structure allows for one or more signatures to be
applied to a message payload. Parameters relating to the content and applied to a message payload. Header parameters relating to the
parameters relating to the signature are carried along with the content and header parameters relating to the signature are carried
signature itself. These parameters may be authenticated by the along with the signature itself. These header parameters may be
signature, or just present. An example of a parameter about the authenticated by the signature, or just present. An example of
content is the content type. Examples of parameters about the header a parameter about the content is the content type. Examples
signature would be the algorithm and key used to create the signature of a header parameters about the signature would be the algorithm and
and counter signatures. key used to create the signature and counter signatures.
RFC 5652 indicates that: RFC 5652 indicates that:
| When more than one signature is present, the successful validation | When more than one signature is present, the successful validation
| of one signature associated with a given signer is usually treated | of one signature associated with a given signer is usually treated
| as a successful signature by that signer. However, there are some | as a successful signature by that signer. However, there are some
| application environments where other rules are needed. An | application environments where other rules are needed. An
| application that employs a rule other than one valid signature for | application that employs a rule other than one valid signature for
| each signer must specify those rules. Also, where simple matching | each signer must specify those rules. Also, where simple matching
| of the signer identifier is not sufficient to determine whether | of the signer identifier is not sufficient to determine whether
skipping to change at page 19, line 44 skipping to change at page 19, line 48
the payload is transported separately ("detached content"), then a the payload is transported separately ("detached content"), then a
nil CBOR object is placed in this location, and it is the nil CBOR object is placed in this location, and it is the
responsibility of the application to ensure that it will be responsibility of the application to ensure that it will be
transported without changes. transported without changes.
Note: When a signature with a message recovery algorithm is used Note: When a signature with a message recovery algorithm is used
(Section 9.1), the maximum number of bytes that can be recovered (Section 9.1), the maximum number of bytes that can be recovered
is the length of the payload. The size of the payload is reduced is the length of the payload. The size of the payload is reduced
by the number of bytes that will be recovered. If all of the by the number of bytes that will be recovered. If all of the
bytes of the payload are consumed, then the payload is encoded as bytes of the payload are consumed, then the payload is encoded as
a zero-length binary string rather than as being absent. a zero-length byte string rather than as being absent.
signatures: This field is an array of signatures. Each signature is signatures: This field is an array of signatures. Each signature is
represented as a COSE_Signature structure. represented as a COSE_Signature structure.
The CDDL fragment that represents the above text for COSE_Sign The CDDL fragment that represents the above text for COSE_Sign
follows. follows.
COSE_Sign = [ COSE_Sign = [
Headers, Headers,
payload : bstr / nil, payload : bstr / nil,
skipping to change at page 20, line 33 skipping to change at page 20, line 36
follows. follows.
COSE_Signature = [ COSE_Signature = [
Headers, Headers,
signature : bstr signature : bstr
] ]
4.2. Signing with One Signer 4.2. Signing with One Signer
The COSE_Sign1 signature structure is used when only one signature is The COSE_Sign1 signature structure is used when only one signature is
going to be placed on a message. The parameters dealing with the going to be placed on a message. The header parameters dealing with
content and the signature are placed in the same pair of buckets the content and the signature are placed in the same pair of buckets
rather than having the separation of COSE_Sign. rather than having the separation of COSE_Sign.
The structure can be encoded as either tagged or untagged depending The structure can be encoded as either tagged or untagged depending
on the context it will be used in. A tagged COSE_Sign1 structure is on the context it will be used in. A tagged COSE_Sign1 structure is
identified by the CBOR tag 18. The CDDL fragment that represents identified by the CBOR tag 18. The CDDL fragment that represents
this is: this is:
COSE_Sign1_Tagged = #6.18(COSE_Sign1) COSE_Sign1_Tagged = #6.18(COSE_Sign1)
The CBOR object that carries the body, the signature, and the The CBOR object that carries the body, the signature, and the
skipping to change at page 21, line 29 skipping to change at page 21, line 34
] ]
4.3. Externally Supplied Data 4.3. Externally Supplied Data
One of the features offered in the COSE document is the ability for One of the features offered in the COSE document is the ability for
applications to provide additional data to be authenticated, but that applications to provide additional data to be authenticated, but that
is not carried as part of the COSE object. The primary reason for is not carried as part of the COSE object. The primary reason for
supporting this can be seen by looking at the CoAP message structure supporting this can be seen by looking at the CoAP message structure
[RFC7252], where the facility exists for options to be carried before [RFC7252], where the facility exists for options to be carried before
the payload. Examples of data that can be placed in this location the payload. Examples of data that can be placed in this location
would be the CoAP code or CoAP options. If the data is in the header would be the CoAP code or CoAP options. If the data is in the
section, then it is available for proxies to help in performing its headers of the CoAP message, then it is available for proxies to help
operations. For example, the Accept Option can be used by a proxy to in performing its operations. For example, the Accept Option can be
determine if an appropriate value is in the proxy's cache. But the used by a proxy to determine if an appropriate value is in the
sender can cause a failure at the server if a proxy, or an attacker, proxy's cache. But the sender can cause a failure at the server if a
changes the set of accept values by including the field in the proxy, or an attacker, changes the set of accept values by including
application supplied data. the field in the application supplied data.
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:
* If multiple items are included, applications need to ensure that * 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 would occur by appending the strings 'AB' and 'CDE' inputs. This would occur by appending the text strings 'AB' and
or by appending the strings 'ABC' and 'DE'. This is usually 'CDE' or by appending the text strings 'ABC' and 'DE'. This is
addressed by making fields a fixed width and/or encoding the usually addressed by making fields a fixed width and/or encoding
length of the field as part of the output. Using options from 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 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.
* If multiple items are included, an order for the items needs to be * 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.
* Applications need to ensure that the byte string is going to be * Applications need to ensure that the byte string is going to be
the same on both sides. Using options from CoAP might give a the same on both sides. Using options from CoAP might give a
skipping to change at page 22, line 27 skipping to change at page 22, line 31
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_structure 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_structure 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 context text string identifying the context of the signature.
context string is: The context text 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.
"CounterSignature0" for signatures used as CounterSignature0 "CounterSignature0" for signatures used as CounterSignature0
attributes. attributes.
skipping to change at page 22, line 51 skipping to change at page 23, line 7
bstr type. If there are no protected attributes, a bstr of bstr type. If there are no protected attributes, a bstr of
length zero is used. length zero is used.
3. The protected attributes from the signer structure encoded in a 3. The protected attributes from the signer structure encoded in a
bstr type. If there are no protected attributes, a bstr of bstr type. If there are no protected attributes, a bstr of
length zero is used. This field is omitted for the COSE_Sign1 length zero is used. This field is omitted for the COSE_Sign1
signature structure and CounterSignature0 attributes. signature structure and CounterSignature0 attributes.
4. The protected attributes from the application encoded in a bstr 4. The protected attributes from the application encoded in a bstr
type. If this field is not supplied, it defaults to a zero- type. If this field is not supplied, it defaults to a zero-
length binary string. (See Section 4.3 for application guidance length byte string. (See Section 4.3 for application guidance on
on constructing this field.) constructing this field.)
5. The payload to be signed encoded in a bstr type. The payload is 5. The payload to be signed encoded in a bstr type. The payload is
placed here independent of how it is transported. placed here independent of how it is transported.
The CDDL fragment that describes the above text is: The CDDL fragment that describes the above text is:
Sig_structure = [ Sig_structure = [
context : "Signature" / "Signature1" / "CounterSignature" / context : "Signature" / "Signature1" / "CounterSignature" /
"CounterSignature0", "CounterSignature0",
body_protected : empty_or_serialized_map, body_protected : empty_or_serialized_map,
skipping to change at page 23, line 38 skipping to change at page 23, line 43
sign with), alg (the algorithm to sign with), and ToBeSigned (the sign with), alg (the algorithm to sign with), and ToBeSigned (the
value to sign). value to sign).
4. Place the resulting signature value in the correct location. 4. Place the resulting signature value in the correct location.
This is the 'signature' field of the COSE_Signature, COSE_Sign1 This is the 'signature' field of the COSE_Signature, COSE_Sign1
or COSE_Countersignature structures. This is the value of the or COSE_Countersignature structures. This is the value of the
Countersignature0 attribute. Countersignature0 attribute.
The steps for verifying a signature are: The steps for verifying a signature are:
1. Create a Sig_structure object and populate it with the 1. Create a Sig_structure and populate it with the appropriate
appropriate fields. fields.
2. Create the value ToBeSigned by encoding the Sig_structure to a 2. Create the value ToBeSigned by encoding the Sig_structure to a
byte string, using the encoding described in Section 10. byte string, using the encoding described in Section 10.
3. Call the signature verification algorithm passing in K (the key 3. Call the signature verification algorithm passing in K (the key
to verify with), alg (the algorithm used sign with), ToBeSigned to verify with), alg (the algorithm used sign with), ToBeSigned
(the value to sign), and sig (the signature to be verified). (the value to sign), and sig (the signature to be verified).
In addition to performing the signature verification, the application In addition to performing the signature verification, the application
performs the appropriate checks to ensure that the key is correctly performs the appropriate checks to ensure that the key is correctly
skipping to change at page 24, line 18 skipping to change at page 24, line 23
countersignatures use the structure COSE_Countersign. This is same countersignatures use the structure COSE_Countersign. This is same
structure as COSE_Signature and thus it can have protected structure as COSE_Signature and thus it can have protected
attributes, chained countersignatures and information about attributes, chained countersignatures and information about
identifying the key. Abbreviated countersignatures use the structure identifying the key. Abbreviated countersignatures use the structure
COSE_Countersign1. This structure only contains the signature value COSE_Countersign1. This structure only contains the signature value
and nothing else. The structures cannot be converted between each and nothing else. The structures cannot be converted between each
other; as the signature computation includes a parameter identifying other; as the signature computation includes a parameter identifying
which structure is being used, the converted structure will fail which structure is being used, the converted structure will fail
signature validation. signature validation.
COSE was designed for uniformity in how the data strutures are COSE was designed for uniformity in how the data structures are
specified. One result of this is that for COSE one can expand the specified. One result of this is that for COSE one can expand the
concept of countersignatures beyond just the idea of signing a concept of countersignatures beyond just the idea of signing a
signature to being able to sign most of the structures without having signature to being able to sign most of the structures without having
to create a new signing layer. When creating a countersignature, one to create a new signing layer. When creating a countersignature, one
needs to be clear about the security properties that result. When needs to be clear about the security properties that result. When
done on a COSE_Signature, the normal countersignature semantics are done on a COSE_Signature, the normal countersignature semantics are
preserved. That is the countersignature makes a statement about the preserved. That is the countersignature makes a statement about the
existence of a signature and, when used as a timestamp, a time point existence of a signature and, when used as a timestamp, a time point
at which the signature exists. When done on a COSE_Mac or a at which the signature exists. When done on a COSE_Mac or a
COSE_Mac0, one effectively upgrades the MAC operation to a signature COSE_Mac0, one effectively upgrades the MAC operation to a signature
skipping to change at page 25, line 41 skipping to change at page 25, line 44
know who originated the message. The objective was to keep the know who originated the message. The objective was to keep the
countersignature as small as possible while still providing the countersignature as small as possible while still providing the
needed security. For abbreviated countersignatures, there is no needed security. For abbreviated countersignatures, there is no
provision for any protected attributes related to the signing provision for any protected attributes related to the signing
operation. Instead, the parameters for computing or verifying the operation. Instead, the parameters for computing or verifying the
abbreviated countersignature are inferred from the same context used abbreviated countersignature are inferred from the same context used
to describe the encryption, signature, or MAC processing. to describe the encryption, signature, or MAC processing.
The byte string representing the signature value is placed in the The byte string representing the signature value is placed in the
CounterSignature0 attribute. This attribute is then encoded as an CounterSignature0 attribute. This attribute is then encoded as an
unprotected header. The attribute is defined below. unprotected header parameter. The attribute is defined below.
The process of creating and validating abbreviated countersignatures The process of creating and validating abbreviated countersignatures
is defined in Section 4.4. is defined in Section 4.4.
+-------------------+-------+------------+-------+------------------+ +-------------------+-------+------------+-------+------------------+
| Name | Label | Value | Value | Description | | Name | Label | Value | Value | Description |
| | | Type | | | | | | Type | | |
+===================+=======+============+=======+==================+ +===================+=======+============+=======+==================+
| CounterSignature0 | 9 | bstr | | Abbreviated | | CounterSignature0 | 9 | bstr | | Abbreviated |
| | | | | Countersignature | | | | | | Countersignature |
skipping to change at page 26, line 27 skipping to change at page 26, line 27
COSE supports two different encryption structures. COSE_Encrypt0 is COSE supports two different encryption structures. COSE_Encrypt0 is
used when a recipient structure is not needed because the key to be used when a recipient structure is not needed because the key to be
used is known implicitly. COSE_Encrypt is used the rest of the time. used is known implicitly. COSE_Encrypt is used the rest of the time.
This includes cases where there are multiple recipients or a This includes cases where there are multiple recipients or a
recipient algorithm other than direct (i.e. pre-shared secret) is recipient algorithm other than direct (i.e. pre-shared secret) is
used. used.
6.1. Enveloped COSE Structure 6.1. Enveloped COSE Structure
The enveloped structure allows for one or more recipients of a The enveloped structure allows for one or more recipients of a
message. There are provisions for parameters about the content and message. There are provisions for header parameters about the
parameters about the recipient information to be carried in the content and header parameters about the recipient information to be
message. The protected parameters associated with the content are carried in the message. The protected header parameters associated
authenticated by the content encryption algorithm. The protected with the content are authenticated by the content encryption
parameters associated with the recipient are authenticated by the algorithm. The protected header parameters associated with the
recipient algorithm (when the algorithm supports it). Examples of recipient are authenticated by the recipient algorithm (when the
parameters about the content are the type of the content and the algorithm supports it). Examples of header parameters about the
content encryption algorithm. Examples of parameters about the content are the type of the content and the content encryption
recipient are the recipient's key identifier and the recipient's algorithm. Examples of header parameters about the recipient are the
encryption algorithm. recipient's key identifier and the recipient's encryption algorithm.
The same techniques and nearly the same structure is used for The same techniques and nearly the same structure is used for
encrypting both the plaintext and the keys. This is different from encrypting both the plaintext and the keys. This is different from
the approach used by both "Cryptographic Message Syntax (CMS)" the approach used by both "Cryptographic Message Syntax (CMS)"
[RFC5652] and "JSON Web Encryption (JWE)" [RFC7516] where different [RFC5652] and "JSON Web Encryption (JWE)" [RFC7516] where different
structures are used for the content layer and for the recipient structures are used for the content layer and for the recipient
layer. Two structures are defined: COSE_Encrypt to hold the layer. Two structures are defined: COSE_Encrypt to hold the
encrypted content and COSE_recipient to hold the encrypted keys for encrypted content and COSE_recipient to hold the encrypted keys for
recipients. Examples of encrypted messages can be found in recipients. Examples of encrypted messages can be found in
Appendix C.3. Appendix C.3.
skipping to change at page 29, line 34 skipping to change at page 29, line 34
] ]
6.3. How to Encrypt and Decrypt for AEAD Algorithms 6.3. How to Encrypt and Decrypt for AEAD Algorithms
The encryption algorithm for AEAD algorithms is fairly simple. The The encryption algorithm for AEAD algorithms is fairly simple. The
first step is to create a consistent byte string for the first step is to create a consistent byte string for the
authenticated data structure. For this purpose, we use an authenticated data structure. For this purpose, we use an
Enc_structure. The Enc_structure is a CBOR array. The fields of the Enc_structure. The Enc_structure is a CBOR array. The fields of the
Enc_structure in order are: Enc_structure in order are:
1. A text string identifying the context of the authenticated data 1. A context text string identifying the context of the
structure. The context string is: authenticated data structure. The context text string is:
"Encrypt0" for the content encryption of a COSE_Encrypt0 data "Encrypt0" for the content encryption of a COSE_Encrypt0 data
structure. structure.
"Encrypt" for the first layer of a COSE_Encrypt data structure "Encrypt" for the first layer of a COSE_Encrypt data structure
(i.e., for content encryption). (i.e., for content encryption).
"Enc_Recipient" for a recipient encoding to be placed in an "Enc_Recipient" for a recipient encoding to be placed in an
COSE_Encrypt data structure. COSE_Encrypt data structure.
skipping to change at page 30, line 48 skipping to change at page 30, line 48
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 6.1.2 and Examples of these algorithms are found in Sections 6.1.2 and
6.3 of [I-D.ietf-cose-rfc8152bis-algs]. 6.3 of [I-D.ietf-cose-rfc8152bis-algs].
Other: The key is randomly or pseudorandomly generated. Other: The key is randomly or pseudo-randomly 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.
How to decrypt a message: How to decrypt a message:
skipping to change at page 35, line 22 skipping to change at page 35, line 22
tag : bstr, tag : bstr,
] ]
7.3. How to Compute and Verify a MAC 7.3. How to Compute and Verify a MAC
In order to get a consistent encoding of the data to be In order to get a consistent encoding of the data to be
authenticated, the MAC_structure is used to have a canonical form. authenticated, the MAC_structure is used to have a canonical form.
The MAC_structure is a CBOR array. The fields of the MAC_structure The MAC_structure is a CBOR array. The fields of the MAC_structure
in order are: in order are:
1. A text string that identifies the structure that is being 1. A context text string that identifies the structure that is being
encoded. This string is "MAC" for the COSE_Mac structure. This encoded. This context text string is "MAC" for the COSE_Mac
string is "MAC0" for the COSE_Mac0 structure. structure. This context text string is "MAC0" for the COSE_Mac0
structure.
2. The protected attributes from the COSE_MAC structure. If there 2. The protected attributes from the COSE_MAC structure. If there
are no protected attributes, a zero-length bstr is used. are no protected attributes, a zero-length bstr is used.
3. The protected attributes from the application encoded as a bstr 3. The protected attributes from the application encoded as a bstr
type. If this field is not supplied, it defaults to a zero- type. If this field is not supplied, it defaults to a zero-
length binary string. (See Section 4.3 for application guidance length byte string. (See Section 4.3 for application guidance on
on constructing this field.) constructing this field.)
4. The payload to be MACed encoded in a bstr type. The payload is 4. The payload to be MACed encoded in a bstr type. The payload is
placed here independent of how it is transported. placed here independent of how it is transported.
The CDDL fragment that corresponds to the above text is: The CDDL fragment that corresponds to the above text is:
MAC_structure = [ MAC_structure = [
context : "MAC" / "MAC0", context : "MAC" / "MAC0",
protected : empty_or_serialized_map, protected : empty_or_serialized_map,
external_aad : bstr, external_aad : bstr,
skipping to change at page 36, line 17 skipping to change at page 36, line 20
compute the MAC on). compute the MAC on).
4. Place the resulting MAC in the 'tag' field of the COSE_Mac or 4. Place the resulting MAC in the 'tag' field of the COSE_Mac or
COSE_Mac0 structure. COSE_Mac0 structure.
5. For COSE_Mac structures, encrypt and encode the MAC key for each 5. For COSE_Mac structures, encrypt and encode the MAC key for each
recipient of the message. recipient of the message.
The steps to verify a MAC are: The steps to verify a MAC are:
1. Create a MAC_structure object and populate it with the 1. Create a MAC_structure and populate it with the appropriate
appropriate fields. fields.
2. Create the value ToBeMaced by encoding the MAC_structure to a 2. Create the value ToBeMaced by encoding the MAC_structure to a
byte string, using the encoding described in Section 10. byte string, using the encoding described in Section 10.
3. For COSE_Mac structures, obtain the cryptographic key from one of 3. For COSE_Mac structures, obtain the cryptographic key from one of
the recipients of the message. the recipients of the message.
4. Call the MAC creation algorithm passing in K (the key to use), 4. Call the MAC creation algorithm passing in K (the key to use),
alg (the algorithm to MAC with), and ToBeMaced (the value to alg (the algorithm to MAC with), and ToBeMaced (the value to
compute the MAC on). compute the MAC on).
5. Compare the MAC value to the 'tag' field of the COSE_Mac or 5. Compare the MAC value to the 'tag' field of the COSE_Mac or
COSE_Mac0 structure. COSE_Mac0 structure.
8. Key Objects 8. Key Objects
A COSE Key structure is built on a CBOR map object. The set of A COSE Key structure is built on a CBOR map. The set of common
common parameters that can appear in a COSE Key can be found in the parameters that can appear in a COSE Key can be found in the IANA
IANA "COSE Key Common Parameters" registry (Section 12.4). "COSE Key Common Parameters" registry (Section 12.4). Additional
Additional parameters defined for specific key types can be found in parameters defined for specific key types can be found in the IANA
the IANA "COSE Key Type Parameters" registry ([COSE.KeyParameters]). "COSE Key Type Parameters" registry ([COSE.KeyParameters]).
A COSE Key Set uses a CBOR array object as its underlying type. The A COSE Key Set uses a CBOR array object as its underlying type. The
values of the array elements are COSE Keys. A COSE Key Set MUST have values of the array elements are COSE Keys. A COSE Key Set MUST have
at least one element in the array. Examples of COSE Key Sets can be at least one element in the array. Examples of COSE Key Sets can be
found in Appendix C.7. found in Appendix C.7.
Each element in a COSE Key Set MUST be processed independently. If Each element in a COSE Key Set MUST be processed independently. If
one element in a COSE Key Set is either malformed or uses a key that one element in a COSE Key Set is either malformed or uses a key that
is not understood by an application, that key is ignored and the is not understood by an application, that key is ignored and the
other keys are processed normally. other keys are processed normally.
skipping to change at page 38, line 25 skipping to change at page 38, line 25
the application MUST verify that this algorithm matches the the application MUST verify that this algorithm matches the
algorithm for which the key is being used. If the algorithms do algorithm for which the key is being used. If the algorithms do
not match, then this key object MUST NOT be used to perform the not match, then this key object MUST NOT be used to perform the
cryptographic operation. Note that the same key can be in a cryptographic operation. Note that the same key can be in a
different key structure with a different or no algorithm different key structure with a different or no algorithm
specified; however, this is considered to be a poor security specified; however, this is considered to be a poor security
practice. practice.
kid: This parameter is used to give an identifier for a key. The kid: This parameter is used to give an identifier for a key. The
identifier is not structured and can be anything from a user- identifier is not structured and can be anything from a user-
provided string to a value computed on the public portion of the provided byte string to a value computed on the public portion of
key. This field is intended for matching against a 'kid' the key. This field is intended for matching against a 'kid'
parameter in a message in order to filter down the set of keys parameter in a message in order to filter down the set of keys
that need to be checked. that need to be checked.
key_ops: This parameter is defined to restrict the set of operations key_ops: This parameter is defined to restrict the set of operations
that a key is to be used for. The value of the field is an array that a key is to be used for. The value of the field is an array
of values from Table 6. Algorithms define the values of key ops of values from Table 6. Algorithms define the values of key ops
that are permitted to appear and are required for specific that are permitted to appear and are required for specific
operations. The set of values matches that in [RFC7517] and operations. The set of values matches that in [RFC7517] and
[W3C.WebCrypto]. [W3C.WebCrypto].
skipping to change at page 40, line 7 skipping to change at page 40, line 7
9. Taxonomy of Algorithms used by COSE 9. Taxonomy of Algorithms used by COSE
In this section, a taxonomy of the different algorithm types that can In this section, a taxonomy of the different algorithm types that can
be used in COSE is laid out. This taxonomy should not be considered be used in COSE is laid out. This taxonomy should not be considered
to be exhaustive as there are new algorithm structures that could be to be exhaustive as there are new algorithm structures that could be
found or are not known to the author. found or are not known to the author.
9.1. Signature Algorithms 9.1. Signature Algorithms
Signature algorithms provide data origination and data integrity
services. Data origination provides the ability to infer who
originated the data based on who signed the data. Data integrity
provides the ability to verify that the data has not been modified
since it was signed.
There are two signature algorithm schemes. The first is signature There are two signature algorithm schemes. The first is signature
with appendix. In this scheme, the message content is processed and with appendix. In this scheme, the message content is processed and
a signature is produced; the signature is called the appendix. This a signature is produced; the signature is called the appendix. This
is the scheme used by algorithms such as ECDSA and the RSA is the scheme used by algorithms such as ECDSA and the RSA
Probabilistic Signature Scheme (RSASSA-PSS). (In fact, the SSA in Probabilistic Signature Scheme (RSASSA-PSS). (In fact, the SSA in
RSASSA-PSS stands for Signature Scheme with Appendix.) RSASSA-PSS stands for Signature Scheme with Appendix.)
The signature functions for this scheme are: The signature functions for this scheme are:
signature = Sign(message content, key) signature = Sign(message content, key)
skipping to change at page 43, line 18 skipping to change at page 43, line 28
sender and the recipient that is used either directly or after sender and the recipient that is used either directly or after
manipulation as the CEK. When direct encryption mode is used, it manipulation as the CEK. When direct encryption mode is used, it
MUST be the only mode used on the message. MUST be the only mode used on the message.
The COSE_Recipient structure for the recipient is organized as The COSE_Recipient structure for the recipient is organized as
follows: follows:
* The 'protected' field MUST be a zero-length item unless it is used * The 'protected' field MUST be a zero-length item unless it is used
in the computation of the content key. in the computation of the content key.
* The 'alg' parameter MUST be present. * The 'alg' header parameter MUST be present.
* A parameter identifying the shared secret SHOULD be present. * A header parameter identifying the shared secret SHOULD be
present.
* The 'ciphertext' field MUST be a zero-length item. * The 'ciphertext' field MUST be a zero-length item.
* The 'recipients' field MUST be absent. * The 'recipients' field MUST be absent.
9.5.2. Key Wrap 9.5.2. Key Wrap
In key wrap mode, the CEK is randomly generated and that key is then In key wrap mode, the CEK is randomly generated and that key is then
encrypted by a shared secret between the sender and the recipient. encrypted by a shared secret between the sender and the recipient.
All of the currently defined key wrap algorithms for COSE are AE All of the currently defined key wrap algorithms for COSE are AE
skipping to change at page 44, line 6 skipping to change at page 44, line 18
* The 'recipients' field is normally absent, but can be used. * The 'recipients' field is normally absent, but can be used.
Applications MUST deal with a recipient field being present that Applications MUST deal with a recipient field being present that
has an unsupported algorithm, not being able to decrypt that has an unsupported algorithm, not being able to decrypt that
recipient is an acceptable way of dealing with it. Failing to recipient is an acceptable way of dealing with it. Failing to
process the message is not an acceptable way of dealing with it. process the message is not an acceptable way of dealing with it.
* The plaintext to be encrypted is the key from next layer down * The plaintext to be encrypted is the key from next layer down
(usually the content layer). (usually the content layer).
* At a minimum, the 'unprotected' field MUST contain the 'alg' * At a minimum, the 'unprotected' field MUST contain the 'alg'
parameter and SHOULD contain a parameter identifying the shared header parameter and SHOULD contain a header parameter identifying
secret. the shared secret.
9.5.3. Key Transport 9.5.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. A set of key transport encryption algorithm to protect the key. A set of key transport
algorithms are defined in [RFC8230]. 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:
* The 'protected' field MUST be absent. * The 'protected' field MUST be absent.
* The plaintext to be encrypted is the key from the next layer down * The plaintext to be encrypted is the key from the next layer down
(usually the content layer). (usually the content layer).
* At a minimum, the 'unprotected' field MUST contain the 'alg' * At a minimum, the 'unprotected' field MUST contain the 'alg'
parameter and SHOULD contain a parameter identifying the header parameter and SHOULD contain a parameter identifying the
asymmetric key. asymmetric key.
9.5.4. Direct Key Agreement 9.5.4. Direct Key Agreement
The 'direct key agreement' class of recipient algorithms uses a key The 'direct key agreement' class of recipient algorithms uses a key
agreement method to create a shared secret. A KDF is then applied to agreement method to create a shared secret. A KDF is then applied to
the shared secret to derive a key to be used in protecting the data. the shared secret to derive a key to be used in protecting the data.
This key is normally used as a CEK or MAC key, but could be used for This key is normally used as a CEK or MAC key, but could be used for
other purposes if more than two layers are in use (see Appendix B). other purposes if more than two layers are in use (see Appendix B).
skipping to change at page 45, line 20 skipping to change at page 45, line 30
different key is created for each message. different key is created for each message.
When direct key agreement mode is used, there MUST be only one When direct key agreement mode is used, there MUST be only one
recipient in the message. This method creates the key directly, and recipient in the message. This method creates the key directly, and
that makes it difficult to mix with additional recipients. If that makes it difficult to mix with additional recipients. If
multiple recipients are needed, then the version with key wrap needs multiple recipients are needed, then the version with key wrap needs
to be used. to be used.
The COSE_Encrypt structure for the recipient is organized as follows: The COSE_Encrypt structure for the recipient is organized as follows:
* At a minimum, headers MUST contain the 'alg' parameter and SHOULD * At a minimum, headers MUST contain the 'alg' header parameter and
contain a parameter identifying the recipient's asymmetric key. SHOULD contain a header parameter identifying the recipient's
asymmetric key.
* The headers SHOULD identify the sender's key for the static-static * The headers SHOULD identify the sender's key for the static-static
versions and MUST contain the sender's ephemeral key for the versions and MUST contain the sender's ephemeral key for the
ephemeral-static versions. ephemeral-static versions.
9.5.5. Key Agreement with Key Wrap 9.5.5. Key Agreement with Key Wrap
Key Agreement with Key Wrap uses a randomly generated CEK. The CEK Key Agreement with Key Wrap uses a randomly generated CEK. The CEK
is then encrypted using a key wrap algorithm and a key derived from is then encrypted using a key wrap algorithm and a key derived from
the shared secret computed by the key agreement algorithm. The the shared secret computed by the key agreement algorithm. The
skipping to change at page 45, line 43 skipping to change at page 46, line 8
encryptedKey = KeyWrap(KDF(DH-Shared, context), CEK) encryptedKey = KeyWrap(KDF(DH-Shared, context), CEK)
The COSE_Encrypt structure for the recipient is organized as follows: The COSE_Encrypt structure for the recipient is organized as follows:
* The 'protected' field is fed into the KDF context structure. * The 'protected' field is fed into the KDF context structure.
* The plaintext to be encrypted is the key from the next layer down * The plaintext to be encrypted is the key from the next layer down
(usually the content layer). (usually the content layer).
* The 'alg' parameter MUST be present in the layer. * The 'alg' header parameter MUST be present in the layer.
* A parameter identifying the recipient's key SHOULD be present. A * A header parameter identifying the recipient's key SHOULD be
parameter identifying the sender's key SHOULD be present. present. A header parameter identifying the sender's key SHOULD
be present.
10. CBOR Encoding Restrictions 10. CBOR Encoding Restrictions
There has been an attempt to limit the number of places where the There has been an attempt to limit the number of places where the
document needs to impose restrictions on how the CBOR Encoder needs document needs to impose restrictions on how the CBOR Encoder needs
to work. We have managed to narrow it down to the following to work. We have managed to narrow it down to the following
restrictions: restrictions:
* The restriction applies to the encoding of the Sig_structure, the * The restriction applies to the encoding of the Sig_structure, the
Enc_structure, and the MAC_structure. Enc_structure, and the MAC_structure.
skipping to change at page 47, line 4 skipping to change at page 47, line 14
* Applications need to determine the set of messages defined in this * Applications need to determine the set of messages defined in this
document that they will be using. The set of messages corresponds document that they will be using. The set of messages corresponds
fairly directly to the set of security services that are needed fairly directly to the set of security services that are needed
and to the security levels needed. and to the security levels needed.
* Applications may define new header parameters for a specific * Applications may define new header parameters for a specific
purpose. Applications will often times select specific header purpose. Applications will often times select specific header
parameters to use or not to use. For example, an application parameters to use or not to use. For example, an application
would normally state a preference for using either the IV or the would normally state a preference for using either the IV or the
Partial IV parameter. If the Partial IV parameter is specified, Partial IV header parameter. If the Partial IV header parameter
then the application also needs to define how the fixed portion of is specified, then the application also needs to define how the
the IV is determined. fixed portion of the IV is determined.
* When applications use externally defined authenticated data, they * When applications use externally defined authenticated data, they
need to define how that data is encoded. This document assumes need to define how that data is encoded. This document assumes
that the data will be provided as a byte string. More information that the data will be provided as a byte string. More information
can be found in Section 4.3. can be found in Section 4.3.
* Applications need to determine the set of security algorithms that * Applications need to determine the set of security algorithms that
are to be used. When selecting the algorithms to be used as the are to be used. When selecting the algorithms to be used as the
mandatory-to-implement set, consideration should be given to mandatory-to-implement set, consideration should be given to
choosing different types of algorithms when two are chosen for a choosing different types of algorithms when two are chosen for a
specific purpose. An example of this would be choosing HMAC- specific purpose. An example of this would be choosing HMAC-
SHA512 and AES-CMAC as different MAC algorithms; the construction SHA512 and AES-CMAC as different MAC algorithms; the construction
is vastly different between these two algorithms. This means that is vastly different between these two algorithms. This means that
a weakening of one algorithm would be unlikely to lead to a a weakening of one algorithm would be unlikely to lead to a
weakening of the other algorithms. Of course, these algorithms do weakening of the other algorithms. Of course, these algorithms do
not provide the same level of security and thus may not be not provide the same level of security and thus may not be
comparable for the desired security functionality. comparable for the desired security functionality.
* Applications may need to provide some type of negotiation or * Applications may need to provide some type of negotiation or
discovery method if multiple algorithms or message structures are discovery method if multiple algorithms or message structures are
permitted. The method can be as simple as requiring permitted. The method can be as simple as requiring pre-
preconfiguration of the set of algorithms to providing a discovery configuration of the set of algorithms to providing a discovery
method built into the protocol. S/MIME provided a number of method built into the protocol. S/MIME provided a number of
different ways to approach the problem that applications could different ways to approach the problem that applications could
follow: follow:
- Advertising in the message (S/MIME capabilities) [RFC5751]. - Advertising in the message (S/MIME capabilities) [RFC5751].
- Advertising in the certificate (capabilities extension) - Advertising in the certificate (capabilities extension)
[RFC4262]. [RFC4262].
- Minimum requirements for the S/MIME, which have been updated - Minimum requirements for the S/MIME, which have been updated
over time [RFC2633] [RFC5751] (note that [RFC2633] has been over time [RFC2633] [RFC5751] (note that [RFC2633] has been
obsoleted by [RFC5751]). obsoleted by [RFC5751]).
12. IANA Considerations 12. IANA Considerations
The registeries and registrations listed below were created during The registries and registrations listed below were created during
processing of RFC 8152 [RFC8152]. The only known action at this time processing of RFC 8152 [RFC8152]. The only known action at this time
is to update the references. is to update the references.
12.1. CBOR Tag Assignment 12.1. CBOR Tag Assignment
IANA assigned tags in the "CBOR Tags" registry as part of processing IANA assigned tags in the "CBOR Tags" registry as part of processing
[RFC8152]. IANA is requested to update the references from [RFC8152] [RFC8152]. IANA is requested to update the references from [RFC8152]
to this document. to this document.
IANA is requested to register a new tag for the CounterSignature IANA is requested to register a new tag for the CounterSignature
skipping to change at page 53, line 39 skipping to change at page 53, line 44
* Is the cryptographic algorithm acceptable in the current context? * Is the cryptographic algorithm acceptable in the current context?
* Have the restrictions associated with the key, such as algorithm * Have the restrictions associated with the key, such as algorithm
or freshness, been checked and are they correct? or freshness, been checked and are they correct?
* Is the request something that is reasonable, given the current * Is the request something that is reasonable, given the current
state of the application? state of the application?
* Have any security considerations that are part of the message been * Have any security considerations that are part of the message been
enforced (as specified by the application or 'crit' parameter)? enforced (as specified by the application or 'crit' header
parameter)?
There are a large number of algorithms presented in There are a large number of algorithms presented in
[I-D.ietf-cose-rfc8152bis-algs] that use nonce values. Nonces [I-D.ietf-cose-rfc8152bis-algs] that use nonce values. Nonces
generally have some type of restriction on their values. Generally a generally have some type of restriction on their values. Generally a
nonce needs to be a unique value either for a key or for some other nonce needs to be a unique value either for a key or for some other
conditions. In all of these cases, there is no known requirement on conditions. In all of these cases, there is no known requirement on
the nonce being both unique and unpredictable; under these the nonce being both unique and unpredictable; under these
circumstances, it's reasonable to use a counter for creation of the circumstances, it's reasonable to use a counter for creation of the
nonce. In cases where one wants the pattern of the nonce to be nonce. In cases where one wants the pattern of the nonce to be
unpredictable as well as unique, one can use a key created for that unpredictable as well as unique, one can use a key created for that
purpose and encrypt the counter to produce the nonce value. purpose and encrypt the counter to produce the nonce value.
One area that has been starting to get exposure is doing traffic One area that has been starting to get exposure is doing traffic
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 messages (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 [I-D.ietf-cose-rfc8152bis-algs] algorithms that are defined in [I-D.ietf-cose-rfc8152bis-algs]
document. This means that it is up to the applications to document 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 how content padding is to be done in order to prevent or discourage
such analysis. (For example, the strings could be defined as 'YES' such analysis. (For example, the text strings could be defined as
and 'NO '.) 'YES' and 'NO '.)
14. Implementation Status 14. Implementation Status
This section is to be removed before publishing as an RFC. This section is to be removed before publishing as an RFC.
This section records the status of known implementations of the This section records the status of known implementations of the
protocol defined by this specification at the time of posting of this protocol defined by this specification at the time of posting of this
Internet-Draft, and is based on a proposal described in [RFC7942]. Internet-Draft, and is based on a proposal described in [RFC7942].
The description of implementations in this section is intended to The description of implementations in this section is intended to
assist the IETF in its decision processes in progressing drafts to assist the IETF in its decision processes in progressing drafts to
skipping to change at page 57, line 37 skipping to change at page 57, line 42
NIST.FIPS.186-4.pdf>. NIST.FIPS.186-4.pdf>.
[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,
<https://www.rfc-editor.org/info/rfc8032>. <https://www.rfc-editor.org/info/rfc8032>.
[I-D.ietf-cose-rfc8152bis-algs] [I-D.ietf-cose-rfc8152bis-algs]
Schaad, J., "CBOR Object Signing and Encryption (COSE): Schaad, J., "CBOR Object Signing and Encryption (COSE):
Initial Algorithms", Work in Progress, Internet-Draft, Initial Algorithms", Work in Progress, Internet-Draft,
draft-ietf-cose-rfc8152bis-algs-05, 11 September 2019, draft-ietf-cose-rfc8152bis-algs-06, 4 November 2019,
<https://tools.ietf.org/html/draft-ietf-cose-rfc8152bis- <https://tools.ietf.org/html/draft-ietf-cose-rfc8152bis-
algs-05>. algs-06>.
15.2. Informative References 15.2. Informative References
[RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)", [RFC8152] Schaad, J., "CBOR Object Signing and Encryption (COSE)",
RFC 8152, DOI 10.17487/RFC8152, July 2017, RFC 8152, DOI 10.17487/RFC8152, July 2017,
<https://www.rfc-editor.org/info/rfc8152>. <https://www.rfc-editor.org/info/rfc8152>.
[RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data
Definition Language (CDDL): A Notational Convention to Definition Language (CDDL): A Notational Convention to
Express Concise Binary Object Representation (CBOR) and Express Concise Binary Object Representation (CBOR) and
skipping to change at page 67, line 44 skipping to change at page 68, line 44
] ]
] ]
) )
C.1.3. Counter Signature C.1.3. Counter Signature
This example uses the following: This example uses the following:
* Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 * Signature Algorithm: ECDSA w/ SHA-256, Curve P-256
* The same parameters are used for both the signature and the * The same header parameters are used for both the signature and the
counter signature. counter signature.
Size of binary file is 180 bytes Size of binary file is 180 bytes
98( 98(
[ [
/ protected / h'', / protected / h'',
/ unprotected / { / unprotected / {
/ countersign / 7:[ / countersign / 7:[
/ protected / h'a10126' / { / protected / h'a10126' / {
\ alg \ 1:-7 \ ECDSA 256 \ \ alg \ 1:-7 \ ECDSA 256 \
 End of changes. 81 change blocks. 
255 lines changed or deleted 277 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/