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.
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:
- 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.
-
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
-
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 -
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
-
Ensure that the configuration file is owned by and readable by the apigee user:
chown apigee:apigee $opt/apigee/customer/application/<file>.properties
-
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
| Keytool Argument | Description |
|---|---|
| -storetype | Store type is BCFKS. |
| -providerpath | Path to bc-fips-XXXX.jar. The version of this jar may change in future OPDK versions. Whatever version is shipped by Apigee should be used. You can also download the jar from Bouncycastle’s repositories. As of release of OPDK 4.53, this should be /opt/apigee/edge-gateway/lib/thirdparty/bc-fips-1.0.2.4.jar. |
| -providerclass | Should be set to org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider. |
| -providername | Should be set to BCFIPS. |
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.