@@ -107,11 +107,12 @@ keys must have corresponding length according to the following table:
107107|=======================
108108
109109[discrete]
110- ==== Password Hashing
110+ ==== Stored password hashing
111+ [[fips-stored-password-hashing]]
111112
112- While {es} offers a number of algorithms for securely hashing credentials in memory and
113+ While {es} offers a number of algorithms for securely hashing credentials
113114on disk, only the `PBKDF2` based family of algorithms is compliant with FIPS
114- 140-2 for password hashing. However, since `PBKDF2` is essentially a key derivation
115+ 140-2 for stored password hashing. However, since `PBKDF2` is essentially a key derivation
115116function, your JVM security provider may enforce a
116117<<keystore-fips-password,112-bit key strength requirement>>. Although FIPS 140-2
117118does not mandate user password standards, this requirement may affect password
@@ -125,8 +126,7 @@ NOTE: You can still use one of the plain `pbkdf2` options instead of `pbkdf2_str
125126you have external policies and tools that can ensure all user passwords for the reserved,
126127native, and file realms are longer than 14 bytes.
127128
128- You must set the `cache.hash_algo` realm settings
129- and the `xpack.security.authc.password_hashing.algorithm` setting to one of the
129+ You must set the `xpack.security.authc.password_hashing.algorithm` setting to one of the
130130available `pbkdf_stretch_*` values.
131131See <<hashing-settings>>.
132132
@@ -139,9 +139,27 @@ for the file realm and the <<security-api-put-user,create users>> and
139139<<security-api-change-password,change password>> APIs for the native and reserved realms.
140140Other types of realms are not affected and do not require any changes.
141141
142- The user cache will be emptied upon node restart, so any existing hashes using
143- non-compliant algorithms will be discarded and the new ones will be created
144- using the compliant `PBKDF2` based algorithm you have selected.
142+ [discrete]
143+ ==== Cached password hashing
144+ [[fips-cached-password-hashing]]
145+
146+ `ssha256` (salted `sha256`) is recommended for cache hashing. Though
147+ `PBKDF2` is compliant with FIPS-140-2, it is -- by design -- slow, and
148+ thus not generally suitable as a cache hashing algorithm. Cached
149+ credentials are never stored on disk, and salted `sha256` provides an
150+ adequate level of security for in-memory credential hashing, without
151+ imposing prohibitive performance overhead. You _may_ use `PBKDF2`,
152+ however you should carefully assess performance impact first. Depending
153+ on your deployment, the overhead of `PBKDF2` could undo most of the
154+ performance gain of using a cache.
155+
156+ Either set all `cache.hash_algo` settings to `ssha256` or leave
157+ them undefined, since `ssha256` is the default value for all
158+ `cache.hash_algo` settings. See <<hashing-settings>>.
159+
160+ The user cache will be emptied upon node restart, so any existing
161+ hashes using non-compliant algorithms will be discarded and the new
162+ ones will be created using the algorithm you have selected.
145163
146164[discrete]
147165=== Limitations
0 commit comments