mirror of
https://github.com/moparisthebest/xeps
synced 2024-12-21 23:28:51 -05:00
Merge pull request #423 from ge0rg/xep0379
XEP-0379: Added "Usability Considerations", removed actual XMPP client, some text editing.
This commit is contained in:
Florian Schmaus
GitHub
commit
2a522c2148
98
xep-0379.xml
98
xep-0379.xml
@ -28,6 +28,12 @@
|
||||
<email>georg@op-co.de</email>
|
||||
<jid>georg@yax.im</jid>
|
||||
</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>
|
||||
<version>0.1.1</version>
|
||||
<date>2017-01-01</date>
|
||||
@ -118,7 +124,7 @@ Romeo mongatague.net capulet.net Juliet
|
||||
optionally a "name" parameter with the suggested display name.
|
||||
</p>
|
||||
<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>
|
||||
<p>
|
||||
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 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>One way to solve this problem is to present Juliet with a web-based landing page that contains the following elements:</p>
|
||||
<ul>
|
||||
<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>
|
||||
</ul>
|
||||
<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
|
||||
recommended clients.</li>
|
||||
</ol>
|
||||
<example caption='Developer-Hosted Landing Page Generated with yaxim'><![CDATA[
|
||||
https://yax.im/i/romeo/montague.net/1tMFqYDdKhfe2pwp/Romeo+Montague
|
||||
<example caption='Developer-Hosted Landing Page Generated with Fictitious JuicyXMPP Client'><![CDATA[
|
||||
https://juicyxmpp.example/i/#romeo@montague.net?preauth=1tMFqYDdKhfe2pwp;name=Romeo+Montague
|
||||
]]></example>
|
||||
<p>A possible screen representation of the landing page would be:</p>
|
||||
<div class="example">
|
||||
@ -189,7 +195,7 @@ https://yax.im/i/romeo/montague.net/1tMFqYDdKhfe2pwp/Romeo+Montague
|
||||
|
||||
</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
|
||||
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
|
||||
@ -237,27 +243,28 @@ https://yax.im/i/romeo/montague.net/1tMFqYDdKhfe2pwp/Romeo+Montague
|
||||
</section2>
|
||||
|
||||
<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
|
||||
client will receive the subscription request:</p>
|
||||
<example caption='Mutual Subscription Request'><![CDATA[
|
||||
<presence from='romeo@montague.net' to='juliet@capulet.net' type='subscribe' />
|
||||
]]></example>
|
||||
<p>Juliet's client SHOULD check the subscription request sender JID against
|
||||
the whitelist, and either automatically approve the request or display an
|
||||
according notification to Juliet.</p>
|
||||
<p>Juliet's client MUST ensure that the sender JID is contained in the
|
||||
auto-approval whitelist before automatically approving the request.
|
||||
Otherwise, it has to fallback to the normal subscription approval
|
||||
process.</p>
|
||||
|
||||
</section2>
|
||||
</section1>
|
||||
<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
|
||||
degradation" to the manual subscription approval process. If a client
|
||||
receives a malformed or unknown 'preauth' token, it MUST ignore it and act
|
||||
as if no preauth token was contained.</p>
|
||||
</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
|
||||
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
|
||||
@ -265,26 +272,6 @@ https://yax.im/i/romeo/montague.net/1tMFqYDdKhfe2pwp/Romeo+Montague
|
||||
same mechanism as before to indicate an unidirectional subscription.
|
||||
</p>
|
||||
</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 topic='Security Considerations' anchor='security'>
|
||||
<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.
|
||||
</p>
|
||||
</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'>
|
||||
<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
|
||||
@ -351,6 +332,47 @@ https://yax.im/i/romeo/montague.net/1tMFqYDdKhfe2pwp/Romeo+Montague
|
||||
equal to the JID, to prevent impersonation attacks.</p>
|
||||
</section2>
|
||||
</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'>
|
||||
<p>This document requires no interaction with &IANA;.</p>
|
||||
</section1>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user