No Description
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

xep-0380.xml 11KB

  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <!DOCTYPE xep SYSTEM 'xep.dtd' [
  3. <!ENTITY % ents SYSTEM 'xep.ent'>
  4. %ents;
  5. ]>
  6. <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
  7. <xep>
  8. <header>
  9. <title>Explicit Message Encryption</title>
  10. <abstract>This specification provides a way to mark encrypted messages so the
  11. recipient can discover how to decrypt it.</abstract>
  13. <number>0380</number>
  14. <status>Deferred</status>
  15. <type>Standards Track</type>
  16. <sig>Standards</sig>
  17. <approver>Council</approver>
  18. <dependencies>
  19. <spec>XMPP Core</spec>
  20. <spec>XMPP IM</spec>
  21. <spec>XEP-0030</spec>
  22. </dependencies>
  23. <supersedes/>
  24. <supersededby/>
  25. <shortname>EME</shortname>
  26. <author>
  27. <firstname>Emmanuel Gil</firstname>
  28. <surname>Peyrot</surname>
  29. <email></email>
  30. <jid></jid>
  31. </author>
  32. <revision>
  33. <version>0.2.0</version>
  34. <date>2018-01-25</date>
  35. <initials>XEP Editor (jwi)</initials>
  36. <remark>Defer due to lack of activity.</remark>
  37. </revision>
  38. <revision>
  39. <version>0.1</version>
  40. <date>2016-10-26</date>
  41. <initials>fs</initials>
  42. <remark>
  43. <p>Initial published version approved by the XMPP Council.</p>
  44. </remark>
  45. </revision>
  46. <revision>
  47. <version>0.0.2</version>
  48. <date>2016-08-28</date>
  49. <initials>egp</initials>
  50. <remark><ul>
  51. <li>Made the 'name' attribute optional for existing mechanisms.</li>
  52. <li>Added a remark about the possibility to hide encrypted messages
  53. following user input.</li>
  54. <li>Made explicit that this protocol affects any encryption mechanism,
  55. present or future, not only those listed here.</li>
  56. <li>Display the namespace of the encryption mechanism in the default
  57. messages.</li>
  58. </ul></remark>
  59. </revision>
  60. <revision>
  61. <version>0.0.1</version>
  62. <date>2016-08-14</date>
  63. <initials>egp</initials>
  64. <remark><p>First draft.</p></remark>
  65. </revision>
  66. </header>
  67. <section1 topic='Introduction' anchor='intro'>
  68. <p>In the past few years we have seen a strong interest in end to end
  69. encryption, with multiple competing mechanisms being defined on top of
  70. XMPP (e.g., &xep0027;, &xep0364; or &xep0373;). This specification
  71. addresses the lack of proper discoverability of most of these solutions by
  72. adding a machine-readable explanation of how a specific message has been
  73. encrypted.</p>
  74. <p>In a federated network where no central entity can mandate a particular
  75. encryption mechanism, it becomes important to allow end users to know that
  76. a message could not be decrypted (e.g., due to a missing plugin), and to
  77. never fail to display that a message has been received due to that.</p>
  78. </section1>
  79. <section1 topic='Requirements' anchor='reqs'>
  80. <p>This document addresses the following requirements:</p>
  81. <ol>
  82. <li>Enable a client to mark a message as encrypted.</li>
  83. <li>Enable a client to determine whether a message was encrypted, no matter
  84. the encryption mechanism used.</li>
  85. <li>Enable a client to offer the user a possibility to decrypt a received
  86. message (depending on the encryption method).</li>
  87. <li>Enable a client to offer the user a possibility to decrypt subsequently
  88. received messages.</li>
  89. </ol>
  90. <p>This document DOES NOT address the non-message usecases, encrypted
  91. presence and iq have very different requirements than those defined
  92. here.</p>
  93. </section1>
  94. <section1 topic='Use Cases' anchor='usecases'>
  95. <section2 topic='Basic Flow' anchor='flow'>
  96. <p>Romeo, wanting to get Juliet’s attention but not wanting to reveal his
  97. intentions to the montague.lit nor to the capulet.lit servers, sends an
  98. encrypted message tagged as OTR, as follows:</p>
  99. <example caption='Example of tagged message encrypted with OTR'><![CDATA[
  100. <message to='juliet@capulet.lit/balcony'
  101. from='romeo@montague.lit/orchard'
  102. id='secret1'>
  103. <body>?OTR?v23?...</body>
  104. <encryption xmlns='urn:xmpp:eme:0'
  105. namespace='urn:xmpp:otr:0'/>
  106. </message>
  107. ]]></example>
  108. <p>Juliet’s client, noticing it does not have any OTR capability, will
  109. display that the message was encrypted but that it is not able to decrypt
  110. it instead of displaying the body, for example:</p>
  111. <div class='example'>
  112. <p>This message was encrypted with OTR (urn:xmpp:otr:0) and could not be
  113. decrypted.</p>
  114. </div>
  115. <p>Juliet may then communicate to Romeo that she was unable to receive his
  116. message, through an error, or maybe out of band.</p>
  117. <p>Romeo, standing firm in his belief that they should not communicate
  118. without encryption in their world where anyone could be a malicious
  119. listener, then discovers that one of Juliet’s clients support &xep0373; and
  120. subsequently starts an encrypted session using that protocol.</p>
  121. <example caption='Example of tagged message encrypted with OX'><![CDATA[
  122. <message to='juliet@capulet.lit/balcony'
  123. from='romeo@montague.lit/orchard'
  124. id='secret2'>
  125. <openpgp xmlns='urn:xmpp:openpgp:0'>
  126. ...
  127. </openpgp>
  128. <body>This message is encrypted with OpenPGP for XMPP.</body>
  129. <encryption xmlns='urn:xmpp:eme:0'
  130. namespace='urn:xmpp:openpgp:0'/>
  131. </message>
  132. ]]></example>
  133. <p>Upon receiving this message, Juliet’s current client prompts her to enable
  134. a plugin, or even do it on its own, possible representations include:</p>
  135. <div class='example'>
  136. <p>This message was encrypted with OpenPGP for XMPP
  137. (urn:xmpp:openpgp:0), <link url="#">click here</link> to enable this
  138. plugin.</p>
  139. </div>
  140. </section2>
  141. <section2 topic='Protocols Supported' anchor='protocols'>
  142. <p>Any encryption mechanism using message as a transport is a candidate, and
  143. MAY have a 'name' attribute to help the receiving client display it to the
  144. user, in case this client doesn’t understand its namespace yet. A 'name'
  145. attribute SHOULD NOT be included for the protocols listed herein, and
  146. SHOULD be ignored by a receiving client:</p>
  147. <table>
  148. <tr>
  149. <th>Name</th>
  150. <th>Namespace</th>
  151. <th>Specification</th>
  152. </tr>
  153. <tr>
  154. <td>OTR</td>
  155. <td>urn:xmpp:otr:0</td>
  156. <td>&xep0364;</td>
  157. </tr>
  158. <tr>
  159. <td>Legacy OpenPGP</td>
  160. <td>jabber:x:encrypted</td>
  161. <td>&xep0027;</td>
  162. </tr>
  163. <tr>
  164. <td>OpenPGP for XMPP</td>
  165. <td>urn:xmpp:openpgp:0</td>
  166. <td>&xep0373;</td>
  167. </tr>
  168. <!--<tr>
  169. <td>OMEMO</td>
  170. <td>urn:xmpp:omemo:0</td>
  171. <td></td>
  172. </tr>-->
  173. </table>
  174. </section2>
  175. <section2 topic='Determining Support' anchor='disco'>
  176. <p>If an entity supports the Encrypted Message Extension protocol, it MUST
  177. report that by including a &xep0030; feature of "urn:xmpp:eme:0" in
  178. response to disco#info requests:</p>
  179. <example caption='Client queries for entity features'><![CDATA[
  180. <iq type='get'
  181. id='disco1'
  182. to='juliet@capulet.lit/balcony'
  183. from='romeo@montague.lit/orchard'>
  184. <query xmlns=''/>
  185. </iq>
  186. ]]></example>
  187. <example caption='Entity responds with features'><![CDATA[
  188. <iq type='result'
  189. id='disco1'
  190. to='romeo@montague.lit/orchard'
  191. from='juliet@capulet.lit/balcony'>
  192. <query xmlns=''>
  193. ...
  194. <feature var='urn:xmpp:eme:0'/>
  195. ...
  196. </query>
  197. </iq>
  198. ]]></example>
  199. <p>Support can also be determined via &xep0115;, a.k.a. "caps".</p>
  200. </section2>
  201. </section1>
  202. <section1 topic='Business Rules' anchor='rules'>
  203. <p>Entities MUST report a failure to the user if they cannot decrypt an
  204. incoming message for any reason, and MAY prompt the user to install or
  205. enable a plugin to decrypt it.</p>
  206. <p>Entities SHOULD include a non-encrypted body as possible, since older
  207. clients not supporting this protocol might otherwise ignore messages sent
  208. with an unknown encryption, making both the sender frustrated that their
  209. message did not get an answer, and the recipient frustrated that they never
  210. saw any message.</p>
  211. <p>A sender entity MAY include the &lt;encryption/&gt; element even if the
  212. recipient doesn’t advertise support for it in their disco, or isn’t
  213. currently connected, since the recipient may be using multiple clients with
  214. different capabilities.</p>
  215. <p>A sender entity MAY include a 'name' attribute for any encryption
  216. mechanism not listed in this specification, to help the receiving entity
  217. present it to the user, but SHOULD NOT include one for the ones listed
  218. here.</p>
  219. <p>A receiving entity MUST NOT use the 'name' attribute if it is present and
  220. they already have a name associated with it.</p>
  221. <p>A receiving entity MAY not display anything in case an encrypted message
  222. has been received, if the user agreed to that behaviour.</p>
  223. </section1>
  224. <section1 topic='Internationalization Considerations' anchor='i18n'>
  225. <p>When a message is marked with an encryption tag and can not be decrypted,
  226. the body can safely be ignored and a localized message displayed
  227. instead.</p>
  228. <p>If an entity includes a 'name' attribute, it should attempt to localise it
  229. to the best of its abilities for the receiving client.</p>
  230. </section1>
  231. <section1 topic='Security Considerations' anchor='security'>
  232. <p>A malicious entity could try to mimick the style of a client’s failure
  233. message, maybe including a link to a compromised plugin, so a client should
  234. not make those missing plugin messages look like normal messages.</p>
  235. </section1>
  236. <section1 topic='IANA Considerations' anchor='iana'>
  237. <p>This document requires no interaction with the Internet Assigned Numbers
  238. Authority (IANA).</p>
  239. </section1>
  240. <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  241. <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
  242. <p>This specification defines the following XML namespace:</p>
  243. <ul>
  244. <li>'urn:xmpp:eme:0'</li>
  245. </ul>
  246. </section2>
  247. </section1>
  248. <section1 topic='XML Schema' anchor='schema'>
  249. <code><![CDATA[
  250. <?xml version='1.0' encoding='UTF-8'?>
  251. <xs:schema attributeFormDefault="unqualified"
  252. elementFormDefault="qualified"
  253. targetNamespace="urn:xmpp:eme:0"
  254. xmlns:xs="">
  255. <xs:annotation>
  256. <xs:documentation>
  257. The protocol documented by this schema is defined in
  258. XEP-xxxx:
  259. </xs:documentation>
  260. </xs:annotation>
  261. <xs:element name="encryption">
  262. <xs:complexType>
  263. <xs:attribute type="xs:string" use="required" name="namespace"/>
  264. <xs:attribute type="xs:string" use="optional" name="name"/>
  265. </xs:complexType>
  266. </xs:element>
  267. </xs:schema>
  268. ]]></code>
  269. </section1>
  270. <section1 topic='Acknowledgements' anchor='ack'>
  271. <p>Thanks to Mathieu Pasquet for his feedback.</p>
  272. </section1>
  273. </xep>