Domain name and TLS certificates

Domain name requirements

If Guardium® Insights is installed on IBM Cloud® or Amazon Web Services (AWS), the FQDN of the Red Hat® OpenShift® Container Platform cluster will be used with the TLS certificate for the platform FQDN. In this case, it is optional to create an FQDN.

If Guardium Insights is not installed on IBM Cloud or AWS, you must create a unique FQDN for Guardium Insights. The FQDN must not be the same as the OpenShift Container Platform cluster FQDN, the IBM Cloud Pak® foundational services FQDN, or any other FQDN associated with the OpenShift Container Platform cluster. To create a unique FQDN, ensure that a local Domain Name System (DNS) server is configured and available. You must create an entry for the FQDN of the OpenShift Container Platform cluster in your DNS server. The FQDN can be created by using one of these record types:

• An A record pointing to the IP address of the cluster.
• A CNAME record pointing to the cluster hostname.

To retrieve the hostname for your OpenShift Container Platform cluster, log in to the cluster with oc login and then get the hostname with this command:

oc get routes console -n openshift-console -o jsonpath='{.spec.host}'

This is an example of the output:

console-openshift-console.apps.cp4s-cluster1.example.com

To verify that the FQDN you created is resolving correctly to provide your cluster hostname or IP address, you can use https://dnschecker.org/. Alternatively, you can use the dig command-line tool. Check that the answer section of the output of the following command provides the FQDN you created:

dig <fqdn-you-created>

Certificate requirements

The TLS certificates must adhere to these requirements:

• The TLS certificate must be an RSA (Rivest-Shamir-Adleman cryptographic algorithm) certificate with a minimum of 2048 bits, or P-256 ECDS (Elliptic Curve Digital Signature Algorithm) certificate no greater than 256 bits.

• The TLS certificate must match the Guardium Insights domain and must specify the domain in the Subject Alternative Name (subjectAltName field).

• The TLS certificate and certificate authorities (CAs) must use a hash algorithm from the SHA-2 family.

• The TLS certificate must have a time span that does not exceed 398 days.

• The TLS server certificate must contain an ExtendedKeyUsage (EKU) extension containing the id-kp-serverAuth object identifier (OID).

• Guardium Insights does not support a password for the certificate key.

Wildcard certificates

Wildcard certificates can be used for Guardium Insights.

When the Guardium Insights domain and the foundational services domain are subdomains of the same base domain and a wildcard certificate is used, HTTP/2 connections between the client browser and the Guardium Insights domain are disabled and HTTP/1.1 protocol is enforced. For example, HTTP/1.1 is enforced under these conditions:

• The Guardium Insights domain is gi.example.com
• The Cloud Pak foundational services domain is cp-console.example.com
• The TLS certificate Subject Alternative Name is set to DNS: *.example.com

Example of TLS certificate generation with OpenSSL

For installation, Guardium Insights requires a server private key and server certificate that use keys that are signed by a trusted certificate authority (CA).

An extra authority certificate is required if the provided server keys are signed by a non-trusted authority.

If you need to generate a signing CA certificate, you can use the following example. The SUBJ environment variable is the name of the CA for which the certificate is generated, for example "/CN=My CA".

export SUBJ="<<Enter CA subject>>"
cat <<EOF > openssl.cfg
[ req ]
distinguished_name = req_distinguished_name
[ req_distinguished_name ]
commonName      = Common Name (for example, fully qualified host name)
commonName_max  = 64
[ v3_ca ]
basicConstraints = critical,CA:TRUE
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer:always
EOF

openssl genrsa -out ca.key 4096
openssl req -x509 -new -nodes -key ca.key -sha256 -days 825 \
     -config openssl.cfg -extensions v3_ca \
     -subj "$SUBJ" -out ca.crt

The result of using this example is that ca.key and ca.crt files are generated, containing the key and certificate for the CA.

To generate the server certificates, you can use the following example. The ca.key and ca.crt files can contain the key and certificate of the signing CA that you generated from the previous example, or your own key model. The DOMAIN environment variable is the name of domain for which the certificate is generated. For wildcard certificates, the value must start with '*.'

1. Create the OpenSSL configuration:

   export DOMAIN="<<Enter domain here>>"
   
   cat > openssl.cfg <<EOF
   [req]
   req_extensions = req_ext
   x509_extensions = usr_cert
   distinguished_name = req_name
   [ req_name ]
   commonName = $DOMAIN
   [ usr_cert ]
   basicConstraints=CA:FALSE
   nsCertType = server
   keyUsage = nonRepudiation, digitalSignature, keyEncipherment
   extendedKeyUsage = serverAuth
   subjectKeyIdentifier = hash
   authorityKeyIdentifier = keyid,issuer
   subjectAltName = DNS:$DOMAIN
   [ req_ext ]
   subjectAltName = DNS:$DOMAIN
   EOF

2. Generate the certificate:

   subj="/CN=$DOMAIN"
   openssl req -nodes -newkey rsa:2048 -keyout tls.key -outform PEM \
      -out tls.csr -subj "$subj" -config openssl.cfg
   openssl x509 -req -sha256 -in tls.csr \
      -out tls.crt.tmp \
      -CA ca.crt -CAkey ca.key \
      -CAcreateserial -CAserial ca.serial \
      -days 398 -extensions usr_cert -extfile openssl.cfg
   cat tls.crt.tmp ca.crt > tls.crt

The result of using this example is that tls.key and tls.crt files are generated, containing the server key and certificate for the domain. The following certificates and key are generated by the example: tls.crt, tls.key, ca.crt.

Certificate replacement

You might need to replace the TLS certificate that you installed, or that is in use with Guardium Insights, because it is invalid. You might also need to update the Guardium Insights application TLS secrets.