moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-12-21 23:28:51 -05:00
Code Issues Releases Wiki Activity

Merge pull request #423 from ge0rg/xep0379

Browse Source 
XEP-0379: Added "Usability Considerations", removed actual XMPP client, some text editing.
This commit is contained in:
Florian Schmaus 2017-02-16 12:39:06 +01:00 committed by GitHub
commit 2a522c2148
1 changed files with 60 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
xep-0379.xml
View File

@ -28,6 +28,12 @@
<email>georg@op-co.de</email> <email>georg@op-co.de</email>
<jid>georg@yax.im</jid> <jid>georg@yax.im</jid>
</author> </author>
<revision>
<version>0.1.2</version>
<date>2017-02-16</date>
<initials>gl</initials>
<remark><p>Added "Usability Considerations", removed actual XMPP client, some text editing.</p></remark>
</revision>
<revision> <revision>
<version>0.1.1</version> <version>0.1.1</version>
<date>2017-01-01</date> <date>2017-01-01</date>
@ -118,7 +124,7 @@ Romeo mongatague.net capulet.net Juliet
optionally a "name" parameter with the suggested display name. optionally a "name" parameter with the suggested display name.
</p> </p>
<example caption='Invitation Link with Roster Action and Authentication Token'><![CDATA[ <example caption='Invitation Link with Roster Action and Authentication Token'><![CDATA[
xmpp:romeo@montague.net?roster;preauth=1tMFqYDdKhfe2pwp;name=Romeo%20Montague xmpp:romeo@montague.net?roster;preauth=1tMFqYDdKhfe2pwp;name=Romeo+Montague
]]></example> ]]></example>
<p> <p>
If the "preauth" parameter is present, the processing client is supposed If the "preauth" parameter is present, the processing client is supposed
@ -136,12 +142,12 @@ xmpp:romeo@montague.net?roster;preauth=1tMFqYDdKhfe2pwp;name=Romeo%20Montague
</section2> </section2>
<section2 topic='Out-of-band transmission and presentation of the link' anchor='link_transmission'> <section2 topic='Out-of-band Transmission and Presentation of the Link' anchor='link_transmission'>
<p>As Romeo doesn't know Juliet's JID in advance, he needs to use an out-of-band method (like e-mail, QR codes or NFC) to transmit the invitation link to Juliet. While these methods allow transmission of <strong>xmpp:</strong> URIs, there is no mechanism to ensure that Juliet actually has a client installed that can open the URI.</p> <p>As Romeo doesn't know Juliet's JID in advance, he needs to use an out-of-band method (like e-mail, QR codes or NFC) to transmit the invitation link to Juliet. While these methods allow transmission of <strong>xmpp:</strong> URIs, there is no mechanism to ensure that Juliet actually has a client installed that can open the URI.</p>
<p>One way to solve this problem is to present Juliet with a web-based landing page that contains the following elements:</p> <p>One way to solve this problem is to present Juliet with a web-based landing page that contains the following elements:</p>
<ul> <ul>
<li>A short text that this is an XMPP invitation from Romeo.</li> <li>A short text that this is an XMPP invitation from Romeo.</li>
<li>A client recommendation (based on the detected web browser) with download links.</li> <li>A client recommendation (based on the detected web browser/OS) with download links.</li>
<li>A prominent button that activates the actual <strong>xmpp:</strong> link.</li> <li>A prominent button that activates the actual <strong>xmpp:</strong> link.</li>
</ul> </ul>
<p>There are multiple options where such a landing page could be hosted:</p> <p>There are multiple options where such a landing page could be hosted:</p>
@ -164,8 +170,8 @@ xmpp:romeo@montague.net?roster;preauth=1tMFqYDdKhfe2pwp;name=Romeo%20Montague
Furthermore, the server operator needs to maintain the list of Furthermore, the server operator needs to maintain the list of
recommended clients.</li> recommended clients.</li>
</ol> </ol>
<example caption='Developer-Hosted Landing Page Generated with yaxim'><![CDATA[ <example caption='Developer-Hosted Landing Page Generated with Fictitious JuicyXMPP Client'><![CDATA[
https://yax.im/i/romeo/montague.net/1tMFqYDdKhfe2pwp/Romeo+Montague https://juicyxmpp.example/i/#romeo@montague.net?preauth=1tMFqYDdKhfe2pwp;name=Romeo+Montague
]]></example> ]]></example>
<p>A possible screen representation of the landing page would be:</p> <p>A possible screen representation of the landing page would be:</p>
<div class="example"> <div class="example">
@ -189,7 +195,7 @@ https://yax.im/i/romeo/montague.net/1tMFqYDdKhfe2pwp/Romeo+Montague
</section2> </section2>
<section2 topic='Subcription request to the user by the link receiver (new contact)' anchor='link_transmission'> <section2 topic='Subcription Request to the User by the Link Receiver (New Contact)' anchor='link_transmission'>
<p>When Juliet opens the <strong>xmpp:</strong> URI (or the according client-supported <p>When Juliet opens the <strong>xmpp:</strong> URI (or the according client-supported
landing page URI) in her client, the client should perform the usual landing page URI) in her client, the client should perform the usual
roster addition action, i.e. display a dialog allowing to edit the entry roster addition action, i.e. display a dialog allowing to edit the entry
@ -237,27 +243,28 @@ https://yax.im/i/romeo/montague.net/1tMFqYDdKhfe2pwp/Romeo+Montague
</section2> </section2>
<section2 topic='Approval by the New Contact' anchor='sub_mutual_approval'> <section2 topic='Approval by the New Contact' anchor='sub_mutual_approval'>
<p>If Juliet's server support pre-approval, it will automatically handle the <p>If Juliet's server supports pre-approval, it will automatically handle the
incoming subscription request and issue a roster push. Otherwise, Juliet's incoming subscription request and issue a roster push. Otherwise, Juliet's
client will receive the subscription request:</p> client will receive the subscription request:</p>
<example caption='Mutual Subscription Request'><![CDATA[ <example caption='Mutual Subscription Request'><![CDATA[
<presence from='romeo@montague.net' to='juliet@capulet.net' type='subscribe' /> <presence from='romeo@montague.net' to='juliet@capulet.net' type='subscribe' />
]]></example> ]]></example>
<p>Juliet's client SHOULD check the subscription request sender JID against <p>Juliet's client MUST ensure that the sender JID is contained in the
the whitelist, and either automatically approve the request or display an auto-approval whitelist before automatically approving the request.
according notification to Juliet.</p> Otherwise, it has to fallback to the normal subscription approval
process.</p>
</section2> </section2>
</section1> </section1>
<section1 topic='Business Rules' anchor='rules'> <section1 topic='Business Rules' anchor='rules'>
<section2 topic='Fallback to manual process' anchor='rules_fallback'> <section2 topic='Fallback to Manual Process' anchor='rules_fallback'>
<p>An implementation of this protocol MUST allow for a "graceful <p>An implementation of this protocol MUST allow for a "graceful
degradation" to the manual subscription approval process. If a client degradation" to the manual subscription approval process. If a client
receives a malformed or unknown 'preauth' token, it MUST ignore it and act receives a malformed or unknown 'preauth' token, it MUST ignore it and act
as if no preauth token was contained.</p> as if no preauth token was contained.</p>
</section2> </section2>
<section2 topic='No expectaion of immediate approval' anchor='rules_expectation'> <section2 topic='No Expectaion of Immediate Approval' anchor='rules_expectation'>
<p>When sending a pre-authenticated subscription request, the contact's <p>When sending a pre-authenticated subscription request, the contact's
client MUST NOT expect an immediate successful approval. If the user's client MUST NOT expect an immediate successful approval. If the user's
issuing client is currently offline, or if the token has expired, a manual issuing client is currently offline, or if the token has expired, a manual
@ -265,26 +272,6 @@ https://yax.im/i/romeo/montague.net/1tMFqYDdKhfe2pwp/Romeo+Montague
same mechanism as before to indicate an unidirectional subscription. same mechanism as before to indicate an unidirectional subscription.
</p> </p>
</section2> </section2>
<section2 topic='Use of multiple clients' anchor='rules_multiclient'>
<p>If a user is logged in with multiple clients, some of their clients will
receive a subscription request with an unknown token. In this case, a client
MAY delay the user notification for a short time, to allow another logged-in
client to automatically handle the subscription request.</p>
</section2>
<section2 topic='Opening the landing page in an app' anchor='rules_multiclient'>
<p>Some mobile device platforms allow an app to register itself as a
handler for cetain URIs. This allows an XMPP client to register for <strong>xmpp:</strong>
URIs, but also to redirect handling of cetain HTTP/HTTPS URIs. A mobile
client SHOULD register for the associated landing page URIs and properly
handle the contained invitations. For example, the yaxim client should
register a handler for <strong>https://yax.im/i/*</strong>, and present
the "Add to roster" dialog if such a link is opened. A client MAY register
for the landing page URIs of other providers after obtaining the
operators' approval.
</p>
</section2>
</section1> </section1>
<section1 topic='Security Considerations' anchor='security'> <section1 topic='Security Considerations' anchor='security'>
<section2 topic='Token Generation' anchor='security_token'> <section2 topic='Token Generation' anchor='security_token'>
@ -326,12 +313,6 @@ https://yax.im/i/romeo/montague.net/1tMFqYDdKhfe2pwp/Romeo+Montague
roster addition and manual subscription approval. roster addition and manual subscription approval.
</p> </p>
</section2> </section2>
<section2 topic='Invitation Link Validity' anchor='security_link'>
<p>The invitation link that is generated by Romeo's client is considered a
personal invitation link for a single person. This, and the fact that the
link can only be used once, should be indicated by the client to Romeo.
</p>
</section2>
<section2 topic='Interception of Links' anchor='security_intercept'> <section2 topic='Interception of Links' anchor='security_intercept'>
<p>A Monkey-in-the-Middle attacker who gains access to the invitation link <p>A Monkey-in-the-Middle attacker who gains access to the invitation link
can manipulate its fields or redeem the link themselves. However, this is can manipulate its fields or redeem the link themselves. However, this is
@ -351,6 +332,47 @@ https://yax.im/i/romeo/montague.net/1tMFqYDdKhfe2pwp/Romeo+Montague
equal to the JID, to prevent impersonation attacks.</p> equal to the JID, to prevent impersonation attacks.</p>
</section2> </section2>
</section1> </section1>
<section1 topic='Usability Considerations' anchor='usability'>
<section2 topic='Use of Multiple Clients' anchor='rules_multiclient'>
<p>If a user is logged in with multiple clients, some of their clients will
receive a subscription request with an unknown token. In this case, a client
MAY delay the user notification for a short time, to allow another logged-in
client to automatically handle the subscription request.</p>
</section2>
<section2 topic='Opening the Landing Page in an App' anchor='rules_multiclient'>
<p>Some mobile device platforms allow an app to register itself as a
handler for cetain URIs. This allows an XMPP client to register for <strong>xmpp:</strong>
URIs, but also to redirect handling of cetain HTTP/HTTPS URIs. A mobile
client SHOULD register for the associated landing page URIs and properly
handle the contained invitations. For example, the JuicyXMPP client should
register a handler for <strong>https://juicyxmpp.example/i/*</strong>, and present
the "Add to roster" dialog if such a link is opened. A client MAY register
for the landing page URIs of other providers after obtaining the
operators' approval.
</p>
</section2>
<section2 topic='Invitation Link Volatility' anchor='rules_volatile'>
<p>By default, Romeo's client should generate personal invitation links
that can only be redeemed once, and only for a limited time. This fact
SHOULD be indicated by the client UI to Romeo.</p>
<p>If a client allows customization of the validity time or the number of
uses for a given invitation token, it SHOULD provide clear language
to inidcate that.</p>
</section2>
<section2 topic='Tagging of Auto-Added Contacts' anchor='rules_group'>
<p>When a new contact is added automatically by the client, it SHOULD
indicate this fact to the user, and allow the user to rename / group
the contact appropriately. One possible way to achieve this is by
putting all auto-added contacts into a special roster group, and by
automatically removing this group on the first manual edit of the
contact.</p>
<p>In this case, the roster group should be named by the client according
to the user's locale settings. However, this approach might lead to
different clients using different group names, resulting in multiple
roster groups with the same goal.</p>
</section2>
</section1>
<section1 topic='IANA Considerations' anchor='iana'> <section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with &IANA;.</p> <p>This document requires no interaction with &IANA;.</p>
</section1> </section1>