ESE Helper Tool

For your convenience, the HiveMQ Enterprise Security Extension provides a small command-line tool (CLI): the ESE Helper. This tool is included in the ESE zip file that you downloaded from the HiveMQ marketplace.

For the purpose of this documentation, a CLI tool has the following structure:

hivemq-ese-helper command sub-command sub-sub-command ... -o value1 --option=value2 argument1 argument2 ...

  • hivemq-ese-helper: The name of the tool. The name is always required.

  • command: The functionality group, or the desired effect. The command is always required. For example, db for database tooling and hash for hashing.

  • sub-command sub-sub-command …​: The actual desired effect. The sub-command is almost always required. For example, create to create something. Additional levels of sub-commands are possible.

  • -o value1: An option in the short form with its value. This entry is purely optional and changes the computation in some way. A space between the option flag -o and the value value1 signals that this value belongs to that option. Some options do not require a value.

  • --option=value2: An option in the long form. This entry is purely optional and changes the computation in some way. An = between the option flag --option and the value value2 signals that this value belongs to that option. Some options do not require a value and therefore do not need an =.

  • argument1 argument2 …​: The arguments of the (sub-)command. The entries define the basic input that is necessary to compute the desired result. Arguments are usually required and are separated by a space.

The ESE Helper is distributed as a precompiled and packaged .jar file with all necessary dependencies (except a JVM) that can be used OS agnostic and as native binaries for GNU/Linux and Darwin (Mac OS X).

Position of the ESE Helper in the extension folder
hivemq-enterprise-security-extension $> tree -L 1
.
├── README.html
├── README.txt
├── drivers
├── lib
├── conf
├── hivemq-enterprise-security-extension-1.0.0.jar
├── helper (1)
│   ├── darwin
│   │   └── hivemq-ese-helper (2)
│   ├── jvm
│   │   └── hivemq-ese-helper.jar (3)
│   └── linux
│       └── hivemq-ese-helper (4)
├── hivemq-extension.xml
├── third-party-licenses
└── scripts
1 The ESE Helper folder
2 The binary executable for Darwin (Mac OS X)
3 The .jar file (requires at least java 8)
4 The binary executable for GNU/Linux

Note, when you use the .jar version, you must use the full invocation command java -jar hivemq-ese-helper.jar …​ (not ./hivemq-ese-helper …​).

Use the two main features of the ESE Helper to simplify administration of the HiveMQ Enterprise Security Extension:

  • Hash passwords according to the defined cryptography with the hash create command

  • Create SQL INSERT statements:

    • for the users table that SQL authentication managers use with the db create mqtt-client-user command

    • for the cc_users table that SQL authentication managers use with the db create control-center-user command


Hash Passwords

The base command for hashing passwords is hash create.

Open a command prompt and navigate to the Enterprise Security Extension directory.

The basic usage of hash create is with a plain-text password as argument. This outputs a Base64 encoded password hash that is created with the default algorithm (SHA512), the default iterations (100), and no salt.

ESE Helper hash create with argument
hivemq-enterprise-security-extension $> ./hivemq-ese-helper hash create my_secret_password

99WDcYNxhgkwutXPjNcYGrXB77WQpf/2cFEbkjK7cHHpI84+BzSWzapyL78QNe/loiRqnK3NHlHviY9CqxAvlg

To display an overview of ESE Helper syntax and functionality, type ./hivemq-ese-helper hash create.

ESE Helper hash create help output
hivemq-enterprise-security-extension $> ./hivemq-ese-helper hash create

Usage: ese-helper hash create [-p[=<passwordOption>]] [-a=<algorithm>]
                              [-i=<iterations>] [-s=<salt>] [<password>]
Hashes a password and prints the hash to STDOUT.
      [<password>]    The password. This OR the -p/--password option is required.
  -a, --algorithm=<algorithm>
                      Valid values: PLAIN, MD5, SHA512, BCRYPT, PKCS5S2. Default value:
                        SHA512.
  -i, --iterations=<iterations>
                      Number of iterations the algorithm uses. Default value:
                        100.
  -p, --password[=<passwordOption>]
                      The password. Use of this option without a value enables
                        interactive mode. This OR password argument is required.
  -s, --salt=<salt>   The salt that is used, a Base64 encoded string (if necessary, padded).

Interactive mode

If desired, you can omit the argument and use the -p/--password option without a value. This option starts the interactive mode of the command and prompts you to insert a password. The advantage of the interactive mode is that the plain-text password is not recorded in the history of your shell.

ESE Helper hash create interactive mode
hivemq-enterprise-security-extension $> ./hivemq-ese-helper hash create -p

Enter a value for --password (The password. Use of this option without a value enables interactive mode. This OR password argument is required.): my_secret_password (1)

99WDcYNxhgkwutXPjNcYGrXB77WQpf/2cFEbkjK7cHHpI84+BzSWzapyL78QNe/loiRqnK3NHlHviY9CqxAvlg==
1 The string my_secret_password is hidden.

If the -p/--password option is used, an additional argument is ignored.

All options

The full configuration options of hash create are:

Option Alternative Default Description

-a

--algorithm=

SHA512

The one-way function that is used. MD5, SHA512, BCRYPT, and PKCS5S2 are possible.

-i

--iterations=

100

The computational difficulty factor of the one-way function. For MD5, SHA512 and PKCS5S2 every positive integer is possible, for BCRYPT only values from 4 to 31 can be used.

-p

--password[=]

The password to be hashed. If you use the option without a value, interactive mode is enabled.

-s

--salt=

The salt that is used. The salt must be a Base64 encoded string (if necessary, padded).


Interact with Databases

The db command is for interacting with SQL databases.

db create

The sub-command create is for adding new information to your database.

Create MQTT Client Users

The command to create mqtt client users is db create mqtt-client-user.

Open a command prompt and navigate to the Enterprise Security Extension directory.

The basic usage of db create mqtt-client-user is with a plain-text username followed by a plain-text password as argument. This option outputs a full SQL INSERT statement that is created with the default algorithm (SHA512), the default iterations (100), and a generated random 16 Byte salt.

ESE Helper db create-insert-statement with arguments
hivemq-enterprise-security-extension $> ./hivemq-ese-helper db create mqtt-client-user my_user my_secret_password

insert into users (username, password, password_iterations, password_salt, algorithm) values ('my_user', 'bSdf47hY52qPBShvJE+mgcGtuQyveNdGWtO11BSm6l6Bp6cicW3ulb9GYaVTxCLyuIbzOgb5VM6KysxXhNgGrA==', 100, 'IThEd9r1+ALx/d++tdcOmw==', 'SHA512');

To display an overview of the ESE Helper syntax and functionality, type ./hivemq-ese-helper db create mqtt-client-user.

ESE Helper db create-insert-statement help output
hivemq-enterprise-security-extension $> ./hivemq-ese-helper db create mqtt-client-user

Usage: ese-helper db create mqtt-client-user [-p[=<passwordOption>]]
                                             [-a=<algorithm>] [-f=<csv>]
                                             [-i=<iterations>] [-s=<salt>]
                                             [<username>] [<password>]
Creates a user INSERT SQL statement and prints the statement to STDOUT.
      [<username>]    The username. This OR -f/--file option is required.
      [<password>]    The password. This OR -f/--file option OR -p/--password
                        option is required.
  -a, --algorithm=<algorithm>
                      Valid values: PLAIN, MD5, SHA512, BCRYPT, PKCS5S2. Default value:
                        SHA512.
  -f, --file=<csv>    A CSV file that provides usernames and passwords. The format is:
                        "username,password\r\n". This OR -p/--password option
                        AND username argument OR username argument AND password
                        argument is required.
  -i, --iterations=<iterations>
                      Number of used iterations in the algorithm. Default value
                        100.
  -p, --password[=<passwordOption>]
                      The password. Use of this option without a value enables
                        interactive mode. This OR -f/--file option OR password
                        argument is required.
  -s, --salt=<salt>   The used salt, encoded Base64 with padding.

Interactive mode

If desired, you can omit the second argument and use the -p/--password option without a value. Use of the -p/--password option without a value starts the interactive mode of the command and prompts you to insert a password. The advantage of the interactive mode is that the plain-text password is not recorded in the history of your shell.

ESE Helper db create mqtt-client-user interactive mode
hivemq-enterprise-security-extension $> ./hivemq-ese-helper db create mqtt-client-user my_user -p

Enter a value for --password (The password. Use of this option without a value enables interactive mode. This OR -f/--file option OR password argument is required.): my_secret_password (1)

insert into users (username, password, password_iterations, password_salt, algorithm) values ('my_user', 'oMKRQuYaeiHYBDO+eWH6jwl9pQQplmgrvG15JySaVDqKg+6nBdesXbaEvxLW3ajsEMZJRIZBGZxVgZFkjl8qxg==', 100, 'ooh/GebePcDJArvDyqucoQ==', 'SHA512');
1 The string my_secret_password is hidden.

If you use the -p/--password option, an additional password argument is ignored.

Using a CSV file

Instead of the username and password arguments, db create mqtt-client-user can be used with the -f/--file option and the path to a comma separated value (CSV) file.

The CSV file needs to be UTF8 encoded and each line must have the following format: <username>,<password>\r\n, where \r is a Carriage Return and \n is a Line Feed character.

Example of the username password CSV file
username1,password1
username2,password2
username3,password3

If you use the db create mqtt-client-user command with the -f/--file option and the example above as value, the following output is the result:

ESE Helper db create mqtt-client-user with CSV file
hivemq-enterprise-security-extension $> ./hivemq-ese-helper db create mqtt-client-user -f credentials.csv

insert into users (username, password, password_iterations, password_salt, algorithm) values ('username1', 'x0a60NOq+IO4DXOESyCSWyjZovDFKT+CvBn+FacpVlXnrHsd2h4iyB9R22E7uPfV+sA21P4iE7fg2kMibHwfjw==', 100, 'NYK6GOErNCRsWyNY3/L6qg==', 'SHA512');
insert into users (username, password, password_iterations, password_salt, algorithm) values ('username2', 'p53/YJdYWZmp1Onp32MBOgZ0xl42EXJlo8uNVVMQ0J+eJEqhKmKfS+nag8wgWE8RlzPjltGp4J8CtfIi5RbKSA==', 100, 'D02AHhrjjiMUyqxV3UKpMA==', 'SHA512');
insert into users (username, password, password_iterations, password_salt, algorithm) values ('username3', 'y/hENzj3PI0E7Q15T/0Vp+AmTn3VRmLyJ6+1lDrLf35di7p7gPPPwK3i8gGrmfp9zqbmPyXs+U63lyD2awt/lw==', 100, '9SemwAk/JgmUVPyXIKSDxg==', 'SHA512');
If a salt is specified when the -f/--file option is used, all INSERT statements that are generated use that same specified salt.

When the -f/--file option is used, all arguments to db create mqtt-client-user and a possible -p/--password option are ignored.

All options

The full configuration options of db create mqtt-client-user are:

Option Alternative Default Description

-a

--algorithm=

SHA512

The one-way function that is used. PLAIN, MD5, SHA512, BCRYPT, and PKCS5S2 are possible.

-i

--iterations=

100

The computational difficulty factor of the one-way function. For MD5, SHA512 and PKCS5S2 every positive integer is possible, for BCRYPT only values from 4 up to and including 31 can be used.

-p

--password[=]

The password to be hashed. If you use this option without a value, interactive mode is enabled.

-s

--salt=

The salt that is used. The salt must be a Base64 encoded string (if necessary, padded).

-f

--file=

Use a CSV file, containing usernames and passwords as input.

Create Control Center Users

The command to create control center users is db create control-center-user.

Open a command prompt and navigate to the Enterprise Security Extension directory.

The basic usage of db create control-center-user is with a plain-text username followed by a plain-text password as argument. This option outputs a full SQL INSERT statement that is created with the default algorithm (SHA512), the default iterations (100), and a generated random 16 Byte salt.

ESE Helper db create-insert-statement with arguments
hivemq-enterprise-security-extension $> ./hivemq-ese-helper db create control-center-user my_user my_secret_password

insert into cc_users (username, password, password_iterations, password_salt, algorithm) values ('my_user', 'bSdf47hY52qPBShvJE+mgcGtuQyveNdGWtO11BSm6l6Bp6cicW3ulb9GYaVTxCLyuIbzOgb5VM6KysxXhNgGrA==', 100, 'IThEd9r1+ALx/d++tdcOmw==', 'SHA512');

To display an overview of the ESE Helper syntax and functionality, type ./hivemq-ese-helper db create control-center-user.

ESE Helper db create-insert-statement help output
hivemq-enterprise-security-extension $> ./hivemq-ese-helper db create control-center-user

Usage: ese-helper db create control-center-user [-p[=<passwordOption>]]
                                             [-a=<algorithm>] [-f=<csv>]
                                             [-i=<iterations>] [-s=<salt>]
                                             [<username>] [<password>]
Creates a user INSERT SQL statement and prints the statement to STDOUT.
      [<username>]    The username. This OR -f/--file option is required.
      [<password>]    The password. This OR -f/--file option OR -p/--password
                        option is required.
  -a, --algorithm=<algorithm>
                      Valid values: PLAIN, MD5, SHA512, BCRYPT, PKCS5S2. Default value:
                        SHA512.
  -f, --file=<csv>    A CSV file that provides usernames and passwords. The format is:
                        "username,password\r\n". This OR -p/--password option
                        AND username argument OR username argument AND password
                        argument is required.
  -i, --iterations=<iterations>
                      Number of used iterations in the algorithm. Default value
                        100.
  -p, --password[=<passwordOption>]
                      The password. Use of this option without a value enables
                        interactive mode. This OR -f/--file option OR password
                        argument is required.
  -s, --salt=<salt>   The used salt, encoded Base64 with padding.

Interactive mode

If desired, you can omit the second argument and use the -p/--password option without a value. Use of the -p/--password option without a value starts the interactive mode of the command and prompts you to insert a password. The advantage of the interactive mode is that the plain-text password is not recorded in the history of your shell.

ESE Helper db create control-center-user interactive mode
hivemq-enterprise-security-extension $> ./hivemq-ese-helper db create control-center-user my_user -p

Enter a value for --password (The password. Use of this option without a value enables interactive mode. This OR -f/--file option OR password argument is required.): my_secret_password (1)

insert into cc_users (username, password, password_iterations, password_salt, algorithm) values ('my_user', 'oMKRQuYaeiHYBDO+eWH6jwl9pQQplmgrvG15JySaVDqKg+6nBdesXbaEvxLW3ajsEMZJRIZBGZxVgZFkjl8qxg==', 100, 'ooh/GebePcDJArvDyqucoQ==', 'SHA512');
1 The string my_secret_password is hidden.

If the -p/--password option an additional password argument is ignored.

Using a CSV file

Instead of the username and password arguments, db create control-center-user can be used with the -f/--file option and the path to a comma separated value (CSV) file.

The CSV file needs to be UTF8 encoded and each line must adhere to the following format: <username>,<password>\r\n, where \r is a Carriage Return and \n is a Line Feed character.

Example of the username password CSV file
username1,password1
username2,password2
username3,password3

If the db create control-center-user command is used with the -f/--file option and the example above as value, the following output is the result:

ESE Helper db create control-center-user with CSV file
hivemq-enterprise-security-extension $> ./hivemq-ese-helper db create control-center-user -f credentials.csv

insert into cc_users (username, password, password_iterations, password_salt, algorithm) values ('username1', 'x0a60NOq+IO4DXOESyCSWyjZovDFKT+CvBn+FacpVlXnrHsd2h4iyB9R22E7uPfV+sA21P4iE7fg2kMibHwfjw==', 100, 'NYK6GOErNCRsWyNY3/L6qg==', 'SHA512');
insert into cc_users (username, password, password_iterations, password_salt, algorithm) values ('username2', 'p53/YJdYWZmp1Onp32MBOgZ0xl42EXJlo8uNVVMQ0J+eJEqhKmKfS+nag8wgWE8RlzPjltGp4J8CtfIi5RbKSA==', 100, 'D02AHhrjjiMUyqxV3UKpMA==', 'SHA512');
insert into cc_users (username, password, password_iterations, password_salt, algorithm) values ('username3', 'y/hENzj3PI0E7Q15T/0Vp+AmTn3VRmLyJ6+1lDrLf35di7p7gPPPwK3i8gGrmfp9zqbmPyXs+U63lyD2awt/lw==', 100, '9SemwAk/JgmUVPyXIKSDxg==', 'SHA512');
If a salt is specified when the -f/--file option is used, all INSERT statements that are generated use that same specified salt.

When the -f/--file option is used, all arguments to db create control-center-user and a possible -p/--password option are ignored.

All options

The full configuration options of db create control-center-user are:

Option Alternative Default Description

-a

--algorithm=

SHA512

The one-way function that is used. PLAIN, MD5, SHA512, BCRYPT, and PKCS5S2 are possible.

-i

--iterations=

100

The computational difficulty factor of the one-way function. For MD5, SHA512 and PKCS5S2 every positive integer is possible, for BCRYPT only values from 4 up to and including 31 can be used.

-p

--password[=]

The password to be hashed. If you use the option without a value, interactive mode is enabled.

-s

--salt=

The salt that is used. The salt must be a Base64 encoded string (if necessary, padded).

-f

--file=

Use a CSV file, containing usernames and passwords as input.

Create Rest API Users

The command to create Rest API users is db create rest-api-user.

Open a command prompt and navigate to the Enterprise Security Extension directory.

The basic usage of db create rest-api-user is with a plain-text username followed by a plain-text password as argument. This option outputs a full SQL INSERT statement that is created with the default algorithm (SHA512), the default iterations (100), and a generated random 16 Byte salt.

ESE Helper db create-insert-statement with arguments
hivemq-enterprise-security-extension $> ./hivemq-ese-helper db create rest-api-user my_user my_secret_password

insert into rest_api_users (username, password, password_iterations, password_salt, algorithm) values ('my_user', 'bSdf47hY52qPBShvJE+mgcGtuQyveNdGWtO11BSm6l6Bp6cicW3ulb9GYaVTxCLyuIbzOgb5VM6KysxXhNgGrA==', 100, 'IThEd9r1+ALx/d++tdcOmw==', 'SHA512');

To display an overview of the ESE Helper syntax and functionality, type ./hivemq-ese-helper db create rest-api-user.

ESE Helper db create-insert-statement help output
hivemq-enterprise-security-extension $> ./hivemq-ese-helper db create rest-api-user

Usage: ese-helper db create rest-api-user [-p[=<passwordOption>]]
                                             [-a=<algorithm>] [-f=<csv>]
                                             [-i=<iterations>] [-s=<salt>]
                                             [<username>] [<password>]
Creates a user INSERT SQL statement and prints the statement to STDOUT.
      [<username>]    The username. This OR -f/--file option is required.
      [<password>]    The password. This OR -f/--file option OR -p/--password
                        option is required.
  -a, --algorithm=<algorithm>
                      Valid values: PLAIN, MD5, SHA512, BCRYPT, PKCS5S2. Default value:
                        SHA512.
  -f, --file=<csv>    A CSV file that provides usernames and passwords. The format is:
                        "username,password\r\n". This OR -p/--password option
                        AND username argument OR username argument AND password
                        argument is required.
  -i, --iterations=<iterations>
                      Number of used iterations in the algorithm. Default value
                        100.
  -p, --password[=<passwordOption>]
                      The password. Use of this option without a value enables
                        interactive mode. This OR -f/--file option OR password
                        argument is required.
  -s, --salt=<salt>   The used salt, encoded Base64 with padding.

Interactive mode

If desired, you can omit the second argument and use the -p/--password option without a value. Use of the -p/--password option without a value starts the interactive mode of the command and prompts you to insert a password. The advantage of the interactive mode is that the plain-text password is not recorded in the history of your shell.

ESE Helper db create rest-api-user interactive mode
hivemq-enterprise-security-extension $> ./hivemq-ese-helper db create rest-api-user my_user -p

Enter a value for --password (The password. Use of this option without a value enables interactive mode. This OR -f/--file option OR password argument is required.): my_secret_password (1)

insert into rest_api_users (username, password, password_iterations, password_salt, algorithm) values ('my_user', 'oMKRQuYaeiHYBDO+eWH6jwl9pQQplmgrvG15JySaVDqKg+6nBdesXbaEvxLW3ajsEMZJRIZBGZxVgZFkjl8qxg==', 100, 'ooh/GebePcDJArvDyqucoQ==', 'SHA512');
1 The string my_secret_password is hidden.

When the -p/--password option is used, additional password arguments are ignored.

Using a CSV file

Instead of the username and password arguments, db create rest-api-user can be used with the -f/--file option and the path to a comma separated value (CSV) file.

The CSV file needs to be UTF8 encoded and each line must adhere to the following format: <username>,<password>\r\n, where \r is a Carriage Return and \n is a Line Feed character.

Example of the username password CSV file
username1,password1
username2,password2
username3,password3

If the db create rest-api-user command is used with the -f/--file option and the example above as value, the following output is the result:

ESE Helper db create rest-api-user with CSV file
hivemq-enterprise-security-extension $> ./hivemq-ese-helper db create rest-api-user -f credentials.csv

insert into rest_api_users (username, password, password_iterations, password_salt, algorithm) values ('username1', 'x0a60NOq+IO4DXOESyCSWyjZovDFKT+CvBn+FacpVlXnrHsd2h4iyB9R22E7uPfV+sA21P4iE7fg2kMibHwfjw==', 100, 'NYK6GOErNCRsWyNY3/L6qg==', 'SHA512');
insert into rest_api_users (username, password, password_iterations, password_salt, algorithm) values ('username2', 'p53/YJdYWZmp1Onp32MBOgZ0xl42EXJlo8uNVVMQ0J+eJEqhKmKfS+nag8wgWE8RlzPjltGp4J8CtfIi5RbKSA==', 100, 'D02AHhrjjiMUyqxV3UKpMA==', 'SHA512');
insert into rest_api_users (username, password, password_iterations, password_salt, algorithm) values ('username3', 'y/hENzj3PI0E7Q15T/0Vp+AmTn3VRmLyJ6+1lDrLf35di7p7gPPPwK3i8gGrmfp9zqbmPyXs+U63lyD2awt/lw==', 100, '9SemwAk/JgmUVPyXIKSDxg==', 'SHA512');
If a salt is specified when the -f/--file option is used, all INSERT statements that are generated use that same specified salt.

When the -f/--file option is used, all arguments to db create rest-api-user and a possible -p/--password option are ignored.

All options

The full configuration options of db create rest-api-user are:

Option Alternative Default Description

-a

--algorithm=

SHA512

The one-way function that is used. PLAIN, MD5, SHA512, BCRYPT, and PKCS5S2 are possible.

-i

--iterations=

100

The computational difficulty factor of the one-way function. For MD5, SHA512 and PKCS5S2 every positive integer is possible, for BCRYPT only values from 4 up to and including 31 can be used.

-p

--password[=]

The password to be hashed. If you use the option without a value, interactive mode is enabled.

-s

--salt=

The salt that is used. The salt must be a Base64 encoded string (if necessary, padded).

-f

--file=

Use a CSV file, containing usernames and passwords as input.

db create-insert-statement

The command db create-insert-statement is deprecated, use db create mqtt-client-user instead.

The command to create SQL INSERT statements is db create-insert-statement.

Open a command prompt and navigate to the Enterprise Security Extension directory.

The basic usage of db create-insert-statement is with a plain-text username followed by a plain-text password as argument. This option outputs a full SQL INSERT statement that is created with the default algorithm (SHA512), the default iterations (100), and a generated random 16 Byte salt.

ESE Helper db create-insert-statement with arguments
hivemq-enterprise-security-extension $> ./hivemq-ese-helper db create-insert-statement my_user my_secret_password

insert into users (username, password, password_iterations, password_salt, algorithm) values ('my_user', 'bSdf47hY52qPBShvJE+mgcGtuQyveNdGWtO11BSm6l6Bp6cicW3ulb9GYaVTxCLyuIbzOgb5VM6KysxXhNgGrA==', 100, 'IThEd9r1+ALx/d++tdcOmw==', 'SHA512');
To display an overview of the ESE Helper syntax and functionality, type `./hivemq-ese-helper db create-insert-statement`.
ESE Helper db create-insert-statement help output
hivemq-enterprise-security-extension $> ./hivemq-ese-helper db create-insert-statement

Usage: ese-helper db create-insert-statement [-p[=<passwordOption>]]
                                             [-a=<algorithm>] [-f=<csv>]
                                             [-i=<iterations>] [-s=<salt>]
                                             [<username>] [<password>]
Creates a user INSERT SQL statement and prints the statement to STDOUT.
      [<username>]    The username. This OR -f/--file option is required.
      [<password>]    The password. This OR -f/--file option OR -p/--password
                        option is required.
  -a, --algorithm=<algorithm>
                      Valid values: PLAIN, MD5, SHA512, BCRYPT, PKCS5S2. Default value:
                        SHA512.
  -f, --file=<csv>    A CSV file that provides usernames and passwords. The format is:
                        "username,password\r\n". This OR -p/--password option
                        AND username argument OR username argument AND password
                        argument is required.
  -i, --iterations=<iterations>
                      Number of used iterations in the algorithm. Default value
                        100.
  -p, --password[=<passwordOption>]
                      The password. Use of this option without a value enables
                        interactive mode. This OR -f/--file option OR password
                        argument is required.
  -s, --salt=<salt>   The used salt, encoded Base64 with padding.

Interactive mode

If desired, you can omit the second argument and use the -p/--password option without a value. This option starts the interactive mode of the command and prompts you to insert a password. The advantage of the interactive mode is that the plain-text password is not recorded in the history of your shell.

ESE Helper db create-insert-statement interactive mode
hivemq-enterprise-security-extension $> ./hivemq-ese-helper db create-insert-statement my_user -p

Enter value for --password (The password. Use of this option without a value enables interactive mode. This OR -f/--file option OR password argument is required.): my_secret_password (1)

insert into users (username, password, password_iterations, password_salt, algorithm) values ('my_user', 'oMKRQuYaeiHYBDO+eWH6jwl9pQQplmgrvG15JySaVDqKg+6nBdesXbaEvxLW3ajsEMZJRIZBGZxVgZFkjl8qxg==', 100, 'ooh/GebePcDJArvDyqucoQ==', 'SHA512');
1 The string my_secret_password is hidden.

When the -p/--password option is used, additional password arguments are ignored.

Using a CSV file

Instead of the username and password arguments, db create-insert-statement can be used with the -f/--file option and the path to a comma separated value (CSV) file.

The CSV file needs to be UTF8 encoded and each line must adhere to the following format: <username>,<password>\r\n, where \r is a Carriage Return and \n is a Line Feed character.

Example of the username password CSV file
username1,password1
username2,password2
username3,password3

If the db create-insert-statement command is used with the -f/--file option and the example above as value, a single SQL command that inserts all data is printed out:

ESE Helper db create-insert-statement with CSV file
hivemq-enterprise-security-extension $> ./hivemq-ese-helper db create-insert-statement -f credentials.csv

insert into users (username, password, password_iterations, password_salt, algorithm)
	('username1', 'rvURL6ceLwqR8Sz8/7Xju4Q6ZvbIMj/Lc0HFhkzpI3pwwhsp0mDmHD9mp6CxWgISK2V8wRLKXP3bt7T68a4daQ==', 100, 'Ye7/YmouWO1Qqb+kJ8Udow==', 'SHA512'),
	('username2', 'wu77tIzRhg6Kcd+PpDNXtDvdNGY5URIUTHCfASHDk8yALjoM4WtSnK2yZOEb5csqf7msma+wArHlaFiARbtmCg==', 100, 'Uq+B5/9yN1fcRUUGe7syrA==', 'SHA512'),
	('username3', '4IvRT8Oi+L3mFpA4Jme+xsSAaOg5TPUdaziOC4UKcEoXGsTI6magQdMyXvf/Jef81+fc6/1FzX+EwaNGsxta+A==', 100, '9SWtpW3T9WTQvEeqElDr9g==', 'SHA512');
If a salt is specified when the -f/--file option is used, all INSERT statements that are generated use that same specified salt.

When the -f/--file option is used, all arguments to db create-insert-statement and a possible -p/--password option are ignored.

All options

The full configuration options of db create-insert-statement are:

Option Alternative Default Description

-a

--algorithm=

SHA512

The one-way function that is used. MD5, SHA512, BCRYPT, and PKCS5S2 are possible.

-i

--iterations=

100

The computational difficulty factor of the one-way function. For MD5, SHA512 and PKCS5S2 every positive integer is possible, for BCRYPT only values from 4 up to and including 31 can be used.

-p

--password[=]

The password to be hashed. If you use the option without a value, interactive mode is enabled.

-s

--salt=

The salt that is used. The salt must be a Base64 encoded string (if necessary, padded).

-f

--file=

Use a CSV file, containing usernames and passwords as input.