Documentation for TLS certificate rotation feature (#2165)

https://trello.com/c/4hpH8ouM/429-dynamic-tls-certificates-with-online-rotation

Author: tonbut

modules/ROOT/pages/configuration/configuration-settings.adoc

@@ -4468,6 +4468,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`
 

modules/ROOT/pages/procedures.adoc

@@ -74,6 +74,17 @@ For more information, see xref:authentication-authorization/index.adoc[Authentic
 | *Mode* 3+| DBMS
 |===
 
+[role=label--enterprise-edition label--admin-only label--new-2025.03]
+[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()

modules/ROOT/pages/security/ssl-framework.adoc

@@ -1108,6 +1108,48 @@ 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]]
+== Certificates 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 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.
+
+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:
+
+[source, properties]
+----
+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 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. 
+
+. Connect to each cluster member in turn with Cypher Shell using a <<ssl-bolt-connect,`bolt` URI scheme>> and run the reload procedure:
+
+[source]
+----
+dbms.security.reloadTLS()
+----
+
+. 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 <<ssl-cluster-config, Configuring SSL for intra-cluster communications>>.
+ 
+
 [[ssl-terminology]]
 == Terminology