Elasticsearch: Improve documentation for FIPS 140-2

[msimos]

Describe the feature:

Our FIPS 140-2 documentation doesn't have any instructions on how to setup Java for FIPS 140-2. And from other sources doesn't seem to be that well documented either (at least I found them confusing). From what I can tell there's two possible ways to do that. Either using SunPKCS11 with NSS or BouncyCastle. However from our documentation its not clear as to which is supported/preferred/tested. Also how one would go about creating a supported keystore/trustore. As from what I have read to do so using the keytool command requires some additional parameters like -providerClass and -storeType. So it would be useful to have a step-by-step guide to configuring OpenJDK/OracleJDK to setting up FIPS 140-2, creating keystore/truststore or using PEM.

Also one possible alternative, to using two Java installations for using elasticsearch-plugin or elasticsearch-certutil is to use:

ES_JAVA_OPTS="-Djava.security.properties=/path/to/java.security" elasticsearch-plugin install <plugin-name>

By specifying an alternate java.security without the FIPS 140-2 configuration. Which maybe easier for end users then setting up an entire separate JAVA and using a different JAVA_HOME.

Elasticsearch version (bin/elasticsearch --version):

Elasticsearch 6.5.2

Plugins installed: []

JVM version (java -version):

OpenJDK 1.8

OS version (uname -a if on a Unix-like system):

Any

[elasticmachine]

Pinging @elastic/es-security

[jkakavas]

The decision to not cover the FIPS 140-2 setup in the documentation was a conscious one. We believed that the process is complicated enough to be laid out in our documentation and that users that would need to use Elasticsearch in a FIPS 140-2 environment would already have that environment in place and would be familiar with its intricacies.

Either using SunPKCS11 with NSS or BouncyCastle

Yes, that is correct. These are the 2 most widely used security provider implementations that offer a fips 140 mode.

Also one possible alternative, to using two Java installations for using elasticsearch-plugin or elasticsearch-certutil is to use:

ES_JAVA_OPTS="-Djava.security.properties=/path/to/java.security" elasticsearch-plugin install

By specifying an alternate java.security without the FIPS 140-2 configuration. Which maybe easier for end users then setting up an entire separate JAVA and using a different JAVA_HOME.

True. The (pointing JAVA_HOME environment variable to a different java installation) sentence was not meant to be the only or the definitive way to do so, just an example.

However from our documentation its not clear as to which is supported/preferred/tested.

I'll take it up to add a section about the limitations that are implied by using SunPCKS11-NSS (these are detailed in https://github.com/elastic/elasticsearch/issues/33459) to the docs.

I'll defer the question to how much in detail we should go about documenting a FIPS 140-2 JVM setup to @jaymode and @joshbressers for some thoughts and guidance.

[msimos]

I think we need some better documentation around this because as you mentioned the process is complicated. And I don't think we can assume that FIPS 140-2 is already setup or the end user is an expert in setting up FIPS 140-2 for Java. If the end user runs into a problem they can't compare their process with the steps we used to configure FIPS 140-2.

[debadair]

[docs issue triage]