Configuring TLS/SSL for Edge On Premises
Edge for Private Cloud v. 4.17.01
TLS (Transport Layer Security, whose predecessor is SSL) is the standard security technology for for ensuring secure, encrypted messaging across your API environment, from apps to Apigee Edge to your back-end services.
Because Edge originally supported SSL, you will see some instances in the Edge UI, Edge XML, and Edge properties that use the term "SSL". For example, the menu entry in the Edge UI that you use to view certs is called SSL Certificates, the XML tag that you use to configure a virtual host to use TLS is named <SSLInfo>, and the property to set the SSL port for the management API is conf_webserver_ssl.port.
Regardless of the environment configuration for your management API—for example, whether you’re using a proxy, a router, and/or a load balancer in front of your management API (or not)— Edge lets you enable and configure TLS, giving you control over message encryption in your on-premise API management environment.
For an on-premises installation of Edge Private Cloud, there are several places where you can configure TLS:
- Between a Router and Message Processor
- For access to the Edge management API
- For access to the Edge management UI
- For access from an app to your APIs
- For access from Edge to your backend services
Configuring TLS for the first three items is described below. All of these procedures assume that you have created a JKS file containing your TLS certification and private key.
To configure TLS for access from an app to your APIs, #4 above, see Configuring TLS access to an API for the Private Cloud. To configure TLS for access from Edge to your backend services, #5 above, see Configuring TLS from Edge to the backend (Cloud and Private Cloud).
For a complete overview of configuring TLS on Edge, see TLS/SSL.
Creating a JKS file
You represent the keystore as a JKS file, where the keystore contains your TLS certificate and private key. There are several ways to create a JKS file, but one way is to use the openssl and keytool utilities.
If you have a certificate chain, all certs in the chain must be appended in order into a single PEM file, where the last certificate is signed by a CA.
For example, you have a PEM file named server.pem containing your TLS certificate and a PEM file named private_key.pem containing your private key. Use the following commands to create the PKCS12 file:
> openssl pkcs12 -export -clcerts -in server.pem -inkey private_key.pem -out keystore.pkcs12
You have to enter the passphrase for the key, if it has one, and an export password. This command creates a PKCS12 file named keystore.pkcs12.
Use the following command to convert it to a JKS file named keystore.jks:
> keytool -importkeystore -srckeystore keystore.pkcs12 -srcstoretype pkcs12 -destkeystore keystore.jks -deststoretype jks
You are prompted to enter the new password for the JKS file, and the existing password for the PKCS12 file.
If you have to specify a key alias, such as when configuring TLS between a Router and Message Processor, include the "-name" option to the openssl command:
> openssl pkcs12 -export -clcerts -in server.pem -inkey private_key.pem -out keystore.pkcs12 -name devtest
Then include the "-alias" option to the keytool command:
> keytool -importkeystore -srckeystore keystore.pkcs12 -srcstoretype pkcs12 -destkeystore keystore.jks -deststoretype jks -alias devtest
Generating an obfuscated password
Some parts of the Edge TLS configuration procedure require you to enter an obfuscated password in a configuration file. An obfuscated password is a more secure alternative to entering your password in plain text.
You can generate an obfuscated password in Java by using the Jetty .jar files installed with Edge. enerate the obfuscated password by using a command in the form:
> java -cp /<inst_root>/apigee/edge-gateway/lib/thirdparty/jetty-http-x.y.z.jar:/<inst_root>/apigee/edge-gateway/lib/thirdparty/jetty-util-x.y.z.jar org.eclipse.jetty.http.security.Password yourPassword
where x.y.z specifies the version number of the Jetty .jar files, such as 8.0.4.v20111024. This command returns the password in the form:
yourPassword OBF:58fh40h61svy156789gk1saj MD5:902fobg9d80e6043b394cb2314e9c6
Use the obfuscated password specified by OBF when configuring TLS.
For more information, see this article.
Help or comments?
- If something's not working: Ask the Apigee Community or see Apigee Support.
- If something's wrong with the docs: Send Docs Feedback
(Incorrect? Unclear? Broken link? Typo?)