honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[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.
This commit is contained in:
Ioannis Kakavas 2018-08-21 12:05:42 +03:00 committed by GitHub
parent 200078734c
commit 65d4f27873
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 116 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
docs/reference/settings/security-hash-settings.asciidoc Normal file
View File

@ -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.
|=======================

21
docs/reference/settings/security-settings.asciidoc
View File

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

0
x-pack/docs/en/rest-api/security/users.asciidoc Normal file
View File

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

@ -55,18 +55,23 @@ cluster.
+ +
-- --
The `users` file stores all the users and their passwords. Each line in the file 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] [source,bash]
---------------------------------------------------------------------- ----------------------------------------------------------------------
rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W rdeniro:$2a$10$BBJ/ILiyJ1eBTYoRKxkqbuDEdYECplvxnqQ47uiowE7yGqvCEgj9W
alpacino:$2a$10$cNwHnElYiMYZ/T3K4PvzGeJ1KbpXZp2PfoQD.gfaVdImnHOwIuBKS 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 editor, we strongly recommend using the <<users-command>> tool to apply the
required changes. 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` 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}, setting in the `elasticsearch.yml` file (as this is a common setting in {es},
changing its value may effect other schedules in the system). changing its value may effect other schedules in the system).
-- --

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

@ -34,6 +34,13 @@ xpack:
type: native type: native
order: 0 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}. . Restart {es}.

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

@ -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 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 salted `sha-256` hash algorithm. You can use a different hashing algorithm by
setting the `cache_hash_algo` setting to any of the following: setting the `cache.hash_algo` realm settings. See
{ref}/security-settings.html#hashing-settings[User cache and password hash algorithms].
[[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`).
|=======================
[[cache-eviction-api]] [[cache-eviction-api]]
==== Evicting users from the cache ==== Evicting users from the cache