Tech pages/OMEMO/Quickstart

PubSub—and by inheritence PEP—supports access models for a node. This document describes an algorithm for setting the access model of a PEP node savely and securely with minimal round trip times. Especially in a scenario where a node is supposed to be private, a publish first and configure access model later approach must be avoided as this could leak information in between those requests.

Publish with publish-options

Assuming we want to publish <content xmlns="com.example.dummy"/> to a node called `com.example.dummy` that should be available to everyone and not just our contacts.

Warning: We must ensure that the server annouces the namespace http://jabber.org/protocol/pubsub#publish-options on the account jid. Otherwise we risk the server just ignoring the publish-options in the following request which would be especially dangerous when trying to set a node to whitelist.

<iq to="account@server.tld" type="set" id="1">
  <pubsub xmlns="http://jabber.org/protocol/pubsub">
    <publish node="com.example.dummy">
      <item>
        <content xmlns="com.example.dummy"/>
      <item>
    </publish>
    <publish-options>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='FORM_TYPE' type='hidden'>
          <value>http://jabber.org/protocol/pubsub#publish-options</value>
        </field>
        <field var='pubsub#access_model'>
          <value>open</value>
        </field>
      </x>
    </publish-options>
  <pubsub>
</iq>

When parsing the response we have differentiate three cases: 1. The server responses with type="result". This happens either when the node was previously configured to be open or when the node did not exist, in which case the server must create that node automatically with the given access model. 2. The server responses with `type="error"` and a pubsub error of `precondition-not-met`. (The `error` element will have a child element called `precondition-not-met`. ([Example code in Conversations](https://github.com/siacs/Conversations/blob/9a57673130cab2794e4ea46b77826dbe962d7046/src/main/java/eu/siacs/conversations/crypto/axolotl/AxolotlService.java#L521-L522)) 3. The server responses with another, more generic error. The handling of that is out of scope of this document.

In case of (2) we will continue with the node-configuration

Node configuration

Node configuration is a two step process that involves downloading the current node configuration and setting a new one with a changed access model. The detailed process is described in [XEP-0060 section 8.2](https://xmpp.org/extensions/xep-0060.html#owner-configure). Essentially the following request will return a data form which can be resubmitted after changing the value of pubsub#access_model.

<iq type="get" to="account@server.tld" id="2">
  <pubsub xmlns="http://jabber.org/protocol/pubsub">
    <configure node="com.example.dummy"/>
  </pubsub>
</iq>

Retry step one

After a successful node configuration the client should retry to publish with publish-options. Appropriate steps should be taken to not end up in an infinte loop in case the server is misbehaving. This primarily means the publication should only be retried once.

OMEMO considerations

Since there is no security risk involved in *not* changing the access model to open OMEMO clients should work with servers that support publish-options and with servers that do not. Changing the access model should be considered optional but highly recommended. Support for publish-options is just starting to roll out to servers while support for node configuration has been around for quite some time in ejabberd. When setting the access model to *open* publish-options is merly a traffic optimization. One could therotically reconfigure the node after every publish. However that creates extra traffic and does not work when setting the access mode to whitelist due to the security risks outlined in the first paragraph. In an attempt to force server operators to offer publish-options ASAP (and thus opening the door for things like Bookmarks in private pep nodes) it is not advisable to go down that road.