9.2. SSL framework - Chapter 9. Security

9.2.1. Introduction

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 9.2.6, “The legacy SSL system”.

9.2.2. Prerequisites

Java configuration

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

Certificates

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.

9.2.3. Define SSL policies

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
`base_directory`	The base directory under which cryptographic objects are searched for by default.	This is a mandatory setting.
`private_key`	The private key used for authenticating and securing this instance.	private.key
`public_certificate`	A public certificate matching the private key signed by a Certificate Authority (CA).	public.crt
`trusted_dir`	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
`revoked_dir`	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 base_directory, and the other copy is to be placed into the trusted_dir.

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.

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

dbms.ssl.policy.example_policy.base_directory=certificates/example_policy

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, 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/trusted

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

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

Setting suffix	Description	Default
`client_auth`	Whether or not clients must be authenticated. Setting this to `REQUIRE` effectively enables mutual authentication for servers. Available values given to this setting are `NONE`, `OPTIONAL`, or `REQUIRE`.	`REQUIRE`
`ciphers`	A list of ciphers which will be allowed during cipher negotiation.	Java platform default allowed cipher suites
`tls_versions`	A list of TLS/SSL protocol versions which will be supported.	`TLSv1.2`
`allow_key_generation`	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.	`false`
`trust_all`	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.	`false`
`verify_hostname`	Enabling this setting will turn on client-side hostname verification. After the client has received the servers public certificate, it will compare the address it used against the certificate Common Name (CN) and Subject Alternative Names (SAN) fields. If the address used doesn’t match those fields, the client will disconnect.	`false`

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

9.2.4. Apply SSL policies

The different communication channels can be secured independently from each other, using the configuration settings below:

bolt.ssl_policy: The policy to be used for Bolt client traffic.
https.ssl_policy: The policy to be used for HTTPS client traffic.
causal_clustering.ssl_policy: The policy to be used for intra-cluster communication.
dbms.backup.ssl_policy: The policy to be used for encrypting backup traffic.

Example 9.4. Apply an SSL policy

Assume that we have configured the policies listed below:

One policy called client_policy for encryption of client traffic.
One policy called cluster_policy for intra-cluster encryption.
One policy called 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_policy

9.2.5. Choosing an SSL provider

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.

Follow these steps to utilize OpenSSL:

Install a suitable dependency into the plugins/ folder of Neo4j. Dependencies can be downloaded from https://netty.io/wiki/forked-tomcat-native.html.
Set 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.

9.2.6. The legacy SSL system

SSL 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=NONE

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.

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.

9.2.7. 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 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
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, and this 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.

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