SSL framework

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:

1. Introduction

The SSL support is enabled per communication channel and requires SSL certificates encoded in the PEM format. The process is described in the following sections.

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

3. Configuration

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

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

The scope is the name of the communication channel, and must be one of bolt, https, cluster, backup or fabric.

Each policy needs to be explicitly enabled by setting:

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

3.1. Settings

The valid values for setting-suffix are described below.

Setting suffix Description Default value

Basic

enabled

Setting this to true will enable 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 Certificate Authority (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 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

ciphers

A comma-separated list of ciphers suits that will be allowed during cipher negotiation. Valid values depend on the current JRE and SSL provider, see note below for examples.

Java platform default allowed cipher suites

tls_versions

A comma-separated list of allowed TLS versions.

TLSv1.2

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.

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

trust_all

Setting this to true will result in all clients and servers being trusted. The content of the trusted_dir directory will be ignored. Use of this is discouraged, since it will not offer security. It is provided as a mean of debugging.

false

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 1. Enable Bolt SSL

In this example we will configure Bolt to use SSL/TLS. As the simplest configuration possible, we will just enable it in neo4j.conf and rely on the default values:

dbms.ssl.policy.bolt.enabled=true

Then create the mandatory directories:

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

Finally, place the files private.key and public.crt into the base directory:

$neo4j-home> cp /path/to/certs/private.key certificates/bolt
$neo4j-home> cp /path/to/certs/public.crt certificates/bolt

The base directory should now show the following listings:

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

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

  1. Install a suitable dependency into the plugins/ folder of Neo4j. Dependencies can be downloaded from https://netty.io/wiki/forked-tomcat-native.html.

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

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