Skip to content

Commit bf9bb6a

Browse files
kevintrollerkevintroller
committed
Add FIPS 140-3 compliance support documentation
- Add gov-cloud-fips-140-3-support.adoc with migration paths, Bouncy Castle setup, cipher suites, keystore formats, and connector compatibility - Update nav.adoc and index.adoc for new FIPS 140-3 content Made-with: Cursor
1 parent 31a5a4e commit bf9bb6a

3 files changed

Lines changed: 294 additions & 1 deletion

File tree

‎modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
** xref:gov-cloud-standalone.adoc[Standalone Mule Support]
44
* xref:release-notes.adoc[Release Notes]
55
* xref:gov-cloud-security.adoc[Security in Government Cloud]
6+
* xref:gov-cloud-fips-140-3-support.adoc[FIPS 140-3 Compliance Support]
67
* xref:gov-cloud-secure-configuration-fedramp.adoc[Secure Configuration for FedRAMP]
78
* xref:gov-cloud-account-setup.adoc[Set Up Your Government Cloud Account]
89
* xref:gov-cloud-load-balancer.adoc[Dedicated Load Balancer]

‎modules/ROOT/pages/gov-cloud-fips-140-3-support.adoc‎

Lines changed: 292 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,292 @@
1+
= FIPS 140-3 Compliance Support
2+
ifndef::env-site,env-github[]
3+
include::_attributes.adoc[]
4+
endif::[]
5+
:keywords: fips, certifications, security, fips-140-3, government cloud
6+
7+
Configure Mule runtime engine (Mule) to run in a Federal Information Processing Standard (FIPS) 140-3 certified environment in MuleSoft Government Cloud.
8+
9+
Mule doesn't run in FIPS security mode by default. To enable it, you must:
10+
11+
* Install a certified cryptography module in your Java environment.
12+
* Adjust Mule runtime settings to run in FIPS security mode.
13+
14+
Follow the migration path that matches your scenario:
15+
16+
* <<migrate-fips1402-to-fips1403,Migrating Mule from FIPS 140-2 to FIPS 140-3>>
17+
* <<migrate-non-fips-to-fips1403,Migrating Mule from Non-FIPS to FIPS 140-3>>
18+
19+
20+
== Compatibility
21+
22+
FIPS 140-3 support in MuleSoft Government Cloud requires:
23+
24+
* Mule runtime engine 4.9 (Government Cloud supported version)
25+
* Java 17 or later
26+
* FIPS license from the license `.zip` file provided by MuleSoft (the non-FIPS license is not valid for FIPS mode)
27+
28+
== Assumptions
29+
30+
This document assumes you are familiar with https://csrc.nist.gov/publications/detail/fips/140/3/final[FIPS 140-3], the US government security standard that requires compliant parties to use only cryptographic algorithms and techniques certified by NIST.
31+
32+
These instructions use Bouncy Castle 2.0.0, the recommended FIPS 140-3 certified security provider for Mule runtime. If you use a different https://csrc.nist.gov/projects/cryptographic-module-validation-program/validated-modules[certified security provider], refer to that provider's documentation for configuration instructions.
33+
34+
[[migrate-fips1402-to-fips1403]]
35+
== Migrating from FIPS 140-2 to FIPS 140-3
36+
37+
If you are currently running Mule in FIPS 140-2 mode and want to move to FIPS 140-3, apply these cipher and configuration changes.
38+
39+
=== Cipher and Protocol Changes
40+
41+
* TLS and cipher suites: +
42+
FIPS 140-3 requires support for TLS 1.3 and TLS 1.2. Earlier TLS versions aren't supported. Use only the FIPS 140-3 compliant cipher suites listed in the xref:#fips-140-3-compliant-cipher-suites[FIPS 140-3 Compliant Cipher Suites] section. Remove or replace any custom TLS or cipher configuration that references FIPS 140-2-only or non–FIPS 140-3 cipher suites.
43+
* Configuration file: +
44+
FIPS 140-3 uses the `$MULE_HOME/conf/tls-fips140-3.conf` file for TLS cipher configuration. Ensure your runtime uses this file and that you have removed or replaced references to any FIPS 140-2 TLS configuration file.
45+
46+
=== Security Provider and Java Configuration
47+
48+
* Bouncy Castle version: +
49+
Replace the FIPS 140-2 Bouncy Castle provider (typically 1.x FIPS) with Bouncy Castle 2.0.0 FIPS. Install the JARs listed in xref:#set_up_environment[Installing Bouncy Castle Security Provider] and update `java.security` to use `BouncyCastleFipsProvider` and `BouncyCastleJsseProvider` as shown there.
50+
51+
* KeyManagerFactory and TrustManagerFactory: +
52+
In `$JAVA_HOME/conf/security/java.security`, set:
53+
+
54+
----
55+
ssl.KeyManagerFactory.algorithm=PKIX
56+
ssl.TrustManagerFactory.algorithm=PKIX
57+
----
58+
59+
=== Runtime Configuration (wrapper.conf)
60+
61+
* Security model: +
62+
Change the Mule security model from FIPS 140-2 to FIPS 140-3:
63+
+
64+
----
65+
# Enable FIPS 140-3 security mode (replace fips140-2)
66+
wrapper.java.additional.<n>=-Dmule.security.model=fips140-3
67+
----
68+
* Approved-only mode: +
69+
Add or ensure:
70+
+
71+
----
72+
wrapper.java.additional.<n>=-Dorg.bouncycastle.fips.approved_only=true
73+
----
74+
* Java 17+ module access: +
75+
Add:
76+
+
77+
----
78+
wrapper.java.additional.<n>=--add-opens=java.base/sun.security.provider=org.bouncycastle.fips.core
79+
----
80+
81+
=== Keystore Format
82+
83+
* BCFKS: +
84+
FIPS 140-3 requires keystores and truststores in `BCFKS` format. If you are still using `PKCS12` or `JKS` from your FIPS 140-2 setup, convert them to `BCFKS` using the steps in xref:#fips-140-3-compliant-keystore-formats[FIPS 140-3 Compliant Keystore Formats]. Update all TLS contexts in your Mule apps to reference the new keystores and set `type="bcfks"`.
85+
86+
=== Connectors and Post-Migration
87+
88+
* Use only connectors tagged as `fips-140-3-verified` in Anypoint Exchange. Replace or remove connectors that were only verified for FIPS 140-2.
89+
* Restart Mule after all changes and confirm in startup logs that FIPS 140-3 security mode is enabled.
90+
91+
[[migrate-non-fips-to-fips1403]]
92+
== Migrating from Non-FIPS to FIPS 140-3
93+
94+
If you are running Mule in standard (non-FIPS) mode and need to move directly to FIPS 140-3, complete the following steps.
95+
96+
=== Prerequisites
97+
98+
* Mule runtime engine 4.9, Java 17 or later, and a FIPS license from the license `.zip` file provided by MuleSoft.
99+
100+
=== Steps
101+
102+
. Install the FIPS 140-3 certified cryptography provider: +
103+
Follow xref:#set_up_environment[Installing Bouncy Castle Security Provider] to install Bouncy Castle 2.0.0 FIPS and configure `java.security` (providers and `ssl.KeyManagerFactory.algorithm` / `ssl.TrustManagerFactory.algorithm`).
104+
105+
. Configure Mule for FIPS 140-3 mode: +
106+
In `$MULE_HOME/conf/wrapper.conf`, add the properties described in xref:#running-mule-in-fips-security-mode[Running Mule in FIPS Security Mode] (`mule.security.model=fips140-3`, `org.bouncycastle.fips.approved_only=true`, and the `--add-opens` option). For Mule 4.9, set the keystore type explicitly:
107+
+
108+
----
109+
wrapper.java.additional.<n>=-Dmule.keystore.type=BCFKS
110+
----
111+
112+
. Convert keystores and truststores to BCFKS: +
113+
Standard Mule setups often use `PKCS12` or `JKS`. Convert all keystores and truststores used by your applications to `BCFKS` using the procedure in xref:#fips-140-3-compliant-keystore-formats[FIPS 140-3 Compliant Keystore Formats].
114+
115+
. Update TLS configuration in Mule apps: +
116+
In your Mule configuration files, update every `tls:context` to use the new BCFKS keystores and truststores with `type="bcfks"` as shown in xref:#fips-140-3-compliant-keystore-formats[FIPS 140-3 Compliant Keystore Formats].
117+
118+
. Remove non-compliant cipher and protocol usage: +
119+
Don't configure custom cipher suites or TLS versions that are not FIPS 140-3 compliant. Rely on the default FIPS 140-3 cipher suites (see xref:#fips-140-3-compliant-cipher-suites[FIPS 140-3 Compliant Cipher Suites]) and ensure no connectors or custom code force non-approved algorithms.
120+
121+
. Verify connector compliance: +
122+
Only use connectors tagged as `fips-140-3-verified` in Anypoint Exchange. Replace or remove any connector that is not FIPS 140-3 verified (see xref:#connectors-compatibility[Connectors Compatibility]).
123+
124+
. Restart Mule and validate: +
125+
Save all changes, restart Mule, and confirm in startup logs that FIPS 140-3 security mode is enabled. Test connectivity and integrations that use TLS and cryptography.
126+
127+
[[set_up_environment]]
128+
== Installing Bouncy Castle Security Provider
129+
130+
Mule runtime uses Bouncy Castle 2.0.0 as its FIPS 140-3 certified cryptography provider.
131+
132+
=== Installation Steps
133+
134+
These instructions show how to install and configure the Bouncy Castle security provider with Java 17 or later.
135+
136+
. Verify that you are using Java 17 or later and `JAVA_HOME` is set.
137+
. Download the Bouncy Castle 2.0.0 provider files from https://www.bouncycastle.org/fips-java/[the BouncyCastle website].
138+
. Copy the required JAR files to the `$MULE_HOME/lib/boot` folder:
139+
+
140+
----
141+
bc-fips-2.0.0.jar
142+
bctls-fips-2.0.19.jar
143+
bcpkix-fips-2.0.7.jar
144+
bcutil-fips-2.0.3.jar
145+
bcpg-fips-2.0.9.jar
146+
bcjmail-fips-2.0.5.jar
147+
----
148+
+
149+
. Configure the security providers in the `$JAVA_HOME/conf/security/java.security` file:
150+
+
151+
----
152+
security.provider.1=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider
153+
security.provider.2=org.bouncycastle.jsse.provider.BouncyCastleJsseProvider fips:BCFIPS
154+
security.provider.3=SUN
155+
----
156+
+
157+
. Configure the key manager and trust manager algorithms in the same `java.security` file:
158+
+
159+
----
160+
ssl.KeyManagerFactory.algorithm=PKIX
161+
ssl.TrustManagerFactory.algorithm=PKIX
162+
----
163+
164+
[[running-mule-in-fips-security-mode]]
165+
== Running Mule in FIPS Security Mode
166+
167+
After installing the Bouncy Castle provider, configure Mule to run in FIPS 140-3 mode:
168+
169+
. Open your `wrapper.conf` file (located in `$MULE_HOME/conf`).
170+
. Add these properties. Replace `<n>` with the next sequential number in your file:
171+
+
172+
----
173+
# Enable FIPS 140-3 security mode
174+
wrapper.java.additional.<n>=-Dmule.security.model=fips140-3
175+
176+
# Enable Bouncy Castle approved-only mode
177+
wrapper.java.additional.<n>=-Dorg.bouncycastle.fips.approved_only=true
178+
179+
# Required for Java 17+ module access
180+
wrapper.java.additional.<n>=--add-opens=java.base/sun.security.provider=org.bouncycastle.fips.core
181+
182+
# For Mule 4.9: set keystore type to BCFKS
183+
wrapper.java.additional.<n>=-Dmule.keystore.type=BCFKS
184+
----
185+
+
186+
. If you are using a clustered environment, also add the cluster encryption key:
187+
+
188+
----
189+
wrapper.java.additional.<n>=-Dmule.cluster.network.encryption.key={your-encryption-key}
190+
----
191+
+
192+
For more information about clustering in FIPS mode, see the Mule runtime documentation on high-availability clusters and FIPS.
193+
+
194+
. Save your changes and start Mule runtime.
195+
196+
When Mule launches, the startup logs show that FIPS 140-3 security mode is enabled. Mule automatically restricts protocol negotiations to use only approved cryptographic cipher suites.
197+
198+
[IMPORTANT]
199+
--
200+
Not all connectors are FIPS 140-3 compliant. Only connectors tagged as `fips-140-3-verified` in Anypoint Exchange are certified for use in FIPS 140-3 environments. Always verify compliance in Exchange before deploying.
201+
--
202+
203+
[[fips-140-3-compliant-cipher-suites]]
204+
== FIPS 140-3 Compliant Cipher Suites
205+
206+
These cipher suites are enabled by default when running Mule in FIPS 140-3 mode. Use these when planning or validating migrations from FIPS 140-2 or non-FIPS runtimes.
207+
208+
=== TLS 1.3 Cipher Suites
209+
210+
* TLS_AES_128_GCM_SHA256
211+
* TLS_AES_256_GCM_SHA384
212+
* TLS_AES_128_CCM_SHA256
213+
* TLS_AES_128_CCM_8_SHA256
214+
215+
=== TLS 1.2 Cipher Suites
216+
217+
* TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
218+
* TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
219+
* TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
220+
* TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
221+
* TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
222+
* TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
223+
* TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
224+
* TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
225+
* TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
226+
* TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
227+
* TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
228+
229+
[NOTE]
230+
--
231+
These cipher suites are configured in the `$MULE_HOME/conf/tls-fips140-3.conf` file. FIPS 140-3 requires support for TLS 1.3 and TLS 1.2. Earlier TLS versions are not supported.
232+
--
233+
234+
[[fips-140-3-compliant-keystore-formats]]
235+
== FIPS 140-3 Compliant Keystore Formats
236+
237+
Keystores or truststores in Mule apps are often formatted as `PKCS12` or `JKS`. These formats are not FIPS compliant. For compliance, convert them to `BCFKS` format:
238+
239+
. Download the `bc-fips-2.0.0.jar` file from the https://www.bouncycastle.org/download/bouncy-castle-java-fips/[Bouncy Castle website].
240+
. Use this example command to convert a keystore to `BCFKS` format:
241+
242+
----
243+
BC_FIPS_JAR=${BC_PATH}/bc-fips-2.0.0.jar # Replace with a correct path
244+
OLD_KEYSTORE="keystore.jks" # Replace with the keystore to convert
245+
OLD_PASSWD="changeit" # Replace with the keystore password
246+
NEW_KEYSTORE="keystore.bcfks" # Replace with the new keystore
247+
NEW_PASSWD="changeit" # Replace with the new keystore password
248+
249+
keytool -importkeystore \
250+
-providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \
251+
-providerpath ${BC_FIPS_JAR} \
252+
-srckeystore ${OLD_KEYSTORE} -srcstoretype JKS -srcstorepass ${OLD_PASSWD} \
253+
-destkeystore ${NEW_KEYSTORE} -deststoretype BCFKS -deststorepass ${NEW_PASSWD}
254+
----
255+
256+
[NOTE]
257+
If the source keystore is `PKCS12`, set `-srcstoretype` to `PKCS12` in the `keytool` command.
258+
259+
[start=4]
260+
. Update the TLS configuration in your Mule configuration file to use the new keystore or truststore:
261+
262+
----
263+
<tls:context>
264+
<tls:key-store type="bcfks" path="server.bcfks" password="changeit" keyPassword="changeit" alias="default" />
265+
<tls:trust-store type="bcfks" path="client.bcfks" password="changeit" />
266+
</tls:context>
267+
----
268+
269+
[[connectors-compatibility]]
270+
== Connectors Compatibility
271+
272+
Only connectors tagged as `fips-140-3-verified` in Anypoint Exchange are certified for use in FIPS 140-3 environments. To check compliance in Exchange before deploying:
273+
274+
. Open Anypoint Exchange.
275+
. Search for the connector.
276+
. Check for the `fips-140-3-verified` tag.
277+
278+
== Tips and Limitations
279+
280+
* Not all encryption schemes and signatures are FIPS 140-3 compliant. If your app uses a non-approved algorithm, you may see a runtime error such as:
281+
+
282+
....
283+
Could not find encryption algorithm '<algorithm-name>'.
284+
You are running in FIPS mode, so please verify that
285+
the algorithm is compliant with FIPS.
286+
....
287+
* Different environments can have different security configurations. Test before deploying to production.
288+
289+
== See Also
290+
291+
* xref:gov-cloud-security.adoc[Security in MuleSoft Government Cloud]
292+
* xref:index.adoc[Government Cloud Overview]

‎modules/ROOT/pages/index.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,7 @@ include::mq::partial$mq-in-govcloud.adoc[tag=mqSupportInGovCloud]
129129

130130
MuleSoft Government Cloud meets all FedRAMP security and compliance standards, and adheres to these additional security protocols:
131131

132-
* Federal Information Processing Standards (FIPS 140-3), for details refer to xref:mule-runtime::fips-140-3-compliance-support.adoc[FIPS 140-3 Compliance Support].
132+
* Federal Information Processing Standards (FIPS 140-3), for details refer to xref:gov-cloud-fips-140-3-support.adoc[FIPS 140-3 Compliance Support].
133133
* Transport Layer Security (TLS) 1.2 encryption
134134
* NIST 800-53
135135
* CIS benchmarks

0 commit comments

Comments
 (0)
⚡