Edge for Private Cloud on FIPS-enabled RHEL 8.X

This article contains details and instructions intended for Edge for Private Cloud customers utilizing version 4.53.00 or above, operating on FIPS-enabled RHEL 8.X.

Pre-install

Ensure that FIPS is enabled on your nodes in addition to the other standard configuration prerequisites listed in the Edge for Private Cloud documentation.

fips-mode-setup --check
FIPS mode is enabled.

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

Java requirements

The Java that you use should be downloaded from Red Hat’s repository to ensure that Java’s security modules are FIPS-aware and can implement FIPS-specific restrictions via Java security.

Installation

In the silent installation configuration file reference, set FIPS_OS=true on every node. You can follow the general installation steps for Edge for Private Cloud as usual.

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. Refer to Converting certificates to supported format for help in creating the file.

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 on relevant articles for TLS configuration to get more details. The appendix lists some helpful commands that can be used to generate these keystores.

Default Java keystore/truststore

When Edge for Private Cloud 4.53.00 or later is operated on FIPS-enabled RHEL 8.X, your message processor, management server, and other edge-* components rely on a default truststore and keystore shipped with the product. These contain CA certificates that your application will trust by default. If you would like to change this to your own store containing CA certificates, follow the procedure below:

1. Create a BCFKS format cacerts file that contains all the CA certificates that you want to trust. Ensure that the keystore password and key password are the same. Refer to the appendix for more details.
2. Place the file in an appropriate path and ensure it is readable by the apigee user:

   cp my-cacerts.bcfks /opt/apigee/customer/application/my-cacerts.bcfks
   chown apigee:apigee /opt/apigee/customer/application/my-cacerts.bcfks

3. Create (or edit) the appropriate configuration file based on the component you’re working with:

   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 file:

         conf_system_javax.net.ssl.trustStore=<PATH to bcfks cacerts>
         conf_system_javax.net.ssl.trustStorePassword=changeme
         conf_system_javax.net.ssl.keyStore=<PATH to bcfks cacerts>
         conf_system_javax.net.ssl.keyStoreType=BCFKS
         conf_system_javax.net.ssl.keyStorePassword=changeme
         

5. Ensure that the configuration file is owned by and readable by the apigee user:

   chown apigee:apigee $opt/apigee/customer/application/<file>.properties

6. Restart the component:

   /opt/apigee/apigee-service/bin/apigee-service  restart

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 the same as those generally run, but the following options need to be added to 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

Similar keytool 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.

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 would like to package it into a PKCS12, refer to Converting certificates to supported format.