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.

130 lines

  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <!DOCTYPE xep SYSTEM 'xep.dtd' [
  3. <!ENTITY namespace "urn:xmpp:client-key:0">
  4. <!ENTITY draft "draft-cridland-kitten-clientkey-00.txt">
  5. <!ENTITY % ents SYSTEM 'xep.ent'>
  6. %ents;
  7. ]>
  8. <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
  9. <xep>
  10. <header>
  11. <title>Client Key Support</title>
  12. <abstract>This specification defines an XMPP binding of the supporting functions for the CLIENT-KEY SASL mechanism.</abstract>
  14. <number>0399</number>
  15. <status>Experimental</status>
  16. <type>Standards Track</type>
  17. <sig>Standards</sig>
  18. <approver>Council</approver>
  19. <dependencies/>
  20. <supersedes/>
  21. <supersededby/>
  22. <shortname>client-key</shortname>
  23. <registry/>
  24. <discuss>standards</discuss>
  25. <author>
  26. <firstname>Dave</firstname>
  27. <surname>Cridland</surname>
  28. <email></email>
  29. <jid></jid>
  30. </author>
  31. <revision>
  32. <version>0.1.0</version>
  33. <date>2018-01-25</date>
  34. <initials>XEP Editor (jwi)</initials>
  35. <remark>Accepted by vote of Council on 2018-01-10.</remark>
  36. </revision>
  37. <revision>
  38. <version>0.0.1</version>
  39. <date>2018-01-08</date>
  40. <initials>dwd</initials>
  41. <remark><p>First draft</p></remark>
  42. </revision>
  43. </header>
  44. <section1 topic='Introduction' anchor='intro'>
  45. <p>The CLIENT-KEY SASL mechanism defined in &draft; suggests supporting protocol messages to be present in the application protocol. This specification defines these for XMPP.</p>
  46. </section1>
  47. <section1 topic="Typical Flow">
  48. <p>A typical client might use this protocol alongside that of TOTP, &xep0388;, and &draft; as follows.</p>
  49. <p>On first use, a client will use a traditional SASL mechanism using SASL2, such as SCRAM. The server will then prompt using &lt;next-authenticate/> to initiate, or perform, TOTP.</p>
  50. <p>The client will then request a Client Key to reauthenticate later. This may be one or both of a short-term Client Key intended for in-memory storage, perhaps for use with ISR, and a longer-term Client Key used for a "remember this client" to suppress 2FA for a period.</p>
  51. <p>Later authentications will use CLIENT-KEY or CLIENT-KEY-PLUS, and the server SHOULD suppress TOTP in such cases.</p>
  52. </section1>
  53. <section1 topic="Client Key Support Operations">
  54. <section2 topic="Client Registration">
  55. <p>Client registration requests a Client Key from the server. It is typically used to speed reauthentication during a session, and to elide a full reauthentication at the start of a subsequent session.</p>
  56. <p>In order to register and obtain a Client Key, a client sends an &IQ; of type "set" containing an XML representation of the data required, within a &lt;register/&gt; element qualified by the '&namespace;' namespace, containing four elements in any order. Descriptions of values are here informative; the canonical definition is in &draft;.</p>
  57. <p>&lt;id/> has a text value of the ClientID, a suitable identifier for the client instance, unique within the scope of the authenticated &BAREJID;.</p>
  58. <p>&lt;name/> has a text value of the Client Name, a human-readable name for the client instance.</p>
  59. <p>&lt;key/> has a text value of the ValidationKey, encoded using Base 64. Implementors are strongly advised to take careful note of the requirements of the ValidationKey as discussed in &draft;.</p>
  60. <p>&lt;ttl/> has a text value containing a integer string representation of the number of seconds the Client Key is requested to last for.</p>
  61. <p>In the following example, the ValidationKey is H("Random"), and the TTL is for 30 days - a reasonable "Remember this client" option.</p>
  62. <example><![CDATA[
  63. <iq type='set' id='123456'>
  64. <register xmlns=']]>&namespace;<![CDATA['>
  65. <id>213456-987123-123987</iq>
  66. <name>SuperChatBiscuit on Honest Pete's Mobile OS</name>
  67. <key>WNiIwIqlYfNw44zul2EhUyqIPXE=</key>
  68. <ttl>2592000</ttl>
  69. </register>
  70. </iq>
  71. ]]></example>
  72. <p>The server responds with two items of information in a &lt;registered/> element qualified by the '&namespace;' namespace. The EncryptedSecret is contained within a &lt;encrypted-secret/> element as a base64-encoded value, and the &lt;expiry/> element contains a timestamp for expiry.</p>
  73. <example><![CDATA[
  74. <iq type='result' id='123456'>
  75. <registered xmlns=']]>&namespace;<![CDATA['>
  76. <encrypted-secret>WNiIwIqlYfNw44zul2EhUyqIPXE=</encrypted-secret>
  77. <expiry>2017-10-15T12:00:00Z</expiry>
  78. </registered>
  79. </iq>
  80. ]]></example>
  81. <p>Note that the expiry time might not be 30 days simply because the client has requested it - the server is free to shorten expiry times.</p>
  82. </section2>
  83. <section2 topic="Key Revocation">
  84. <p>Any authenticated client may revoke a key belonging to the same user by sending an &IQ; of type "set" containing a &lt;revoke/> element qualified by the '&namespace;' namespace, containing a &lt;key/> element whose text value is the ClientID corresponding to the key to be revoked.</p>
  85. <example><![CDATA[
  86. <iq type='set' id='123456'>
  87. <revoke xmlns=']]>&namespace;<![CDATA['>
  88. <id>213456-987123-123987</iq>
  89. </revoke>
  90. </iq>
  91. ]]></example>
  92. </section2>
  93. <section2 topic="Key Enumeration">
  94. <p>Any authenticated client may enumerate keys belonging to the same user by sending an &IQ; of type "get" containing a &lt;list/> element qualified by the '&namespace;' namespace.</p>
  95. <example><![CDATA[
  96. <iq type='get' id='123456'>
  97. <list xmlns=']]>&namespace;<![CDATA['/>
  98. </iq>
  99. ]]></example>
  100. <p>The server responds with an &IQ; of type 'result', containing the &lt;list/> element qualified by the '&namespace;' namespace. This element contains a sequence of &lt;key/> elements each containing (in any order) the &lt;id/>, &lt;name/> and &lt;expiry/> elements as in registration.</p>
  101. <example><![CDATA[
  102. <iq type='result' id='123456'>
  103. <list xmlns=']]>&namespace;<![CDATA['>
  104. <key>
  105. <id>213456-987123-123987</iq>
  106. <name>SuperChatBiscuit on Honest Pete's Mobile OS</name>
  107. <expiry>2017-10-15T12:00:00Z</expiry>
  108. </key>
  109. <key>
  110. <id>313456-987123-123987</iq>
  111. <name>SuperChatChocolate on Honest Bob's Mobile OS</name>
  112. <expiry>2018-01-08T12:00:00Z</expiry>
  113. </key>
  114. </list>
  115. </iq>
  116. ]]></example>
  117. </section2>
  118. </section1>
  119. <section1 topic='Determining Support' anchor='support'>
  120. <p>Support for this protocol is advertised as the Disco feature '&namespace;'; however clients MAY infer support if the CLIENT-KEY or CLIENT-KEY-PLUS SASL mechanism is supported.</p>
  121. </section1>
  122. <section1 topic='Security Considerations' anchor='security'>
  123. <p>Security considerations for this specification are covered within the Internet-Draft &draft; - this specification introduces no further considerations by design, but relies heavily on the guidance given there.</p>
  124. </section1>
  125. </xep>