No Description
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

xep-0379.xml 21KB

  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <!DOCTYPE xep SYSTEM 'xep.dtd' [
  3. <!ENTITY % ents SYSTEM 'xep.ent'>
  4. %ents;
  5. ]>
  6. <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
  7. <xep>
  8. <header>
  9. <title>Pre-Authenticated Roster Subscription</title>
  10. <abstract>This document defines a protocol and URI scheme for pre-authenticated roster links that allow a third party to automatically obtain the user's presence subscription. The goal of this is to make onboarding of new XMPP IM contacts as easy as possible.</abstract>
  12. <number>0379</number>
  13. <status>Experimental</status>
  14. <type>Standards Track</type>
  15. <sig>Standards</sig>
  16. <approver>Council</approver>
  17. <dependencies>
  18. <spec>XMPP Core</spec>
  19. <spec>RFC 5122</spec>
  20. <spec>XEP-0147</spec>
  21. </dependencies>
  22. <supersedes/>
  23. <supersededby/>
  24. <shortname>pars</shortname>
  25. <author>
  26. <firstname>Georg</firstname>
  27. <surname>Lukas</surname>
  28. <email></email>
  29. <jid></jid>
  30. </author>
  31. <revision>
  32. <version>0.2.0</version>
  33. <date>2017-03-06</date>
  34. <initials>gl</initials>
  35. <remark><p>Change URI format, editing, add reference to XEP-0401.</p></remark>
  36. </revision>
  37. <revision>
  38. <version>0.1.2</version>
  39. <date>2017-02-16</date>
  40. <initials>gl</initials>
  41. <remark><p>Added "Usability Considerations", removed actual XMPP client, some text editing.</p></remark>
  42. </revision>
  43. <revision>
  44. <version>0.1.1</version>
  45. <date>2017-01-01</date>
  46. <initials>ssw</initials>
  47. <remark><p>Minor DTD and formatting fixes.</p></remark>
  48. </revision>
  49. <revision>
  50. <version>0.1.0</version>
  51. <date>2016-07-20</date>
  52. <initials>gl (XEP Editor: ssw)</initials>
  53. <remark><p>First draft.</p></remark>
  54. </revision>
  55. </header>
  56. <section1 topic='Introduction' anchor='intro'>
  57. <p>Romeo is an active XMPP IM (Instant Messaging) user. He convinces Juliet
  58. (who doesn't have an XMPP account yet) to install a client and
  59. register with some server. Now, Romeo only needs to create a mutual
  60. presence subscription with her, without yet knowing her JID.</p>
  61. <p>This specification allows Romeo to create an out-of-band link (URI) which,
  62. when opened in Juilet's (or another user's) client, will:</p>
  63. <ul>
  64. <li>Add Romeo to Juliet's roster (with a display name optionally specified by Romeo)</li>
  65. <li>Add Juliet to Romeo's roster (without a pre-defined display name)</li>
  66. <li>Establish a mutual presence subscription between Romeo and Juliet</li>
  67. </ul>
  68. <p>The perceivable effect is that with a single click, Romeo and Juliet
  69. become "friends" in terms of XMPP presence subscription.</p>
  70. </section1>
  71. <section1 topic='Requirements' anchor='reqs'>
  72. <p>This specification makes use of XMPP URIs. The basic URI scheme for XMPP
  73. is defined in &rfc5122; and extended in &xep0147; to support different
  74. actions like "roster" for roster addition and "subscribe" for presence
  75. subscription.
  76. </p>
  77. </section1>
  78. <section1 topic='Pre-Authenticated Roster Subscription' anchor='pars'>
  79. <p>The process of mutual roster addition and subscription involves multiple
  80. steps:</p>
  81. <ol>
  82. <li>Generation of invitation link</li>
  83. <li>Out-of-band transmission and presentation of the link</li>
  84. <li>Subcription request to the user by the link receiver (new contact)</li>
  85. <li>Approval by the user and mutual subscription request</li>
  86. <li>Approval by the new contact</li>
  87. </ol>
  88. <p>The general idea of the protocol and the details of the individual steps
  89. are outlined in the following.</p>
  90. <section2 topic='General Idea' anchor='general_idea'>
  91. <p>As Romeo doesn't know Juliet's JID, he needs to send an out-of-band
  92. invitation. Later, his client needs to match an incoming subscription
  93. request to this invitation, so it can perform a secure automatic roster
  94. addition and subscription approval. This matching is accomplished by
  95. means of an authentication token, which is generated by Romeo's client,
  96. added to the invitation link and then carried over into the subscription
  97. request eventually made by Juliet's client. Romeo's client can then
  98. compare the token received in a subscription request to the list of
  99. issued tokens, and automatically approve the subscription.</p>
  100. <code caption='Successful PARS Protocol Flow'><![CDATA[
  101. Romeo Juliet
  102. | | | |
  103. | Send out-of-band invitation link |
  104. |;preauth=token |
  105. |- - - - - - - - - - - - - - - - - - - - - - ->|
  106. | | | roster add |
  107. | | |<--------------|
  108. | presence subscription request w/ token |
  109. | <presence><preauth token="..."/></presence> |
  110. |<---------------------------------------------|
  111. | (token validation check) | |
  112. | presence subscribed | |
  113. |--------------------------------------------->|
  114. | roster add | | |
  115. |------------->| | |
  116. | presence subscription request| |
  117. |--------------------------------------------->|
  118. | | (auto approval) |
  119. | | presence subscribed |
  120. |<---------------------------------------------|
  121. ]]></code>
  122. </section2>
  123. <section2 topic='Generation of Invitation Link' anchor='link_generation'>
  124. <p>Whenever Romeo wishes to invite somebody to his roster, his client will
  125. generate an invitation link that contains a new authentication token.
  126. This document extends the "roster" URI action defined in <cite>XEP-0147</cite> with
  127. a new key-value parameter named "preauth" to store the generated token.
  128. Romeo's client will create an <strong>xmpp:</strong> link containing Romeo's JID, the
  129. "roster" action, the "preauth" parameter with the token value, and
  130. optionally a "name" parameter with the suggested display name.
  131. </p>
  132. <example caption='Invitation Link with Roster Action and Authentication Token'><![CDATA[
  134. ]]></example>
  135. <p>
  136. If the "preauth" parameter is present, the processing client is supposed
  137. not only to add the user to the roster, but also to automatically send a
  138. subscription request containing the authentication token.
  139. </p>
  140. <p></p>
  141. <p><strong>Server-side implementation:</strong> it is
  142. possible (but out-of-scope for this document), to let the user's server
  143. handle generation of links as well as automatic approval of qualified
  144. subscription requests. One such approach is documented in &xep0401;.</p>
  145. </section2>
  146. <section2 topic='Out-of-band Transmission and Presentation of the Link' anchor='link_transmission'>
  147. <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>
  148. <p>One way to solve this problem is to present Juliet with a web-based landing page that contains the following elements:</p>
  149. <ul>
  150. <li>A short text that this is an XMPP invitation from Romeo.</li>
  151. <li>A client recommendation (based on the detected web browser/OS) with download links.</li>
  152. <li>A prominent button that activates the actual <strong>xmpp:</strong> link.</li>
  153. </ul>
  154. <p>There are multiple options where such a landing page could be hosted:</p>
  155. <ol>
  156. <li><strong>XSF:</strong> a central place would provide a common ground
  157. for a curated client list and ensure long-term availability. However,
  158. the operator would be able to collect meta-data and abuse authentication tokens.</li>
  159. <li><strong>Client developer:</strong> the developer of Romeo's client can
  160. provide a landing page for invitation requests created with this
  161. client. This is a feasible short-term solution and allows to recommend
  162. the same client as used by the link sender. However, it shares the
  163. privacy objections of the XSF solution and can not guarantee
  164. long-term availability of the service. If the client development shuts
  165. down, invitation links created with the client will cease working.</li>
  166. <li><strong>User's server:</strong> this is the optimal long-term
  167. solution, as the user's server is already entrusted with the relevant
  168. meta-data and will exist at least as long as the user's account on that
  169. server. However, this requires an additional server component to query
  170. for invitation URIs and a web server hosting the landing page.
  171. Furthermore, the server operator needs to maintain the list of
  172. recommended clients.</li>
  173. </ol>
  174. <example caption='Developer-Hosted Landing Page Generated with Fictitious JuicyXMPP Client'><![CDATA[
  175. https://juicyxmpp.example/i/;preauth=1tMFqYDdKhfe2pwp;name=Romeo+Montague
  176. ]]></example>
  177. <p>A possible screen representation of the landing page would be:</p>
  178. <div class="example">
  179. <p><strong><em>Romeo Montague</em> has invited you to chat</strong></p>
  180. <p><strong><link url=';preauth=1tMFqYDdKhfe2pwp;name=Romeo%20Montague'>Add "Romeo Montague"</link></strong></p>
  181. <p>If this link does not work, you need to install and configure
  182. an XMPP client. Please visit this page again afterwards. Choose one of
  183. these for your <em>Tomato OS</em>:</p>
  184. <ul>
  185. <li><strong>JuicyXMPP</strong> (link to XMPP client)</li>
  186. <li><strong>VegetableChat</strong> (link to XMPP client)</li>
  187. </ul>
  188. <p>Check the <link url=''>full list of XMPP clients</link>.</p>
  189. <p>No further action is required if you do not know <em>Romeo Montague</em> or do not want to chat with them.</p>
  190. <p>XMPP is a provider-independent form of instant messaging. That means
  191. you can pick from many different clients and have a free choice of
  192. server operators to communicate with <em>Romeo Montague</em>.</p>
  193. </div>
  194. </section2>
  195. <section2 topic='Subcription Request to the User by the Link Receiver (New Contact)' anchor='link_transmission'>
  196. <p>When Juliet opens the <strong>xmpp:</strong> URI (or the according client-supported
  197. landing page URI) in her client, the client should perform the usual
  198. roster addition action, i.e. display a dialog allowing to edit the entry
  199. or to cancel the process. If Juliet completes the roster addition, the
  200. client SHOULD also send a subscription request to Romeo. This request
  201. SHOULD contain a 'preauth' element containing the authentication token
  202. from the invitation link.
  203. </p>
  204. <example caption='Subscription Request with Pre-Authenticated Roster Subscription Element'><![CDATA[
  205. <presence to='' type='subscribe'>
  206. <preauth xmlns='urn:xmpp:pars:0' token='1tMFqYDdKhfe2pwp' />
  207. </presence>
  208. ]]></example>
  209. <p>If Juliet's server supports <link
  210. url=''>subscription
  211. pre-approval</link>, the client SHOULD additionally pre-approve Romeo:
  212. </p>
  213. <example caption='Juliet Pre-approves Romeo'><![CDATA[
  214. <presence to='' type='subscribed' />
  215. ]]></example>
  216. <p>If Juliet's server does not indicate pre-approval support, her client
  217. SHOULD store Romeo's JID in a local auto-approval whitelist, together
  218. with an appropriate expiration time.
  219. </p>
  220. </section2>
  221. <section2 topic='Approval by the User and Mutual Subscription Request' anchor='sub_approval'>
  222. <p>When Romeo's client receives a subscription request containing a
  223. 'preauth' element, it needs to extract the authentication token and
  224. check if the token is a valid one and was previously issued by the client
  225. (see security considerations below).</p>
  226. <example caption='Subscription Request With Tokens Received by Romeo'><![CDATA[
  227. <presence to='' from='' type='subscribe'>
  228. <preauth xmlns='urn:xmpp:pars:0' token='1tMFqYDdKhfe2pwp' />
  229. </presence>
  230. ]]></example>
  231. <p>If the token is considered valid, the client SHOULD automatically approve
  232. the subscription request, add the sender of the subscription request to
  233. the roster and send a subscription request of its own.</p>
  234. <example caption='Automatic Approval and Response Subscription Request'><![CDATA[
  235. <presence to='' type='subscribed' />
  236. <presence to='' type='subscribe' />
  237. ]]></example>
  238. </section2>
  239. <section2 topic='Approval by the New Contact' anchor='sub_mutual_approval'>
  240. <p>If Juliet's server supports pre-approval, it will automatically handle the
  241. incoming subscription request and issue a roster push. Otherwise, Juliet's
  242. client will receive the subscription request:</p>
  243. <example caption='Mutual Subscription Request'><![CDATA[
  244. <presence from='' to='' type='subscribe' />
  245. ]]></example>
  246. <p>Juliet's client MUST ensure that the sender JID is contained in the
  247. auto-approval whitelist before automatically approving the request.
  248. Otherwise, it has to fallback to the normal subscription approval
  249. process.</p>
  250. </section2>
  251. </section1>
  252. <section1 topic='Business Rules' anchor='rules'>
  253. <section2 topic='Fallback to Manual Process' anchor='rules_fallback'>
  254. <p>An implementation of this protocol MUST allow for a "graceful
  255. degradation" to the manual subscription approval process. If a client
  256. receives a malformed or unknown 'preauth' token, it MUST ignore it and act
  257. as if no preauth token was contained.</p>
  258. </section2>
  259. <section2 topic='No Expectaion of Immediate Approval' anchor='rules_expectation'>
  260. <p>When sending a pre-authenticated subscription request, the contact's
  261. client MUST NOT expect an immediate successful approval. If the user's
  262. issuing client is currently offline, or if the token has expired, a manual
  263. approval will be performed. Therefore, the contact's client should use the
  264. same mechanism as before to indicate an unidirectional subscription.
  265. </p>
  266. </section2>
  267. </section1>
  268. <section1 topic='Security Considerations' anchor='security'>
  269. <section2 topic='Token Generation' anchor='security_token'>
  270. <p>As the authentication token grants automatic addition to
  271. Romeo's roster and automatic approval of presence subscription,
  272. the token SHOULD be created with a cryptographically secure random
  273. number generator <note>See for example <tt><link
  274. url=''>getrandom(2)</link></tt>,
  275. <tt><link
  276. url=''>SecureRandom</link></tt>
  277. or <tt>/dev/urandom</tt>. More information about the randomness
  278. requirements for security can be found in &rfc4086;</note> and
  279. provide sufficient entropy to make brute-force attacks
  280. infeasible. It is suggested to generate at least 80 bits of
  281. entropy, and to use an encoding that can be easily encoded as part
  282. of an URI (e.g. Base-32).</p> <p>It is possible to use a different token
  283. generation scheme like &saml; or JWT (&rfc7519;).
  284. In such a case, the issuer must ensure a comparable security level and
  285. limit token reuse.</p>
  286. </section2>
  287. <section2 topic='Checking Token Validity' anchor='security_validity'>
  288. <p>To limit the potential for abuse, the token SHOULD be limited in as follows:</p>
  289. <ul>
  290. <li><strong>Usage:</strong> in the typical scenario, each token may only
  291. be used once. While it is possible for a client to generate a token for
  292. multiple uses (like for embedding it in a contact card), the
  293. conventional manual roster management should be used for public
  294. invitation links.</li>
  295. <li><strong>Time:</strong> each token MUST have a limited validity time.
  296. As the token is transmitted out-of-band, it should provide sufficient
  297. reaction time, e.g. one week. This time limit also allows the issuer to
  298. delete expired tokens.</li>
  299. <li><strong>Identity:</strong> if the JID of the token receiver is known
  300. in advance, the token sender MUST NOT allow a different JID to redeem
  301. this token.</li>
  302. </ul>
  303. <p>If a token is considered invalid (due to failing any of the above
  304. conditions, or for other reasons), a client MUST fall back to manual
  305. roster addition and manual subscription approval.
  306. </p>
  307. </section2>
  308. <section2 topic='Interception of Links' anchor='security_intercept'>
  309. <p>A Monkey-in-the-Middle attacker who gains access to the invitation link
  310. can manipulate its fields or redeem the link themselves. However, this is
  311. true for all communication performed using the chosen medium and is out of
  312. scope for this document.</p>
  313. <p>Ideally, Romeo's client should highlight automatically-added roster items
  314. and provide an easy mechanism to remove them and cancel their
  315. subscription.</p>
  316. </section2>
  317. <section2 topic='Display Names' anchor='security_display'>
  318. <p>An attacker can lure the user by providing an invitation link with a
  319. 'name' parameter that does not match the JID. Therefore, a client SHOULD
  320. always display both the JID and the proposed display name when adding a
  321. roster item.</p>
  322. <p>When the user's client automatically approves a subscription, it SHOULD
  323. add the new contact to the roster without a 'name' or with the 'name'
  324. equal to the JID, to prevent impersonation attacks.</p>
  325. </section2>
  326. </section1>
  327. <section1 topic='Usability Considerations' anchor='usability'>
  328. <section2 topic='Use of Multiple Clients' anchor='rules_multiclient'>
  329. <p>If a user is logged in with multiple clients, some of their clients will
  330. receive a subscription request with an unknown token. In this case, a client
  331. MAY delay the user notification for a short time, to allow another logged-in
  332. client to automatically handle the subscription request.</p>
  333. </section2>
  334. <section2 topic='Opening the Landing Page in an App' anchor='rules_multiclient'>
  335. <p>Some mobile device platforms allow an app to register itself as a
  336. handler for cetain URIs. This allows an XMPP client to register for <strong>xmpp:</strong>
  337. URIs, but also to redirect handling of cetain HTTP/HTTPS URIs. A mobile
  338. client SHOULD register for the associated landing page URIs and properly
  339. handle the contained invitations. For example, the JuicyXMPP client should
  340. register a handler for <strong>https://juicyxmpp.example/i/*</strong>, and present
  341. the "Add to roster" dialog if such a link is opened. A client MAY register
  342. for the landing page URIs of other providers after obtaining the
  343. operators' approval.
  344. </p>
  345. </section2>
  346. <section2 topic='Invitation Link Volatility' anchor='rules_volatile'>
  347. <p>By default, Romeo's client should generate personal invitation links
  348. that can only be redeemed once, and only for a limited time. This fact
  349. SHOULD be indicated by the client UI to Romeo.</p>
  350. <p>If a client allows customization of the validity time or the number of
  351. uses for a given invitation token, it SHOULD provide clear language
  352. to inidcate that.</p>
  353. </section2>
  354. <section2 topic='Tagging of Auto-Added Contacts' anchor='rules_group'>
  355. <p>When a new contact is added automatically by the client, it SHOULD
  356. indicate this fact to the user, and allow the user to rename / group
  357. the contact appropriately. One possible way to achieve this is by
  358. putting all auto-added contacts into a special roster group, and by
  359. automatically removing this group on the first manual edit of the
  360. contact.</p>
  361. <p>In this case, the roster group should be named by the client according
  362. to the user's locale settings. However, this approach might lead to
  363. different clients using different group names, resulting in multiple
  364. roster groups with the same goal.</p>
  365. </section2>
  366. </section1>
  367. <section1 topic='IANA Considerations' anchor='iana'>
  368. <p>This document requires no interaction with &IANA;.</p>
  369. </section1>
  370. <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  371. <p>Include the "urn:xmpp:pars:0" namespace in the registry of protocol
  372. namespaces. Include "preauth" as an additional key-value parameter to the
  373. roster query action.</p>
  374. <code caption='New Roster Query Action Parameter'><![CDATA[
  375. <querytype>
  376. <name>roster</name>
  377. ...
  378. <key>
  379. <name>preauth</name>
  380. <desc>the token used to obtain an automatic approval from the target JID</desc>
  381. </key>
  382. </querytype>
  383. ]]></code>
  384. </section1>
  385. <section1 topic='XML Schema' anchor='schema'>
  386. <p>REQUIRED for protocol specifications.</p>
  387. </section1>
  388. </xep>