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-0396.xml 7.0KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134
  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <!DOCTYPE xep SYSTEM 'xep.dtd' [
  3. <!ENTITY secret "&lt;secret/&gt;">
  4. <!ENTITY % ents SYSTEM 'xep.ent'>
  5. %ents;
  6. ]>
  7. <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
  8. <xep>
  9. <header>
  10. <title>Jingle Encrypted Transports - OMEMO</title>
  11. <abstract>Extension for JET introducing OMEMO End-to-End Encrypted Jingle Transports.</abstract>
  12. &LEGALNOTICE;
  13. <number>0396</number>
  14. <status>Experimental</status>
  15. <type>Standards Track</type>
  16. <sig>Standards</sig>
  17. <approver>Council</approver>
  18. <dependencies>
  19. <spec>XEP-0391</spec>
  20. <spec>XEP-0234</spec>
  21. <spec>XEP-0384</spec>
  22. </dependencies>
  23. <supersedes/>
  24. <supersededby/>
  25. <shortname>jet-omemo</shortname>
  26. <schemaloc>
  27. <ns>jingle</ns>
  28. <url>http://xmpp.org/schemas/jingle.xsd</url>
  29. </schemaloc>
  30. <schemaloc>
  31. <ns>jingle:errors</ns>
  32. <url>http://xmpp.org/schemas/jingle-errors.xsd</url>
  33. </schemaloc>
  34. <registry/>
  35. <discuss>jingle</discuss>
  36. &paulschaub;
  37. <revision>
  38. <version>0.1</version>
  39. <date>2017-11-29</date>
  40. <initials>XEP Editor (jwi)</initials>
  41. <remark><p>Accepted by Council as Expremental XEP</p></remark>
  42. </revision>
  43. <revision>
  44. <version>0.0.1</version>
  45. <date>2017-10-06</date>
  46. <initials>vv</initials>
  47. <remark><p>First draft</p></remark>
  48. </revision>
  49. </header>
  50. <section1 topic='Introduction' anchor='intro'>
  51. <p>&xep0391; can be used to utilize different end-to-end encryption methods to secure Jingle Transports, eg. in the context of &xep0234;. This document aims to extend &xep0391; to allow the use of OMEMO encryption with Jingle transports. To achieve this goal, this protocol extension makes use of OMEMOs <link url='https://xmpp.org/extensions/xep-0384.html#usecases-keysend'>KeyTransportElements</link>.</p>
  52. </section1>
  53. <section1 topic='Mappings' anchor='mappings'>
  54. <p>Conveniently the OMEMO protocol already provides a way to transport key material to another entity. So called KeyTransportElements are basically normal OMEMO MessageElements, but without a payload, so the contained key can be used for something else (see Section 4.6 of <cite>XEP-0384</cite>). This extension uses the key encrypted in the KeyTransportMessages &lt;key&gt; attribute and initialization vector from the &lt;iv&gt; attribute to secure Jingle Transports. The key corresponds to the <cite>Transport Key</cite> of <cite>XEP-0391</cite>, while the iv corresponds to the <cite>Initialization Vector</cite>. The KeyTransportMessage is the equivalent to the <cite>Envelope Element</cite>. Note that within the Envelope Element, the Transport Key is encrypted with the OMEMO ratchet.</p>
  55. </section1>
  56. <section1 topic='Limitations' anchor='limitations'>
  57. <p>Unfortunately &xep0384; determines the type of the transported key to be AES-128-GCM-NoPadding, so no other configuration can be used in the context of this extension.</p>
  58. <p>Since OMEMO deviceIds are not bound to XMPP resources, the initiator MUST encrypt the Transport Key for every device of the recipient.</p>
  59. </section1>
  60. <section1 topic='Key Transport' anchor='transport'>
  61. <p>In order to transport a key to the responder, the initiator creates a fresh AES-128-GCM-NoPadding Transport Key and Initialization Vector and generates an OMEMO KeyTransportElement from it as described in <cite>XEP-0384</cite>. This is then added as a child of the JET &lt;security&gt; element. The 'cipher' attribute MUST be set to 'aes-128-gcm-nopadding:0' (see the <link url='https://xmpp.org/extensions/xep-0391.html#ciphers'>ciphers</link> section of <cite>XEP-0391</cite>). The value of the 'type' attribute must be set to the namespace of the used version of <cite>XEP-0384</cite> &VNOTE;.</p>
  62. <p></p>
  63. <example caption="Romeo initiates an OMEMO encrypted file offer"><![CDATA[
  64. <iq from='romeo@montague.example/dr4hcr0st3lup4c'
  65. id='nzu25s8'
  66. to='juliet@capulet.example/yn0cl4bnw0yr3vym'
  67. type='set'>
  68. <jingle xmlns='urn:xmpp:jingle:1'
  69. action='session-initiate'
  70. initiator='romeo@montague.example/dr4hcr0st3lup4c'
  71. sid='851ba2'>
  72. <content creator='initiator' name='a-file-offer' senders='initiator'>
  73. <description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
  74. <file>
  75. <date>1969-07-21T02:56:15Z</date>
  76. <desc>This is a test. If this were a real file...</desc>
  77. <media-type>text/plain</media-type>
  78. <name>test.txt</name>
  79. <range/>
  80. <size>6144</size>
  81. <hash xmlns='urn:xmpp:hashes:2'
  82. algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
  83. </file>
  84. </description>
  85. <transport xmlns='urn:xmpp:jingle:transports:s5b:1'
  86. mode='tcp'
  87. sid='vj3hs98y'>
  88. <candidate cid='hft54dqy'
  89. host='192.168.4.1'
  90. jid='romeo@montague.example/dr4hcr0st3lup4c'
  91. port='5086'
  92. priority='8257636'
  93. type='direct'/>
  94. </transport>
  95. <security xmlns='urn:xmpp:jingle:jet:0'
  96. name='a-file-offer'
  97. cipher='urn:xmpp:ciphers:aes-128-gcm-nopadding'
  98. type='eu.siacs.conversations.axolotl'>
  99. <encrypted xmlns='eu.siacs.conversations.axolotl'>
  100. <header sid='27183'>
  101. <key rid='31415'>BASE64ENCODED...</key>
  102. <key prekey="true" rid='12321'>BASE64ENCODED...</key>
  103. <!-- ... -->
  104. <iv>BASE64ENCODED...</iv>
  105. </header>
  106. </encrypted>
  107. </security>
  108. </content>
  109. </jingle>
  110. </iq>]]></example>
  111. <p>The recipient decrypts the OMEMO KeyTransportElement to retrieve the Transport Secret. Transport Key and Initialization Vector are later used to encrypt/decrypt data as described in &xep0391;.</p>
  112. </section1>
  113. <section1 topic='Determining Support' anchor='support'>
  114. <p>To advertise its support for JET-OMEMO, when replying to service discovery information ("disco#info") requests an entity MUST return URNs for any version of this extension, as well as of the JET extension that the entity supports -- e.g., "urn:xmpp:jingle:jet-omemo:0" for this version, or "urn:xmpp:jingle:jet:0" for &xep0391; &VNOTE;.</p>
  115. <example caption="Service discovery information request"><![CDATA[
  116. <iq from='romeo@montague.example/dr4hcr0st3lup4c'
  117. id='uw72g176'
  118. to='juliet@capulet.example/yn0cl4bnw0yr3vym'
  119. type='get'>
  120. <query xmlns='http://jabber.org/protocol/disco#info'/>
  121. </iq>]]></example>
  122. <example caption="Service discovery information response"><![CDATA[
  123. <iq from='juliet@capulet.example/yn0cl4bnw0yr3vym'
  124. id='uw72g176'
  125. to='romeo@montague.example/dr4hcr0st3lup4c'
  126. type='result'>
  127. <query xmlns='http://jabber.org/protocol/disco#info'>
  128. <feature var='urn:xmpp:jingle:jet:0'/>
  129. <feature var='urn:xmpp:jingle:jet-omemo:0'/>
  130. </query>
  131. </iq>]]></example>
  132. <p>In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.</p>
  133. </section1>
  134. </xep>