From 2f5198a9acedcc655ce534e1f93176d85bf61f00 Mon Sep 17 00:00:00 2001 From: Benjamin Marwell Date: Sun, 23 Jul 2023 21:20:16 +0200 Subject: [PATCH 1/2] [#185] update documentation on shiro2 --- src/site/content/command-line-hasher.adoc | 16 ++++++---- src/site/content/configuration.adoc | 35 +++++++++------------ src/site/content/cryptography-features.adoc | 8 +++-- 3 files changed, 30 insertions(+), 29 deletions(-) diff --git a/src/site/content/command-line-hasher.adoc b/src/site/content/command-line-hasher.adoc index 22193bb99d..feb6a8a12f 100644 --- a/src/site/content/command-line-hasher.adoc +++ b/src/site/content/command-line-hasher.adoc @@ -37,12 +37,14 @@ 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 both standard (MD5, SHA1) and more complex password hashing scenarios. +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. +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 @@ -62,11 +64,12 @@ 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] ---- -$shiro1$SHA-256$500000$eWpVX2tGX7WCP2J+jMCNqw==$it/NRclMOHrfOvhAEFZ0mxIZRdbcfqIBdwdwdDXW2dM= +[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: @@ -75,10 +78,11 @@ Take this value and place it as the password in the user definition line (follow ---- [users] ... -user1 = $shiro1$SHA-256$500000$eWpVX2tGX7WCP2J+jMCNqw==$it/NRclMOHrfOvhAEFZ0mxIZRdbcfqIBdwdwdDXW2dM= +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: +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] ---- diff --git a/src/site/content/configuration.adoc b/src/site/content/configuration.adoc index 064547f88d..89b4ec3350 100644 --- a/src/site/content/configuration.adoc +++ b/src/site/content/configuration.adoc @@ -439,40 +439,33 @@ Each line in the [users] section must conform to the following format: [#Configuration-INIConfiguration-Sections-users-EncryptingPasswords] ===== Encrypting Passwords -If you don't want the [users] section passwords to be in plain-text, you can encrypt them using your favorite hash algorithm (MD5, Sha1, Sha256, etc.) however you like and use the resulting string as the password value. By default, the password string is expected to be Hex encoded, but can be configured to be Base64 encoded instead (see below). +Since Shiro 2.0, the `[users]` section cannot contain plain-text passwords. +You can encrypt them using https://en.wikipedia.org/wiki/Key_derivation_function[key derivation functions]. +Shiro provides implementations for bcrypt and argon2. +If unsure, use argon2 derived passwords. + +The algorithms from Shiro 1 (e.g. md5, SHA1, SHA256, etc.) are long deemed insecure and not supported anymore. +There is neither a direct migration path nor backward compatibility. + [NOTE] ==== .Easy Secure Passwords -To save time and use best-practices, you might want to use Shiro's link:command-line-hasher.html[Command Line Hasher], which will hash passwords as well as any other type of resource. It is especially convenient for encrypting INI `[users]` passwords. +To save time and use best-practices, you might want to use Shiro's link:command-line-hasher.html[Command Line Hasher], which will apply one of the secure KDFs to a given password as well as any other type of resources. +It is especially convenient for encrypting INI `[users]` passwords. ==== -Once you've specified the hashed text password values, you have to tell Shiro that these are encrypted. You do that by configuring the implicitly created `iniRealm` in the [main] section to use an appropriate `CredentialsMatcher` implementation corresponding to the hash algorithm you've specified: +Once you've specified the derived text password values, you have to tell Shiro that these are encrypted. +You do that by configuring the implicitly created `iniRealm` in the [main] section to use an appropriate `CredentialsMatcher` implementation corresponding to the hash algorithm you've specified: [source,ini] ---- [main] -... -sha256Matcher = org.apache.shiro.authc.credential.Sha256CredentialsMatcher -... -iniRealm.credentialsMatcher = $sha256Matcher -... +# Shiro2CryptFormat [users] # user1 = sha256-hashed-hex-encoded password, role1, role2, ... -user1 = 2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b, role1, role2, ... ----- - -You can configure any properties on the `CredentialsMatcher` like any other object to reflect your hashing strategy, for example, to specify if salting is used or how many hash iterations to execute. See the link:static/current/apidocs/org/apache/shiro/authc/credential/HashedCredentialsMatcher.html[`org.apache.shiro.authc.credential.HashedCredentialsMatcher`] JavaDoc to better understand hashing strategies and if they might be useful to you. - -For example, if your users' password strings were Base64 encoded instead of the default Hex, you could specify: - -[source,ini] ----- -[main] -... -# true = hex, false = base64: -sha256Matcher.storedCredentialsHexEncoded = false +user1 = $shiro2$argon2id$v=19$t=1,m=65536,p=4$H5z81Jpr4ntZr3MVtbOUBw$fJDgZCLZjMC6A2HhnSpxULMmvVdW3su+/GCU3YbxfFQ, role1, role2, ... ---- [#Configuration-INIConfiguration-Sections-roles] diff --git a/src/site/content/cryptography-features.adoc b/src/site/content/cryptography-features.adoc index d28a7ea0f7..dbab36f6f3 100644 --- a/src/site/content/cryptography-features.adoc +++ b/src/site/content/cryptography-features.adoc @@ -51,9 +51,13 @@ Shiro will automatically enable the more secure options to ensure your data is a [#CryptographyFeatures-HashFeatures] == Hash Features +* *Default KDF algorithms* * +Shiro 2 provides argon2 and bcrypt support out of the box. +Passwords should not be saved using hash algorithms, but modern KDFs do provide a sensible level of security against brute force attacks. + * *Default interface implementations* + -Shiro provides default Hash (aka Message Digests in the JDK) implementations out-of-the-box, such as MD5, SHA1, SHA-256, et al. -This provides a type-safe construction method (e.g. `new Md5Hash(data)`) instead of being forced to use type-unsafe string factory methods in the JDK. +Shiro provides default Hash (aka Message Digests in the JDK) implementations out-of-the-box, such as SHA-256, SHA-386, SHA-512, et al. +This provides a type-safe construction method (e.g. `new Sha256Hash(data)`) instead of being forced to use type-unsafe string factory methods in the JDK. * *Built-in Hex and Base64 conversion* + Shiro Hash instances can automatically provide Hex and Base-64 encoding of hashed data via their `toHex()` and `toBase64()` methods. From 45b0c5f63ccaef054e5eab30821aac720a88efb8 Mon Sep 17 00:00:00 2001 From: Benjamin Marwell Date: Tue, 23 Jan 2024 10:20:13 +0100 Subject: [PATCH 2/2] [#185] rework to a v2/ structure --- src/site/content/command-line-hasher.adoc | 17 ++- src/site/content/v2/command-line-hasher.adoc | 118 +++++++++++++++++++ src/site/templates/macros/versions.ftl | 48 ++++++++ src/site/templates/page.ftl | 9 ++ 4 files changed, 182 insertions(+), 10 deletions(-) create mode 100644 src/site/content/v2/command-line-hasher.adoc diff --git a/src/site/content/command-line-hasher.adoc b/src/site/content/command-line-hasher.adoc index feb6a8a12f..4415afb7f8 100644 --- a/src/site/content/command-line-hasher.adoc +++ b/src/site/content/command-line-hasher.adoc @@ -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: @@ -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 @@ -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: @@ -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] ---- diff --git a/src/site/content/v2/command-line-hasher.adoc b/src/site/content/v2/command-line-hasher.adoc new file mode 100644 index 0000000000..a6ed3fc379 --- /dev/null +++ b/src/site/content/v2/command-line-hasher.adoc @@ -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] +---- + -r fileInCurrentDirectory.txt + -r ../../relativePathFile.xml + -r ~/documents/myfile.pdf + -r /usr/local/logs/absolutePathFile.log + -r url:http://foo.com/page.html -r classpath:/WEB-INF/lib/something.jar +---- diff --git a/src/site/templates/macros/versions.ftl b/src/site/templates/macros/versions.ftl index 0f617ebc91..b08398e602 100644 --- a/src/site/templates/macros/versions.ftl +++ b/src/site/templates/macros/versions.ftl @@ -5,3 +5,51 @@ <#assign oldReleases = data.get('releases.yaml').oldReleases> <#assign artifacts = data.get('artifacts.yaml').artifacts> + +<#macro shirov2> + <#assign theDate = .now?date> +
+ + + + + + + +
+ + +
Shiro v2 alpha notice
+
+

As of ${theDate?iso_utc}, this version of Apache Shiro is in Alpha stage.

+
+
+
+ + +<#macro shirov1 sourcepage="" hasv2=false> + <#assign theDate = .now?date> +
+ + + + + + + +
+
Handy Hint
+ 		+
Shiro v1 version notice
+
+

As of ${theDate?iso_utc}, Shiro v1 will soon be superseded by v2.

+ <#if (sourcepage)?? && (sourcepage)?is_string && (sourcepage) != "" && hasv2 == true> + <#assign target=sourcepage?keep_after_last("/") /> +

+ Read this page in the v2 documentation. +

+ +
+
+
+ diff --git a/src/site/templates/page.ftl b/src/site/templates/page.ftl index 868fabc3e1..cba2d98af9 100644 --- a/src/site/templates/page.ftl +++ b/src/site/templates/page.ftl @@ -31,6 +31,15 @@ + <#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 /> + + <@content.body?interpret />