diff --git a/xep-0399.xml b/xep-0399.xml new file mode 100644 index 00000000..94171e56 --- /dev/null +++ b/xep-0399.xml @@ -0,0 +1,129 @@ + + + + +%ents; +]> + + +
+ Client Key Support + This specification defines an XMPP binding of the supporting functions for the CLIENT-KEY SASL mechanism. + &LEGALNOTICE; + 0399 + Experimental + Standards Track + Standards + Council + + + + client-key + + standards + + Dave + Cridland + dave.cridland@surevine.com + dave.cridland@surevine.com + + + 0.1.0 + 2018-01-25 + XEP Editor (jwi) + Accepted by vote of Council on 2018-01-10. + + + 0.0.1 + 2018-01-08 + dwd +

First draft

 + +
+ +

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.

+ + + +

A typical client might use this protocol alongside that of TOTP, &xep0388;, and &draft; as follows.

+

On first use, a client will use a traditional SASL mechanism using SASL2, such as SCRAM. The server will then prompt using <next-authenticate/> to initiate, or perform, TOTP.

+

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.

+

Later authentications will use CLIENT-KEY or CLIENT-KEY-PLUS, and the server SHOULD suppress TOTP in such cases.

+ + + + +

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.

+

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 <register/> element qualified by the '&namespace;' namespace, containing four elements in any order. Descriptions of values are here informative; the canonical definition is in &draft;.

+

<id/> has a text value of the ClientID, a suitable identifier for the client instance, unique within the scope of the authenticated &BAREJID;.

+

<name/> has a text value of the Client Name, a human-readable name for the client instance.

+

<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;.

+

<ttl/> has a text value containing a integer string representation of the number of seconds the Client Key is requested to last for.

+

In the following example, the ValidationKey is H("Random"), and the TTL is for 30 days - a reasonable "Remember this client" option.

+ + + 213456-987123-123987 + SuperChatBiscuit on Honest Pete's Mobile OS + WNiIwIqlYfNw44zul2EhUyqIPXE= + 2592000 + + + ]]> +

The server responds with two items of information in a <registered/> element qualified by the '&namespace;' namespace. The EncryptedSecret is contained within a <encrypted-secret/> element as a base64-encoded value, and the <expiry/> element contains a timestamp for expiry.

+ + + WNiIwIqlYfNw44zul2EhUyqIPXE= + 2017-10-15T12:00:00Z + + +]]> +

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.

+ + +

Any authenticated client may revoke a key belonging to the same user by sending an &IQ; of type "set" containing a <revoke/> element qualified by the '&namespace;' namespace, containing a <key/> element whose text value is the ClientID corresponding to the key to be revoked.

+ + + 213456-987123-123987 + + + ]]> + + +

Any authenticated client may enumerate keys belonging to the same user by sending an &IQ; of type "get" containing a <list/> element qualified by the '&namespace;' namespace.

+ + + + ]]> +

The server responds with an &IQ; of type 'result', containing the <list/> element qualified by the '&namespace;' namespace. This element contains a sequence of <key/> elements each containing (in any order) the <id/>, <name/> and <expiry/> elements as in registration.

+ + + + 213456-987123-123987 + SuperChatBiscuit on Honest Pete's Mobile OS + 2017-10-15T12:00:00Z + + + 313456-987123-123987 + SuperChatChocolate on Honest Bob's Mobile OS + 2018-01-08T12:00:00Z + + + + ]]> + + + + +

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.

+ + + +

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.

+ +