This section provides guidance on enabling FIPS mode on RHEL 8, ensuring a secure and compliant environment for Edge for Private Cloud versions 4.53.00 or higher. ## Pre-install Ensure that FIPS is enabled on your nodes along with the other standard configuration prerequisites listed in the [Edge Installation Overview](https://docs.apigee.com/private-cloud/v4.53.00/installation-overview) documentation. ``` fips-mode-setup --check FIPS mode is enabled. # Command output ``` If FIPS mode is currently disabled, refer to the official Red Hat documentation for instructions on how to enable it: [Switching RHEL 8 to FIPS mode](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/8/html/security_hardening/switching-rhel-to-fips-mode_security-hardening#federal-information-processing-standards-140-and-fips-mode_switching-rhel-to-fips-mode). ### Java requirements The Java you use should be downloaded from Red Hat's repository to ensure that its security modules are FIPS-compliant, enabling FIPS-specific restrictions through Java security. ## Installation In the [Edge Configuration File Reference](https://docs.apigee.com/private-cloud/v4.53.00/edge-configuration-file-reference), set `FIPS_OS=true` on each node. You can follow the general installation steps for Edge for Private Cloud as usual. > [!NOTE] > **Note:** For Edge for Private Cloud 4.53.00, you can only set up a new cluster on a FIPS-enabled RHEL 8.X OS. In-place upgrades are not supported. If you are currently using an older version of Edge for Private Cloud on a FIPS-enabled RHEL 7 (or a similar OS), directly upgrading to Edge for Private Cloud 4.53.00 on a FIPS-enabled RHEL 8.X is not possible. > [!NOTE] > **Note:** If you have an existing installation of Edge for Private Cloud and want to set up Edge for Private Cloud 4.53.00 on a FIPS-enabled RHEL 8.X OS, follow these steps: > > 1. Follow the [fresh installation instructions](https://docs.apigee.com/private-cloud/v4.53.00/install-edge-apigee-setup-utility) to create a new cluster of Edge for Private Cloud 4.53 or later on a FIPS-enabled RHEL 8.X system. > 2. Use management APIs to import data, such as proxies and KVMs, from your existing cluster. > 3. Use management APIs to export the previously imported data into the new cluster of Edge for Private Cloud 4.53 or later on the FIPS-enabled RHEL 8.X system. ## Private key format Only PKCS12/PFX format can be used to upload private keys to Apigee keystores for use in your API proxies or virtual hosts. For guidance on creating the file, refer to [Converting certificates to supported format](https://docs.apigee.com/how-to-guides/converting-certificates-to-supported-format#packaging-pem-key-and-certificate-files-into-pkcs12pfx). ## General TLS operations When using Edge for Private Cloud 4.53.00 or later on FIPS-enabled RHEL 8.X, most TLS-related component configurations of Edge will need to be done via PKCS12 or BCFKS format keystores. Refer to FIPS-specific documentation or notes in relevant articles for TLS configuration to get more details. The [appendix](https://docs.apigee.com/private-cloud/v4.53.00/fips-considerations-rhel-8#appendix) lists some helpful commands that can be used to generate these keystores. ## Default Java keystore/truststore When you use Edge for Private Cloud 4.53.00 on FIPS-enabled RHEL 8.X, your Message Processor, Management Server, and other `edge-*` components point by default to a placeholder BCFKS keystore and truststore (`/opt/apigee/edge-gateway/vault/bcfks-cacerts`) shipped with the product. > [!CAUTION] > **Important:** The `/opt/apigee/edge-gateway/vault/bcfks-cacerts` file shipped with the product is a placeholder. Do not use `/opt/apigee/edge-gateway/vault/bcfks-cacerts` as-is. For security and for your components to trust external or internal CA certificates, you must generate your own BCFKS `cacerts` store and configure your Edge components to use it. To generate your own BCFKS `cacerts` store and configure your Edge components to use it, follow these steps: 1. Generate your own BCFKS format `cacerts` file containing all the CA certificates that you want to trust. Ensure that the keystore password and key password are the same (and at least 14 characters if strict BCFIPS password checks apply). - **Option A:** Convert the host OS or JDK `cacerts` store into BCFKS format (recommended if you want to include the standard OS trusted root CAs managed by `update-ca-trust`): BC_FIPS_JAR=$(ls /opt/apigee/edge-gateway/lib/thirdparty/bc-fips-*.jar \ | head -n 1) keytool -J-Dcom.redhat.fips=false -importkeystore \ -srckeystore /etc/pki/java/cacerts \ -srcstoretype JKS \ -srcstorepass changeit \ -destkeystore my-cacerts.bcfks \ -deststoretype BCFKS \ -deststorepass YOUR_STORE_PASSWORD \ -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \ -providername BCFIPS \ -providerpath "$BC_FIPS_JAR" \ -noprompt - **Option B:** Create a new BCFKS store with custom CA certificates (`.pem` or `.crt`), or import additional custom CA certificates into an existing BCFKS store (such as `my-cacerts.bcfks` from Option A): BC_FIPS_JAR=$(ls /opt/apigee/edge-gateway/lib/thirdparty/bc-fips-*.jar \ | head -n 1) keytool -J-Dcom.redhat.fips=false -importcert \ -file PATH_TO_CA_CERT.pem \ -alias CA_ALIAS \ -keystore my-cacerts.bcfks \ -storetype BCFKS \ -storepass YOUR_STORE_PASSWORD \ -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \ -providername BCFIPS \ -providerpath "$BC_FIPS_JAR" \ -noprompt - **Optional:** Verify the contents of your BCFKS store: BC_FIPS_JAR=$(ls /opt/apigee/edge-gateway/lib/thirdparty/bc-fips-*.jar \ | head -n 1) keytool -J-Dcom.redhat.fips=false -list \ -keystore my-cacerts.bcfks \ -storetype BCFKS \ -storepass YOUR_STORE_PASSWORD \ -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \ -providername BCFIPS \ -providerpath "$BC_FIPS_JAR" > [!NOTE] > **Note:** Pass `-J-Dcom.redhat.fips=false` to `keytool` so that OpenJDK's default Red Hat NSS FIPS hook does not block `keytool` from using the BouncyCastle FIPS (`BCFIPS`) provider or reading `/etc/pki/java/cacerts` on a FIPS-enabled RHEL 8 node. 2. On each node running any of the Edge components listed in Step 3, copy the BCFKS file to an appropriate path and ensure that the `apigee` user can read it: cp my-cacerts.bcfks /opt/apigee/customer/application/my-cacerts.bcfks chown apigee:apigee /opt/apigee/customer/application/my-cacerts.bcfks chmod 600 /opt/apigee/customer/application/my-cacerts.bcfks 3. On each node, create or edit the configuration file for each installed component from the following table (repeating Steps 3--6 for each listed component on the node): | Component | File | |---|---| | `edge-management-server` | `/opt/apigee/customer/application/management-server.properties` | | `edge-message-processor` | `/opt/apigee/customer/application/message-processor.properties` | | `edge-router` | `/opt/apigee/customer/application/router.properties` | | `edge-postgres-server` | `/opt/apigee/customer/application/postgres-server.properties` | | `edge-qpid-server` | `/opt/apigee/customer/application/qpid-server.properties` | 4. Add the following lines to the configuration file: ``` conf_system_javax.net.ssl.trustStore=/opt/apigee/customer/application/my-cacerts.bcfks conf_system_javax.net.ssl.trustStorePassword=YOUR_STORE_PASSWORD conf_system_javax.net.ssl.keyStore=/opt/apigee/customer/application/my-cacerts.bcfks conf_system_javax.net.ssl.keyStoreType=BCFKS conf_system_javax.net.ssl.keyStorePassword=YOUR_STORE_PASSWORD ``` Replace `/opt/apigee/customer/application/my-cacerts.bcfks` and `YOUR_STORE_PASSWORD` with the path and password for your BCFKS `cacerts` file. 5. Ensure that the `apigee` user owns and can read the configuration file: ``` chown apigee:apigee /opt/apigee/customer/application/FILE.properties ``` 6. Restart the component: ``` /opt/apigee/apigee-service/bin/apigee-service COMPONENT restart ``` > [!NOTE] > **Note:** You must also restart the component any time you add, remove, or update certificates in your BCFKS file, because the component loads the keystore and truststore into memory only at JVM startup. ## Appendix ### BCFKS keystore operation sample commands The command below generates a BCFKS keystore with a self-signed key and certificate pair: ``` keytool -genkeypair -keyalg RSA -alias node0 -validity 365 -keystore keystore.node0 \ -storepass keypass -keypass keypass -v \ -dname "EMAILADDRESS=youremail@domain.com, CN=yourcn, OU=yourou, O=youro, L=yourl, C=yourc" \ -storetype BCFKS -providerpath /opt/apigee/edge-gateway/lib/thirdparty/bc-fips-1.0.2.4.jar \ -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providername BCFIPS ``` Keytool commands remain consistent with those typically used, but the following options must be included in the keytool command: ``` --storetype BCFKS -providerpath /opt/apigee/edge-gateway/lib/thirdparty/bc-fips-1.0.2.4.jar -providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providername BCFIPS ``` ### Keytool Arguments | Keytool Argument | Description | |---|---| | `-storetype` | Set the store type to `BCFKS`. | | `-providerpath` | Specify the path to `bc-fips-XXXX.jar`. This version may change in future OPDK releases. Use the version shipped by Apigee or download it from Bouncycastle's repositories. For OPDK 4.53, the path should be `/opt/apigee/edge-gateway/lib/thirdparty/bc-fips-1.0.2.4.jar`. | | `-providerclass` | Set this to `org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider`. | | `-providername` | Set this to `BCFIPS`. | Similar [keytool](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html) commands can be used to import or export certificates and/or keys from or to a BCFKS format keystore. For more information on how to work with BCFKS, check the [BouncyCastle documentation](https://www.bouncycastle.org/documentation). ### PKCS12 Store To generate a PKCS12 store, `openssl` commands can be used: ``` # Generate a self-signed private key and certificate openssl req -x509 -newkey rsa:2048 -keyout private.key -out certificate.pem -sha256 -days 36500 -nodes -subj "/C=yourc/ST=yourst/L=yourl/O=youro/OU=yourou/CN=cn/emailAddress=email" # Package the above generated key and cert into a PKCS12 openssl pkcs12 -export -clcerts -in certificate.pem -inkey private.key -out keystore.pfx -name myalias ``` If you have your own private key and certificate and need to convert them into a PKCS12 format, refer to [Converting certificates to supported format](https://docs.apigee.com/how-to-guides/converting-certificates-to-supported-format#packaging-pem-key-and-certificate-files-into-pkcs12pfx).