Document users hashed passwords with argon2 does not work in FIPS environment
closes #33296 Signed-off-by: mposolda <mposolda@gmail.com> Co-authored-by: Steven Hawkins <shawkins@redhat.com> Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com> Signed-off-by: Marek Posolda <mposolda@gmail.com>
This commit is contained in:
parent
456878bb00
commit
41c72d46d2
2 changed files with 18 additions and 6 deletions
|
@ -42,6 +42,9 @@ per-hashing request.
|
|||
To prevent excessive memory and CPU usage, the parallel computation of hashes by Argon2 is by default limited to the number of cores available to the JVM.
|
||||
To support the memory intensive nature of Argon2, we have updated the default GC from ParallelGC to G1GC for a better heap utilization.
|
||||
|
||||
Note that Argon2 is not compliant with FIPS 140-2. So if you are in the FIPS environment, the default algorithm will be still PBKDF2. Also note that if you are on non-FIPS environment and
|
||||
you plan to migrate to the FIPS environment, consider changing the password policy to a FIPS compliant algorithm such as `pbkdf2-sha512` at the outset. Otherwise, users will not be able to log in after they switch to the FIPS environment.
|
||||
|
||||
= New Hostname options
|
||||
|
||||
In response to the complexity and lack of intuitiveness experienced with previous hostname configuration settings, we are proud to introduce Hostname v2 options.
|
||||
|
|
|
@ -122,7 +122,7 @@ When starting the server, you can check that the startup log contains `KC` provi
|
|||
|
||||
[source]
|
||||
----
|
||||
KC(BCFIPS version 1.000203 Approved Mode, FIPS-JVM: enabled) version 1.0 - class org.keycloak.crypto.fips.KeycloakFipsSecurityProvider,
|
||||
KC(BCFIPS version 2.0 Approved Mode, FIPS-JVM: enabled) version 1.0 - class org.keycloak.crypto.fips.KeycloakFipsSecurityProvider,
|
||||
----
|
||||
|
||||
=== Cryptography restrictions in strict mode
|
||||
|
@ -131,18 +131,22 @@ KC(BCFIPS version 1.000203 Approved Mode, FIPS-JVM: enabled) version 1.0 - class
|
|||
supported in {project_name} when using strict mode. Some examples are importing or generating a keystore of an OIDC or SAML client in the Admin Console or for a `java-keystore` provider in the realm keys.
|
||||
|
||||
* User passwords must be 14 characters or longer. {project_name} uses PBKDF2 based password encoding by default. BCFIPS approved mode requires passwords to be at least 112 bits
|
||||
(effectively 14 characters) with PBKDF2 algorithm. If you want to allow a shorter password, set the property `max-padding-length` of provider `pbkdf2-sha256` of SPI `password-hashing`
|
||||
to value 14 to provide additional padding when verifying a hash created by this algorithm. This setting is also backwards compatible with previously stored passwords.
|
||||
(effectively 14 characters) with PBKDF2 algorithm. If you want to allow a shorter password, set the property `max-padding-length` of provider `pbkdf2-sha512` of SPI `password-hashing`
|
||||
to 14 to provide additional padding when verifying a hash created by this algorithm. This setting is also backwards compatible with previously stored passwords.
|
||||
For example, if the user's database is in a non-FIPS environment and you have shorter passwords and you want to verify them now with {project_name} using BCFIPS in approved mode, the passwords should work.
|
||||
So effectively, you can use an option such as the following when starting the server:
|
||||
|
||||
[source]
|
||||
----
|
||||
--spi-password-hashing-pbkdf2-sha256-max-padding-length=14
|
||||
--spi-password-hashing-pbkdf2-sha512-max-padding-length=14
|
||||
----
|
||||
|
||||
NOTE: Using the option above does not break FIPS compliance. However, note that longer passwords are good practice anyway. For example, passwords auto-generated by modern browsers match this
|
||||
requirement as they are longer than 14 characters.
|
||||
requirement as they are longer than 14 characters. If you want to omit the option for max-padding-length, you can set the password policy to your realms to have passwords at least 14 characters long.
|
||||
|
||||
NOTE: When you are migrating from {project_name} older than 24, or if you explicitly set the password policy to override the default hashing algorithm, it is possible that some of your users use an older
|
||||
algorithm like `pbkdf2-sha256`. In this case, consider adding the `--spi-password-hashing-pbkdf2-sha256-max-padding-length=14` option to ensure that users having their passwords hashed with
|
||||
the older `pbkdf2-sha256` can log in because their passwords may be shorter than 14 characters.
|
||||
|
||||
* RSA keys of 1024 bits do not work (2048 is the minimum). This applies for keys used by the {project_name} realm itself (Realm keys from the `Keys` tab in the admin console), but also client keys and IDP keys
|
||||
|
||||
|
@ -166,7 +170,7 @@ that it is not already available in your FIPS security providers:
|
|||
fips.provider.7=XMLDSig
|
||||
----
|
||||
|
||||
Adding this security provider should work well. In fact, it is FIPS compliant and is already added by default in the OpenJDK 21.
|
||||
Adding this security provider should work well. In fact, it is FIPS compliant and is already added by default in the OpenJDK 21 and newer versions of OpenJDK 17.
|
||||
Details are in the https://bugzilla.redhat.com/show_bug.cgi?id=1940064[bugzilla].
|
||||
|
||||
NOTE: It is recommended to look at `JAVA_HOME/conf/security/java.security` and check all configured providers here and make sure that the number matches. In other words, `fips.provider.7`
|
||||
|
@ -257,6 +261,11 @@ Then build FIPS as an optimized Docker image and start it as described in the <@
|
|||
If you previously used {project_name} in a non-fips environment, it is possible to migrate it to a FIPS environment including its data. However, restrictions and considerations exist as
|
||||
mentioned in previous sections, namely:
|
||||
|
||||
* Starting with {project_name} 25, the default algorithm for password hashing is `argon2`. However, this algorithm is not supported for FIPS 140-2. This means that if your users hashed their password
|
||||
with `argon2`, they will not be able to login after switch to the FIPS environment. If you plan to migrate to the FIPS environment, consider setting the
|
||||
Password policy for your realm from the beginning (before any users are created) and override the default algorithm for example to `pbkdf2-sha512`, which is FIPS compliant. This strategy helps to make the
|
||||
migration to the FIPS environment to be smooth. Otherwise, if your users are already on `argon2` passwords, simply ask users to reset the password after migrating to the FIPS
|
||||
environment. For instance, ask users to use "Forget password" or send the email for reset-password to all users.
|
||||
* Make sure all the {project_name} functionality relying on keystores uses only supported keystore types. This differs based on whether strict or non-strict mode is used.
|
||||
* Kerberos authentication may not work. If your authentication flow uses `Kerberos` authenticator, this authenticator will be automatically switched to `DISABLED` when migrated to FIPS
|
||||
environment. It is recommended to remove any `Kerberos` user storage providers from your realm and disable `Kerberos` related functionality in LDAP providers before switching to FIPS environment.
|
||||
|
|
Loading…
Reference in a new issue