Skip to content

Commit 6a43abb

Browse files
renetapopovarenetapopova
authored
Update the ssl config for backup (#2610)
1 parent 1390ef6 commit 6a43abb

File tree

2 files changed

+129
-49
lines changed

2 files changed

+129
-49
lines changed

‎modules/ROOT/pages/backup-restore/online-backup.adoc‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -308,19 +308,32 @@ When using the `neo4j-admin database backup` command, you can configure the back
308308
For more information on how to configure SSL in Neo4j, see xref:security/ssl-framework.adoc[SSL framework].
309309

310310
Configuration for the backup server should be added to the _neo4j.conf_ file and configuration for backup client to the _neo4j-admin.conf_ file.
311-
SSL settings should be set identically between both to ensure compatibility.
311+
The easiest way to ensure compatibility is to use the same SSL policy configuration for both the server and the client.
312+
For production environments, it is recommended to use Certificate Authorities (CAs) to sign certificates rather than self-signed certificates.
313+
314+
312315

313316
The default backup port is 6362, configured with key `server.backup.listen_address`.
314317
The SSL configuration policy has the key of `dbms.ssl.policy.backup`.
315318

316319
As an example, add the following content to your _neo4j.conf_ and _neo4j-admin.conf_ files:
317320

321+
.Server configuration in _neo4j.conf_
322+
[source, properties]
323+
----
324+
dbms.ssl.policy.backup.enabled=true
325+
dbms.ssl.policy.backup.client_auth=REQUIRE
326+
dbms.ssl.policy.backup.tls_versions=TLSv1.2,TLSv1.3
327+
dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
328+
----
329+
330+
.Client configuration in _neo4j-admin.conf_
318331
[source, properties]
319332
----
320333
dbms.ssl.policy.backup.enabled=true
321-
dbms.ssl.policy.backup.tls_versions=TLSv1.2
322-
dbms.ssl.policy.backup.ciphers=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
323334
dbms.ssl.policy.backup.client_auth=REQUIRE
335+
dbms.ssl.policy.backup.tls_versions=TLSv1.2,TLSv1.3
336+
dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
324337
----
325338

326339
[TIP]

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

Lines changed: 113 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -180,7 +180,7 @@ You can identify them by the line `-----BEGIN RSA PRIVATE KEY-----` at the begin
180180
While Neo4j 5.0 can load and use those keys, they are considered deprecated and will be removed in a future version.
181181
====
182182
183-
183+
[[ssl-validate-certs]]
184184
=== Validate the key and the certificate
185185
186186
If you need, you can validate the key file and the certificate as follows:
@@ -217,6 +217,11 @@ The SSL policies are configured by assigning values to parameters of the followi
217217
* `scope` is the name of the communication channel, such as `bolt`, `https`, `cluster`, and `backup`.
218218
* `setting-suffix` can be any of the following:
219219
+
220+
[NOTE]
221+
====
222+
Neo4j does not validate the `setting-suffix` and if it is misspelled or incorrectly set, it will be ignored.
223+
====
224+
+
220225
[options="header"]
221226
|===
222227
| Setting suffix | Description | Default value
@@ -396,7 +401,7 @@ dbms.ssl.policy.bolt.public_certificate=public.crt
396401
+
397402
[TIP]
398403
====
399-
If the certificate is a different path outside of NEO4J_HOME, then set the absolute path for the certificates directory.
404+
If the certificate is located outside of `NEO4J_HOME`, then set the absolute path for the certificates directory.
400405
====
401406
402407
.. Set the Bolt client authentication to `NONE` to disable the mutual authentication:
@@ -624,7 +629,7 @@ dbms.ssl.policy.https.public_certificate=public.crt
624629
+
625630
[TIP]
626631
====
627-
If the certificate is a different path outside of NEO4J_HOME, then set the absolute path for the certificates directory.
632+
If the certificate is located outside of `NEO4J_HOME`, then set the absolute path for the certificates directory.
628633
====
629634
630635
.. Set the HTTPS client authentication to `NONE` to disable the mutual authentication:
@@ -655,22 +660,23 @@ openssl s_client -connect my_domain.com:7473
655660
Intra-cluster encryption is the security solution for the cluster communication.
656661
The Neo4j cluster communicates on 3 ports:
657662
658-
* 6000 - Transactions
659-
* 7000 - Raft communications
660-
* 7688 - Server side routing
663+
* `6000` - Transactions
664+
* `7000` - Raft communications
665+
* `7688` - Server side routing
666+
667+
To configure SSL for intra-cluster communication, create the folder structure and place the key and certificate files under it.
668+
Then, configure the SSL cluster policies in the _neo4j.conf_ file and test that the intra-cluster communication is encrypted.
661669
662-
To set up intra-cluster encryption, on each server create the folder structure and place the key file and the certificates under those.
663-
Then, you need to configure the SSL cluster policies in the _neo4j.conf_ file and test that the intra-cluster communication is encrypted.
670+
==== Set up SSL certificates for intra-cluster communications
664671
665-
. Set up the _cluster_ folder under _certificates_.
666-
.. Create a directory _cluster_ under_<NEO4J_HOME>/certificates_ folder:
672+
. Create a directory _cluster_ under _<NEO4J_HOME>/certificates_ folder:
667673
+
668674
[source, shell]
669675
----
670676
mkdir certificates/cluster
671677
----
672678
673-
.. Create a directory _trusted_ and _revoked_ under _<NEO4J_HOME>/certificates/cluster_ folder:
679+
. Create a directory _trusted_ and _revoked_ under _<NEO4J_HOME>/certificates/cluster_ folder:
674680
+
675681
[source, shell]
676682
----
@@ -703,9 +709,11 @@ Thus, the servers are able to establish trust relationships with each other.
703709
----
704710
cp /path/to/certs/public.crt certificates/cluster/revoked
705711
----
706-
+
712+
713+
==== Verify the folder structure and permissions
714+
707715
The folder structure should look like this with the right file permissions and the groups and ownerships:
708-
+
716+
709717
[options="header", cols="3,1,4*m"]
710718
|===
711719
| Path
@@ -757,21 +765,22 @@ The folder structure should look like this with the right file permissions and t
757765
| 0755
758766
| drwxr-xr-x
759767
|===
760-
+
768+
761769
[TIP]
762770
====
763771
The owner/group should be configured to the user/group that will be running the `neo4j` service.
764772
Default user/group is neo4j/neo4j.
765773
====
766774
767-
. Set the cluster SSL configuration in _neo4j.conf_.
768-
.. Set the cluster SSL policy to `true`:
775+
==== Set the cluster SSL configuration in _neo4j.conf_
776+
777+
. Set the cluster SSL policy to `true`:
769778
+
770779
[source, properties]
771780
----
772781
dbms.ssl.policy.cluster.enabled=true
773782
----
774-
.. Set the appropriate certificates path and the right key and cert files:
783+
. Set the appropriate certificates path and the right key and cert files:
775784
+
776785
[source, properties]
777786
----
@@ -782,10 +791,10 @@ dbms.ssl.policy.cluster.public_certificate=public.crt
782791
+
783792
[TIP]
784793
====
785-
If the certificate is a different path outside of NEO4J_HOME, then set the absolute path for the certificates directory.
794+
If the certificate is located outside of `NEO4J_HOME`, then set the absolute path for the certificates directory.
786795
====
787796
788-
.. Set the cluster client authentication to `REQUIRE` to enable the mutual authentication, which means that both ends of a channel have to authenticate:
797+
. Set the cluster client authentication to `REQUIRE` to enable the mutual authentication, which means that both ends of a channel have to authenticate:
789798
+
790799
[source, properties]
791800
----
@@ -799,14 +808,16 @@ The actual xref:security/ssl-framework.adoc#term-ssl-cryptographic-objects[crypt
799808
The trusted CA certificate will be shared however.
800809
====
801810
802-
.. Verify that the intra-cluster communication is encrypted.
811+
==== Verify that the intra-cluster communication is encrypted
812+
813+
Once the intra-cluster encryption is enabled, you can verify that the communication is encrypted.
803814
You may use an external tooling, such as Nmap (https://nmap.org/download.html):
804-
+
815+
805816
[source, shell]
806817
----
807818
nmap --script ssl-enum-ciphers -p <port> <hostname>
808819
----
809-
+
820+
810821
[NOTE]
811822
====
812823
The hostname and port have to be adjusted according to your configuration.
@@ -823,24 +834,47 @@ For more details on securing the comunication between the cluster servers, see x
823834
[[ssl-backup-config]]
824835
=== Configure SSL for backup communication
825836
826-
In a single instance, by default the backup communication happens on port `6362`.
827-
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.
828-
These ports are configured by `dbms.backup.listen.address` (port `6362`) and `server.cluster.listen_address` (port `6000`) respectively.
829-
If the intra-cluster encryption is enabled and the backup communication is using port `6000`, then your communication channels are already encrypted.
830-
The following steps assumes that your backup is set up on a different port.
837+
In a single instance, the backup communication happens on port `6362` by default. +
838+
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:
839+
840+
* `dbms.backup.listen.address` (port `6362`)
841+
* `server.cluster.listen_address` (port `6000`)
842+
843+
If the <<ssl-cluster-config, intra-cluster encryption>> is enabled and the backup communication uses port `6000`, then the communication channels are already encrypted.
844+
845+
However, if your backup communication uses a different port, you need to enable SSL for it by creating a separate SSL policy.
846+
847+
When setting up SSL for backup communication, you can choose between two options for certificates:
848+
849+
* 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.
850+
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.
851+
* 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.
852+
853+
854+
You can configure SSL for backup communication in one of the following ways:
855+
856+
* Use the same certificates in the _trusted_dir_ on both the backup server and client. +
857+
This approach is simpler to configure but less secure, as both ends share the same identity and trust the same certificate.
858+
859+
* Mirror the certificates on the backup server and client to achieve mutual authentication. +
860+
Add the server certificate to the client's _trusted_dir_ and the client certificate to the server's _trusted_dir_.
861+
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.
862+
863+
* Use a certificate authority (CA) to sign both the client's and server's certificates.
864+
In this case, the _trusted_dir_ must contain only the CA or intermediate certificates.
831865
832-
To set up SSL for backup communication, create the folder structure and place the key file and the certificates under those.
833-
Then, you need to configure the SSL backup policies in the _neo4j.conf_ file.
866+
==== Set up SSL certificates for backup
834867
835-
. Set up the _backup_ folder under _certificates_.
836-
.. Create a directory _backup_ under _<NEO4J_HOME>/certificates_ folder:
868+
Create the folder structure and place the key and certificate files under it.
869+
870+
. Create a directory _backup_ under _<NEO4J_HOME>/certificates_ folder:
837871
+
838872
[source, shell]
839873
----
840874
mkdir certificates/backup
841875
----
842876
843-
.. Create a directory _trusted_ and _revoked_ under _<NEO4J_HOME>/certificates/backup_ folder:
877+
. Create a directory _trusted_ and _revoked_ under _<NEO4J_HOME>/certificates/backup_ folder:
844878
+
845879
[source, shell]
846880
----
@@ -867,9 +901,11 @@ cp /path/to/certs/public.crt certificates/backup/trusted
867901
----
868902
cp /path/to/certs/public.crt certificates/backup/revoked
869903
----
870-
+
871-
The folder structure should look like this with the right file permissions and the groups and ownerships:
872-
+
904+
905+
==== Verify the backup folder structure and permissions
906+
907+
The folder structure should look like this with the right file permissions and the groups and ownerships, assuming the `neo4j` user runs the service:
908+
873909
[options="header", cols="3,1,4*m"]
874910
|===
875911
| Path
@@ -921,21 +957,23 @@ The folder structure should look like this with the right file permissions and t
921957
| 0755
922958
| drwxr-xr-x
923959
|===
924-
+
960+
925961
[TIP]
926962
====
927963
The owner/group should be configured to the user/group that will be running the `neo4j` service.
928964
Default user/group is neo4j/neo4j.
929965
====
930966
931-
. Set the backup SSL configuration in _neo4j.conf_.
932-
.. Set the backup SSL policy to `true`:
967+
[ssl-backup-server-config]
968+
==== Set the backup SSL configuration in the _neo4j.conf_ file.
969+
970+
. Set the backup SSL policy to `true`:
933971
+
934972
[source, properties]
935973
----
936974
dbms.ssl.policy.backup.enabled=true
937975
----
938-
.. Set the appropriate certificates path and the right key and cert files:
976+
. Set the appropriate certificates path and the right key and cert files:
939977
+
940978
[source, properties]
941979
----
@@ -946,16 +984,45 @@ dbms.ssl.policy.backup.public_certificate=public.crt
946984
+
947985
[TIP]
948986
====
949-
If the certificate is a different path outside of NEO4J_HOME, then set the absolute path for the certificates directory.
987+
If the certificate is located outside of `NEO4J_HOME`, then set the absolute path for the certificates directory.
950988
====
951989
952-
.. Set the backup client authentication to `REQUIRE` to enable the mutual authentication, which means that both ends of a channel have to authenticate:
990+
. Set the backup client authentication to `REQUIRE` to enable the mutual authentication, which means that both ends of a channel have to authenticate:
953991
+
954992
[source, properties]
955993
----
956994
dbms.ssl.policy.backup.client_auth=REQUIRE
957995
----
958996
997+
[NOTE]
998+
====
999+
Neo4j does not validate the `setting-suffix` and if it is misspelled or incorrect, it will be ignored.
1000+
See <<ssl-configuration, Configuration>> for more details.
1001+
====
1002+
1003+
[ssl-backup-client-config]
1004+
=== Configure the backup client for SSL
1005+
1006+
When using `neo4j-admin backup` command, the backup client needs to be configured to use SSL as well.
1007+
Regardless of which backup port you are targeting (see <<ssl-backup-config>>), the backup client uses the SSL policy specified in `dbms.ssl.policy.backup.*`, given the same SSL policy name matches between server and client.
1008+
1009+
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.
1010+
1011+
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.
1012+
1013+
For example, if you have set up the backup SSL policy described in section <<ssl-backup-config>>, then you need to set the following in the _neo4j-admin.conf_ file on the backup client machine:
1014+
1015+
[source, properties]
1016+
----
1017+
dbms.ssl.policy.backup.enabled=true
1018+
dbms.ssl.policy.backup.base_directory=certificates/backup
1019+
dbms.ssl.policy.backup.private_key=private.key
1020+
dbms.ssl.policy.backup.public_certificate=public.crt
1021+
dbms.ssl.policy.backup.client_auth=REQUIRE
1022+
dbms.ssl.policy.backup.tls_versions=TLSv1.2,TLSv1.3
1023+
dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
1024+
----
1025+
9591026
[[ssl-other-configs]]
9601027
=== Other configurations for SSL
9611028
@@ -1051,25 +1118,25 @@ However, you still can use them by explicitly specifying their configuration and
10511118
.Bolt
10521119
[source, properties]
10531120
----
1054-
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
1121+
dbms.ssl.policy.bolt.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA3844
10551122
----
10561123
10571124
.HTTPS
10581125
[source, properties]
10591126
----
1060-
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
1127+
dbms.ssl.policy.https.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA3844
10611128
----
10621129
10631130
.Intra-cluster encryption
10641131
[source, properties]
10651132
----
1066-
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
1133+
dbms.ssl.policy.cluster.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA3844
10671134
----
10681135
10691136
.Backup
10701137
[source, properties]
10711138
----
1072-
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
1139+
dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA3844
10731140
----
10741141
10751142
[[ssl-ocsp-config]]
@@ -1162,7 +1229,7 @@ This means that while new connections will use new certificates, the existing co
11621229
Even if a certificate expires, active connections remain unaffected because the certificates are only used during the initial connection handshake.
11631230
11641231
. 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>>.
1165-
1232+
11661233
11671234
[[ssl-terminology]]
11681235
== Terminology

0 commit comments

Comments
 (0)