XEP-xxxx: OMEMO Encrypted Jingle File Transfer

WARNING: This document has not yet been accepted for consideration or approved in any official manner by the XMPP Standards Foundation, and this document is not yet an XMPP Extension Protocol (XEP). If this document is accepted as a XEP by the XMPP Council, it will be published at <http://xmpp.org/extensions/> and announced on the <standards@xmpp.org> mailing list.

Table of Contents

1. Introduction

Jingle File Transfer (XEP-0234) [1] describes a very flexible and powerful method for peer-to-peer file transfer with interchangable transports. Unfortunatly only some of those transports can by encrypted (e.g. Jingle In-Band Bytestreams Transport Method (XEP-0261) [2]) and none integrate into existing end-to-end encryption schemes. This specification defines an approach to encrypt the actual file before transferring it by using the OMEMO encryption. Note that the encryption can and should happen on the fly.

2. Requirements

• Keep the protocol flow as close to Jingle File Transfer as possible and only change the file description
• Keep the required changes for a client that already supports Jingle File Transfer and the OMEMO encryption to a minimum

3. Use Cases

Remeo and Juliet are already engaged in a private, OMEMO encrypted conversation and want to negotiate a file transfer. The session-initiate stanza of an OMEMO encrypted file tranfer differs from the session-initiate of a regular Jingle File Transfer in that the 'file' element is wrapped in an 'encrypted' element. This reuses the KeyTransportElement from the OMEMO specification.

Example 1. Initiator sends session-initiate

<iq from='romeo@montague.lit/orchard'
    id='nzu25s8'
    to='juliet@capulet.lit/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-initiate'
          initiator='romeo@montague.lit/orchard'
          sid='851ba2'>
    <content creator='initiator' name='a-file-offer'>
      <description xmlns='urn:xmpp:jingle:apps:encrypted:file-transfer:0'>
        <encrypted xmlns='urn:xmpp:omemo:0'>
          <header sid='27183'>
            <key rid='31415'>BASE64ENCODED...</key>
            <key rid='12321'>BASE64ENCODED...</key>
            <iv>BASE64ENCODED...</iv>
          </header>
          <file>
            <date>2015-08-30T23:24:05Z</date>
            <desc>This is a test. If this were a real file...</desc>
            <media-type>image/png</media-type>
            <name>omemo.png</name>
            <range/>
            <size>51158</size>
            <hash xmlns='urn:xmpp:hashes:1' algo='sha-1'/>
        </file>
        </encrypted>
      </description>
      <transport xmlns='urn:xmpp:jingle:transports:s5b:1'
        	 mode='tcp'
                 sid='vj3hs98y'>
        <candidate cid='hft54dqy'
                   host='192.168.4.1'
                   jid='romeo@montague.lit/orchard'
                   port='5086'
                   priority='8257636'
                   type='direct'/>
        <candidate cid='hutr46fe'
                   host='24.24.24.1'
                   jid='romeo@montague.lit/orchard'
                   port='5087'
                   priority='8258636'
                   type='direct'/>
      </transport>
    </content>
  </jingle>
</iq>
  

The rest of the negotiation is analogous to a regular file transfer. The file is then encrypted and decrypted respectively using the key/IV pair extracted from the encryption header in AES-GCM. The crypto operation SHOULD happen on the fly.

4. Communicating the Checksum or Hashing Algorithm

Even though AES-GCM comes with build-in integrity protection the hosting entity can—at any time during the lifetime of the session—communicate the checksum of the encrypted file.

Example 2. Initiator sends checksum in session-info

<iq from='romeo@montague.lit/orchard'
    id='kqh401b5'
    to='juliet@capulet.lit/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-info'
          initiator='romeo@montague.lit/orchard'
          sid='a73sjjvkla37jfea'>
    <checksum xmlns='urn:xmpp:jingle:apps:encrypted:file-transfer:0'>
      <file>
        <hash xmlns='urn:xmpp:hashes:1' algo='sha-1'>552da749930852c69ae5d2141d3766b1</hash>
      </file>
    </checksum>
  </jingle>
</iq>
  

5. Business Rules

• AES-GCM being a block cipher will influence the file size. The file size reported in the session intilization MUST be the encrypted one.
• The file hash MUST be the hash of encrypted file.
• An encryption header MUST only be used for one session. However when doing a rangend tranfer on a previously aborted file the key/IV pair MUST be reused and packed into a new header to keep the integrity of the file.

6. Determining Support

To advertise its support for the OMEMO Encrypted Jingle File Transfer, when replying to service discovery information ("disco#info") requests an entity MUST return URNs for any version of this protocol that the entity supports -- e.g., 'urn:xmpp:jingle:apps:encrypted:file-transfer:0' for this version (see Namespace Versioning regarding the possibility of incrementing the version number).

Example 3. Service discovery information request

<iq from='romeo@montague.lit/orchard'
    id='uw72g176'
    to='juliet@capulet.lit/balcony'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
  

Example 4. Service discovery information response

<iq from='juliet@capulet.lit/balcony'
    id='uw72g176'
    to='romeo@montague.lit/orchard'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <feature var='urn:xmpp:jingle:1'/>
    <feature var='urn:xmpp:jingle:apps:encrypted:file-transfer:0'/>
    <feature var='urn:xmpp:jingle:apps:file-transfer:4'/>
    <feature var='urn:xmpp:jingle:transports:s5b:1'/>
    <feature var='urn:xmpp:jingle:transports:ibb:1'/>
  </query>
</iq>
  

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 Entity Capabilities (XEP-0115) [3]. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.

7. Implementation Notes

Since the OMEMO Encryption does not provide a direct relation between resources and Device ID’s the initiating entity might not the Device ID of the resource it is creating a session with. Thus it MAY include a key for every trusted device of the foreign entity. However it SHOULD omit the keys for its own devices.

8. Security Considerations

• Being built upon both Jingle File Transfer and OMEMO encryption, the same security considerations apply.
• Only the raw file is being encrypted. The encryption does not apply for the meta data sent with the session initialization including the content-type and the description

9. IANA Considerations

This document requires no interaction with the Internet Assigned Numbers Authority (IANA).

10. XMPP Registrar Considerations

11. XML Schema

tbd

Appendices

Appendix A: Document Information

Series: XEP
Number: xxxx
Publisher: XMPP Standards Foundation
Status: ProtoXEP
Type: Standards Track
Version: 0.0.1
Last Updated: 2015-09-02
Approving Body: XMPP Council
Dependencies: XMPP Core, XEP-0001, Etc.
Supersedes: None
Superseded By: None
Short Name: NOT_YET_ASSIGNED
This document in other formats: XML  PDF

Appendix B: Author Information

Appendix C: Legal Notices

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.

Errata can be sent to <editor@xmpp.org>.

Appendix F: Requirements Conformance

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

Appendix G: Notes

Appendix H: Revision History

Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/

END