[DOCS] Add configurable password hashing docs (#32849)

* [DOCS] Add configurable password hashing docs

Adds documentation about the newly introduced configuration option
for setting the password hashing algorithm to be used for the users
cache and for storing credentials for the native and file realm.

docs/reference/settings/security-hash-settings.asciidoc

@@ -0,0 +1,84 @@
+[float]
+[[hashing-settings]]
+==== User cache and password hash algorithms
+
+Certain realms store user credentials in memory. To limit exposure
+to credential theft and mitigate credential compromise, the cache only stores
+a hashed version of the user credentials in memory. By default, the user cache
+is hashed with a salted `sha-256` hash algorithm. You can use a different
+hashing algorithm by setting the `cache.hash_algo` realm settings to any of the
+following values:
+
+[[cache-hash-algo]]
+.Cache hash algorithms
+|=======================
+| Algorithm           | | | Description
+| `ssha256`           | | | Uses a salted `sha-256` algorithm (default).
+| `md5`               | | | Uses `MD5` algorithm.
+| `sha1`              | | | Uses `SHA1` algorithm.
+| `bcrypt`            | | | Uses `bcrypt` algorithm with salt generated in 1024 rounds.
+| `bcrypt4`           | | | Uses `bcrypt` algorithm with salt generated in 16 rounds.
+| `bcrypt5`           | | | Uses `bcrypt` algorithm with salt generated in 32 rounds.
+| `bcrypt6`           | | | Uses `bcrypt` algorithm with salt generated in 64 rounds.
+| `bcrypt7`           | | | Uses `bcrypt` algorithm with salt generated in 128 rounds.
+| `bcrypt8`           | | | Uses `bcrypt` algorithm with salt generated in 256 rounds.
+| `bcrypt9`           | | | Uses `bcrypt` algorithm with salt generated in 512 rounds.
+| `pbkdf2`            | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
+                             pseudorandom function using 10000 iterations.
+| `pbkdf2_1000`       | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
+                             pseudorandom function using 1000 iterations.
+| `pbkdf2_10000`      | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
+                             pseudorandom function using 10000 iterations.
+| `pbkdf2_50000`      | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
+                             pseudorandom function using 50000 iterations.
+| `pbkdf2_100000`     | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
+                             pseudorandom function using 100000 iterations.
+| `pbkdf2_500000`     | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
+                              pseudorandom function using 500000 iterations.
+| `pbkdf2_1000000`    | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
+                             pseudorandom function using 1000000 iterations.
+| `noop`,`clear_text` | | | Doesn't hash the credentials and keeps it in clear text in
+                            memory. CAUTION: keeping clear text is considered insecure
+                            and can be compromised at the OS level (for example through
+                            memory dumps and using `ptrace`).
+|=======================
+
+Likewise, realms that store passwords hash them using cryptographically strong 
+and password-specific salt values. You can configure the algorithm for password 
+hashing by setting the `xpack.security.authc.password_hashing.algorithm` setting 
+to one of the following:
+
+[[password-hashing-algorithms]]
+.Password hashing algorithms
+|=======================
+| Algorithm           | | | Description
+
+| `bcrypt`            | | | Uses `bcrypt` algorithm with salt generated in 1024 rounds. (default)
+| `bcrypt4`           | | | Uses `bcrypt` algorithm with salt generated in 16 rounds.
+| `bcrypt5`           | | | Uses `bcrypt` algorithm with salt generated in 32 rounds.
+| `bcrypt6`           | | | Uses `bcrypt` algorithm with salt generated in 64 rounds.
+| `bcrypt7`           | | | Uses `bcrypt` algorithm with salt generated in 128 rounds.
+| `bcrypt8`           | | | Uses `bcrypt` algorithm with salt generated in 256 rounds.
+| `bcrypt9`           | | | Uses `bcrypt` algorithm with salt generated in 512 rounds.
+| `bcrypt10`          | | | Uses `bcrypt` algorithm with salt generated in 1024 rounds.
+| `bcrypt11`          | | | Uses `bcrypt` algorithm with salt generated in 2048 rounds.
+| `bcrypt12`          | | | Uses `bcrypt` algorithm with salt generated in 4096 rounds.
+| `bcrypt13`          | | | Uses `bcrypt` algorithm with salt generated in 8192 rounds.
+| `bcrypt14`          | | | Uses `bcrypt` algorithm with salt generated in 16384 rounds.
+| `pbkdf2`            | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
+                             pseudorandom function using 10000 iterations.
+| `pbkdf2_1000`       | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
+                             pseudorandom function using 1000 iterations.
+| `pbkdf2_10000`      | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
+                             pseudorandom function using 10000 iterations.
+| `pbkdf2_50000`      | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
+                             pseudorandom function using 50000 iterations.
+| `pbkdf2_100000`     | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
+                             pseudorandom function using 100000 iterations.
+| `pbkdf2_500000`     | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
+                              pseudorandom function using 500000 iterations.
+| `pbkdf2_1000000`    | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
+                             pseudorandom function using 1000000 iterations.
+|=======================
+
+

docs/reference/settings/security-settings.asciidoc

@@ -52,6 +52,12 @@ sensitive nature of the information.
 `xpack.security.authc.accept_default_password`::
 In `elasticsearch.yml`, set this to `false` to disable support for the default "changeme" password.
 
+[[password-hashing-settings]]
+==== Password hashing settings
+`xpack.security.authc.password_hashing.algorithm`::
+Specifies the hashing algorithm that is used for secure user credential storage. 
+See <<password-hashing-algorithms>>. Defaults to `bcrypt`.
+
 [float]
 [[anonymous-access-settings]]
 ==== Anonymous access settings
@@ -164,9 +170,8 @@ the standard {es} <<time-units,time units>>. Defaults to `20m`.
 cache at any given time. Defaults to 100,000.
 
 `cache.hash_algo`:: (Expert Setting) The hashing algorithm that is used for the 
-in-memory cached user credentials. For possible values, see 
-{xpack-ref}/controlling-user-cache.html[Cache hash algorithms]. Defaults to 
-`ssha256`.
+in-memory cached user credentials. For possible values, see <<cache-hash-algo>>. 
+Defaults to `ssha256`.
 
 
 [[ref-users-settings]]
@@ -190,8 +195,7 @@ Defaults to 100,000.
 
 `cache.hash_algo`::
 (Expert Setting) The hashing algorithm that is used for the in-memory cached
-user credentials. See the {xpack-ref}/controlling-user-cache.html#controlling-user-cache[Cache hash algorithms] table for
-all possible values. Defaults to `ssha256`.
+user credentials. See <<cache-hash-algo>>. Defaults to `ssha256`.
 
 [[ref-ldap-settings]]
 [float]
@@ -444,8 +448,7 @@ Defaults to `100000`.
 
 `cache.hash_algo`::
 (Expert Setting) Specifies the hashing algorithm that is used for the
-in-memory cached user credentials. See {xpack-ref}/controlling-user-cache.html#controlling-user-cache[Cache hash algorithms]
-table for all possible values. Defaults to `ssha256`.
+in-memory cached user credentials. See <<cache-hash-algo>>. Defaults to `ssha256`.
 
 [[ref-ad-settings]]
 [float]
@@ -684,7 +687,7 @@ Defaults to `100000`.
 
 `cache.hash_algo`::
 (Expert Setting) Specifies the hashing algorithm that is used for
-the in-memory cached user credentials (see {xpack-ref}/controlling-user-cache.html#controlling-user-cache[Cache hash algorithms] table for all possible values). Defaults to `ssha256`.
+the in-memory cached user credentials. See <<cache-hash-algo>>. Defaults to `ssha256`.
 
 `follow_referrals`::
 If set to `true` {security} follows referrals returned by the LDAP server. 
@@ -1335,3 +1338,5 @@ List of IP addresses to allow for this profile.
 
 `transport.profiles.$PROFILE.xpack.security.filter.deny`::
 List of IP addresses to deny for this profile.
+
+include::security-hash-settings.asciidoc[]

x-pack/docs/en/security/authentication/configuring-file-realm.asciidoc

@@ -55,18 +55,23 @@ cluster.
 +
 --
 The `users` file stores all the users and their passwords. Each line in the file 
-represents a single user entry consisting of the username and **hashed** password.
+represents a single user entry consisting of the username and **hashed** and **salted** password.
 
 [source,bash]
 ----------------------------------------------------------------------
 rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W
 alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS
-jacknich:$2a$10$GYUNWyABV/Ols/.bcwxuBuuaQzV6WIauW6RdboojxcixBq3LtI3ni
+jacknich:{PBKDF2}50000$z1CLJt0MEFjkIK5iEfgvfnA6xq7lF25uasspsTKSo5Q=$XxCVLbaKDimOdyWgLCLJiyoiWpA/XDMe/xtVgn1r5Sg=
 ----------------------------------------------------------------------
 
-{security} uses `bcrypt` to hash the user passwords.
+NOTE: To limit exposure to credential theft and mitigate credential compromise,
+the file realm stores passwords and caches user credentials according to
+security best practices. By default, a hashed version of user credentials
+is stored in memory, using a salted `sha-256` hash algorithm and a hashed
+version of passwords is stored on disk salted and hashed with the `bcrypt`
+hash algorithm. To use different hash algorithms, see <<hashing-settings>>.
 
-While it is possible to modify this files directly using any standard text
+While it is possible to modify the `users` files directly using any standard text
 editor, we strongly recommend using the <<users-command>> tool to apply the 
 required changes.
 
@@ -103,4 +108,4 @@ By default, {security} checks these files for changes every 5 seconds. You can
 change this default behavior by changing the `resource.reload.interval.high` 
 setting in the `elasticsearch.yml` file (as this is a common setting in {es},
 changing its value may effect other schedules in the system).
---
+--

x-pack/docs/en/security/authentication/configuring-native-realm.asciidoc

@@ -34,6 +34,13 @@ xpack:
           type: native
           order: 0
 ------------------------------------------------------------
+
+NOTE: To limit exposure to credential theft and mitigate credential compromise,
+the native realm stores passwords and caches user credentials according to
+security best practices. By default, a hashed version of user credentials
+is stored in memory, using a salted `sha-256` hash algorithm and a hashed
+version of passwords is stored on disk salted and hashed with the `bcrypt`
+hash algorithm. To use different hash algorithms, see <<hashing-settings>>.
 --
 
 . Restart {es}.

x-pack/docs/en/security/authentication/user-cache.asciidoc

@@ -12,27 +12,8 @@ object to avoid unnecessarily needing to perform role mapping on each request.
 
 The cached user credentials are hashed in memory. By default, {security} uses a
 salted `sha-256` hash algorithm. You can use a different hashing algorithm by
-setting the `cache_hash_algo` setting to any of the following:
-
-[[cache-hash-algo]]
-.Cache hash algorithms
-|=======================
-| Algorithm           | | | Description
-| `ssha256`           | | | Uses a salted `sha-256` algorithm (default).
-| `md5`               | | | Uses `MD5` algorithm.
-| `sha1`              | | | Uses `SHA1` algorithm.
-| `bcrypt`            | | | Uses `bcrypt` algorithm with salt generated in 1024 rounds.
-| `bcrypt4`           | | | Uses `bcrypt` algorithm with salt generated in 16 rounds.
-| `bcrypt5`           | | | Uses `bcrypt` algorithm with salt generated in 32 rounds.
-| `bcrypt6`           | | | Uses `bcrypt` algorithm with salt generated in 64 rounds.
-| `bcrypt7`           | | | Uses `bcrypt` algorithm with salt generated in 128 rounds.
-| `bcrypt8`           | | | Uses `bcrypt` algorithm with salt generated in 256 rounds.
-| `bcrypt9`           | | | Uses `bcrypt` algorithm with salt generated in 512 rounds.
-| `noop`,`clear_text` | | | Doesn't hash the credentials and keeps it in clear text in
-                            memory. CAUTION: keeping clear text is considered insecure
-                            and can be compromised at the OS level (for example through
-                            memory dumps and using `ptrace`).
-|=======================
+setting the `cache.hash_algo` realm settings. See 
+{ref}/security-settings.html#hashing-settings[User cache and password hash algorithms].
 
 [[cache-eviction-api]]
 ==== Evicting users from the cache