Difference between revisions of "XMPP IM Client Design Guidelines"
m (→Description: typo) |
Neustradamus (talk | contribs) m |
||
| (7 intermediate revisions by 2 users not shown) | |||
| Line 9: | Line 9: | ||
=== Description === | === Description === | ||
XMPP Clients should only ask the user for | XMPP Clients should only ask the user for their JID and password. A proper XMPP setup does not require more information in order for the client to establish a successful connection to the server. There should be a single JID text field in which the user is expected to enter their bare JID. Visual feedback once it was detected that a valid bare JID was entered, e.g. a green check mark or changing the field's background color (from red) to green, is also a good idea. | ||
=== Rationale === | === Rationale === | ||
Splitting the JID into multiple input fields makes it impossible for the user to simply copy&paste | Splitting the JID into multiple input fields makes it impossible for the user to simply copy&paste their JID into the field. Asking the user for more then their bare JID and password increases the UI elements and reduces the usability. | ||
== Provide an advanced option allowing the user to specify the host and port to connect to == | == Provide an advanced option allowing the user to specify the host and port to connect to == | ||
| Line 65: | Line 65: | ||
=== Description === | === Description === | ||
Users want to know the type of a remote resource, e.g. "Is this the resource of my friends mobile device or of | Users want to know the type of a remote resource, e.g. "Is this the resource of my friends mobile device or of their desktop?". Clients should display the type using the 'identity' information provided by [http://xmpp.org/extensions/xep-0030.html#info-basic XEP-30 disco#info] query results. Also they should set a meaningful XEP-30 'identity'. So instead of having a resource like '/work-pc', the client should return | ||
<pre name='xml'> | <pre name='xml'> | ||
| Line 118: | Line 118: | ||
== Implement SCRAM | == Implement PLAIN and SCRAM == | ||
=== Description === | === Description === | ||
| Line 124: | Line 124: | ||
Do '''not''': Implement DIGEST-MD5 or CRAM-MD5. These mechanisms only work if the server has access to the plain password. | Do '''not''': Implement DIGEST-MD5 or CRAM-MD5. These mechanisms only work if the server has access to the plain password. | ||
Do: Implement SCRAM-SHA-1 and PLAIN. | Do: Implement SCRAM-SHA-1 / SCRAM-SHA-256 / SCRAM-SHA-512 / SCRAM-SHA3-512 and PLAIN. | ||
=== Rationale === | === Rationale === | ||
Hashing and salting passwords helps making it hard to retrieve the plain password from a compromised server. However, we would also like to be able to protect the password while it is in transit. These two concepts are difficult to combine: DIGEST-MD5 and CRAM-MD5 | Hashing and salting passwords helps making it hard to retrieve the plain password from a compromised server. However, we would also like to be able to protect the password while it is in transit. These two concepts are difficult to combine: DIGEST-MD5 and CRAM-MD5 do not protect the password in transit or at rest – the mechanisms can't work if the server wants to store the password hashed and salted. SCRAM protects the password both in flight and at rest. | ||
PLAIN is a widely used fallback that is still useful for servers that store their passwords hashed differently than required by SCRAM. | |||
See [[ | See [[SASL Authentication and SCRAM]] for help with implementing SCRAM. | ||
For more detailed and up to date recommendations see [https://xmpp.org/extensions/xep-0438.html XEP-0438: Best practices for password hashing and storage] | |||
Latest revision as of 01:53, 9 March 2021
Introduction
These Guidelines provide some advices and recommendations to XMPP IM Client developers about how to use XMPP for Instant Messaging purposes. This document was created collaboratively by the XMPP community, it is not a official publication of the XMPP Standards Foundation (XSF), nor are developers required to follow the recommendations.
Advices And Recommendations
Do not to split up JIDs into multiple input fields, require only the user's JID and password
Description
XMPP Clients should only ask the user for their JID and password. A proper XMPP setup does not require more information in order for the client to establish a successful connection to the server. There should be a single JID text field in which the user is expected to enter their bare JID. Visual feedback once it was detected that a valid bare JID was entered, e.g. a green check mark or changing the field's background color (from red) to green, is also a good idea.
Rationale
Splitting the JID into multiple input fields makes it impossible for the user to simply copy&paste their JID into the field. Asking the user for more then their bare JID and password increases the UI elements and reduces the usability.
Provide an advanced option allowing the user to specify the host and port to connect to
Description
Users should be able to specify the host and port to which the client tries to establish the connection to. If this is specified the usual and recommend way to determine the host/port via DNS SRV resource records is not used.
Rationale
Some servers don't have proper DNS SRV resource records configured.
Provide an advanced option allowing the user to specify the SASL authentication identity (authcid)
Description
Users should be able to specify the authentication identity the client uses when performing SASL authentication. If this is specified the usual and recommend way of using the locapart of the users JID is not used.
Rationale
Nothing in the XMPP specification requires the SASL authentication identity to be the localpart of the users JID. While this is true for most XMPP services, there are services which need the SASL authentication identity to be something else.
Show user's room nickname and allow to change it
Description
Rationale
Use only TLS secured XMPP c2s connections
Description
Rationale
Do not to encode any semantics into the resource, let the server generate a resource for you
Description
Instead of letting the user specify a resource or providing a pre-configured list of possible resource names (e.g. '/home', '/work', '/notebook') let the server generate a resource for your client (RFC 6120 7.6). Servers are required to support this. You may optionally provide a possibility to configure the resource to the user under a "advanced settings" menu (or similar). But a XMPP user should not need to configure or specify a resource.
Ideally you also store the resource you obtained from the server on the first connection, and re-use that on later connections. That way, a properly-configured server will close your old session if it still was deemed active by it. But make sure to handle 'conflict' stream errors in case the server terminates the new session with a 'conflict' stream error.
Rationale
Resource names should not be guessable to prevent presence leaks (RFC 6120 13.10.2).
Providing a default resource also prevents the user from using the same software from two different locations at the same time.
Show the type and name of a resource (mobile, pc, home, work, etc.) by means of Service Discovery and not the resource string itself. Also set meaningful 'identity' information yourself
Description
Users want to know the type of a remote resource, e.g. "Is this the resource of my friends mobile device or of their desktop?". Clients should display the type using the 'identity' information provided by XEP-30 disco#info query results. Also they should set a meaningful XEP-30 'identity'. So instead of having a resource like '/work-pc', the client should return
<iq type='result'
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'
id='info4'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<identity
category='client'
type='pc'
name='Work PC'/>
<feature var='jabber:iq:time'/>
<feature var='jabber:iq:version'/>
</query>
</iq>
within the 'disco#info' results.
Rationale
Encoding semantics in the value of the resource is not recommend (see previous item).
When making a custom extension, add new elements to <message>, <iq> or <presence> stanzas
Description
Do not:
- Add new attributes on the
<message>,<iq>or<presence>elements. - Create new
typevalues for stanzas. - Create new top-level elements.
- Put your custom data in the
<body>of a<message>. - Invent new values for the
<show>element in<presence>stanzas (allowed values are listed in RFC 6121 section 4.7.2.1)
Do:
Add a new XML element in your own namespace:
<message
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'
type='chat'>
<data xmlns='https://example.im/my-awesome-new-xmpp-app'></data>
</message>
Rationale
XMPP is very extensible, but some rules need to be followed if you want (standard) XMPP servers to be able to handle your message. The attributes of <message>, <iq> or <presence> elements may be stripped by servers if they do not understand it, or the server may completely refuse to handle the packet. Any XML element inside the stanza will be passed along to the recipient unchanged. This will also make it easier for other XMPP libraries to work with your data.
Implement PLAIN and SCRAM
Description
Do not: Implement DIGEST-MD5 or CRAM-MD5. These mechanisms only work if the server has access to the plain password.
Do: Implement SCRAM-SHA-1 / SCRAM-SHA-256 / SCRAM-SHA-512 / SCRAM-SHA3-512 and PLAIN.
Rationale
Hashing and salting passwords helps making it hard to retrieve the plain password from a compromised server. However, we would also like to be able to protect the password while it is in transit. These two concepts are difficult to combine: DIGEST-MD5 and CRAM-MD5 do not protect the password in transit or at rest – the mechanisms can't work if the server wants to store the password hashed and salted. SCRAM protects the password both in flight and at rest.
PLAIN is a widely used fallback that is still useful for servers that store their passwords hashed differently than required by SCRAM.
See SASL Authentication and SCRAM for help with implementing SCRAM.
For more detailed and up to date recommendations see XEP-0438: Best practices for password hashing and storage