How To Set Up SSL Certificate For Your Docker-Compose Environment With A .pfx File

Image by author — Photo by Tima Miroshnichenko

I haven't heard of .pfx files before having to use them to configure SSL certificates for a Docker environment.

It turned out that:

.pfx files are password-protected files that contain both public and private certificate pairs.

So instead of receiving .crt, .pem, or .key files from your SSL certificate provider, you might receive a .pfx file.

In this tutorial, I’d like to walk you through the process of extracting the certificate and keys from a .pfx file and using them for your docker environment.

Prerequisites

• A .pfx file
• Docker-compose application with an Nginx service to handle all the incoming requests

There are two main parts to this tutorial:

• The first part is about extracting the certificate and the private key from a .pfx file
• and the second is related to configuring a docker-compose environment to use the extracted certificate and key.

Are you ready? Let’s jump right in.

1- Extracting the certificate and the private key from the .pfx file

This is a 2-step process. We’ll need to extract the … private key first. Actually, this is not really the private key and I’ll tell you why in a few seconds.

Then we’ll extract the real private key before extracting the certificate itself in order to use them for our SSL certificate setup.

So hang in man.

1.1 Extract an encrypted version of the certificate key

Run the following command to get an encrypted version of the private key.

openssl pkcs12 -in yourfile.pfx -nocerts -out [encrypted_ssl_certificate_secret.key]

You will be asked to enter the password used to create the .pfx file you’ve got, that’s the first step. Then you’ll be prompted to input a second password: this last password is meant for protecting the real key that is contained in the .pfx file.

1.2 Extract the actual certificate key

We’re now everything we need to extract the real private key. Run:

openssl rsa -in encrypted_ssl_certificate_secret.key -out ssl_certificate_secret.key

Type in the second password that you set to protect the private key file in the previous step.

You can see the ssl_certificate_secret.key in the current directory.

1.3 Extract the certificate

We’re done with extracting the private key. We need to do the same for the certificate. Run the following command:

openssl pkcs12 -in yourfile.pfx -clcerts -nokeys -out my_certificate.crt

Yeah, we have extracted your SSL certificate but that’s not all. We need to add to my_certificate.crt, the Certificate Authority (CA) one.

To generate the CA certificate, let’s run:

openssl pkcs12 -in yourfile.pfx -cacerts -out ca_certificate.crt

Now, we’ll add up these certificates to get the final certificate we need:

cat domain.tld.crt my_certificate.crt > ssl_certificate.crt

Voilà!!!

But wait, wait …, man. We’re at a step from the finish line.

2- Configuring Nginx in your Docker environment to use the certificate

Well, we’ve just finished the first main part of our whole craft. Let’s see how we can use the ssl_certificate.crt andssl_certificate_secret.crt files.

2.1 Configure Nginx

If you’ve ever used an Nginx container in your docker setup before, you know that we often load its config from the local storage and that’s exactly what we’re going to do.

So your current Nginx config file should look like this:

server {
  listen 80;

  root /var/www/public;

  add_header X-Frame-Options "SAMEORIGIN";
  add_header X-Content-Type-Options "nosniff";
  index index.php index.html;
  charset utf-8;
  location = /favicon.ico { access_log off; log_not_found off; }
  location = /robots.txt  { access_log off; log_not_found off; }
  error_page 404 /index.php;
  
  location / {
    ...
  }
  ...
}

Add your certificate files to it. In the end, it should look like this instead:

server {
  listen 443 ssl;
  
  root /var/www/public;
  
  ssl_certificate    /etc/ssl/private/ssl_certificate.crt;
  ssl_certificate_key /etc/ssl/private/ssl_certificate_secret.key;
  add_header X-Frame-Options "SAMEORIGIN";
  add_header X-Content-Type-Options "nosniff";
  index index.php index.html;
  charset utf-8;
  location = /favicon.ico { access_log off; log_not_found off; }
  location = /robots.txt  { access_log off; log_not_found off; }
  error_page 404 /index.php;
  
  location / {
    ...
  }
  ...
}

But these changes won’t work on their own. This moves us to the next step.

2.2 Update your docker-compose file

Your Docker-Compose file should currently look like this:

version: '3.7'
services:
proxy:
    image: nginx:<tag>
    volumes:
      - ...
      - ./nginx.conf:/etc/nginx/nginx.conf:ro

To make the certificates available inside the container we should edit the volume section of our service. Your file should look like this at the end of the process:

version: '3.7'
services:
proxy:
    image: nginx:<tag>
    volumes:
      - ...
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs/ssl_certificate.crt: /etc/ssl/private/ssl_certificate.crt:ro
      - ./certs/ssl_certificate_secret.key: /etc/ssl/private/ssl_certificate_secret.key:ro

Yes, yes I can see someone's head shaking 😲: This is not efficient. Yes, I totally agree. We did it for the sake of simplifying the concept first.

Here is the right way of doing it:

version: '3.7'
services:
proxy:
    image: nginx:<tag>
    volumes:
      - ...
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/ssl/private:ro

🎉 Sure, great, simple, and nice, right? But don’t forget to copy the ssl_certificate.crt and the ssl_certificate_secret.key into the ./certs folder.

Conclusion

In order to secure your communication with its API, a third-party API provider can require that you enable SSL certification for your Docker containers.

There are various certificate formats, they can provide you with. In this tutorial, we focused on one of the less-known but very useful ones: .pfx files.

From extracting the certificate and its secret to using it in our docker-compose environment, we saw how to proceed.

Thanks for reading. I’d like to know your experience with setting up an SSL certificate for your Docker environment.

Till next time, take care.

Cheers!!!