Updating the DV Certificate for On-Prem Server API

As part of security enhancements since version 5.8.1 of On-Prem, HTTP communication between the On-Prem API and Agents now occurs over TLS as this requires a Domain Validated (DV) server certificate with domain/IP validation.

By default, the On-Prem installation comes with a self-signed certificate, which Agents do not authenticate because it does not include the assigned domain/IP. Therefore, an additional step is required to generate a certificate with a specific domain/IP so that the Agent can verify the server certificate and domain/IP.

This document outlines the steps to update the DV certificate of the On-Prem server.

Steps required to update the DV certificate:

1. Generate the DV certificate.
2. Update the On-Prem server.
3. (Optional) Update the Agent’s Microsoft Windows machine.
4. Verify certificate installation.
5. Restart services.

Step 1: Generate the DV certificate

There are two options for generating a server DV certificate:

Option 1: Obtain a signed DV certificate from a trusted authority (CA)

A certificate signed by a Certificate Authority (CA) is pre-trusted by Microsoft Windows. You can purchase a DV certificate from a trusted CA like GoDaddy and follow their instructions to generate the certificate.

Option 2: Generate a self-signed DV certificate

You can generate a self-signed certificate using OpenSSL if you do not want to purchase one.

To generate a self-signed certificate:

1. Generate a Private Key. Run the following command to create a private key:
   openssl genrsa -out cert_selfsigned.key 2048
2. Create a Certificate Signing Request (CSR). 
   Generate a CSR with the desired details, replacing <IP> or <PRIVATE DOMAIN> accordingly, on-prem IP or private domain:
   openssl req -new -key cert_selfsigned.key -out cert_selfsigned.csr -subj "/C=US/ST=State/L=City/O=YourCompany/CN=<IP or PRIVATE DOMAIN>"
3. Create a configuration file for the IP-based Certificate. 
   Create a file named san.cnf and add the following content:
   
   [req]
distinguished_name = req_distinguished_name
x509_extensions = v3_req
prompt = no
[req_distinguished_name]
C = US
ST = State
L = City
O = YourCompany
CN = <IP>
[v3_req]
subjectAltName = IP:<IP>
4. Generate a Self-Signed Certificate.
   Create the SSL certificate with the following command:
   openssl x509 -req -in cert_selfsigned.csr -signkey cert_selfsigned.key -out cert_selfsigned.crt -days 365 -extfile san.cnf -extensions v3_req
   
   The certificate is valid for 365 days. Modify the -days parameter as needed.  As a security best practice, we recommend regularly rotating the certificate to mitigate potential risks.

Step 2: Update the On-prem Server

To update the on-prem server:

1. Copy the generated certificate and key to the On-Prem server.
2. Ensure proper permissions for the files by storing them securely in /etc/datahub/nginx for certificates and private keys.
   sudo chmod 644 /etc/datahub/nginx/cert_selfsigned.crt
sudo chmod 600 /etc/datahub/nginx/cert_selfsigned.key
3. Navigate to the On-Prem installation folder:
   cd /opt/datahub
4. Run the update script:
   sudo ./update_https_certificate.sh <Path to new certificate> <Path to new certificate key> [Path to installed On-Prem]

Step 3: (If Self-Signed) Transfer the Certificate and Key to Microsoft Windows

To use the self-signed certificate on Microsoft Windows, follow these steps:

1. Generate a P12 File

• Run the following commands to create a .p12 certificate package:
  openssl pkcs12 -export -out cert_selfsigned.p12 -inkey cert_selfsigned.key -in cert_selfsigned.crt -certfile cert_selfsigned.crt
chmod 600 cert_selfsigned.p12

2. Import the Certificate Using PowerShell

• Open PowerShell as an Administrator and run the following command. You will be prompted for the P12 password set earlier:
  Import-PfxCertificate -FilePath "C:\certificates\cert_selfsigned.p12" -CertStoreLocation Cert:\LocalMachine\Root

3. Import the certificate using the GUI (Certificate Manager)

• Press Win + R, type certlm.msc, and press Enter
• Navigate to Trusted Root Certification Authorities → Certificates
• Click Import and select Local Machine as the Store Location
• Select the .p12 file and enter the password when prompted

Step 4: Verify Certificate Installation

Use the GUI (Certificate Manager)

• Press Win + R, type certlm.msc, and press Enter
• Navigate to Trusted Root Certification Authorities → Certificates
• Look for the certificate in the list and verify its subject details

Step 5: Restart Services

For the changes to take effect, restart any affected services