RFC 9052

Internet Engineering Task Force (IETF) J. Schaad Request for Comments: 9052 August Cellars STD: 96 August 2022 Obsoletes: 8152
Category: Standards Track
ISSN: 2070-1721

CBOR Object Signing and Encryption (COSE): Structures and Process

Abstract

Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. There is a need to be able to define basic security services for this data format. This document defines the CBOR Object Signing and Encryption (COSE) protocol. This specification describes how to create and process signatures, message authentication codes, and encryption using CBOR for serialization. This specification additionally describes how to represent cryptographic keys using CBOR.

This document, along with RFC 9053, obsoletes RFC 8152.

Status of This Memo

This is an Internet Standards Track document.

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc9052.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.

Table of Contents

Introduction 1.1. Requirements Terminology 1.2. Changes from RFC 8152 1.3. Design Changes from JOSE 1.4. CDDL Grammar for CBOR Data Structures 1.5. CBOR-Related Terminology 1.6. Document Terminology
Basic COSE Structure
Header Parameters 3.1. Common COSE Header Parameters
Signing Objects 4.1. Signing with One or More Signers 4.2. Signing with One Signer 4.3. Externally Supplied Data 4.4. Signing and Verification Process
Encryption Objects 5.1. Enveloped COSE Structure 5.1.1. Content Key Distribution Methods 5.2. Single Recipient Encrypted 5.3. How to Encrypt and Decrypt for AEAD Algorithms 5.4. How to Encrypt and Decrypt for AE Algorithms
MAC Objects 6.1. MACed Message with Recipients 6.2. MACed Messages with Implicit Key 6.3. How to Compute and Verify a MAC
Key Objects 7.1. COSE Key Common Parameters
Taxonomy of Algorithms Used by COSE 8.1. Signature Algorithms 8.2. Message Authentication Code (MAC) Algorithms 8.3. Content Encryption Algorithms 8.4. Key Derivation Functions (KDFs) 8.5. Content Key Distribution Methods 8.5.1. Direct Encryption 8.5.2. Key Wrap 8.5.3. Key Transport 8.5.4. Direct Key Agreement 8.5.5. Key Agreement with Key Wrap
CBOR Encoding Restrictions
Application Profiling Considerations
IANA Considerations 11.1. COSE Header Parameters Registry 11.2. COSE Key Common Parameters Registry 11.3. Media Type Registrations 11.3.1. COSE Security Message 11.3.2. COSE Key Media Type 11.4. CoAP Content-Formats Registry 11.5. CBOR Tags Registry 11.6. Expert Review Instructions
Security Considerations
References 13.1. Normative References 13.2. Informative References Appendix A. Guidelines for External Data Authentication of Algorithms Appendix B. Two Layers of Recipient Information Appendix C. Examples C.1. Examples of Signed Messages C.1.1. Single Signature C.1.2. Multiple Signers C.1.3. Signature with Criticality C.2. Single Signer Examples C.2.1. Single ECDSA Signature C.3. Examples of Enveloped Messages C.3.1. Direct ECDH C.3.2. Direct Plus Key Derivation C.3.3. Encrypted Content with External Data C.4. Examples of Encrypted Messages C.4.1. Simple Encrypted Message C.4.2. Encrypted Message with a Partial IV C.5. Examples of MACed Messages C.5.1. Shared Secret Direct MAC C.5.2. ECDH Direct MAC C.5.3. Wrapped MAC C.5.4. Multi-Recipient MACed Message C.6. Examples of MAC0 Messages C.6.1. Shared-Secret Direct MAC C.7. COSE Keys C.7.1. Public Keys C.7.2. Private Keys Acknowledgments Author's Address
Introduction

There has been an increased focus on small, constrained devices that make up the Internet of Things (IoT). One of the standards that has come out of this process is "Concise Binary Object Representation (CBOR)" [STD94]. CBOR extended the data model of JavaScript Object Notation (JSON) [STD90] by allowing for binary data, among other changes. CBOR has been adopted by several of the IETF working groups dealing with the IoT world as their method of encoding data structures. CBOR was designed specifically to be small in terms of both messages transported and implementation size and to have a schema-free decoder. A need exists to provide message security services for IoT, and using CBOR as the message-encoding format makes sense.

The JOSE Working Group produced a set of documents [RFC7515] [RFC7516] [RFC7517] [RFC7518] that specified how to process encryption, signatures, and Message Authentication Code (MAC) operations and how to encode keys using JSON. This document defines the CBOR Object Signing and Encryption (COSE) standard, which does the same thing for the CBOR encoding format. This document is combined with [RFC9053], which provides an initial set of algorithms. While there is a strong attempt to keep the flavor of the original JSON Object Signing and Encryption (JOSE) documents, two considerations are taken into account:

CBOR has capabilities that are not present in JSON and are appropriate to use. One example of this is the fact that CBOR has a method of encoding binary data directly without first converting it into a base64-encoded text string.
COSE is not a direct copy of the JOSE specification. In the process of creating COSE, decisions that were made for JOSE were re-examined. In many cases, different results were decided on, as the criteria were not always the same.

This document contains:

The description of the structure for the CBOR objects that are transmitted over the wire. Two objects each are defined for encryption, signing, and message authentication. One object is defined for transporting keys and one for transporting groups of keys.
The procedures used to build the inputs to the cryptographic functions required for each of the structures.
A set of attributes that apply to the different security objects.

This document does not contain the rules and procedures for using specific cryptographic algorithms. Details on specific algorithms can be found in [RFC9053] and [RFC8230]. Details for additional algorithms are expected to be defined in future documents.

COSE was initially designed as part of a solution to provide security to Constrained RESTful Environments (CoRE), and this is done using [RFC8613] and [CORE-GROUPCOMM]. However, COSE is not restricted to just these cases and can be used in any place where one would consider either JOSE or Cryptographic Message Syntax (CMS) [RFC5652] for the purpose of providing security services. COSE, like JOSE and CMS, is only for use in store-and-forward or offline protocols. The use of COSE in online protocols needing encryption requires that an online key establishment process be done before sending objects back and forth. Any application that uses COSE for security services first needs to determine what security services are required and then select the appropriate COSE structures and cryptographic algorithms based on those needs. Section 10 provides additional information on what applications need to specify when using COSE.

One feature that is present in CMS that is not present in this standard is a digest structure. This omission is deliberate. It is better for the structure to be defined in each protocol as different protocols will want to include a different set of fields as part of the structure. While an algorithm identifier and the digest 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 multiple values. Applications may additionally want to define additional data fields as part of the structure. One such application-specific element would be to include a URI or other pointer to where the data that is being hashed can be obtained. [RFC9054] contains one such possible structure and defines a set of digest algorithms.

During the process of advancing COSE to Internet Standard, it was noticed that the description of the security properties of countersignatures was incorrect for the COSE_Sign1 structure. Since the security properties that were described -- those of a true countersignature -- were those that the working group desired, the decision was made to remove all of the countersignature text from this document and create a new document [COSE-COUNTERSIGN] to both deprecate the old countersignature algorithm and header parameters and define a new algorithm and header parameters with the desired security properties.

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 RFC 8152

Split the original document into this document and [RFC9053].
Added some text describing why there is no digest structure defined by COSE.
Made text clarifications and changes in terminology.
Removed all of the details relating to countersignatures and placed them in [COSE-COUNTERSIGN].

1.3. Design Changes from JOSE

A single overall message structure has been defined so that encrypted, signed, and MACed messages can easily be identified and still have a consistent view.
Signed messages distinguish between the protected and unprotected header parameters that relate to the content and those that relate to the signature.
MACed messages are separated from signed messages.
MACed messages have the ability to use the same set of recipient algorithms as enveloped messages for obtaining the MAC authentication key.
Binary encodings are used, rather than base64url encodings, to encode binary data.
The authentication tag for encryption algorithms has been combined with the ciphertext.
The set of cryptographic algorithms has been expanded in some directions and trimmed in others.

1.4. CDDL Grammar for CBOR Data Structures

When COSE was originally written, the Concise Data Definition Language (CDDL) [RFC8610] had not yet been published in an RFC, so it could not be used as the data description language to normatively describe the CBOR data structures employed by COSE. For that reason, the CBOR data objects defined here are described in prose. Additional (non-normative) descriptions of the COSE data objects are provided in a subset of CDDL, described below.

This document was developed by first working on the grammar and then developing the prose to go with it. An artifact of this is that the prose was written using the primitive-type strings defined by Concise Data Definition Language (CDDL) [RFC8610]. In this specification, the following primitive types are used:

any: A nonspecific value that permits all CBOR values to be placed here.

bool: A boolean value (true: major type 7, value 21; false: major type 7, value 20).

bstr: Byte string (major type 2).

int: An unsigned integer or a negative integer.

nil: A null value (major type 7, value 22).

nint: A negative integer (major type 1).

tstr: A UTF-8 text string (major type 3).

uint: An unsigned integer (major type 0).

Three syntaxes from CDDL appear in this document as shorthand. These are:

FOO / BAR: Indicates that either FOO or BAR can appear here.

[+ FOO]: Indicates that the type FOO appears one or more times in an array.

FOO: Indicates that the type FOO appears zero or more times.

Two of the constraints defined by CDDL are also used in this document. These are:

type1 .cbor type2: Indicates that the contents of type1, usually bstr, contains a value of type2.

type1 .size integer: Indicates that the contents of type1 is integer bytes long.

As well as the prose description, a grammar for the CBOR data structures is presented in the subset of CDDL described previously. The CDDL grammar is informational; the prose description is normative.

The collected CDDL can be extracted from the XML version of this document via the XPath expression below. (Depending on the XPath evaluator one is using, it may be necessary to deal with > as an entity.)

//sourcecode[@type='cddl']/text()

CDDL expects the initial nonterminal symbol to be the first symbol in the file. For this reason, the first fragment of CDDL is presented here.

start = COSE_Messages / COSE_Key / COSE_KeySet / Internal_Types

; This is defined to make the tool quieter: Internal_Types = Sig_structure / Enc_structure / MAC_structure

The nonterminal Internal_Types is defined for dealing with the automated validation tools used during the writing of this document. It references those nonterminals that are used for security computations but are not emitted for transport.

1.5. CBOR-Related Terminology

In JSON, maps are called objects and only have one kind of map key: a text string. In COSE, we use text strings, negative integers, and unsigned integers as map keys. The integers are used for compactness of encoding and easy comparison. The inclusion of text strings allows for an additional range of short encoded values to be used as well. Since the word "key" is mainly used in its other meaning, as a cryptographic key, we use the term "label" for this usage as a map key.

In a CBOR map defined by this specification, the presence a label that is neither a text string nor an integer is an error. Applications can either fail processing or process messages by ignoring incorrect labels; however, they MUST NOT create messages with incorrect labels.

A CDDL grammar fragment defines the nonterminal "label", as in the previous paragraph, and "values", which permits any value to be used.

label = int / tstr values = any

1.6. Document Terminology

In this document, we use the following terminology:

Byte: A synonym for octet.

Constrained Application Protocol (CoAP): A specialized web transfer protocol for use in constrained systems. It is defined in [RFC7252].

Authenticated Encryption (AE) algorithms [RFC5116]: Encryption algorithms that provide an authentication check of the contents along with the encryption service. An example of an AE algorithm used in COSE is AES Key Wrap [RFC3394]. These algorithms are used for key encryption, but Authenticated Encryption with Associated Data (AEAD) algorithms would be preferred.

AEAD algorithms [RFC5116]: Encryption algorithms that provide the same authentication service of the content as AE algorithms do, and also allow associated data that is not part of the encrypted body to be included in the authentication service. An example of an AEAD algorithm used in COSE is AES-GCM [RFC5116]. These algorithms are used for content encryption and can be used for key encryption as well.

"Context" is used throughout the document to represent information that is not part of the COSE message. Information that is part of the context can come from several different sources, including protocol interactions, associated key structures, and program configuration. The context to use can be implicit, identified using the "kid context" header parameter defined in [RFC8613], or identified by a protocol-specific identifier. Context should generally be included in the cryptographic construction; 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.