From 3f3c304530389809f80043e3e43489e3eae70534 Mon Sep 17 00:00:00 2001 From: Tony Butterfield <1846725+tonbut@users.noreply.github.com> Date: Wed, 5 Mar 2025 12:20:27 +0000 Subject: [PATCH 01/12] Added detail for certificate rotation feature --- .../ROOT/pages/security/ssl-framework.adoc | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/modules/ROOT/pages/security/ssl-framework.adoc b/modules/ROOT/pages/security/ssl-framework.adoc index fd8419439..9bca2c1b6 100644 --- a/modules/ROOT/pages/security/ssl-framework.adoc +++ b/modules/ROOT/pages/security/ssl-framework.adoc @@ -1108,6 +1108,31 @@ Beware that the SSL debug option logs a new statement every time a client connec To avoid that scenario, make sure this setting is only enabled for a short term duration. ==== +[[certificate-rotation]] +== Certificate Rotation +It is considered best practice to use certificates with reasonably short duration. This, however, requires the periodic rotation of certificates whereby old certificates are removed and the new ones installed. Previous versions of Neo4j required a the restart of a database instance for changes to be applied. New certificates can now be rotated in and SSL configuration changed without a restart being required. This reduces undesirable effects of transient loss of cluster members. + +. Enable the dynamic reloading of certificates on all cluster members. It is best to do this when the cluster is deployed as changing this configuration requires a restart: + +[source, properties] +---- +dbms.security.tls_reload=true (default is false) +---- + +. Make necessary changes to any of the SSL configuration and/or replace certificates for desired scopes. New certificates will need to be copied to all cluster members as required. + +. Connect to each cluster member in turn using Cypher Shell using a bolt scheme and run the reload procedure: + +[source] +---- +dbms.reloadTLSCertificates() +---- + +. New settings will take effect immediately, however existing connections will not be pre-emptively terminated. + +. Verify that the intra-cluster communication is still encrypted using external tooling, such as Nmap, described above. + + [[ssl-terminology]] == Terminology From b1a7655ec5af255fad76bcae35426c1d33b44752 Mon Sep 17 00:00:00 2001 From: Tony Butterfield <1846725+tonbut@users.noreply.github.com> Date: Mon, 10 Mar 2025 11:11:35 +0000 Subject: [PATCH 02/12] added additional detail regarding replacing existing certificates --- modules/ROOT/pages/security/ssl-framework.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/security/ssl-framework.adoc b/modules/ROOT/pages/security/ssl-framework.adoc index 9bca2c1b6..dba91b24c 100644 --- a/modules/ROOT/pages/security/ssl-framework.adoc +++ b/modules/ROOT/pages/security/ssl-framework.adoc @@ -1119,7 +1119,9 @@ It is considered best practice to use certificates with reasonably short duratio dbms.security.tls_reload=true (default is false) ---- -. Make necessary changes to any of the SSL configuration and/or replace certificates for desired scopes. New certificates will need to be copied to all cluster members as required. +. Replace old certificates either by overwriting on the filesystem, or copying them to a new location and updating the required SSL configuration for each effected scope. Both certificates may exist on the filesystem but only one can be referenced in the configuration. New certificates will need to be copied to all cluster members as required. + +. Make necessary changes to any of the SSL configuration. and/or replace certificates for effected scopes. . Connect to each cluster member in turn using Cypher Shell using a bolt scheme and run the reload procedure: From 32d4c7dcdf8077db8c83b4d56edc307e03891ec4 Mon Sep 17 00:00:00 2001 From: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Thu, 13 Mar 2025 11:14:53 +0100 Subject: [PATCH 03/12] Change the formatting and add some xrefs --- .../ROOT/pages/security/ssl-framework.adoc | 25 +++++++++++++------ 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/modules/ROOT/pages/security/ssl-framework.adoc b/modules/ROOT/pages/security/ssl-framework.adoc index dba91b24c..33ee9347a 100644 --- a/modules/ROOT/pages/security/ssl-framework.adoc +++ b/modules/ROOT/pages/security/ssl-framework.adoc @@ -1108,22 +1108,33 @@ Beware that the SSL debug option logs a new statement every time a client connec To avoid that scenario, make sure this setting is only enabled for a short term duration. ==== +[role=label--new-2025.03] [[certificate-rotation]] -== Certificate Rotation -It is considered best practice to use certificates with reasonably short duration. This, however, requires the periodic rotation of certificates whereby old certificates are removed and the new ones installed. Previous versions of Neo4j required a the restart of a database instance for changes to be applied. New certificates can now be rotated in and SSL configuration changed without a restart being required. This reduces undesirable effects of transient loss of cluster members. +== Certificates rotation -. Enable the dynamic reloading of certificates on all cluster members. It is best to do this when the cluster is deployed as changing this configuration requires a restart: +It is considered best practice to use certificates with reasonably short duration. +This, however, requires the periodic rotation of certificates whereby old certificates are removed and the new ones are installed. +Previous versions of Neo4j required a database restart for changes to be applied. +Starting from 2025.03, new certificates can be rotated in, and SSL configuration can be updated without requiring a restart. +This reduces undesirable effects of transient loss of cluster members. + +Following are the steps of newly introduced certificates rotation. + +. Enable the dynamic reloading of certificates on all cluster members. +It is best to do this when the cluster is deployed as changing this configuration requires a restart: [source, properties] ---- dbms.security.tls_reload=true (default is false) ---- -. Replace old certificates either by overwriting on the filesystem, or copying them to a new location and updating the required SSL configuration for each effected scope. Both certificates may exist on the filesystem but only one can be referenced in the configuration. New certificates will need to be copied to all cluster members as required. +. Replace old certificates either by overwriting on the filesystem or by copying them to a new location and updating the required SSL configuration for each effected scope. +Both certificates may exist on the filesystem but only one can be referenced in the configuration. +New certificates need to be copied to all cluster members as required. -. Make necessary changes to any of the SSL configuration. and/or replace certificates for effected scopes. +. Make necessary changes to any of the SSL configuration and/or replace certificates for effected scopes. -. Connect to each cluster member in turn using Cypher Shell using a bolt scheme and run the reload procedure: +. Connect to each cluster member in turn with Cypher Shell using a <> and run the reload procedure: [source] ---- @@ -1132,7 +1143,7 @@ dbms.reloadTLSCertificates() . New settings will take effect immediately, however existing connections will not be pre-emptively terminated. -. Verify that the intra-cluster communication is still encrypted using external tooling, such as Nmap, described above. +. Verify that the intra-cluster communication is still encrypted using external tooling, such as Nmap, described in <>. [[ssl-terminology]] From 61b51da31629e82187899784e5c962ee78031915 Mon Sep 17 00:00:00 2001 From: Tony Butterfield <1846725+tonbut@users.noreply.github.com> Date: Thu, 13 Mar 2025 11:42:55 +0000 Subject: [PATCH 04/12] Update modules/ROOT/pages/security/ssl-framework.adoc Co-authored-by: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> --- modules/ROOT/pages/security/ssl-framework.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/security/ssl-framework.adoc b/modules/ROOT/pages/security/ssl-framework.adoc index 33ee9347a..e426cab2b 100644 --- a/modules/ROOT/pages/security/ssl-framework.adoc +++ b/modules/ROOT/pages/security/ssl-framework.adoc @@ -1129,7 +1129,7 @@ dbms.security.tls_reload=true (default is false) ---- . Replace old certificates either by overwriting on the filesystem or by copying them to a new location and updating the required SSL configuration for each effected scope. -Both certificates may exist on the filesystem but only one can be referenced in the configuration. +New and old certificates may exist on the filesystem but only one can be referenced in the configuration. New certificates need to be copied to all cluster members as required. . Make necessary changes to any of the SSL configuration and/or replace certificates for effected scopes. From 491e25bd07312c9c796a5f0712ab3f4af5d764d8 Mon Sep 17 00:00:00 2001 From: Tony Butterfield <1846725+tonbut@users.noreply.github.com> Date: Thu, 13 Mar 2025 11:45:12 +0000 Subject: [PATCH 05/12] Update modules/ROOT/pages/security/ssl-framework.adoc Co-authored-by: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> --- modules/ROOT/pages/security/ssl-framework.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/security/ssl-framework.adoc b/modules/ROOT/pages/security/ssl-framework.adoc index e426cab2b..cc3fe5659 100644 --- a/modules/ROOT/pages/security/ssl-framework.adoc +++ b/modules/ROOT/pages/security/ssl-framework.adoc @@ -1118,7 +1118,7 @@ Previous versions of Neo4j required a database restart for changes to be applied Starting from 2025.03, new certificates can be rotated in, and SSL configuration can be updated without requiring a restart. This reduces undesirable effects of transient loss of cluster members. -Following are the steps of newly introduced certificates rotation. +The following steps outline the process for certificates rotation. . Enable the dynamic reloading of certificates on all cluster members. It is best to do this when the cluster is deployed as changing this configuration requires a restart: From e4caea10be30509c28f6addaa8aac4352a9d7c6e Mon Sep 17 00:00:00 2001 From: Tony Butterfield <1846725+tonbut@users.noreply.github.com> Date: Fri, 14 Mar 2025 13:20:27 +0000 Subject: [PATCH 06/12] review feedback --- modules/ROOT/pages/procedures.adoc | 10 ++++++++++ modules/ROOT/pages/security/ssl-framework.adoc | 4 ++-- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/procedures.adoc b/modules/ROOT/pages/procedures.adoc index 69c59339f..89ab2135b 100644 --- a/modules/ROOT/pages/procedures.adoc +++ b/modules/ROOT/pages/procedures.adoc @@ -74,6 +74,16 @@ For more information, see xref:authentication-authorization/index.adoc[Authentic | *Mode* 3+| DBMS |=== +[procedure_dbms_security_reload_tls]] +=== dbms.security.reloadTLS() + + +.Details +|=== +| *Syntax* 3+m| dbms.security.reloadTLS() +| *Description* 3+a| Trigger the dynamic reloading of all TLS certificates and configuration. +| *Mode* 3+| DBMS +|=== [[procedure_dbms_showcurrentuser]] === dbms.showCurrentUser() diff --git a/modules/ROOT/pages/security/ssl-framework.adoc b/modules/ROOT/pages/security/ssl-framework.adoc index cc3fe5659..bfdaa9f44 100644 --- a/modules/ROOT/pages/security/ssl-framework.adoc +++ b/modules/ROOT/pages/security/ssl-framework.adoc @@ -1125,7 +1125,7 @@ It is best to do this when the cluster is deployed as changing this configuratio [source, properties] ---- -dbms.security.tls_reload=true (default is false) +dbms.security.tls_reload_enabled=true (default is false) ---- . Replace old certificates either by overwriting on the filesystem or by copying them to a new location and updating the required SSL configuration for each effected scope. @@ -1138,7 +1138,7 @@ New certificates need to be copied to all cluster members as required. [source] ---- -dbms.reloadTLSCertificates() +dbms.security.reloadTLS() ---- . New settings will take effect immediately, however existing connections will not be pre-emptively terminated. From b6a121976dc2ff9e57d543289b816fc2acb16c89 Mon Sep 17 00:00:00 2001 From: Tony Butterfield <1846725+tonbut@users.noreply.github.com> Date: Mon, 17 Mar 2025 11:33:26 +0000 Subject: [PATCH 07/12] added tags --- modules/ROOT/pages/procedures.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/ROOT/pages/procedures.adoc b/modules/ROOT/pages/procedures.adoc index 89ab2135b..0ddce0331 100644 --- a/modules/ROOT/pages/procedures.adoc +++ b/modules/ROOT/pages/procedures.adoc @@ -74,6 +74,7 @@ For more information, see xref:authentication-authorization/index.adoc[Authentic | *Mode* 3+| DBMS |=== +[role=label--enterprise-edition label--admin-only] [procedure_dbms_security_reload_tls]] === dbms.security.reloadTLS() From 490ed3aef1d2e95d3c59de1e253cf2cf48dcf36f Mon Sep 17 00:00:00 2001 From: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Wed, 19 Mar 2025 13:40:53 +0100 Subject: [PATCH 08/12] Add `dbms.security.tls_reload_enabled` to the configs ref page --- .../configuration/configuration-settings.adoc | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/modules/ROOT/pages/configuration/configuration-settings.adoc b/modules/ROOT/pages/configuration/configuration-settings.adoc index 4bdfdcced..55f9b7765 100644 --- a/modules/ROOT/pages/configuration/configuration-settings.adoc +++ b/modules/ROOT/pages/configuration/configuration-settings.adoc @@ -4384,6 +4384,22 @@ m|+++false+++ |=== +[role=label--enterprise-edition label--new-2025.03] +[[config_dbms.security.tls_reload_enabled]] +=== `dbms.security.tls_reload_enabled` + +.dbms.security.tls_reload_enabled +[frame="topbot", stripes=odd, grid="cols", cols="<1s,<4"] +|=== +|Description +a|Enable the reloading to TLS configuration and certificates dynamically by calling a procedure. +|Valid values +a|A boolean. +|Default value +m|+++false+++ +|=== + + [[config_dbms.netty.ssl.provider]] === `dbms.netty.ssl.provider` From f3dd1fd399267bf26df88c30804262832a03de67 Mon Sep 17 00:00:00 2001 From: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Wed, 19 Mar 2025 14:00:25 +0100 Subject: [PATCH 09/12] Update modules/ROOT/pages/procedures.adoc --- modules/ROOT/pages/procedures.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/procedures.adoc b/modules/ROOT/pages/procedures.adoc index 0ddce0331..8002e3106 100644 --- a/modules/ROOT/pages/procedures.adoc +++ b/modules/ROOT/pages/procedures.adoc @@ -74,7 +74,7 @@ For more information, see xref:authentication-authorization/index.adoc[Authentic | *Mode* 3+| DBMS |=== -[role=label--enterprise-edition label--admin-only] +[role=label--enterprise-edition label--admin-only label--new-2025.03] [procedure_dbms_security_reload_tls]] === dbms.security.reloadTLS() From c03941fe5e1886ff38fe8fdcd0f9aeeda3734447 Mon Sep 17 00:00:00 2001 From: Tony Butterfield <1846725+tonbut@users.noreply.github.com> Date: Thu, 20 Mar 2025 14:31:51 +0000 Subject: [PATCH 10/12] Update modules/ROOT/pages/security/ssl-framework.adoc Co-authored-by: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> --- modules/ROOT/pages/security/ssl-framework.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/security/ssl-framework.adoc b/modules/ROOT/pages/security/ssl-framework.adoc index bfdaa9f44..e0ba3a055 100644 --- a/modules/ROOT/pages/security/ssl-framework.adoc +++ b/modules/ROOT/pages/security/ssl-framework.adoc @@ -1128,7 +1128,9 @@ It is best to do this when the cluster is deployed as changing this configuratio dbms.security.tls_reload_enabled=true (default is false) ---- -. Replace old certificates either by overwriting on the filesystem or by copying them to a new location and updating the required SSL configuration for each effected scope. +. Replace old certificates either by overwriting them on the filesystem or by copying them to a new location. +Then update the required SSL configuration for each effected scope. ++ New and old certificates may exist on the filesystem but only one can be referenced in the configuration. New certificates need to be copied to all cluster members as required. From 4abe088bb54db0402a1f8020bde08adcd694dca1 Mon Sep 17 00:00:00 2001 From: Tony Butterfield <1846725+tonbut@users.noreply.github.com> Date: Thu, 20 Mar 2025 14:32:16 +0000 Subject: [PATCH 11/12] Update modules/ROOT/pages/security/ssl-framework.adoc Co-authored-by: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> --- modules/ROOT/pages/security/ssl-framework.adoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/security/ssl-framework.adoc b/modules/ROOT/pages/security/ssl-framework.adoc index e0ba3a055..6df18c3ec 100644 --- a/modules/ROOT/pages/security/ssl-framework.adoc +++ b/modules/ROOT/pages/security/ssl-framework.adoc @@ -1143,7 +1143,9 @@ New certificates need to be copied to all cluster members as required. dbms.security.reloadTLS() ---- -. New settings will take effect immediately, however existing connections will not be pre-emptively terminated. +. New settings will take effect immediately; however, existing connections will not be preemptively terminated. +This means that while new connections will use new certificates, the existing connections (established before the update) will continue using the old certificates. +Even if a certificate expires, active connections remain unaffected because the certificates are only used during the initial connection handshake. . Verify that the intra-cluster communication is still encrypted using external tooling, such as Nmap, described in <>. From 5345ef5419cf5a968bec91ef87d1b4895226c833 Mon Sep 17 00:00:00 2001 From: Tony Butterfield <1846725+tonbut@users.noreply.github.com> Date: Thu, 20 Mar 2025 14:32:35 +0000 Subject: [PATCH 12/12] Update modules/ROOT/pages/security/ssl-framework.adoc Co-authored-by: NataliaIvakina <82437520+NataliaIvakina@users.noreply.github.com> --- modules/ROOT/pages/security/ssl-framework.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/security/ssl-framework.adoc b/modules/ROOT/pages/security/ssl-framework.adoc index 6df18c3ec..733133eda 100644 --- a/modules/ROOT/pages/security/ssl-framework.adoc +++ b/modules/ROOT/pages/security/ssl-framework.adoc @@ -1131,7 +1131,7 @@ dbms.security.tls_reload_enabled=true (default is false) . Replace old certificates either by overwriting them on the filesystem or by copying them to a new location. Then update the required SSL configuration for each effected scope. + -New and old certificates may exist on the filesystem but only one can be referenced in the configuration. +New and old certificates may co-exist on the filesystem, but only one can be referenced in the configuration. New certificates need to be copied to all cluster members as required. . Make necessary changes to any of the SSL configuration and/or replace certificates for effected scopes.