53/WAKU2-X3DH specifies the Waku X3DH protocol for end-to-end encryption. Once two peers complete an X3DH handshake, they SHOULD establish an X3DH session.
Session Establishment # A node identifies a peer by their installation-id which MAY be interpreted as a device identifier.">
53/WAKU2-X3DH specifies the Waku X3DH protocol for end-to-end encryption. Once two peers complete an X3DH handshake, they SHOULD establish an X3DH session.
Session Establishment # A node identifies a peer by their installation-id which MAY be interpreted as a device identifier." />
<p>The node’s pre-key bundle SHOULD be broadcasted on a content topic derived from the node’s public key.</p>
<!-- raw HTML omitted -->
<p>The derivation is further described in <ahref="https://specs.status.im/spec/10#contact-code-topic">10/WAKU-USAGE</a></p>
<h2id="initialization">
Initialization
<aclass="anchor"href="#initialization">#</a>
</h2>
<p>A node initializes a new session once a successful X3DH exchange has taken place.
Subsequent messages will use the established session until re-keying is necessary.</p>
<h2id="concurrent-sessions">
Concurrent sessions
<aclass="anchor"href="#concurrent-sessions">#</a>
</h2>
<p>If a node creates two sessions concurrently between two peers, the one with the symmetric key first in byte order SHOULD be used, this marks that the other has expired.</p>
<h2id="re-keying">
Re-keying
<aclass="anchor"href="#re-keying">#</a>
</h2>
<p>On receiving a bundle from a given peer with a higher version, the old bundle SHOULD be marked as expired and a new session SHOULD be established on the next message sent.</p>
<p>Multi-device support is quite challenging as there is not a central place where information on which and how many devices (identified by their respective <code>installation-id</code>) a peer has, is stored.</p>
<p>Furthermore, account recovery always needs to be taken into consideration, where a user wipes clean the whole device and the node loses all the information about any previous sessions.
Taking these considerations into account, the way the network propagates multi-device information using X3DH bundles, which will contain information about paired devices as well as information about the sending device.
This means that every time a new device is paired, the bundle needs to be updated and propagated with the new information, the user has the responsibility to make sure the pairing is successful.</p>
<p>The method is loosely based on <ahref="https://signal.org/docs/specifications/sesame/">Signal’s Sesame Algorithm</a>.</p>
<h2id="pairing">
Pairing
<aclass="anchor"href="#pairing">#</a>
</h2>
<p>A new <code>installation-id</code> MUST be generated on a per-device basis.
The device should be paired as soon as possible if other devices are present.</p>
<p>If a bundle is received, which has the same <code>IK</code> as the keypair present on the device, the devices MAY be paired.
Once a user enables a new device, a new bundle MUST be generated which includes pairing information.</p>
<p>The bundle MUST be propagated to contacts through the usual channels.</p>
<p>Removal of paired devices is a manual step that needs to be applied on each device, and consist simply in disabling the device, at which point pairing information will not be propagated anymore.</p>
<p>When sending a message, the peer SHOULD send a message to other <code>installation-id</code> that they have seen.
The node caps the number of devices to <code>n</code>, ordered by last activity.
The node sends messages using pairwise encryption, including their own devices.</p>
<p>Where <code>n</code> is the maximum number of devices that can be paired.</p>
<h2id="account-recovery">
Account recovery
<aclass="anchor"href="#account-recovery">#</a>
</h2>
<p>Account recovery is the same as adding a new device, and it MUST be handled the same way.</p>
<h2id="partitioned-devices">
Partitioned devices
<aclass="anchor"href="#partitioned-devices">#</a>
</h2>
<p>In some cases (i.e. account recovery when no other pairing device is available, device not paired), it is possible that a device will receive a message that is not targeted to its own <code>installation-id</code>.
In this case an empty message containing bundle information MUST be sent back, which will notify the receiving end not to include the device in any further communication.</p>
<li>Inherits all security considerations from <ahref="/spec/53">53/WAKU2-X3DH</a>.</li>
</ol>
<h1id="recommendations">
Recommendations
<aclass="anchor"href="#recommendations">#</a>
</h1>
<ol>
<li>The value of <code>n</code> SHOULD be configured by the app-protocol.
<ul>
<li>The default value SHOULD be 3, since a larger number of devices will result in a larger bundle size, which may not be desirable in a peer-to-peer network.</li>
</ul>
</li>
</ol>
<h1id="copyright">
Copyright
<aclass="anchor"href="#copyright">#</a>
</h1>
<p>Copyright and related rights waived via <ahref="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p>
