-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathxep-0396.xml
140 lines (140 loc) · 7.21 KB
/
xep-0396.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY secret "<secret/>">
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Jingle Encrypted Transports - OMEMO</title>
<abstract>Extension for JET introducing OMEMO End-to-End Encrypted Jingle Transports.</abstract>
&LEGALNOTICE;
<number>0396</number>
<status>Deferred</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XEP-0391</spec>
<spec>XEP-0234</spec>
<spec>XEP-0384</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>jet-omemo</shortname>
<schemaloc>
<ns>jingle</ns>
<url>http://xmpp.org/schemas/jingle.xsd</url>
</schemaloc>
<schemaloc>
<ns>jingle:errors</ns>
<url>http://xmpp.org/schemas/jingle-errors.xsd</url>
</schemaloc>
<registry/>
<discuss>jingle</discuss>
&paulschaub;
<revision>
<version>0.2.0</version>
<date>2018-12-06</date>
<initials>XEP Editor (jsc)</initials>
<remark>Defer due to lack of activity.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2017-11-29</date>
<initials>XEP Editor (jwi)</initials>
<remark><p>Accepted by Council as Expremental XEP</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2017-10-06</date>
<initials>vv</initials>
<remark><p>First draft</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<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>
</section1>
<section1 topic='Mappings' anchor='mappings'>
<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 <key> attribute and initialization vector from the <iv> 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>
</section1>
<section1 topic='Limitations' anchor='limitations'>
<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>
<p>Since OMEMO deviceIds are not bound to XMPP resources, the initiator MUST encrypt the Transport Key for every device of the recipient.</p>
</section1>
<section1 topic='Key Transport' anchor='transport'>
<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 <security> 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>
<p></p>
<example caption="Romeo initiates an OMEMO encrypted file offer"><![CDATA[
<iq from='romeo@montague.example/dr4hcr0st3lup4c'
id='nzu25s8'
to='juliet@capulet.example/yn0cl4bnw0yr3vym'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-initiate'
initiator='romeo@montague.example/dr4hcr0st3lup4c'
sid='851ba2'>
<content creator='initiator' name='a-file-offer' senders='initiator'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:5'>
<file>
<date>1969-07-21T02:56:15Z</date>
<desc>This is a test. If this were a real file...</desc>
<media-type>text/plain</media-type>
<name>test.txt</name>
<range/>
<size>6144</size>
<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'/>
</transport>
<security xmlns='urn:xmpp:jingle:jet:0'
name='a-file-offer'
cipher='urn:xmpp:ciphers:aes-128-gcm-nopadding'
type='eu.siacs.conversations.axolotl'>
<encrypted xmlns='eu.siacs.conversations.axolotl'>
<header sid='27183'>
<key rid='31415'>BASE64ENCODED...</key>
<key prekey="true" rid='12321'>BASE64ENCODED...</key>
<!-- ... -->
<iv>BASE64ENCODED...</iv>
</header>
</encrypted>
</security>
</content>
</jingle>
</iq>]]></example>
<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>
</section1>
<section1 topic='Determining Support' anchor='support'>
<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>
<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-omemo: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>
</xep>