SSL framework

The SSL framework provides support for securing the following Neo4j communication channels using standard SSL/TLS technology:

  • bolt (port - 7687)

  • https (port - 7473)

  • cluster (ports - 5000, 6000, 7000, and 7688)

  • backups (port - 6362)

This page describes how to set up SSL within your environment, how to view, validate, and test the certificates.

As of Neo4j 5.23, the use of port 5000 for discovery management and discovery service v1 is deprecated. Neo4j 5.23 introduces the discovery service v2, which now utilizes the port 6000. For more details, refer to Clustering → Cluster server discovery.

SSL Providers

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.

Follow these steps to use OpenSSL:

Using dynamic versions of tcnative will require 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.

The following table shows information about supported Neo4j versions.

The following table lists when the netty-tcnative dependency was updated in Neo4j.

If a Neo4j version is not listed, use the table entry for the next earliest Neo4j version listed.

For example: for Neo4j 5.15.0 the next earliest version listed in the table is 5.10, so the required netty-tcnative version is 2.0.61.Final.
Table 1. Netty-TCNative support per Neo4j version
Neo4j version tcnative version Direct link

5.23

2.0.65.Final. Only netty-tcnative-boringssl-static is required.

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.

netty-tcnative-boringssl-static-2.0.65.Final netty-tcnative-classes-2.0.65.Final

5.10

2.0.61.Final. Both netty-tcnative-boringssl-static and netty-tcnative-classes are required.

netty-tcnative-boringssl-static-2.0.61.Final netty-tcnative-classes-2.0.61.Final

5.8

2.0.60.Final. Both netty-tcnative-boringssl-static and netty-tcnative-classes are required.

netty-tcnative-boringssl-static-2.0.60.Final netty-tcnative-classes-2.0.60.Final

5.5

2.0.56.Final. Both netty-tcnative-boringssl-static and netty-tcnative-classes are required.

netty-tcnative-boringssl-static-2.0.56.Final netty-tcnative-classes-2.0.56.Final

5.1

2.0.54.Final. Both netty-tcnative-boringssl-static and netty-tcnative-classes are required.

netty-tcnative-boringssl-static-2.0.54.Final netty-tcnative-classes-2.0.54.Final

Using OpenSSL can significantly improve performance, especially for AES-GCM-cryptos, e.g. TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256.

Certificates and private keys

Certificates

The SSL configuration requires SSL certificates to be issued by a Certificate Authority (CA). All certificates must follow the X.509 standard and be saved in a PEM-encoded file.

Valid trusted certificates can be generated for free using non-profit CAs such as Let’s Encrypt.
Example public.crt file
-----BEGIN CERTIFICATE-----
MIIDojCCAoqgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMQswCQYDVQQGEwJTRTEQ
     ...
xsUBvcQuyxewlvWRS18YB51J+yu0Xg==
-----END CERTIFICATE-----

The instructions on this page assume that you have already obtained the required certificates from the CA and added them to the public.crt file. To achieve this, you should concatenate each PEM-encoded certificate, starting from the leaf certificate and moving up the chain toward the root.

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. Multi-host and wildcard certificates are also supported.

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 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:

X509v3 Extended Key Usage:
    TLS Web Server Authentication, TLS Web Client Authentication

Transformations

Neo4j requires all SSL certificates to be in the PEM format. If your certificate is in the binary DER format, you must transform it into PEM format.

Transform DER format certificate to PEM format
openssl x509 -in cert.der -inform der -outform pem -out cert.crt

Private keys

Private keys must be in the standard format PKCS #8 and saved as a PEM-encoded file.

Example private.key file
-----BEGIN PRIVATE KEY-----
MIICdQIBADANBgkqhkiG9w0BAQEFAASCAl8wggJbAgEAAoGBAN5D0I4bgdQK4In6
     ...
oaMe91ZPQ1JI
-----END PRIVATE KEY-----

Private keys can also be encrypted with a passphrase according to the PKCS #5 standard.

Example private.key file with passphrase encryption
-----BEGIN ENCRYPTED PRIVATE KEY-----
MIICojAcBgoqhkiG9w0BDAEEMA4ECL3eSAoRlJ18AgIIAASCAoCj7WDyjsgcawdv
     ...
lYeSjVah
-----END ENCRYPTED PRIVATE KEY-----

Transformation

If the private key is encoded with the old PKCS #1 format, the file will typically start with the line:

-----BEGIN RSA PRIVATE KEY-----

You can convert it to PKCS #8 format with the following command:

Convert a PKCS #1 key to a PKCS #8 key
openssl pkcs8 -topk8 -in pkcs1.key -out pkcs8.key

An unencrypted private key could be PKCS #1 or PKCS #8. It can be encrypted with the following command:

Convert an unencrypted key to an encrypted PKCS #8 key using 256bit AES in cipher-block-chaining (CBC) mode
openssl pkcs8 -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA512 -in pkcs1or8.key -out pkcs8.encrypted.key
Supported encryption arguments to openssl are:

  • -v2 aes-128-cbc -v2prf hmacWithSHA1

  • -v2 aes-128-cbc -v2prf hmacWithSHA224

  • -v2 aes-128-cbc -v2prf hmacWithSHA256

  • -v2 aes-128-cbc -v2prf hmacWithSHA384

  • -v2 aes-128-cbc -v2prf hmacWithSHA512

  • -v2 aes-256-cbc -v2prf hmacWithSHA224

  • -v2 aes-256-cbc -v2prf hmacWithSHA256

  • -v2 aes-256-cbc -v2prf hmacWithSHA384

  • -v2 aes-256-cbc -v2prf hmacWithSHA512

Versions before Neo4j 5.0 allow keys to be stored with the old PKCS #1 standard. You can identify them by the line -----BEGIN RSA PRIVATE KEY----- at the beginning of the file. While Neo4j 5.0 can load and use those keys, they are considered deprecated and will be removed in a future version.

Validate the key and the certificate

If you need, you can validate the key file and the certificate as follows:

Validate the key
openssl rsa -in private.key -check
Validate certificate in the PEM format
openssl x509 -in public.crt –text –noout

Connectors

Before enabling SSL support, you must ensure the following 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 Configure connectors.

Configuration

The SSL policies are configured by assigning values to parameters of the following format:

dbms.ssl.policy.<scope>.<setting-suffix>

  • scope is the name of the communication channel, such as bolt, https, cluster, and backup.

  • setting-suffix can be any of the following:

    Setting suffix Description Default value

    Basic

    enabled

    Setting this to true enables this policy.

    false

    base_directory

    The base directory under which cryptographic objects are searched for by default.

    certificates/<scope>

    private_key

    The private key used for authenticating and securing this instance.

    private.key

    private_key_password

    The passphrase to decode the private key. Only applicable for encrypted private keys.

    public_certificate

    A public certificate matching the private key signed by a CA.

    public.crt

    trusted_dir

    A directory populated with certificates of trusted parties.

    trusted/

    revoked_dir

    A directory populated with certificate revocation lists (CRLs).

    revoked/

    Advanced

    verify_hostname

    Enabling 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. 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, SSL provider, and TLS version. For Ciphers supported by the Oracle JRE, see the 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. 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 Supported from Neo4j 5.24

    client_auth

    Whether or not clients must be authenticated. Setting this to REQUIRE enables mutual authentication for servers. Other possible values are NONE and OPTIONAL.

    OPTIONAL for bolt and https;
    REQUIRE for cluster and backup.

    trust_all

    Setting this to true results in all clients and servers to be trusted and the content of the trusted_dir directory to be ignored. Use this only as a mean of debugging, since it does not offer security.

    false

For security reasons, Neo4j does not automatically create any of these directories. Therefore, the creation of an SSL policy requires the appropriate file system structure to be set up manually. Note that the existence of the directories, the certificate file, and the private key are mandatory. Ensure that only the Neo4j user can read the private key.

Each policy needs to be explicitly enabled by setting:

dbms.ssl.policy.<scope>.enabled=true

Configure SSL over Bolt

Bolt protocol is based on the PackStream serialization and supports the Cypher type system, protocol versioning, authentication, and TLS via certificates. For Neo4j clusters, Bolt provides smart client routing with load balancing and failover. When server side routing is enabled, an additional Bolt port is open on 7688. It can be used only within the cluster and with all the same settings as the external Bolt port.

Bolt connector is used by Cypher Shell, Neo4j Browser, and by the officially supported language drivers. Bolt connector is enabled by default but its encryption is disabled. To enable the encryption over Bolt, create the folder structure and place the key file and the certificates under those. Then, you need to configure the SSL Bolt policies in the neo4j.conf file.

  1. Enable the Bolt connector to enable SSL over Bolt:

    server.bolt.enabled=true (default is true)

  2. Set up the bolt folder under certificates.

    1. Create a directory bolt under <NEO4J_HOME>/certificates folder:

      mkdir certificates/bolt

    2. Create a directory trusted and revoked under <NEO4J_HOME>/certificates/bolt folder:

      mkdir certificates/bolt/trusted
mkdir certificates/bolt/revoked

  3. Place the certificates private.key and the public.crt files under <NEO4J_HOME>/certificates/bolt folder:

    cp /path/to/certs/private.key certificates/bolt
cp /path/to/certs/public.crt certificates/bolt

  4. Place the public.crt file under the <NEO4J_HOME>/certificates/bolt/trusted folder.

    cp /path/to/certs/public.crt certificates/bolt/trusted

  5. (Optional) If a particular certificate is revoked, then place it under <NEO4J_HOME>/certificates/bolt/revoked folder.

    cp /path/to/certs/public.crt certificates/bolt/revoked

    The folder structure should look like this with the right file permissions and the groups and ownerships:

    Path Directory/File Owner Group Permission Unix/Linux View

    /data/neo4j/certificates/bolt

    Directory

    neo4j

    neo4j

    0755

    drwxr-xr-x

    /data/neo4j/certificates/bolt/public.crt

    File

    neo4j

    neo4j

    0644

    -rw-r—​r--

    /data/neo4j/certificates/bolt/private.key

    File

    neo4j

    neo4j

    0400

    -r--------

    /data/neo4j/certificates/bolt/trusted

    Directory

    neo4j

    neo4j

    0755

    drwxr-xr-x

    /data/neo4j/certificates/bolt/trusted/public.crt

    File

    neo4j

    neo4j

    0644

    -rw-r—​r--

    /data/neo4j/certificates/bolt/revoked

    Directory

    neo4j

    neo4j

    0755

    drwxr-xr-x

    The owner/group should be configured to the user/group that will be running the neo4j service. Default user/group is neo4j/neo4j.

  6. Set the Bolt SSL configuration in neo4j.conf.

    1. Set the SSL Bolt policy to true:

      dbms.ssl.policy.bolt.enabled=true

    2. Set the appropriate certificates path and the right key and cert files:

      dbms.ssl.policy.bolt.base_directory=certificates/bolt
dbms.ssl.policy.bolt.private_key=private.key
dbms.ssl.policy.bolt.public_certificate=public.crt

      If the certificate is a different path outside of NEO4J_HOME, then set the absolute path for the certificates directory.

    3. Set the Bolt client authentication to NONE to disable the mutual authentication:

      dbms.ssl.policy.bolt.client_auth=NONE

    4. Set the Bolt TLS level to allow the connector to accept encrypted and/or unencrypted connections:

      server.bolt.tls_level=REQUIRED (default is DISABLED)

      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.

  7. Test the SSL connection to the specified host and Bolt port and view the certificate:

    openssl s_client -connect my_domain.com:7687

Connect with SSL over Bolt

Each of the neo4j and bolt URI schemes permit variants that contain extra encryption and trust information. The +s variants enable encryption with a full certificate check. The +ssc variants enable encryption with no certificate check. This latter variant is designed specifically for use with self-signed certificates.

URI Scheme Routing Description

neo4j

Yes

Unsecured

neo4j+s

Yes

Secured with full certificate

neo4j+ssc

Yes

Secured with self-signed certificate

bolt

No

Unsecured

bolt+s

No

Secured with full certificate

bolt+ssc

No

Secured with self-signed certificate

Once SSL is enabled over Bolt, you can connect to the Neo4j DBMS using neo4j+s or bolt+s:

Cypher Shell
cypher-shell -a neo4j+s://<Server DNS or IP>:<Bolt port>

or

cypher-shell -a bolt+s://<Server DNS or IP>:<Bolt port>
Neo4j Browser

From the Connect URL dropdown menu, select the URI scheme you want to use (neo4j+s or bolt+s).

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.

Configure SSL over HTTPS

HTTP(s) is used by the Neo4j Browser and the HTTP API. HTTPS (secure HTTP) is set to encrypt network communications. To enable the encryption over HTTPS, create the folder structure and place the key file and the certificates under those. Then, you need to configure the SSL HTTPS policies in the neo4j.conf file and disable the HTTP connector.

The HTTPS configuration requires that Bolt is also set. Refer to Configure SSL over Bolt for more instructions.

  1. Enable the HTTPS connector to enable SSL over HTTPS:

    server.https.enabled=true (default is false)

  2. Set up the https folder under certificates.

    1. Create a directory https under <NEO4J_HOME>/certificates folder:

      mkdir certificates/https

    2. Create a directory trusted and revoked under <NEO4J_HOME>/certificates/https folder:

      mkdir certificates/https/trusted
mkdir certificates/https/revoked

  3. Place the certificates private.key and the public.crt files under <NEO4J_HOME>/certificates/https folder:

    cp /path/to/certs/private.key certificates/https
cp /path/to/certs/public.crt certificates/https

  4. Place the public.crt file under the <NEO4J_HOME>/certificates/https/trusted folder.

    cp /path/to/certs/public.crt certificates/https/trusted

  5. (Optional) If a particular certificate is revoked, then place it under <NEO4J_HOME>/certificates/https/revoked folder.

    cp /path/to/certs/public.crt certificates/https/revoked

    The folder structure should look like this with the right file permissions and the groups and ownerships:

    Path Directory/File Owner Group Permission Unix/Linux View

    /data/neo4j/certificates/https

    Directory

    neo4j

    neo4j

    0755

    drwxr-xr-x

    /data/neo4j/certificates/https/public.crt

    File

    neo4j

    neo4j

    0644

    -rw-r—​r--

    /data/neo4j/certificates/https/private.key

    File

    neo4j

    neo4j

    0400

    -r--------

    /data/neo4j/certificates/https/trusted

    Directory

    neo4j

    neo4j

    0755

    drwxr-xr-x

    /data/neo4j/certificates/https/trusted/public.crt

    File

    neo4j

    neo4j

    0644

    -rw-r—​r--

    /data/neo4j/certificates/https/revoked

    Directory

    neo4j

    neo4j

    0755

    drwxr-xr-x

    The owner/group should be configured to the user/group that will be running the neo4j service. Default user/group is neo4j/neo4j.

  6. Set the HTTPS SSL configuration in neo4j.conf.

    1. Set the SSL HTTPS policy to true:

      dbms.ssl.policy.https.enabled=true

    2. Set the appropriate certificates path and the right key and cert files:

      dbms.ssl.policy.https.base_directory=certificates/https
dbms.ssl.policy.https.private_key=private.key
dbms.ssl.policy.https.public_certificate=public.crt

      If the certificate is a different path outside of NEO4J_HOME, then set the absolute path for the certificates directory.

    3. Set the HTTPS client authentication to NONE to disable the mutual authentication:

      dbms.ssl.policy.https.client_auth=NONE

    4. Disable HTTP connector:

      server.http.enabled=false

  7. Test the SSL connection to the specified host and HTTPS port and view the certificate:

    openssl s_client -connect my_domain.com:7473

Configure SSL for intra-cluster communications

Intra-cluster encryption is the security solution for the cluster communication. The Neo4j cluster communicates on 4 ports:

  • 5000 - Discovery management

  • 6000 - Transactions

  • 7000 - Raft communications

  • 7688 - Server side routing

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.

  1. Set up the cluster folder under certificates.

    1. Create a directory cluster under_<NEO4J_HOME>/certificates_ folder:

      mkdir certificates/cluster

    2. Create a directory trusted and revoked under <NEO4J_HOME>/certificates/cluster folder:

      mkdir certificates/cluster/trusted
mkdir certificates/cluster/revoked

  2. Place the certificates private.key and the public.crt files under <NEO4J_HOME>/certificates/cluster folder:

    cp /path/to/certs/private.key certificates/cluster
cp /path/to/certs/public.crt certificates/cluster

  3. Place the public.crt file under the <NEO4J_HOME>/certificates/cluster/trusted folder.

    cp /path/to/certs/public.crt certificates/cluster/trusted

    If each server has a certificate of its own, signed by a CA, then each server’s public certificate has to be put in the trusted folder on each instance of the cluster. Thus, the servers are able to establish trust relationships with each other.

  4. (Optional) If a particular certificate is revoked, then place it under <NEO4J_HOME>/certificates/cluster/revoked folder.

    cp /path/to/certs/public.crt certificates/cluster/revoked

    The folder structure should look like this with the right file permissions and the groups and ownerships:

    Path Directory/File Owner Group Permission Unix/Linux View

    /data/neo4j/certificates/cluster

    Directory

    neo4j

    neo4j

    0755

    drwxr-xr-x

    /data/neo4j/certificates/cluster/public.crt

    File

    neo4j

    neo4j

    0644

    -rw-r—​r--

    /data/neo4j/certificates/cluster/private.key

    File

    neo4j

    neo4j

    0400

    -r--------

    /data/neo4j/certificates/cluster/trusted

    Directory

    neo4j

    neo4j

    0755

    drwxr-xr-x

    /data/neo4j/certificates/cluster/trusted/public.crt

    File

    neo4j

    neo4j

    0644

    -rw-r—​r--

    /data/neo4j/certificates/cluster/revoked

    Directory

    neo4j

    neo4j

    0755

    drwxr-xr-x

    The owner/group should be configured to the user/group that will be running the neo4j service. Default user/group is neo4j/neo4j.

  5. Set the cluster SSL configuration in neo4j.conf.

    1. Set the cluster SSL policy to true:

      dbms.ssl.policy.cluster.enabled=true

    2. Set the appropriate certificates path and the right key and cert files:

      dbms.ssl.policy.cluster.base_directory=certificates/cluster
dbms.ssl.policy.cluster.private_key=private.key
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.

    3. Set the cluster client authentication to REQUIRE to enable the mutual authentication, which means that both ends of a channel have to authenticate:

      dbms.ssl.policy.cluster.client_auth=REQUIRE

      The policy must be configured on every server with the same settings. The actual cryptographic objects installed will be mostly different since they do not share the same private keys and corresponding certificates. The trusted CA certificate will be shared however.

    4. Verify that the intra-cluster communication is encrypted. You may use an external tooling, such as Nmap (https://nmap.org/download.html):

      nmap --script ssl-enum-ciphers -p <port> <hostname>

      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. 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.

For more details on securing the comunication between the cluster servers, see Intra-cluster encryption.

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.

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.

  1. Set up the backup folder under certificates.

    1. Create a directory backup under <NEO4J_HOME>/certificates folder:

      mkdir certificates/backup

    2. Create a directory trusted and revoked under <NEO4J_HOME>/certificates/backup folder:

      mkdir certificates/backup/trusted
mkdir certificates/backup/revoked

  2. Place the certificates private.key and the public.crt files under <NEO4J_HOME>/certificates/backup folder:

    cp /path/to/certs/private.key certificates/backup
cp /path/to/certs/public.crt certificates/backup

  3. Place the public.crt file under the <NEO4J_HOME>/certificates/backup/trusted folder.

    cp /path/to/certs/public.crt certificates/backup/trusted

  4. (Optional) If a particular certificate is revoked, then place it under <NEO4J_HOME>/certificates/backup/revoked folder.

    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:

    Path Directory/File Owner Group Permission Unix/Linux View

    /data/neo4j/certificates/backup

    Directory

    neo4j

    neo4j

    0755

    drwxr-xr-x

    /data/neo4j/certificates/backup/public.crt

    File

    neo4j

    neo4j

    0644

    -rw-r—​r--

    /data/neo4j/certificates/backup/private.key

    File

    neo4j

    neo4j

    0400

    -r--------

    /data/neo4j/certificates/backup/trusted

    Directory

    neo4j

    neo4j

    0755

    drwxr-xr-x

    /data/neo4j/certificates/backup/trusted/public.crt

    File

    neo4j

    neo4j

    0644

    -rw-r—​r--

    /data/neo4j/certificates/backup/revoked

    Directory

    neo4j

    neo4j

    0755

    drwxr-xr-x

    The owner/group should be configured to the user/group that will be running the neo4j service. Default user/group is neo4j/neo4j.

  5. Set the backup SSL configuration in neo4j.conf.

    1. Set the backup SSL policy to true:

      dbms.ssl.policy.backup.enabled=true

    2. Set the appropriate certificates path and the right key and cert files:

      dbms.ssl.policy.backup.base_directory=certificates/backup
dbms.ssl.policy.backup.private_key=private.key
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.

    3. Set the backup client authentication to REQUIRE to enable the mutual authentication, which means that both ends of a channel have to authenticate:

      dbms.ssl.policy.backup.client_auth=REQUIRE

Other configurations for SSL

Using encrypted private key

To use an encrypted private key, configure the following settings. The private key password must be clear text format without any quotes.

Bolt
dbms.ssl.policy.bolt.private_key_password=<clear text password>
HTTPS
dbms.ssl.policy.https.private_key_password=<password>
Intra-cluster encryption
dbms.ssl.policy.cluster.private_key_password=<password>
Backup
dbms.ssl.policy.backup.private_key_password=<password>

If hardcoding of clear text private key password is not feasible due to security constraints, it can be set up to use dynamic password pickup by following these steps:

  1. Create a file containing the cleartext password for the private key password and encrypt it with the certificate (assuming private key for cert has password set and certificate is in pwd):

    echo "password123" > passwordfile

base64 -w 0 certificate.crt | openssl aes-256-cbc -a -salt -in passwordfile -out password.enc -pass stdin

    Delete the password file and set file permissions for password.enc to 400 (e.g. chmod 400 password.enc).

  2. Verify that encrypted password can be read from password.enc:

    base64 -w 0 certificate.crt | openssl aes-256-cbc -a -d -in password.enc -pass stdin

  3. Set the neo4j.conf dbms.ssl.policy.<type>.private_key_password to be able to read out encrypted password. To adjust paths to cert and encrypted password file, use full paths:

    dbms.ssl.policy.bolt.private_key_password=$(base64 -w 0 certificate.crt | openssl aes-256-cbc -a -d -in password.enc -pass stdin)

Using a dynamic command requires Neo4j to be started with the --expand-commands option. For more information, see Command expansion.

Using specific cipher

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.

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
Bolt
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
HTTPS
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
Intra-cluster encryption
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
Backup
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

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. 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:

  1. Set the SSL Bolt policy to true:

    dbms.ssl.policy.bolt.enabled=true

  2. Enable the OCSP stapling for Bolt:

    server.bolt.ocsp_stapling_enabled=true (default = false)

SSL logs

All information related to SSL can be found in the debug.log file. You can also enable additional debug logging for SSL by adding the following configuration to the neo4j.conf file and restarting Neo4j.

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. To get the contents of this, since neo4j.log just contains STDOUT content, look for the neo4j service log contents using journalctl:

neo4j@ubuntu:/var/log/neo4j$ journalctl -u neo4j -b > neo4j.log
neo4j@ubuntu:/var/log/neo4j$ vi neo4j.log

Beware that the SSL debug option logs a new statement every time a client connects over SSL, which can make neo4j.log grow large reasonably quickly. To avoid that scenario, make sure this setting is only enabled for a short term duration.

Terminology

The following terms are relevant to SSL support within Neo4j:

Certificate Authority (CA)

A trusted entity that issues electronic documents that can verify the identity of a digital entity. The term commonly refers to globally recognized CAs, but can also include internal CAs that are trusted inside of an organization. The electronic documents are digital certificates. They are an essential part of secure communication, and play an important part in the Public Key Infrastructure.

Certificate Revocation List (CRL)

In the event of a certificate being compromised, that certificate can be revoked. This is done by means of a list (located in one or several files) spelling out which certificates are revoked. The CRL is always issued by the CA which issues the corresponding certificates.

cipher

An algorithm for performing encryption or decryption. In the most general implementation of encrypted communications, Neo4j makes implicit use of ciphers that are included as part of the Java platform. The configuration of the SSL framework also allows for the explicit declaration of allowed ciphers.

communication channel

A means for communicating with the Neo4j database. Available channels are:

  • Bolt client traffic

  • HTTPS client traffic

  • intra-cluster communication

  • backup traffic

cryptographic objects

A term denoting the artifacts private keys, certificates and CRLs.

configuration parameters

These are the parameters defined for a certain ssl policy in neo4j.conf.

certificate

SSL certificates are issued by a trusted certificate authority (CA). The public key can be obtained and used by anyone to encrypt messages intended for a particular recipient. The certificate is commonly stored in a file named <file name>.crt. This is also referred to as the public key.

SAN

SAN is an acronym for Subject Alternative Names. It is an extension to certificates that one can include optionally. When presented with a certificate that includes SAN entries, it is recommended that the address of the host is checked against this field. Verifying that the hostname matches the certificate SAN helps prevent attacks where a rogue machine has access to a valid key pair.

SSL

SSL is an acronym for Secure Sockets Layer, and is the predecessor of TLS. It is common to refer to SSL/TLS as just SSL. However, the modern and secure version is TLS, which is also the default in Neo4j.

SSL policy

An SSL policy in Neo4j consists of a a digital certificate and a set of configuration parameters defined in neo4j.conf.

PKCS #1

PKCS #1 is the first family of standards called Public-Key Cryptography Standards (PKCS). It provides the basic definitions and recommendations for implementing the RSA algorithm for public-key cryptography. It defines the mathematical properties of public and private keys, primitive operations for encryption and signatures, secure cryptographic schemes, and related ASN.1 syntax representations.

PKCS #5

PKCS #5 contains recommendations for implementating password-based cryptography, covering key derivation functions, encryption schemes, message authentication schemes, and ASN.1 syntax, identifying the techniques.

PKCS #8

PKCS #8 is a standard syntax for storing private key information. The PKCS #8 private key may be encrypted with a passphrase using the PKCS #5 standards, which support multiple ciphers. The main difference from PKCS #1 is that it allows more algorithms than RSA and supports stronger encryption of the private key.

private key

The private key ensures that encrypted messages can be deciphered only by the intended recipient. The private key is commonly stored in a file named <file name>.key. It is important to protect the private key to ensure the integrity of encrypted communication.

Public Key Infrastructure (PKI)

A set of roles, policies, and procedures needed to create, manage, distribute, use, store, and revoke digital certificates and manage public-key encryption.

public key

The public key can be obtained and used by anyone to encrypt messages intended for a particular recipient. This is also referred to as the certificate.

TLS protocol

The cryptographic protocol that provides communications security over a computer network. The Transport Layer Security (TLS) protocol and its predecessor, the Secure Sockets Layer (SSL) protocol, are both frequently referred to as "SSL".

TLS version

A version of the TLS protocol.

X.509

X.509 is an International Telecommunication Union (ITU) standard defining the format of public key certificates.