From a047c84e3d1ef6d0bb16f961fe733b931d7a5af8 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Thu, 18 Sep 2025 17:11:42 +0100 Subject: [PATCH 1/7] update the ssl config for backup --- .../pages/backup-restore/online-backup.adoc | 31 +++++++++++++++++-- .../ROOT/pages/security/ssl-framework.adoc | 4 +-- 2 files changed, 31 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/backup-restore/online-backup.adoc b/modules/ROOT/pages/backup-restore/online-backup.adoc index 67c6445d8..8347ac791 100644 --- a/modules/ROOT/pages/backup-restore/online-backup.adoc +++ b/modules/ROOT/pages/backup-restore/online-backup.adoc @@ -315,12 +315,39 @@ The SSL configuration policy has the key of `dbms.ssl.policy.backup`. As an example, add the following content to your _neo4j.conf_ and _neo4j-admin.conf_ files: +.Server configuration in _neo4j.conf_ [source, properties] ---- +server.backup.listen_address=0.0.0.0:6362 dbms.ssl.policy.backup.enabled=true -dbms.ssl.policy.backup.tls_versions=TLSv1.2 -dbms.ssl.policy.backup.ciphers=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 +dbms.ssl.policy.backup.base_directory=certificates/backup +dbms.ssl.policy.backup.private_key=private.key +dbms.ssl.policy.backup.public_certificate=public.crt dbms.ssl.policy.backup.client_auth=REQUIRE +dbms.ssl.policy.backup.tls_versions=TLSv1.2,TLSv1.3 +# dbms.ssl.policy.backup.tls_versions=TLSv1.2 +dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 +# dbms.ssl.policy.backup.ciphers=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 +# dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 +# dbms.netty.ssl.provider=OPENSSL +dbms.netty.ssl.provider=JDK +---- + +.Client configuration in _neo4j-admin.conf_ +[source, properties] +---- +# Enable SSL backup +dbms.ssl.policy.backup.enabled=true +# dbms.ssl.policy.backup.base_directory=certificates/backup +dbms.ssl.policy.backup.private_key=/path/to/certificates/backup/private.key +dbms.ssl.policy.backup.public_certificate=/path/to/certificates/backup/public.crt +dbms.ssl.policy.backup.client_auth=REQUIRE +dbms.ssl.policy.backup.tls_versions=TLSv1.2,TLSv1.3 +# dbms.ssl.policy.backup.tls_versions=TLSv1.2 +dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 +# dbms.netty.ssl.provider=OPENSSL +dbms.netty.ssl.provider=JDK +server.jvm.additional=-Djavax.net.ssl.trustStore=/path/to/certificates/backup/trusted/ ---- [TIP] diff --git a/modules/ROOT/pages/security/ssl-framework.adoc b/modules/ROOT/pages/security/ssl-framework.adoc index ffd78dddb..b54f48a4f 100644 --- a/modules/ROOT/pages/security/ssl-framework.adoc +++ b/modules/ROOT/pages/security/ssl-framework.adoc @@ -928,7 +928,7 @@ The owner/group should be configured to the user/group that will be running the Default user/group is neo4j/neo4j. ==== -. Set the backup SSL configuration in _neo4j.conf_. +. Set the backup SSL configuration in both _neo4j.conf_ and _neo4j-admin.conf_. .. Set the backup SSL policy to `true`: + [source, properties] @@ -1162,7 +1162,7 @@ This means that while new connections will use new certificates, the existing co 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-terminology]] == Terminology From baf9dca4810dd761ddf025be009ab00fa86a3e46 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 24 Sep 2025 17:24:23 +0100 Subject: [PATCH 2/7] apply suggestions from review --- .../pages/backup-restore/online-backup.adoc | 19 --------------- .../ROOT/pages/security/ssl-framework.adoc | 23 ++++++++++++++++++- 2 files changed, 22 insertions(+), 20 deletions(-) diff --git a/modules/ROOT/pages/backup-restore/online-backup.adoc b/modules/ROOT/pages/backup-restore/online-backup.adoc index 8347ac791..876834e42 100644 --- a/modules/ROOT/pages/backup-restore/online-backup.adoc +++ b/modules/ROOT/pages/backup-restore/online-backup.adoc @@ -318,36 +318,17 @@ As an example, add the following content to your _neo4j.conf_ and _neo4j-admin.c .Server configuration in _neo4j.conf_ [source, properties] ---- -server.backup.listen_address=0.0.0.0:6362 -dbms.ssl.policy.backup.enabled=true -dbms.ssl.policy.backup.base_directory=certificates/backup -dbms.ssl.policy.backup.private_key=private.key -dbms.ssl.policy.backup.public_certificate=public.crt dbms.ssl.policy.backup.client_auth=REQUIRE dbms.ssl.policy.backup.tls_versions=TLSv1.2,TLSv1.3 -# dbms.ssl.policy.backup.tls_versions=TLSv1.2 dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 -# dbms.ssl.policy.backup.ciphers=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 -# dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 -# dbms.netty.ssl.provider=OPENSSL -dbms.netty.ssl.provider=JDK ---- .Client configuration in _neo4j-admin.conf_ [source, properties] ---- -# Enable SSL backup -dbms.ssl.policy.backup.enabled=true -# dbms.ssl.policy.backup.base_directory=certificates/backup -dbms.ssl.policy.backup.private_key=/path/to/certificates/backup/private.key -dbms.ssl.policy.backup.public_certificate=/path/to/certificates/backup/public.crt dbms.ssl.policy.backup.client_auth=REQUIRE dbms.ssl.policy.backup.tls_versions=TLSv1.2,TLSv1.3 -# dbms.ssl.policy.backup.tls_versions=TLSv1.2 dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 -# dbms.netty.ssl.provider=OPENSSL -dbms.netty.ssl.provider=JDK -server.jvm.additional=-Djavax.net.ssl.trustStore=/path/to/certificates/backup/trusted/ ---- [TIP] diff --git a/modules/ROOT/pages/security/ssl-framework.adoc b/modules/ROOT/pages/security/ssl-framework.adoc index b54f48a4f..9542ce04e 100644 --- a/modules/ROOT/pages/security/ssl-framework.adoc +++ b/modules/ROOT/pages/security/ssl-framework.adoc @@ -928,7 +928,7 @@ The owner/group should be configured to the user/group that will be running the Default user/group is neo4j/neo4j. ==== -. Set the backup SSL configuration in both _neo4j.conf_ and _neo4j-admin.conf_. +. Set the backup SSL configuration in the _neo4j.conf_ file. .. Set the backup SSL policy to `true`: + [source, properties] @@ -956,6 +956,27 @@ If the certificate is a different path outside of NEO4J_HOME, then set the absol dbms.ssl.policy.backup.client_auth=REQUIRE ---- +=== Configure the backup client for SSL + +When using `neo4j-admin backup` command, you need to specify the SSL policy to be used by the backup client. +You can do this by setting a matching SSL configuration in the _neo4j.conf_ and _neo4j-admin.conf_ files. +This is crucial for the backup to work properly. +For example, if you have set up the backup SSL policy described in section <>, then you need to set the following in the _neo4j-admin.conf_ file: + +[source, properties] +---- +dbms.ssl.policy.backup.enabled=true +dbms.ssl.policy.backup.base_directory=/path/to/certificates/backup +dbms.ssl.policy.backup.private_key=private.key +dbms.ssl.policy.backup.public_certificate=public.crt +dbms.ssl.policy.backup.client_auth=REQUIRE +---- + +[NOTE] +==== +Keep in mind that if you are a backup client on a different machine from the Neo4j server, you must also ensure that equivalent SSL certs are installed in both places. +==== + [[ssl-other-configs]] === Other configurations for SSL From 490efa58916a1c5b69916adfb80a4a2270b10c16 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 24 Sep 2025 17:26:45 +0100 Subject: [PATCH 3/7] update the note --- 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 9542ce04e..88ed4c1a4 100644 --- a/modules/ROOT/pages/security/ssl-framework.adoc +++ b/modules/ROOT/pages/security/ssl-framework.adoc @@ -974,7 +974,7 @@ dbms.ssl.policy.backup.client_auth=REQUIRE [NOTE] ==== -Keep in mind that if you are a backup client on a different machine from the Neo4j server, you must also ensure that equivalent SSL certs are installed in both places. +Keep in mind that if the backup client is on a different machine from the Neo4j server, you must install the same SSL certs and keys on the backup client machine as well, so that the backup client can authenticate the server and vice versa. ==== [[ssl-other-configs]] From 1404ae78668ed8cb91c44dd929c1a9d41776be2a Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Thu, 25 Sep 2025 11:34:13 +0100 Subject: [PATCH 4/7] apply suggestions from review --- modules/ROOT/pages/backup-restore/online-backup.adoc | 2 ++ modules/ROOT/pages/security/ssl-framework.adoc | 2 ++ 2 files changed, 4 insertions(+) diff --git a/modules/ROOT/pages/backup-restore/online-backup.adoc b/modules/ROOT/pages/backup-restore/online-backup.adoc index 876834e42..1a8d9b152 100644 --- a/modules/ROOT/pages/backup-restore/online-backup.adoc +++ b/modules/ROOT/pages/backup-restore/online-backup.adoc @@ -318,6 +318,7 @@ As an example, add the following content to your _neo4j.conf_ and _neo4j-admin.c .Server configuration in _neo4j.conf_ [source, properties] ---- +dbms.ssl.policy.backup.enabled=true dbms.ssl.policy.backup.client_auth=REQUIRE dbms.ssl.policy.backup.tls_versions=TLSv1.2,TLSv1.3 dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 @@ -326,6 +327,7 @@ dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE .Client configuration in _neo4j-admin.conf_ [source, properties] ---- +dbms.ssl.policy.backup.enabled=true dbms.ssl.policy.backup.client_auth=REQUIRE dbms.ssl.policy.backup.tls_versions=TLSv1.2,TLSv1.3 dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 diff --git a/modules/ROOT/pages/security/ssl-framework.adoc b/modules/ROOT/pages/security/ssl-framework.adoc index 88ed4c1a4..d3d311291 100644 --- a/modules/ROOT/pages/security/ssl-framework.adoc +++ b/modules/ROOT/pages/security/ssl-framework.adoc @@ -970,6 +970,8 @@ dbms.ssl.policy.backup.base_directory=/path/to/certificates/backup dbms.ssl.policy.backup.private_key=private.key dbms.ssl.policy.backup.public_certificate=public.crt dbms.ssl.policy.backup.client_auth=REQUIRE +dbms.ssl.policy.backup.tls_versions=TLSv1.2,TLSv1.3 +dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 ---- [NOTE] From 8b47a2c6d48ef7ebcd6863dc19e9249d6087d0a3 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Mon, 29 Sep 2025 14:10:07 +0100 Subject: [PATCH 5/7] apply suggestions from review --- .../ROOT/pages/security/ssl-framework.adoc | 113 +++++++++++------- 1 file changed, 67 insertions(+), 46 deletions(-) diff --git a/modules/ROOT/pages/security/ssl-framework.adoc b/modules/ROOT/pages/security/ssl-framework.adoc index d3d311291..944cae015 100644 --- a/modules/ROOT/pages/security/ssl-framework.adoc +++ b/modules/ROOT/pages/security/ssl-framework.adoc @@ -180,7 +180,7 @@ You can identify them by the line `-----BEGIN RSA PRIVATE KEY-----` at the begin While Neo4j 5.0 can load and use those keys, they are considered deprecated and will be removed in a future version. ==== - +[[ssl-validate-certs]] === Validate the key and the certificate If you need, you can validate the key file and the certificate as follows: @@ -655,22 +655,23 @@ openssl s_client -connect my_domain.com:7473 Intra-cluster encryption is the security solution for the cluster communication. The Neo4j cluster communicates on 3 ports: -* 6000 - Transactions -* 7000 - Raft communications -* 7688 - Server side routing +* `6000` - Transactions +* `7000` - Raft communications +* `7688` - Server side routing + +To configure SSL for intra-cluster communication, create the folder structure and place the key and certificate files under it. +Then, configure the SSL cluster policies in the _neo4j.conf_ file and test that the intra-cluster communication is encrypted. -To set up intra-cluster encryption, on each server create the folder structure and place the key file and the certificates under those. -Then, you need to configure the SSL cluster policies in the _neo4j.conf_ file and test that the intra-cluster communication is encrypted. +==== Set up SSL certificates for intra-cluster communications -. Set up the _cluster_ folder under _certificates_. -.. Create a directory _cluster_ under_/certificates_ folder: +. Create a directory _cluster_ under _/certificates_ folder: + [source, shell] ---- mkdir certificates/cluster ---- -.. Create a directory _trusted_ and _revoked_ under _/certificates/cluster_ folder: +. Create a directory _trusted_ and _revoked_ under _/certificates/cluster_ folder: + [source, shell] ---- @@ -703,9 +704,11 @@ Thus, the servers are able to establish trust relationships with each other. ---- cp /path/to/certs/public.crt certificates/cluster/revoked ---- -+ + +==== Verify the folder structure and permissions + The folder structure should look like this with the right file permissions and the groups and ownerships: -+ + [options="header", cols="3,1,4*m"] |=== | Path @@ -757,21 +760,22 @@ The folder structure should look like this with the right file permissions and t | 0755 | drwxr-xr-x |=== -+ + [TIP] ==== The owner/group should be configured to the user/group that will be running the `neo4j` service. Default user/group is neo4j/neo4j. ==== -. Set the cluster SSL configuration in _neo4j.conf_. -.. Set the cluster SSL policy to `true`: +==== Set the cluster SSL configuration in _neo4j.conf_ + +. Set the cluster SSL policy to `true`: + [source, properties] ---- dbms.ssl.policy.cluster.enabled=true ---- -.. Set the appropriate certificates path and the right key and cert files: +. Set the appropriate certificates path and the right key and cert files: + [source, properties] ---- @@ -785,7 +789,7 @@ dbms.ssl.policy.cluster.public_certificate=public.crt If the certificate is a different path outside of NEO4J_HOME, then set the absolute path for the certificates directory. ==== -.. Set the cluster client authentication to `REQUIRE` to enable the mutual authentication, which means that both ends of a channel have to authenticate: +. Set the cluster client authentication to `REQUIRE` to enable the mutual authentication, which means that both ends of a channel have to authenticate: + [source, properties] ---- @@ -799,14 +803,16 @@ The actual xref:security/ssl-framework.adoc#term-ssl-cryptographic-objects[crypt The trusted CA certificate will be shared however. ==== -.. Verify that the intra-cluster communication is encrypted. +==== Verify that the intra-cluster communication is encrypted + +Once the intra-cluster encryption is enabled, you can verify that the communication is encrypted. You may use an external tooling, such as Nmap (https://nmap.org/download.html): -+ + [source, shell] ---- nmap --script ssl-enum-ciphers -p ---- -+ + [NOTE] ==== The hostname and port have to be adjusted according to your configuration. @@ -823,24 +829,28 @@ For more details on securing the comunication between the cluster servers, see x [[ssl-backup-config]] === Configure SSL for backup communication -In a single instance, by default the backup communication happens on port `6362`. -In a cluster topology, it is possible to take a backup from any server, and each server has two configurable ports capable of serving a backup. -These ports are configured by `dbms.backup.listen.address` (port `6362`) and `server.cluster.listen_address` (port `6000`) respectively. -If the intra-cluster encryption is enabled and the backup communication is using port `6000`, then your communication channels are already encrypted. -The following steps assumes that your backup is set up on a different port. +In a single instance, the backup communication happens on port `6362` by default. + +In a cluster topology, it is possible to take a backup from any server, and each server has two configurable ports capable of serving a backup: -To set up SSL for backup communication, create the folder structure and place the key file and the certificates under those. -Then, you need to configure the SSL backup policies in the _neo4j.conf_ file. +* `dbms.backup.listen.address` (port `6362`) +* `server.cluster.listen_address` (port `6000`) -. Set up the _backup_ folder under _certificates_. -.. Create a directory _backup_ under _/certificates_ folder: +If the <> is enabled and the backup communication uses port `6000`, then the communication channels are already encrypted. +The following steps assume that your backup is set up on a different port. + +==== Set up SSL certificates for backup + +Create the folder structure and place the key and certificate files under it. +Then, configure the SSL backup policies in the _neo4j.conf_ file. + +. Create a directory _backup_ under _/certificates_ folder: + [source, shell] ---- mkdir certificates/backup ---- -.. Create a directory _trusted_ and _revoked_ under _/certificates/backup_ folder: +. Create a directory _trusted_ and _revoked_ under _/certificates/backup_ folder: + [source, shell] ---- @@ -867,9 +877,11 @@ cp /path/to/certs/public.crt certificates/backup/trusted ---- cp /path/to/certs/public.crt certificates/backup/revoked ---- -+ -The folder structure should look like this with the right file permissions and the groups and ownerships: -+ + +==== Verify the backup folder structure and permissions + +The folder structure should look like this with the right file permissions and the groups and ownerships, assuming the `neo4j` user runs the service: + [options="header", cols="3,1,4*m"] |=== | Path @@ -921,21 +933,22 @@ The folder structure should look like this with the right file permissions and t | 0755 | drwxr-xr-x |=== -+ + [TIP] ==== The owner/group should be configured to the user/group that will be running the `neo4j` service. Default user/group is neo4j/neo4j. ==== -. Set the backup SSL configuration in the _neo4j.conf_ file. -.. Set the backup SSL policy to `true`: +==== Set the backup SSL configuration in the _neo4j.conf_ file. + +. Set the backup SSL policy to `true`: + [source, properties] ---- dbms.ssl.policy.backup.enabled=true ---- -.. Set the appropriate certificates path and the right key and cert files: +. Set the appropriate certificates path and the right key and cert files: + [source, properties] ---- @@ -949,7 +962,7 @@ dbms.ssl.policy.backup.public_certificate=public.crt If the certificate is a different path outside of NEO4J_HOME, then set the absolute path for the certificates directory. ==== -.. Set the backup client authentication to `REQUIRE` to enable the mutual authentication, which means that both ends of a channel have to authenticate: +. Set the backup client authentication to `REQUIRE` to enable the mutual authentication, which means that both ends of a channel have to authenticate: + [source, properties] ---- @@ -958,15 +971,28 @@ dbms.ssl.policy.backup.client_auth=REQUIRE === Configure the backup client for SSL -When using `neo4j-admin backup` command, you need to specify the SSL policy to be used by the backup client. -You can do this by setting a matching SSL configuration in the _neo4j.conf_ and _neo4j-admin.conf_ files. -This is crucial for the backup to work properly. +When using `neo4j-admin backup` command, the backup client needs to be configured to use SSL as well. +Regardless of which backup port you are targeting (see <>), the backup client uses the SSL policy specified in `dbms.ssl.policy.backup.*`, given the same SSL policy name matches between server and client. + +[NOTE] +==== +If the backup client is on a different machine from the Neo4j server, you must install sympathetic SSL certificates and keys on the backup client machine as well, so that the backup client can authenticate the server and vice versa. +If you want mutual TLS with self-signed certificates, the server must have the client's certificate in its _trusted_dir_, and the client must have the server's certificate in its _trusted_dir_. +If you use a certificate authority (CA) to signs both the client's and server's certificates, the _trusted_dir_ must contain only the CA or intermediate certificates. + +Furthermore, Neo4j does not validate the certificates. +It is your responsibility to ensure that the certificates are valid. +See <> for details. +==== + +Configure the SSL backup policies in the _neo4j-admin.conf_ file on the backup client machine. + For example, if you have set up the backup SSL policy described in section <>, then you need to set the following in the _neo4j-admin.conf_ file: [source, properties] ---- dbms.ssl.policy.backup.enabled=true -dbms.ssl.policy.backup.base_directory=/path/to/certificates/backup +dbms.ssl.policy.backup.base_directory=certificates/backup dbms.ssl.policy.backup.private_key=private.key dbms.ssl.policy.backup.public_certificate=public.crt dbms.ssl.policy.backup.client_auth=REQUIRE @@ -974,11 +1000,6 @@ dbms.ssl.policy.backup.tls_versions=TLSv1.2,TLSv1.3 dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 ---- -[NOTE] -==== -Keep in mind that if the backup client is on a different machine from the Neo4j server, you must install the same SSL certs and keys on the backup client machine as well, so that the backup client can authenticate the server and vice versa. -==== - [[ssl-other-configs]] === Other configurations for SSL From 842b92b171072b3067e947ec29265c4e1719ac85 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 28 Oct 2025 12:37:53 +0000 Subject: [PATCH 6/7] further clarifications --- .../pages/backup-restore/online-backup.adoc | 4 +- .../ROOT/pages/security/ssl-framework.adoc | 53 ++++++++++++------- 2 files changed, 38 insertions(+), 19 deletions(-) diff --git a/modules/ROOT/pages/backup-restore/online-backup.adoc b/modules/ROOT/pages/backup-restore/online-backup.adoc index 1a8d9b152..e08c6ab6c 100644 --- a/modules/ROOT/pages/backup-restore/online-backup.adoc +++ b/modules/ROOT/pages/backup-restore/online-backup.adoc @@ -308,7 +308,9 @@ When using the `neo4j-admin database backup` command, you can configure the back For more information on how to configure SSL in Neo4j, see xref:security/ssl-framework.adoc[SSL framework]. Configuration for the backup server should be added to the _neo4j.conf_ file and configuration for backup client to the _neo4j-admin.conf_ file. -SSL settings should be set identically between both to ensure compatibility. +The easiest way to ensure compatibility is to use the same SSL policy configuration for both the server and the client. +However, this approach is not recommended for production environments, where it is better to use Certificate Authorities (CAs) to sign the certificates used by both the server and the client. +For details, see xref:security/ssl-framework.adoc[SSL framework]. The default backup port is 6362, configured with key `server.backup.listen_address`. The SSL configuration policy has the key of `dbms.ssl.policy.backup`. diff --git a/modules/ROOT/pages/security/ssl-framework.adoc b/modules/ROOT/pages/security/ssl-framework.adoc index 944cae015..5b660a0f0 100644 --- a/modules/ROOT/pages/security/ssl-framework.adoc +++ b/modules/ROOT/pages/security/ssl-framework.adoc @@ -217,6 +217,11 @@ The SSL policies are configured by assigning values to parameters of the followi * `scope` is the name of the communication channel, such as `bolt`, `https`, `cluster`, and `backup`. * `setting-suffix` can be any of the following: + +[NOTE] +==== +Neo4j does not validate the `setting-suffix` and if it is misspelled or incorrectly set, it will be ignored. +==== ++ [options="header"] |=== | Setting suffix | Description | Default value @@ -396,7 +401,7 @@ dbms.ssl.policy.bolt.public_certificate=public.crt + [TIP] ==== -If the certificate is a different path outside of NEO4J_HOME, then set the absolute path for the certificates directory. +If the certificate is located outside of `NEO4J_HOME`, then set the absolute path for the certificates directory. ==== .. Set the Bolt client authentication to `NONE` to disable the mutual authentication: @@ -624,7 +629,7 @@ dbms.ssl.policy.https.public_certificate=public.crt + [TIP] ==== -If the certificate is a different path outside of NEO4J_HOME, then set the absolute path for the certificates directory. +If the certificate is located outside of `NEO4J_HOME`, then set the absolute path for the certificates directory. ==== .. Set the HTTPS client authentication to `NONE` to disable the mutual authentication: @@ -786,7 +791,7 @@ dbms.ssl.policy.cluster.public_certificate=public.crt + [TIP] ==== -If the certificate is a different path outside of NEO4J_HOME, then set the absolute path for the certificates directory. +If the certificate is located outside of `NEO4J_HOME`, then set the absolute path for the certificates directory. ==== . Set the cluster client authentication to `REQUIRE` to enable the mutual authentication, which means that both ends of a channel have to authenticate: @@ -836,12 +841,25 @@ In a cluster topology, it is possible to take a backup from any server, and each * `server.cluster.listen_address` (port `6000`) If the <> is enabled and the backup communication uses port `6000`, then the communication channels are already encrypted. -The following steps assume that your backup is set up on a different port. + +However, if your backup communication uses a different port, you need to enable SSL for it by creating a separate SSL policy. + +When setting up SSL for backup communication, you can choose between two options for certificates: + +* self-signed certificates -- This is typically the case where the system is fully internal (not internet-facing), you control both ends of the connection, and the distribution of certificates can be automated and secured. +* certificates signed by a certificate authority (CA) -- This is typically the case where at least one end of the connection is internet-facing, and you want to use certificates signed by a trusted CA to avoid security flaws associated with self-signed certificates. + +There are three possible approaches to set up SSL for backup communication: + +* Use the same self-signed certificates in the _trusted_dir_ on both the backup server and client. +* Mirror the self-signed certificates if you want mutual TLS. +This means, the server has the client's certificates in its _trusted_dir_, and the client has the server's certificates in its _trusted_dir_. +* Use a certificate authority (CA) to signs both the client's and server's certificates. +In this case, the _trusted_dir_ must contain only the CA or intermediate certificates. ==== Set up SSL certificates for backup Create the folder structure and place the key and certificate files under it. -Then, configure the SSL backup policies in the _neo4j.conf_ file. . Create a directory _backup_ under _/certificates_ folder: + @@ -940,6 +958,7 @@ The owner/group should be configured to the user/group that will be running the Default user/group is neo4j/neo4j. ==== +[ssl-backup-server-config] ==== Set the backup SSL configuration in the _neo4j.conf_ file. . Set the backup SSL policy to `true`: @@ -959,7 +978,7 @@ dbms.ssl.policy.backup.public_certificate=public.crt + [TIP] ==== -If the certificate is a different path outside of NEO4J_HOME, then set the absolute path for the certificates directory. +If the certificate is located outside of `NEO4J_HOME`, then set the absolute path for the certificates directory. ==== . Set the backup client authentication to `REQUIRE` to enable the mutual authentication, which means that both ends of a channel have to authenticate: @@ -969,25 +988,23 @@ If the certificate is a different path outside of NEO4J_HOME, then set the absol dbms.ssl.policy.backup.client_auth=REQUIRE ---- +[NOTE] +==== +Neo4j does not validate the `setting-suffix` and if it is misspelled or incorrect, it will be ignored. +See <> for more details. +==== + +[ssl-backup-client-config] === Configure the backup client for SSL When using `neo4j-admin backup` command, the backup client needs to be configured to use SSL as well. Regardless of which backup port you are targeting (see <>), the backup client uses the SSL policy specified in `dbms.ssl.policy.backup.*`, given the same SSL policy name matches between server and client. -[NOTE] -==== -If the backup client is on a different machine from the Neo4j server, you must install sympathetic SSL certificates and keys on the backup client machine as well, so that the backup client can authenticate the server and vice versa. -If you want mutual TLS with self-signed certificates, the server must have the client's certificate in its _trusted_dir_, and the client must have the server's certificate in its _trusted_dir_. -If you use a certificate authority (CA) to signs both the client's and server's certificates, the _trusted_dir_ must contain only the CA or intermediate certificates. - -Furthermore, Neo4j does not validate the certificates. -It is your responsibility to ensure that the certificates are valid. -See <> for details. -==== +If the backup client is on a different machine from the backup server, you must install SSL certificates and keys on the backup client machine as well, so that the backup client can authenticate the server and vice versa. -Configure the SSL backup policies in the _neo4j-admin.conf_ file on the backup client machine. +The following steps assume that you have already set up the SSL certificates and keys on the backup server machine and you are using the self-signed certificates. -For example, if you have set up the backup SSL policy described in section <>, then you need to set the following in the _neo4j-admin.conf_ file: +For example, if you have set up the backup SSL policy described in section <>, then you need to set the following in the _neo4j-admin.conf_ file on the backup client machine: [source, properties] ---- From fcc5270e6eb2428f2dc4146eed039046a35ec8d9 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Thu, 6 Nov 2025 16:13:19 +0000 Subject: [PATCH 7/7] apply suggestions from review --- .../pages/backup-restore/online-backup.adoc | 9 +++--- .../ROOT/pages/security/ssl-framework.adoc | 30 +++++++++++-------- 2 files changed, 23 insertions(+), 16 deletions(-) diff --git a/modules/ROOT/pages/backup-restore/online-backup.adoc b/modules/ROOT/pages/backup-restore/online-backup.adoc index e08c6ab6c..5b8c8c7a6 100644 --- a/modules/ROOT/pages/backup-restore/online-backup.adoc +++ b/modules/ROOT/pages/backup-restore/online-backup.adoc @@ -309,8 +309,9 @@ For more information on how to configure SSL in Neo4j, see xref:security/ssl-fra Configuration for the backup server should be added to the _neo4j.conf_ file and configuration for backup client to the _neo4j-admin.conf_ file. The easiest way to ensure compatibility is to use the same SSL policy configuration for both the server and the client. -However, this approach is not recommended for production environments, where it is better to use Certificate Authorities (CAs) to sign the certificates used by both the server and the client. -For details, see xref:security/ssl-framework.adoc[SSL framework]. +For production environments, it is recommended to use Certificate Authorities (CAs) to sign certificates rather than self-signed certificates. + + The default backup port is 6362, configured with key `server.backup.listen_address`. The SSL configuration policy has the key of `dbms.ssl.policy.backup`. @@ -323,7 +324,7 @@ As an example, add the following content to your _neo4j.conf_ and _neo4j-admin.c dbms.ssl.policy.backup.enabled=true dbms.ssl.policy.backup.client_auth=REQUIRE dbms.ssl.policy.backup.tls_versions=TLSv1.2,TLSv1.3 -dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 +dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ---- .Client configuration in _neo4j-admin.conf_ @@ -332,7 +333,7 @@ dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE dbms.ssl.policy.backup.enabled=true dbms.ssl.policy.backup.client_auth=REQUIRE dbms.ssl.policy.backup.tls_versions=TLSv1.2,TLSv1.3 -dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 +dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ---- [TIP] diff --git a/modules/ROOT/pages/security/ssl-framework.adoc b/modules/ROOT/pages/security/ssl-framework.adoc index 5b660a0f0..86521ae09 100644 --- a/modules/ROOT/pages/security/ssl-framework.adoc +++ b/modules/ROOT/pages/security/ssl-framework.adoc @@ -846,15 +846,21 @@ However, if your backup communication uses a different port, you need to enable When setting up SSL for backup communication, you can choose between two options for certificates: -* self-signed certificates -- This is typically the case where the system is fully internal (not internet-facing), you control both ends of the connection, and the distribution of certificates can be automated and secured. -* certificates signed by a certificate authority (CA) -- This is typically the case where at least one end of the connection is internet-facing, and you want to use certificates signed by a trusted CA to avoid security flaws associated with self-signed certificates. +* self-signed certificates -- This is typically the case where you control both ends of the connection, and the distribution of certificates can be automated and secured. +However, self-signed certificates do not verify the identity of the server, so they cannot be trusted by clients and are vulnerable to man-in-the-middle attacks. +* certificates signed by a certificate authority (CA) -- more secure option, because a known trusted authority verifies the identity of the server, ensuring authenticity and preventing impersonation. -There are three possible approaches to set up SSL for backup communication: -* Use the same self-signed certificates in the _trusted_dir_ on both the backup server and client. -* Mirror the self-signed certificates if you want mutual TLS. -This means, the server has the client's certificates in its _trusted_dir_, and the client has the server's certificates in its _trusted_dir_. -* Use a certificate authority (CA) to signs both the client's and server's certificates. +You can configure SSL for backup communication in one of the following ways: + +* Use the same certificates in the _trusted_dir_ on both the backup server and client. + +This approach is simpler to configure but less secure, as both ends share the same identity and trust the same certificate. + +* Mirror the certificates on the backup server and client to achieve mutual authentication. + +Add the server certificate to the client's _trusted_dir_ and the client certificate to the server's _trusted_dir_. +This way, the server validates the client's certificate in addition to the typical normal TLS where only the client validates the server's certificate. + +* Use a certificate authority (CA) to sign both the client's and server's certificates. In this case, the _trusted_dir_ must contain only the CA or intermediate certificates. ==== Set up SSL certificates for backup @@ -1014,7 +1020,7 @@ dbms.ssl.policy.backup.private_key=private.key dbms.ssl.policy.backup.public_certificate=public.crt dbms.ssl.policy.backup.client_auth=REQUIRE dbms.ssl.policy.backup.tls_versions=TLSv1.2,TLSv1.3 -dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 +dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ---- [[ssl-other-configs]] @@ -1112,25 +1118,25 @@ However, you still can use them by explicitly specifying their configuration and .Bolt [source, properties] ---- -dbms.ssl.policy.bolt.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 +dbms.ssl.policy.bolt.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA3844 ---- .HTTPS [source, properties] ---- -dbms.ssl.policy.https.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 +dbms.ssl.policy.https.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA3844 ---- .Intra-cluster encryption [source, properties] ---- -dbms.ssl.policy.cluster.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 +dbms.ssl.policy.cluster.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA3844 ---- .Backup [source, properties] ---- -dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 +dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA3844 ---- [[ssl-ocsp-config]]