1
0
mirror of https://github.com/moparisthebest/xeps synced 2024-10-31 15:35:07 -04:00
xeps/xep-0380.xml

322 lines
11 KiB
XML
Raw Normal View History

<?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;
2016-10-26 16:44:25 -04:00
<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>
2019-01-27 13:25:10 -05:00
&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>
2019-04-28 11:46:48 -04:00
<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>
2016-10-26 16:44:25 -04:00
<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 Juliets 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>Juliets 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'>
2016-10-26 16:44:25 -04:00
<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 Juliets 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, Juliets current client prompts her to enable
a plugin, or even do it on its own, possible representations include:</p>
<div class='example'>
2016-10-26 16:44:25 -04:00
<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 doesnt 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>
2019-04-28 11:46:48 -04:00
<tr>
<td>OMEMO</td>
2019-04-28 11:46:48 -04:00
<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>
2019-04-28 11:46:48 -04:00
<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 doesnt advertise support for it in their disco, or isnt
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 clients 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>