7.3. Unified SSL framework

This section describes SSL/TLS integration for securing communication channels in Neo4j.

7.3.1. About SSL/TLS in general

Neo4j supports the securing of communication channels using standard SSL/TLS technology. It is common to refer to SSL/TLS as simply SSL for reasons of brevity and that is the approach used here and in configuration. The modern and secure versions of the standard are however all TLS and this is also the default in Neo4j.

The security provided through SSL can be varied through configuration to provide various levels of integrity, confidentiality and authentication. Various ciphers and algorithms provide the basis for key exchanges, encryption and message digests whereas a public/private key infrastructure provides the basis for authentication.

7.3.2. 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.
An algorithm for performing encryption or decryption. In the most general implementation of encryption of Neo4j communications, we make 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
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.
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.
SSL policy
An SSL policy in Neo4j consists of a digital certificate and a set of configuration parameters defined in neo4j.conf.
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 version
A version of the TLS protocol.
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".

7.3.3. Communication channels

The Neo4j platform has the following communication channels or groups of channels:

  • Bolt client traffic
  • HTTPS client traffic
  • Intra-cluster communication and HTTPS client traffic

These can be secured independently from each other, according to required security practices.

7.3.4. Policy definition

SSL support in Neo4j is enabled by creating an SSL policy, which consists of an SSL certificate together with a set of parameters. These policies can then be applied to the various communication channels.

The policies are configured in neo4j.conf under a group-setting as dbms.ssl.policy.<policy-name>.<setting-suffix> where the policy-name can be chosen freely, and valid values for setting-suffix are described below. A policy is configured using the following parameters:

Setting suffix Description Default value


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

No default. This value must be provided to define a new policy.


The private key used for authenticating and securing this instance.



A public certificate matching the private key signed by a Certificate Authority (CA).



A directory populated with certificates of trusted parties.



A directory populated with certificate revocation lists (CRLs).


The only mandatory setting is the base directory defined by dbms.ssl.policy.<policy-name>.base_directory. By defining the base directory, we implicitly tell Neo4j to define a policy with the name <policy-name>. If no other settings for this policy have been defined, Neo4j will by default be looking for the private key and the certificate file inside the base directory, as well as two subdirectories called trusted and revoked. If other paths are preferred, all the default values can be overridden. For reasons of security Neo4j will not attempt to automatically create any of these directories. The creation of an SSL policy therefore requires the appropriate file system structure to be set up manually. Note that the existence of the directories is mandatory, as well as the presence of the certificate file and the private key. Ensure correct permissions are set on the private key, such that only the Neo4j user can read it.

Additionally, the following parameters can be configured for a policy:

Setting suffix Description Default


Whether or not clients must be authenticated. Setting this to REQUIRE effectively enables mutual authentication for servers. Available values to given to this setting are NONE, OPTIONAL, or REQUIRE.



A list of ciphers which will be allowed during cipher negotiation.

Java platform default allowed cipher suites


A list of TLS/SSL protocol versions which will be supported.



It is strongly recommended to keep this parameter at its default value of false. If set to true, it will enable the auto-generation of a .key/.crt file pair on startup. Additionally, the required directory structure will be generated automatically.



It is strongly recommended to keep this parameter at its default value of false. Setting it to true means "trust anyone" and essentially disables authentication.


The combination of Neo4j and the Java platform will provide strong cipher suites and protocols.

Example 7.24. Define a policy

In this example we will define and create configuration for a policy called example_policy. As the simplest configuration possible, we define the base directory for this policy in neo4j.conf:


Then create the mandatory directories:

$neo4j-home> mkdir certificates/example_policy
$neo4j-home> mkdir certificates/example_policy/trusted
$neo4j-home> mkdir certificates/example_policy/revoked

Finally place the files private.key and public.crt into the base directory. We will have the following listing:

$neo4j-home> ls certificates/example_policy
-r-------- ... private.key
-rw-r--r-- ... public.crt
drwxr-xr-x ... revoked
drwxr-xr-x ... trusted

7.3.5. Applying SSL policies

A communication channel or group of channels gets an SSL policy applied by binding it to an SSL policy name. Causal Clustering, Bolt and HTTPS can be configured with SSL policies, using the configuration settings causal_clustering.ssl_policy, bolt.ssl_policy and https.ssl_policy.

Example 7.25. Apply an SSL policy

The following example will configure a causal cluster to use the policy named example_policy:


7.3.6. Certificate formats

All certificates need to be in the PEM format, and they can be combined into one file. The private key is also required to be in the PEM format. Multi-host and wildcard certificates are supported. Such certificates are required if Neo4j has been configured with multiple connectors that bind to different interfaces.

7.3.7. Legacy SSL system

In previous versions of Neo4j, SSL support for Bolt and HTTPS was provided using a different system, which we here call the legacy SSL system. It is expected that this legacy system is to be deprecated at some point in the future, so it is recommended to use the standard SSL configuration instead. The legacy policy is available in the SSL framework under the special legacy policy name, but it does not allow the full flexibility of the framework.

In order to configure the legacy SSL system with Neo4j, you must have your private key and certificate in files named neo4j.key and neo4j.cert, respectively. Note that the key should be unencrypted. Place the files into the assigned directory. The default is a directory named certificates, which is located in the neo4j-home directory. The directory can also be configured explicitly using dbms.directories.certificates in neo4j.conf.

If started without any certificates installed, the Neo4j process will automatically generate a self-signed SSL certificate and a private key in the default directory. Using auto-generation of self-signed SSL certificates will not work if Neo4j has been configured with multiple connectors that bind to different IP addresses. If you need to use multiple IP addresses, please configure certificates manually and use multi-host or wildcard certificates instead.

The Legacy SSL system is essentially equivalent to the following SSL policy definition:



The HTTPS and Bolt servers do not support client authentication (a.k.a. mutual authentication). As a result, client_auth has to be turned off explicitly by having client_auth=NONE while migrating HTTPS and Bolt servers to the new ssl policy. When client authentication is disabled, values assigned to trusted_dir, revoked_dir or trust_all will be ignored as they are settings used in client authentication.

Although not mentioned above, the tls_versions and ciphers settings are supported in HTTPS and Bolt servers. This is because in the legacy policy, the default values of these two settings are the same as the default values for SSL policies.