elastic · jkakavas · Aug 21, 2018 · Aug 14, 2018 · Aug 14, 2018 · Aug 16, 2018
diff --git a/docs/reference/settings/security-hash-settings.asciidoc b/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.
+|=======================
+
+
diff --git a/docs/reference/settings/security-settings.asciidoc b/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[]
diff --git a/x-pack/docs/en/rest-api/security/users.asciidoc b/x-pack/docs/en/rest-api/security/users.asciidoc
diff --git a/x-pack/docs/en/security/authentication/configuring-file-realm.asciidoc b/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).
---
+--
diff --git a/x-pack/docs/en/security/authentication/configuring-native-realm.asciidoc b/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}.

diff --git a/x-pack/docs/en/security/authentication/user-cache.asciidoc b/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