xeps/xep-0380.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Explicit Message Encryption</title>
  <abstract>This specification provides a way to mark encrypted messages so the
    recipient can discover how to decrypt it.</abstract>
  &LEGALNOTICE;
  <number>0380</number>
  <status>Deferred</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XMPP IM</spec>
    <spec>XEP-0030</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>EME</shortname>
  &linkmauve;
  <revision>
    <version>0.4.0</version>
    <date>2021-11-18</date>
    <initials>melvo</initials>
    <remark>
      <p>Add new OMEMO namespaces:</p>
      <ul>
        <li>Add 'urn:xmpp:omemo:1' for OMEMO versions since 0.4.0</li>
        <li>Add 'urn:xmpp:omemo:2' for OMEMO versions since 0.8.0</li>
      </ul>
    </remark>
  </revision>
  <revision>
    <version>0.3.0</version>
    <date>2019-04-28</date>
    <initials>lnj</initials>
    <remark>
      <p>Added OMEMO encryption namespace.</p>
      <p>Made XEP experimental again.</p>
    </remark>
  </revision>
  <revision>
    <version>0.2.0</version>
    <date>2018-01-25</date>
    <initials>XEP Editor (jwi)</initials>
    <remark>Defer due to lack of activity.</remark>
  </revision>
  <revision>
	<version>0.1</version>
	<date>2016-10-26</date>
	<initials>fs</initials>
	<remark>
	  <p>Initial published version approved by the XMPP Council.</p>
	</remark>
  </revision>
  <revision>
    <version>0.0.2</version>
    <date>2016-08-28</date>
    <initials>egp</initials>
    <remark><ul>
      <li>Made the 'name' attribute optional for existing mechanisms.</li>
      <li>Added a remark about the possibility to hide encrypted messages
        following user input.</li>
      <li>Made explicit that this protocol affects any encryption mechanism,
        present or future, not only those listed here.</li>
      <li>Display the namespace of the encryption mechanism in the default
        messages.</li>
    </ul></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2016-08-14</date>
    <initials>egp</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>

<section1 topic='Introduction' anchor='intro'>
  <p>In the past few years we have seen a strong interest in end to end
    encryption, with multiple competing mechanisms being defined on top of
    XMPP (e.g., &xep0027;, &xep0364; or &xep0373;).  This specification
    addresses the lack of proper discoverability of most of these solutions by
    adding a machine-readable explanation of how a specific message has been
    encrypted.</p>
  <p>In a federated network where no central entity can mandate a particular
    encryption mechanism, it becomes important to allow end users to know that
    a message could not be decrypted (e.g., due to a missing plugin), and to
    never fail to display that a message has been received due to that.</p>
</section1>

<section1 topic='Requirements' anchor='reqs'>
  <p>This document addresses the following requirements:</p>
  <ol>
    <li>Enable a client to mark a message as encrypted.</li>
    <li>Enable a client to determine whether a message was encrypted, no matter
      the encryption mechanism used.</li>
    <li>Enable a client to offer the user a possibility to decrypt a received
      message (depending on the encryption method).</li>
    <li>Enable a client to offer the user a possibility to decrypt subsequently
      received messages.</li>
  </ol>
  <p>This document DOES NOT address the non-message usecases, encrypted
    presence and iq have very different requirements than those defined
    here.</p>
</section1>

<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Basic Flow' anchor='flow'>
  <p>Romeo, wanting to get Juliet’s attention but not wanting to reveal his
    intentions to the montague.lit nor to the capulet.lit servers, sends an
    encrypted message tagged as OTR, as follows:</p>
  <example caption='Example of tagged message encrypted with OTR'><![CDATA[
<message to='juliet@capulet.lit/balcony'
         from='romeo@montague.lit/orchard'
         id='secret1'>
  <body>?OTR?v23?...</body>
  <encryption xmlns='urn:xmpp:eme:0'
              namespace='urn:xmpp:otr:0'/>
</message>
]]></example>

  <p>Juliet’s client, noticing it does not have any OTR capability, will
    display that the message was encrypted but that it is not able to decrypt
    it instead of displaying the body, for example:</p>
  <div class='example'>
    <p>This message was encrypted with OTR (urn:xmpp:otr:0) and could not be
      decrypted.</p>
  </div>

  <p>Juliet may then communicate to Romeo that she was unable to receive his
    message, through an error, or maybe out of band.</p>
  <p>Romeo, standing firm in his belief that they should not communicate
    without encryption in their world where anyone could be a malicious
    listener, then discovers that one of Juliet’s clients support &xep0373; and
    subsequently starts an encrypted session using that protocol.</p>
  <example caption='Example of tagged message encrypted with OX'><![CDATA[
<message to='juliet@capulet.lit/balcony'
         from='romeo@montague.lit/orchard'
         id='secret2'>
  <openpgp xmlns='urn:xmpp:openpgp:0'>
    ...
  </openpgp>
  <body>This message is encrypted with OpenPGP for XMPP.</body>
  <encryption xmlns='urn:xmpp:eme:0'
              namespace='urn:xmpp:openpgp:0'/>
</message>
]]></example>

  <p>Upon receiving this message, Juliet’s current client prompts her to enable
    a plugin, or even do it on its own, possible representations include:</p>
  <div class='example'>
    <p>This message was encrypted with OpenPGP for XMPP
      (urn:xmpp:openpgp:0), <link url="#">click here</link> to enable this
      plugin.</p>
  </div>
</section2>

<section2 topic='Protocols Supported' anchor='protocols'>
  <p>Any encryption mechanism using message as a transport is a candidate, and
    MAY have a 'name' attribute to help the receiving client display it to the
    user, in case this client doesn’t understand its namespace yet.  A 'name'
    attribute SHOULD NOT be included for the protocols listed herein, and
    SHOULD be ignored by a receiving client:</p>

  <table>
    <tr>
      <th>Name</th>
      <th>Namespace</th>
      <th>Specification</th>
    </tr>
    <tr>
      <td>OTR</td>
      <td>urn:xmpp:otr:0</td>
      <td>&xep0364;</td>
    </tr>
    <tr>
      <td>Legacy OpenPGP</td>
      <td>jabber:x:encrypted</td>
      <td>&xep0027;</td>
    </tr>
    <tr>
      <td>OpenPGP for XMPP</td>
      <td>urn:xmpp:openpgp:0</td>
      <td>&xep0373;</td>
    </tr>
    <tr>
      <td>OMEMO</td>
      <td>eu.siacs.conversations.axolotl</td>
      <td>https://xmpp.org/extensions/attic/xep-0384-0.3.0.html</td>
    </tr>
    <tr>
      <td>OMEMO 1</td>
      <td>urn:xmpp:omemo:1</td>
      <td>https://xmpp.org/extensions/attic/xep-0384-0.4.0.html</td>
    </tr>
    <tr>
      <td>OMEMO 2</td>
      <td>urn:xmpp:omemo:2</td>
      <td>&xep0384;</td>
    </tr>
  </table>
</section2>

<section2 topic='Determining Support' anchor='disco'>
  <p>If an entity supports the Encrypted Message Extension protocol, it MUST
    report that by including a &xep0030; feature of "urn:xmpp:eme:0" in
    response to disco#info requests:</p>
  <example caption='Client queries for entity features'><![CDATA[
<iq type='get'
    id='disco1'
    to='juliet@capulet.lit/balcony'
    from='romeo@montague.lit/orchard'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>

  <example caption='Entity responds with features'><![CDATA[
<iq type='result'
    id='disco1'
    to='romeo@montague.lit/orchard'
    from='juliet@capulet.lit/balcony'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='urn:xmpp:eme:0'/>
    ...
  </query>
</iq>
]]></example>

  <p>Support can also be determined via &xep0115;, a.k.a. "caps".</p>
</section2>
</section1>

<section1 topic='Business Rules' anchor='rules'>
  <p>Entities MUST report a failure to the user if they cannot decrypt an
    incoming message for any reason, and MAY prompt the user to install or
    enable a plugin to decrypt it.</p>
  <p>Entities SHOULD include a non-encrypted body as possible, since older
    clients not supporting this protocol might otherwise ignore messages sent
    with an unknown encryption, making both the sender frustrated that their
    message did not get an answer, and the recipient frustrated that they never
    saw any message.</p>
  <p>A sender entity MAY include the &lt;encryption/&gt; element even if the
    recipient doesn’t advertise support for it in their disco, or isn’t
    currently connected, since the recipient may be using multiple clients with
    different capabilities.</p>
  <p>A sender entity MAY include a 'name' attribute for any encryption
    mechanism not listed in this specification, to help the receiving entity
    present it to the user, but SHOULD NOT include one for the ones listed
    here.</p>
  <p>A receiving entity MUST NOT use the 'name' attribute if it is present and
    they already have a name associated with it.</p>
  <p>A receiving entity MAY not display anything in case an encrypted message
    has been received, if the user agreed to that behaviour.</p>
</section1>

<section1 topic='Internationalization Considerations' anchor='i18n'>
  <p>When a message is marked with an encryption tag and can not be decrypted,
    the body can safely be ignored and a localized message displayed
    instead.</p>
  <p>If an entity includes a 'name' attribute, it should attempt to localise it
    to the best of its abilities for the receiving client.</p>
</section1>

<section1 topic='Security Considerations' anchor='security'>
  <p>A malicious entity could try to mimick the style of a client’s failure
    message, maybe including a link to a compromised plugin, so a client should
    not make those missing plugin messages look like normal messages.</p>
</section1>

<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with the Internet Assigned Numbers
    Authority (IANA).</p>
</section1>

<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
    <p>This specification defines the following XML namespace:</p>
    <ul>
      <li>'urn:xmpp:eme:0'</li>
    </ul>
  </section2>
</section1>

<section1 topic='XML Schema' anchor='schema'>
  <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema attributeFormDefault="unqualified"
  elementFormDefault="qualified"
  targetNamespace="urn:xmpp:eme:0"
  xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-xxxx: http://xmpp.org/extensions/xep-xxxx.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name="encryption">
    <xs:complexType>
      <xs:attribute type="xs:string" use="required" name="namespace"/>
      <xs:attribute type="xs:string" use="optional" name="name"/>
    </xs:complexType>
  </xs:element>

</xs:schema>
]]></code>
</section1>

<section1 topic='Acknowledgements' anchor='ack'>
  <p>Thanks to Mathieu Pasquet for his feedback.</p>
</section1>
</xep>