Skip to content

Commit 65d4f27

Browse files
jkakavasjkakavas
authored
[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.
1 parent 2000787 commit 65d4f27

File tree

6 files changed

+116
-34
lines changed

6 files changed

+116
-34
lines changed

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

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
[float]
2+
[[hashing-settings]]
3+
==== User cache and password hash algorithms
4+
5+
Certain realms store user credentials in memory. To limit exposure
6+
to credential theft and mitigate credential compromise, the cache only stores
7+
a hashed version of the user credentials in memory. By default, the user cache
8+
is hashed with a salted `sha-256` hash algorithm. You can use a different
9+
hashing algorithm by setting the `cache.hash_algo` realm settings to any of the
10+
following values:
11+
12+
[[cache-hash-algo]]
13+
.Cache hash algorithms
14+
|=======================
15+
| Algorithm | | | Description
16+
| `ssha256` | | | Uses a salted `sha-256` algorithm (default).
17+
| `md5` | | | Uses `MD5` algorithm.
18+
| `sha1` | | | Uses `SHA1` algorithm.
19+
| `bcrypt` | | | Uses `bcrypt` algorithm with salt generated in 1024 rounds.
20+
| `bcrypt4` | | | Uses `bcrypt` algorithm with salt generated in 16 rounds.
21+
| `bcrypt5` | | | Uses `bcrypt` algorithm with salt generated in 32 rounds.
22+
| `bcrypt6` | | | Uses `bcrypt` algorithm with salt generated in 64 rounds.
23+
| `bcrypt7` | | | Uses `bcrypt` algorithm with salt generated in 128 rounds.
24+
| `bcrypt8` | | | Uses `bcrypt` algorithm with salt generated in 256 rounds.
25+
| `bcrypt9` | | | Uses `bcrypt` algorithm with salt generated in 512 rounds.
26+
| `pbkdf2` | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
27+
pseudorandom function using 10000 iterations.
28+
| `pbkdf2_1000` | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
29+
pseudorandom function using 1000 iterations.
30+
| `pbkdf2_10000` | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
31+
pseudorandom function using 10000 iterations.
32+
| `pbkdf2_50000` | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
33+
pseudorandom function using 50000 iterations.
34+
| `pbkdf2_100000` | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
35+
pseudorandom function using 100000 iterations.
36+
| `pbkdf2_500000` | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
37+
pseudorandom function using 500000 iterations.
38+
| `pbkdf2_1000000` | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
39+
pseudorandom function using 1000000 iterations.
40+
| `noop`,`clear_text` | | | Doesn't hash the credentials and keeps it in clear text in
41+
memory. CAUTION: keeping clear text is considered insecure
42+
and can be compromised at the OS level (for example through
43+
memory dumps and using `ptrace`).
44+
|=======================
45+
46+
Likewise, realms that store passwords hash them using cryptographically strong
47+
and password-specific salt values. You can configure the algorithm for password
48+
hashing by setting the `xpack.security.authc.password_hashing.algorithm` setting
49+
to one of the following:
50+
51+
[[password-hashing-algorithms]]
52+
.Password hashing algorithms
53+
|=======================
54+
| Algorithm | | | Description
55+
56+
| `bcrypt` | | | Uses `bcrypt` algorithm with salt generated in 1024 rounds. (default)
57+
| `bcrypt4` | | | Uses `bcrypt` algorithm with salt generated in 16 rounds.
58+
| `bcrypt5` | | | Uses `bcrypt` algorithm with salt generated in 32 rounds.
59+
| `bcrypt6` | | | Uses `bcrypt` algorithm with salt generated in 64 rounds.
60+
| `bcrypt7` | | | Uses `bcrypt` algorithm with salt generated in 128 rounds.
61+
| `bcrypt8` | | | Uses `bcrypt` algorithm with salt generated in 256 rounds.
62+
| `bcrypt9` | | | Uses `bcrypt` algorithm with salt generated in 512 rounds.
63+
| `bcrypt10` | | | Uses `bcrypt` algorithm with salt generated in 1024 rounds.
64+
| `bcrypt11` | | | Uses `bcrypt` algorithm with salt generated in 2048 rounds.
65+
| `bcrypt12` | | | Uses `bcrypt` algorithm with salt generated in 4096 rounds.
66+
| `bcrypt13` | | | Uses `bcrypt` algorithm with salt generated in 8192 rounds.
67+
| `bcrypt14` | | | Uses `bcrypt` algorithm with salt generated in 16384 rounds.
68+
| `pbkdf2` | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
69+
pseudorandom function using 10000 iterations.
70+
| `pbkdf2_1000` | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
71+
pseudorandom function using 1000 iterations.
72+
| `pbkdf2_10000` | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
73+
pseudorandom function using 10000 iterations.
74+
| `pbkdf2_50000` | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
75+
pseudorandom function using 50000 iterations.
76+
| `pbkdf2_100000` | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
77+
pseudorandom function using 100000 iterations.
78+
| `pbkdf2_500000` | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
79+
pseudorandom function using 500000 iterations.
80+
| `pbkdf2_1000000` | | | Uses `PBKDF2` key derivation function with `HMAC-SHA512` as a
81+
pseudorandom function using 1000000 iterations.
82+
|=======================
83+
84+

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

+13-8
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,12 @@ sensitive nature of the information.
5252
`xpack.security.authc.accept_default_password`::
5353
In `elasticsearch.yml`, set this to `false` to disable support for the default "changeme" password.
5454

55+
[[password-hashing-settings]]
56+
==== Password hashing settings
57+
`xpack.security.authc.password_hashing.algorithm`::
58+
Specifies the hashing algorithm that is used for secure user credential storage.
59+
See <<password-hashing-algorithms>>. Defaults to `bcrypt`.
60+
5561
[float]
5662
[[anonymous-access-settings]]
5763
==== Anonymous access settings
@@ -164,9 +170,8 @@ the standard {es} <<time-units,time units>>. Defaults to `20m`.
164170
cache at any given time. Defaults to 100,000.
165171

166172
`cache.hash_algo`:: (Expert Setting) The hashing algorithm that is used for the
167-
in-memory cached user credentials. For possible values, see
168-
{xpack-ref}/controlling-user-cache.html[Cache hash algorithms]. Defaults to
169-
`ssha256`.
173+
in-memory cached user credentials. For possible values, see <<cache-hash-algo>>.
174+
Defaults to `ssha256`.
170175

171176

172177
[[ref-users-settings]]
@@ -190,8 +195,7 @@ Defaults to 100,000.
190195

191196
`cache.hash_algo`::
192197
(Expert Setting) The hashing algorithm that is used for the in-memory cached
193-
user credentials. See the {xpack-ref}/controlling-user-cache.html#controlling-user-cache[Cache hash algorithms] table for
194-
all possible values. Defaults to `ssha256`.
198+
user credentials. See <<cache-hash-algo>>. Defaults to `ssha256`.
195199

196200
[[ref-ldap-settings]]
197201
[float]
@@ -444,8 +448,7 @@ Defaults to `100000`.
444448

445449
`cache.hash_algo`::
446450
(Expert Setting) Specifies the hashing algorithm that is used for the
447-
in-memory cached user credentials. See {xpack-ref}/controlling-user-cache.html#controlling-user-cache[Cache hash algorithms]
448-
table for all possible values. Defaults to `ssha256`.
451+
in-memory cached user credentials. See <<cache-hash-algo>>. Defaults to `ssha256`.
449452

450453
[[ref-ad-settings]]
451454
[float]
@@ -684,7 +687,7 @@ Defaults to `100000`.
684687

685688
`cache.hash_algo`::
686689
(Expert Setting) Specifies the hashing algorithm that is used for
687-
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`.
690+
the in-memory cached user credentials. See <<cache-hash-algo>>. Defaults to `ssha256`.
688691

689692
`follow_referrals`::
690693
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.
13351338

13361339
`transport.profiles.$PROFILE.xpack.security.filter.deny`::
13371340
List of IP addresses to deny for this profile.
1341+
1342+
include::security-hash-settings.asciidoc[]

‎x-pack/docs/en/rest-api/security/users.asciidoc

Whitespace-only changes.

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

+10-5
Original file line numberDiff line numberDiff line change
@@ -55,18 +55,23 @@ cluster.
5555
+
5656
--
5757
The `users` file stores all the users and their passwords. Each line in the file
58-
represents a single user entry consisting of the username and **hashed** password.
58+
represents a single user entry consisting of the username and **hashed** and **salted** password.
5959

6060
[source,bash]
6161
----------------------------------------------------------------------
6262
rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W
6363
alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS
64-
jacknich:$2a$10$GYUNWyABV/Ols/.bcwxuBuuaQzV6WIauW6RdboojxcixBq3LtI3ni
64+
jacknich:{PBKDF2}50000$z1CLJt0MEFjkIK5iEfgvfnA6xq7lF25uasspsTKSo5Q=$XxCVLbaKDimOdyWgLCLJiyoiWpA/XDMe/xtVgn1r5Sg=
6565
----------------------------------------------------------------------
6666

67-
{security} uses `bcrypt` to hash the user passwords.
67+
NOTE: To limit exposure to credential theft and mitigate credential compromise,
68+
the file realm stores passwords and caches user credentials according to
69+
security best practices. By default, a hashed version of user credentials
70+
is stored in memory, using a salted `sha-256` hash algorithm and a hashed
71+
version of passwords is stored on disk salted and hashed with the `bcrypt`
72+
hash algorithm. To use different hash algorithms, see <<hashing-settings>>.
6873

69-
While it is possible to modify this files directly using any standard text
74+
While it is possible to modify the `users` files directly using any standard text
7075
editor, we strongly recommend using the <<users-command>> tool to apply the
7176
required changes.
7277

@@ -103,4 +108,4 @@ By default, {security} checks these files for changes every 5 seconds. You can
103108
change this default behavior by changing the `resource.reload.interval.high`
104109
setting in the `elasticsearch.yml` file (as this is a common setting in {es},
105110
changing its value may effect other schedules in the system).
106-
--
111+
--

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

+7
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,13 @@ xpack:
3434
type: native
3535
order: 0
3636
------------------------------------------------------------
37+
38+
NOTE: To limit exposure to credential theft and mitigate credential compromise,
39+
the native realm stores passwords and caches user credentials according to
40+
security best practices. By default, a hashed version of user credentials
41+
is stored in memory, using a salted `sha-256` hash algorithm and a hashed
42+
version of passwords is stored on disk salted and hashed with the `bcrypt`
43+
hash algorithm. To use different hash algorithms, see <<hashing-settings>>.
3744
--
3845

3946
. Restart {es}.

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

+2-21
Original file line numberDiff line numberDiff line change
@@ -12,27 +12,8 @@ object to avoid unnecessarily needing to perform role mapping on each request.
1212

1313
The cached user credentials are hashed in memory. By default, {security} uses a
1414
salted `sha-256` hash algorithm. You can use a different hashing algorithm by
15-
setting the `cache_hash_algo` setting to any of the following:
16-
17-
[[cache-hash-algo]]
18-
.Cache hash algorithms
19-
|=======================
20-
| Algorithm | | | Description
21-
| `ssha256` | | | Uses a salted `sha-256` algorithm (default).
22-
| `md5` | | | Uses `MD5` algorithm.
23-
| `sha1` | | | Uses `SHA1` algorithm.
24-
| `bcrypt` | | | Uses `bcrypt` algorithm with salt generated in 1024 rounds.
25-
| `bcrypt4` | | | Uses `bcrypt` algorithm with salt generated in 16 rounds.
26-
| `bcrypt5` | | | Uses `bcrypt` algorithm with salt generated in 32 rounds.
27-
| `bcrypt6` | | | Uses `bcrypt` algorithm with salt generated in 64 rounds.
28-
| `bcrypt7` | | | Uses `bcrypt` algorithm with salt generated in 128 rounds.
29-
| `bcrypt8` | | | Uses `bcrypt` algorithm with salt generated in 256 rounds.
30-
| `bcrypt9` | | | Uses `bcrypt` algorithm with salt generated in 512 rounds.
31-
| `noop`,`clear_text` | | | Doesn't hash the credentials and keeps it in clear text in
32-
memory. CAUTION: keeping clear text is considered insecure
33-
and can be compromised at the OS level (for example through
34-
memory dumps and using `ptrace`).
35-
|=======================
15+
setting the `cache.hash_algo` realm settings. See
16+
{ref}/security-settings.html#hashing-settings[User cache and password hash algorithms].
3617

3718
[[cache-eviction-api]]
3819
==== Evicting users from the cache

0 commit comments

Comments
 (0)