understanding SSL implementation for wasp probe

Products

• DX Unified Infrastructure Management (Nimsoft / UIM)

Issue/Introduction

This article is intended to serve as a deeper explanation of the documented process for installing an authority-signed SSL certificate on the wasp probe for UMP/OC and Admin Console, including renewal of certificates.
 
The documentation for implementing new certificates can be found here:
https://techdocs.broadcom.com/us/en/ca-enterprise-software/it-operations-management/unified-infrastructure-management/20-4/installing/optional-post-installation-tasks/configure-https-in-admin-console-or-ump.html 
 
In this article we will focus on implementing/renewing Authority-Signed certificates as this is the most common use case for our customers; however, the information here is generally applicable to self-signed certificates as well.
 

The high-level steps, as documented above, are:

1. Enable HTTPS on the wasp probe by setting an HTTPS port
2. Reinitialize the wasp keystore
3. Generate a Public and Private Key Pair
4. Generate and submit a Certificate Signing Request (CSR) and Receive a certificate or set of certificates from a Certificate Authority in return
5. Import the certificate(s) to the wasp keystore

 
We will explore each of these steps here to provide a greater of what is actually happening during each step of the process.
 

Environment

UIM 9.x or later

Resolution

Enable HTTPS on the wasp probe by setting an HTTPS port

This step is relatively self-explanatory, but it’s useful to understand exactly what’s going on under the hood.  
Ordinarily, the wasp probe is configured only to listen for HTTP requests, on port 80 by default (configurable by http_port key in wasp.cfg).  
Adding the https_port key to the config and assigning a value (e.g. 443) causes two things to happen:

1.    The probe begins listening on the assigned port for encrypted HTTPS connections.
2.    A self-signed SSL certificate is automatically generated and stored in the wasp.keystore file (located under /probes/service/wasp/conf on the UMP/Admin Console robot.)

An SSL certificate must be present for any HTTPS connection to succeed, and in this case the automatically generated self-signed certificate allows HTTPS connections to be successfully made to the server (although most browsers will issue a security warning.) 
In order to proceed with implementing an authority-signed certificate, we need to replace this self-signed certificate with the one we want to use.  Which brings us to the next step:

Reinitialize the wasp keystore
The wasp keystore is a file which holds the certificate information, including the public/private key pairs associated with the certificate.  It can be thought of as a “storage area” for the security and certificate information.

When you initially implement HTTPS on wasp by adding the https_port key, the keystore password is randomized and not recorded, so it must be reset to a known value in order to be able to manipulate the contents.

This is the main purpose of the ssl_reinitialize_keystore callback on the wasp probe – to define a new password for the keystore, which will be associated with the keystore itself and also encrypted into the wasp.cfg so the wasp can access it.  Without a known password, certificates cannot be imported or renewed. Therefore, it is very important that you remember/securely record this password for future use.   If you need to change this password, you must use the ssl_reinitialize_keystore callback to generate a new keystore and password.

Generate a public and private key pair
Once you have initialized the keystore, the next step is to generate a public and private key pair.  This is the step in the documentation where you use the java keytool along with the “-genkeypair” command.

First – a brief note on a public/private key pair and what this represents.  You can think of this, in a way, as creating a “fingerprint” unique to your keystore and instance of wasp.  This “fingerprint” will be included in the request you submit to your Certificate Authority and the certificate they provide will essentially be created based on that fingerprint.  Later, when HTTPS requests are made, the certificate fingerprint will be validated by the browser to ensure the identity of the server matches what is expected.
Therefore, the keytool commands we perform in this section accomplish the following:

“-delete -alias wasp”  -- this deletes the existing self-signed certificate that was generated on initialization of the keystore.
“-genkeypair” – this generates a new “fingerprint” in the keystore.  You will be prompted to enter the relevant details for your server and organization, but most importantly when asked to “enter your first and last name” you should actually enter server+domain name for which the certificate will be requested.  (e.g. www.example.com )

Now that you have generated a new key pair, you can issue a Certificate Signing Request (CSR), which is a request for your Certificate Authority to provide an SSL certificate for the server which is represented by this specific key pair/fingerprint.

Generate and submit a CSR and Receive a certificate or set of certificates from a Certificate Authority in return 

At this point we use the -certreq command with keytool to generate a .CSR file.  This process is fairly self-explanatory – essentially we are generating a small file which contains the public key information contained within the keypair we just created.  Generally speaking, most (if not all) Certificiate Authorities have a relatively easy-to-use interface for purchasing new SSL certificates which involves submitting the .CSR file (often by pasting it into a browser window.)  You should consult with the Certificate Authority of your choice for details on this process if needed.

Generally speaking, after submitting your CSR (and appropriate payment), the Certificate Authority will allow you to download one or more certificate files in various formats.

There may be several certificates, identified as “root” certificates, “chain” or “intermediate” certificates, and a “signed” or “entity” certificate.  It’s best to download all of these certificates in either .CER or .CRT format if your Certificate Authority allows this; otherwise if you are given something different like a .PFX file it may be necessary to convert this to .CER or .CRT – instructions for doing so are widely available online.

Once you have downloaded the .CER or .CRT files, you will move on to importing them.

Import the certificate(s) to the wasp keystore

Importing the certificates using the -import command on the keystore tool is a relatively straightforward process, but it may be helpful to understand what these certificates really do and why we import them the way we do.

A root certificate is a certificate that is signed with the public key of a valid Certificate Authority.  This certificate is used to verify that a certificate was issued by the issuer that is listed on the certificate – the public key used to sign the certificate provided by the Certificate Authority must match the public key in that Authority’s root certificate.

In many cases, the root certificate for most major Certificate Authorities will already exist in an operating-system level or browser-level keystore but we need to import it into the wasp’s own keystore so that we can check the validity of the certificate being used.

An intermediate or chain certificate may not be provided by all Certificate Authorities; some do not bother with this step.  An intermediate certificate serves as a sort of “middleman” in terms of authenticating the validity of a certificate.  Instead of using the public key of a root certificate to sign issued certificates, a Certificate Authority may use the public key of an intermediate certificate, which was in turn generated using the public key of the root certificate.  The signed certificate is then verified against the intermediate certificate which in turn is verified against the root certificate.

For our purposes, the only thing we need to worry about here is whether or not our chosen Certificate Authority provides an intermediate certificate or not.  If they do, we need to import it, after importing the root certificate.  If not, then we don’t need to worry about it.

A signed or entity certificate is the actual certificate file which is unique to an individual signing request – it’s the SSL certificate which identifies the site itself.   This is the certificate which we assign the alias “wasp” and must be imported last.

Renewing an existing certificate

With the above in mind, renewing an existing certificate is a very simple process as long as you have securely recorded/remembered your keystore password from the initial setup process.

To replace an existing certificate, all we need to do is obtain a new .CER or .CRT file which was signed by the existing public key and import it, overwriting the existing certificate.

If you obtained your new certificate by simply going to your Certificate Authority and paying for a renewal (or receiving an auto-renewal) then you should have been provided a new .CER or .CRT file without needing to submit a new CSR – this would simply be a new copy of your existing certificate but with a new expiration date.

To import this file, all we need to do is follow the very last step of creating a new certificate – use keytool to import the new certificate under the “wasp” alias:

1.    Copy the .cer/.crt file to the wasp/conf folder.
2.    use the keytool to import the certificate:

<UMP or UIM server_installation>/jre/<jre_version>/bin/keytool  -import  -trustcacerts  -alias wasp  -file <your_domain>.crt  -keystore <UMP or UIM server_installation>Nimsoft/probes/service/wasp/conf/wasp.keystore

You will be prompted that the alias “wasp” exists, and asked if you would like to overwrite?  Reply “Yes” here to replace the expired certificate with the new one, and provide the keystore password when prompted to do so.

That’s all there is to a renewal – restart wasp and the new certificate will be in place.