From 6676a49091511149e78cf629d6dca9ce5aede1b5 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 22 Oct 2024 09:30:48 +0100 Subject: [PATCH 1/3] Improve the documentation around the use of ciphers --- .../pages/backup-restore/online-backup.adoc | 8 ++- .../pages/clustering/setup/encryption.adoc | 70 ++++++++++++------- .../ROOT/pages/security/ssl-framework.adoc | 6 +- 3 files changed, 56 insertions(+), 28 deletions(-) diff --git a/modules/ROOT/pages/backup-restore/online-backup.adoc b/modules/ROOT/pages/backup-restore/online-backup.adoc index 609712ffe..2a1a6ceda 100644 --- a/modules/ROOT/pages/backup-restore/online-backup.adoc +++ b/modules/ROOT/pages/backup-restore/online-backup.adoc @@ -234,7 +234,7 @@ While the server is checkpointing, the backup job receives no data, which may le To extend the backup timeout, modify the xref:configuration/configuration-settings.adoc#config_dbms.cluster.catchup.client_inactivity_timeout[`dbms.cluster.catchup.client_inactivity_timeout`] setting, which restricts the network inactivity. It controls the timeout duration of the catchup protocol, which is the underlying protocol of multiple catchup processes, including backups. -You can also tune up xref:configuration/configuration-settings.adoc#_checkpoint_settings[the Checkpoint settings] or check that your disks are performant enough to handle the load. +You can also tune up xref:configuration/configuration-settings.adoc#_checkpoint_settings[the Checkpoint settings] or check that your disks are performant enough to handle the load. For more information, see xref:performance/disks-ram-and-other-tips.adoc#performance-checkpoint-iops-limit[Checkpoint IOPS limit]. To read more about checkpointing, see xref:database-internals/checkpointing.adoc[Database internals -> Checkpointing and log pruning]. @@ -318,8 +318,12 @@ dbms.ssl.policy.backup.ciphers=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 dbms.ssl.policy.backup.client_auth=REQUIRE ---- -[NOTE] +[TIP] ==== +Neo4j 5.24 also supports TLSv1.3. +To use both TLSv1.2 and TLSv1.3 versions, you must specify which ciphers to be enforced for each version. +Otherwise, Neo4j could use every possible cipher in the JVM for those versions, leading to a less secure configuration. + For a detailed list of recommendations regarding security in Neo4j, see xref:security/checklist.adoc[Security checklist]. ==== diff --git a/modules/ROOT/pages/clustering/setup/encryption.adoc b/modules/ROOT/pages/clustering/setup/encryption.adoc index 867e93d2a..f8738c1c8 100644 --- a/modules/ROOT/pages/clustering/setup/encryption.adoc +++ b/modules/ROOT/pages/clustering/setup/encryption.adoc @@ -1,5 +1,6 @@ :description: This section describes how to secure the cluster communication between server instances. :page-aliases: clustering/intra-cluster-encryption.adoc + [role=enterprise-edition] [[clustering-intra-cluster-encryption]] = Intra-cluster encryption @@ -104,41 +105,62 @@ By default, cluster communication is unencrypted. To configure a cluster to encrypt its intra-cluster communication, set `dbms.ssl.policy.cluster.enabled` to `true`. An SSL policy utilizes the installed cryptographic objects and additionally allows parameters to be configured. -Use the following parameters in the configuration: - -.Example settings -[options="header"] -|=== -| Setting suffix | Value | Comment -| `client_auth` | `REQUIRE` | Setting this to `REQUIRE` effectively enables mutual authentication for servers. -| `ciphers` | `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384` | -A particular single strong cipher can be enforced and thus remove any doubt about which cipher gets negotiated and chosen. -The selected cipher offers Perfect Forward Secrecy (PFS) which is generally desirable. -It also uses Advanced Encryption Standard (AES) for symmetric encryption which has great support for acceleration in hardware and thus allows performance to generally be negligibly affected. -| `tls_versions` | `TLSv1.2` | -With control of the entire cluster, the latest TLS standard can be enforced without any concern for backwards compatibility. +Use the parameters in one of the following configurations: + +[.tabbed-example] +===== +[.include-with-one-TLS-version] +====== + +The following example assumes that an SSL policy is created and configured as per the <> and uses the default TLSv1.2. + +Add the following content to the _neo4j.conf_ file: + +[source, properties] +---- +dbms.ssl.policy.cluster.enabled=true +dbms.ssl.policy.cluster.tls_versions=TLSv1.2 \ # <1> +dbms.ssl.policy.cluster.ciphers=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 \ # <2> +dbms.ssl.policy.cluster.client_auth=REQUIRE # <3> +---- + +<1> With control of the entire cluster, the default TLS standard can be enforced without any concern for backwards compatibility. It has no known security vulnerabilities and uses the most modern algorithms for key exchanges, etc. -|=== +<2> A particular single strong cipher can be enforced and thus remove any doubt about which cipher gets negotiated and chosen. +The selected cipher offers Perfect Forward Secrecy (PFS) and uses the Advanced Encryption Standard (AES) for symmetric encryption. +AES has great support for hardware acceleration and thus allows performance to be generally negligibly affected. +<3> Setting the cluster client authentication to `REQUIRE` enables mutual authentication, meaning both ends of a channel must authenticate. -In the following example, an SSL policy is created and configured that is used in the example cluster. -.Configure the cluster SSL policy -==== -This example assumes that the directory structure is created, and certificate files are installed, as per the previous example. +====== +[role=include-with-two-TLS-versions label--new-5.24] +====== + +The following example assumes that an SSL policy is created and configured as per the <> and uses both TLSv1.2 and TLSv1.3. Add the following content to the _neo4j.conf_ file: [source, properties] ---- dbms.ssl.policy.cluster.enabled=true -dbms.ssl.policy.cluster.tls_versions=TLSv1.2 -dbms.ssl.policy.cluster.ciphers=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 -dbms.ssl.policy.cluster.client_auth=REQUIRE +dbms.ssl.policy.bolt.tls_versions=TLSv1.3,TLSv1.2 \ # <1> +dbms.ssl.policy.bolt.ciphers=TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_DSS_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA \ # <2> +dbms.ssl.policy.cluster.client_auth=REQUIRE \# <3> ---- -Any user data communicated between instances is now secured. -Note that an instance that is not correctly setup is not able to communicate with the others. -==== +<1> With control of the entire cluster, the default TLS standard can be enforced without any concern for backwards compatibility. +It has no known security vulnerabilities and uses the most modern algorithms for key exchanges, etc. +<2> If you want to specify ciphers for both supported TLS versions, you must specify ciphers for each TLS version not to get more ciphers than expected. +The selected ciphers offer Perfect Forward Secrecy (PFS) and use the Advanced Encryption Standard (AES) for symmetric encryption. +AES has great support for hardware acceleration and thus allows performance to be generally negligibly affected. +<3> Setting the cluster client authentication to `REQUIRE` enables mutual authentication, meaning both ends of a channel must authenticate. +They have no known security vulnerabilities and use the most modern algorithms for key exchanges, etc. + +====== +===== + +Any user data communicated between servers is now secured. +Note that a server that is not correctly setup is not able to communicate with the others. The policy must be configured on every server with the same settings. The actual cryptographic objects installed are mostly different since they do not share the same private keys and corresponding certificates. diff --git a/modules/ROOT/pages/security/ssl-framework.adoc b/modules/ROOT/pages/security/ssl-framework.adoc index aa661475c..9d3f72b23 100644 --- a/modules/ROOT/pages/security/ssl-framework.adoc +++ b/modules/ROOT/pages/security/ssl-framework.adoc @@ -284,10 +284,12 @@ The SSL policies are configured by assigning values to parameters of the followi Names (SAN) fields. If the address does not match those fields, the client disconnects. | `false` | `ciphers` | A comma-separated list of ciphers suites allowed during cipher negotiation. - Valid values depend on the current JRE and SSL provider. + Valid values depend on the current JRE, SSL provider, and TLS version. For Ciphers supported by the Oracle JRE, see the link:https://docs.oracle.com/en/java/javase/17/docs/specs/security/standard-names.html#jsse-cipher-suite-names[Oracle official documentation]. | Java platform default allowed cipher suites. -| `tls_versions` | A comma-separated list of allowed TLS versions. By default only TLSv1.2 and TLSv1.3 are allowed. | `TLSv1.2` + +| `tls_versions` | A comma-separated list of allowed TLS versions. By default only TLSv1.2 and TLSv1.3 are allowed. + To use both TLSv1.2 and TLSv1.3 versions, you must specify which ciphers to be enforced for each version. + Otherwise, Neo4j could use every possible cipher in the JVM for those versions, leading to a less secure configuration. | `TLSv1.2` + `TLSv1.3` label:new[Supported from Neo4j 5.24] | `client_auth` | Whether or not clients must be authenticated. Setting this to `REQUIRE` enables mutual authentication for servers. From 06003136ec555fab3ad6307becf998832a2e0e3b Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 22 Oct 2024 09:57:16 +0100 Subject: [PATCH 2/3] Update modules/ROOT/pages/clustering/setup/encryption.adoc --- modules/ROOT/pages/clustering/setup/encryption.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/encryption.adoc b/modules/ROOT/pages/clustering/setup/encryption.adoc index f8738c1c8..b42d0b7c3 100644 --- a/modules/ROOT/pages/clustering/setup/encryption.adoc +++ b/modules/ROOT/pages/clustering/setup/encryption.adoc @@ -143,7 +143,7 @@ Add the following content to the _neo4j.conf_ file: [source, properties] ---- dbms.ssl.policy.cluster.enabled=true -dbms.ssl.policy.bolt.tls_versions=TLSv1.3,TLSv1.2 \ # <1> +dbms.ssl.policy.cluster.tls_versions=TLSv1.3,TLSv1.2 \ # <1> dbms.ssl.policy.bolt.ciphers=TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_DSS_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA \ # <2> dbms.ssl.policy.cluster.client_auth=REQUIRE \# <3> ---- From ff99cbc08d0582fd2fd182579093c9d0b9ac95fb Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Tue, 22 Oct 2024 09:57:36 +0100 Subject: [PATCH 3/3] Update modules/ROOT/pages/clustering/setup/encryption.adoc --- modules/ROOT/pages/clustering/setup/encryption.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/encryption.adoc b/modules/ROOT/pages/clustering/setup/encryption.adoc index b42d0b7c3..cfdddeeee 100644 --- a/modules/ROOT/pages/clustering/setup/encryption.adoc +++ b/modules/ROOT/pages/clustering/setup/encryption.adoc @@ -144,7 +144,7 @@ Add the following content to the _neo4j.conf_ file: ---- dbms.ssl.policy.cluster.enabled=true dbms.ssl.policy.cluster.tls_versions=TLSv1.3,TLSv1.2 \ # <1> -dbms.ssl.policy.bolt.ciphers=TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_DSS_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA \ # <2> +dbms.ssl.policy.cluster.ciphers=TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_DSS_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA \ # <2> dbms.ssl.policy.cluster.client_auth=REQUIRE \# <3> ----