This section describes SSL/TLS integration for securing communication channels in Neo4j.
Neo4j supports the securing of communication channels using standard SSL/TLS technology.
This section describes the following:
SSL support is enabled by creating an SSL policy, which consists of an SSL certificate together with a set of parameters. The policy is then applied to the communication channel(s) that you wish to secure. The process is described in the following sections.
|
If Neo4j is started without any SSL policy definitions, it will default to the legacy SSL system. Additionally, if no certificates are installed, the Neo4j process will automatically generate a self-signed SSL certificate and a private key in a default directory. For details, refer to Section 7.3.5, “The legacy SSL system”. |
The Neo4j SSL framework uses strong cryptography which may need to be specifically enabled on your Java platform. For example, see: http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html
The instructions in this section assume that you have already acquired the required certificates.
All certificates must 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.
SSL policies are configured by assigning values to parameters of the following format:
dbms.ssl.policy.<policy-name>.<setting-suffix>
The policy-name is the name of the policy that you wish to define.
The basic valid values for setting-suffix are described below:
| Setting suffix | Description | Default value |
|---|---|---|
|
|
The base directory under which cryptographic objects are searched for by default. |
This is a mandatory setting. |
|
|
The private key used for authenticating and securing this instance. |
private.key |
|
|
A public certificate matching the private key signed by a Certificate Authority (CA). |
public.crt |
|
|
A directory populated with certificates of trusted parties. If configured, this must be an absolute path. At the very minimum, this must contain this node’s public certificate (public.crt). |
trusted |
|
|
A directory populated with certificate revocation lists (CRLs). If configured, this must be an absolute path. |
revoked |
|
The public certificate must be duplicated.
One copy is to be placed into the |
The only mandatory setting is the base directory defined by dbms.ssl.policy.<policy-name>.base_directory.
By defining the base directory, we 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 security reasons, 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.
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:
dbms.ssl.policy.example_policy.base_directory=certificates/example_policyThen create the mandatory directories:
$neo4j-home> mkdir certificates/example_policy
$neo4j-home> mkdir certificates/example_policy/trusted
$neo4j-home> mkdir certificates/example_policy/revokedFinally, place the files private.key and public.crt into the base directory, and place another copy of the public.crt into the trusted directory:
$neo4j-home> cp /path/to/certs/private.key certificates/example_policy
$neo4j-home> cp /path/to/certs/public.crt certificates/example_policy
$neo4j-home> cp /path/to/certs/public.crt certificates/example_policy/trustedWe will have the following listings:
$neo4j-home> ls certificates/example_policy
-r-------- ... private.key
-rw-r--r-- ... public.crt
drwxr-xr-x ... revoked
drwxr-xr-x ... trusted
$neo4j-home> ls certificates/example_policy/trusted
-rw-r--r-- ... public.crtAdditionally, the following parameters can be configured for a policy:
| Setting suffix | Description | Default |
|---|---|---|
|
|
Whether or not clients must be authenticated.
Setting this to |
|
|
|
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 |
|
|
|
It is strongly recommended to keep this parameter at its default value of |
|
The combination of Neo4j and the Java platform will provide strong cipher suites and protocols.
The different communication channels can be secured independently from each other, using the configuration settings below:
bolt.ssl_policyhttps.ssl_policycausal_clustering.ssl_policydbms.backup.ssl_policyAssume that we have configured the policies listed below:
client_policy for encryption of client traffic.
cluster_policy for intra-cluster encryption.
backup_policy for encrypting backup traffic.
The following example will configure the encryption accordingly:
bolt.ssl_policy=client_policy
https.ssl_policy=client_policy
causal_clustering.ssl_policy=cluster_policy
dbms.backup.ssl_policy=backup_policySSL support can also be provided for Bolt and HTTPS using the legacy SSL system. The legacy system is expected to be deprecated at some point in the future, so it is recommended to use the standard SSL configuration instead.
In order to configure the legacy SSL system with Neo4j, the private key and certificate files must be 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 policy is available in the SSL framework under the special legacy policy name, but it does not allow the full flexibility of the framework.
It is essentially equivalent to the following SSL policy definition:
bolt.ssl_policy=legacy
https.ssl_policy=legacy
dbms.ssl.policy.legacy.base_directory=certificates
dbms.ssl.policy.legacy.private_key=neo4j.key
dbms.ssl.policy.legacy.public_certificate=neo4j.cert
dbms.ssl.policy.legacy.allow_key_generation=true
dbms.ssl.policy.legacy.client_auth=NONEThe 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.
The tls_versions and ciphers settings are supported in HTTPS and Bolt servers.
The legacy policy defaults to the TLS versions and cipher suites supported by the Java platform.
The following terms are relevant to SSL support within Neo4j:
A means for communicating with the Neo4j database. Available channels are: