Establishing secure connections between API boundaries is something that most companies (if not all) will be concerned about during the implementation of API-based projects. This is important whether if you are exposing APIs for consumption or if you are invoking existing APIs. In order to establish secure connections, SSL certificates are the most well known practice used to ensure data confidentiality. However; importing SSL certificates into the API Gateway has proven itself to be a tedious - often error prone practice - that most administrators/developers struggle with.
Starting from release 18.1.3, the API Platform Gateway provides a easy-to-use utility that aims to minimize the struggle during the import of SSL certificates. This utility is called SSLCertUtility, and it can be found within the installer contents of the API Gateway. Thus; in order to get this utility, you need to download the API Gateway installer from the API Platform Management Portal...
... and thereafter extracting its contents to a directory:
The intention of this blog is to show how to use this utility to import SSL certificates; that in turn will be used to secure connections from the API Gateway to any backend service exposed with that certificate. By using this utility, you might solve errors related to establishing connections through SSL when the certificate is not installed (or it is not installed correctly) such as errors related to SSL handshake.
To showcase how this utility works, we are going to demonstrate how to import the SSL certificate from Fidelity. Open a new terminal and navigate to the directory where you extracted the API Gateway installer contents. Then, you can execute the utility SSLCertUtility as shown below:
As you can see, the utility is very straightforward. The red arrows shown in the picture above highlight what should be the user input. Once you provide all the requested inputs, you should see the following output:
[INFO] JAVA_HOME being used by the tool is: /oracle/jdk1.8.0_161 [INFO] Executing tool. Output as follows: The Keystore File has been backed up to location file:///oracle/jdk1.8.0_161/jre/lib/security/cacerts.backup.2018-02-21_03-29-44 Issuer: CN=Entrust Root Certification Authority - G2, OU="(c) 2009 Entrust, Inc. - for authorized use only", OU=See www.entrust.net/legal-terms, O="Entrust, Inc.", C=US SN: 30215777750102225331854468774 SHA-1 Thumbprint : cc136695639065fab47074d28c55314c66077e90 Basic Contraint 0 Name: CN=Entrust Certification Authority - L1M,OU=(c) 2014 Entrust\, Inc. - for authorized use only,OU=See www.entrust.net/legal-terms,O=Entrust\, Inc.,C=US DN = CN=Entrust Certification Authority - L1M,OU=(c) 2014 Entrust\, Inc. - for authorized use only,OU=See www.entrust.net/legal-terms,O=Entrust\, Inc.,C=US CN = Entrust Certification Authority - L1M Alias Name created EntrustCertificationAuthority-L1M30215777750102225331854468774 Adding Certificate having CN CN=Entrust Certification Authority - L1M,OU=(c) 2014 Entrust\, Inc. - for authorized use only,OU=See www.entrust.net/legal-terms,O=Entrust\, Inc.,C=US with alias EntrustCertificationAuthority-L1M30215777750102225331854468774
The utility makes sure to create a backup of your key store file before doing any changes. The backup is created in the same directory that holds the key store file that you have provided, and it is suffixed with the ".backup" extension. This gives you the ability to revert anything that goes wrong during the SSL certificate import. Also, all the details of the import are shown step-by-step, since we have specified that we want to run the tool in debug mode. This is quite useful if you want to understand which certificate (server, intermediate or root) is causing the issue when the import fails.
When you provide the URL of the server that contains the SSL certificate; the utility makes sure to fetch all the certificates necessary automatically, and in the proper format. This eliminates the manual step of capturing the certificates through a browser. This manual step is often seen as error prone because there are multiple ways to do the same thing, as a consequence of using different browsers. You may be well versed while using Google Chrome, but while using Firefox you may have some difficulties. For this reason, the utility takes care of capturing the certificate(s) for you.
It is your responsibility to specify which key store file to use. When requested, you have to specify the location where your key store file resides. Make sure to provide the exact key store file that belongs to the JDK being used by your API Gateway. Otherwise, the utility may import the certificate(s) successfully but there will be no effect in runtime during API calls. This is particularly true if you have multiple JDK installs. To be on the safe side, always check which JDK the API Gateway is using before running this utility. As you may have noticed as well, you are responsible for providing the password that will be used to handle the key file store. Usually the default password of any fresh JDK install is changeit, but you may need to provide a different one if someone has changed the password.
After specifying the key store details, your are requested to specify which certificate type you are interested. It is important to understand the options available so you can better inform the utility about your intentions. There are three options available:
- CA: Means "CA Certificate Chain", and should be used when your intention is to import the intermediate and root certificates.
- IM: Means "Intermediate", and should be used when your intention is to import the intermediate certificate only.
- SS: Means "Self-Signed", and should be used when your intention is to import the intermediate, root and server certificates.
The "SS" option should be pretty common in Development and QA scenarios, where people are accessing backend services that sit behind load balancers that uses self-signed certificates. OTD (Oracle Traffic Director) is a good example of load balancer that by default comes with self-signed certificate that needs to be imported in the API Gateway to allow the traffic. This is true even if you are trying to access a OTD instance that was provisioned by the Oracle Cloud, such as an OTD instance from Java Cloud Service or SOA Cloud Service.
The utility also provides an option to specify aliases for each certificate imported. After specifying the certificate type, the utility will know which certificates you are interested to import. For example, if you chose "CA", then immediately after that the utility will ask the following questions:
- "Do you have an alias for root certificate [y/n]?"
- "Do you have an alias for intermediate certificate [y/n]?"
if you intend to specify an alias for a given certificate (root, intermediate or server) then you need to answer "y" for the respective question. When you do this, the utility will subsequently ask the following question:
- "What is the alias for the <CERTIFICATE_TYPE> certificate?"
Simply type the alias you want to provide and hit enter. The alias is a plain string but with no spaces and preferably with no special characters. Keep in mind that you will have to do this for each question that you gave "y" as an answer. Also, providing an alias while importing certificates is not a mandatory step but rather, a best practice. If you don't provide one, an machine-generated alias will be created for you. By definition; an alias is just a handle to a key/pair or a certificate, so if you ever need to modify one that has been imported before - you can reference it using an alias that is understandable by humans.
The utility needs to have outbound internet connection to be able to fetch the certificate(s) from the URL provided. Therefore, it is up to you making sure that there is connectivity. If you are running the utility from an environment that usually don't provide outbound internet connection (such as Data Centers or Cloud Machines) you won't be able to run the utility correctly. A common way to overcome this limitation is using network proxies when available. If you need to use network proxies while running the utility, make sure to answer "y" to the following question:
- "Do you need a proxy to connect to server [y/n]?"
If your answer is "y", then the utility will subsequently ask the following questions:
- "What is the proxy host ?"
- "What is the proxy port ?"
The value of the proxy host must be a valid address that points to your network proxy. The utility won't infer if the network proxy is SSL-based or not, so you have to provide the appropriate protocol prefix (HTTP or HTTPS) before the address. The port must be a valid, non-negative number. Usually, it is 80 for HTTP-based network proxies or 443 if it is HTTPS. Make sure to provide the correct values for the network proxy host and port, otherwise the utility will fail.
This blog have shown how to leverage the SSLCertUtility to import SSL certificates. This utility was introduced in the 18.1.3 release of the API Platform Gateway, and certainly provides a very handy way to import SSL certificates. This blog doesn't intend to be a replacement for the official documentation but rather, a public reference of how to use the utility with a hands-on example.