mirror of
https://github.com/moparisthebest/xeps
synced 2024-12-22 15:48:52 -05:00
300 lines
11 KiB
XML
300 lines
11 KiB
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>Experimental</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.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>&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 <encryption/> 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>
|