diff --git a/modules/ROOT/pages/authentication-authorization/index.adoc b/modules/ROOT/pages/authentication-authorization/index.adoc index 5db485a8e..9703d9b79 100644 --- a/modules/ROOT/pages/authentication-authorization/index.adoc +++ b/modules/ROOT/pages/authentication-authorization/index.adoc @@ -82,7 +82,7 @@ xref:authentication-authorization/built-in-roles.adoc#auth-built-in-roles-overvi The Neo4j security model is stored in the system graph, which is maintained in the xref:database-administration/index.adoc#manage-databases-system[`system` database]. All administrative commands need to be executed against it. -When connected to the DBMS over xref:configuration/connectors.adoc[], administrative commands are automatically routed to the `system` database. +When connected to the DBMS over xref:configuration/connectors.adoc[Configure network connectors], administrative commands are automatically routed to the `system` database. [[auth-terminology]] == Terminology diff --git a/modules/ROOT/pages/configuration/configuration-settings.adoc b/modules/ROOT/pages/configuration/configuration-settings.adoc index 5423d5fbb..4dc821ff2 100644 --- a/modules/ROOT/pages/configuration/configuration-settings.adoc +++ b/modules/ROOT/pages/configuration/configuration-settings.adoc @@ -889,7 +889,7 @@ m|+++PRIMARY+++ Connection settings control the communication between servers and between a server and a client. Neo4j provides support for Bolt, HTTP, and HTTPS protocols via connectors. -For more information about the connectors, see xref:configuration/connectors.adoc[Configure connectors]. +For more information about the connectors, see xref:configuration/connectors.adoc[Configure network connectors]. When configuring the HTTPS or xref:/performance/bolt-thread-pool-configuration.adoc[Bolt], see also <<_security_settings>> and xref:security/ssl-framework.adoc[SSL framework] for details on how to work with SSL certificates. diff --git a/modules/ROOT/pages/configuration/ports.adoc b/modules/ROOT/pages/configuration/ports.adoc index 090b7a769..b6b5639b5 100644 --- a/modules/ROOT/pages/configuration/ports.adoc +++ b/modules/ROOT/pages/configuration/ports.adoc @@ -114,7 +114,7 @@ Default port: `7474` * Used by Neo4j Browser and the HTTP API. -For more information, see xref:configuration/connectors.adoc[]. +For more information, see xref:configuration/connectors.adoc[Configure network connectors]. === HTTPS @@ -145,7 +145,7 @@ Default port: `7473` * Used by Neo4j Browser and the HTTP API. -For more information, see xref:configuration/connectors.adoc[]. +For more information, see xref:configuration/connectors.adoc[Configure network connectors]. === Bolt @@ -180,7 +180,7 @@ Default port: `7687` * Used by Cypher Shell, Neo4j Browser, and the official Neo4j drivers. -For more information, see xref:configuration/connectors.adoc[]. +For more information, see xref:configuration/connectors.adoc[Configure network connectors]. [role=enterprise-edition] diff --git a/modules/ROOT/pages/docker/security.adoc b/modules/ROOT/pages/docker/security.adoc index 7f79ff4f1..debe003ca 100644 --- a/modules/ROOT/pages/docker/security.adoc +++ b/modules/ROOT/pages/docker/security.adoc @@ -77,7 +77,7 @@ dbms.ssl.policy.bolt.public_certificate=public.crt ==== For more information on configuring SSL policies, see xref:security/ssl-framework.adoc#ssl-configuration[Configuration]. -For more information on configuring connectors, see xref:configuration/connectors.adoc#connectors-configuration-options[Configuration options]. +For more information on configuring network connectors, see xref:configuration/connectors.adoc#connectors-configuration-options[Configure network connectors -> Configuration options]. ==== diff --git a/modules/ROOT/pages/security/checklist.adoc b/modules/ROOT/pages/security/checklist.adoc index 1cc68ff7c..cfacdd125 100644 --- a/modules/ROOT/pages/security/checklist.adoc +++ b/modules/ROOT/pages/security/checklist.adoc @@ -28,7 +28,7 @@ Refer to xref:configuration/file-locations.adoc#file-locations-permissions[File For details, see xref:clustering/setup/encryption.adoc[Intra-cluster encryption]. .. If using clustering, configure and use encryption for backups. This ensures that only servers with the specified SSL policy and SSL certificates can access the server and perform the backup. -.. For configuring your Bolt and HTTPS connectors, refer to xref:configuration/connectors.adoc[Configure connectors]. +.. For configuring your Bolt and HTTPS connectors, refer to xref:configuration/connectors.adoc[Configure network connectors]. .. If using LDAP, configure your LDAP system with encryption via StartTLS. For more information, see xref:authentication-authorization/ldap-integration.adoc#auth-ldap-encrypted-starttls[Use LDAP with encryption via StartTLS]. . Be on top of the security for custom extensions: diff --git a/modules/ROOT/pages/security/ssl-framework.adoc b/modules/ROOT/pages/security/ssl-framework.adoc index cd6b72b0a..fd8419439 100644 --- a/modules/ROOT/pages/security/ssl-framework.adoc +++ b/modules/ROOT/pages/security/ssl-framework.adoc @@ -18,70 +18,37 @@ This page describes how to set up SSL within your environment, how to view, vali The secure networking in Neo4j is provided through the Netty library, which supports both the native JDK SSL provider as well as Netty-supported OpenSSL derivatives. Each version of Neo4j ships with a version of Netty and Netty requires a specific version of the `netty-tcnative` library for compatibility, which can be found in the `lib/` directory of the Neo4j installation. +2025.01.0 ships with _Netty 2.0.69.Final_ and requires _netty-tcnative-boringssl-static-2.0.69.Final_. -Follow these steps to use OpenSSL: +// To uncomment the following when the table contains more than one entry. +//================================== +// The following table shows information about supported Neo4j versions and the required `netty-tcnative` dependency. +// If a Neo4j version is not listed, use the table entry for the previous Neo4j version. + +// .Netty-TCNative support per Neo4j version +// [options="header,autowidth", cols="1,4"] +// |=== +// | Neo4j version +// | tcnative version -* Install a suitable `netty-tcnative` dependency into the `plugins/` directory of Neo4j. -** Dependencies can be downloaded from https://netty.io/wiki/forked-tomcat-native.html. -** Which `netty-tcnative` version you need depends upon the Neo4j version. -For versioning details, see the <> table. -Make sure to install a build variant that matches your OS and architecture. -* Set `xref:configuration/configuration-settings.adoc#config_dbms.netty.ssl.provider[dbms.netty.ssl.provider]=OPENSSL`. -* Restart Neo4j. +// | 2025.01 +// | 2.0.69.Final and netty-tcnative-boringssl-static-2.0.69.Final +// |=== [NOTE] ==== -Using dynamic versions of tcnative will require installation of platform-specific dependency libraries as described in https://netty.io/wiki/forked-tomcat-native.html. +Using dynamic versions of tcnative requires installation of platform-specific dependency libraries as described in https://netty.io/wiki/forked-tomcat-native.html. -In most use cases, the statically linked `boringssl` variant of `netty-tcnative` will be sufficient to enable SSL encryption. +In most use cases, the statically linked `boringssl` variant of `netty-tcnative` is sufficient to enable SSL encryption. ==== -The following table shows information about supported Neo4j versions and when the `netty-tcnative` dependency was updated. -If a Neo4j version is not listed, use the table entry for the previous Neo4j version. - -[[table]] -.Netty-TCNative support per Neo4j version -[options="header,autowidth", cols="1,4,2"] -|=== -| Neo4j version -| tcnative version -| Direct link - -| 5.23 -| 2.0.65.Final. Only netty-tcnative-boringssl-static is required. -| https://search.maven.org/artifact/io.netty/netty-tcnative-boringssl-static/2.0.65.Final/jar[netty-tcnative-boringssl-static-2.0.65.Final] - -| 5.20 -| 2.0.65.Final. Both netty-tcnative-boringssl-static and netty-tcnative-classes are required. -| https://search.maven.org/artifact/io.netty/netty-tcnative-boringssl-static/2.0.65.Final/jar[netty-tcnative-boringssl-static-2.0.65.Final] -https://search.maven.org/artifact/io.netty/netty-tcnative-classes/2.0.65.Final/jar[netty-tcnative-classes-2.0.65.Final] - -| 5.10 -| 2.0.61.Final. Both netty-tcnative-boringssl-static and netty-tcnative-classes are required. -| https://search.maven.org/artifact/io.netty/netty-tcnative-boringssl-static/2.0.61.Final/jar[netty-tcnative-boringssl-static-2.0.61.Final] -https://search.maven.org/artifact/io.netty/netty-tcnative-classes/2.0.61.Final/jar[netty-tcnative-classes-2.0.61.Final] - -| 5.8 -| 2.0.60.Final. Both netty-tcnative-boringssl-static and netty-tcnative-classes are required. -| https://search.maven.org/artifact/io.netty/netty-tcnative-boringssl-static/2.0.60.Final/jar[netty-tcnative-boringssl-static-2.0.60.Final] -https://search.maven.org/artifact/io.netty/netty-tcnative-classes/2.0.60.Final/jar[netty-tcnative-classes-2.0.60.Final] - -| 5.5 -| 2.0.56.Final. Both netty-tcnative-boringssl-static and netty-tcnative-classes are required. -| https://search.maven.org/artifact/io.netty/netty-tcnative-boringssl-static/2.0.56.Final/jar[netty-tcnative-boringssl-static-2.0.56.Final] -https://search.maven.org/artifact/io.netty/netty-tcnative-classes/2.0.56.Final/jar[netty-tcnative-classes-2.0.56.Final] - -| 5.1 -| 2.0.54.Final. Both netty-tcnative-boringssl-static and netty-tcnative-classes are required. -| https://search.maven.org/artifact/io.netty/netty-tcnative-boringssl-static/2.0.54.Final/jar[netty-tcnative-boringssl-static-2.0.54.Final] -https://search.maven.org/artifact/io.netty/netty-tcnative-classes/2.0.54.Final/jar[netty-tcnative-classes-2.0.54.Final] -|=== - +Follow these steps to use OpenSSL: -[NOTE] -==== +. Install a suitable `netty-tcnative` dependency into the `plugins/` directory of Neo4j. +Which `netty-tcnative` version you need depends on your OS and architecture. +. Set `xref:configuration/configuration-settings.adoc#config_dbms.netty.ssl.provider[dbms.netty.ssl.provider]=OPENSSL`. Using OpenSSL can significantly improve performance, especially for AES-GCM-cryptos, e.g. TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256. -==== +. Restart Neo4j. [[ssl-certificates]] == Certificates and private keys @@ -110,21 +77,21 @@ To achieve this, you should concatenate each PEM-encoded certificate, starting f [TIP] ==== -If the same certificates are used across all instances of the cluster, make sure that when generating the certificates to include the DNS names of all the cluster instances in the certificates. +If the same certificates are used across all instances of the cluster, ensure that the DNS names of all cluster instances are included in the certificates when generating them. Multi-host and wildcard certificates are also supported. ==== [TIP] ==== If setting up intra-cluster encryption as part of a cluster configuration, ensure that the certificates used on the cluster endpoint support server and client usage. -This is because when connecting between the Neo4j servers for clustering, each server uses its own certificate to authenticate as a client on the connection to another server. +This is because when connecting the servers for clustering, each server uses its own certificate to authenticate as a client on the connection to another server. This could be verified from within the certificate details: ---- openssl x509 -in public.crt -noout -text ---- -We should see that the X509v3 Extended Key Usage section shows both the usages listed: +You should see that the X509v3 Extended Key Usage section shows both the usages listed: ---- X509v3 Extended Key Usage: @@ -231,14 +198,14 @@ openssl x509 -in public.crt –text –noout ---- [[ssl-connectors]] -== Connectors +== Network connectors -Before enabling SSL support, you must ensure the following connector configurations to avoid errors: +Before enabling SSL support, you must ensure the following network connector configurations to avoid errors: * Set `server.https.enabled` to `true` when using HTTPS. * Set `server.bolt.tls_level` to `REQUIRED` or `OPTIONAL` when using Bolt. -For more information on configuring connectors, see xref:configuration/connectors.adoc[Configure connectors]. +For more information on configuring network connectors, see xref:configuration/connectors.adoc[Configure network connectors]. [[ssl-configuration]] == Configuration @@ -263,7 +230,7 @@ The SSL policies are configured by assigning values to parameters of the followi | `trusted_dir` | A directory populated with certificates of trusted parties. | `trusted/` | `revoked_dir` | A directory populated with certificate revocation lists (CRLs). | `revoked/` 3+^.^| *Advanced* -| `verify_hostname` footnote:[In Neo4j 2025.01, the default value is changed from `false` to `true`.] | Enabling this setting turns on client-side hostname verification. +| `verify_hostname` footnote:[In Neo4j 2025.01, the default value is changed from `false` to `true`.] | This setting turns on client-side hostname verification. After receiving the server's public certificate, the client compares the address it uses against the certificate Common Name (CN) and Subject Alternative Names (SAN) fields. @@ -293,9 +260,7 @@ Note that the existence of the directories, the certificate file, and the privat Ensure that only the Neo4j user can read the private key. ==== -Each policy needs to be explicitly enabled by setting: - -`dbms.ssl.policy..enabled=true` +Each policy needs to be explicitly enabled by setting `dbms.ssl.policy..enabled=true`. [[ssl-bolt-config]] === Configure SSL over Bolt @@ -450,10 +415,8 @@ server.bolt.tls_level=REQUIRED (default is DISABLED) + [TIP] ==== -In Neo4j version 3.5, the default value is `OPTIONAL`. -In the Neo4j 4.x versions, the default value is `DISABLED`, where only unencrypted client connections are to be accepted by this connector, and all encrypted connections will be rejected. -Use `REQUIRED` when only encrypted client connections are to be accepted by this connector, and all unencrypted connections will be rejected. -Use `OPTIONAL` where either encrypted or unencrypted client connections are accepted by this connector. +`REQUIRED` means the connector accepts only encrypted client connections and reject the unencrypted ones. +`OPTIONAL` means the connector accepts either encrypted or unencrypted client connections. ==== . Test the SSL connection to the specified host and Bolt port and view the certificate: @@ -514,15 +477,17 @@ or cypher-shell -a bolt+s://: ---- -Neo4j Browser:: -From the *Connect URL* dropdown menu, select the URI scheme you want to use (`neo4j+s` or `bolt+s`). -+ -[NOTE] -==== -URI schemes ending `+ssc` are not supported by Neo4j Browser since the browser’s OS handles certificate trust. -If it is necessary to connect to a Neo4j instance using a self-signed certificate from Neo4j Browser, first visit a web page that uses the self-signed certificate in order to prompt the browser to request that certificate trust be granted. -Once that trust has been granted, you can connect with URI schemes ending `+s`. -==== +// This should be described in the Browser guide, not here. +// =========================== +// Neo4j Browser:: +// From the *Connect URL* dropdown menu, select the URI scheme you want to use (`neo4j+s` or `bolt+s`). +// + +// [NOTE] +// ==== +// URI schemes ending `+ssc` are not supported by Neo4j Browser since the browser’s OS handles certificate trust. +// If it is necessary to connect to a Neo4j instance using a self-signed certificate from Neo4j Browser, first visit a web page that uses the self-signed certificate in order to prompt the browser to request that certificate trust be granted. +// Once that trust has been granted, you can connect with URI schemes ending `+s`. +// ==== [[ssl-https-config]] === Configure SSL over HTTPS @@ -830,7 +795,7 @@ dbms.ssl.policy.cluster.client_auth=REQUIRE [NOTE] ==== The policy must be configured on every server with the same settings. -The actual xref:security/ssl-framework.adoc#term-ssl-cryptographic-objects[cryptographic objects] installed will be mostly different since they do not share the same private keys and corresponding certificates. +The actual xref:security/ssl-framework.adoc#term-ssl-cryptographic-objects[cryptographic objects] installed will mostly be different since they do not share the same private keys and corresponding certificates. The trusted CA certificate will be shared however. ==== @@ -845,7 +810,7 @@ nmap --script ssl-enum-ciphers -p [NOTE] ==== The hostname and port have to be adjusted according to your configuration. -This can prove that TLS is in fact enabled and that only the intended cipher suites are enabled. +This can prove that TLS is enabled and that only the intended cipher suites are enabled. All servers and all applicable ports should be tested. If the intra-cluster encryption is enabled, the output should indicate the port is open and it is using TLS with the ciphers used. ==== @@ -1066,22 +1031,10 @@ For more information, see xref:configuration/command-expansion.adoc[Command expa There are cases where Neo4j Enterprise requires the use of specific ciphers for encryptions. One can set up a Neo4j configuration by specifying the list of cipher suites that will be allowed during cipher negotiation. Valid values depend on the current JRE and SSL provider. -For Oracle JRE here is the list of supported ones - https://docs.oracle.com/en/java/javase/17/docs/specs/security/standard-names.html#jsse-cipher-suite-names. +For Oracle JRE here is the list of supported ones - https://docs.oracle.com/en/java/javase/21/docs/specs/security/standard-names.html#jsse-cipher-suite-names. -[role=label--deprecated-5.26] -[IMPORTANT] -==== - -CBC (cipher block chaining) ciphers, as used in TLS v1.2 network encryption, have several security vulnerabilities that make them less secure than alternative methods. -The Internet Engineering Task Force (IETF) does not recommend using CBC-based ciphers (RFC 8447), and these ciphers were removed from the TLS standard with the development of TLS v1.3. - -Note that the use of the following CBC-based ciphers are deprecated from Neo4j 5.26: - -* TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 -* TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 -* TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 -* TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 -==== +Note that CBC (cipher block chaining)-based ciphers (RFC 8447), used in TLS v1.2 network encryption, are not supported in 2025.01. +See xref:changes-deprecations-removals.adoc[] for more information. .Bolt [source, properties] @@ -1110,7 +1063,7 @@ dbms.ssl.policy.backup.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE [[ssl-ocsp-config]] === Using OCSP stapling -From Neo4j 4.2, Neo4j supports OCSP stapling, which is implemented on the server side, and can be configured in the _neo4j.config_ file. +Neo4j supports OCSP stapling, which is implemented on the server side, and can be configured in the _neo4j.config_ file. OCSP stapling is also available for Java Bolt driver and HTTP API. On the server side in the _neo4j.conf_ file, configure the following settings: @@ -1139,8 +1092,8 @@ You can also enable additional debug logging for SSL by adding the following con server.jvm.additional=-Djavax.net.debug=ssl:handshake ---- -This will log additional information in the _neo4j.log_ file. -In some installations done using `rpm` based installs, _neo4j.log_ is not created. +This logs additional information in the _neo4j.log_ file. +In some installations, for example, RPM-based installs, _neo4j.log_ is not created. To get the contents of this, since _neo4j.log_ just contains `STDOUT` content, look for the `neo4j` service log contents using `journalctl`: [source]