First draft.
Romeo is an active XMPP IM (Instant Messaging) user. He convinces Juliet - (who doesn't have an XMPP account yet) to install a client and - register with some server. Now, Romeo only needs to create a mutual - presence subscription with her, without yet knowing her JID.
-This specification allows Romeo to create an out-of-band link (URI) which, - when opened in Juilet's (or another user's) client, will:
-The perceivable effect is that with a single click, Romeo and Juliet - become "friends" in terms of XMPP presence subscription.
- -This specification makes use of XMPP URIs. The basic URI scheme for XMPP - is defined in &rfc5122; and extended in &xep0147; to support different - actions like "roster" for roster addition and "subscribe" for presence - subscription. -
-The process of mutual roster addition and subscription involves multiple - steps:
-The general idea of the protocol and the details of the individual steps - are outlined in the following.
-As Romeo doesn't know Juliet's JID, he needs to send an out-of-band - invitation. Later, his client needs to match an incoming subscription - request to this invitation, so it can perform a secure automatic roster - addition and subscription approval. This matching is accomplished by - means of an authentication token, which is generated by Romeo's client, - added to the invitation link and then carried over into the subscription - request eventually made by Juliet's client. Romeo's client can then - compare the token received in a subscription request to the list of - issued tokens, and automatically approve the subscription.
-|
- | | | roster add |
- | | |<--------------|
- | presence subscription request w/ token |
- |
- Whenever Romeo wishes to invite somebody to his roster, his client will - generate an invitation link that contains a new authentication token. - This document extends the "roster" URI action defined in XEP-0147 with - a new key-value parameter named "preauth" to store the generated token. - Romeo's client will create an xmpp: link containing Romeo's JID, the - "roster" action, the "preauth" parameter with the token value, and - optionally a "name" parameter with the suggested display name. -
-- If the "preauth" parameter is present, the processing client is supposed - not only to add the user to the roster, but also to automatically send a - subscription request containing the authentication token. -
- - - -Server-side implementation: it is - possible (but out-of-scope for this document), to let the user's server - handle generation of links as well as automatic approval of qualified - subscription requests. This requires an additional mechanism to query the - server for new (and possibly also for pending) invitation links.
- -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 xmpp: URIs, there is no mechanism to ensure that Juliet actually has a client installed that can open the URI.
-One way to solve this problem is to present Juliet with a web-based landing page that contains the following elements:
-There are multiple options where such a landing page could be hosted:
-A possible screen representation of the landing page would be:
-Romeo Montague has invited you to chat
- -Add Romeo Montague
-If this link does not work, you need to install and configure - an XMPP client. Please visit this page again afterwards. Choose one of - these for your Tomato OS:
-Check the full list of XMPP clients.
-No further action is required if you do not know Romeo Montague or do not want to chat with them.
-XMPP is a provider-independent form of instant messaging. That means - you can pick from many different clients and have a free choice of - server operators to communicate with Romeo Montague.
- -When Juliet opens the xmpp: 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 - or to cancel the process. If Juliet completes the roster addition, the - client SHOULD also send a subscription request to Romeo. This request - SHOULD contain a 'preauth' element containing the authentication token - from the invitation link. -
-If Juliet's server supports subscription - pre-approval, the client SHOULD additionally pre-approve Romeo: -
-If Juliet's server does not indicate pre-approval support, her client - SHOULD store Romeo's JID in a local auto-approval whitelist, together - with an appropriate expiration time. -
-When Romeo's client receives a subscription request containing a - 'preauth' element, it needs to extract the authentication token and - check if the token is a valid one and was previously issued by the client - (see security considerations below).
-If the token is considered valid, the client SHOULD automatically approve - the subscription request, add the sender of the subscription request to - the roster and send a subscription request of its own.
-If Juliet's server support pre-approval, it will automatically handle the - incoming subscription request and issue a roster push. Otherwise, Juliet's - client will receive the subscription request:
-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.
- -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.
-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 - approval will be performed. Therefore, the contact's client should use the - same mechanism as before to indicate an unidirectional subscription. -
-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.
-Some mobile device platforms allow an app to register itself as a - handler for cetain URIs. This allows an XMPP client to register for xmpp: - 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 https://yax.im/i/*, 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. -
-As the authentication token grants automatic addition to
- Romeo's roster and automatic approval of presence subscription,
- the token SHOULD be created with a cryptographically secure random
- number generator
It is possible to use a different token
- generation scheme like SAML
To limit the potential for abuse, the token SHOULD be limited in as follows:
-If a token is considered invalid (due to failing any of the above - conditions, or for other reasons), a client MUST fall back to manual - roster addition and manual subscription approval. -
-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. -
-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 - true for all communication performed using the chosen medium and is out of - scope for this document.
-Ideally, Romeo's client should highlight automatically-added roster items - and provide an easy mechanism to remove them and cancel their - subscription.
-An attacker can lure the user by providing an invitation link with a - 'name' parameter that does not match the JID. Therefore, a client SHOULD - always display both the JID and the proposed display name when adding a - roster item.
-When the user's client automatically approves a subscription, it SHOULD - add the new contact to the roster without a 'name' or with the 'name' - equal to the JID, to prevent impersonation attacks.
-This document requires no interaction with &IANA;.
-Include the "urn:xmpp:pars:0" namespace in the registry of protocol - namespaces. Include "preauth" as an additional key-value parameter to the - roster query action.
-
- roster
- ...
-
- preauth
- the token used to obtain an automatic approval from the target JID
-
-
-]]>
-REQUIRED for protocol specifications.
-First draft.
Romeo is an active XMPP IM (Instant Messaging) user. He convinces Juliet + (who doesn't have an XMPP account yet) to install a client and + register with some server. Now, Romeo only needs to create a mutual + presence subscription with her, without yet knowing her JID.
+This specification allows Romeo to create an out-of-band link (URI) which, + when opened in Juilet's (or another user's) client, will:
+The perceivable effect is that with a single click, Romeo and Juliet + become "friends" in terms of XMPP presence subscription.
+This specification makes use of XMPP URIs. The basic URI scheme for XMPP + is defined in &rfc5122; and extended in &xep0147; to support different + actions like "roster" for roster addition and "subscribe" for presence + subscription. +
+The process of mutual roster addition and subscription involves multiple + steps:
+The general idea of the protocol and the details of the individual steps + are outlined in the following.
+As Romeo doesn't know Juliet's JID, he needs to send an out-of-band + invitation. Later, his client needs to match an incoming subscription + request to this invitation, so it can perform a secure automatic roster + addition and subscription approval. This matching is accomplished by + means of an authentication token, which is generated by Romeo's client, + added to the invitation link and then carried over into the subscription + request eventually made by Juliet's client. Romeo's client can then + compare the token received in a subscription request to the list of + issued tokens, and automatically approve the subscription.
+|
+ | | | roster add |
+ | | |<--------------|
+ | presence subscription request w/ token |
+ |
+ Whenever Romeo wishes to invite somebody to his roster, his client will + generate an invitation link that contains a new authentication token. + This document extends the "roster" URI action defined in XEP-0147 with + a new key-value parameter named "preauth" to store the generated token. + Romeo's client will create an xmpp: link containing Romeo's JID, the + "roster" action, the "preauth" parameter with the token value, and + optionally a "name" parameter with the suggested display name. +
++ If the "preauth" parameter is present, the processing client is supposed + not only to add the user to the roster, but also to automatically send a + subscription request containing the authentication token. +
+ + + +Server-side implementation: it is + possible (but out-of-scope for this document), to let the user's server + handle generation of links as well as automatic approval of qualified + subscription requests. This requires an additional mechanism to query the + server for new (and possibly also for pending) invitation links.
+ +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 xmpp: URIs, there is no mechanism to ensure that Juliet actually has a client installed that can open the URI.
+One way to solve this problem is to present Juliet with a web-based landing page that contains the following elements:
+There are multiple options where such a landing page could be hosted:
+A possible screen representation of the landing page would be:
+Romeo Montague has invited you to chat
+ +Add Romeo Montague
+If this link does not work, you need to install and configure + an XMPP client. Please visit this page again afterwards. Choose one of + these for your Tomato OS:
+Check the full list of XMPP clients.
+No further action is required if you do not know Romeo Montague or do not want to chat with them.
+XMPP is a provider-independent form of instant messaging. That means + you can pick from many different clients and have a free choice of + server operators to communicate with Romeo Montague.
+ +When Juliet opens the xmpp: 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 + or to cancel the process. If Juliet completes the roster addition, the + client SHOULD also send a subscription request to Romeo. This request + SHOULD contain a 'preauth' element containing the authentication token + from the invitation link. +
+If Juliet's server supports subscription + pre-approval, the client SHOULD additionally pre-approve Romeo: +
+If Juliet's server does not indicate pre-approval support, her client + SHOULD store Romeo's JID in a local auto-approval whitelist, together + with an appropriate expiration time. +
+When Romeo's client receives a subscription request containing a + 'preauth' element, it needs to extract the authentication token and + check if the token is a valid one and was previously issued by the client + (see security considerations below).
+If the token is considered valid, the client SHOULD automatically approve + the subscription request, add the sender of the subscription request to + the roster and send a subscription request of its own.
+If Juliet's server support pre-approval, it will automatically handle the + incoming subscription request and issue a roster push. Otherwise, Juliet's + client will receive the subscription request:
+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.
+ +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.
+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 + approval will be performed. Therefore, the contact's client should use the + same mechanism as before to indicate an unidirectional subscription. +
+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.
+Some mobile device platforms allow an app to register itself as a + handler for cetain URIs. This allows an XMPP client to register for xmpp: + 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 https://yax.im/i/*, 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. +
+As the authentication token grants automatic addition to
+ Romeo's roster and automatic approval of presence subscription,
+ the token SHOULD be created with a cryptographically secure random
+ number generator
It is possible to use a different token
+ generation scheme like SAML
To limit the potential for abuse, the token SHOULD be limited in as follows:
+If a token is considered invalid (due to failing any of the above + conditions, or for other reasons), a client MUST fall back to manual + roster addition and manual subscription approval. +
+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. +
+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 + true for all communication performed using the chosen medium and is out of + scope for this document.
+Ideally, Romeo's client should highlight automatically-added roster items + and provide an easy mechanism to remove them and cancel their + subscription.
+An attacker can lure the user by providing an invitation link with a + 'name' parameter that does not match the JID. Therefore, a client SHOULD + always display both the JID and the proposed display name when adding a + roster item.
+When the user's client automatically approves a subscription, it SHOULD + add the new contact to the roster without a 'name' or with the 'name' + equal to the JID, to prevent impersonation attacks.
+This document requires no interaction with &IANA;.
+Include the "urn:xmpp:pars:0" namespace in the registry of protocol + namespaces. Include "preauth" as an additional key-value parameter to the + roster query action.
+
+ roster
+ ...
+
+ preauth
+ the token used to obtain an automatic approval from the target JID
+
+
+]]>
+ REQUIRED for protocol specifications.
+