Credentials and Passwords

Overview

This guide covers a variety of topics related to credentials and passwords used by the internal authentication backend. If a different authentication backend (or mechanism) is used, the material in this guide is not applicable.

RabbitMQ supports multiple authentication mechanisms. Some of them use username/password pairs. These credential pairs are then handed over to an authentication backends that perform authentication. One of the backends, known as internal or built-in, uses internal RabbitMQ data store to store user credentials. When a new user is added using rabbitmqctl, her password is combined with a salt value and hashed.

As of version 3.6.0, RabbitMQ can be configured to use several password hashing functions:

• SHA-256
• SHA-512
• MD5 (only for backwards compatibility)

SHA-256 is used by default. More algorithms can be provided by plugins.

Configuring Algorithm to Use

It is possible to change what algorithm is used via RabbitMQ configuration file, for example, to use SHA-512:

[
  {rabbit, [{password_hashing_module, rabbit_password_hashing_sha512}]}
].

Out of the box, the following hashing modules are provided:

• rabbit_password_hashing_sha256 (default)
• rabbit_password_hashing_sha512
• rabbit_password_hashing_md5 (for backwards compatibility)

Updated hashing algorithm will be applied to newly created users or when password is changed using rabbitmqctl.

Upgrading from pre-3.6.0 to 3.6.1 or Later Versions

When upgrading from a pre-3.6 version to RabbitMQ 3.6.1 or later, all existing users are marked as using the legacy password hashing function, therefore they will be able to authenticate. No upgrade steps are required.

When importing definitions exported from versions earlier than 3.6.0 into a 3.6.1 or later release, existing user records will use MD5 for password hashing. In order to migrate them to a more secure algorithm, use rabbitmqctl to update their passwords.

Upgrading from pre-3.6.0 to 3.6.0

When upgrading from a pre-3.6 version to RabbitMQ 3.6.0 (but not later versions), all existing users are marked as using the legacy password hashing function, therefore they will be able to authenticate. No upgrade steps are required.

If you'd like to avoid using MD5 for existing users, you need to update passwords for all users using rabbitmqctl after upgrading.

When importing definitions exported from versions earlier than 3.6.0, it is possible to go back to MD5 (as a temporary measure) by setting this to rabbit_password_hashing_md5:

• Set rabbit.password_hashing_module to rabbit_password_hashing_md5 in the config. This means all imported (or newly created any other way) user records will have MD5 applied for hashing, with a relevant hint stored for later authentication.
• Perform definitions import
• Stop the (new) node
• Set rabbit.password_hashing_module to rabbit_password_hashing_sha256 in the config

The above steps are only necessary for those who perform an export on a pre-3.6.0 node and then an import to 3.6.0. Those who upgrade "in place" or move definitions from a 3.6.0+ node to another 3.6.0+ node do not need to do anything.

The most secure thing to do is to update passwords for all existing users, if possible, to avoid relying on MD5 for anything.

Credential Validation

Starting with version 3.6.7 it is possible to define a credential validator. It only has effect on the internal authentication backend and kicks in when a new user is added or password of an existing user is changed.

Validators are modules that implement a validation function. To use a validator, it is necessary to specify it and its additional settings in the config file. There are three credential validators available out of the box:

• rabbit_credential_validator_accept_everything: unconditionally accepts all values. This validator is used by default for backwards compatibility.
• rabbit_credential_validator_min_password_length: validates password length
• rabbit_credential_validator_password_regexp: validates that password matches a regular expression

The following example demonstrates how rabbit_credential_validator_min_password_length is used:

[
 {rabbit, [
           {credential_validator, [{validation_backend,
                                    rabbit_credential_validator_min_password_length},
                                   {min_length, 30}]}
          ]}
].
        

The following example demonstrates how rabbit_credential_validator_password_regexp is used:

[
 {rabbit, [
           {credential_validator, [{validation_backend,
                                    rabbit_credential_validator_password_regexp},
                                   {regexp, <<"^[a-bA-Z0-9$]{20,100}">>}]}
          ]}
].
        

Computing Password Hash

In order to update a user's password hash via the HTTP API, the password hash must be generated using the following algorithm:

• Generate a random 32 bit salt:
  908D C60A
• Concatenate that with the UTF-8 representation of the password (in this case test12):
  908D C60A 7465 7374 3132
• Take the SHA-256 hash (assuming the hashing function wasn't modified):
  A5B9 24B3 096B 8897 D65A 3B5F 80FA 5DB62 A94 B831 22CD F4F8 FEAD 10D5 15D8 F391
• Concatenate the salt again:
  908D C60A A5B9 24B3 096B 8897 D65A 3B5F 80FA 5DB62 A94 B831 22CD F4F8 FEAD 10D5 15D8 F391
• Convert to base64 encoding:
  kI3GCqW5JLMJa4iX1lo7X4D6XbYqlLgxIs30+P6tENUV2POR
• Use the base64-encoded value as the password_hash value in the request JSON.