]>

hannes.tschofenig@gmx.net

lhazlewood@gmail.com

Security JOSE Internet-Draft JSON Object Signing and Encryption (JOSE) and CBOR Object Signing and Encryption (COSE) are two widely used security wrappers, which have been developed in the IETF and have intentionally been kept in sync. This document provides guidance for protocol designers developing extensions for JOSE/COSE and for implementers of JOSE/COSE libraries. Developers of application using JSON and/or JOSE should also read this document but are realistically more focused on the documentation offered by the library they are using.

Introduction JSON Object Signing and Encryption (JOSE) has initially been designed to offer provide a security wrapper for access tokens used by the OAuth protocol, particularly a digital signature. The wider applicability of a standard for describing security-related meta-data was, however, immediately recognized. Today, JOSE is in widespread use and the functionality is spread accross various specifications (such as for the JSON Web Signature and for JSON Web Encryption). With the development of CBOR a binary encoding format was developed to address use cases where JSON was too verbose. A security wrapper that uses CBOR-based encoding was needed and CBOR Object Signing and Encryption (COSE) was standardized and later updated with and . The JOSE and COSE specifications have intentionally been kept in sync since protocols and payloads today are often described in the Concise Data Definition Language (CDDL) and serialized to either JOSE or COSE thereby making them attractive to developers from the web and the embedded world at the same time. Due to the similarity of the designs, the guidance provided in this document is therefore applicable to JOSE and COSE. Unfortunately, some practices cause challenges from a security point of view and this document captures those. We hope that this document helps to design better extensions for JOSE/COSE and to make the life of developers easier. The document is structured as follows. describes the challenges with key identification. Future versions of this document will add further challenges. then offers guidance for how to create better designs for JOSE/COSE.

Terminology and Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 .

Key Identification The security wrappers in JOSE and COSE use a simple design, at least for the basic functionality like digital signatures and MACs using a single recipient. The security wrapper contains the following structure: A header, which is split into a protected and unprotected parameters. The payload, which may be detached and will then be conveyed independently. This is the payload we want to protect. In many applications this payload is a JSON-based payload (in case of JOSE) or a CBOR-encoded payload (in case of COSE). There are also standardize payloads, such as JSON Web Token (JWT) and CBOR Web Token (CWT) . A digital signature, a tag (for a MAC), or a ciphertext (for encryption). The purpose of the header is to provide instructions for the protection of the payload, including algorithm information used to provide protection of the payload, the identification of the key to verify the digital signature, MAC, or encryption, X.509 certificates and certificate chains, countersignature. Although the layering is quite simple with the header providing the information to provide protection of the payload, some specifications and applications started to place information for key identification inside the payload. This approach destroys the clear layering. The use of the 'kid' parameter is the preferred way to identify a key but nothing in states that the key identification values must be globally unique (and therefore "collision resistant"). If a JOSE-/COSE-protected message is intended for external/3rd party recipients, then the 'kid' parameter MUST contain a globally unique value, or other header parameters when combined associated with the 'kid' result in a globally unique value. If a JOSE-/COSE-protected message is used in a domain-specific context only, such as within an enterprise or a workload environment, then the uniqueness requirements are lifted. The practice of placing some or all key identification into the payload, instead of the JOSE/COSE header, forces a parser to defer security processing of the payload to a later point in time, to look inside the payload to find the appropriate keying material and to subsequently verify the payload. Since the parser implementation does not know what fields will be used for key identification it has to expose all information to an application prior to signature verification or MAC processing. There is a large risk that application developers make security- relevant decisions already prior to the completion of the security processing. There is no need for such design since there are existing header parameters available to store the necessary information. If those headers are insufficient, then it is always possible to define new header parameter to convey this information. This approach also simplifies libraries since they do not need to understand the payload content to fetch the correct information. When key identification-related claims are placed in the payload, those claims SHOULD be repeated in the header, as defined in (for COSE) and in (for JOSE). This approach should only be used as a last resort, when the previous two approaches cannot be used. Finally, an easy transition from a system using digital signatures over payloads to encrypted payloads is not possible since information needed for key look-up are found in the encrypted payload. A re-design would therefore be required.

Guidance We RECOMMEND that protocol designers and implementers use the available header parameter for key identification. If the standardized parameters are insufficient, new header parameters can be defined. Re-using existing header parameters will improve interoperability because there are a limited number of cases on how to select a key. Information that is needed for determining the keying material needed to cryptographically verify the protected payload MUST be placed into the header of the JOSE/COSE security wrapper.

IANA Considerations This document does not make requests to IANA.

Security Considerations This specification makes security recommendations for the JOSE/COSE specification suite. Therefore, it is entirely about security.

In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. JSON Web Signature (JWS) represents content secured with digital signatures or Message Authentication Codes (MACs) using JSON-based data structures. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and an IANA registry defined by that specification. Related encryption capabilities are described in the separate JSON Web Encryption (JWE) specification. JSON Web Encryption (JWE) represents encrypted content using JSON-based data structures. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and IANA registries defined by that specification. Related digital signature and Message Authentication Code (MAC) capabilities are described in the separate JSON Web Signature (JWS) specification. 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. The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack. This document obsoletes RFC 7049, providing editorial improvements, new details, and errata fixes while keeping full compatibility with the interchange format of RFC 7049. It does not create a new version of the format. 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 a set of algorithms that can be used with the CBOR Object Signing and Encryption (COSE) protocol (RFC 9052). This document, along with RFC 9052, obsoletes RFC 8152. JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. CBOR Web Token (CWT) is a compact means of representing claims to be transferred between two parties. The claims in a CWT are encoded in the Concise Binary Object Representation (CBOR), and CBOR Object Signing and Encryption (COSE) is used for added application-layer security protection. A claim is a piece of information asserted about a subject and is represented as a name/value pair consisting of a claim name and a claim value. CWT is derived from JSON Web Token (JWT) but uses CBOR rather than JSON. Mattr Self-Issued Consulting This document describes how to include CBOR Web Token (CWT) claims in the header parameters of any COSE structure. This functionality helps to facilitate applications that wish to make use of CBOR Web Token (CWT) claims in encrypted COSE structures and/or COSE structures featuring detached signatures, while having some of those claims be available before decryption and/or without inspecting the detached payload.

Acknowledgments TBD: Add your name here.