Browse Source

XEP-0227: New revision 1.1

- Discourage inclusion of plaintext passwords
- Document a format for including SCRAM data
- Define data formats for PEP and MAM data
master
Matthew Wild 1 year ago committed by Jonas Schäfer
parent
commit
357529d470
  1. 191
      xep-0227.xml

191
xep-0227.xml

@ -37,6 +37,13 @@ @@ -37,6 +37,13 @@
<email>waqas20@gmail.com</email>
<jid>waqas@jaim.at</jid>
</author>
&mwild;
<revision>
<version>1.1</version>
<date>2021-06-02</date>
<initials>mw</initials>
<remark><p>Discourage use of 'password', provide a way to include SCRAM credentials, PEP nodes and message archives.</p></remark>
</revision>
<revision>
<version>1.0</version>
<date>2010-03-12</date>
@ -141,18 +148,20 @@ @@ -141,18 +148,20 @@
</section2>
<section2 topic='Users' anchor='users'>
<p>Each user is represented by a &lt;user/&gt; element under the &lt;host/&gt; element. The &lt;user/&gt; element MUST have a 'name' attribute, which contains the node part of the user's JID, and SHOULD have a 'password' attribute, which contains the user's password.</p>
<p>Each user is represented by a &lt;user/&gt; element under the &lt;host/&gt; element. The &lt;user/&gt; element MUST have a 'name' attribute, which contains the node part of the user's JID.</p>
<p>If the plaintext password of the user is known, it MAY be included in the 'password' attribute, although this is not recommended from a security perspective. For more information see <link url='#security'>Security Considerations</link>. See also the SCRAM credentials section for an alternative.</p>
<example caption='The user element'><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='urn:xmpp:pie:0'>
<host jid='capulet.com'>
<user name='juliet' password='s3crEt'>
<user name='juliet'>
[ ... ]
</user>
</host>
<host jid='montague.net'>
<user name='romeo' password='iLuvJuLi3T'>
<user name='romeo'>
[ ... ]
</user>
</host>
@ -160,6 +169,40 @@ @@ -160,6 +169,40 @@
]]></example>
</section2>
<section2 topic='SCRAM credentials' anchor='scram-credentials'>
<p>Authentication secrets may be included that allow for authentication using the SCRAM family of mechanisms, as defined in &rfc5802;.</p>
<p>Each set of credentials should be encapsulated within a &lt;scram-credentials/&gt; element in the 'urn:xmpp:pie:0#scram' namespace, and contained within the relevant &lt;user/&gt; element. The element should have a 'mechanism' attribute specifying the registered name of the mechanism that the credentials are used for (always without the "-PLUS" suffix), e.g. 'SCRAM-SHA-1'. The element MUST contain a single occurrence of each of the following child elements:</p>
<ul>
<li>&lt;iter-count/&gt;: containing the SCRAM iteration count, e.g. '10000'. This must be a positive integer without leading zeros.</li>
<li>&lt;salt/&gt;: containing the base64-encoded salt.</li>
<li>&lt;server-key/&gt;: containing the base64-encoded ServerKey defined by SCRAM.</li>
<li>&lt;stored-key/&gt;: containing the base64-encoded StoredKey defined by SCRAM.</li>
</ul>
<p>There may be multiple occurrences of &lt;scram-credentials/&gt; for a single user, however they MUST all have a unique 'mechanism' attribute.</p>
<example caption='Including a user&apos;s SCRAM credentials'><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='urn:xmpp:pie:0'>
<host jid='capulet.com'>
<user name='juliet'>
<scram-credentials xmlns='urn:xmpp:pie:0#scram' mechanism='SCRAM-SHA-1'>
<iter-count>100000</iter-count>
<salt>TmFDbE5hQ2xOYUNsTmFDbE5hQ2xOYUNsTmFDbE5hQ2xOYUNsTmFDbE5hQ2wK</salt>
<server-key>0pXWGK0GZJ6TR73AIUN3ITYtA1g=</server-key>
<stored-key>Q6qT/SbybblGCZz8e8eSfCJOQic=</stored-key>
</scram-credentials>
</user>
</host>
</server-data>
]]></example>
<p>Be aware of the <link url='#security'>Security Considerations</link> when including credentials in a data export. Even though SCRAM credentials are stored in a hashed form, leaking them still allows an attacker to impersonate the user to other servers employing the same SCRAM parameters, and it also allows for offline dictionary or brute-force attacks.</p>
</section2>
<section2 topic='Rosters' anchor='rosters'>
<p>Each &lt;user/&gt; element SHOULD contain the user's roster in the form of a &lt;query/&gt; element qualified by the 'jabber:iq:roster' namespace. This element contains the user's roster in the same format as when retrieving the roster from the server, as described in section 7.3 of &xmppim;.</p>
@ -167,7 +210,7 @@ @@ -167,7 +210,7 @@
<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='urn:xmpp:pie:0'>
<host jid='capulet.com'>
<user name='juliet' password='s3crEt'>
<user name='juliet'>
<query xmlns='jabber:iq:roster'>
<item jid='romeo@montague.net'
name='Romeo'
@ -188,7 +231,7 @@ @@ -188,7 +231,7 @@
<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='urn:xmpp:pie:0'>
<host jid='capulet.com'>
<user name='juliet' password='s3crEt'>
<user name='juliet'>
<offline-messages>
<message xmlns='jabber:client'
from='romeo@montague.net/orchard'
@ -215,7 +258,7 @@ @@ -215,7 +258,7 @@
<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='urn:xmpp:pie:0'>
<host jid='shakespeare.lit'>
<user name='hamlet' password='2b0Rnot2B'>
<user name='hamlet'>
<query xmlns="jabber:iq:private">
<exodus xmlns="exodus:prefs">
<defaultnick>Hamlet</defaultnick>
@ -234,7 +277,7 @@ @@ -234,7 +277,7 @@
<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='urn:xmpp:pie:0'>
<host jid='capulet.com'>
<user name='juliet' password='s3crEt'>
<user name='juliet'>
<vCard xmlns='vcard-temp'>
<FN>Juliet Capulet</FN>
</vCard>
@ -251,7 +294,7 @@ @@ -251,7 +294,7 @@
<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='urn:xmpp:pie:0'>
<host jid='capulet.com'>
<user name='juliet' password='s3crEt'>
<user name='juliet'>
<query xmlns='jabber:iq:privacy'>
<default name='public'/>
<list name='public'>
@ -282,7 +325,7 @@ @@ -282,7 +325,7 @@
<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='urn:xmpp:pie:0'>
<host jid='capulet.com'>
<user name='juliet' password='s3crEt'>
<user name='juliet'>
<presence xmlns='jabber:client'
type='subscribe'
id='xk3h1v69'
@ -297,6 +340,132 @@ @@ -297,6 +340,132 @@
</server-data>
]]></example>
</section2>
<section2 topic='Personal Eventing Protocol' anchor='pep'>
<p>A user's PEP data (as defined in &xep0163;) SHOULD be included if known.</p>
<p>Node configuration and the actual node data are encapsulated separately, as described below. A typical export that contains both node configuration and the actual data contained within the node, will include two &lt;pubsub/&gt; elements (qualified by different namespaces).</p>
<p>Many server implementations include support for additional pubsub features from &xep0060; beyond those required by XEP-0163. This specification aims to preserve this additional data also, when it is present and supported by both servers.</p>
<section3 topic='PEP node configuration' anchor='pep-config'>
<p>Within the &lt;user/&gt; element there should be a single &lt;pubsub/&gt; element qualified by the 'http://jabber.org/protocol/pubsub#owner' namespace (note the '#owner' suffix). Within this element, there MUST be one &lt;configure/&gt; element for each exported node, with the node's name in the 'node' attribute. There MAY be additional elements included, at most one per node of each kind: &lt;subscriptions/&gt; and &lt;affiliations&gt;, following the syntax defined in XEP-0060.</p>
<p>The format of the &lt;configure/&gt; is a &xep0004; data form, typically containing the fields documented in XEP-0060, encoding the configuration of the named node.</p>
<p>As a general rule, importers SHOULD ignore node configuration options that the target server implementation doesn't recognise, to allow porting data between different implementations even in the presence of custom extensions. Exceptions to this requirement may be made for imports that are expected to be lossless, for example if the user has specifically requested a lossless import, or if the importer recognises certain configuration fields as critical to protect the node's security or integrity.</p>
</section3>
<section3 topic='PEP node items' anchor='pep-items'>
<p>Within the &lt;user/&gt; element there should be a single &lt;pubsub/&gt; element qualified by the 'http://jabber.org/protocol/pubsub' namespace (note the lack of any suffix). Within this element, there MUST be one &lt;items/&gt; element for each exported node, with the node's name in the 'node' attribute.</p>
<p>Any node listed in this element MUST have a corresponding configuration included as described in the previous section.</p>
<p>Each &lt;items&gt; element MUST contain zero or more &lt;item/&gt; elements as defined by XEP-0060.</p>
</section3>
<p>This example demonstrates an export for a user who has two nodes: a private bookmarks node with two bookmarks, and a public nickname node containing a single item.</p>
<example caption='Romeo&apos;s exported PEP data'><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='urn:xmpp:pie:0'>
<host jid='capulet.com'>
<user name='romeo'>
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
<configure node='urn:xmpp:bookmarks:1'>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/pubsub#node_config</value>
</field>
<field var='pubsub#access_model'>
<value>whitelist</value>
</field>
</x>
</configure>
<affiliations node='urn:xmpp:bookmarks:1'>
<affiliation jid='mercutio@example.net' affiliation='member'/>
</affiliations>
<subscriptions node='urn:xmpp:bookmarks:1'>
<subscription jid='mercutio@example.net' subscription='subscribed' subid='123-abc'/>
</subscriptions>
<configure node='http://jabber.org/protocol/nick'>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/pubsub#node_config</value>
</field>
<field var='pubsub#access_model'>
<value>open</value>
</field>
</x>
</configure>
</pubsub>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='urn:xmpp:bookmarks:1'>
<item id='theplay@conference.shakespeare.lit'>
<conference xmlns='urn:xmpp:bookmarks:1'
name='The Play&apos;s the Thing'
autojoin='true'>
<nick>Romeo</nick>
</conference>
</item>
<item id='orchard@conference.shakespeare.lit'>
<conference xmlns='urn:xmpp:bookmarks:1'
name='The Orchard'
autojoin='1'>
<nick>Romeo</nick>
</conference>
</item>
</items>
<items node='http://jabber.org/protocol/nick'>
<item id='current'>
<nick xmlns='http://jabber.org/protocol/nick'>Romy</nick>
</item>
</items>
</pubsub>
</user>
</host>
</server-data>
]]></example>
</section2>
<section2 topic='Message Archive' anchor='archive'>
<p>A user's &xep0313; message archive MAY be included in an export. If included, they MUST be formatted as a series of XEP-0313 &lt;result/&gt; elements within an &lt;archive/&gt; element qualified by the 'urn:xmpp:pie:0#mam' namespace. The result elements MUST be in chronological order (from oldest to newest).</p>
<example caption='Juliet&apos;s exported message archive'><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='urn:xmpp:pie:0'>
<host jid='capulet.com'>
<user name='juliet'>
<archive xmlns='urn:xmpp:pie:0#mam'>
<result xmlns='urn:xmpp:mam:2' id='28482-98726-73623'>
<forwarded xmlns='urn:xmpp:forward:0'>
<delay xmlns='urn:xmpp:delay' stamp='2010-07-10T23:08:25Z'/>
<message xmlns='jabber:client'
to='juliet@capulet.lit/balcony'
from='romeo@montague.lit/orchard'
type='chat'>
<body>Call me but love, and I'll be new baptized; Henceforth I never will be Romeo.</body>
</message>
</forwarded>
</result>
<result xmlns='urn:xmpp:mam:2' id='5d398-28273-f7382'>
<forwarded xmlns='urn:xmpp:forward:0'>
<delay xmlns='urn:xmpp:delay' stamp='2010-07-10T23:09:32Z'/>
<message xmlns='jabber:client'
to='romeo@montague.lit/orchard'
from='juliet@capulet.lit/balcony'
type='chat' id='8a54s'>
<body>What man art thou that thus bescreen'd in night so stumblest on my counsel?</body>
</message>
</forwarded>
</result>
</archive>
</user>
</host>
</server-data>
]]></example>
</section2>
</section1>
<section1 topic='Use of XInclude' anchor='xinclude'>
@ -334,7 +503,7 @@ @@ -334,7 +503,7 @@
<example caption='The user file'><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<user xmlns='urn:xmpp:pie:0'
name='juliet' password='s3crEt'>
name='juliet'>
<query xmlns='jabber:iq:roster'>
<item jid='romeo@montague.net'
name='Romeo'
@ -369,7 +538,7 @@ @@ -369,7 +538,7 @@
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>Exported data files are to be handled with care, since they contain data that users expect to be protected, in particular passwords. An exporting server SHOULD make sure that the generated file is not accessible to unauthorized persons, e.g. by enforcing strict file permissions.</p>
<p>Exported data files are to be handled with care, since they contain data that users expect to be protected, in particular passwords. An exporting server SHOULD make sure that the generated file is not accessible to unauthorized persons, e.g. by enforcing strict file permissions. It may also apply suitable encryption before storing or transmitting the data.</p>
<p>XInclude &lt;include/&gt; elements which are indirect descendants of the &lt;user/&gt; element SHOULD be treated as opaque user data, and SHOULD NOT be processed.</p>
</section1>

Loading…
Cancel
Save