Skip to content

Commit d52d17f

Browse files
authored
Recommend ssha256 cache hasher in FIPS docs (#87255) (#88718)
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.
1 parent 890b8f4 commit d52d17f

File tree

1 file changed

+26
-8
lines changed

1 file changed

+26
-8
lines changed

x-pack/docs/en/security/fips-140-compliance.asciidoc

Lines changed: 26 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -113,11 +113,12 @@ keys must have corresponding length according to the following table:
113113
|=======================
114114

115115
[discrete]
116-
==== Password Hashing
116+
==== Stored password hashing
117+
[[fips-stored-password-hashing]]
117118

118-
While {es} offers a number of algorithms for securely hashing credentials in memory and
119+
While {es} offers a number of algorithms for securely hashing credentials
119120
on disk, only the `PBKDF2` based family of algorithms is compliant with FIPS
120-
140-2 for password hashing. However, since `PBKDF2` is essentially a key derivation
121+
140-2 for stored password hashing. However, since `PBKDF2` is essentially a key derivation
121122
function, your JVM security provider may enforce a
122123
<<keystore-fips-password,112-bit key strength requirement>>. Although FIPS 140-2
123124
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
131132
you have external policies and tools that can ensure all user passwords for the reserved,
132133
native, and file realms are longer than 14 bytes.
133134

134-
You must set the `cache.hash_algo` realm settings
135-
and the `xpack.security.authc.password_hashing.algorithm` setting to one of the
135+
You must set the `xpack.security.authc.password_hashing.algorithm` setting to one of the
136136
available `pbkdf_stretch_*` values.
137137
When FIPS-140 mode is enabled, the default value for
138138
`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
147147
<<security-api-change-password,change password>> APIs for the native and reserved realms.
148148
Other types of realms are not affected and do not require any changes.
149149

150-
The user cache will be emptied upon node restart, so any existing hashes using
151-
non-compliant algorithms will be discarded and the new ones will be created
152-
using the compliant `PBKDF2` based algorithm you have selected.
150+
[discrete]
151+
==== Cached password hashing
152+
[[fips-cached-password-hashing]]
153+
154+
`ssha256` (salted `sha256`) is recommended for cache hashing. Though
155+
`PBKDF2` is compliant with FIPS-140-2, it is -- by design -- slow, and
156+
thus not generally suitable as a cache hashing algorithm. Cached
157+
credentials are never stored on disk, and salted `sha256` provides an
158+
adequate level of security for in-memory credential hashing, without
159+
imposing prohibitive performance overhead. You _may_ use `PBKDF2`,
160+
however you should carefully assess performance impact first. Depending
161+
on your deployment, the overhead of `PBKDF2` could undo most of the
162+
performance gain of using a cache.
163+
164+
Either set all `cache.hash_algo` settings to `ssha256` or leave
165+
them undefined, since `ssha256` is the default value for all
166+
`cache.hash_algo` settings. See <<hashing-settings>>.
167+
168+
The user cache will be emptied upon node restart, so any existing
169+
hashes using non-compliant algorithms will be discarded and the new
170+
ones will be created using the algorithm you have selected.
153171

154172
[discrete]
155173
=== Limitations

0 commit comments

Comments
 (0)