mTLS Certificates Generation Guide

This guide explains how to generate the self-signed TLS certificates used for mutual TLS (mTLS) authentication between the USP Server and the USP Manager.

info

For an explanation of why and where these certificates are required, refer to USP Manager and USP Server mTLS Authentication.

warning

This guide uses a local Certificate Authority (CA) to sign the certificates.

Overview

By the end of this guide, you will have the following files:

Use	File Number	File	Where to Set It
Signs the certificates	n/a	usp-ca.key	Not set anywhere. Keep it private; it is needed only to sign certificates, including renewals.
Validates and identifies the USP Server	1	usp-ca.crt	In the web.tls.ca argument in the USP Server's .hcl file.
	2	usp-server-1.key	In the web.tls.key argument in the USP Server's .hcl file.
	3	usp-server-1.crt	In the web.tls.cert argument in the USP Server's .hcl file.
Validates and identifies the USP Manager	1	usp-ca.crt	In the USP Manager as a CA Certificate.
	4	usp-manager.key	In the PEM-encoded Private Key field of the Proxy Server's TLS Certificate.
	5	usp-manager.crt	In the Public X.509 Certificate field of the Proxy Server's TLS Certificate.

This guide uses one CA to sign both certificates, so the same file, usp-ca.crt, is set on both the USP Server and the USP Manager.

The 1 in usp-server-1 numbers the USP Server. To connect more USP Servers to the same USP Manager, generate another USP Server certificate and key for each one (for example, usp-server-2) and add a Proxy Server for it.

The diagram shows where each certificate is used:

warning

The name argument in the USP Server's .hcl file must match the Name of the corresponding Proxy Server in the USP Manager. This is how the USP Server accepts the configuration sent by the USP Manager.

Prerequisites

• OpenSSL is installed on a trusted system (for example, your local workstation or a secure certificate host). On Windows, OpenSSL must be installed and available in the PATH. The Windows commands in this guide are written for CMD and also run unchanged in Windows PowerShell 5.1 and PowerShell 7.x.
• You have shell access to the USP Server host to deploy its certificates.
• You have access to the USP Admin UI or USP REST API to add certificates for the USP Manager.
• You know the hostname and IP address of the USP Server (referred to in this guide as <usp-server-hostname> and <usp-server-ip-address>) and the hostname of the USP Manager (<usp-manager-hostname>).
• Define the absolute path of the directory where you will store the certificates. This guide refers to it as <certificates-directory>.

Generating the Certificates

1. Create a Directory for Your Certificates

Linux

$

mkdir -p <certificates-directory>

Windows (CMD)

C:\>

mkdir <certificates-directory>

2. Generate the Certificate Authority

Create a new CA certificate and private key. The CN value can be any descriptive name:

Linux

$

openssl req -new -x509 -nodes -days 36500 \
-subj "/CN=UDMG USP CA" \
-keyout <certificates-directory>/usp-ca.key \
-out <certificates-directory>/usp-ca.crt

Windows (CMD)

C:\>

openssl req -new -x509 -nodes -days 36500 -subj "/CN=UDMG USP CA" -keyout <certificates-directory>\usp-ca.key -out <certificates-directory>\usp-ca.crt

The command produces the following files:

• usp-ca.key: Private key
• usp-ca.crt: Certificate

3. Generate the USP Server Certificate

Generate the private key of the USP Server, create its certificate signing request, and sign it with the CA.

3.1 Generate the Private Key

Linux

$

openssl genrsa -out <certificates-directory>/usp-server-1.key 2048

Windows (CMD)

C:\>

openssl genrsa -out <certificates-directory>\usp-server-1.key 2048

3.2 Create the Certificate Signing Request

The CN value must be the hostname of the USP Server:

Linux

$

openssl req -new -key <certificates-directory>/usp-server-1.key \
-subj "/CN=<usp-server-hostname>" \
-out <certificates-directory>/usp-server-1.csr

Windows (CMD)

C:\>

openssl req -new -key <certificates-directory>\usp-server-1.key -subj "/CN=<usp-server-hostname>" -out <certificates-directory>\usp-server-1.csr

3.3 Create the SAN File

Create a file named usp-server-1-cert.cnf in <certificates-directory> with the following content, which defines the Subject Alternative Names (SAN) of the USP Server certificate:

usp-server-1-cert.cnf

subjectAltName=DNS:<usp-server-hostname>,IP:<usp-server-ip-address>

3.4 Sign the Certificate

Linux

$

openssl x509 -req \
-in <certificates-directory>/usp-server-1.csr \
-CA <certificates-directory>/usp-ca.crt \
-CAkey <certificates-directory>/usp-ca.key \
-extfile <certificates-directory>/usp-server-1-cert.cnf \
-CAcreateserial \
-days 365 \
-out <certificates-directory>/usp-server-1.crt

Windows (CMD)

C:\>

openssl x509 -req -in <certificates-directory>\usp-server-1.csr -CA <certificates-directory>\usp-ca.crt -CAkey <certificates-directory>\usp-ca.key -extfile <certificates-directory>\usp-server-1-cert.cnf -CAcreateserial -days 365 -out <certificates-directory>\usp-server-1.crt

The command produces the following files:

• usp-server-1.key: Private key
• usp-server-1.crt: Certificate

4. Generate the USP Manager Certificate

Generate the private key of the USP Manager, create its certificate signing request, and sign it with the CA.

4.1 Generate the Private Key

Linux

$

openssl genrsa -out <certificates-directory>/usp-manager.key 2048

Windows (CMD)

C:\>

openssl genrsa -out <certificates-directory>\usp-manager.key 2048

4.2 Create the Certificate Signing Request

The CN value must be the hostname of the USP Manager:

Linux

$

openssl req -new -key <certificates-directory>/usp-manager.key \
-subj "/CN=<usp-manager-hostname>" \
-out <certificates-directory>/usp-manager.csr

Windows (CMD)

C:\>

openssl req -new -key <certificates-directory>\usp-manager.key -subj "/CN=<usp-manager-hostname>" -out <certificates-directory>\usp-manager.csr

4.3 Sign the Certificate

Linux

$

openssl x509 -req \
-in <certificates-directory>/usp-manager.csr \
-CA <certificates-directory>/usp-ca.crt \
-CAkey <certificates-directory>/usp-ca.key \
-CAcreateserial \
-days 365 \
-out <certificates-directory>/usp-manager.crt

Windows (CMD)

C:\>

openssl x509 -req -in <certificates-directory>\usp-manager.csr -CA <certificates-directory>\usp-ca.crt -CAkey <certificates-directory>\usp-ca.key -CAcreateserial -days 365 -out <certificates-directory>\usp-manager.crt

The command produces the following files:

• usp-manager.key: Private key
• usp-manager.crt: Certificate

5. Verify the Certificates

Verify that both certificates are signed by your CA:

Linux

$

openssl verify -verbose -CAfile <certificates-directory>/usp-ca.crt <certificates-directory>/usp-server-1.crt

$

openssl verify -verbose -CAfile <certificates-directory>/usp-ca.crt <certificates-directory>/usp-manager.crt

Windows (CMD)

C:\>

openssl verify -verbose -CAfile <certificates-directory>\usp-ca.crt <certificates-directory>\usp-server-1.crt

C:\>

openssl verify -verbose -CAfile <certificates-directory>\usp-ca.crt <certificates-directory>\usp-manager.crt

Each command prints OK when the certificate is valid:

<certificates-directory>/usp-server-1.crt: OK
<certificates-directory>/usp-manager.crt: OK

6. Delete the Intermediate Files (Optional)

The certificate generation creates temporary files (the certificate signing requests, the SAN file, and the CA serial number file). They are only needed while generating and signing the certificates, and can be deleted afterwards:

Linux

$

rm <certificates-directory>/usp-server-1.csr <certificates-directory>/usp-manager.csr <certificates-directory>/usp-server-1-cert.cnf <certificates-directory>/usp-ca.srl

Windows (CMD)

C:\>

del <certificates-directory>\usp-server-1.csr <certificates-directory>\usp-manager.csr <certificates-directory>\usp-server-1-cert.cnf <certificates-directory>\usp-ca.srl

warning

Only delete these intermediate files. Do not delete the private keys (*.key) or the certificates (*.crt), as they are required for USP Server and USP Manager operation.

Configuring the Certificates

1. Add the CA Certificate

Add usp-ca.crt as a CA Certificate in the USP Admin UI, pasting its content in the Certificate field. For instructions, refer to Adding a CA Certificate.

To display the content of usp-ca.crt so you can copy and paste it, run:

Linux

$

cat <certificates-directory>/usp-ca.crt

Windows (CMD)

C:\>

type <certificates-directory>\usp-ca.crt

2. Add the USP Manager TLS Certificate

Add usp-manager.crt and usp-manager.key as a TLS Certificate in the USP Admin UI, pasting their content in the Public X.509 Certificate and PEM-encoded Private Key fields. For instructions, refer to Adding a TLS Certificate.

To display the content of both files so you can copy and paste it, run:

Linux

$

cat <certificates-directory>/usp-manager.crt

$

cat <certificates-directory>/usp-manager.key

Windows (CMD)

C:\>

type <certificates-directory>\usp-manager.crt

C:\>

type <certificates-directory>\usp-manager.key

3. Add a Proxy Server

Add a Proxy Server with usp-server-1 as its Name, selecting the CA Certificate you added in step 1 of this section in its CA Certificate field and the TLS Certificate you added in step 2 in its TLS Certificate field. For instructions, refer to Adding a Proxy Server.

4. Copy the Files to the USP Server Host

Copy usp-server-1.crt, usp-server-1.key, and usp-ca.crt to the USP Server host.

5. Configure the USP Server

In the USP Server's .hcl file, set the name, web.tls.cert, web.tls.key, and web.tls.ca arguments. Replace <certificates-directory> with the absolute path of the directory on the USP Server host where the three files are stored.

Linux

usp-server.hcl

name = "usp-server-1"

web {
  tls {
    cert = "<certificates-directory>/usp-server-1.crt"
    key  = "<certificates-directory>/usp-server-1.key"
    ca   = "<certificates-directory>/usp-ca.crt"
  }
}

Windows (CMD)

usp-server.hcl

name = "usp-server-1"

web {
  tls {
    cert = "<certificates-directory>\\usp-server-1.crt"
    key  = "<certificates-directory>\\usp-server-1.key"
    ca   = "<certificates-directory>\\usp-ca.crt"
  }
}

On Windows, write each backslash of the path twice in the .hcl file (for example, C:\\USP\\files).

For details on each argument, refer to USP Server Configuration File.