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
The National Institute of Standards and Technology (NIST) developed the Federal Information Processing Standard (FIPS) Publication 140-2 as a security standard that sets forth requirements for cryptographic modules, including hardware, software, and/or firmware, for U.S. federal agencies.
9
9
While FIPS 140 compliance is primarily required for federal agencies and their contractors, it also is used in the healthcare sector under regulations like the Health Insurance Portability and Accountability Act (HIPAA) to protect patient data.
10
10
11
-
Neo4j 4.4 officially supports FIPS 140-2 compliance.
12
-
13
11
This guide helps configure Neo4j to use TLS/SSL encryption in a FIPS-compliant way.
14
12
It is supplementary to the xref:security/ssl-framework.adoc[SSL framework documentation], as many of the configuration processes and requirements are the same.
15
13
16
14
17
-
[[fips-prerequisites]]
15
+
[[ssl-fips-prerequisites]]
18
16
== Prerequisites
19
17
20
18
* Verify that the machine running Neo4j has FIPS-compatible hardware and operating system.
21
19
Only xref:installation/requirements.adoc#deployment-requirements-software[Linux operating systems] are supported for Neo4j FIPS compatibility.
22
-
* Deploy OpenSSL 3.0.8/3.0.9 in the FIPS mode.
20
+
* Use Neo4j Enterprise 4.4.36 or later.
23
21
* Install and configure a non-native authentication provider, for example LDAP or SSO.
24
22
See xref:authentication-authorization/index.adoc[].
25
23
26
24
27
-
[[fips-ssl-providers]]
25
+
[[fips-ssl-provider]]
28
26
== Enable FIPS SSL provider
29
27
30
-
Set SSL policies on Bolt and HTTPS in the _neo4j.conf_ file.
31
-
See xref:security/ssl-framework.adoc#ssl-configuration[SSL framework -> Configuration] for detailed instructions.
28
+
The secure networking in Neo4j is provided through the Netty library, which supports both the native JDK SSL provider and Netty-supported OpenSSL derivatives.
29
+
Specifically Netty's _Forked Tomcat Native_ library called https://github.com/netty/netty-tcnative[netty-tcnative].
32
30
33
-
=== Set SSL provider to OpenSSL
31
+
The `netty-tcnative` library is provided in several variants.
32
+
However, to achieve FIPS compliance, you must use the dynamically linked version of `netty-tcnative` alongside a FIPS-compatible installation of OpenSSL.
34
33
35
-
Instructions on how to build and install a FIPS-compatible OpenSSL are out of scope for this document.
36
-
Installation steps can differ depending on operating system, and other security requirements you might have for OpenSSL.
34
+
The dynamically linked library requires the following dependencies to be installedfootnote:[https://netty.io/wiki/forked-tomcat-native.html]:
37
35
38
-
* For a list of FIPS certified OpenSSL versions, see link:https://openssl-library.org/source/[].
39
-
* A FIPS provider must be installed into OpenSSL.
40
-
* OpenSSL must be configured to use the FIPS provider by default.
36
+
* Apache Portable Runtime Library
37
+
* A FIPS certified version of OpenSSL, with a FIPS provider installed and set as default.
41
38
42
-
=== Use the correct version of the `netty-tcnative` library
39
+
Refer to https://netty.io/wiki/forked-tomcat-native.html[Forked Tomcat Native] for more information.
43
40
44
-
To achieve FIPS compliance, you must use the dynamically linked version of `netty-tcnative` alongside a FIPS-compatible installation of OpenSSL.
45
41
46
-
. The dynamically linked library requires the Apache Portable Runtime Library also to be installed.
47
-
To install it, use the operating system’s package manager.
48
-
+
49
-
In Debian/Ubuntu this package is usually called `libapr1`.
50
-
+
42
+
[NOTE]
43
+
====
44
+
Netty provides 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].
45
+
46
+
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.
47
+
====
48
+
49
+
[[install-apr]]
50
+
=== Install Apache portable runtime library
51
+
52
+
To install https://apr.apache.org[Apache Portable Runtime Library], use the operating system's package manager.
53
+
54
+
In Debian/Ubuntu this package is usually called `libapr1`
51
55
[source, console, subs="attributes"]
52
56
.Install Apache Portable Runtime Library in Debian or Ubuntu
53
57
----
54
58
apt install -y libapr1
55
59
----
56
-
+
60
+
57
61
In RedHat Enterprise Linux, the package is usually called `apr`:
58
-
+
62
+
59
63
[source, console, subs="attributes"]
60
64
.Install Apache Portable Runtime Library in RedHat
The location of the `lib` directory is dependent on the installation and your operating system.
73
-
Default file locations are documented in the xref:configuration/file-locations.adoc[Configuration -> Default file locations].
74
-
====
72
+
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.
75
73
76
-
. Make sure there are no `netty-tcnative-boringssl` libraries present in the `lib` folder.
74
+
In general:
75
+
76
+
* For a list of FIPS certified OpenSSL versions, see https://openssl-library.org/source/[].
77
+
* A FIPS provider must be installed into OpenSSL.
78
+
* OpenSSL must be configured to use the FIPS provider by default.
79
+
80
+
81
+
[[install-netty-tcnative-lib]]
82
+
=== Install `netty-tcnative` library
83
+
84
+
85
+
// TODO
86
+
87
+
// download files, but which files? have a table maybe?
88
+
// put files in lib folder. Can recycle the 5x documentation.
89
+
90
+
// from 4.4.36 neo4j has used 2.0.65.Final
91
+
// before that it used 2.0.61.Final
92
+
// this needs to be a table, but that doesn't make sense until we have to provide more than one version of netty tcnative
93
+
94
+
. Locate the Neo4j `lib` directory.
77
95
+
96
+
The location of the `lib` directory is different depending on the method used to install Neo4j.
97
+
Check the xref:configuration/file-locations.adoc#neo4j-lib[file locations] documentation for the correct location.
98
+
+
99
+
This location will be referred to as _<NEO4J_LIB>_.
100
+
. Make sure there are no `netty-tcnative-boringssl` libraries present in the _<NEO4J_LIB>_ folder.
. Check which `netty-tcnative` libraries are available:
107
+
. Download netty-tcnative dynamic library.
108
+
+
109
+
The dynamic version of `netty-tcnative` library provided by link:https://netty.io/wiki/forked-tomcat-native.html[netty.io] is not compatible with OpenSSL 3.0.0 or later.
110
+
+
111
+
To get around this, we have re-compiled `netty-tcnative` to make OpenSSL 3 compatible netty-tcnative JAR files for use with Neo4j.
112
+
These can be downloaded from https://assets.neo4j.com/netty-tcnative/2.0.65.Final/simplified/netty-tcnative-2.0.65.Final-all.tar[]
113
+
+
114
+
// This is commented out because we only have one compatible version of tcnative so far.
115
+
// when we have more versions to be compatible with then it makes sense to use a table instead of a direct link.
116
+
// However it looks a bit weird to use a table when we only have one row in the table.
117
+
//
118
+
// To download the correct `netty-tcnative` version for your Neo4j installation, check the table for a download link:
// If a Neo4j version is not listed, use the table entry for the next earliest Neo4j version listed.
132
+
//
133
+
// For example: for Neo4j 4.4.38 the next earliest version listed in the table is 4.4.36, so the required `netty-tcnative` version is `2.0.65.Final`.
134
+
// ====
83
135
+
136
+
There are Linux and Fedora Linux variants available in the tar, compiled for both x86_64 and ARM 64 architectures. Select the one matching the local machine's operating system and architecture.
137
+
+
138
+
. Copy the downloaded `netty-tcnative` JAR file into _<NEO4J_LIB>_.
139
+
+
140
+
. Verify the `netty-tcnative` dependencies are correctly installed using https://www.man7.org/linux/man-pages/man1/ldd.1.html[`ldd`]:
The `ldd` command shows a list of library dependencies and where they are loaded from on the local machine.
158
+
** If any dependencies are missing, they must be installed, or Neo4j will fail to run.
159
+
** The `libssl.so` and `libcrypto.so` libraries listed must be the ones installed with OpenSSL in the previous steps.
94
160
95
-
=== Generate SSL certificate and private key
161
+
[NOTE]
162
+
====
163
+
Only copy *one* of the JAR files. Otherwise Neo4j will not be able to resolve dependencies at runtime.
164
+
In case of this error, you will get a message like:
165
+
[source]
166
+
----
167
+
"Failed to load any of the given libraries: [netty_tcnative_linux_x86_64, netty_tcnative_linux_x86_64_fedora, netty_tcnative_x86_64, netty_tcnative]".
168
+
----
169
+
====
170
+
171
+
[[generate-ssl-cert-private-key]]
172
+
== Generate SSL certificate and private key
173
+
174
+
Neo4j SSL encryption requires a xref:security/ssl-framework.adoc#term-ssl-certificate[certificate] in the X.509 standard and a private key in PKCS #8 format, both encoded in PEM format.
96
175
97
176
[IMPORTANT]
98
177
====
99
178
For FIPS compatibility, the private key must be secured with a password.
100
179
====
180
+
101
181
Refer to the xref:security/ssl-framework.adoc#ssl-certificates[SSL certificate and key instructions] for more information.
102
182
103
-
=== Configure _neo4j.conf_
104
183
105
-
At last, you have to configure the _neo4j.conf_ file to use FIPS 140-2 approved ciphers.
184
+
[[configure-neo4j-ssl-encryption]]
185
+
== Configure Neo4j to use SSL encryption
186
+
187
+
SSL configuration is described in detail in xref:security/ssl-framework.adoc#ssl-configuration[SSL framework configuration].
188
+
189
+
This section describes configuration that must be done *in addition to* standard non-FIPS compliant SSL configuration.
190
+
191
+
[[bolt-ssl-fips]]
192
+
=== Bolt
193
+
194
+
. Set `xref:configuration/configuration-settings.adoc#config_dbms.netty.ssl.provider[dbms.netty.ssl.provider]=OPENSSL`
195
+
. Set `xref:configuration/configuration-settings.adoc#config_server.bolt.tls_level[dbms.connector.bolt.tls_level]=REQUIRED`
196
+
. Follow instructions on how to xref:security/ssl-framework.adoc#ssl-bolt-config[Configure SSL over Bolt].
. Follow the instructions in xref:security/ssl-framework.adoc#ssl-config-private-key[SSL Framework -> Using encrypted private key] to configure `dbms.ssl.policy.bolt.private_key_password` to dynamically read the password from an encrypted password file.
207
+
The password must *not* be set in plain text.
208
+
209
+
210
+
[[https-ssl-fips]]
211
+
=== HTTPS
212
+
213
+
This section is only applicable if HTTPS is enabled.
214
+
215
+
. Follow instructions on how to xref:security/ssl-framework.adoc#ssl-https-config[Configure SSL over HTTPS].
. Follow the instructions in xref:security/ssl-framework.adoc#ssl-config-private-key[SSL Framework -> Using encrypted private key] to configure `dbms.ssl.policy.https.private_key_password` to dynamically read the password from an encrypted password file. The password must NOT be set in plain text.
227
+
228
+
[[intra-cluster-encryption-ssl-fips]]
229
+
=== Intra-cluster encryption
230
+
231
+
For FIPS compatbility, intra-cluster encryption must be enabled if you are running a Neo4j cluster.
232
+
233
+
. Follow instructions to xref:security/ssl-framework.adoc#ssl-cluster-config[configure SSL for intra-cluster communication].
. Follow the instructions in xref:security/ssl-framework.adoc#ssl-config-private-key[SSL Framework -> Using encrypted private key] to configure `dbms.ssl.policy.cluster.private_key_password` to dynamically read the password from an encrypted password file.
245
+
The password must *not* be set in plain text.
246
+
247
+
248
+
[[backup-ssl-fips]]
249
+
=== Backup
250
+
251
+
This section is applicable on instances or cluster members used for taking backups.
252
+
253
+
. Follow instructions on how to xref:security/ssl-framework.adoc#ssl-backup-config[Configure SSL for backup communication].
. Follow the instructions in xref:security/ssl-framework.adoc#ssl-config-private-key[SSL Framework -> Using encrypted private key] to configure `dbms.ssl.policy.backup.private_key_password` to dynamically read the password from an encrypted password file.
0 commit comments