Skip to content

Commit 6f8ad24

Browse files
iigoninbennygoerzigKarstenSchnitterKai Sternad
committed
init FIPS documentation
Signed-off-by: Igonin <[email protected]> Co-authored-by: Benny Goerzig <[email protected]> Co-authored-by: Karsten Schnitter <[email protected]> Co-authored-by: Kai Sternad <[email protected]>
1 parent 5708ac6 commit 6f8ad24

File tree

1 file changed

+178
-0
lines changed

1 file changed

+178
-0
lines changed

‎_getting-started/fips.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
---
2+
layout: default
3+
title: Getting started with OpenSearch FIPS
4+
nav_order: 70
5+
---
6+
7+
# Getting started with OpenSearch FIPS
8+
9+
The Federal Information Processing Standard (FIPS) 140-2 is a U.S. government standard that defines security requirements for cryptographic modules. When running OpenSearch in a FIPS-compliant environment, you need to configure the system to use FIPS-validated cryptographic providers.
10+
11+
To achieve FIPS compliance, OpenSearch requires:
12+
13+
- FIPS-validated cryptographic providers for all cryptographic operations (Bouncy Castle FIPS is included with OpenSearch)
14+
- JVM configured to use these FIPS-validated providers
15+
- FIPS-compliant key stores and trust stores in BCFKS or PKCS11 format
16+
- Strong passwords meeting FIPS minimum requirements (112 bits / approximately 14 characters)
17+
18+
## FIPS demo installer
19+
20+
By default, the JVM uses the `cacerts` trust store (typically in PKCS12 format) for SSL/TLS connections, which contains trusted certificate authority (CA) certificates. However, the standard PKCS12 format is not FIPS-compliant.
21+
22+
OpenSearch includes a FIPS demo installer CLI tool that simplifies the trust store configuration process. This tool is located in `distribution/tools/fips-demo-installer-cli` and provides an automated way to set up a FIPS-compliant trust store by converting the JVM's default trust store to BCFKS format.
23+
24+
This tool is designed for demo and development purposes. Before deploying to production, carefully review all generated configuration and replace demo settings with production-appropriate values.
25+
{: .warning}
26+
27+
### Prerequisites
28+
29+
Before running the FIPS demo installer, ensure the following:
30+
31+
- OpenSearch is installed and the installation directory is accessible.
32+
- You have write permissions to the OpenSearch configuration directory.
33+
- The `jvm.options` file exists in the configuration directory.
34+
35+
### Available commands
36+
37+
The FIPS demo installer provides the following commands:
38+
39+
| Command | Description |
40+
|---------|-------------|
41+
| `generated` | Generate a new BCFKS trust store from the JVM default trust store |
42+
| `system` | Use existing system PKCS11 trust store |
43+
| `show-providers` | Show available security providers and exit (no configuration changes) |
44+
45+
### Configuration options
46+
47+
The FIPS demo installer supports the following command-line options:
48+
49+
| Option | Description |
50+
|--------|-------------|
51+
| `-f`, `--force` | Force configuration even if FIPS settings already exist in jvm.options |
52+
| `-n`, `--non-interactive` | Run in non-interactive mode (use defaults, no prompts) |
53+
| `-p`, `--password` | Password for the BCFKS trust store (overrides auto-generated password in non-interactive mode) |
54+
| `--pkcs11-provider` | Specify a PKCS11 provider name directly (used with `system` command) |
55+
| `--help` | Display help information for commands |
56+
57+
### Non-interactive mode
58+
59+
To run the installer in non-interactive mode for automated deployments, use the `-n` or `--non-interactive` flag:
60+
61+
```
62+
./bin/opensearch-fips-demo-installer -n
63+
```
64+
{% include copy.html %}
65+
66+
The non-interactive mode runs without prompts and automatically performs the following:
67+
68+
- Defaults to generating a new BCFKS trust store
69+
- Auto-confirms all prompts
70+
- Generates a secure 24-character password (or uses one specified with `-p`)
71+
- Selects the first available PKCS11 provider when using the `system` command
72+
73+
Non-interactive mode is ideal for automated provisioning scripts and configuration management tools.
74+
{: .note}
75+
76+
### Examples
77+
78+
Here are some common command variations for the FIPS demo installer:
79+
80+
On Windows, use `opensearch-fips-demo-installer.bat` instead of the shell script.
81+
{: .note}
82+
83+
```bash
84+
# Interactive mode (prompts for all choices)
85+
./bin/opensearch-fips-demo-installer
86+
87+
# Non-interactive mode with auto-generated password - overrides existing FIPS configuration
88+
./bin/opensearch-fips-demo-installer -n -f
89+
90+
# Generate BCFKS trust store with custom password
91+
./bin/opensearch-fips-demo-installer generated -p "MySecurePassword123!"
92+
93+
# Use system PKCS11 trust store with specific provider
94+
./bin/opensearch-fips-demo-installer system --pkcs11-provider YourPKCS11-Provider
95+
```
96+
{% include copy.html %}
97+
98+
### Configuration output
99+
100+
After running the FIPS demo installer, the following properties are added to your `jvm.options` file:
101+
102+
```
103+
################################################################
104+
## Start OpenSearch FIPS Demo Configuration
105+
## WARNING: revise all the lines below before you go into production
106+
################################################################
107+
108+
-Djavax.net.ssl.trustStore=/path/to/opensearch/config/opensearch-fips-truststore.bcfks
109+
-Djavax.net.ssl.trustStorePassword=<your-password>
110+
-Djavax.net.ssl.trustStoreType=BCFKS
111+
-Djavax.net.ssl.trustStoreProvider=BCFIPS
112+
################################################################
113+
```
114+
115+
These properties configure the JVM to use the FIPS-compliant trust store for all SSL/TLS connections if no other trust store is defined.
116+
117+
## Troubleshooting FIPS
118+
119+
This section covers common issues when running OpenSearch in FIPS mode.
120+
121+
### Trust store type not specified
122+
123+
```
124+
Trust store type must be specified using the '-Djavax.net.ssl.trustStoreType' JVM option. Accepted values are PKCS11 and BCFKS.
125+
```
126+
127+
This error indicates that the FIPS trust store configuration is incomplete or missing from `jvm.options`. To resolve this issue:
128+
129+
- Verify that you have run the FIPS demo installer successfully.
130+
- Check that `jvm.options` contains the FIPS trust store configuration block.
131+
132+
### Trust store file not found
133+
134+
If you see an error indicating the trust store file cannot be found, verify that:
135+
136+
- The path in `jvm.options` is correct and absolute.
137+
- The trust store file exists at the specified location.
138+
- OpenSearch has read permissions for the trust store file.
139+
140+
### Certificate conversion failures
141+
142+
Some certificates in the JVM default trust store may not be compatible with BCFKS format. The installer will report how many certificates were successfully converted. Review the output to ensure critical certificates were converted successfully.
143+
144+
### Keystore password too weak for FIPS mode
145+
146+
If OpenSearch fails to start with the error:
147+
148+
```
149+
org.bouncycastle.crypto.fips.FipsUnapprovedOperationError: password must be at least 112 bits
150+
```
151+
152+
This error occurs when the [OpenSearch keystore]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/security-settings/#password-protection) `$OPENSEARCH_HOME/config/opensearch.keystore` has a password that does not meet FIPS requirements. In FIPS mode, Bouncy Castle enforces a minimum password strength of 112 bits, which is approximately 14 characters.
153+
154+
Because FIPS mode is already active, the `opensearch-keystore passwd` command will not accept the existing weak password. The workaround is to recreate the keystore:
155+
156+
```bash
157+
# List existing secrets for backup (if needed)
158+
./bin/opensearch-keystore list
159+
160+
# Create a new keystore with a FIPS-compliant password (at least 14 characters)
161+
./bin/opensearch-keystore create --password
162+
163+
# Re-add any secrets that were stored in the old keystore (if needed)
164+
./bin/opensearch-keystore add <setting-name>
165+
```
166+
{% include copy.html %}
167+
168+
Ensure your new password is at least 14 characters long and includes a mix of uppercase, lowercase, numbers, and special characters. For security best practices, consider using a password manager to generate and store complex passwords.
169+
{: .note}
170+
171+
## Next steps
172+
173+
After configuring FIPS mode for OpenSearch:
174+
175+
- Review the [Security configuration]({{site.url}}{{site.baseurl}}/security/configuration/index/) guide for additional security settings.
176+
- Configure [TLS certificates]({{site.url}}{{site.baseurl}}/security/configuration/tls/) for node-to-node and client-to-node encryption.
177+
- Set up [authentication and authorization]({{site.url}}{{site.baseurl}}/security/configuration/configuration/) for your cluster.
178+
- Review [Best practices for OpenSearch security]({{site.url}}{{site.baseurl}}/security/configuration/best-practices/) for comprehensive security guidance.

0 commit comments

Comments
 (0)