You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
:description: How to configure Neo4j to use FIPS compatible SSL encryption.
2
+
[role=enterprise-edition]
3
+
[[ssl-fips-compatibility]]
4
+
= Configuring SSL for FIPS 140-2 compatibility
5
+
6
+
Federal Information Processing Standards (FIPS) is ...
7
+
8
+
https://csrc.nist.gov/pubs/fips/140-2/upd2/final
9
+
10
+
This is a guide to help configure Neo4j to use SSL encryption in a FIPS compatible way.
11
+
It is supplementary to xref:security/ssl-framework.adoc[] as many of the configuration processes and requirements are the same.
12
+
13
+
. Enable a FIPS certified cryptographic provider
14
+
. Generate SSL certificate and private key xref:security/ssl-framework.adoc#ssl-certificates[instructions]
15
+
. Configure Neo4j to use SSL for all network connections xref:security/ssl-framework.adoc#ssl-configuration[]
16
+
. Setup a non-native authentication provider, for example LDAP or SSO. xref:authentication-authorization/index.adoc[]
17
+
. verify?
18
+
. security checklist? (cross ref)
19
+
20
+
21
+
== Prerequisites
22
+
TODO
23
+
24
+
* FIPS compatible operating system and hardware. Only Linux operating systems are supported for Neo4j FIPS compatibility at this time.
25
+
* Neo4j Enterprise 5.23.0 or later.
26
+
27
+
== Enable FIPS SSL Provider (Docker)
28
+
29
+
The Neo4j RedHat UBI9 Docker image comes with the SSL provider and dependencies pre-installed, but it is not enabled by default.
30
+
31
+
[NOTE]
32
+
====
33
+
The Debian based Neo4j Docker image does *not* support FIPS compatible encryption.
34
+
====
35
+
36
+
To enable the OpenSSL FIPS provider, set the environment variable `NEO4J_OPENSSL_FIPS_ENABLE=true` when starting the container.
37
+
38
+
[source, shell, subs="attributes"]
39
+
.Example starting a Neo4j UBI9 container with FIPS enable flag set.
40
+
----
41
+
docker run -it --rm \
42
+
--publish=7474:7474 \
43
+
--publish=7687:7687 \
44
+
--env=NEO4J_OPENSSL_FIPS_ENABLE=true \
45
+
--volume=$HOME/neo4j/data:/data \
46
+
--volume=$HOME/neo4j/conf:/conf \
47
+
--volume=$HOME/neo4j/certificates:/ssl \
48
+
neo4j:{neo4j-version-exact}-enterprise-ubi9
49
+
----
50
+
51
+
== Enable FIPS SSL provider
52
+
53
+
[IMPORTANT]
54
+
====
55
+
Skip this section if using Neo4j in Docker.
56
+
====
57
+
58
+
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.
59
+
Specifically Netty's "Forked Tomcat Native" library called https://github.com/netty/netty-tcnative[netty-tcnative].
60
+
61
+
To be FIPS compatible, the dynamically linked version of `netty-tcnative` must be used, alongside a FIPS compatible installation of OpenSSL.
62
+
63
+
The `netty-tcnative` library is provided in several variants, but
64
+
to be FIPS compatible the dynamically linked version of `netty-tcnative` must be used.
65
+
This dynamically linked library requires that the following dependencies are installedfootnote:[https://netty.io/wiki/forked-tomcat-native.html]:
66
+
67
+
* Apache Portable Runtime Library
68
+
* A FIPS certified version of OpenSSL, with a FIPS provider installed and set as default.
69
+
70
+
Refer to https://netty.io/wiki/forked-tomcat-native.html for more information.
71
+
72
+
73
+
[NOTE]
74
+
====
75
+
Netty provide a convenient pre-build, statically linked version of `netty-tcnative` using BoringSSL, but this is not FIPS certifiedfootnote:[https://boringssl.googlesource.com/boringssl/+/master/crypto/fipsmodule/FIPS.md].
76
+
77
+
By using the dynamic `netty-tcnative` library variant combined with a FIPS certified OpenSSL installation, Neo4j's cryptographic operations are delegated by `netty-tcnative` to OpenSSL, transitively giving FIPS compatibility.
78
+
====
79
+
80
+
[[install-apr]]
81
+
=== Install Apache portable runtime library
82
+
83
+
The simplest way to install https://apr.apache.org[Apache Portable Runtime Library] is to use the operating system's package manager.
84
+
85
+
In Debian/Ubuntu this package is usually called `libapr1`
86
+
[source, shell, subs="attributes"]
87
+
.Install Apache Portable Runtime Library in Debian or Ubuntu
88
+
----
89
+
apt install -y libapr1
90
+
----
91
+
92
+
In RedHat Enterprise Linux the package is usually called `apr`:
93
+
94
+
[source, shell, subs="attributes"]
95
+
.Install Apache Portable Runtime Library in RedHat
96
+
----
97
+
dnf install -y apr
98
+
----
99
+
100
+
=== Install OpenSSL
101
+
102
+
Instructions on how to build and install a FIPS compatible OpenSSL are out of scope for this document. Installation steps can differ depending on operating system, and other security requirements you might have for OpenSSL.
103
+
104
+
In general:
105
+
106
+
* A list of FIPS certified OpenSSL versions can be found at https://openssl-library.org/source/
Since Neo4j 5.23.0, builds of `netty-tcnative` dynamic library are provided in
126
+
the Neo4j `lib` directory under their own subfolder called `netty-tcnative`.
127
+
128
+
Installation is just a case of copying the correct jar for the local machine's operating system and architecture into the
129
+
130
+
To install the `netty-tcnative` dynamic library:
131
+
132
+
. Locate the Neo4j `lib` directory.
133
+
+
134
+
The location of the `lib` directory is different depending on the method used to install Neo4j. Check the xref:configuration/file-locations.adoc#neo4j-lib[file locations] documentation for the correct location.
135
+
+
136
+
This location will be referred to as _<NEO4J_LIB>_.
137
+
+
138
+
. BLAh
139
+
+
140
+
[source, shell]
141
+
.Check which netty-tcnative libraries are available
The `ldd` command will show a list of `netty-tcnative` library dependencies and where they will be loaded from on the local machine.
167
+
If any dependencies are missing, they must be installed or Neo4j will fail to run.
168
+
169
+
170
+
== Generate SSL certificate and private key
171
+
172
+
Neo4j SSL encryption requires a
173
+
xref:security/ssl-framework.adoc#term-ssl-certificate[certificate] in the xref:security/ssl-framework.adoc#term-ssl-x509[X.509] standard, encoded in PEM format.
174
+
and a private key in xref:security/ssl-framework.adoc#term-ssl-pkcs8[PKCS #8] format, also PEM encoded.
175
+
176
+
For FIPS compatibility, the private key must also be secured with a passphrase.
177
+
178
+
Refer to the xref:security/ssl-framework.adoc#ssl-certificates[SSL certificate and key instructions] for a detailed setup guide to creating the SSL certificate and key pair.
Copy file name to clipboardExpand all lines: modules/ROOT/pages/security/ssl-framework.adoc
+35-97Lines changed: 35 additions & 97 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,138 +13,76 @@ The SSL framework provides support for securing the following Neo4j communicatio
13
13
This page describes how to set up SSL within your environment, how to view, validate, and test the certificates.
14
14
15
15
[[ssl-providers]]
16
-
== SSL providers
16
+
== SSL Providers
17
17
18
18
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.
19
+
Each version of Neo4j ships with a version of Netty, and Netty requires a specific version of the `netty-tcnative` library for compatibility.
19
20
20
21
Follow these steps to use OpenSSL:
21
22
22
-
- Install a suitable dependency into the `plugins/` folder of Neo4j.
23
+
* Install a suitable `netty-tcnative` dependency into the `plugins/` folder of Neo4j.
24
+
** Dependencies can be downloaded from https://netty.io/wiki/forked-tomcat-native.html.
25
+
** Which `netty-tcnative` version you need depends upon the Neo4j version.
26
+
For versioning details, see the <<table, Netty support per Neo4j version>> table.
27
+
Make sure to install a build variant that matches your OS and architecture.
28
+
* Set `xref:configuration/configuration-settings.adoc#config_dbms.netty.ssl.provider[dbms.netty.ssl.provider]=OPENSSL`.
29
+
* Restart Neo4j.
23
30
24
31
[NOTE]
25
32
====
26
-
Dependencies can be downloaded from https://netty.io/wiki/forked-tomcat-native.html.
27
-
Which dependencies you need depends upon the Neo4j version.
28
-
Each version of Neo4j ships with a version of Netty and Netty requires specific tcnative versions.
29
-
Make sure to install the version that matches your OS processor.
30
-
For more details, see the <<table, Netty support per Neo4j version>>.
33
+
Using non-static versions of tcnative will require installation of platform-specific dependency libraries as described in https://netty.io/wiki/forked-tomcat-native.html.
34
+
35
+
In most use cases, the statically linked `boringssl` variant of `netty-tcnative` will be sufficient to enable SSL encryption.
31
36
====
32
37
33
-
- Using non static versions of tcnative will require installation of platform-specific OpenSSL dependencies as described in https://netty.io/wiki/forked-tomcat-native.html.
34
-
- Set `xref:configuration/configuration-settings.adoc#config_dbms.netty.ssl.provider[dbms.netty.ssl.provider]=OPENSSL`.
35
-
- Restart Neo4j.
38
+
The following table shows information about supported Neo4j versions.
36
39
37
-
[NOTE]
40
+
The following table lists when the `netty-tcnative` dependency was updated in Neo4j.
41
+
42
+
[TIP]
38
43
====
39
-
From Neo4j 5.21 on, required Netty and tcnative files are included in the _/lib_ directory.
44
+
If a Neo4j version is not listed, use the table entry for the next earliest Neo4j version listed.
45
+
46
+
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`.
40
47
====
41
48
42
-
The following table includes detailed information about supported Neo4j versions:
43
49
44
50
[[table]]
45
-
.Netty support per Neo4j version
46
-
[options="header", cols="1,1,2,3"]
51
+
.Netty-TCNative support per Neo4j version
52
+
[options="header,autowidth", cols="1,4,2"]
47
53
|===
48
54
| Neo4j version
49
-
| Netty version
50
55
| tcnative version
51
56
| Direct link
52
57
53
-
| 5.22
54
-
| 4.1.111.Final
55
-
| 2.0.65.Final. Both netty-tcnative-boringssl-static and netty-tcnative-classes are required.
@@ -1133,7 +1071,7 @@ For more information, see xref:configuration/command-expansion.adoc[Command expa
1133
1071
There are cases where Neo4j Enterprise requires the use of specific ciphers for encryptions.
1134
1072
One can set up a Neo4j configuration by specifying the list of cipher suites that will be allowed during cipher negotiation.
1135
1073
Valid values depend on the current JRE and SSL provider.
1136
-
For Oracle JRE here is the list of supported ones - https://docs.oracle.com/en/java/javase/11/docs/specs/security/standard-names.html#jsse-cipher-suite-names.
1074
+
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.
0 commit comments