|
| 1 | +[role="xpack"] |
| 2 | +[[fips-140-compliance]] |
| 3 | +=== FIPS 140-2 |
| 4 | + |
| 5 | +The Federal Information Processing Standard (FIPS) Publication 140-2, (FIPS PUB |
| 6 | +140-2), titled "Security Requirements for Cryptographic Modules" is a U.S. |
| 7 | +government computer security standard used to approve cryptographic modules. |
| 8 | +{es} offers a FIPS 140-2 compliant mode and as such can run in a FIPS 140-2 |
| 9 | +enabled JVM. In order to set {es} in fips mode, you must set the |
| 10 | +`xpack.security.fips_mode.enabled` to `true` in `elasticsearch.yml` |
| 11 | + |
| 12 | +For {es}, FIPS 140-2 compliance is ensured by |
| 13 | + |
| 14 | +- Using FIPS approved / NIST recommended cryptographic algorithms. |
| 15 | +- Delegating the implementation of these cryptographic algorithms to a NIST |
| 16 | + validated cryptographic module (available via the Java Security Provider |
| 17 | + in use in the JVM). |
| 18 | +- Allowing the configuration of {es} in a FIPS 140-2 compliant manner, as |
| 19 | + documented below. |
| 20 | + |
| 21 | +[float] |
| 22 | +=== Upgrade considerations |
| 23 | + |
| 24 | +If you plan to upgrade your existing Cluster to a version that can be run in |
| 25 | +a FIPS 140-2 enabled JVM, the suggested approach is to first perform a rolling |
| 26 | +upgrade to the new version in your existing JVM and perform all necessary |
| 27 | +configuration changes in preparation for running in fips mode. You can then |
| 28 | +perform a rolling restart of the nodes, this time starting each node in the FIPS |
| 29 | +140-2 JVM. This will allow {es} to take care of a couple of things automatically for you: |
| 30 | + |
| 31 | +- <<secure-settings, Secure Settings>> will be upgraded to the latest format version as |
| 32 | + previous format versions cannot be loaded in a FIPS 140-2 JVM. |
| 33 | +- Self-generated trial licenses will be upgraded to the latest format that |
| 34 | + is compliant with FIPS 140-2. |
| 35 | + |
| 36 | +If you are on a appropriate license level (platinum) you can elect to perform |
| 37 | +a rolling upgrade while at the same time running each upgraded node in a |
| 38 | +FIPS 140-2 JVM. In this case, you would need to also regenerate your |
| 39 | +`elasticsearch.keystore` and migrate all secure settings to it, in addition to the |
| 40 | +necessary configuration changes outlined below, before starting each node. |
| 41 | + |
| 42 | +[float] |
| 43 | +=== Configuring {es} for FIPS 140-2 |
| 44 | + |
| 45 | +Apart from setting `xpack.security.fips_mode.enabled`, a number of security |
| 46 | +related settings need to be configured accordingly in order to be compliant |
| 47 | +and able to run {es} successfully in a FIPS 140-2 enabled JVM. |
| 48 | + |
| 49 | +[float] |
| 50 | +==== TLS |
| 51 | + |
| 52 | +SSLv2 and SSLv3 are not allowed by FIPS 140-2, so `SSLv2Hello` and `SSLv3` cannot |
| 53 | +be used for <<ssl-tls-settings, xpack.ssl.supported_protocols>> |
| 54 | + |
| 55 | +NOTE: The use of TLS ciphers is mainly governed by the relevant crypto module |
| 56 | +(the FIPS Approved Security Provider that your JVM uses). All the ciphers that |
| 57 | +are configured by default in {es} are FIPS 140-2 compliant and as such can be |
| 58 | +used in a FIPS 140-2 JVM. (see <<ssl-tls-settings, xpack.ssl.cipher_suites>>) |
| 59 | + |
| 60 | +[float] |
| 61 | +==== TLS Keystores and keys |
| 62 | + |
| 63 | +Keystores can be used in a number of <<ssl-tls-settings>> in order to |
| 64 | +conveniently store key and trust material. Neither `JKS`, nor `PKCS#12` keystores |
| 65 | +can be used in a FIPS 140-2 enabled JVM however, so you must refrain from using |
| 66 | +these keystores. Your FIPS 140-2 provider may provide a compliant keystore that |
| 67 | +can be used or you can use PEM encoded files. To use PEM encoded key material, |
| 68 | +you can use the relevant `\*.key` and `*.certificate` configuration |
| 69 | +options, and for trust material you can use `*.certificate_authorities`. |
| 70 | + |
| 71 | + |
| 72 | +FIPS 140-2 compliance dictates that the length of the public keys used for TLS |
| 73 | +must correspond to the strength of the symmetric key algorithm in use in TLS. |
| 74 | +Depending on the value of <<ssl-tls-settings, xpack.ssl.cipher_suites>> that |
| 75 | +you select to use, the TLS keys must have corresponding length according to |
| 76 | +the following table: |
| 77 | + |
| 78 | +[[comparable-key-strength]] |
| 79 | +.Comparable key strengths |
| 80 | +|======================= |
| 81 | +| Symmetric Key Algorithm | RSA key Length | ECC key length |
| 82 | +| `3DES` | 2048 | 224-255 |
| 83 | +| `AES-128` | 3072 | 256-383 |
| 84 | +| `AES-256` | 15630 | 512+ |
| 85 | +|======================= |
| 86 | + |
| 87 | +[float] |
| 88 | +==== Password Hashing |
| 89 | + |
| 90 | +{es} offers a number of algorithms for securely hashing credentials in memory and |
| 91 | +on disk. However, only the `PBKDF2` family of algorithms is compliant with FIPS |
| 92 | +140-2 for password hashing. You must set the the `cache.hash_algo` realm settings |
| 93 | +and the `xpack.security.authc.password_hashing.algorithm` setting to one of the |
| 94 | +available `PBKDF2` values. |
| 95 | +See <<hashing-settings>>. |
| 96 | + |
| 97 | +Password hashing configuration changes are not retroactive so the stored hashed |
| 98 | +credentials of existing users of the file and native realms will not be updated |
| 99 | +on disk. |
| 100 | +Authentication will still work, but in order to ensure FIPS 140-2 compliance, |
| 101 | +you would need to recreate users or change their password using the |
| 102 | +<<users-command, elasticsearch-user>> CLI tool for the file realm and the |
| 103 | +<<security-api-users,User Management APIs>> for the native realm. |
| 104 | + |
| 105 | +The user cache will be emptied upon node restart, so any existing hashes using |
| 106 | +non-compliant algorithms will be discarded and the new ones will be created |
| 107 | +using the compliant `PBKDF2` algorithm you have selected. |
| 108 | + |
| 109 | +[float] |
| 110 | +=== Limitations |
| 111 | + |
| 112 | +Due to the limitations that FIPS 140-2 compliance enforces, a small number of |
| 113 | +features are not available while running in fips mode. The list is as follows: |
| 114 | + |
| 115 | +* Azure Classic Discovery Plugin |
| 116 | +* Ingest Attachment Plugin |
| 117 | +* The {ref}/certutil.html[`elasticsearch-certutil`] tool. However, |
| 118 | + `elasticsearch-certutil` can very well be used in a non FIPS 140-2 |
| 119 | + enabled JVM (pointing `JAVA_HOME` environment variable to a different java |
| 120 | + installation) in order to generate the keys and certificates that |
| 121 | + can be later used in the FIPS 140-2 enabled JVM. |
| 122 | +* The `elasticsearch-plugin` tool. Accordingly, `elasticsearch-plugin` can be |
| 123 | + used with a different (non FIPS 140-2 enabled) Java installation if |
| 124 | + available. |
| 125 | +* The SQL CLI client cannot run in a FIPS 140-2 enabled JVM while using |
| 126 | + TLS for transport security or PKI for client authentication. |
| 127 | +* The SAML Realm cannot decrypt and consume encrypted Assertions or encrypted |
| 128 | + attributes in Attribute Statements from the SAML IdP. |
0 commit comments