XEP-xxxx: Gateway Relayed Encryption

1. Introduction¶

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.

2. Requirements¶

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.

3. Glossary¶

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.

4. Overview¶

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.

5. Formatter¶

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 Service Discovery (XEP-0030) [1] 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".

6. Encrypter¶

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 Service Discovery (XEP-0030) [1] 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".

7. Relayed Encryption Data¶

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 Data Forms (XEP-0004) [2]. 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 Field Standardization for Data Forms (XEP-0068) [3].

<iq type='get'
    from='romeo@example.net/orchard'
    to='some_user@gateway.example.org'
    id='data1'>
  <data xmlns='urn:xmpp:gre:0'
        formatter='urn:xmpp:gre:formatter:some_formatter:0'
        encrypter='urn:xmpp:gre:encrypter:some_encrypter:0'>
    <!-- Arbitrary child elements can be added here -->
  </data>
</iq>

<iq type='result'
    from='some_user@gateway.example.org'
    to='romeo@example.net/orchard'
    id='data1'>
  <data xmlns='urn:xmpp:gre:0'>
    <x xmlns='jabber:x:data' type='result'>
      <field var='FORM_TYPE' type='hidden'>
        <value>urn:xmpp:gre:data</value>
      </field>
      <field var='sender_id'>
        <value>some_id_for_legacy_network@example.com</value>
      </field>
      <!-- Other fields can be added here as per formatter and encrypter specifications -->
    </x>
  </data>
</iq>

8. Sending and Receiving Encrypted Messages¶

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.

<message to='some_user@gateway.example.org'>
  <encrypted xmlns='urn:xmpp:gre:0'
    formatter='urn:xmpp:gre:formatter:example_formatter:0'
    encrypter='urn:xmpp:gre:encrypter:example_encrypter:0'>
    <!-- DATA AS SPECIFIED BY ENCRYPTER -->
  </encrypted>
</message>

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.

9. Business Rules¶

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 Service Discovery (XEP-0030) [1] 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 Explicit Message Encryption (XEP-0380) [4] 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 Message Carbons (XEP-0280) [5]. 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), JID Escaping (XEP-0106) [6] 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 Jingle XML Streams (XEP-0247) [7] 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.

10. Discovering Support¶

If an entity supports Gateway Relayed Encryption, it MUST advertise it by including the "urn:xmpp:gre:0" discovery feature in response to a Service Discovery (XEP-0030) [1] information request. In addition, entities MUST support at least one formatter and one encrypter, and MUST include the corresponding namespace in their feature.

<iq type='get'
    from='juliet@example.org/balcony'
    to='some_gateway.example.org'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

<iq type='result'
    from='some_gateway.example.org'
    to='juliet@example.org/balcony'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='urn:xmpp:gre:0'/>
    <feature var='urn:xmpp:gre:formatter:example_formatter:0'/>
    <feature var='urn:xmpp:gre:encrypter:example_encrypter:0'/>
    ...
  </query>
</iq>

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

11. Security Considerations¶

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.

12. IANA Considerations¶

This document does not require interaction with the Internet Assigned Numbers Authority (IANA) [8].

13. XMPP Registrar Considerations¶

TODO

14. Acknowledgements¶

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

Appendices

Appendix A: Document Information¶

Series

XEP

Number

xxxx

Publisher

XMPP Standards Foundation

Status

ProtoXEP

Type

Standards Track

Version

0.0.1

Last Updated

2025-01-12

Approving Body

XMPP Council

Dependencies

XMPP Core, XEP-0001

Supersedes

None

Superseded By

None

Short Name

gre

This document in other formats: XML  PDF

Appendix B: Author Information¶

Jérôme Poisson

Email

goffi@goffi.org

JabberID

goffi@jabber.fr

Appendix C: Legal Notices¶

Appendix D: Relation to XMPP¶

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Appendix E: Discussion Venue¶

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <https://xmpp.org/community/> for a complete list.

Errata can be sent to <editor@xmpp.org>.

Appendix F: Requirements Conformance¶

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

Appendix G: Notes¶

Appendix H: Revision History¶

Note: Older versions of this specification might be available at https://xmpp.org/extensions/attic/

1. Version 0.0.1 (2025-01-12)¶

   First draft.

   jp

Appendix I: Bib(La)TeX Entry

@report{poisson2025gre,
  title = {Gateway Relayed Encryption},
  author = {Poisson, Jérôme},
  type = {XEP},
  number = {xxxx},
  version = {0.0.1},
  institution = {XMPP Standards Foundation},
  url = {https://xmpp.org/extensions/xep-xxxx.html},
  date = {2025-01-12/2025-01-12},
}

END