Skip to content

Commit 74048ff

Browse files
lcawllcawl
committed
[DOCS] Adds hash algorithms to security settings
1 parent 8fde52e commit 74048ff

File tree

2 files changed

+92
-10
lines changed

2 files changed

+92
-10
lines changed

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

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

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

+9-10
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,8 @@ In `elasticsearch.yml`, set this to `false` to disable support for the default "
5555
[[password-hashing-settings]]
5656
==== Password hashing settings
5757
`xpack.security.authc.password_hashing.algorithm`::
58-
Specifies the hashing algorithm that is used for secure user credential storage
59-
(see {xpack-ref}/password-hashing.html#password-hashing-algorithms[Password hashing algorithms] table for all possible values). Defaults to `bcrypt`.
58+
Specifies the hashing algorithm that is used for secure user credential storage.
59+
See <<password-hashing-algorithms>>. Defaults to `bcrypt`.
6060

6161
[float]
6262
[[anonymous-access-settings]]
@@ -170,9 +170,8 @@ the standard {es} <<time-units,time units>>. Defaults to `20m`.
170170
cache at any given time. Defaults to 100,000.
171171

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

177176

178177
[[ref-users-settings]]
@@ -196,8 +195,7 @@ Defaults to 100,000.
196195

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

202200
[[ref-ldap-settings]]
203201
[float]
@@ -450,8 +448,7 @@ Defaults to `100000`.
450448

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

456453
[[ref-ad-settings]]
457454
[float]
@@ -690,7 +687,7 @@ Defaults to `100000`.
690687

691688
`cache.hash_algo`::
692689
(Expert Setting) Specifies the hashing algorithm that is used for
693-
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`.
694691

695692
`follow_referrals`::
696693
If set to `true` {security} follows referrals returned by the LDAP server.
@@ -1314,3 +1311,5 @@ List of IP addresses to allow for this profile.
13141311

13151312
`transport.profiles.$PROFILE.xpack.security.filter.deny`::
13161313
List of IP addresses to deny for this profile.
1314+
1315+
include::security-hash-settings.asciidoc[]

0 commit comments

Comments
 (0)