Internet DRAFT - draft-tschofenig-jose-cose-guidance
draft-tschofenig-jose-cose-guidance
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,
<https://datatracker.ietf.org/doc/html/draft-ietf-cose-
cwt-claims-in-headers-07>.
[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 & 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, <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
Tschofenig & Hazlewood Expires 25 April 2024 [Page 6]
