diff --git a/x-pack/docs/en/security/fips-140-compliance.asciidoc b/x-pack/docs/en/security/fips-140-compliance.asciidoc index beea826b4d277..5a1b8e4e69fa3 100644 --- a/x-pack/docs/en/security/fips-140-compliance.asciidoc +++ b/x-pack/docs/en/security/fips-140-compliance.asciidoc @@ -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 <>. Although FIPS 140-2 does not mandate user password standards, this requirement may affect password @@ -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`. @@ -147,9 +147,27 @@ for the file realm and the <> and <> 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 <>. + +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