diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 9d4aa9b98..a36ba052a 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -57,6 +57,7 @@ include::partial$nav-app-dev.adoc[] * xref:securing.adoc[Security] ** xref:secure-configuration-properties.adoc[Secure Configuration Properties] ** xref:fips-140-2-compliance-support.adoc[FIPS 140-2 Compliance Support] + ** xref:fips-140-3-compliance-support.adoc[FIPS 140-3 Compliance Support] ** xref:setting-up-ldap-provider-for-spring-security.adoc[Configure LDAP Provider for Spring Security] ** xref:component-authorization-using-spring-security.adoc[Component Authorization Using Spring Security] ** xref:tls-configuration.adoc[TLS Configuration] diff --git a/modules/ROOT/pages/fips-140-3-compliance-support.adoc b/modules/ROOT/pages/fips-140-3-compliance-support.adoc new file mode 100644 index 000000000..94758c581 --- /dev/null +++ b/modules/ROOT/pages/fips-140-3-compliance-support.adoc @@ -0,0 +1,193 @@ += FIPS 140-3 Compliance Support +ifndef::env-site,env-github[] +include::_attributes.adoc[] +endif::[] +:keywords: fips, certifications, security, fips-140-3 + +Configure Mule 4 to run in a Federal Information Processing Standard (FIPS) 140-3 certified environment. + +Mule doesn't run in FIPS security mode by default. To enable it, you must: + +* Install a certified cryptography module in your Java environment. +* Adjust Mule runtime settings to run in FIPS security mode. + +== Compatibility + +FIPS 140-3 support requires: + +* Mule 4.10 or later ++ +For earlier versions of Mule runtime, use xref:fips-140-2-compliance-support.adoc[FIPS 140-2 Compliance Support] which requires: +* Java 17 or later +* FIPS license from the license `.zip` file provided by MuleSoft (the non-FIPS license isn't valid for FIPS mode) + +== Assumptions + +This document assumes you're familiar with https://csrc.nist.gov/publications/detail/fips/140/3/final[FIPS 140-3], the US government security standard that requires that compliant parties use only cryptographic algorithms and techniques that have been certified by NIST. + +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. + +[[set_up_environment]] +== Installing Bouncy Castle Security Provider + +Mule runtime uses Bouncy Castle 2.0.0 as its FIPS 140-3 certified cryptography provider. + +=== Installation Steps + +These instructions show how to install and configure Bouncy Castle security provider in Java 17 or later. + +. Verify that you're using Java 17 or later and `JAVA_HOME` is set. +. Download the Bouncy Castle 2.0.0 provider files from https://www.bouncycastle.org/fips-java/[the BouncyCastle website]. +. Copy the required JAR files to the `$MULE_HOME/lib/boot` folder: ++ +---- +bc-fips-2.0.0.jar +bctls-fips-2.0.19.jar +bcpkix-fips-2.0.7.jar +bcutil-fips-2.0.3.jar +bcpg-fips-2.0.9.jar +bcjmail-fips-2.0.5.jar +---- ++ +. Configure the security providers in the `$JAVA_HOME/conf/security/java.security` file: ++ +---- +security.provider.1=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider +security.provider.2=org.bouncycastle.jsse.provider.BouncyCastleJsseProvider fips:BCFIPS +security.provider.3=SUN +---- ++ +. Configure the key manager and trust manager algorithms in the same `java.security` file: ++ +---- +ssl.KeyManagerFactory.algorithm=PKIX +ssl.TrustManagerFactory.algorithm=PKIX +---- + +== Running Mule in FIPS Security Mode + +After installing the Bouncy Castle provider, configure Mule to run in FIPS 140-3 mode: + +. Open your `wrapper.conf` file (located in `$MULE_HOME/conf`). +. Add these properties. Replace `` with the next sequential number in your file: ++ +---- +# Enable FIPS 140-3 security mode +wrapper.java.additional.=-Dmule.security.model=fips140-3 + +# Enable Bouncy Castle approved-only mode +wrapper.java.additional.=-Dorg.bouncycastle.fips.approved_only=true + +# Required for Java 17+ module access +wrapper.java.additional.=--add-opens=java.base/sun.security.provider=org.bouncycastle.fips.core +---- ++ +. If you're using a clustered environment, also add the cluster encryption key: ++ +---- +wrapper.java.additional.=-Dmule.cluster.network.encryption.key={your-encryption-key} +---- ++ +For more information about clustering in FIPS mode, see xref:mule-high-availability-ha-clusters.adoc#cluster_fips[Cluster reference]. ++ +. Save your changes and start Mule runtime. + +[NOTE] +-- +Starting with Mule 4.10, BCFKS is the default keystore type. Setting `mule.keystore.type=BCFKS` in your `wrapper.conf` file isn't required. +-- + +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. + +[IMPORTANT] +-- +Not all connectors are FIPS 140-3 compliant. Only connectors tagged as `fips-140-3-verified` in Anypoint Exchange are certified to use in FIPS 140-3 environments. Always verify compliance in Exchange before deploying. +-- + +== FIPS 140-3 Compliant Cipher Suites + +These cipher suites are enabled by default when running Mule in FIPS 140-3 mode. + +=== TLS 1.3 Cipher Suites + +* TLS_AES_128_GCM_SHA256 +* TLS_AES_256_GCM_SHA384 +* TLS_AES_128_CCM_SHA256 +* TLS_AES_128_CCM_8_SHA256 + +=== TLS 1.2 Cipher Suites + +* TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 +* TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 +* TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 +* TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 +* TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 +* TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 +* TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 +* TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA +* TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA +* TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA +* TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA + +[NOTE] +-- +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 aren't supported. +-- + +== FIPS 140-3 Compliant Keystore Formats + +Keystores or truststores in Mule apps are usually formatted as `PKCS12` or `JKS`. These formats aren't FIPS compliant. For compliance, convert them to `BCFKS` format: + +. Download the `bc-fips-2.0.0.jar` file from the https://www.bouncycastle.org/download/bouncy-castle-java-fips/[Bouncy Castle website]. +. Use this example command to convert a keystore to `BCFKS` format: + +---- +BC_FIPS_JAR=${BC_PATH}/bc-fips-2.0.0.jar # Replace with a correct path +OLD_KEYSTORE="keystore.jks" # Replace with the keystore to convert +OLD_PASSWD="changeit" # Replace with the keystore password +NEW_KEYSTORE="keystore.bcfks" # Replace with the new keystore +NEW_PASSWD="changeit" # Replace with the new keystore password + +keytool -importkeystore \ + -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \ + -providerpath ${BC_FIPS_JAR} \ + -srckeystore ${OLD_KEYSTORE} -srcstoretype JKS -srcstorepass ${OLD_PASSWD} \ + -destkeystore ${NEW_KEYSTORE} -deststoretype BCFKS -deststorepass ${NEW_PASSWD} +---- + +[NOTE] +If the source keystore is `PKCS12`, set `-srcstoretype` to `PKCS12` in the `keytool` command. + +[start=4] +. Update the xref:tls-configuration.adoc[TLS configuration] in the Mule configuration file to use the new keystore or truststore: + +---- + + + + +---- + +== Connectors Compatibility + +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: + +. Open Anypoint Exchange. +. Search for the connector. +. Check for the `fips-140-3-verified` tag. + +== Tips and Limitations + +* Not all encryption schemes and signatures are FIPS 140-3 compliant. If your app uses a non-approved algorithm, you get this runtime error: +.... + Could not find encryption algorithm ''. + You are running in FIPS mode, so please verify that + the algorithm is compliant with FIPS. +.... +* Different environments can have different security configurations. Test before deploying to production. + +== See Also + +* https://csrc.nist.gov/projects/cryptographic-module-validation-program/validated-modules[Validated FIPS-3 Cryptographic Modules] +* https://csrc.nist.gov/publications/detail/fips/140/3/final[FIPS 140-3 Standard] +* xref:fips-140-2-compliance-support.adoc[FIPS 140-2 Compliance Support]