Generating a PFX Certificate Bundle for mTLS

Overview

Some external APIs (application programming interfaces) and services need callers to use a client-side certificate. This is to prove the client's identity to the remote server receiving the request. The caller uses a certificate and private keypair to sign requests made to the remote server. In turn, the remote server authenticates the caller's certificate to validate the request. Unqork supports configuring the mTLS (Mutual Transport Layer Security) certificate as a PFX (personal information exchange) certificate bundle in hexadecimal notation. The bundle must include the signed certificate, intermediate certificates, and the private key.

This article discusses PFX and PEM (privacy-enhanced mail) files, but file extensions can vary. For example, you might work with files that use a .crt or .key extension, rather than .pem. PEM indicates a type of encoding so .pem, .key, and .crt could all contain certificate and/or public or private key information. This article also covers how to combine a signed certificate, intermediate certificates, and the private key into a PFX certificate. If you aren’t sure which files to include, see your signing authority's documentation.

It’s common to generate a self-signed certificate to use with mTLS. It's not necessary for the certificate to be publicly signed. This is because the remote service must be explicitly configured with the certificate. To get a publicly-signed certificate, you can buy one from a public CA (Certificate Authority).

What You'll Learn

In this article, you'll learn how to:

Generating a Self-Signed Certificate Key Pair

Let’s start by generating a self-signed certificate keypair from the CLI (command-line interface). If you already have a certificate and key for this purpose, you can skip to Converting a PEM file to PFX Format.

Here, you'll use OpenSSL to generate the keypair. If you're using Linux or MacOS, you can visit https://www.openssl.org/source/ to get the latest OpenSSL toolkit. If you're using Windows, you can visit https://slproweb.com/products/Win32OpenSSL.html.

Linux/MacOS

1. Open Terminal.
2. Create a new folder for your keys.
Copy
 
$ mkdir <your_pki_directory>
$ cd <your_pki_directory>
3. Generate a self-signed certificate and keypair using OpenSSL.

This code snippet contains long lines of code. If viewing this document as a PDF, some of the code may not be visible. To view the code snippet in its entirety, search for this article in our In-Product Help.

Copy
 
$ openssl req -x509 -newkey rsa:4096 -keyout privateKey.key -out certificate.crt -days 3650 -subj '/CN=<your_environment>' -nodes

In the code snippet above:

  • The Common Name “/CN=<your_environment>-staging.unqork.io” is a suggested naming convention. To avoid receiving an error message, manually enter the quotation marks in the above script.

  • The -days parameter shows the number of days (3650) the certificate and keypair are valid.

  • certificate.crt must be provided to the service owner for configuration on their side.

4. Bundle the privateKey.key and the certificate.crt into a PFX certificate with OpenSSL.
Copy
 
$ openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt

If you regenerate a new certificate, the remote service owner must also reconfigure their system.

5. When the prompt appears, enter a PEM passphrase.

When asked to set a passphrase, be sure to record it in a secure location. You'll need the passphrase every time you use the certificate. It's best practice to use a password manager and treat the passphrase and the file the same way you treat any password.

Windows

1. Enter openssl in the Search bar.
2. Select Win64 OpenSSL Command Prompt.
3. Generate a self-signed certificate and keypair using OpenSSL.

This code snippet contains long lines of code. If viewing this document as a PDF, some of the code may not be visible. To view the code snippet in its entirety, search for this article in our In-Product Help.

Copy 
openssl req -x509 -newkey rsa:4096 -sha256 -keyout privateKey.key -out certificate.crt -days 3650 -subj “/CN=<your_environment>” -nodes

In the code snippet above:

  • The Common Name “/CN=<your_environment>-staging.unqork.io” is a suggested naming convention. To avoid receiving an error message, manually enter the quotation marks in the above script.

  • The -days parameter shows the number of days (3650) the certificate and keypair are valid.

  • certificate.crt must be provided to the service owner for configuration on their side.

4. Bundle the privateKey.key and certificate.crt into a PFX certificate with OpenSSL.
Copy 
openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt

If you regenerate a new certificate, the remote service owner must also reconfigure their system.

5. When the prompt appears, enter a PEM passphrase.

When asked to set a passphrase, be sure to record it in a secure location. You'll need the passphrase every time you use the certificate. It's best practice to use a password manager and treat the passphrase and the file the same way you treat any password.

Converting a PEM file to PFX Format

To add and validate a certificate in Services Administration, the certificate must be in PFX format. PFX is a format for storing the certificate and private key in one password-protected file. If your file is in PEM format, you can use OpenSSL to convert the PEM file to PFX. If the file is already in PFX format, you can skip to Getting the Hex Representation of the PFX File.

Linux/MacOS

1. Open Terminal.
2. Go to <your_pki_directory>. Or, if you have a publicly signed certificate, the directory where you downloaded the files from the signing entity.
Copy 
$ cd /<your_folder_path>
3. Create the bundle using OpenSSL.
Copy 
$ openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt

To convert a certificate from a public CA, you'll add -certfile <root_certificate_chain>.crt to the end of the command. This is the certificate chain leading up to the root CA. One or more PEM certificates are typically inside the file. A self-signed certificate doesn't have the root certificate chain. Not sure which certificate to use? Your signing authority's documentation will help you find the correct file.

  • privateKey.key is the private key.

  • certificate.crt is the signed certificate file.

Windows

1. Type openssl in the Search bar.
2. Select Win64 OpenSSL Command Prompt.
3. Create the bundle using OpenSSL.
Copy 
openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt

To convert a certificate from a public CA, you'll add -certfile <root_certificate_chain>.crt to the end of the command. This is the certificate chain leading up to the root CA. One or more PEM certificates are typically inside the file. A self-signed certificate doesn't have the root certificate chain. Not sure which certificate to use? Your signing authority's documentation will help you find the correct file.

  • privateKey.key is the private key.

  • certificate.crt is the signed certificate file.

Now you're ready to get the PFX file's hex representation and set it up in Unqork.

Getting the Hex Representation of the PFX File

There are several ways to get the hex representation of the PFX file. We'll cover two of them below:

  • Using an IDE (integrated development environment) text and code editor program, like Sublime Text (available here: https://www.sublimetext.com/download.)

  • Using the Linux/MacOS CLI to create a file with the hex representation.

Using an IDE (Sublime Text)

1. Open the PFX file with Sublime Text. The file displays in hex representation.

Using the Linux/MacOS CLI

1. Open Terminal.
2. Create a file with the hex representation.
Copy 
# xxd -p -c16 certificate.pfx certificate-hex.pfx

Unqork ignores whitespaces. So, you can submit the hex representation with or without the spaces included.

3. Copy the converted file to your clipboard.
Copy 
# pbcopy < ./certificate-hex.pfx

Adding an mTLS Certificate to Certificate Management

Now that your certificate is in the correct format, you're ready to add it to the certificate dashboard in Certificate Management. From Certificate Management, you can easily add, view, and manage mTLS certificates in your environment.

The following instructions cover how to add an mTLS certificate and link services to it. You can also set up a certificate without linking services to it. After completing the required fields in the Mutual TLS Info tab, click Next. Then, without attaching any services on the Attach Services tab, click Add Certificate.

To learn more about the Certificate Management page, search Certificate Management in our In-Product Help.

To add a certificate to the certificate dashboard:

1. Click the Settings drop-down at the top right of the Unqork Designer Platform.
2. Click Administration.
3. Under Integration, select Certificate Management.
4. Click + New Certificate. The certificate configuration modal opens.
5. Enter a name for your certificate in the Certificate Title field.

Certificate names must be unique.

6. Copy and paste the contents of the mTLS certificate into the PFX or PKCS12 Encoded (hex) Private Key and Certificate Chain field.  
7. Copy and paste the certificate password into the PFX Passphrase field, if required.

8. Click Next.
9. From the Attach Services drop-down, select the service(s) to link to your certificate.

Services must be set up in Services Administration to show in the Attach Services drop-down.

You can link one certificate to several services. However, each service can only be linked to one certificate at a time.

10. Click Add Services.

11. Click Add Certificate.

Nice work! You successfully added your PFX certificate bundle for mTLS authentication.