| [#CommandLineHasher-CommandLineHasher] |
| = Command Line Hasher |
| :jbake-date: 2010-03-18 00:00:00 |
| :jbake-type: page |
| :jbake-status: published |
| :jbake-tags: documentation, hashes, command-line, cli, hasher, tool |
| :idprefix: |
| :icons: font |
| :toc: |
| |
| Shiro 2.0.0 and later provides a command line program that can hash strings and resources (files, URLs, classpath entries) of almost any type. |
| To use it, you must have a Java Virtual Machine installed and the 'java' command must be accessible in your `$PATH` environment variable. |
| |
| [CAUTION] |
| ==== |
| Do not use the hashes provided in the link:../command-line-hasher.html[command line hasher v1.x] versions anymore! |
| They are outdated and all considered insecure! |
| ==== |
| |
| [#CommandLineHasher-Usage] |
| == Usage |
| |
| Ensure you have access to the `shiro-tools-hasher-${versions.latestRelease}-cli.jar` file. |
| You can either find this in a source build in the _buildroot_`/tools/hasher/target` directory or via download through Maven. |
| |
| [source,bash] |
| ---- |
| # Use the following to download from Maven Central into |
| # ~/.m2/repository/org/apache/shiro/tools/shiro-tools-hasher/${versions.latestRelease}/shiro-tools-hasher-${versions.latestRelease}-cli.jar |
| $ mvn dependency:get -DgroupId=org.apache.shiro.tools -DartifactId=shiro-tools-hasher -Dclassifier=cli -Dversion=${versions.latestRelease} |
| |
| ---- |
| |
| Once you have access to the jar, you can run the following command: |
| |
| [source,bash] |
| ---- |
| $ java -jar shiro-tools-hasher-${versions.latestRelease}-cli.jar |
| ---- |
| |
| This will print all available options for standard (argon2, bcrypt) and less secure hashing scenarios. |
| |
| [#CommandLineHasher-CommonScenarios] |
| == Common Scenarios |
| |
| Please read the printed instructions for the above command. |
| It will provide an exhaustive list of instructions which will help you use the hasher depending on your needs. |
| However, we've provided some quick reference usages/scenarios below for convenience. |
| |
| [#CommandLineHasher-shiro.iniUserPasswords] |
| === `shiro.ini` User Passwords |
| |
| It is best to keep user passwords in the `shiro.ini` `[users]` section secure. To add a new user account line, use the above command with the `**-p**` (or `--password`) option: |
| |
| [source,bash] |
| ---- |
| $ java -jar shiro-tools-hasher-${versions.latestRelease}-cli.jar -p |
| ---- |
| |
| It will then ask you to enter the password and then confirm it: |
| |
| [source,bash] |
| ---- |
| Password to hash: |
| Password to hash (confirm): |
| ---- |
| |
| When this command executes, it will print out the securely-salted-iterated-and-hashed password. |
| For example: |
| |
| [source,bash] |
| ---- |
| [INFO ] $shiro2$argon2id$v=19$t=1,m=65536,p=4$H5z81Jpr4ntZr3MVtbOUBw$fJDgZCLZjMC6A2HhnSpxULMmvVdW3su+/GCU3YbxfFQ |
| ---- |
| |
| Take this value and place it as the password in the user definition line (followed by any optional roles) as defined in the link:/configuration.html#Configuration-INIConfiguration-Sections-users[INI Users Configuration] documentation. For example: |
| |
| [source,ini] |
| ---- |
| [users] |
| ... |
| user1 = $shiro2$argon2id$v=19$t=1,m=65536,p=4$H5z81Jpr4ntZr3MVtbOUBw$fJDgZCLZjMC6A2HhnSpxULMmvVdW3su+/GCU3YbxfFQ |
| ---- |
| |
| You will also need to ensure that the implicit `iniRealm` uses a `CredentialsMatcher` that knows how to perform secure hashed password comparisons. |
| So configure this in the `[main]` section as well: |
| |
| [source,ini] |
| ---- |
| [main] |
| ... |
| passwordMatcher = org.apache.shiro.authc.credential.PasswordMatcher |
| iniRealm.credentialsMatcher = $passwordMatcher |
| ... |
| ---- |
| |
| [#CommandLineHasher-MD5checksum] |
| === MD5 checksum |
| |
| Although you can perform any hash with any algorithm supported on the JVM, the default hashing algorithm is MD5, common for file checksums. Just use the `**-r**` (or `--resource`) option to indicate the following value is a resource location (and not text you wish hashed): |
| |
| [source,bash] |
| ---- |
| $ java -jar shiro-tools-hasher-X.X.X-cli.jar -r RESOURCE_PATH |
| ---- |
| |
| By default `RESOURCE_PATH` is expected to be a file path, but you may specify classpath or URL resources by using the `classpath:` or `url:` prefix respectively. |
| |
| Some examples: |
| |
| [source,bash] |
| ---- |
| <command> -r fileInCurrentDirectory.txt |
| <command> -r ../../relativePathFile.xml |
| <command> -r ~/documents/myfile.pdf |
| <command> -r /usr/local/logs/absolutePathFile.log |
| <command> -r url:http://foo.com/page.html <command> -r classpath:/WEB-INF/lib/something.jar |
| ---- |