188 lines
8.6 KiB
Plaintext
188 lines
8.6 KiB
Plaintext
[role="xpack"]
|
|
[[fips-140-compliance]]
|
|
=== FIPS 140-2
|
|
|
|
The Federal Information Processing Standard (FIPS) Publication 140-2, (FIPS PUB
|
|
140-2), titled "Security Requirements for Cryptographic Modules" is a U.S.
|
|
government computer security standard used to approve cryptographic modules.
|
|
{es} offers a FIPS 140-2 compliant mode and as such can run in a FIPS 140-2
|
|
configured JVM.
|
|
|
|
IMPORTANT: The JVM bundled with {es} is not configured for FIPS 140-2. You must
|
|
configure an external JDK with a FIPS 140-2 certified Java Security Provider.
|
|
Refer to the {es}
|
|
https://www.elastic.co/support/matrix#matrix_jvm[JVM support matrix] for
|
|
supported JVM configurations.
|
|
|
|
After configuring your JVM for FIPS 140-2, you can run {es} in FIPS 140-2 mode by
|
|
setting the `xpack.security.fips_mode.enabled` to `true` in `elasticsearch.yml`.
|
|
|
|
For {es}, adherence to FIPS 140-2 is ensured by:
|
|
|
|
- Using FIPS approved / NIST recommended cryptographic algorithms.
|
|
- Delegating the implementation of these cryptographic algorithms to a NIST
|
|
validated cryptographic module (available via the Java Security Provider
|
|
in use in the JVM).
|
|
- Allowing the configuration of {es} in a FIPS 140-2 compliant manner, as
|
|
documented below.
|
|
|
|
[discrete]
|
|
=== Upgrade considerations
|
|
|
|
[IMPORTANT]
|
|
====
|
|
include::fips-java17.asciidoc[]
|
|
====
|
|
|
|
|
|
If you plan to upgrade your existing cluster to a version that can be run in
|
|
a FIPS 140-2 configured JVM, we recommend to first perform a rolling
|
|
upgrade to the new version in your existing JVM and perform all necessary
|
|
configuration changes in preparation for running in FIPS 140-2 mode. You can then
|
|
perform a rolling restart of the nodes, starting each node in a FIPS 140-2 JVM.
|
|
During the restart, {es}:
|
|
|
|
- Upgrades <<secure-settings,secure settings>> to the latest, compliant format.
|
|
A FIPS 140-2 JVM cannot load previous format versions. If your keystore is
|
|
not password-protected, you must manually set a password. See
|
|
<<keystore-fips-password>>.
|
|
- Upgrades self-generated trial licenses to the latest FIPS 140-2 compliant format.
|
|
|
|
If your {subscriptions}[subscription] already supports FIPS 140-2 mode, you
|
|
can elect to perform a rolling upgrade while at the same time running each
|
|
upgraded node in a FIPS 140-2 JVM. In this case, you would need to also manually
|
|
regenerate your `elasticsearch.keystore` and migrate all secure settings to it,
|
|
in addition to the necessary configuration changes outlined below, before
|
|
starting each node.
|
|
|
|
[discrete]
|
|
=== Configuring {es} for FIPS 140-2
|
|
|
|
Apart from setting `xpack.security.fips_mode.enabled`, a number of security
|
|
related settings need to be configured accordingly in order to be compliant
|
|
and able to run {es} successfully in a FIPS 140-2 configured JVM.
|
|
|
|
[discrete]
|
|
[[keystore-fips-password]]
|
|
==== {es} Keystore
|
|
|
|
FIPS 140-2 (via NIST Special Publication 800-132) dictates that encryption keys should at
|
|
least have an effective strength of 112 bits.
|
|
As such, the {es} keystore that stores the node's <<secure-settings,secure settings>>
|
|
needs to be password protected with a password that satisfies this requirement.
|
|
This means that the password needs to be 14 bytes long which is equivalent
|
|
to a 14 character ASCII encoded password, or a 7 character UTF-8 encoded password.
|
|
You can use the <<elasticsearch-keystore, elasticsearch-keystore passwd>> subcommand to change or set the
|
|
password of an existing keystore.
|
|
Note that when the keystore is password-protected, you must supply the password each time
|
|
Elasticsearch starts.
|
|
|
|
[discrete]
|
|
==== TLS
|
|
|
|
SSLv2 and SSLv3 are not allowed by FIPS 140-2, so `SSLv2Hello` and `SSLv3` cannot
|
|
be used for <<ssl-tls-settings,`ssl.supported_protocols`>>.
|
|
|
|
NOTE: The use of TLS ciphers is mainly governed by the relevant crypto module
|
|
(the FIPS Approved Security Provider that your JVM uses). All the ciphers that
|
|
are configured by default in {es} are FIPS 140-2 compliant and as such can be
|
|
used in a FIPS 140-2 JVM. See <<ssl-tls-settings,`ssl.cipher_suites`>>.
|
|
|
|
[discrete]
|
|
==== TLS keystores and keys
|
|
|
|
Keystores can be used in a number of <<ssl-tls-settings>> in order to
|
|
conveniently store key and trust material. Neither `JKS`, nor `PKCS#12` keystores
|
|
can be used in a FIPS 140-2 configured JVM. Avoid using
|
|
these types of keystores. Your FIPS 140-2 provider may provide a compliant keystore
|
|
implementation that can be used, or you can use PEM encoded files. To use PEM encoded
|
|
key material, you can use the relevant `\*.key` and `*.certificate` configuration
|
|
options, and for trust material you can use `*.certificate_authorities`.
|
|
|
|
|
|
FIPS 140-2 compliance dictates that the length of the public keys used for TLS
|
|
must correspond to the strength of the symmetric key algorithm in use in TLS.
|
|
Depending on the value of `ssl.cipher_suites` that you select to use, the TLS
|
|
keys must have corresponding length according to the following table:
|
|
|
|
[[comparable-key-strength]]
|
|
.Comparable key strengths
|
|
|=======================
|
|
| Symmetric Key Algorithm | RSA key Length | ECC key length
|
|
| `3DES` | 2048 | 224-255
|
|
| `AES-128` | 3072 | 256-383
|
|
| `AES-256` | 15630 | 512+
|
|
|=======================
|
|
|
|
[discrete]
|
|
==== Stored password hashing
|
|
[[fips-stored-password-hashing]]
|
|
|
|
While {es} offers a number of algorithms for securely hashing credentials
|
|
on disk, only the `PBKDF2` based family of algorithms is compliant with FIPS
|
|
140-2 for stored password hashing. However, since `PBKDF2` is essentially a key derivation
|
|
function, your JVM security provider may enforce a
|
|
<<keystore-fips-password,112-bit key strength requirement>>. Although FIPS 140-2
|
|
does not mandate user password standards, this requirement may affect password
|
|
hashing in {es}. To comply with this requirement,
|
|
while allowing you to use passwords that satisfy your security policy, {es} offers
|
|
<<hashing-settings, pbkdf2_stretch>> which is the suggested hashing algorithm when running
|
|
{es} in FIPS 140-2 environments. `pbkdf2_stretch` performs a single round of SHA-512
|
|
on the user password before passing it to the `PBKDF2` implementation.
|
|
|
|
NOTE: You can still use one of the plain `pbkdf2` options instead of `pbkdf2_stretch` if
|
|
you have external policies and tools that can ensure all user passwords for the reserved,
|
|
native, and file realms are longer than 14 bytes.
|
|
|
|
You must set the `xpack.security.authc.password_hashing.algorithm` setting to one of the
|
|
available `pbkdf_stretch_*` values.
|
|
When FIPS-140 mode is enabled, the default value for
|
|
`xpack.security.authc.password_hashing.algorithm` is `pbkdf2_stretch`.
|
|
See <<hashing-settings>>.
|
|
|
|
Password hashing configuration changes are not retroactive so the stored hashed
|
|
credentials of existing users of the reserved, native, and file realms are not
|
|
updated on disk.
|
|
To ensure FIPS 140-2 compliance, recreate users or
|
|
change their password using the <<users-command, elasticsearch-user>> CLI tool
|
|
for the file realm and the <<security-api-put-user,create users>> and
|
|
<<security-api-change-password,change password>> APIs for the native and reserved realms.
|
|
Other types of realms are not affected and do not require any changes.
|
|
|
|
[discrete]
|
|
==== Cached password hashing
|
|
[[fips-cached-password-hashing]]
|
|
|
|
`ssha256` (salted `sha256`) is recommended for cache hashing. Though
|
|
`PBKDF2` is compliant with FIPS-140-2, it is -- by design -- slow, and
|
|
thus not generally suitable as a cache hashing algorithm. Cached
|
|
credentials are never stored on disk, and salted `sha256` provides an
|
|
adequate level of security for in-memory credential hashing, without
|
|
imposing prohibitive performance overhead. You _may_ use `PBKDF2`,
|
|
however you should carefully assess performance impact first. Depending
|
|
on your deployment, the overhead of `PBKDF2` could undo most of the
|
|
performance gain of using a cache.
|
|
|
|
Either set all `cache.hash_algo` settings to `ssha256` or leave
|
|
them undefined, since `ssha256` is the default value for all
|
|
`cache.hash_algo` settings. See <<hashing-settings>>.
|
|
|
|
The user cache will be emptied upon node restart, so any existing
|
|
hashes using non-compliant algorithms will be discarded and the new
|
|
ones will be created using the algorithm you have selected.
|
|
|
|
[discrete]
|
|
=== Limitations
|
|
|
|
Due to the limitations that FIPS 140-2 compliance enforces, a small number of
|
|
features are not available while running in FIPS 140-2 mode. The list is as follows:
|
|
|
|
* Azure Classic Discovery Plugin
|
|
* The <<certutil,`elasticsearch-certutil`>> tool. However,
|
|
`elasticsearch-certutil` can very well be used in a non FIPS 140-2
|
|
configured JVM (pointing `ES_JAVA_HOME` environment variable to a different
|
|
java installation) in order to generate the keys and certificates that
|
|
can be later used in the FIPS 140-2 configured JVM.
|
|
* The SQL CLI client cannot run in a FIPS 140-2 configured JVM while using
|
|
TLS for transport security or PKI for client authentication.
|