From 3cd8d87159ca79d3cdc7d9b843b7776bf9b9f6e4 Mon Sep 17 00:00:00 2001 From: "tmp_github@goffi.org" Date: Sun, 12 Jan 2025 23:53:12 +0100 Subject: [PATCH] Add ProtoXEP: Gateway Relayed Encryption This specification describes a mechanism for end-to-end encryption with gateways that is compatible with third-party networks. --- inbox/gateway-relayed-encryption.xml | 203 +++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 inbox/gateway-relayed-encryption.xml diff --git a/inbox/gateway-relayed-encryption.xml b/inbox/gateway-relayed-encryption.xml new file mode 100644 index 00000000..fd8269fc --- /dev/null +++ b/inbox/gateway-relayed-encryption.xml @@ -0,0 +1,203 @@ + + +%ents; +]> + + +
+ Gateway Relayed Encryption + This specification describes a mechanism for end-to-end encryption with gateways that is compatible with third-party networks. + &LEGALNOTICE; + xxxx + ProtoXEP + Standards Track + Standards + Council + + XMPP Core + XEP-0001 + + + + gre + + gre + e2ee + + + Jérôme + Poisson + goffi@goffi.org + goffi@jabber.fr + + + 0.0.1 + 2025-01-12 + jp +

First draft.

 + +
+ + +

Gateways are widely used in XMPP for communicating with third-party networks, often referred to as "legacy networks". The existing mechanisms face two significant security challenges:

+
    +
  • Credentials are frequently stored by the gateway, most of time unencrypted.
    • +
  • End-to-end encryption is currently not feasible: either end-to-end encryption (e2ee) is omitted entirely, or a message must be decrypted by the gateway before being re-encrypted for the target protocol.
    • +
+

This specification proposes a solution to address the second issue. It defines a method for gateways to instruct end-user clients on how to format and encrypt payloads.

+ +

Common encryption algorithms, such as OpenPGP, are often used by third-party networks; however, protocols typically employ their own formatting beforehand. By providing a mechanism that explains how to format the payload and which algorithm to use for encryption, clients can format and encrypt payloads themselves. This allows gateways to forward encrypted payloads (and apply additional treatments if necessary) without being able to access or decrypt the plain text content.

+

This specification provides the general mechanism for relayed encryption; separate XEPs will specify specific encryption algorithms and payload formatting means.

+ + + +

The design goals of this XEP are:

+
    +
  • To allow optional backward compatibility with clients that do not support this specification or requested formatting methods/encryption algorithms.
    • +
  • It must be possible for a gateway to make use of this specification mandatory, so no plain text or decryptable content is used.
    • +
  • To support the inclusion of attachments.
    • +
  • To require as little effort as possible from XMPP clients: they should perform only minimal formatting and encryption to keep clear payloads out of reach for gateways. The gateway will handle most legacy protocol conversions and management tasks.
    • +
  • To be extensible and flexible enough to support various use cases.
    • +
+

Note: This specification focuses on gateways for &MESSAGE; stanzas, but it may be extended later for Pubsub-based gateways or other use cases.

+ + + +

This section defines key terms used throughout this specification.

+
    +
  • Formatter: A specification that explains how a message must be arranged before encryption.
    • +
  • Formatted Payload: The data resulting from processing by the formatter, before encryption.
    • +
  • Encrypted: A specification detailing how to encrypt the formatted payload before sending it to the gateway.
    • +
+ + + +

A gateway needs to define two things to allow for relayed encryption: a formatter and an encrypter. The formatter is used to teach clients how to arrange the content of the payload before encrypting it, and the encrypter specifies which algorithms and parameters must be used. This specification defines a wrapper to then send the encrypted payload to the gateway. In addition, a generic method to request data necessary for the formatter and encrypter is also specified.

+ + + +

A formatter describes how a client must arrange payload content before encryption. It can be a well-known format (e.g., MIME) that the client can use if it knows it, or it can be a generic formatter using sandboxed technology (such as WebAssembly). The output of the formatter will be used internally by the client directly as input for the encrypter.

+

To specify the formatter to use, a &xep0030; disco feature of 'urn:xmpp:gre:formatter:[FORMATTER_NAME]:[VERSION]' MUST be announced, where [FORMATTER_NAME] is the short name of the formatter, and [VERSION] is the version of the formatter specification to use. A gateway MAY specify several versions of the same formatter if it supports more than one; the client SHOULD use the highest version that it implements. Gateways MAY have more than one kind of formatter, in which case the client chooses which one to use based on its internal implementation.

+

Specifications of formatters SHOULD be named with the following template: "GRE Formatter: [FORMATTER NAME]" and MUST have the tags "gre" and "formatter".

+ + + +

An encrypter describes to a client which encryption algorithm and parameters must be used when encrypting the payload. It specifies necessary details such as the type of encryption, key size, mode of operation, initialization vectors (if applicable), and any other required parameters. The output of the encrypter will be the encrypted payload that is sent to the gateway. Encrypter specifications SHOULD specify how various keys and other required data are exchanged. Encrypter MUST specify how the <encrypted/> element (as specified in Sending and Receiving Encrypted Data) children must be built to send the message.

+

As with formatters, an encrypter can be a well-known encryption algorithm (e.g., OpenPGP) or a generic encrypter using sandboxed technology (such as WebAssembly). However, unlike formatters, sandboxing is not enough for encrypters; they must also be verified and validated. Since the encrypter is a crucial part of the system, nothing provided by a gateway can be used without further validation. A generic encrypter specification MUST specify how to verify and validate provided generic encrypters.

+

To specify the encrypter to use, a &xep0030; disco feature of 'urn:xmpp:gre:encrypter:[ENCRYPTER_NAME]:[VERSION]' MUST be announced, where [ENCRYPTER_NAME] is the short name of the encrypter, and [VERSION] is the version of the encrypter specification to use. A gateway MAY specify several versions of the same encrypter if it supports more than one; the client SHOULD use the highest version that it implements. Gateways MAY have more than one kind of encrypter, in which case the client chooses which one to use based on its internal implementation.

+

Specifications of encrypters SHOULD be named with the following template: "GRE Encrypter: [ENCRYPTER_NAME]" and MUST have the tags "gre" and "encrypter".

+ + + +

Some data may be necessary to format and/or encrypt a message. This specification provides a simple mechanism to retrieve data from a gateway to prepare encryption.

+

To exchange data, a client MAY send an &IQ; of type 'get', which MUST include a "data" child element qualified by the namespace 'urn:xmpp:gre:0'. The "formatter" attribute MUST be set to the namespace of the chosen formatter, and the "encrypter" attribute MUST be set to the namespace of the chosen encrypter. This element MAY contain arbitrary child elements specified either by the used formatter and/or encrypter specifications. The stanza MUST be sent to the bare JID of the destination, i.e., the "localpart" of the JID MUST be specified (as the returned data may be specific to the recipient).

+

The gateway MUST return the data in a form as specified in &xep0004;. The form MUST have a "FORM_TYPE" of "urn:xmpp:gre:data" and MUST include a 'sender_id' field for which the value is the ID used on the legacy network as seen by other entities on the legacy network (e.g., the "from" email seen by the recipient for an email gateway).

+

Formatter and encrypter specific data MAY be added to the form, using namespaced fields with Clark Notation as explained in &xep0068;.

+ + + + + + +]]> + + + + + + urn:xmpp:gre:data + + + some_id_for_legacy_network@example.com + + + + + +]]> + + + +

Once a message has been encrypted and is ready to be sent to the gateway for relay, the client MUST create an <encrypted/> element as a child of the &MESSAGE; stanza. This element MUST have the namespace 'urn:xmpp:gre:0', a "formatter" attribute with the namespace of the used formatter, and an "encrypter" attribute with the namespace of the used encrypter. The children of this element MUST follow the specification of the chosen encrypter.

+ + + + +]]> +

The gateway is then free to adapt the encrypted data and transmit it using the legacy network protocol.

+

The same element is used by the gateway to send encrypted messages from entities on the legacy network.

+ + + +

The following business rules apply to Gateway Relayed Encryption:

+
    +
  • If the gateway accepts only encrypted content using this specification, it MUST advertise this fact by adding the "urn:xmpp:gre:encrypted_only:0" feature in response to &xep0030; information requests and MUST reject non-encrypted content with a stanza error. The stanza error MUST have a type set to "modify", a "policy-violation" condition, and SHOULD include a <text/> element stating clearly that the message must be encrypted using this specification.
    • +
  • Client implementations SHOULD use &xep0380; to advertise the fact that the message is encrypted.
    • +
  • When a user has multiple devices, all devices SHOULD receive copies of sent and received encrypted messages thanks to &xep0280;. To decrypt the messages and maintain a synchronized history, other devices must implement this specification and the used formatter and encrypter. The encrypter specification SHOULD explain how to decrypt the message for other devices.
    • +
  • To simplify recipient ID manipulation (which can be important for formatters), &xep0106; MUST be used to transform recipient IDs as used by legacy networks into JIDs used by the gateway.
    • +
  • It is expected that Relayed Encryption Data can be cached and called only once per session. However, the formatter and/or encrypter MAY request that those data are dynamic and need to be retrieved before each encryption. Due to the extra resources it would require, this behavior is discouraged unless absolutely necessary.
    • +
  • To limit metadata to the server and avoid reaching the maximum stanza size, it is recommended to use &xep0247; between the client and the gateway for sending large encrypted content (notably with attachments). Note, however, that this will skip carbon copy, thereby breaking history synchronization across multiple devices.
    • +
+ + + +

If an entity supports Gateway Relayed Encryption, it MUST advertise it by including the "urn:xmpp:gre:0" discovery feature in response to a &xep0030; information request. In addition, entities MUST support at least one formatter and one encrypter, and MUST include the corresponding namespace in their feature.

+ + +]]> + + + ... + + + + ... + +]]> +

If a gateway accepts only content encrypted using this specification, it MUST advertise it by adding the "urn:xmpp:gre:encrypted_only:0" feature.

+ + + + +

The following security considerations apply to the Gateway Relayed Encryption protocol:

+
    +
  • Clients must be cautious about every data received from the gateway and notify users of anything suspicious. For instance, if a gateway is known to only accept encrypted content with "urn:xmpp:gre:encrypted_only:0", any change in policy should be explicitly shown to the end-user before sending unencrypted data.
    • +
  • Whenever possible, encrypters SHOULD sign the encrypted payload.
    • +
+ + + +

This document does not require interaction with &IANA;.

+ + + +

TODO

+ + + +

Thanks to NLNet foundation/NGI Zero Core for funding the work on this specification.

+ + +