]>

hannes.tschofenig@gmx.net

lhazlewood@gmail.com

Intuit

yaronf.ietf@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) was originally designed to provide a security wrapper for access tokens used in the OAuth protocol, focusing particularly on digital signatures. However, its utility as a standard for describing security-related metadata was quickly recognized. Today, JOSE is widely adopted and its functionality spans across various specifications (such as for JSON Web Signature and for JSON Web Encryption). With the development of CBOR , a binary encoding format was introduced to address use cases where JSON was too verbose. A security wrapper utilizing CBOR-based encoding was required, leading to the standardization of CBOR Object Signing and Encryption (COSE), further refined by and . The JOSE and COSE specifications have intentionally been kept in sync because modern protocols and payloads are frequently described in the Concise Data Definition Language (CDDL) and serialized to either JOSE or COSE formats. This convergence makes them attractive to developers working across web and embedded systems. Due to their similar designs, the guidance provided in this document is applicable to both JOSE and COSE. However, certain practices pose security challenges, which are addressed in this document. Our aim is to assist in designing better extensions for JOSE/COSE and to simplify developers' workflows. The document is structured as follows: outlines challenges related to key identification. Future versions of this document will address additional challenges. provides recommendations on creating improved 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 employ a straightforward design, especially for basic functionalities like digital signatures and MACs aimed at a single recipient. The security wrapper comprises the following components: A header, divided into protected and unprotected parameters. The payload, which may be detached and transmitted independently. This payload requires protection and often consists of a JSON-based format (for JOSE) or a CBOR-encoded format (for COSE). Standardized payloads include JSON Web Tokens (JWT) and CBOR Web Tokens (CWT) . A digital signature, a tag (for MAC), or ciphertext (for encryption). The header's purpose is to provide instructions for protecting the payload, including: Algorithm information used to protect the payload, Key identification for verifying the digital signature, MAC, or encryption, X.509 certificates and certificate chains, Countersignature. While the layering is straightforward with the header providing instructions for payload protection, certain specifications and applications have begun embedding key identification information within the payload itself, disrupting this clear separation. Using the 'kid' parameter is the recommended approach for key identification, although does not mandate that key identification values be globally unique (and hence "collision resistant"). If a JOSE- or COSE-protected message is intended for external or third-party recipients: The 'kid' parameter MUST contain a globally unique value, or Other header parameters, when combined with 'kid', must result in a globally unique value. For JOSE/COSE-protected messages used within domain-specific contexts like enterprises or specific workloads, uniqueness requirements are relaxed. The practice of placing key identification information into the payload instead of the JOSE/COSE header forces a parser to postpone security processing until later. The parser must inspect the payload to find the appropriate keying material and subsequently verify it. Since the parser does not know in advance which fields contain key identification, it must expose all information to the application before signature verification or MAC processing. This introduces significant risk, as application developers may make security decisions before completing security processing. This design is unnecessary because existing header parameters can store this information. If these headers are insufficient, new header parameters can always be defined to convey necessary information. This approach also simplifies libraries, as they do not need to understand payload content to retrieve correct information. When key identification claims are placed in the payload, they SHOULD also be duplicated in the header, as specified in (for COSE) and (for JOSE). This approach should only be used as a last resort if the previous methods cannot be implemented. Finally, transitioning seamlessly from a system using digital signatures over payloads to encrypted payloads is challenging when necessary key lookup information is embedded within the encrypted payload. A redesign is therefore necessary.

Guidance We RECOMMEND that protocol designers and implementers utilize 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 required to determine the keying material for cryptographically verifying the protected payload MUST be placed in 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. Another use case is using CWT claims with payloads that are not CWT Claims Sets, including payloads that are not CBOR at all.

Acknowledgments TBD: Add your name here.