Browse Source

Recommend `ssha256` cache hasher in FIPS docs (#87255)

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 #86740 for more context.
Nikolaj Volgushev 3 years ago
parent
commit
d6e5c29e25
1 changed files with 26 additions and 8 deletions
  1. 26 8
      x-pack/docs/en/security/fips-140-compliance.asciidoc

+ 26 - 8
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
 <<keystore-fips-password,112-bit key strength requirement>>. 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 <<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