- Elasticsearch Guide: other versions:
- What is Elasticsearch?
- What’s new in 8.14
- Quickstart
- Set up Elasticsearch
- Installing Elasticsearch
- Configuring Elasticsearch
- Important Elasticsearch configuration
- Secure settings
- Auditing settings
- Circuit breaker settings
- Cluster-level shard allocation and routing settings
- Miscellaneous cluster settings
- Cross-cluster replication settings
- Discovery and cluster formation settings
- Field data cache settings
- Health Diagnostic settings
- Index lifecycle management settings
- Data stream lifecycle settings
- Index management settings
- Index recovery settings
- Indexing buffer settings
- License settings
- Local gateway settings
- Logging
- Machine learning settings
- Monitoring settings
- Nodes
- Networking
- Node query cache settings
- Search settings
- Security settings
- Shard allocation, relocation, and recovery
- Shard request cache settings
- Snapshot and restore settings
- Transforms settings
- Thread pools
- Watcher settings
- Advanced configuration
- Important system configuration
- Bootstrap Checks
- Heap size check
- File descriptor check
- Memory lock check
- Maximum number of threads check
- Max file size check
- Maximum size virtual memory check
- Maximum map count check
- Client JVM check
- Use serial collector check
- System call filter check
- OnError and OnOutOfMemoryError checks
- Early-access check
- All permission check
- Discovery configuration check
- Bootstrap Checks for X-Pack
- Starting Elasticsearch
- Stopping Elasticsearch
- Discovery and cluster formation
- Add and remove nodes in your cluster
- Full-cluster restart and rolling restart
- Remote clusters
- Plugins
- Upgrade Elasticsearch
- Index modules
- Mapping
- Dynamic mapping
- Explicit mapping
- Runtime fields
- Field data types
- Aggregate metric
- Alias
- Arrays
- Binary
- Boolean
- Completion
- Date
- Date nanoseconds
- Dense vector
- Flattened
- Geopoint
- Geoshape
- Histogram
- IP
- Join
- Keyword
- Nested
- Numeric
- Object
- Percolator
- Point
- Range
- Rank feature
- Rank features
- Search-as-you-type
- Semantic text
- Shape
- Sparse vector
- Text
- Token count
- Unsigned long
- Version
- Metadata fields
- Mapping parameters
- Mapping limit settings
- Removal of mapping types
- Text analysis
- Overview
- Concepts
- Configure text analysis
- Built-in analyzer reference
- Tokenizer reference
- Token filter reference
- Apostrophe
- ASCII folding
- CJK bigram
- CJK width
- Classic
- Common grams
- Conditional
- Decimal digit
- Delimited payload
- Dictionary decompounder
- Edge n-gram
- Elision
- Fingerprint
- Flatten graph
- Hunspell
- Hyphenation decompounder
- Keep types
- Keep words
- Keyword marker
- Keyword repeat
- KStem
- Length
- Limit token count
- Lowercase
- MinHash
- Multiplexer
- N-gram
- Normalization
- Pattern capture
- Pattern replace
- Phonetic
- Porter stem
- Predicate script
- Remove duplicates
- Reverse
- Shingle
- Snowball
- Stemmer
- Stemmer override
- Stop
- Synonym
- Synonym graph
- Trim
- Truncate
- Unique
- Uppercase
- Word delimiter
- Word delimiter graph
- Character filters reference
- Normalizers
- Index templates
- Data streams
- Ingest pipelines
- Example: Parse logs
- Enrich your data
- Processor reference
- Append
- Attachment
- Bytes
- Circle
- Community ID
- Convert
- CSV
- Date
- Date index name
- Dissect
- Dot expander
- Drop
- Enrich
- Fail
- Fingerprint
- Foreach
- Geo-grid
- GeoIP
- Grok
- Gsub
- HTML strip
- Inference
- Join
- JSON
- KV
- Lowercase
- Network direction
- Pipeline
- Redact
- Registered domain
- Remove
- Rename
- Reroute
- Script
- Set
- Set security user
- Sort
- Split
- Trim
- Uppercase
- URL decode
- URI parts
- User agent
- Ingest pipelines in Search
- Aliases
- Search your data
- Query DSL
- Aggregations
- Bucket aggregations
- Adjacency matrix
- Auto-interval date histogram
- Categorize text
- Children
- Composite
- Date histogram
- Date range
- Diversified sampler
- Filter
- Filters
- Frequent item sets
- Geo-distance
- Geohash grid
- Geohex grid
- Geotile grid
- Global
- Histogram
- IP prefix
- IP range
- Missing
- Multi Terms
- Nested
- Parent
- Random sampler
- Range
- Rare terms
- Reverse nested
- Sampler
- Significant terms
- Significant text
- Terms
- Time series
- Variable width histogram
- Subtleties of bucketing range fields
- Metrics aggregations
- Pipeline aggregations
- Average bucket
- Bucket script
- Bucket count K-S test
- Bucket correlation
- Bucket selector
- Bucket sort
- Change point
- Cumulative cardinality
- Cumulative sum
- Derivative
- Extended stats bucket
- Inference bucket
- Max bucket
- Min bucket
- Moving function
- Moving percentiles
- Normalize
- Percentiles bucket
- Serial differencing
- Stats bucket
- Sum bucket
- Bucket aggregations
- Geospatial analysis
- EQL
- ES|QL
- SQL
- Overview
- Getting Started with SQL
- Conventions and Terminology
- Security
- SQL REST API
- SQL Translate API
- SQL CLI
- SQL JDBC
- SQL ODBC
- SQL Client Applications
- SQL Language
- Functions and Operators
- Comparison Operators
- Logical Operators
- Math Operators
- Cast Operators
- LIKE and RLIKE Operators
- Aggregate Functions
- Grouping Functions
- Date/Time and Interval Functions and Operators
- Full-Text Search Functions
- Mathematical Functions
- String Functions
- Type Conversion Functions
- Geo Functions
- Conditional Functions And Expressions
- System Functions
- Reserved keywords
- SQL Limitations
- Scripting
- Data management
- ILM: Manage the index lifecycle
- Tutorial: Customize built-in policies
- Tutorial: Automate rollover
- Index management in Kibana
- Overview
- Concepts
- Index lifecycle actions
- Configure a lifecycle policy
- Migrate index allocation filters to node roles
- Troubleshooting index lifecycle management errors
- Start and stop index lifecycle management
- Manage existing indices
- Skip rollover
- Restore a managed data stream or index
- Data tiers
- Autoscaling
- Monitor a cluster
- Roll up or transform your data
- Set up a cluster for high availability
- Snapshot and restore
- Secure the Elastic Stack
- Elasticsearch security principles
- Start the Elastic Stack with security enabled automatically
- Manually configure security
- Updating node security certificates
- User authentication
- Built-in users
- Service accounts
- Internal users
- Token-based authentication services
- User profiles
- Realms
- Realm chains
- Security domains
- Active Directory user authentication
- File-based user authentication
- LDAP user authentication
- Native user authentication
- OpenID Connect authentication
- PKI user authentication
- SAML authentication
- Kerberos authentication
- JWT authentication
- Integrating with other authentication systems
- Enabling anonymous access
- Looking up users without authentication
- Controlling the user cache
- Configuring SAML single-sign-on on the Elastic Stack
- Configuring single sign-on to the Elastic Stack using OpenID Connect
- User authorization
- Built-in roles
- Defining roles
- Role restriction
- Security privileges
- Document level security
- Field level security
- Granting privileges for data streams and aliases
- Mapping users and groups to roles
- Setting up field and document level security
- Submitting requests on behalf of other users
- Configuring authorization delegation
- Customizing roles and authorization
- Enable audit logging
- Restricting connections with IP filtering
- Securing clients and integrations
- Operator privileges
- Troubleshooting
- Some settings are not returned via the nodes settings API
- Authorization exceptions
- Users command fails due to extra arguments
- Users are frequently locked out of Active Directory
- Certificate verification fails for curl on Mac
- SSLHandshakeException causes connections to fail
- Common SSL/TLS exceptions
- Common Kerberos exceptions
- Common SAML issues
- Internal Server Error in Kibana
- Setup-passwords command fails due to connection failure
- Failures due to relocation of the configuration files
- Limitations
- Watcher
- Command line tools
- elasticsearch-certgen
- elasticsearch-certutil
- elasticsearch-create-enrollment-token
- elasticsearch-croneval
- elasticsearch-keystore
- elasticsearch-node
- elasticsearch-reconfigure-node
- elasticsearch-reset-password
- elasticsearch-saml-metadata
- elasticsearch-service-tokens
- elasticsearch-setup-passwords
- elasticsearch-shard
- elasticsearch-syskeygen
- elasticsearch-users
- How to
- Troubleshooting
- Fix common cluster issues
- Diagnose unassigned shards
- Add a missing tier to the system
- Allow Elasticsearch to allocate the data in the system
- Allow Elasticsearch to allocate the index
- Indices mix index allocation filters with data tiers node roles to move through data tiers
- Not enough nodes to allocate all shard replicas
- Total number of shards for an index on a single node exceeded
- Total number of shards per node has been reached
- Troubleshooting corruption
- Fix data nodes out of disk
- Fix master nodes out of disk
- Fix other role nodes out of disk
- Start index lifecycle management
- Start Snapshot Lifecycle Management
- Restore from snapshot
- Troubleshooting broken repositories
- Addressing repeated snapshot policy failures
- Troubleshooting an unstable cluster
- Troubleshooting discovery
- Troubleshooting monitoring
- Troubleshooting transforms
- Troubleshooting Watcher
- Troubleshooting searches
- Troubleshooting shards capacity health issues
- Troubleshooting an unbalanced cluster
- Capture diagnostics
- REST APIs
- API conventions
- Common options
- REST API compatibility
- Autoscaling APIs
- Behavioral Analytics APIs
- Compact and aligned text (CAT) APIs
- cat aliases
- cat allocation
- cat anomaly detectors
- cat component templates
- cat count
- cat data frame analytics
- cat datafeeds
- cat fielddata
- cat health
- cat indices
- cat master
- cat nodeattrs
- cat nodes
- cat pending tasks
- cat plugins
- cat recovery
- cat repositories
- cat segments
- cat shards
- cat snapshots
- cat task management
- cat templates
- cat thread pool
- cat trained model
- cat transforms
- Cluster APIs
- Cluster allocation explain
- Cluster get settings
- Cluster health
- Health
- Cluster reroute
- Cluster state
- Cluster stats
- Cluster update settings
- Nodes feature usage
- Nodes hot threads
- Nodes info
- Prevalidate node removal
- Nodes reload secure settings
- Nodes stats
- Cluster Info
- Pending cluster tasks
- Remote cluster info
- Task management
- Voting configuration exclusions
- Create or update desired nodes
- Get desired nodes
- Delete desired nodes
- Get desired balance
- Reset desired balance
- Cross-cluster replication APIs
- Connector APIs
- Create connector
- Delete connector
- Get connector
- List connectors
- Update connector API key id
- Update connector configuration
- Update connector index name
- Update connector filtering
- Update connector name and description
- Update connector pipeline
- Update connector scheduling
- Update connector service type
- Create connector sync job
- Cancel connector sync job
- Delete connector sync job
- Get connector sync job
- List connector sync jobs
- Check in a connector
- Update connector error
- Update connector last sync stats
- Update connector status
- Check in connector sync job
- Set connector sync job error
- Set connector sync job stats
- Data stream APIs
- Document APIs
- Enrich APIs
- EQL APIs
- ES|QL APIs
- Features APIs
- Fleet APIs
- Graph explore API
- Index APIs
- Alias exists
- Aliases
- Analyze
- Analyze index disk usage
- Clear cache
- Clone index
- Close index
- Create index
- Create or update alias
- Create or update component template
- Create or update index template
- Create or update index template (legacy)
- Delete component template
- Delete dangling index
- Delete alias
- Delete index
- Delete index template
- Delete index template (legacy)
- Exists
- Field usage stats
- Flush
- Force merge
- Get alias
- Get component template
- Get field mapping
- Get index
- Get index settings
- Get index template
- Get index template (legacy)
- Get mapping
- Import dangling index
- Index recovery
- Index segments
- Index shard stores
- Index stats
- Index template exists (legacy)
- List dangling indices
- Open index
- Refresh
- Resolve index
- Resolve cluster
- Rollover
- Shrink index
- Simulate index
- Simulate template
- Split index
- Unfreeze index
- Update index settings
- Update mapping
- Index lifecycle management APIs
- Create or update lifecycle policy
- Get policy
- Delete policy
- Move to step
- Remove policy
- Retry policy
- Get index lifecycle management status
- Explain lifecycle
- Start index lifecycle management
- Stop index lifecycle management
- Migrate indices, ILM policies, and legacy, composable and component templates to data tiers routing
- Inference APIs
- Info API
- Ingest APIs
- Licensing APIs
- Logstash APIs
- Machine learning APIs
- Machine learning anomaly detection APIs
- Add events to calendar
- Add jobs to calendar
- Close jobs
- Create jobs
- Create calendars
- Create datafeeds
- Create filters
- Delete calendars
- Delete datafeeds
- Delete events from calendar
- Delete filters
- Delete forecasts
- Delete jobs
- Delete jobs from calendar
- Delete model snapshots
- Delete expired data
- Estimate model memory
- Flush jobs
- Forecast jobs
- Get buckets
- Get calendars
- Get categories
- Get datafeeds
- Get datafeed statistics
- Get influencers
- Get jobs
- Get job statistics
- Get model snapshots
- Get model snapshot upgrade statistics
- Get overall buckets
- Get scheduled events
- Get filters
- Get records
- Open jobs
- Post data to jobs
- Preview datafeeds
- Reset jobs
- Revert model snapshots
- Start datafeeds
- Stop datafeeds
- Update datafeeds
- Update filters
- Update jobs
- Update model snapshots
- Upgrade model snapshots
- Machine learning data frame analytics APIs
- Create data frame analytics jobs
- Delete data frame analytics jobs
- Evaluate data frame analytics
- Explain data frame analytics
- Get data frame analytics jobs
- Get data frame analytics jobs stats
- Preview data frame analytics
- Start data frame analytics jobs
- Stop data frame analytics jobs
- Update data frame analytics jobs
- Machine learning trained model APIs
- Clear trained model deployment cache
- Create or update trained model aliases
- Create part of a trained model
- Create trained models
- Create trained model vocabulary
- Delete trained model aliases
- Delete trained models
- Get trained models
- Get trained models stats
- Infer trained model
- Start trained model deployment
- Stop trained model deployment
- Update trained model deployment
- Migration APIs
- Node lifecycle APIs
- Query rules APIs
- Reload search analyzers API
- Repositories metering APIs
- Rollup APIs
- Root API
- Script APIs
- Search APIs
- Search Application APIs
- Searchable snapshots APIs
- Security APIs
- Authenticate
- Change passwords
- Clear cache
- Clear roles cache
- Clear privileges cache
- Clear API key cache
- Clear service account token caches
- Create API keys
- Create or update application privileges
- Create or update role mappings
- Create or update roles
- Create or update users
- Create service account tokens
- Delegate PKI authentication
- Delete application privileges
- Delete role mappings
- Delete roles
- Delete service account token
- Delete users
- Disable users
- Enable users
- Enroll Kibana
- Enroll node
- Get API key information
- Get application privileges
- Get builtin privileges
- Get role mappings
- Get roles
- Get service accounts
- Get service account credentials
- Get Security settings
- Get token
- Get user privileges
- Get users
- Grant API keys
- Has privileges
- Invalidate API key
- Invalidate token
- OpenID Connect prepare authentication
- OpenID Connect authenticate
- OpenID Connect logout
- Query API key information
- Query User
- Update API key
- Update Security settings
- Bulk update API keys
- SAML prepare authentication
- SAML authenticate
- SAML logout
- SAML invalidate
- SAML complete logout
- SAML service provider metadata
- SSL certificate
- Activate user profile
- Disable user profile
- Enable user profile
- Get user profiles
- Suggest user profile
- Update user profile data
- Has privileges user profile
- Create Cross-Cluster API key
- Update Cross-Cluster API key
- Snapshot and restore APIs
- Snapshot lifecycle management APIs
- SQL APIs
- Synonyms APIs
- Text structure APIs
- Transform APIs
- Usage API
- Watcher APIs
- Definitions
- Migration guide
- Release notes
- Elasticsearch version 8.14.3
- Elasticsearch version 8.14.2
- Elasticsearch version 8.14.1
- Elasticsearch version 8.14.0
- Elasticsearch version 8.13.4
- Elasticsearch version 8.13.3
- Elasticsearch version 8.13.2
- Elasticsearch version 8.13.1
- Elasticsearch version 8.13.0
- Elasticsearch version 8.12.2
- Elasticsearch version 8.12.1
- Elasticsearch version 8.12.0
- Elasticsearch version 8.11.4
- Elasticsearch version 8.11.3
- Elasticsearch version 8.11.2
- Elasticsearch version 8.11.1
- Elasticsearch version 8.11.0
- Elasticsearch version 8.10.4
- Elasticsearch version 8.10.3
- Elasticsearch version 8.10.2
- Elasticsearch version 8.10.1
- Elasticsearch version 8.10.0
- Elasticsearch version 8.9.2
- Elasticsearch version 8.9.1
- Elasticsearch version 8.9.0
- Elasticsearch version 8.8.2
- Elasticsearch version 8.8.1
- Elasticsearch version 8.8.0
- Elasticsearch version 8.7.1
- Elasticsearch version 8.7.0
- Elasticsearch version 8.6.2
- Elasticsearch version 8.6.1
- Elasticsearch version 8.6.0
- Elasticsearch version 8.5.3
- Elasticsearch version 8.5.2
- Elasticsearch version 8.5.1
- Elasticsearch version 8.5.0
- Elasticsearch version 8.4.3
- Elasticsearch version 8.4.2
- Elasticsearch version 8.4.1
- Elasticsearch version 8.4.0
- Elasticsearch version 8.3.3
- Elasticsearch version 8.3.2
- Elasticsearch version 8.3.1
- Elasticsearch version 8.3.0
- Elasticsearch version 8.2.3
- Elasticsearch version 8.2.2
- Elasticsearch version 8.2.1
- Elasticsearch version 8.2.0
- Elasticsearch version 8.1.3
- Elasticsearch version 8.1.2
- Elasticsearch version 8.1.1
- Elasticsearch version 8.1.0
- Elasticsearch version 8.0.1
- Elasticsearch version 8.0.0
- Elasticsearch version 8.0.0-rc2
- Elasticsearch version 8.0.0-rc1
- Elasticsearch version 8.0.0-beta1
- Elasticsearch version 8.0.0-alpha2
- Elasticsearch version 8.0.0-alpha1
- Dependencies and versions
FIPS 140-2
editFIPS 140-2
editThe 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. Elasticsearch offers a FIPS 140-2 compliant mode and as such can run in a FIPS 140-2 configured JVM.
The JVM bundled with Elasticsearch 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 Elasticsearch JVM support matrix for supported JVM configurations. See subscriptions for required licensing.
Compliance with FIPS 140-2 requires using only FIPS approved / NIST recommended cryptographic algorithms. Generally this can be done by the following:
- Installation and configuration of a FIPS certified Java security provider.
- Ensuring the configuration of Elasticsearch is FIPS 140-2 compliant as documented below.
-
Setting
xpack.security.fips_mode.enabled
totrue
inelasticsearch.yml
. Note - this setting alone is not sufficient to be compliant with FIPS 140-2.
Configuring Elasticsearch for FIPS 140-2
editDetailed instructions for the configuration required for FIPS 140-2 compliance is beyond the scope of this document. It is the responsibility of the user to ensure compliance with FIPS 140-2. Elasticsearch has been tested with a specific configuration described below. However, there are other configurations possible to achieve compliance.
The following is a high-level overview of the required configuration:
- Use an externally installed Java installation. The JVM bundled with Elasticsearch is not configured for FIPS 140-2.
-
Install a FIPS certified security provider .jar file(s) in Elasticsearch’s
lib
directory. - Configure Java to use a FIPS certified security provider (see below).
- Configure Elasticsearch’s security manager to allow use of the FIPS certified provider (see below).
- Ensure the keystore and truststore are configured correctly (see below).
- Ensure the TLS settings are configured correctly (see below).
- Ensure the password hashing settings are configured correctly (see below).
- Ensure the cached password hashing settings are configured correctly (see below).
-
Configure
elasticsearch.yml
to use FIPS 140-2 mode, see (below). - Verify the security provider is installed and configured correctly (see below).
- Review the upgrade considerations (see below) and limitations (see below).
Java security provider
editDetailed instructions for installation and configuration of a FIPS certified Java security provider is beyond the scope of this document. Specifically, a FIPS certified JCA and JSSE implementation is required so that the JVM uses FIPS validated implementations of NIST recommended cryptographic algorithms.
Elasticsearch has been tested with Bouncy Castle’s bc-fips 1.0.2.4 and bctls-fips 1.0.17. Please refer to the [Support Matrix] for details on which combinations of JVM and security provider are supported in FIPS mode. Elasticsearch does not ship with a FIPS certified provider. It is the responsibility of the user to install and configure the security provider to ensure compliance with FIPS 140-2. Using a FIPS certified provider will ensure that only approved cryptographic algorithms are used.
To configure Elasticsearch to use additional security provider(s) configure Elasticsearch’s JVM property java.security.properties
to point to a file
(example) in Elasticsearch’s
config
directory. Ensure the FIPS certified security provider is configured with the lowest order. This file should contain the necessary
configuration to instruct Java to use the FIPS certified security provider.
Java security manager
editAll code running in Elasticsearch is subject to the security restrictions enforced by the Java security manager. The security provider you have installed and configured may require additional permissions in order to function correctly. You can grant these permissions by providing your own Java security policy
To configure Elasticsearch’s security manager configure the JVM property java.security.policy
to point a file
(example)in Elasticsearch’s
config
directory with the desired permissions. This file should contain the necessary configuration for the Java security manager
to grant the required permissions needed by the security provider.
Elasticsearch Keystore
editFIPS 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 Elasticsearch keystore that stores the node’s 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 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.
TLS
editSSLv2 and SSLv3 are not allowed by FIPS 140-2, so SSLv2Hello
and SSLv3
cannot
be used for ssl.supported_protocols
.
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 Elasticsearch are FIPS 140-2 compliant and as such can be
used in a FIPS 140-2 JVM. See ssl.cipher_suites
.
TLS keystores and keys
editKeystores can be used in a number of General 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:
Table 81. Comparable key strengths
Symmetric Key Algorithm |
RSA key Length |
ECC key length |
|
2048 |
224-255 |
|
3072 |
256-383 |
|
15630 |
512+ |
Stored password hashing
editWhile Elasticsearch 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
112-bit key strength requirement. Although FIPS 140-2
does not mandate user password standards, this requirement may affect password
hashing in Elasticsearch. To comply with this requirement,
while allowing you to use passwords that satisfy your security policy, Elasticsearch offers
pbkdf2_stretch which is the suggested hashing algorithm when running
Elasticsearch 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.
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 User cache and password hash algorithms.
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 elasticsearch-user CLI tool for the file realm and the create users and change password APIs for the native and reserved realms. Other types of realms are not affected and do not require any changes.
Cached password hashing
editssha256
(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 User cache and password hash algorithms.
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.
Configure Elasticsearch elasticsearch.yml
edit-
Set
xpack.security.fips_mode.enabled
totrue
inelasticsearch.yml
. This setting is used to ensure to configure some internal configuration to be FIPS 140-2 compliant and provides some additional verification. -
Set
xpack.security.autoconfiguration.enabled
tofalse
. This will disable the automatic configuration of the security settings. Users must ensure that the security settings are configured correctly for FIPS-140-2 compliance. This is only applicable for new installations. -
Set
xpack.security.authc.password_hashing.algorithm
appropriately see above. - Other relevant security settings. For example, TLS for the transport and HTTP interfaces. (not explicitly covered here or in the example below)
-
Optional: Set
xpack.security.fips_mode.required_providers
inelasticsearch.yml
to ensure the required security providers (8.13+). see below.
xpack.security.fips_mode.enabled: true xpack.security.autoconfiguration.enabled: false xpack.security.fips_mode.required_providers: ["BCFIPS", "BCJSSE"] xpack.security.authc.password_hashing.algorithm: "pbkdf2_stretch"
Verify the security provider is installed
editTo verify that the security provider is installed and in use, you can use any of the following steps:
-
Verify the required security providers are configured with the lowest order in the file pointed to by
java.security.properties
. For example,security.provider.1
is a lower order thansecurity.provider.2
-
Set
xpack.security.fips_mode.required_providers
inelasticsearch.yml
to the list of required security providers. This setting is used to ensure that the correct security provider is installed and configured. (8.13+) If the security provider is not installed correctly, Elasticsearch will fail to start.["BCFIPS", "BCJSSE"]
are the values to use for Bouncy Castle’s FIPS JCE and JSSE certified provider.
Upgrade considerations
editElasticsearch 8.0+ requires Java 17 or later. Elasticsearch 8.13+ has been tested with Bouncy Castle's Java 17 certified FIPS implementation and is the recommended Java security provider when running Elasticsearch in FIPS 140-2 mode. Note - Elasticsearch does not ship with a FIPS certified security provider and requires explicit installation and configuration.
Alternatively, consider using Elasticsearch Service in the FedRAMP-certified GovCloud region.
Some encryption algorithms may no longer be available by default in updated FIPS 140-2 security providers. Notably, Triple DES and PKCS1.5 RSA are now discouraged and Bouncy Castle now requires explicit configuration to continue using these algorithms.
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, Elasticsearch:
- Upgrades 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 Elasticsearch Keystore.
- Upgrades self-generated trial licenses to the latest FIPS 140-2 compliant format.
If your 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.
Limitations
editDue 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
elasticsearch-certutil
tool. However,elasticsearch-certutil
can very well be used in a non FIPS 140-2 configured JVM (pointingES_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.
On this page