From 77fb6cea17ee802b4e29adc5c0c48d250fa5cd95 Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Thu, 18 Apr 2024 23:04:58 +0100 Subject: [PATCH] Add separate certificates section #433 (#6881) * adding separate certificates section #433 Signed-off-by: AntonEliatra * Update tls.md Signed-off-by: AntonEliatra * Update tls.md Signed-off-by: AntonEliatra * Apply suggestions from code review Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Signed-off-by: AntonEliatra * Update tls.md Signed-off-by: AntonEliatra * Update tls.md Signed-off-by: AntonEliatra * Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: AntonEliatra --------- Signed-off-by: AntonEliatra Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Co-authored-by: Heather Halter Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Co-authored-by: Nathan Bower --- _security/configuration/tls.md | 54 +++++++++++++++++++++++++++------- 1 file changed, 44 insertions(+), 10 deletions(-) diff --git a/_security/configuration/tls.md b/_security/configuration/tls.md index a207b384a1..1d942da417 100755 --- a/_security/configuration/tls.md +++ b/_security/configuration/tls.md @@ -25,9 +25,9 @@ The following tables contain the settings you can use to configure the location Name | Description :--- | :--- `plugins.security.ssl.transport.pemkey_filepath` | Path to the certificate's key file (PKCS \#8), which must be under the `config` directory, specified using a relative path. Required. -`plugins.security.ssl.transport.pemkey_password` | Key password. Omit this setting if the key has no password. Optional. +`plugins.security.ssl.transport.pemkey_password` | The key password. Omit this setting if the key has no password. Optional. `plugins.security.ssl.transport.pemcert_filepath` | Path to the X.509 node certificate chain (PEM format), which must be under the `config` directory, specified using a relative path. Required. -`plugins.security.ssl.transport.pemtrustedcas_filepath` | Path to the root CAs (PEM format), which must be under the `config` directory, specified using a relative path. Required. +`plugins.security.ssl.transport.pemtrustedcas_filepath` | Path to the root certificate authorities (CAs) (PEM format), which must be under the `config` directory, specified using a relative path. Required. ### REST layer TLS @@ -36,7 +36,7 @@ Name | Description :--- | :--- `plugins.security.ssl.http.enabled` | Whether to enable TLS on the REST layer. If enabled, only HTTPS is allowed. Optional. Default is `false`. `plugins.security.ssl.http.pemkey_filepath` | Path to the certificate's key file (PKCS \#8), which must be under the `config` directory, specified using a relative path. Required. -`plugins.security.ssl.http.pemkey_password` | Key password. Omit this setting if the key has no password. Optional. +`plugins.security.ssl.http.pemkey_password` | The key password. Omit this setting if the key has no password. Optional. `plugins.security.ssl.http.pemcert_filepath` | Path to the X.509 node certificate chain (PEM format), which must be under the `config` directory, specified using a relative path. Required. `plugins.security.ssl.http.pemtrustedcas_filepath` | Path to the root CAs (PEM format), which must be under the `config` directory, specified using a relative path. Required. @@ -54,14 +54,13 @@ Name | Description :--- | :--- `plugins.security.ssl.transport.keystore_type` | The type of the keystore file, JKS or PKCS12/PFX. Optional. Default is JKS. `plugins.security.ssl.transport.keystore_filepath` | Path to the keystore file, which must be under the `config` directory, specified using a relative path. Required. -`plugins.security.ssl.transport.keystore_alias: my_alias` | Alias name. Optional. Default is the first alias. +`plugins.security.ssl.transport.keystore_alias` | The alias name of the keystore. Optional. Default is the first alias. `plugins.security.ssl.transport.keystore_password` | Keystore password. Default is `changeit`. `plugins.security.ssl.transport.truststore_type` | The type of the truststore file, JKS or PKCS12/PFX. Default is JKS. `plugins.security.ssl.transport.truststore_filepath` | Path to the truststore file, which must be under the `config` directory, specified using a relative path. Required. -`plugins.security.ssl.transport.truststore_alias` | Alias name. Optional. Default is all certificates. +`plugins.security.ssl.transport.truststore_alias` | The alias name of the truststore. Optional. Default is all certificates. `plugins.security.ssl.transport.truststore_password` | Truststore password. Default is `changeit`. - ### REST layer TLS Name | Description @@ -69,12 +68,47 @@ Name | Description `plugins.security.ssl.http.enabled` | Whether to enable TLS on the REST layer. If enabled, only HTTPS is allowed. Optional. Default is false. `plugins.security.ssl.http.keystore_type` | The type of the keystore file, JKS or PKCS12/PFX. Optional. Default is JKS. `plugins.security.ssl.http.keystore_filepath` | Path to the keystore file, which must be under the `config` directory, specified using a relative path. Required. -`plugins.security.ssl.http.keystore_alias` | Alias name. Optional. Default is the first alias. -`plugins.security.ssl.http.keystore_password` | Keystore password. Default is `changeit`. +`plugins.security.ssl.http.keystore_alias` | The alias name of the keystore. Optional. Default is the first alias. +`plugins.security.ssl.http.keystore_password` | The password for the keystore. Default is `changeit`. `plugins.security.ssl.http.truststore_type` | The type of the truststore file, JKS or PKCS12/PFX. Default is JKS. `plugins.security.ssl.http.truststore_filepath` | Path to the truststore file, which must be under the `config` directory, specified using a relative path. Required. -`plugins.security.ssl.http.truststore_alias` | Alias name. Optional. Default is all certificates. -`plugins.security.ssl.http.truststore_password` | Truststore password. Default is `changeit`. +`plugins.security.ssl.http.truststore_alias` | The alias name of the truststore. Optional. Default is all certificates. +`plugins.security.ssl.http.truststore_password` | The password for the truststore. Default is `changeit`. + + +## Separate client and server certificates for transport layer TLS + +By default, transport layer TLS certificates need to be configured as both the client (`TLS Web Client Authentication`) and server (`TLS Web Server Authentication`) in the certificate's `Extended Key Usage` section because the nodes using the TLS certificates assume the responsibility of serving and receiving the communication requests internally. +If you want to use separate certificates for the client and server, add the `plugins.security.ssl.transport.extended_key_usage_enabled: true` setting to `opensearch.yml`. Next, configure the settings outlined in the [separate client and server X.509 PEM certificates and PKCS #8 keys]({{site.url}}{{site.baseurl}}/security/configuration/tls/#separate-client-and-server-x509-pem-certificates-and-pkcs-8-keys) or [separate client and server keystore and truststore files]({{site.url}}{{site.baseurl}}/security/configuration/tls/#separate-client-and-server-keystore-and-truststore-files) sections. + +### Separate client and server X.509 PEM certificates and PKCS #8 keys + +Name | Description +:--- | :--- +`plugins.security.ssl.transport.server.pemkey_filepath` | The path to the server certificate's key file (PKCS \#8). Must be specified using a relative path under the `config` directory. Required. +`plugins.security.ssl.transport.server.pemkey_password` | The server key password. Omit this setting if the key has no password. Optional. +`plugins.security.ssl.transport.server.pemcert_filepath` | The path to the X.509 node server certificate chain (PEM format). Must be specified using a relative path under the `config` directory. Required. +`plugins.security.ssl.transport.server.pemtrustedcas_filepath` | The path to the root CAs (PEM format). Must be specified using a relative path under the `config` directory. Required. +`plugins.security.ssl.transport.client.pemkey_filepath` | The path to the client certificate's key file (PKCS \#8). Must be specified using a relative path under the `config` directory. Required. +`plugins.security.ssl.transport.client.pemkey_password` | The client key password. Omit this setting if the key has no password. Optional. +`plugins.security.ssl.transport.client.pemcert_filepath` | The path to the X.509 node client certificate chain (PEM format). Must be specified using a relative path under the `config` directory. Required. +`plugins.security.ssl.transport.client.pemtrustedcas_filepath` | The path to the root CAs (PEM format). Must be specified using a relative path under the `config` directory. Required. + +### Separate client and server keystore and truststore files + +Name | Description +:--- | :--- +`plugins.security.ssl.transport.keystore_type` | The type of the keystore file, either `JKS` or `PKCS12/PFX`. Optional. Default is `JKS`. +`plugins.security.ssl.transport.keystore_filepath` | The path to the keystore file. Must be specified using a relative path under the `config` directory. Required. +`plugins.security.ssl.transport.server.keystore_alias` | The alias name of the server key. Optional. Default is the first alias. +`plugins.security.ssl.transport.client.keystore_alias` | The alias name of the client key. Optional. Default is the first alias. +`plugins.security.ssl.transport.server.keystore_keypassword` | The keystore password for the server. Default is `changeit`. +`plugins.security.ssl.transport.client.keystore_keypassword` | The keystore password for the client. Default is `changeit`. +`plugins.security.ssl.transport.server.truststore_alias` | The alias name of the server. Optional. Default is all certificates. +`plugins.security.ssl.transport.client.truststore_alias` | The alias name of the client. Optional. Default is all certificates. +`plugins.security.ssl.transport.truststore_filepath` | The path to the `truststore` file. Must be specified using a relative path under the `config` directory. Required. +`plugins.security.ssl.transport.truststore_type` | The type of the `truststore` file, either `JKS` or `PKCS12/PFX`. Default is `JKS`. +`plugins.security.ssl.transport.truststore_password` | The `truststore` password. Default is `changeit`. ## Configuring node certificates