moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-21 08:45:04 -05:00
Code Issues Releases Wiki Activity

xep-0384: use entities for NSs

Browse Source 
Signed-off-by: Maxime “pep” Buquet <pep@bouah.net>
This commit is contained in:
Maxime “pep” Buquet 2020-03-09 00:18:10 +01:00 committed by Daniel Gultsch
parent c55d88b45e
commit 45b6821385
1 changed files with 30 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
xep-0384.xml
View File

@ -3,6 +3,9 @@
<!ENTITY content "&lt;content/&gt;">
<!ENTITY payload "&lt;payload/&gt;">
<!ENTITY % ents SYSTEM "xep.ent">
<!ENTITY ns "urn:xmpp:omemo:1">
<!ENTITY nsdevices "urn:xmpp:omemo:1:devices">
<!ENTITY nsbundles "urn:xmpp:omemo:1:bundles">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
@ -69,7 +72,7 @@
<li>Specify OMEMO encryption for XEP-0045 Multi-User Chats.</li>
<li>Use XEP-0420: Stanza Content Encryption.</li>
<li>Use AES256/CBC to encrypt SCE payload.</li>
<li>Change namespace to 'urn:xmpp:omemo:1'</li>
<li>Change namespace to <tt>&ns;</tt></li>
<li>Use wrapping 'keys' element for key elements in 'header'.</li>
<li>Define threat model</li>
</ul>
@ -206,7 +209,7 @@
<section1 topic='Glossary' anchor='glossary'>
<dl>
<di><dt>Device</dt><dd>A communication end point, i.e. a specific client instance</dd></di>
<di><dt>OMEMO element</dt><dd>An &lt;encrypted&gt; element in the urn:xmpp:omemo:1 namespace</dd></di>
<di><dt>OMEMO element</dt><dd>An &lt;encrypted&gt; element in the <tt>&ns;</tt> namespace</dd></di>
<di><dt>Bundle</dt><dd>A collection of publicly accessible data used by the X3DH key exchange that can be used to build a session with a device, namely its public IdentityKey, a signed PreKey with corresponding signature, and a list of (single use) PreKeys.</dd></di>
<di><dt>rid</dt><dd>The device id of the intended recipient of the containing &lt;key&gt;</dd></di>
<di><dt>sid</dt><dd>The device id of the sender of the containing OMEMO element</dd></di>
@ -309,16 +312,16 @@
</p>
</section2>
<section2 topic='Discovering peer support' anchor='usecases-discovering'>
<p>In order to determine whether a given contact has devices that support OMEMO, the devices node in PEP is consulted. Devices MUST subscribe to 'urn:xmpp:omemo:1:devices' via PEP, so that they are informed whenever their contacts add a new device. They MUST cache the most up-to-date version of the device list.</p>
<p>In order to determine whether a given contact has devices that support OMEMO, the devices node in PEP is consulted. Devices MUST subscribe to <tt>&nsdevices;</tt> via PEP, so that they are informed whenever their contacts add a new device. They MUST cache the most up-to-date version of the device list.</p>
<example caption='Devicelist update received by subscribed clients'><![CDATA[
<message from='juliet@capulet.lit'
to='romeo@montague.lit'
type='headline'
id='update_01'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='urn:xmpp:omemo:1:devices'>
<items node=']]>&nsdevices;<![CDATA['>
<item id='current'>
<devices xmlns='urn:xmpp:omemo:1'>
<devices xmlns=']]>&ns;<![CDATA['>
<device id='12345' />
<device id='4223' label='Gajim on Ubuntu Linux' />
</devices>
@ -330,15 +333,15 @@
<section2 topic='Announcing support' anchor='usecases-announcing'>
<section3 topic='Device list' anchor='devices'>
<p>In order for other devices to be able to initiate a session with a given device, it first has to announce itself by adding its device id to the devices PEP node. </p>
<p>It is RECOMMENDED to set the access model of the ‘urn:xmpp:omemo:1:devices’ node to ‘open’ to give entities without presence subscription read access to the devices and allow them to establish an OMEMO session. Not having presence subscription is a common occurrence on the first few messages between two contacts and can also happen fairly frequently in group chats as not every participant had prior communication with every other participant.</p>
<p>It is RECOMMENDED to set the access model of the <tt>&nsdevices;</tt> node to ‘open’ to give entities without presence subscription read access to the devices and allow them to establish an OMEMO session. Not having presence subscription is a common occurrence on the first few messages between two contacts and can also happen fairly frequently in group chats as not every participant had prior communication with every other participant.</p>
<p>The access model can be changed efficiently by using publish-options.</p>
<p>The device element MAY contain an attribute called label, which is a user defined string describing the device that published that bundle. It is RECOMMENDED to keep the length of the label under 53 Unicode code points.</p>
<example caption='Adding the own device id to the list'><![CDATA[
<iq from='juliet@capulet.lit' type='set' id='announce1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='urn:xmpp:omemo:1:devices'>
<publish node=']]>&nsdevices;<![CDATA['>
<item id='current'>
<devices xmlns='urn:xmpp:omemo:1'>
<devices xmlns=']]>&ns;<![CDATA['>
<device id='12345' label='Dino on Lenovo Thinkpad T495'/>
<device id='4223' />
<device id='31415' label='Conversations on Pixel 3' />
@ -361,15 +364,15 @@
<p>This step presents the risk of introducing a race condition: Two devices might simultaneously try to announce themselves, unaware of the other's existence. The second device would overwrite the first one. To mitigate this, devices MUST check that their own device id is contained in the list whenever they receive a PEP update from their own account. If they have been removed, they MUST reannounce themselves.</p>
</section3>
<section3 topic='Bundles' anchor='bundles'>
<p>Furthermore, a device MUST publish its IdentityKey, a signed PreKey, and a list of PreKeys. This tuple is called a bundle and is provided by OMEMO libraries. Bundles are maintained as multiple items in a PEP node called ‘urn:xmpp:omemo:1:bundles’. Each bundle MUST be stored in a seperate item. The item id MUST be set to the device id.</p>
<p>A bundle is an element called 'bundle' in the 'urn:xmpp:omemo:1' namespace. It has a child element called ‘spk’ that contains the public part of the signed PreKey as base64 encoded data, a child element called ‘spks’ that contains the signed PreKey signature as base64 encoded data and a child element called ‘ik’ that contains the public part of the identity key as base64 encoded data. PreKeys are multiple elements called ‘pk’ that each contain the public part of one PreKey as base64 encoded data. PreKeys are wrapped in an element called ‘prekeys’ which is a child of the bundle element.</p>
<p>When publishing bundles a client MUST make sure that the 'urn:xmpp:omemo:1:bundles' node is configured to store multiple items. This is not the default with &xep0163;. If the node doesn’t exist yet it can be configured on the fly by using publish-options as described in <link url="https://xmpp.org/extensions/xep-0060.html#publisher-publish-options"><cite>XEP-0060</cite> §7.1.5</link>. The value for 'pubsub#max_items' in publish_options MUST be set to 'max'. If the node did exist and was configured differently the bundle publication will fail. Clients MUST then reconfigure the node as described in <link url="https://xmpp.org/extensions/xep-0060.html#owner-configure"><cite>XEP-0060</cite> §8.2</link>.</p>
<p>Furthermore, a device MUST publish its IdentityKey, a signed PreKey, and a list of PreKeys. This tuple is called a bundle and is provided by OMEMO libraries. Bundles are maintained as multiple items in a PEP node called <tt>&nsbundles;</tt>. Each bundle MUST be stored in a seperate item. The item id MUST be set to the device id.</p>
<p>A bundle is an element called 'bundle' in the <tt>&ns;</tt> namespace. It has a child element called ‘spk’ that contains the public part of the signed PreKey as base64 encoded data, a child element called ‘spks’ that contains the signed PreKey signature as base64 encoded data and a child element called ‘ik’ that contains the public part of the identity key as base64 encoded data. PreKeys are multiple elements called ‘pk’ that each contain the public part of one PreKey as base64 encoded data. PreKeys are wrapped in an element called ‘prekeys’ which is a child of the bundle element.</p>
<p>When publishing bundles a client MUST make sure that the <tt>&nsbundles;</tt> node is configured to store multiple items. This is not the default with &xep0163;. If the node doesn’t exist yet it can be configured on the fly by using publish-options as described in <link url="https://xmpp.org/extensions/xep-0060.html#publisher-publish-options"><cite>XEP-0060</cite> §7.1.5</link>. The value for 'pubsub#max_items' in publish_options MUST be set to 'max'. If the node did exist and was configured differently the bundle publication will fail. Clients MUST then reconfigure the node as described in <link url="https://xmpp.org/extensions/xep-0060.html#owner-configure"><cite>XEP-0060</cite> §8.2</link>.</p>
<example caption='Publishing bundle information'><![CDATA[
<iq from='juliet@capulet.lit' type='set' id='annouce2'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='urn:xmpp:omemo:1:bundles'>
<publish node=']]>&nsbundles;<![CDATA['>
<item id='31415'>
<bundle xmlns='urn:xmpp:omemo:1'>
<bundle xmlns=']]>&ns;<![CDATA['>
<spk id='0'>b64/encoded/data</spk>
<spks>b64/encoded/data</spks>
<ik>b64/encoded/data</ik>
@ -394,14 +397,14 @@
</publish-options>
</pubsub>
</iq>]]></example>
<p>As with the 'urn:xmpp:omemo:1:devices' node it is RECOMMENDED to set the access model of the 'urn:xmpp:omemo:1:bundles' to open. Clients that do not adhere to the recommended access model (and for example want to stick to the default 'presence') are highly encouraged to configure the same access model for 'urn:xmpp:omemo:1:devices' and 'urn:xmpp:omemo:1:bundles', otherwise remote entities might end up in a situation where they are able to retrieve the device list but not the bundle or vice versa.</p>
<p>As with the <tt>&nsdevices;</tt> node it is RECOMMENDED to set the access model of the <tt>&nsbundles;</tt> to open. Clients that do not adhere to the recommended access model (and for example want to stick to the default 'presence') are highly encouraged to configure the same access model for <tt>&nsdevices;</tt> and <tt>&nsbundles;</tt> otherwise remote entities might end up in a situation where they are able to retrieve the device list but not the bundle or vice versa.</p>
<p>The access model can be changed efficiently by using publish-options.</p>
<example caption='Publishing bundle information with an open access model'><![CDATA[
<iq from='juliet@capulet.lit' type='set' id='annouce2'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='urn:xmpp:omemo:1:bundles'>
<publish node=']]>&nsbundles;<![CDATA['>
<item id='31415'>
<bundle xmlns='urn:xmpp:omemo:1'>
<bundle xmlns=']]>&ns;<![CDATA['>
<!-- … -->
</bundle>
</item>
@ -431,7 +434,7 @@
to='juliet@capulet.lit'
id='fetch1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='urn:xmpp:omemo:1:bundles'>
<items node=']]>&nsbundles;<![CDATA['>
<item id='31415'/>
<items>
</pubsub>
@ -482,7 +485,7 @@
The &content; element is encrypted as described in the section about <link url="#protocol-message_encryption">Message Encryption</link>.
</p>
<p>
Clients SHOULD only consider the devices on the 'urn:xmpp:omemo:1:devices' node of each recipient (i.e. including his own devices node, but excluding itself).
Clients SHOULD only consider the devices on the <tt>&nsdevices;</tt> node of each recipient (i.e. including his own devices node, but excluding itself).
</p>
</section3>
<section3 topic='Message structure description' anchor='message-structure-description'>
@ -494,7 +497,7 @@
</p>
<example caption="Sending a message"><![CDATA[
<message to='juliet@capulet.lit' from='romeo@montague.lit' id='send1'>
<encrypted xmlns='urn:xmpp:omemo:1'>
<encrypted xmlns=']]>&ns;<![CDATA['>
<header sid='27183'>
<keys jid='juliet@capulet.lit'>
<key rid='31415'>b64/encoded/data</key>
@ -533,25 +536,25 @@
<example caption='Juliet fetching devices for Remeo and Mercutio'><![CDATA[
<iq type='get' from='juliet@capulet.lit' to='romeo@montague.lit' id='gfetch0'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='urn:xmpp:omemo:1:devices'/>
<items node=']]>&nsdevices;<![CDATA['/>
</pubsub>
</iq>
<iq type='get' from='juliet@capulet.lit' to='mercutio@verona.lit' id='gfetch1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='urn:xmpp:omemo:1:devices'/>
<items node=']]>&nsdevices;<![CDATA['/>
</pubsub>
</iq>]]></example>
<example caption='Juliet fetches bundles for Romeo and Mercutio'><![CDATA[
<iq type='get' from='juliet@capulet.lit' to='romeo@montague.lit' id='gfetch2'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='urn:xmpp:omemo:1:bundles'>
<items node=']]>&nsbundles;<![CDATA['>
<item id='123'/>
<items>
</pubsub>
</iq>
<iq type='get' from='juliet@capulet.lit' to='mercutio@verona.lit' id='gfetch3'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='urn:xmpp:omemo:1:bundles'>
<items node=']]>&nsbundles;<![CDATA['>
<item id='456'/>
<items>
</pubsub>
@ -564,7 +567,7 @@
from='juliet@capulet.lit/balcony'
to='secret-room@conference.capulet.lit'
type='groupchat'>
<encrypted xmlns='urn:xmpp:omemo:1'>
<encrypted xmlns=']]>&ns;<![CDATA['>
<header sid='27183'>
<keys jid='juliet@capulet.lit'>
<key rid='31415'>b64/encoded/data</key>
@ -619,7 +622,7 @@
<section2 topic='Protocol Namespaces' anchor='namespaces'>
<p>This specification defines the following XMPP namespaces:</p>
<ul>
<li>urn:xmpp:omemo:1</li>
<li>&ns;</li>
</ul>
</section2>
<section2 topic='Protocol Versioning' anchor='versioning'>
@ -630,8 +633,8 @@
<code><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="urn:xmpp:omemo:1"
xmlns="urn:xmpp:omemo:1">
targetNamespace="]]>&ns;<![CDATA["
xmlns="]]>&ns;<![CDATA[">
<xs:element name="encrypted">
<xs:complexType>