Skip to content

Commit

Permalink
Recommend ssha256 cache hasher in FIPS docs (elastic#87255)
Browse files Browse the repository at this point in the history
Our docs currently recommend PBKDF2 as a cache hasher in FIPS mode.
However, the performance overhead of PBKDF2 is prohibitive; ssha256
is a more appropriate choice for in-memory credential hashing. This PR
updates the docs to reflect this. See elastic#86740 for more context.
  • Loading branch information
n1v0lg committed Jul 22, 2022
1 parent c7f4454 commit 17d5463
Showing 1 changed file with 26 additions and 8 deletions.
34 changes: 26 additions & 8 deletions x-pack/docs/en/security/fips-140-compliance.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -113,11 +113,12 @@ keys must have corresponding length according to the following table:
|=======================

[discrete]
==== Password Hashing
==== Stored password hashing
[[fips-stored-password-hashing]]

While {es} offers a number of algorithms for securely hashing credentials in memory and
While {es} offers a number of algorithms for securely hashing credentials
on disk, only the `PBKDF2` based family of algorithms is compliant with FIPS
140-2 for password hashing. However, since `PBKDF2` is essentially a key derivation
140-2 for stored password hashing. However, since `PBKDF2` is essentially a key derivation
function, your JVM security provider may enforce a
<<keystore-fips-password,112-bit key strength requirement>>. Although FIPS 140-2
does not mandate user password standards, this requirement may affect password
Expand All @@ -131,8 +132,7 @@ NOTE: You can still use one of the plain `pbkdf2` options instead of `pbkdf2_str
you have external policies and tools that can ensure all user passwords for the reserved,
native, and file realms are longer than 14 bytes.

You must set the `cache.hash_algo` realm settings
and the `xpack.security.authc.password_hashing.algorithm` setting to one of the
You must set the `xpack.security.authc.password_hashing.algorithm` setting to one of the
available `pbkdf_stretch_*` values.
When FIPS-140 mode is enabled, the default value for
`xpack.security.authc.password_hashing.algorithm` is `pbkdf2_stretch`.
Expand All @@ -147,9 +147,27 @@ for the file realm and the <<security-api-put-user,create users>> and
<<security-api-change-password,change password>> APIs for the native and reserved realms.
Other types of realms are not affected and do not require any changes.

The user cache will be emptied upon node restart, so any existing hashes using
non-compliant algorithms will be discarded and the new ones will be created
using the compliant `PBKDF2` based algorithm you have selected.
[discrete]
==== Cached password hashing
[[fips-cached-password-hashing]]

`ssha256` (salted `sha256`) is recommended for cache hashing. Though
`PBKDF2` is compliant with FIPS-140-2, it is -- by design -- slow, and
thus not generally suitable as a cache hashing algorithm. Cached
credentials are never stored on disk, and salted `sha256` provides an
adequate level of security for in-memory credential hashing, without
imposing prohibitive performance overhead. You _may_ use `PBKDF2`,
however you should carefully assess performance impact first. Depending
on your deployment, the overhead of `PBKDF2` could undo most of the
performance gain of using a cache.

Either set all `cache.hash_algo` settings to `ssha256` or leave
them undefined, since `ssha256` is the default value for all
`cache.hash_algo` settings. See <<hashing-settings>>.

The user cache will be emptied upon node restart, so any existing
hashes using non-compliant algorithms will be discarded and the new
ones will be created using the algorithm you have selected.

[discrete]
=== Limitations
Expand Down

0 comments on commit 17d5463

Please sign in to comment.