Skip to main content

Guidance for COSE and JOSE Protocol Designers and Implementers
draft-tschofenig-jose-cose-guidance-01

Document Type Active Internet-Draft (candidate for jose WG)
Authors Hannes Tschofenig , Les Hazlewood , Yaron Sheffer
Last updated 2024-07-08
RFC stream Internet Engineering Task Force (IETF)
Intended RFC status (None)
Formats
Additional resources Mailing list discussion
Stream WG state Call For Adoption By WG Issued
On agenda jose at IETF-121
Document shepherd (None)
IESG IESG state I-D Exists
Consensus boilerplate Unknown
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-tschofenig-jose-cose-guidance-01
JOSE                                                       H. Tschofenig
Internet-Draft                                                          
Intended status: Best Current Practice                      L. Hazlewood
Expires: 9 January 2025                                                 
                                                              Y. Sheffer
                                                                  Intuit
                                                             8 July 2024

     Guidance for COSE and JOSE Protocol Designers and Implementers
                 draft-tschofenig-jose-cose-guidance-01

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 9 January 2025.

Copyright Notice

   Copyright (c) 2024 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

Tschofenig, et al.       Expires 9 January 2025                 [Page 1]
Internet-Draft             COSE/JOSE Guidance                  July 2024

   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

   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) 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 [RFC7515]
   for JSON Web Signature and [RFC7516] for JSON Web Encryption).

   With the development of CBOR [RFC8949], 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 [RFC9052] and [RFC9053].

   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.

Tschofenig, et al.       Expires 9 January 2025                 [Page 2]
Internet-Draft             COSE/JOSE Guidance                  July 2024

   The document is structured as follows: Section 3 outlines challenges
   related to key identification.  Future versions of this document will
   address additional challenges.  Section 4 provides recommendations on
   creating improved 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 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) [RFC7519] and
      CBOR Web Tokens (CWT) [RFC8392].

   *  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.

Tschofenig, et al.       Expires 9 January 2025                 [Page 3]
Internet-Draft             COSE/JOSE Guidance                  July 2024

   Using the 'kid' parameter is the recommended approach for key
   identification, although [RFC7515] 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
   [I-D.ietf-cose-cwt-claims-in-headers] (for COSE) and Section 5.3 of
   [RFC7519] (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.

Tschofenig, et al.       Expires 9 January 2025                 [Page 4]
Internet-Draft             COSE/JOSE Guidance                  July 2024

4.  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.

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-10, 29 November 2023,
              <https://datatracker.ietf.org/doc/html/draft-ietf-cose-
              cwt-claims-in-headers-10>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/rfc/rfc2119>.

   [RFC7515]  Jones, M., Bradley, J., and N. Sakimura, "JSON Web
              Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
              2015, <https://www.rfc-editor.org/rfc/rfc7515>.

   [RFC7516]  Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
              RFC 7516, DOI 10.17487/RFC7516, May 2015,
              <https://www.rfc-editor.org/rfc/rfc7516>.

   [RFC7519]  Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
              (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
              <https://www.rfc-editor.org/rfc/rfc7519>.

Tschofenig, et al.       Expires 9 January 2025                 [Page 5]
Internet-Draft             COSE/JOSE Guidance                  July 2024

   [RFC8392]  Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig,
              "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392,
              May 2018, <https://www.rfc-editor.org/rfc/rfc8392>.

   [RFC8949]  Bormann, C. and P. Hoffman, "Concise Binary Object
              Representation (CBOR)", STD 94, RFC 8949,
              DOI 10.17487/RFC8949, December 2020,
              <https://www.rfc-editor.org/rfc/rfc8949>.

   [RFC9052]  Schaad, J., "CBOR Object Signing and Encryption (COSE):
              Structures and Process", STD 96, RFC 9052,
              DOI 10.17487/RFC9052, August 2022,
              <https://www.rfc-editor.org/rfc/rfc9052>.

   [RFC9053]  Schaad, J., "CBOR Object Signing and Encryption (COSE):
              Initial Algorithms", RFC 9053, DOI 10.17487/RFC9053,
              August 2022, <https://www.rfc-editor.org/rfc/rfc9053>.

Appendix A.  Acknowledgments

   TBD: Add your name here.

Authors' Addresses

   Hannes Tschofenig
   Email: hannes.tschofenig@gmx.net

   Les Hazlewood
   Email: lhazlewood@gmail.com

   Yaron Sheffer
   Intuit
   Email: yaronf.ietf@gmail.com

Tschofenig, et al.       Expires 9 January 2025                 [Page 6]