Password Manager

mosquitto_passwd`

Synopsis

• mosquitto_passwd [ -H hash ] [ -c | -D ] passwordfile username

• mosquitto_passwd [ -H hash ] -b passwordfile username password

• mosquitto_passwd -U passwordfile

Description

mosquitto_passwd is a tool for managing password files for the mosquitto MQTT broker.

Usernames must not contain ":". Passwords are stored in a similar format to crypt.

Options

-b

Run in batch mode. This allows the password to be provided at the command line which can be convenient but should be used with care because the password will be visible on the command line and in command history.

Add a user to an existing password file, passing the password on the command line: mosquitto_passwd -b /etc/mosquitto/passwd ral z2Dr0BsvtZ

-c

Create a new password file. If the file already exists, it will be overwritten.

Add a user to a new password file: mosquitto_passwd -c /etc/mosquitto/passwd ral

-D

Delete the specified user from the password file.

mosquitto_passwd -D /etc/mosquitto/passwd ral

-H

Choose the hash to use. Can be one of sha512-pbkdf2 or sha512. Defaults to sha512-pbkdf2. The sha512 option is provided for creating password files for use with Eclipse Mosquitto 1.6 and earlier.

Add a user to an existing password file using the sha512 hash for Mosquitto 1.6 compatibility: mosquitto_passwd -H sha512 /etc/mosquitto/passwd ral

-U

This option can be used to upgrade/convert a password file with plain text passwords into one using hashed passwords. It will modify the specified file. It does not detect whether passwords are already hashed, so using it on a password file that already contains hashed passwords will generate new hashes based on the old hashes and render the password file unusable.

passwordfile

The password file to modify.

username

The username to add/update/delete.

password

The password to use when in batch mode.

Example: mosquitto_passwd -b -c <path> -D user1 -H sha512 - U <path> <path> user2 passwordexample

Update the password for a user in an existing password file: mosquitto_passwd /etc/mosquitto/passwd ral

Add a user to an existing password file: mosquitto_passwd /etc/mosquitto/passwd ral

Exit Status

mosquitto_sub returns zero on success, or non-zero on error. If the connection is refused by the broker at the MQTT level, then the exit code is the CONNACK reason code. If another error occurs, the exit code is a libmosquitto return value.

MQTT v3.1.1 CONNACK codes:

• 0 Success
• 1 Connection refused: Bad protocol version
• 2 Connection refused: Identifier rejected
• 3 Connection refused: Server unavailable
• 4 Connection refused: Bad username/password
• 5 Connection refused: Not authorized

MQTT v5 CONNACK codes:

• 0 Success

• 128 Unspecified error

• 129 Malformed packet

• 130 Protocol error

• 131 Implementation specific error

• 132 Unsupported protocol version

• 133 Client ID not valid

• 134 Bad username or password

• 135 Not authorized

• 136 Server unavailable

• 137 Server busy

• 138 Banned

• 139 Server shutting down

• 140 Bad authentication method

• 141 Keep alive timeout

• 142 Session taken over

• 143 Topic filter invalid

• 144 Topic name invalid

• 147 Receive maximum exceeded

• 148 Topic alias invalid

• 149 Packet too large

• 150 Message rate too high

• 151 Quota exceeded

• 152 Administrative action

• 153 Payload format invalid

• 154 Retain not supported

• 155 QoS not supported

• 156 Use another server

• 157 Server moved

• 158 Shared subscriptions not supported

• 159 Connection rate exceeded

• 160 Maximum connect time

• 161 Subscription IDs not supported

• 162 Wildcard subscriptions not supported

Examples

Add a user to a new password file:

mosquitto_passwd -c /etc/mosquitto/passwd ral

Delete a user from a password file:

mosquitto_passwd -D /etc/mosquitto/passwd ral

The Dynamic Security plugin offers a easy to use GUI to configure security measurements.

Read more about [Dynamic Security] (NEW_management-center.md#dynamic-security).

If you want more control over authentication of your users than is offered by a password file, then an authentication plugin may be suitable for you. The features offered depend on which plugin you use.

Configuring the plugin Configuring a plugin varies depending on the version of Mosquitto plugin interface the plugin was written for, either version 2.0 and up, or 1.6.x and earlier. For 1.6.x and below, use the auth_plugin option. These plugins are also supported by version 2.0:

listener 1883 auth_plugin <path to plugin>

Some plugins require extra configuration which will be described in their documentation. For 2.0 and up, use the plugin option:

listener 1883 plugin <path to plugin>

Read more about [Available plugins] (NEW_management-center.md#available-plugins).

Certificates

The highest security levels can be achieved using client certificates (x509).

When using certificate based encryption there are three options that affect authentication.

The first is require_certificate, which may be set to true or false. If false, the TLS component of the client will verify the server but there is no requirement for the client to provide anything for the server: authentication is limited to the MQTT built in username/password. If require_certificate is true, the client must provide a valid certificate in order to connect successfully.

In this case, the second and third options, use_identity_as_username and use_subject_as_username, become relevant. If set to true, use_identity_as_username causes the Common Name (CN) from the client certificate to be used instead of the MQTT username for access control purposes.

The password is not used because it is assumed that only authenticated clients have valid certificates. This means that any CA certificates you include in cafile or capath will be able to issue client certificates that are valid for connecting to your broker. If use_identity_as_username is false, the client must authenticate as normal (if required by password_file) through the MQTT options. The same principle applies for the use_subject_as_username option, but the entire certificate subject is used as the username instead of just the CN.

How to create client certificates:

Generate a private key and certificate signing request. Send the CSR to a commercial Certificate Authority with some money, and the CA sends you a certificate.

Generate a private key and own self signed certificate to act as a Certificate Authority, then generate a server private key and CSR and sign the server CSR with your CA private key to generate the server certificate (clients need the CA certificate, and this can be used for multiple servers).

Read more about Authorization: [Here] (NEW_publishing.md). And [here] (NEW_mosquitto-configuration.md#tls-support).

Explanation about Device Authentication.

When using pre-shared-key based encryption through the psk_hint and psk_file options, the client must provide a valid identity and key in order to connect to the broker before any MQTT communication takes place.

info

Digression: PSK

A pre-shared key (PSK) is a previously exchanged key for symmetric encryption. This allows data to be both encrypted and decrypted.

If use_identity_as_username is true, the PSK identity is used instead of the MQTT username for access control purposes. If use_identity_as_username is false, the client may still authenticate using the MQTT username/password if using the password_file option.

Both certificate and PSK based encryption are configured on a per-listener basis.

Authentication plugins can be created to augment the password_file, acl_file and psk_file options with e.g. SQL based lookups.

Read more about Certificates: [Here] (NEW_publishing.md). And [here] (NEW_mosquitto-configuration.md#tls-support).

It is possible to support multiple authentication schemes at once. A config could be created that had a listener for all of the different encryption options described above and hence a large number of ways of authenticating.