Skip to content

Commit

Permalink
[#185] rework to a v2/ structure
Browse files Browse the repository at this point in the history
  • Loading branch information
@bmarwell
bmarwell committed Jan 23, 2024
1 parent 2f5198a commit 45b0c5f
Show file tree
Hide file tree
Showing 4 changed files with 182 additions and 10 deletions.
17 changes: 7 additions & 10 deletions src/site/content/command-line-hasher.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
:jbake-type: page
:jbake-status: published
:jbake-tags: documentation, hashes, command-line, cli, hasher, tool
:shiro-hasv2: true
:idprefix:
:icons: font
:toc:
Expand Down Expand Up @@ -37,14 +38,12 @@ Once you have access to the jar, you can run the following command:
$ java -jar shiro-tools-hasher-${versions.latestRelease}-cli.jar
----

This will print all available options for standard (argon2, bcrypt) and less secure hashing scenarios.
This will print all available options for both standard (MD5, SHA1) and more complex password 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.
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
Expand All @@ -64,12 +63,11 @@ Password to hash:
Password to hash (confirm):
----

When this command executes, it will print out the securely-salted-iterated-and-hashed password.
For example:
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
$shiro1$SHA-256$500000$eWpVX2tGX7WCP2J+jMCNqw==$it/NRclMOHrfOvhAEFZ0mxIZRdbcfqIBdwdwdDXW2dM=
----

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:
Expand All @@ -78,11 +76,10 @@ Take this value and place it as the password in the user definition line (follow
----
[users]
...
user1 = $shiro2$argon2id$v=19$t=1,m=65536,p=4$H5z81Jpr4ntZr3MVtbOUBw$fJDgZCLZjMC6A2HhnSpxULMmvVdW3su+/GCU3YbxfFQ
user1 = $shiro1$SHA-256$500000$eWpVX2tGX7WCP2J+jMCNqw==$it/NRclMOHrfOvhAEFZ0mxIZRdbcfqIBdwdwdDXW2dM=
----

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:
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]
----
Expand Down
118 changes: 118 additions & 0 deletions src/site/content/v2/command-line-hasher.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
[#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
----
48 changes: 48 additions & 0 deletions src/site/templates/macros/versions.ftl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,51 @@
<#assign oldReleases = data.get('releases.yaml').oldReleases>

<#assign artifacts = data.get('artifacts.yaml').artifacts>

<#macro shirov2>
<#assign theDate = .now?date>
<div class="admonitionblock important">
<table>
<tbody>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
<div class="title">Shiro v2 alpha notice</div>
<div class="paragraph">
<p>As of ${theDate?iso_utc}, this version of Apache Shiro is in Alpha stage.</p>
</div>
</td>
</tr>
</tbody>
</table>
</div>
</#macro>

<#macro shirov1 sourcepage="" hasv2=false>
<#assign theDate = .now?date>
<div class="admonitionblock tip">
<table>
<tbody>
<tr>
<td class="icon">
<div class="title">Handy Hint</div>
</td>
<td class="content">
<div class="title">Shiro v1 version notice</div>
<div class="paragraph">
<p>As of ${theDate?iso_utc}, Shiro v1 will soon be superseded by v2.<p>
<#if (sourcepage)?? && (sourcepage)?is_string && (sourcepage) != "" && hasv2 == true>
<#assign target=sourcepage?keep_after_last("/") />
<p>
<a href="./v2/${target}">Read this page in the v2 documentation</a>.
</p>
</#if>
</div>
</td>
</tr>
</tbody>
</table>
</div>
</#macro>
9 changes: 9 additions & 0 deletions src/site/templates/page.ftl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,15 @@
</div>
</#if>

<#import "macros/versions.ftl" as versions>
<#if (content.uri)?contains("/v2/") || (content.uri)?starts_with("v2/")>
<@versions.shirov2 />
<#else>
<#-- this is a shiro v1 page -->
<#assign hasv2=((content["shiro-hasv2"])?? && (content["shiro-hasv2"]) == "true") />
<@versions.shirov1 (content.uri) hasv2 />
</#if>

<@content.body?interpret />

<hr />
Expand Down

0 comments on commit 45b0c5f

Please sign in to comment.