Skip to content

Commit a679447

Browse files
NataliaIvakinajennyowen
NataliaIvakina
and
jennyowen
authored
New SSL instructions for FIPS compatibility (neo4j#1806) (neo4j#1841)
I cleaned up the existing SSL documentation and added a new page about how to configure SSL to be FIPS compatible. --------- Co-authored-by: Jenny Owen <[email protected]>
1 parent cfd6c7b commit a679447

File tree

5 files changed

+306
-99
lines changed

5 files changed

+306
-99
lines changed

‎modules/ROOT/content-nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -193,6 +193,7 @@
193193
* xref:security/index.adoc[]
194194
** xref:security/securing-extensions.adoc[]
195195
** xref:security/ssl-framework.adoc[]
196+
*** xref:security/ssl-fips-compatibility.adoc[]
196197
** xref:security/browser.adoc[]
197198
** xref:security/checklist.adoc[]
198199

‎modules/ROOT/pages/configuration/file-locations.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88

99
The page describes the Neo4j directories, specifying their default locations per distribution and minimal file permissions.
1010

11+
If Neo4j was installed using a `tar.gz` or `zip` archive, _<NEO4J_HOME>_ refers to the location the archive was extracted to.
12+
1113
Instructions provided for Neo4j Desktop are applicable across all operating systems where Neo4j Desktop is supported.
1214

1315
[NOTE]

‎modules/ROOT/pages/docker/introduction.adoc‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,6 @@ Variants of the Neo4j image are tagged according to
1111
Community/Enterprise Edition and the operating system used as the base image.
1212

1313

14-
All supported tags can be found at https://hub.docker.com/_/neo4j/tags.
15-
1614
=== Neo4j editions
1715
Tags are available for both Community Edition and Enterprise Edition.
1816
Version-specific Enterprise Edition tags have an `-enterprise` suffix after the version number, for example: `neo4j:{neo4j-version-exact}-enterprise`.

‎modules/ROOT/pages/security/ssl-fips-compatibility.adoc‎

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
[role=enterprise-edition]
2+
[[ssl-fips-compatibility]]
3+
= Configuring SSL for FIPS 140-2 compatibility
4+
:description: How to configure Neo4j to use FIPS compatible SSL encryption.
5+
:keywords: ssl, tls, authentication, encryption, encrypted, security, fips, fips 140, fips 140-2, nist, hipaa
6+
7+
Federal Information Processing Standards (FIPS) 140 is a U.S. government standard established by the National Institute of Standards and Technology (NIST) which is used to accredit cryptographic modules such as those used in TLS network encryption.
8+
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.
9+
10+
This guide helps configure Neo4j to use TLS/SSL encryption in a FIPS-compliant way.
11+
It is supplementary to the xref:security/ssl-framework.adoc[] documentation, as many of the configuration processes and requirements are the same.
12+
13+
14+
[[ssl-fips-prerequisites]]
15+
== Prerequisites
16+
17+
* Verify that the machine running Neo4j has FIPS-compatible hardware and operating system.
18+
Only xref:installation/requirements.adoc#deployment-requirements-software[Linux operating systems] are supported for Neo4j FIPS compatibility at this time.
19+
* Use Neo4j Enterprise 5.23.0 or later.
20+
* Install and configure a non-native authentication provider, for example LDAP or SSO. See xref:authentication-authorization/index.adoc[].
21+
22+
23+
[[fips-ssl-provider-docker]]
24+
== Enable FIPS SSL provider (Docker)
25+
26+
The Neo4j RedHat UBI9 Docker image comes with the SSL provider and dependencies pre-installed, but it is not enabled by default.
27+
28+
[NOTE]
29+
====
30+
The Debian based Neo4j Docker image does *not* support FIPS compatible encryption.
31+
====
32+
33+
To enable the OpenSSL FIPS provider, set the environment variable `NEO4J_OPENSSL_FIPS_ENABLE=true` when starting the container.
34+
35+
[source, console, subs="attributes"]
36+
.Example of starting a Neo4j UBI9 container with FIPS enable flag set.
37+
----
38+
docker run -it --rm \
39+
--publish=7474:7474 \
40+
--publish=7687:7687 \
41+
--env=NEO4J_OPENSSL_FIPS_ENABLE=true \
42+
--volume=$HOME/neo4j/data:/data \
43+
--volume=$HOME/neo4j/conf:/conf \
44+
--volume=$HOME/neo4j/certificates:/ssl \
45+
neo4j:{neo4j-version-exact}-enterprise-ubi9
46+
----
47+
48+
[[fips-ssl-provider]]
49+
== Enable FIPS SSL provider
50+
51+
[IMPORTANT]
52+
====
53+
Skip this section if using Neo4j in Docker.
54+
====
55+
56+
The secure networking in Neo4j is provided through the Netty library, which supports both the native JDK SSL provider and Netty-supported OpenSSL derivatives.
57+
Specifically Netty's _Forked Tomcat Native_ library called https://github.com/netty/netty-tcnative[netty-tcnative].
58+
59+
The `netty-tcnative` library is provided in several variants.
60+
However, to achieve FIPS compliance, you must use the dynamically linked version of `netty-tcnative` alongside a FIPS-compatible installation of OpenSSL.
61+
62+
The dynamically linked library requires the following dependencies to be installedfootnote:[https://netty.io/wiki/forked-tomcat-native.html]:
63+
64+
* Apache Portable Runtime Library
65+
* A FIPS certified version of OpenSSL, with a FIPS provider installed and set as default.
66+
67+
Refer to https://netty.io/wiki/forked-tomcat-native.html[Forked Tomcat Native] for more information.
68+
69+
70+
[NOTE]
71+
====
72+
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].
73+
74+
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.
75+
====
76+
77+
[[install-apr]]
78+
=== Install Apache portable runtime library
79+
80+
To install https://apr.apache.org[Apache Portable Runtime Library], use the operating system's package manager.
81+
82+
In Debian/Ubuntu this package is usually called `libapr1`
83+
[source, console, subs="attributes"]
84+
.Install Apache Portable Runtime Library in Debian or Ubuntu
85+
----
86+
apt install -y libapr1
87+
----
88+
89+
In RedHat Enterprise Linux, the package is usually called `apr`:
90+
91+
[source, console, subs="attributes"]
92+
.Install Apache Portable Runtime Library in RedHat
93+
----
94+
dnf install -y apr
95+
----
96+
97+
[[install-openssl]]
98+
=== Install OpenSSL
99+
100+
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.
101+
102+
In general:
103+
104+
* For a list of FIPS certified OpenSSL versions, see https://openssl-library.org/source/[].
105+
* A FIPS provider must be installed into OpenSSL.
106+
* OpenSSL must be configured to use the FIPS provider by default.
107+
108+
109+
110+
[[install-netty-tcnative-lib]]
111+
=== Install the correct `netty-tcnative` library
112+
113+
Since Neo4j 5.23.0, builds of `netty-tcnative` dynamic library are provided in the Neo4j `lib` directory under their own subfolder called `netty-tcnative`.
114+
115+
To install the `netty-tcnative` dynamic library:
116+
117+
. Locate the Neo4j `lib` directory.
118+
+
119+
The location of the `lib` directory is different depending on the method used to install Neo4j.
120+
Check the xref:configuration/file-locations.adoc#neo4j-lib[file locations] documentation for the correct location.
121+
+
122+
This location will be referred to as _<NEO4J_LIB>_.
123+
. Make sure there are no `netty-tcnative-boringssl` libraries present in the _<NEO4J_LIB>_ folder.
124+
+
125+
[source, console]
126+
----
127+
find <NEO4J_LIB> -name "netty-tcnative-boringssl*.jar" -delete
128+
----
129+
+
130+
. Check which netty-tcnative libraries are available:
131+
+
132+
[source, console]
133+
----
134+
ls -l <NEO4J_LIB>/netty-tcnative
135+
----
136+
There are Linux and Fedora Linux variants available, compiled for both x86_64 and ARM 64 architectures.
137+
Select the one matching the local machine's operating system and architecture.
138+
+
139+
. Verify the dependencies are correctly installed using https://www.man7.org/linux/man-pages/man1/ldd.1.html[`ldd`]:
140+
+
141+
[source, console]
142+
.Verify netty-tcnative dependencies are installed
143+
----
144+
unzip -d /tmp <NEO4J_LIB>/netty-tcnative/netty-tcnative-*-linux-$(arch).jar
145+
ldd /tmp/META-INF/native/libnetty_tcnative_linux_*.so
146+
rm -rf /tmp/META-INF
147+
----
148+
+
149+
[source, console]
150+
.Verify Fedora variant of netty-tcnative dependencies are installed
151+
----
152+
unzip -d /tmp <NEO4J_LIB>/netty-tcnative/netty-tcnative-*-linux-$(arch)-fedora.jar
153+
ldd /tmp/META-INF/native/libnetty_tcnative_linux_$(arch).so
154+
rm -rf /tmp/META-INF
155+
----
156+
The `ldd` command shows a list of library dependencies and where they are loaded from on the local machine.
157+
** If any dependencies are missing, they must be installed, or Neo4j will fail to run.
158+
** The `libssl.so` and `libcrypto.so` libraries listed must be the ones installed with OpenSSL in the previous steps.
159+
+
160+
. Copy the verified JAR file to _<NEO4J_LIB>_.
161+
+
162+
[NOTE]
163+
====
164+
Only copy *one* of the JAR files. Otherwise Neo4j will not be able to resolve dependencies at runtime.
165+
In case of this error, you will get a message like:
166+
[source]
167+
----
168+
"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]".
169+
----
170+
====
171+
172+
[[generate-ssl-cert-private-key]]
173+
== Generate SSL certificate and private key
174+
175+
Neo4j SSL encryption requires a xref:security/ssl-framework.adoc#term-ssl-certificate[certificate] in the xref:security/ssl-framework.adoc#term-ssl-x509[X.509] standard and a private key in xref:security/ssl-framework.adoc#term-ssl-pkcs8[PKCS #8] format, both encoded in PEM format.
176+
177+
[IMPORTANT]
178+
====
179+
For FIPS compatibility, the private key must be secured with a password.
180+
====
181+
182+
Refer to the xref:security/ssl-framework.adoc#ssl-certificates[SSL certificate and key instructions] for more information.
183+
184+
185+
[[configure-neo4j-ssl-encryption]]
186+
== Configure Neo4j to use SSL encryption
187+
188+
SSL configuration is described in detail in xref:security/ssl-framework.adoc#ssl-configuration[SSL framework configuration].
189+
190+
This section describes configuration that must be done *in addition to* standard non-FIPS compliant SSL configuration.
191+
192+
[[bolt-ssl-fips]]
193+
=== Bolt
194+
195+
. Set `xref:configuration/configuration-settings.adoc#config_dbms.netty.ssl.provider[dbms.netty.ssl.provider]=OPENSSL`
196+
. Set `xref:configuration/configuration-settings.adoc#config_server.bolt.tls_level[server.bolt.tls_level]=REQUIRED`
197+
. Follow instructions on how to xref:security/ssl-framework.adoc#ssl-bolt-config[Configure SSL over Bolt].
198+
. Set additional Bolt configurations:
199+
+
200+
[source, properties]
201+
----
202+
dbms.ssl.policy.bolt.trust_all=false
203+
dbms.ssl.policy.bolt.tls_level=REQUIRED
204+
dbms.ssl.policy.bolt.tls_versions=TLSv1.2,TLSv1.3
205+
dbms.ssl.policy.bolt.ciphers=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256,TLS_AES_128_CCM_8_SHA256,TLS_AES_128_CCM_SHA256
206+
----
207+
. 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.
208+
The password must *not* be set in plain text.
209+
210+
211+
[[https-ssl-fips]]
212+
=== HTTPS
213+
214+
This section is only applicable if HTTPS is enabled.
215+
216+
. Follow instructions on how to xref:security/ssl-framework.adoc#ssl-https-config[Configure SSL over HTTPS].
217+
+
218+
. Set additional HTTPS configurations:
219+
+
220+
[source, properties]
221+
----
222+
dbms.ssl.policy.https.trust_all=false
223+
dbms.ssl.policy.https.tls_level=REQUIRED
224+
dbms.ssl.policy.https.tls_versions=TLSv1.2,TLSv1.3
225+
dbms.ssl.policy.https.ciphers=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256,TLS_AES_128_CCM_8_SHA256,TLS_AES_128_CCM_SHA256
226+
----
227+
. 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.
228+
229+
[[intra-cluster-encryption-ssl-fips]]
230+
=== Intra-cluster encryption
231+
232+
For FIPS compatbility, intra-cluster encryption must be enabled if you are running a Neo4j cluster.
233+
234+
. Follow instructions to xref:security/ssl-framework.adoc#ssl-cluster-config[configure SSL for intra-cluster communication].
235+
. Set additional cluster configurations:
236+
+
237+
[source, properties]
238+
----
239+
dbms.ssl.policy.cluster.enabled=true
240+
dbms.ssl.policy.cluster.tls_level=REQUIRED
241+
dbms.ssl.policy.cluster.client_auth=REQUIRED
242+
dbms.ssl.policy.cluster.tls_versions=TLSv1.2,TLSv1.3
243+
dbms.ssl.policy.cluster.ciphers=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256,TLS_AES_128_CCM_8_SHA256,TLS_AES_128_CCM_SHA256
244+
----
245+
. 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.
246+
The password must *not* be set in plain text.
247+
248+
249+
[[backup-ssl-fips]]
250+
=== Backup
251+
252+
This section is applicable on instances or cluster members used for taking backups.
253+
254+
. Follow instructions on how to xref:security/ssl-framework.adoc#ssl-backup-config[Configure SSL for backup communication].
255+
. Set additional backup configurations:
256+
+
257+
[source, properties]
258+
----
259+
dbms.ssl.policy.backup.enabled=true
260+
dbms.ssl.policy.backup.client_auth=REQUIRED
261+
dbms.ssl.policy.backup.trust_all=false
262+
dbms.ssl.policy.backup.tls_versions=TLSv1.2,TLSv1.3
263+
dbms.ssl.policy.backup.ciphers=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256,TLS_AES_128_CCM_8_SHA256,TLS_AES_128_CCM_SHA256
264+
----
265+
. 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.
266+
The password must *not* be set in plain text.
267+

0 commit comments

Comments
 (0)