mod_auth_internal_hashed

This is an authentication provider module that stores passwords in the configured data store, in hashed form.

Usage

Required reading

Hashing passwords in the data store protects them from immediate use by anyone with access to the store, as the original password cannot be easily recovered. This is in general good for security, but has some implications you should be aware of:

  • Once hashed, there is no way to go back to plain storage without resetting all users’ passwords, nor is there any way to switch to a different hash function at this time.
  • There is currently no standard way to migrate hashed passwords between different XMPP server software. This is being worked on.
  • For clients that do not support the new SCRAM-SHA-1 mechanism (most at the time of writing), authentication will be slower.
  • DIGEST-MD5 is not compatible with hashed password storage, and will not work, and older clients might complain about that.
  • Clients that do not yet support SCRAM-SHA-1 will only be able to use the PLAIN mechanism to authenticate, which is insecure if used without TLS (and completely trusted certificates).

With the last point in mind, think carefully about whether it is easier for you to secure your server or secure and educate all your users. 😄

“The user’s going to pick dancing pigs over security every time.” – Bruce Schneier

For a more thorough discussion on these issues, see our article “Plain or hashed?”.

Activating

When you first activate hashed storage, user accounts will automatically be upgraded from plain to hashed one-by-one as they log in.

In your config file, put:

authentication = "internal_hashed"

This can be set globally or per-host.

Hash function

The hash function used with PBKDF2 can be configured.

Note that SHA-1 as used here is not in any way insecure. Changing hash function from the default has negotiable effect on security, and large effect on client compatibility, as it may force clients to fall back to less secure authentication. For more security without complications, increase the iteration count instead.

This can only be set once, before any user accounts have been created. Changing it invalidates all user accounts and they will have to have their passwords reset.

password_hash = "SHA-1" -- "SHA-256" is the other option

Iteration count

This determines how expensive the password hash derivation function is. Higher values makes the hashes harder to brute-force, but may also make authentications more expensive for clients.

default_iteration_count = 10000