RFC 7165

Use Cases and Requirements for JSON Object Signing and Encryption (JOSE)

📅 published April 2014, from ietf

RFC 7165: Use Cases and Requirements for JSON Object Signing and Encryption (JOSE) 🎀

Okay bestie, this is RFC 7165 💖 It's from the Internet Engineering Task Force (IETF), written by R. Barnes at Mozilla. It's Category: Informational, so it's for reading and understanding, not a Standards Track spec 🦋 It's dated April 2014 and has ISSN: 2070-1721. The header doesn't list anything it obsoletes or updates, so it stands on its own ✨

Abstract ✨

Lots of internet apps need object-based security on top of the network-layer and transport-layer stuff 🔐 For ages, the Cryptographic Message Syntax (CMS) has been the binary secure object format built on ASN.1. But binary encodings like ASN.1 are getting less common, and text formats like the JavaScript Object Notation (JSON) are everywhere now 💅 This doc lays out the use cases and requirements for a secure object format encoded in JSON, pulled from a bunch of app security mechanisms that are still in development 🌸

Status of This Memo

Okay so this doc is not an Internet Standards Track specification. It's published for informational purposes 📚

It's a product of the IETF, so it represents the consensus of the IETF community 🫶 It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). Not every IESG-approved doc is a candidate for any level of Internet Standard, so see Section 2 of RFC 5741 for that.

If you want the current status, errata, or a way to give feedback, check out http://www.rfc-editor.org/info/rfc7165 🍓

Copyright (c) 2014 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 (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, since they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they're provided without warranty as described in the Simplified BSD License 🎀

Table of Contents

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
2.  Definitions . . . . . . . . . . . . . . . . . . . . . . . . .   4
3.  Basic Requirements  . . . . . . . . . . . . . . . . . . . . .   5
4.  Requirements on Application Protocols . . . . . . . . . . . .   6
5.  Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . .   7
  5.1.  Security Tokens . . . . . . . . . . . . . . . . . . . . .   7
  5.2.  OAuth . . . . . . . . . . . . . . . . . . . . . . . . . .   7
  5.3.  OpenID Connect  . . . . . . . . . . . . . . . . . . . . .   9
  5.4.  XMPP  . . . . . . . . . . . . . . . . . . . . . . . . . .  10
  5.5.  ALTO  . . . . . . . . . . . . . . . . . . . . . . . . . .  12
  5.6.  Emergency Alerting  . . . . . . . . . . . . . . . . . . .  13
  5.7.  Web Cryptography  . . . . . . . . . . . . . . . . . . . .  15
  5.8.  Constrained Devices . . . . . . . . . . . . . . . . . . .  16
    5.8.1.  Example: MAC Based on ECDH-Derived Key  . . . . . . .  16
    5.8.2.  Object Security for CoAP  . . . . . . . . . . . . . .  17
6.  Requirements  . . . . . . . . . . . . . . . . . . . . . . . .  18
  6.1.  Functional Requirements . . . . . . . . . . . . . . . . .  18
  6.2.  Security Requirements . . . . . . . . . . . . . . . . . .  19
  6.3.  Desiderata  . . . . . . . . . . . . . . . . . . . . . . .  20
7.  Security Considerations . . . . . . . . . . . . . . . . . . .  20
8.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  21
  8.1.  Normative References  . . . . . . . . . . . . . . . . . .  21
  8.2.  Informative References  . . . . . . . . . . . . . . . . .  21
Appendix A.  Acknowledgements . . . . . . . . . . . . . . . . . .  25

1. Introduction

Internet apps sit on the layered architecture of the Internet and use security at all the layers 🌈 A lot of apps mainly lean on channel-based security like IPsec and Transport Layer Security (TLS), which builds a secure channel at the IP or transport layer that app data can flow through [RFC4301] [RFC5246]. But these can't give you end-to-end security in some cases. Like, in protocols with application-layer intermediaries, channel-based security protects messages from attackers between the intermediaries, but not from the intermediaries themselves 🙈 Those cases need object-based security, which wraps the app data inside a secure object that untrusted entities can safely handle 🔥

The most famous example of this today is Secure/Multipurpose Internet Mail Extensions (S/MIME) protections in the email system [RFC5751] [RFC5322]. An email usually gets passed through a bunch of intermediate Mail Transfer Agents (MTAs) on its way to the destination 📬 Those MTAs often use channel-based protections for their own connections (e.g., STARTTLS [RFC3207]), but those protections don't stop the MTAs from messing with the message. So to get end-to-end security when the MTAs might be untrusted, mail users can use S/MIME to embed message bodies in a secure object format that gives confidentiality, integrity, and data origin authentication 🫶

S/MIME is built on the Cryptographic Message Syntax (CMS) for secure objects [RFC5652]. CMS is defined using Abstract Syntax Notation 1 (ASN.1) and is usually encoded with the ASN.1 Distinguished Encoding Rules (DER), which give you a binary encoding of the protected message and its associated parameters [ITU.X690.2002]. These days, ASN.1 usage has dropped (along with other binary encodings for general objects), while more apps rely on text-based formats like the Extensible Markup Language (XML) [W3C.REC-xml] or the JavaScript Object Notation (JSON) [RFC7159] 💅

So a lot of current apps are way better at processing text-based objects than ASN.1 ones. Honestly, lots of them can't process ASN.1 at all 😭 To make it easier to add object-based security features to these apps, the IETF JSON Object Signing and Encryption (JOSE) working group got chartered to develop a secure object format based on JSON 🧚 The basic requirements are pretty straightforward, namely confidentiality and integrity mechanisms encoded in JSON. But discussions in the working group showed that different apps wanting to use the JOSE formats have different requirements 👑 This document sums up the use cases for JOSE that those potential apps have in mind, plus the resulting requirements for security mechanisms and object encodings.

Some systems that use XML specified XML-based security mechanisms for object security, namely XML Digital Signatures and XML Encryption [W3C.xmldsig-core] [W3C.xmlenc-core]. Several security token systems use these (e.g., Security Assertion Markup Language (SAML) [OASIS.saml-core-2.0-os] and Web Services Federation [WS-Federation]), and so does the Common Alerting Protocol (CAP) emergency alerting format [CAP]. But here's the tea: XML-based secure object formats bring similar levels of complexity to ASN.1 (e.g., because of the need for XML canonicalization) 💀 So developers who don't have the tools or motivation to handle ASN.1 probably aren't going to use XML security either. That's the whole reason for a JSON-based secure object format that's simple enough to implement and deploy that developers can adopt it with minimal effort and tools 🌸

2. Definitions

Okay so this document makes heavy use of standard security terminology [RFC4949] ✨ Also, since the use cases for JOSE and CMS are pretty similar, we'll sometimes draw analogies to some CMS concepts [RFC5652] 🦋

The JOSE working group charter says the group should define three basic JSON object formats:

  1. Integrity-protected object format
  2. Confidentiality-protected object format
  3. A format for expressing keys

In this document, we'll call these the "signed object format", the "encrypted object format", and the "key format", respectively 🎀 The JOSE working group items meant to describe these formats are JSON Web Signature [JWS], JSON Web Encryption [JWE], and JSON Web Key [JWK], respectively. The algorithms and algorithm identifiers used by JWS, JWE, and JWK are defined in JSON Web Algorithms [JWA] 💖

In general, whenever we don't need to tell asymmetric and symmetric operations apart, we'll use terms like "signing" and "signature" to mean both true digital signatures using asymmetric cryptography and Message Authentication Codes (MACs) using symmetric keys 🔑

In the lifespan of a secure object there are two basic roles: an entity that creates the object (e.g., encrypting or signing a payload), and an entity that uses the object (decrypting and verifying). We'll call these roles "sender" and "recipient", respectively 🧚 Heads up that some requirements and use cases might talk about these as single entities, but each object can have multiple entities in each role. For example, a message might be signed by multiple senders or decrypted by multiple recipients 👑

3. Basic Requirements ✨

okay bestie, so for the encrypted and signed object formats, the protections come from proper cryptographic mechanisms 🔐. You get confidentiality from symmetric or asymmetric encryption, and integrity from MACs or digital signatures. JOSE has to support both symmetric and asymmetric operations, no skipping either one 💅

  • The JOSE encrypted object format must support object encryption in the case where the sender and receiver share a symmetric key. 🔑
  • The JOSE encrypted object format must support object encryption in the case where the sender has only a public key for the receiver. 🦋
  • The JOSE signed object format must support integrity protection using MACs, for the case where the sender and receiver share only a symmetric key. 🎀
  • The JOSE signed object format must support integrity protection using digital signatures, for the case where the receiver has only a public key for the sender. 🌸

ngl this part is so important. In some apps, the key used to process a JOSE object comes from the app context instead of being written right in the object 👀. So to avoid confusion, endpoints that don't have the context they need have to notice that and fail cleanly 🫶. Also, apart from keys, JOSE objects don't do pre-negotiation. Every cryptographic parameter has to be stated directly in the JOSE object 💜

  • The JOSE signed and encrypted object formats must define the process by which an implementation recognizes whether it has the key required to process a given object, whether the key is specified by the object or by some out-of-band mechanism. 🔍
  • Each algorithm used for JOSE must define which parameters are required to be present in a JOSE object using that algorithm. 🧚

Now, when two entities are about to swap a bunch of JOSE objects, pre-negotiating some parameters can be super helpful, because then they don't have to be signaled in every single object 🍓. BUT, so we don't confuse endpoints that can't do pre-negotiation, it's useful to signal when pre-negotiated parameters are in use. Lowkey genius ✨

  • It should be possible to extend the base JOSE signed and encrypted object formats to indicate that pre-negotiated parameters are to be used to process the object. This extension should also provide a means of indicating which parameters are to be used. 🌈

The whole point of the key format is to give the recipient enough info to actually use the encoded key to process cryptographic messages. Sometimes that means you need extra parameters along with the bare key, so it's not just the key by itself 🗝️

  • The JOSE key format must enable inclusion of all algorithm parameters necessary to use the encoded key, including an identifier for the algorithm with which the key is used as well as any additional parameters required by the algorithm (e.g., elliptic curve parameters). 💖

4. Requirements on Application Protocols 🎀

The JOSE secure object formats explain how the crypto processing happens on secured content, so the recipient of an object can properly decrypt an encrypted object or verify a signature 🔓. BUT, to actually use JOSE, applications still need to spell out several things about how JOSE gets used 🙈

  • What application content is to be protected
  • Which cryptographic algorithms are to be used
  • How application protocol entities establish keys
  • Whether keys are to be explicitly indicated in JOSE objects or associated by application context
  • Which serialization(s) of JOSE objects are to be used

5. Use Cases 🌸

Several IETF working groups building application-layer protocols have said they want to use the JOSE data formats in their designs for end-to-end security features 🙌. In this section, we sum up the use cases these groups proposed and talk about the requirements those imply for the JOSE object formats 📝

5.1. Security Tokens 🎫

Security tokens are a super common use case for object-based security, like SAML assertions [OASIS.saml-core-2.0-os]. Basically, they carry info about a subject entity ("claims" or "assertions") from an issuer to a recipient. The security features of a token format let the recipient check that the claims really came from the issuer and, if the object is confidentiality protected, that nobody else could see them along the way 👀

Security tokens show up in federation protocols like SAML 2.0 [OASIS.saml-core-2.0-os], WS-Federation [WS-Federation], Mozilla Persona [Persona], and OpenID Connect [OpenID.Core]. They also show up in resource authorization protocols like OAuth 2.0 [RFC6749], including for OAuth bearer tokens [RFC6750]. In some cases, security tokens are used for client authentication and for access control [JWT-BEARER] [SAML2] 💅

JSON Web Token [JWT] is a security token format based on JSON and JOSE. It's used with Mozilla Persona, OpenID Connect, and OAuth. Because JWTs often live in contexts with limited space (e.g., HTTP query parameters), it's a core requirement for JWTs, and therefore JOSE, to have a compact, URL-safe representation 🦋✨

5.2. OAuth 🔐

The OAuth protocol defines a mechanism for distributing and using authorization tokens over HTTP [RFC6749]. A client that wants to access a protected resource asks the resource owner for authorization. If the resource owner says yes, they direct an authorization server to issue an access token to the client. When the client wants to get to the protected resource, it presents the token to the relevant resource server, which checks that the token is valid before granting access 🗝️

                 +---------------+          +---------------+
                 |               |          |               |
                 |   Resource    |<........>| Authorization |
                 |    Server     |          |     Server    |
                 |               |          |               |
                 +---------------+          +---------------+
                              ^                |
                              |                |
                              |                |
                              |                |
                              |                |
                 +------------|--+          +--|------------+
                 |            +----------------+            |
                 |               |          |   Resource    |
                 |     Client    |          |     Owner     |
                 |               |          |               |
                 +---------------+          +---------------+

                        Figure 1: The OAuth Process

Effectively, this process moves the token from the authorization server (as the sender of the object) to the resource server (the recipient), going through the client and the resource owner (the resource owner because of how HTTP works under the hood). Just like with email, the application object gets carried by untrusted intermediaries 📬

This application has two essential security requirements: integrity and data origin authentication 💜. Integrity protection is needed so the resource owner and the client can't modify the permission encoded in the token. Even though the resource owner is the one who ultimately grants authorization, they're not trusted to change the authorization token, because that could, for example, grant access to resources the resource owner doesn't own 🙅‍♀️

Data origin authentication is needed so the resource server can verify that the token was issued by a trusted authorization server 🫶

Confidentiality protection may also be needed if the authorization server is worried about the resource owner or client seeing permissions info. For example, permissions related to social networking might count as private info. BUT, OAuth already requires that the underlying HTTP transactions be protected by TLS, so tokens are already confidentiality protected from entities other than the resource owner and client 🔒

The confidentiality and integrity needs are covered by the basic requirements for signed and encrypted object formats, whether the signing and encryption use asymmetric or symmetric cryptography. Which mechanism gets used depends on the relationship between the two servers, specifically whether they share a symmetric key or only public keys 🌈

Authentication requirements also depend on deployment characteristics. Where there's a relatively strong binding between the resource server and the authorization server, it may be enough for the authorization server that issues a token to be identified by the key used to sign the token. This requires that the protocol carry either the public key of the authorization server or an identifier for the public or symmetric key. In OAuth, the "client_id" parameter (external to the token) identifies the key to be used 🧚

There can also be more advanced cases where the authorization server's key isn't known in advance to the resource server. This might happen if an entity set up a collection of authorization servers (say, for load balancing), each with its own independent key pair. In these cases, it may be necessary to also include a certificate or certificate chain for the authorization server, so the resource server can verify that the authorization server is an entity it trusts 🎀

The HTTP transport for OAuth puts a specific constraint on the encoding. In OAuth, tokens often need to be passed as query parameters in HTTP URIs [RFC2616] after being base64url encoded [RFC4648]. While there's no specified limit on the length of URIs (and therefore of query parameters), in practice, URIs of more than 2,048 characters are rejected by some user agents. So this use case requires that JOSE objects be small enough, even after being signed and possibly encrypted 🍓💀

5.3. OpenID Connect ✨

okay so OpenID Connect [OpenID.Core] is a simple, REST/JSON-based identity federation protocol layered on top of OAuth 2.0 🫶 it's giving clean, cute, and very on purpose. It uses the JWT and JOSE formats both to represent security tokens and to provide security for other protocol messages (performing signing and optionally encryption). It also negotiates the algorithms to be used and distributes info about the keys to be used, using protocol elements that are not part of the JWT and JOSE header parameters 🔑

so in the OpenID Connect context, the recipient of a JWT is allowed to accept it without integrity protection in the JWT itself 👀 in that case, the recipient chooses to rely on transport security instead of object security. for example, if the payload is delivered over a TLS-protected channel, the recipient may regard the protections provided by TLS as sufficient, so JOSE protection would not be required 🌸

however, even in this case, it is desirable to associate some metadata with the JWT payload (claim set), such as the content type, or other application-specific metadata 🎀 in a signed or encrypted object, these metadata values could be carried in a header along with the other metadata required for signing or encryption. so it would thus simplify the design of OpenID Connect if there could be a JOSE object format that does not apply cryptographic protections to its payload, but still allows a header to be attached to the payload in the same way as a signed or encrypted object 🧚

5.4. XMPP 💬

the Extensible Messaging and Presence Protocol (XMPP) routes messages from one end client to another by way of XMPP servers [RFC6120] 📨 there are typically two servers involved in delivering any given message. the first client (Alice) sends a message for another client (Bob) to her server (A). Server A uses Bob's identity and the DNS to locate the server for Bob's domain (B), and then delivers the message to that server. Server B then routes the message to Bob 💌

          +-------+   +----------+   +----------+   +-----+
          | Alice |-->| Server A |-->| Server B |-->| Bob |
          +-------+   +----------+   +----------+   +-----+

                 Figure 2: Delivering an XMPP Message

the untrusted-intermediary problems are especially intense for XMPP, because in many current deployments, the holder of an XMPP domain outsources the operation of the domain's servers to a different entity 😬 in this environment, there is a clear risk of exposing the domain holder's private information to the domain operator. XMPP already has a defined mechanism for end-to-end security using S/MIME, but it has failed to gain widespread deployment [RFC3923], partly because of key management challenges and partly because of the difficulty of processing S/MIME objects 💀

the XMPP working group is in the process of developing a new end-to-end encryption system, with an encoding based on JOSE and a clearer key management system [XMPP-E2E] 🔐 sending an encrypted message in this system involves two steps. First, the sender generates a symmetric Session Master Key (SMK), encrypts the message content (including a per-message Content Master Key), and sends the encrypted message to the desired set of recipients. Second, each recipient "dials back" to the sender, providing his public key. The sender then responds with the relevant SMK, wrapped with the recipient's public key 🦋

          +-------+   +----------+   +----------+   +-----+
          | Alice |<->| Server A |<->| Server B |<->| Bob |
          +-------+   +----------+   +----------+   +-----+
              |             |              |           |
              |------------Encrypted message---------->|
              |             |              |           |
              |<---------------Public key--------------|
              |             |              |           |
              |---------------Wrapped SMK------------->|
              |             |              |           |

              Figure 3: Delivering a Secure XMPP Message

the main thing this system requires from the JOSE formats is confidentiality protection via content encryption, plus an integrity check via a MAC derived from the same symmetric key 🛡️ the separation of the key exchange from the transmission of the encrypted content, however, requires that the JOSE encrypted object format allow wrapped symmetric keys to be carried separately from the encrypted payload. in addition, the encrypted object will need to have a tag for the key that was used to encrypt the content, so that the recipient (Bob) can present the tag to the sender (Alice) when requesting the wrapped key 🏷️

another important feature of XMPP is that it allows for the simultaneous delivery of a message to multiple recipients 📬 in the diagrams above, Server A could deliver the message not only to Server B (for Bob) but also to Servers C, D, E, etc., for other users. in such cases, to avoid the multiple "dial back" transactions implied by the above mechanism, XMPP systems will likely reuse a given SMK for multiple individual messages, refreshing the SMK on a periodic and/or event-driven basis (e.g., when the recipient's presence changes) ⏰ they might also cache public keys for end recipients, so that wrapped keys can be sent along with content on future messages. this implies that the JOSE encrypted object format must support the provision of multiple versions of the same wrapped SMK (much as a CMS EnvelopedData structure can include multiple RecipientInfo structures) 🧩

in the current draft of the XMPP end-to-end security system, each party is authenticated by virtue of the other party's trust in the XMPP message routing system. the sender is authenticated to the receiver because he can receive messages for the identifier "Alice" (in particular, the request for wrapped keys) and can originate messages for that identifier (the wrapped key). likewise, the receiver is authenticated to the sender because he received the original encrypted message and originated the request for a wrapped key. so the authentication here requires not only that XMPP routing be done properly, but also that TLS be used on every hop. moreover, it requires that the TLS channels have strong authentication, since a man in the middle on any of the three hops can masquerade as Bob and obtain the key material for an encrypted message 😱

because this authentication is quite weak (depending on the use of TLS on three hops) and unverifiable by the endpoints, it is possible that the XMPP working group will integrate some sort of credentials for end recipients. in which case, there would need to be a way to associate these credentials with JOSE objects 🚨

finally, it's worth noting that XMPP is based on XML, not JSON. so by using JOSE, XMPP will be carrying JSON objects within XML 🤯 it is thus a desirable property for JOSE objects to be encoded in such a way as to be safe for inclusion in XML. otherwise, an explicit CDATA indication must be given to the parser to indicate that it is not to be parsed as XML. one way to meet this requirement would be to apply base64url encoding, but for XMPP messages of medium-to-large size, this could impose a fair degree of overhead 🐢

5.5. ALTO 🗺️

Application-Layer Traffic Optimization (ALTO) is a system for distributing network topology information to end devices, so that those devices can modify their behavior to have a lower impact on the network [RFC6708] 🌍 the ALTO protocol distributes topology information in the form of JSON objects carried in HTTP [RFC2616] [ALTO]. the basic version of ALTO is simply a client-server protocol, so simple use of HTTPS suffices for this case [RFC2818] 🔒 however, there is beginning to be some discussion of use cases for ALTO in which these JSON objects will be distributed through a collection of intermediate servers before reaching the client, while still preserving the ability of the client to authenticate the original source of the object. even the base ALTO protocol notes that "ALTO Clients obtaining ALTO information through redistribution must be able to validate the received ALTO information" to ensure that it was generated by an appropriate ALTO server 🕵️‍♀️

in this case, the security requirements are straightforward. JOSE objects carrying ALTO payloads will need to bear digital signatures from the originating servers, which will be bound to certificates attesting to the identities of the servers. there is no requirement for confidentiality in this case, since ALTO information is generally public 🌷

the more interesting questions are encoding questions 🤓 ALTO objects are likely to be much larger than payloads in the two cases above, with sizes of up to several megabytes. processing of such large objects can be done more quickly if it can be done in a single pass, which may be possible if JOSE objects require specific orderings of fields within the JSON structure ⚡

in addition, because ALTO objects are also encoded as JSON, they are already safe for inclusion in a JOSE object 💖 signed JOSE objects will likely carry the signed data in a string alongside the signature. JSON objects have the property that they can be safely encoded in JSON strings. all they require is that unnecessary white space be removed, a much simpler transformation than, say, base64url encoding. this raises the question of whether it might be possible to optimize the JOSE encoding for certain "JSON-safe" cases 🧠

finally, it may be desirable for ALTO to have a "detached signature" mechanism, that is, a way to encode signature information separate from the protected content 🎁 this would allow the ALTO protocol to include the signature in an HTTPS header, with the signed content as the HTTPS entity body 🫧

5.6. Emergency Alerting 🚨

okay so emergency alerting is a super emerging use case for IP networks [ALERT-REQ] 😭. Alerting systems let authorities warn people about danger on the way by sending alert messages to connected devices. Like, if a hurricane or tornado is coming, alerts can go out to every device in its path 🌪️.

The most critical security requirement here is that it must not be possible for an attacker to send false alerts to devices. bestie, that would let someone cause wide-spread panic 💀. In practice, alert systems stop these attacks in two ways. First, they put controls on who can send messages at the points where alerts are originated. Second, they make recipients verify that the alert was sent by an authorized source ✨. The first kind of control is done with local security on the hosts that alerts can come from. The second kind is done with digital signatures on alert messages, using channel-based or object-based mechanisms. With an object-based mechanism, the signature value is encoded in a secure object. With a channel-based mechanism, the alert is "signed" just by being sent over an authenticated, integrity-protected channel 🔒.

Alerts usually reach end recipients through a series of intermediaries 🧚. For example, a national weather service might originate a hurricane alert, but it might first get delivered to a national gateway, and then to network operators, who broadcast it to end subscribers.

        +------------+    +------------+    +------------+
        | Originator |    | Originator |    | Originator |
        +------------+    +------------+    +------------+
              |                 .                 .
              +-----------------+..................
                                |
                                V
                           +---------+
                           | Gateway |
                           +---------+
                                |
                   +------------+------------+
                   |                         |
                   V                         V
              +---------+               +---------+
              | Network |               | Network |
              +---------+               +---------+
                   |                         |
            +------+-----+            +------+-----+
            |            |            |            |
            V            V            V            V
        +--------+   +--------+   +--------+   +--------+
        | Device |   | Device |   | Device |   | Device |
        +--------+   +--------+   +--------+   +--------+

               Figure 4: Delivering an Emergency Alert

To verify alert signatures, recipients have to be provisioned with the proper public keys for trusted alert authorities 🗝️. This trust can be "piece-wise" along the path the alert takes. For example, the alert relays operated by networks might have a full set of certificates for all alert originators, while end devices may only trust their local alert relay. Or, devices might require that a device be signed by an authorized originator and by its local network's relay.

This setup creates a need for multiple signatures on alert documents, so that an alert can carry signatures from any or all of the entities that processed it along the path 💅. To keep things simple, these signatures should be "modular," meaning a new signature can be added without having to alter or recompute previous signatures 🎀.

5.7. Web Cryptography 🔐

The W3C Web Cryptography API defines a standard cryptographic API for the Web [WebCrypto] 🌸. If a browser exposes this API, then JavaScript provided as part of a Web page can ask the browser to do cryptographic operations, like digest, MAC, encryption, or digital signing.

One of the key reasons to have the browser do these operations is to stop JavaScript code from accessing the keying material used for them 🙈. For example, this separation would keep code injected through a cross-site scripting (XSS) attack from reading and exfiltrating keys stored within a browser. Malicious code could still use the key while it's running in the browser, but this vulnerability can only be exercised while that malicious code is active in a user's browser.

However, the Web Cryptography API also provides a key export functionality, which can let JavaScript extract a key from the API in wrapped form 👀. For example, JavaScript code might provide a public key whose corresponding private key is held by another device. The wrapped key from the API could then be used to safely transport the key to the new device. Yes, this could potentially let malicious code export a key, but the need for an explicit export operation is a control point, which allows for user notification or consent verification ✋.

The Web Cryptography API also lets browsers put limits on how the keys they handle can be used 💜. For example, a symmetric key might be marked as usable only for encryption, and not for MAC. When a key is exported in wrapped form, these attributes should be carried along with it.

So the Web Cryptography API needs formats to express several forms of keys 💖. Obviously, the public key from an asymmetric key pair can be freely imported to and exported from the browser, so there needs to be a format for public keys. There's also a need for a format to express private keys and symmetric keys. For non-public keys, the main need is a wrapped form, where the confidentiality and integrity of the key are assured cryptographically, and these protections should also apply to any attributes of the key. It may also be useful to define a direct, unwrapped format for use within a security boundary.

5.8. Constrained Devices 🦋

This section describes use cases for constrained devices as defined in [CONSTRAINED]. The typical issues with this type of device are limited memory, limited power supply, low processing power, and severe message size limitations for the communication protocols 🔋.

5.8.1. Example: MAC Based on ECDH-Derived Key 🧁

Suppose a small, low-power device maker has decided to use the output of the JOSE working group as their encryption and authentication framework. The device maker has a limited budget for both gates and power, so there are a bunch of short cuts and design decisions that have been made to minimize these needs 📉.

The design team has determined that MACs are going to be sufficient to provide the necessary authentication. However, even though a MAC is going to be used, they don't want to use a single long-term shared secret. Instead, they've adopted the following proposal for computing a shared secret that can be validated 🤌:

  • An Elliptic-Curve Diffie-Hellman (ECDH) key pair is generated for the device at the time of manufacturing. (Or, as part of the configuration process during installation.)
  • An ECDH public key for the controller is configured at the time of configuration.
  • The configuration system performs the ECDH computation and configures the device with the resulting shared secret. This process removes the need for the device to be able to perform the required ECDH processing. The security requirements on protecting this computed shared secret are the same as the requirements on protecting the private ECDH key 🔑.
  • A counter and an increment value are configured onto the device.
  • When a message is to be sent by the device, the counter is incremented and a new MAC key is computed from the ECDH secret and the counter value. A custom Key Derivation Function (KDF) based on AES-CBC is used to derive the required MAC key. The MAC key is then used to compute the MAC value for the message.

In a similar way, the KDF function can be used to compute an Authenticated Encryption with Associated Data (AEAD) algorithm key when the system needs to provide confidentiality for the message 🛡️. The controller, being a larger device, will do the ECDH step and use a random number generator to generate the sender nonce value.

5.8.2. Object Security for CoAP 🍓

This use case deals with constrained devices of class C0/C1 (see [CONSTRAINED]). These devices communicate using RESTful requests and responses transferred over the Constrained Application Protocol [CoAP]. To keep things simple, all communication is assumed to be unicast, i.e., these security measures don't cover multicast or broadcast 📡.

In this kind of setting, session-based security might be too costly (e.g., to run a 4-pass authentication protocol), since receiving and especially sending uses a lot of power, particularly for wireless devices 🪫. So, just securing the CoAP payload by replacing a plaintext payload of a request or response with a JWE object is an important alternative solution. It allows a trade-off between protection (the CoAP headers are not protected) and performance ⚖️.

In a simple setting, think about the payload of a CoAP GET response from a sensor-type device. The information in a sensor reading may be privacy or business sensitive, and it needs both integrity protection and encryption 🕵️‍♀️.

But some sensor readings are very short, say, a few bytes, and in this case, default encryption and integrity protection algorithms (such as 128-bit AES-CBC with HMAC_SHA256) may cause a dramatic expansion of the payload, even before counting JWE headers 😭.

Also, the value of certain sensor readings may decline rapidly, e.g., traffic or environmental measurements, so it must be possible to reduce the security overhead 📉.

This leads to the following requirements that could be covered by specific JWE/JWS profiles 📝:

  • The size of the secure object shall be as small as possible. Receiving an object may cost orders of magnitude more in terms of power than performing, say, public key cryptography on the object, particularly in a wireless setting.
  • Integrity protection: The object shall be able to support integrity protection, i.e., have a field containing a digital signature. Both public key signatures and keyed MACs shall be supported.
  • Encryption: The object shall be able to support encryption as an optional addition to integrity protection. It shall be possible to exclude certain fields from encryption, which are needed before verifying integrity or decrypting the object.
  • Cipher suites: It should be possible to support a variety of cipher suites to support the constrained devices' use cases. For example:
    • Block ciphers with block sizes of, e.g., 96 bits, in addition to the standard 128 bits.
    • Modes of operation for block ciphers that do not expand the message size to a block boundary, such as AES-GCM.
    • Cipher suites that support combined encryption and MAC calculation (i.e., AEAD modes for block ciphers).

6. Requirements 📋

This section sums up the requirements from the above use cases and lists further requirements that weren't directly derived from them 💅. There are also some constraints that aren't hard requirements, but are still desirable properties for the JOSE system to have ✨.

6.1. Functional Requirements

okay so this is the "what does it have to DO" list, and it's giving very specific energy 💅✨

F1 Define formats for secure objects that provide the following security properties:

  • Digital signature (integrity/authentication under an asymmetric key pair)
  • Message authentication (integrity/authentication under a symmetric key)
  • Authenticated encryption

F2 Define a format for public keys and private keys for asymmetric cryptographic algorithms, with associated attributes, including a wrapped form for private keys. 🔑

F3 Define a format for symmetric keys with associated attributes, allowing for both wrapped and unwrapped keys. 🎀

F4 Define a JSON serialization for each of the above objects. An object in this encoding must be valid according to the JSON ABNF syntax [RFC7159]. 💖

F5 Define a compact, URL-safe text serialization for the encrypted and signed object formats. 🦋

F6 Allow for attributes associated to wrapped keys to be bound to them cryptographically. 🔐

F7 Allow for wrapped keys to be separated from a secure object that uses a symmetric key. In such cases, cryptographic components of the secure object other than the wrapped key (e.g., ciphertext, MAC values) must be independent of the wrapped form of the key. For example, if an encrypted object is prepared for multiple recipients, then only the wrapped key may vary, not the ciphertext. Bestie, this one is so precise it's iconic 🫶

F8 Do not impose more overhead than is required to meet the requirements in this document, especially when a large amount of application content is being protected. No bloat, no cap 🌸

6.2. Security Requirements

ok the security section is where it gets SERIOUS 😭🔥

S1 Provide mechanisms to avoid repeated use of the same symmetric key for encryption or MAC computation. Instead, long-lived keys should be used only for key wrapping, not for direct encryption/MAC. It should be possible to use any of the key management techniques provided in CMS [RFC5652]:

  • Key transport (wrapping for a public key)
  • Key encipherment (wrapping for a symmetric key)
  • Key agreement (wrapping for a Diffie-Hellman (DH) public key)
  • Password-based encryption (wrapping under a key derived from a password)

S2 Where long-lived symmetric keys are used directly for cryptographic operations (i.e., where requirement S1 is not met), provide deployment guidance on key management practices, such as the need to limit key lifetimes. ⏳

S3 Use cryptographic algorithms in a manner compatible with major validation processes. For example, if typical validation standards allow algorithm A to be used for purpose X but not purpose Y, then JOSE should not recommend using algorithm A for purpose Y. Not recommending the wrong thing is literally the whole vibe 🙈

S4 Support operation with or without pre-negotiation. It must be possible to create or process secure objects without any configuration beyond key provisioning. If it is possible for keys to be derived from application context, it must be possible for a recipient to recognize when it does not have the appropriate key. 🧚

6.3. Desiderata

these are the "it would be so nice if" wishes, and I am OBSESSED 🥹

D1 Maximize compatibility with the W3C Web Crypto specifications, e.g., by coordinating with the Web Crypto working group to encourage alignment of algorithms and algorithm identifiers. 🌈

D2 Avoid JSON canonicalization to the extent possible. That is, all other things being equal, techniques that rely on fixing a serialization of an object (e.g., by encoding it with base64url) are preferred over those that require converting an object to a canonical form. Canonical form is a whole mess, so we're avoiding it where we can 🙅‍♀️

D3 Maximize the extent to which the inputs and outputs of JOSE cryptographic operations can be controlled by the applications, as opposed to involving processing specific to JOSE. This allows JOSE the flexibility to address the needs of many cryptographic protocols. For example, in some cases, it might allow JOSE objects to be translated to legacy formats such as CMS without the need for re-encryption or re-signing. Flexibility queen behavior 👑

7. Security Considerations

okay this section is dramatic and I'm here for it 💀 but it's also really important, so listen up bestie 🫶

The main focus of this document is the requirements for a JSON-based secure object format. At the level of general security considerations for object-based security technologies, the security considerations for this format are the same as for CMS [RFC5652]. The big difference between JOSE and CMS is that JOSE is built on JSON, and JSON doesn't have a canonical representation. Without a canonical form, it's hard to tell whether two JSON objects actually say the same thing, and that could open the door to vulnerabilities in some JOSE usages. Be careful out there 😭🔥

8. References

8.1. Normative References

  • [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", RFC 4949, August 2007.
  • [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, RFC 5652, September 2009.
  • [RFC6120] Saint-Andre, P., "Extensible Messaging and Presence Protocol (XMPP): Core", RFC 6120, March 2011.
  • [RFC6708] Kiesel, S., Previdi, S., Stiemerling, M., Woundy, R., and Y. Yang, "Application-Layer Traffic Optimization (ALTO) Requirements", RFC 6708, September 2012.
  • [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012.
  • [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, March 2014.
  • [W3C.REC-xml] Bray, T., Maler, E., Paoli, J., and C. Sperberg-McQueen, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", W3C Recommendation, November 2008, <http://www.w3.org/TR/2008/REC-xml-20081126/>.
  • [WebCrypto] Dahl, D. and R. Sleevi, "Web Cryptography API", W3C Working Draft, January 2013, <http://www.w3.org/TR/2013/WD-WebCryptoAPI-20130108/>.

8.2. Informative References

  • [ALERT-REQ] Schulzrinne, H., Norreys, S., Rosen, B., and H. Tschofenig, "Requirements, Terminology and Framework for Exigent Communications", Work in Progress, March 2012.
  • [ALTO] Alimi, R., Ed., Penno, R., Ed., and Y. Yang, Ed., "ALTO Protocol", Work in Progress, March 2014.
  • [CAP] Botterell, A. and E. Jones, "Common Alerting Protocol, v1.1", OASIS Standard CAP-V1.1, October 2005, <http://www.oasis-open.org/committees/download.php/15135/emergency-CAPv1.1-Corrected_DOM.pdf>.
  • [CONSTRAINED] Bormann, C., Ersue, M., and A. Keranen, "Terminology for Constrained Node Networks", Work in Progress, March 2014.
  • [CoAP] Shelby, Z., Hartke, K., and C. Bormann, "Constrained Application Protocol (CoAP)", Work in Progress, June 2013.
  • [ITU.X690.2002] International Telecommunications Union, "Information Technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)", ITU-T Recommendation X.690, July 2002.
  • [JWA] Jones, M., "JSON Web Algorithms (JWA)", Work in Progress, March 2014.
  • [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", Work in Progress, March 2014.
  • [JWK] Jones, M., "JSON Web Key (JWK)", Work in Progress, March 2014.
  • [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", Work in Progress, March 2014.
  • [JWT-BEARER] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants", Work in Progress, March 2014.
  • [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", Work in Progress, March 2014.
  • [OASIS.saml-core-2.0-os] Cantor, S., Kemp, J., Maler, E., and R. Philpott, "Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0", Oasis Standard, March 2005, <http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf>.
  • [OpenID.Core] Bradley, J., de Medeiros, B., Jones, M., Mortimore, C., and N. Sakimura, "OpenID Connect Core 1.0", December 2013, <http://openid.net/specs/openid-connect-core-1_0.html>.
  • [Persona] Mozilla Developer Network, "Mozilla Persona", April 2013, <https://developer.mozilla.org/en-US/docs/Persona>.
  • [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
  • [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
  • [RFC3207] Hoffman, P., "SMTP Service Extension for Secure SMTP over Transport Layer Security", RFC 3207, February 2002.
  • [RFC3923] Saint-Andre, P., "End-to-End Signing and Object Encryption for the Extensible Messaging and Presence Protocol (XMPP)", RFC 3923, October 2004.
  • [RFC4301] Kent, S. and K. Seo, "Security Architecture for the Internet Protocol", RFC 4301, December 2005.
  • [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, October 2006.
  • [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008.
  • [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, October 2008.
  • [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet Mail Extensions (S/MIME) Version 3.2 Message Specification", RFC 5751, January 2010.
  • [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, October 2012.
  • [SAML2] Campbell, B., Mortimore, C., and M. Jones, "SAML 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants", Work in Progress, March 2014.
  • [W3C.xmldsig-core] Eastlake, D., Reagle, J., and D. Solo, "XML-Signature Syntax and Processing", W3C Recommendation, June 2008, <http://www.w3.org/TR/2008/REC-xmldsig-core-20080610/>.
  • [W3C.xmlenc-core] Eastlake, D. and J. Reagle, "XML Encryption Syntax and Processing", W3C Candidate Recommendation, December 2002, <http://www.w3.org/TR/2002/REC-xmlenc-core-20021210/>.
  • [WS-Federation] Goodner, M., Kaler, C., McIntosh, M., and A. Nadalin, "Web Services Federation Language (WS-Federation) Version 1.2", Oasis Standard, May 2009, <http://docs.oasis-open.org/wsfed/federation/v1.2/os/ws-federation-1.2-spec-os.html>.
  • [XMPP-E2E] Miller, M., "End-to-End Object Encryption and Signatures for the Extensible Messaging and Presence Protocol (XMPP)", Work in Progress, June 2013.

Appendix A. Acknowledgements

big thank-you energy to everyone who helped make this happen 🫶💜

Thanks to Matt Miller for discussions related to the XMPP end-to-end security model and to Mike Jones for considerations related to security tokens and XML security. Thanks to Mark Watson for raising the need for representing symmetric keys and binding attributes to them. Thanks to Ludwig Seitz for contributing the constrained device use case. Legends only 🌟

Author's Address ✨

Richard Barnes
Mozilla
331 E. Evelyn Ave.
Mountain View, CA  94041
US

EMail: rlb@ipv.sx
📦 where this page comes from