JOSE H. Tschofenig Internet-Draft Intended status: Best Current Practice L. Hazlewood Expires: 25 April 2024 23 October 2023 Guidance for COSE and JOSE Protocol Designers and Implementers draft-tschofenig-jose-cose-guidance-00 Abstract 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. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 25 April 2024. Copyright Notice Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved. 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 Tschofenig & Hazlewood Expires 25 April 2024 [Page 1] Internet-Draft COSE/JOSE Guidance October 2023 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 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Terminology and Requirements Language . . . . . . . . . . . . 3 3. Key Identification . . . . . . . . . . . . . . . . . . . . . 3 4. Guidance . . . . . . . . . . . . . . . . . . . . . . . . . . 5 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 6. Security Considerations . . . . . . . . . . . . . . . . . . . 5 7. Normative References . . . . . . . . . . . . . . . . . . . . 5 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 6 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 6 1. 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 [RFC7515] for the JSON Web Signature and [RFC7516] for JSON Web Encryption). With the development of CBOR [RFC8949] 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 [RFC9052] and [RFC9053]. 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. Tschofenig & Hazlewood Expires 25 April 2024 [Page 2] Internet-Draft COSE/JOSE Guidance October 2023 The document is structured as follows. Section 3 describes the challenges with key identification. Future versions of this document will add further challenges. Section 4 then offers guidance for how to create better designs for JOSE/COSE. 2. 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 [RFC2119]. 3. 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) [RFC7519] and CBOR Web Token (CWT) [RFC8392]. * 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. Tschofenig & Hazlewood Expires 25 April 2024 [Page 3] Internet-Draft COSE/JOSE Guidance October 2023 The use of the 'kid' parameter is the preferred way to identify a key but nothing in [RFC7515] 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 [I-D.ietf-cose-cwt-claims-in-headers] (for COSE) and in Section 5.3 of [RFC7519] (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. Tschofenig & Hazlewood Expires 25 April 2024 [Page 4] Internet-Draft COSE/JOSE Guidance October 2023 4. 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. 5. IANA Considerations This document does not make requests to IANA. 6. Security Considerations This specification makes security recommendations for the JOSE/COSE specification suite. Therefore, it is entirely about security. 7. Normative References [I-D.ietf-cose-cwt-claims-in-headers] Looker, T. and M. B. Jones, "CBOR Web Token (CWT) Claims in COSE Headers", Work in Progress, Internet-Draft, draft- ietf-cose-cwt-claims-in-headers-07, 22 October 2023, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015, . [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", RFC 7516, DOI 10.17487/RFC7516, May 2015, . [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, . Tschofenig & Hazlewood Expires 25 April 2024 [Page 5] Internet-Draft COSE/JOSE Guidance October 2023 [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, May 2018, . [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", STD 94, RFC 8949, DOI 10.17487/RFC8949, December 2020, . [RFC9052] Schaad, J., "CBOR Object Signing and Encryption (COSE): Structures and Process", STD 96, RFC 9052, DOI 10.17487/RFC9052, August 2022, . [RFC9053] Schaad, J., "CBOR Object Signing and Encryption (COSE): Initial Algorithms", RFC 9053, DOI 10.17487/RFC9053, August 2022, . Appendix A. Acknowledgments TBD: Add your name here. Authors' Addresses Hannes Tschofenig Email: hannes.tschofenig@gmx.net Les Hazlewood Email: lhazlewood@gmail.com Tschofenig & Hazlewood Expires 25 April 2024 [Page 6]