Update JET

inbox/jet.xml

@@ -8,7 +8,7 @@
 <xep>
 <header>
   <title>Jingle Encrypted Transports</title>
-  <abstract>This specification defines a method that allows to use established encryption schemes like OpenPGP or OMEMO for end-to-end encryption of Jingle transports.</abstract>
+  <abstract>This specification defines a method that allows to use established encryption schemes for end-to-end encryption of Jingle transports.</abstract>
   &LEGALNOTICE;
   <number>XXXX</number>
   <status>ProtoXEP</status>
@@ -73,23 +73,23 @@
     <tr>
       <td>Envelope Element</td>
       <td>EE</td>
-      <td>Output of an established end-to-end encryption methods when encrypting TS. Examples for such methods could be &xep0384; or &xep0374;.</td> 
+      <td>Output element of an established end-to-end encryption method when encrypting TS.</td> 
     </tr>
   </table>
 </section1>
 <section1 topic='Principle' anchor='principle'>
-  <p>Lets assume Romeo wants to initiate an encrypted Jingle session with Juliet. Prior to the Jingle session initiation, an already existing, established and (ideally) authenticated end-to-end encryption session between Romeo and Juliet MUST exist. Examples for suitable encryption sessions are &xep0384; and &xep0374;. This session is needed to transfer the Transport Secret from Romeo to Juliet.</p>
+  <p>Lets assume Romeo wants to initiate an encrypted Jingle session with Juliet. Prior to the Jingle session initiation, an already existing, established and (ideally) authenticated end-to-end encryption session between Romeo and Juliet MUST exist. This session is needed to transfer the Transport Secret from Romeo to Juliet.</p>
   <p>When this precondition is met, Romeo initially generates a transport key (TK) and associated initialization vector (IV). These will later be used by the sender to encrypt, and respectively by the recipient to decrypt data that is exchanged. This protocol defines a set of usable <link url='#ciphers'>ciphers</link> from which Romeo might choose. TK and IV are serialized to create the transport secret (TS).</p>
   <p>Next Romeo uses her established encryption session with Juliet to encrypt TS. The resulting envelope element (EE) will be part of the Jingle session initiation as child of the JET &secret; element.</p>
-  <p>When Juliet receives Romeos session request, she decrypts EE to retrieve TS, from which she can deserialize TK and IV. Now she and Romeo can go on with the session negotiation. Once the session is established, data can be encrypted and exchanged.</p>
+  <p>When Juliet receives Romeos session request, she decrypts EE to retrieve TS, from which she can deserialize TK and IV. Now she and Romeo can go on with the session negotiation. Once the session is established, data can be encrypted and exchanged. Both parties MUST keep a copy of TS in cache until the Jingle session is ended.</p>
 </section1>
 <section1 topic='Encrypted Jingle File Transfer using JET' anchor='jft'>
   <p>&xep0234; has the disadvantage, that transmitted files are not encrypted (aside from regular TLS transport encryption), which means that intermediate nodes like XMPP/proxy server(s) have access to the transferred data. Considering that end-to-end encryption becomes more and more important to protect free speech and personal expression, this is a major flaw that needs to be addressed.</p>
   <p>In order to initiate an encrypted file transfer, the initiator includes a JET &secret; in the Jingle file transfer request.</p>
   
-  <section2 topic='File offer'>
+  <section2 topic='File Offer'>
-    <p>In this scenario Romeo wants to send an encrypted text file over to Juliet. He chooses to use their existing &xep0384; session to do so. First, he generates a fresh AES-256 transport key and IV. TK and IV are serialized into TS which is then encrypted using Romeos OMEMO session with Juliet.</p>
+    <p>In this scenario Romeo wants to send an encrypted text file over to Juliet. First, he generates a fresh AES-256 transport key and IV. TK and IV are serialized into TS which is then encrypted using Romeos end-to-end-encryption session with Juliet.</p>
-    <p>The resulting OMEMO element (EE) is sent as part of the security element along with the rest of the jingle stanza over to Juliet.</p>
+    <p>The resulting envelope element (EE) is sent as part of the security element along with the rest of the jingle stanza over to Juliet.</p>
     <example caption="Romeo initiates an encrypted file offer"><![CDATA[
 <iq from='romeo@montague.example/dr4hcr0st3lup4c'
     id='nzu25s8'
@@ -125,13 +125,8 @@
       <security xmlns='urn:xmpp:jingle:jet:0'
                 name='a-file-offer'
                 cipher='urn:xmpp:ciphers:aes-256-gcm-nopadding'
-                type='urn:xmpp:omemo:0'>
+                type='urn:xmpp:encryption:stub:0'>
-        <encrypted xmlns='urn:xmpp:omemo:0'>
+        <encrypted xmlns='urn:xmpp:encryption:stub:0'>
-          <header sid='27183'>
-            <key rid='31415'>BASE64ENCODED...</key>
-            <key rid='12321'>BASE64ENCODED...</key>
-            <iv>BASE64ENCODED...</iv>
-          </header>
           <payload>BASE64-ENCODED-ENCRYPTED-SECRET</payload>
         </encrypted>
       </security>
@@ -139,12 +134,12 @@
   </jingle>
 </iq>]]></example>
 
-    <p>Juliet decrypts the OMEMO element (EE) using her session with Romeo to retrieve TS from which she deserializes TK and IV. Both Juliet and Romeo then carry on with the session negotiation as described in &xep0234;. Before Romeo starts transmitting the file, he encrypts it using TK and IV. He then transmitts the encrypted file over to Juliet.</p>
+    <p>Juliet decrypts the envelope element (EE) using her session with Romeo to retrieve TS from which she deserializes TK and IV. Both Juliet and Romeo then carry on with the session negotiation as described in &xep0234;. Before Romeo starts transmitting the file, he encrypts it using TK and IV. He then transmitts the encrypted file over to Juliet.</p>
     <p>When Juliet received the file, she uses the TK and IV to decrypt the received file.</p>
   </section2>
   
   <section2 topic='File Request'>
-    <p>Juliet might want to request a file transfer from Romeo. This can be the case, when Romeo hosts the file. In order to do so, she sends generates TK and IV, creates TS from those and encrypts TS with an encryption method of her choice to get EE. TK and IV will be used by Romeo to encrypt the requested file before sending it to Juliet. In this example we assume, that Romeo and Juliet secured their communications using &xep0374;.</p>
+    <p>Juliet might want to request a file transfer from Romeo. This can be the case, when Romeo hosts the file. In order to do so, she sends generates TK and IV, creates TS from those and encrypts TS with an encryption method of her choice to get EE. TK and IV will be used by Romeo to encrypt the requested file before sending it to Juliet.</p>
     <example caption="Juliet initiates an encrypted file request"><![CDATA[
 <iq from='juliet@capulet.example/yn0cl4bnw0yr3vym'
     id='wsn361c3'
@@ -174,20 +169,64 @@
       <security xmlns='urn:xmpp:jingle:jet:0'
                 name='a-file-request'
                 cipher='urn:xmpp:ciphers:aes-256-gcm-nopadding'
-                type='urn:xmpp:openpgp:0'>
+                type='urn:xmpp:encryption:stub:0'>
-        <signcrypt xmlns='urn:xmpp:openpgp:0'>
+        <encrypted xmlns='urn:xmpp:encryption:stub:0'>
-          <to jid='romeo@montague.example'/>
+          <payload>BASE64-ENCODED-ENCRYPTED-SECRET</payload>
-          <time stamp='2014-07-10T17:06:00+02:00'/>
+        </encrypted>
-          <rpad>f0rm1l4n4-mT8y33j!Y%fRSrcd^ZE4Q7VDt1L%WEgR!kv</rpad>
-          <payload>
-            <body xmlns='jabber:client'>BASE64-ENCODED-ENCRYPTED-SECRET</body>
-          </payload>
-        </signcrypt>
       </security>
     </content>
   </jingle>
 </iq>]]></example>
   </section2>
+
+  <section2 topic='Encrypted Ranged Transfers'>
+    <p>&xep0234; defines a way for parties to request ranged transfers. This can be used to resume interrupted transfers etc. In case of an interrupted transfer, the receiving party might be able to decrypt parts of the received file. When requesting a resumption of the transfer, the recipient therefore can use the index of the last successfully decrypted byte of the file as offset in the ranged transfer. Since a resumed transfer takes place in a new session, the old transport secret might no longer be available to either party. For that reason the receiver creates a new TS for the session-initiation. The sending party then encrypts and sends only the requested parts of the file.</p>
+    <example caption="Romeo requests the resumption of an interrupted transfer using a fresh transport secret"><![CDATA[
+<iq from='romeo@montague.example/dr4hcr0st3lup4c'
+    id='wsn361c3'
+    to='juliet@capulet.example/yn0cl4bnw0yr3vym'
+    type='set'>
+  <jingle xmlns='urn:xmpp:jingle:1'
+          action='session-initiate'
+          initiator='romeo@montague.example/dr4hcr0st3lup4c'
+          sid='uj3b2'>
+    <content creator='initiator' name='restart' senders='responder'>
+      <description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
+        <file>
+          <range offset='270336'/>
+          <hash xmlns='urn:xmpp:hashes:2'
+                algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
+        </file>
+      </description>
+      <transport xmlns='urn:xmpp:jingle:transports:s5b:1'
+             mode='tcp'
+                 sid='vj3hs98y'>
+        <candidate cid='hft54dqy'
+                   host='192.168.4.1'
+                   jid='romeo@montague.example/dr4hcr0st3lup4c'
+                   port='5086'
+                   priority='8257636'
+                   type='direct'/>
+        <candidate cid='hutr46fe'
+                   host='24.24.24.1'
+                   jid='romeo@montague.example/dr4hcr0st3lup4c'
+                   port='5087'
+                   priority='8258636'
+                   type='direct'/>
+      </transport>
+      <security xmlns='urn:xmpp:jingle:jet:0'
+                name='restart'
+                cipher='urn:xmpp:ciphers:aes-256-gcm-nopadding'
+                type='urn:xmpp:encryption:stub:0'>
+        <encrypted xmlns='urn:xmpp:encryption:stub:0'>
+          <payload>BASE64-ENCODED-ENCRYPTED-SECRET</payload>
+        </encrypted>
+      </security>
+    </content>
+  </jingle>
+</iq>]]></example>
+  </section2>
+
 </section1>
 
 <section1 topic='Ciphers' anchor='ciphers'>
@@ -218,11 +257,32 @@
   <p>The column 'serialization' describes, how the key and iv are serialized. "::" means plain concatenation of byte arrays.</p>
 </section1>
 
+<section1 topic='Determining Support' anchor='support'>
+  <p>To advertise its support for the Jingle Encrypted Transports, when replying to service discovery information ("disco#info") requests an entity MUST return URNs for any version, or extension of this protocol that the entity supports -- e.g., "urn:xmpp:jingle:jet:0" for this version, or "urn:xmpp:jingle:jet-stub:0" for a stub encryption method &VNOTE;.</p>
+  <example caption="Service discovery information request"><![CDATA[
+<iq from='romeo@montague.example/dr4hcr0st3lup4c'
+    id='uw72g176'
+    to='juliet@capulet.example/yn0cl4bnw0yr3vym'
+    type='get'>
+  <query xmlns='http://jabber.org/protocol/disco#info'/>
+</iq>]]></example>
+  <example caption="Service discovery information response"><![CDATA[
+<iq from='juliet@capulet.example/yn0cl4bnw0yr3vym'
+    id='uw72g176'
+    to='romeo@montague.example/dr4hcr0st3lup4c'
+    type='result'>
+  <query xmlns='http://jabber.org/protocol/disco#info'>
+    <feature var='urn:xmpp:jingle:jet:0'/>
+    <feature var='urn:xmpp:jingle:jet-stub:0'/>
+  </query>
+</iq>]]></example>
+  <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>
+</section1>
+
 <section1 topic='Security Considerations' anchor='security'>
   <p>The initiator SHOULD NOT use the generated key TK as IV, but instead generate a seperate random IV.</p>
   <p>Instead of falling back to unencrypted transfer in case something goes wrong, implementations MUST instead abort the Jingle session, informing the user.</p>
   <p>IMPORTANT: This approach does not deal with metadata. In case of &xep0234;, an attacker with access to the sent stanzas can for example still see the name of the file and other information included in the &lt;file/&gt; element.</p>
-  <p>When using OX as encryption method, clients might want to protect against replay attacks</p>
   <p>The responder MUST check, whether the envelope element belongs to the initiator to prevent MitM attacks</p>
 </section1>
 
@@ -236,7 +296,7 @@
 </section1>
 <section1 topic='TODO'>
   <ul>
-    <li>Service discovery</li>
+    <li>Split up the protocol into encryption method specific sub protocols (jet-omemo, jet-ox...)</li>
   </ul>
 </section1>
 </xep>