From 9ad86dd25eacb536950b0ee625c137b40bf63ea3 Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Thu, 4 Apr 2024 11:23:53 +0100 Subject: [PATCH 1/6] adding hot reload TLS certificate section #433 Signed-off-by: AntonEliatra --- _api-reference/index.md | 1 + _security/configuration/tls.md | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+) diff --git a/_api-reference/index.md b/_api-reference/index.md index 41d54989c8..815b4af365 100644 --- a/_api-reference/index.md +++ b/_api-reference/index.md @@ -61,6 +61,7 @@ This reference includes the REST APIs supported by OpenSearch. If a REST API is - [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/) - [Tasks]({{site.url}}{{site.baseurl}}/api-reference/tasks/) - [Transforms API]({{site.url}}{{site.baseurl}}/im-plugin/index-transforms/transforms-apis/) +- [Hot reload TLS certificates]({{site.url}}{{site.baseurl}}/security/configuration/tls/#hot-reloading-tls-certificates) diff --git a/_security/configuration/tls.md b/_security/configuration/tls.md index a207b384a1..b34c01b027 100755 --- a/_security/configuration/tls.md +++ b/_security/configuration/tls.md @@ -226,3 +226,35 @@ The default insecure SSL password settings have been deprecated. In order to use * plugins.security.ssl.transport.truststore_password_secure These settings allow for the use of encrypted passwords in the settings. + +## Hot reloading TLS certificates + +Updating expired (or nearly expired) certificates does not require cluster restart. You can use hot reloading to achieve this without any downtime. + +In order to enable hot reloading of TLS certificates, add the following line to `opensearch.yml` + +`opendistro_security.ssl_cert_reload_enabled: true` + +This setting is set to false by default +{: .note } + +The following API expects the old certificates to be replaced with valid certificates issued with the same `Issuer/Subject DN` and `SAN`. The new certificates also need be in the same location as previous certificates, in order to prevent any changes to `opensearch.yml` file. This api is only accessible using [super admin user's certificate and key]({{site.url}}{{site.baseurl}}/security/configuration/tls/#configuring-admin-certificates) + +### Reload TLS certificates on transport layer + ```json + curl --cacert --cert --key -XPUT https://localhost:9200/_opendistro/_security/api/ssl/transport/reloadcerts + ``` + {% include copy.html %} + +Expected response +```{ "message": "successfully updated transport certs"}``` + +### Reload TLS certificates on http layer + ```json + curl --cacert --cert --key -XPUT https://localhost:9200/_opendistro/_security/api/ssl/http/reloadcerts + ``` + {% include copy.html %} + +Expected response +```{ "message": "successfully updated http certs"}``` + From c5afdc23961e0c5b12c22105505be1ae66bae5cc Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Thu, 4 Apr 2024 17:15:45 +0100 Subject: [PATCH 2/6] fixing issues on hot reload #433 Signed-off-by: AntonEliatra --- _security/configuration/tls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security/configuration/tls.md b/_security/configuration/tls.md index b34c01b027..e17dc1769f 100755 --- a/_security/configuration/tls.md +++ b/_security/configuration/tls.md @@ -238,7 +238,7 @@ In order to enable hot reloading of TLS certificates, add the following line to This setting is set to false by default {: .note } -The following API expects the old certificates to be replaced with valid certificates issued with the same `Issuer/Subject DN` and `SAN`. The new certificates also need be in the same location as previous certificates, in order to prevent any changes to `opensearch.yml` file. This api is only accessible using [super admin user's certificate and key]({{site.url}}{{site.baseurl}}/security/configuration/tls/#configuring-admin-certificates) +The following API expects the old certificates to be replaced with valid certificates issued with the same `Issuer/Subject DN` and `SAN`. The new certificates also need be in the same location as previous certificates, in order to prevent any changes to `opensearch.yml` file. This API is only accessible using [super admin user's certificate and key]({{site.url}}{{site.baseurl}}/security/configuration/tls/#configuring-admin-certificates) ### Reload TLS certificates on transport layer ```json From 6f4737473dc76833ba9a6ebdd5f2b0823631f880 Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Mon, 8 Apr 2024 09:53:06 +0100 Subject: [PATCH 3/6] Update tls.md Signed-off-by: AntonEliatra --- _security/configuration/tls.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_security/configuration/tls.md b/_security/configuration/tls.md index e17dc1769f..ceac8a24bc 100755 --- a/_security/configuration/tls.md +++ b/_security/configuration/tls.md @@ -233,7 +233,7 @@ Updating expired (or nearly expired) certificates does not require cluster resta In order to enable hot reloading of TLS certificates, add the following line to `opensearch.yml` -`opendistro_security.ssl_cert_reload_enabled: true` +`plugins.security.ssl_cert_reload_enabled: true` This setting is set to false by default {: .note } @@ -242,7 +242,7 @@ The following API expects the old certificates to be replaced with valid certifi ### Reload TLS certificates on transport layer ```json - curl --cacert --cert --key -XPUT https://localhost:9200/_opendistro/_security/api/ssl/transport/reloadcerts + curl --cacert --cert --key -XPUT https://localhost:9200/_plugins/_security/api/ssl/transport/reloadcerts ``` {% include copy.html %} @@ -251,7 +251,7 @@ Expected response ### Reload TLS certificates on http layer ```json - curl --cacert --cert --key -XPUT https://localhost:9200/_opendistro/_security/api/ssl/http/reloadcerts + curl --cacert --cert --key -XPUT https://localhost:9200/_plugins/_security/api/ssl/http/reloadcerts ``` {% include copy.html %} From 3ac312616a92d6f8eab274881facdf6605874a19 Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Mon, 15 Apr 2024 09:22:12 +0100 Subject: [PATCH 4/6] Apply suggestions from code review Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Signed-off-by: AntonEliatra --- _security/configuration/tls.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/_security/configuration/tls.md b/_security/configuration/tls.md index ceac8a24bc..182581890c 100755 --- a/_security/configuration/tls.md +++ b/_security/configuration/tls.md @@ -229,32 +229,40 @@ These settings allow for the use of encrypted passwords in the settings. ## Hot reloading TLS certificates -Updating expired (or nearly expired) certificates does not require cluster restart. You can use hot reloading to achieve this without any downtime. +Updating expired or nearly expired TLS certificates does not require restarting the cluster. Instead, enable hot reloading of TLS cerificates by adding the following line to `opensearch.yml`: -In order to enable hot reloading of TLS certificates, add the following line to `opensearch.yml` `plugins.security.ssl_cert_reload_enabled: true` -This setting is set to false by default +This setting is set to `false` by default. {: .note } -The following API expects the old certificates to be replaced with valid certificates issued with the same `Issuer/Subject DN` and `SAN`. The new certificates also need be in the same location as previous certificates, in order to prevent any changes to `opensearch.yml` file. This API is only accessible using [super admin user's certificate and key]({{site.url}}{{site.baseurl}}/security/configuration/tls/#configuring-admin-certificates) +After enabling hot reloading, use the Reload Certificates API to replace the expired certification. The API expects the old certificates to be replaced with valid certificates issued with the same `Issuer/Subject DN` and `SAN`. The new certificates also need be in the same location as the previous certificates, in order to prevent any changes to `opensearch.yml` file. -### Reload TLS certificates on transport layer +Only a [super admin]({{site.url}}{{site.baseurl}}/security/configuration/tls/#configuring-admin-certificates) can use the Reload Certificates API. +{: .note } + +### Reload TLS certificates on the transport layer + The following example reloads TLS certificates on the transport layer: + ```json curl --cacert --cert --key -XPUT https://localhost:9200/_plugins/_security/api/ssl/transport/reloadcerts ``` {% include copy.html %} -Expected response +You should receive the following response: ```{ "message": "successfully updated transport certs"}``` -### Reload TLS certificates on http layer +### Reload TLS certificates on the http layer + +The following example reloads TLS certificates on the `http` layer: + ```json curl --cacert --cert --key -XPUT https://localhost:9200/_plugins/_security/api/ssl/http/reloadcerts ``` {% include copy.html %} -Expected response +You should receive the following response: + ```{ "message": "successfully updated http certs"}``` From 15c80261632b0ee8174c05ce89e81236517762f2 Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Wed, 17 Apr 2024 17:02:36 +0100 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: AntonEliatra --- _security/configuration/tls.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_security/configuration/tls.md b/_security/configuration/tls.md index 182581890c..a02d9dc7f1 100755 --- a/_security/configuration/tls.md +++ b/_security/configuration/tls.md @@ -234,12 +234,12 @@ Updating expired or nearly expired TLS certificates does not require restarting `plugins.security.ssl_cert_reload_enabled: true` -This setting is set to `false` by default. +This setting is `false` by default. {: .note } -After enabling hot reloading, use the Reload Certificates API to replace the expired certification. The API expects the old certificates to be replaced with valid certificates issued with the same `Issuer/Subject DN` and `SAN`. The new certificates also need be in the same location as the previous certificates, in order to prevent any changes to `opensearch.yml` file. +After enabling hot reloading, use the Reload Certificates API to replace the expired certificates. The API expects the old certificates to be replaced with valid certificates issued with the same `Issuer/Subject DN` and `SAN`. The new certificates also need be stored in the same location as the previous certificates in order to prevent any changes to the `opensearch.yml` file. -Only a [super admin]({{site.url}}{{site.baseurl}}/security/configuration/tls/#configuring-admin-certificates) can use the Reload Certificates API. +Only a [superadmin]({{site.url}}{{site.baseurl}}/security/configuration/tls/#configuring-admin-certificates) can use the Reload Certificates API. {: .note } ### Reload TLS certificates on the transport layer From 7b42bee3490840ff3adaac70e38687711846ff6b Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Wed, 17 Apr 2024 17:03:42 +0100 Subject: [PATCH 6/6] Update tls.md Signed-off-by: AntonEliatra --- _security/configuration/tls.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_security/configuration/tls.md b/_security/configuration/tls.md index a02d9dc7f1..307176c870 100755 --- a/_security/configuration/tls.md +++ b/_security/configuration/tls.md @@ -243,7 +243,7 @@ Only a [superadmin]({{site.url}}{{site.baseurl}}/security/configuration/tls/#con {: .note } ### Reload TLS certificates on the transport layer - The following example reloads TLS certificates on the transport layer: + The following command reloads TLS certificates on the transport layer: ```json curl --cacert --cert --key -XPUT https://localhost:9200/_plugins/_security/api/ssl/transport/reloadcerts @@ -255,7 +255,7 @@ You should receive the following response: ### Reload TLS certificates on the http layer -The following example reloads TLS certificates on the `http` layer: +The following command reloads TLS certificates on the `http` layer: ```json curl --cacert --cert --key -XPUT https://localhost:9200/_plugins/_security/api/ssl/http/reloadcerts