OpenSearch/docs/reference/settings/common-defs.asciidoc

tag::ssl-certificate[]
Specifies the path for the PEM encoded certificate (or certificate chain) that is
associated with the key.
//TBD: This setting can be used only if `ssl.key` is set.
end::ssl-certificate[]

tag::ssl-certificate-authorities[]
List of paths to PEM encoded certificate files that should be trusted.
//TBD: You cannot use this setting and `ssl.truststore.path` at the same time.
end::ssl-certificate-authorities[]

tag::ssl-cipher-suites-values[]
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-cipher-suites-values-java11]
end::ssl-cipher-suites-values[]

tag::ssl-cipher-suites-values-java11[]
Supported cipher suites vary depending on which version of Java you use. For
example, for version 11 the default value is `TLS_AES_256_GCM_SHA384`, 
`TLS_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, 
`TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`,   
`TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, 
`TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, 
`TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`,  
`TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, 
`TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`,
`TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`,
`TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`,
`TLS_RSA_WITH_AES_128_CBC_SHA`.
+
--
NOTE: The default cipher suites list above includes TLSv1.3 ciphers and ciphers
that require the _Java Cryptography Extension (JCE) Unlimited Strength
Jurisdiction Policy Files_ for 256-bit AES encryption. If TLSv1.3 is not
available, the TLSv1.3 ciphers `TLS_AES_256_GCM_SHA384` and
`TLS_AES_128_GCM_SHA256` are not included in the default list. If 256-bit AES is
unavailable, ciphers with `AES_256` in their names are not included in the
default list. Finally, AES GCM has known performance issues in Java versions
prior to 11 and is included in the default list only when using Java 11 or above.

For more information, see Oracle's
https://docs.oracle.com/en/java/javase/11/security/oracle-providers.html#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2[Java Cryptography Architecture documentation].
--
end::ssl-cipher-suites-values-java11[]

tag::ssl-key-pem[]
Path to a PEM encoded file containing the private key.
//TBD: You cannot use this setting and `ssl.keystore.path` at the same time.
end::ssl-key-pem[]

tag::ssl-key-passphrase[]
The passphrase that is used to decrypt the private key. Since the key might not
be encrypted, this value is optional.
//TBD: You cannot use this setting and `ssl.secure_key_passphrase` at the same time.
end::ssl-key-passphrase[]

tag::ssl-keystore-key-password[]
The password for the key in the keystore. The default is the keystore password.
//TBD: You cannot use this setting and `ssl.keystore.secure_key_password` at the same time.
end::ssl-keystore-key-password[]

tag::ssl-keystore-password[]
The password for the keystore.
//TBD: You cannot use this setting and `ssl.keystore.secure_password` at the same time.
end::ssl-keystore-password[]

tag::ssl-keystore-path[]
The path for the keystore file that contains a private key and certificate.
//TBD: It must be either a Java keystore (jks) or a PKCS#12 file.
//TBD: You cannot use this setting and `ssl.key` at the same time.
end::ssl-keystore-path[]

tag::ssl-keystore-secure-key-password[]
The password for the key in the keystore. The default is the keystore password.
//TBD: You cannot use this setting and `ssl.keystore.key_password` at the same time.
end::ssl-keystore-secure-key-password[]

tag::ssl-keystore-secure-password[]
The password for the keystore.
//TBD: You cannot use this setting and `ssl.keystore.password` at the same time.
end::ssl-keystore-secure-password[]

tag::ssl-keystore-type-pkcs12[]
The format of the keystore file. It must be either `jks` or `PKCS12`. If the
keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults 
to `PKCS12`. Otherwise, it defaults to `jks`.
end::ssl-keystore-type-pkcs12[]

tag::ssl-secure-key-passphrase[]
The passphrase that is used to decrypt the private key. Since the key might not
be encrypted, this value is optional. 
//TBD: You cannot use this setting and `ssl.key_passphrase` at the same time.
end::ssl-secure-key-passphrase[]

tag::ssl-supported-protocols[]
Supported protocols with versions. Valid protocols: `SSLv2Hello`,
`SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM's SSL provider supports TLSv1.3,
the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is
`TLSv1.2,TLSv1.1`.
+
--
NOTE: If `xpack.security.fips_mode.enabled` is `true`, you cannot use `SSLv2Hello` 
or `SSLv3`. See <<fips-140-compliance>>.

--
end::ssl-supported-protocols[]

tag::ssl-truststore-password[]
The password for the truststore.
//TBD: You cannot use this setting and `ssl.truststore.secure_password` at the same time.
end::ssl-truststore-password[]

tag::ssl-truststore-path[]
The path for the keystore that contains the certificates to trust. It must be
either a Java keystore (jks) or a PKCS#12 file.
//TBD: You cannot use this setting and `ssl.certificate_authorities` at the same time.
end::ssl-truststore-path[]

tag::ssl-truststore-secure-password[]
Password for the truststore.
//TBD: You cannot use this setting and `ssl.truststore.password` at the same time.
end::ssl-truststore-secure-password[]

tag::ssl-truststore-type[]
The format of the truststore file. It must be either `jks` or `PKCS12`. If the
file name ends in ".p12", ".pfx" or "pkcs12", the default is `PKCS12`.
Otherwise, it defaults to `jks`.
end::ssl-truststore-type[]

tag::ssl-truststore-type-pkcs11[]
The format of the truststore file. For the Java keystore format, use `jks`. For
PKCS#12 files, use `PKCS12`. For a PKCS#11 token, use `PKCS11`. The default is
`jks`.
end::ssl-truststore-type-pkcs11[]

tag::ssl-verification-mode-values[]
Valid values are:
- `full`, which verifies that the provided certificate is signed by a trusted
authority (CA) and also verifies that the server's hostname (or IP address)
matches the names identified within the certificate.
- `certificate`, which verifies that the provided certificate is signed by a
trusted authority (CA), but does not perform any hostname verification.
- `none`, which performs _no verification_ of the server's certificate. This
mode disables many of the security benefits of SSL/TLS and should only be used
after very careful consideration. It is primarily intended as a temporary
diagnostic mechanism when attempting to resolve TLS errors; its use on
production clusters is strongly discouraged.
+
The default value is `full`.
end::ssl-verification-mode-values[]