Sectigo Docker integration

Overview

The Sectigo Docker integration provides a seamless way to retrieve SSL/TLS certificates issued by the Sectigo Certificate Manager (SCM). The certificate can be used to secure a Docker container and its communication with other containers.

The Sectigo Docker integration provides an entrypoint that can be incorporated with any Dockerfile. It seamlessly generates the key and certificate signing request and returns the certificate issued by SCM. The use of certificates can be configured by Docker users as per their requirements. The entrypoint supports both the generation of new SSL certificates and the use of existing certificates stored in a location accessible to a Dockerfile. The entrypoint also checks the validity of a certificate when an existing certificate is used. There are various types of SSL certificates that can be requested by supplying the configuration options.

The types of certificates available to you are based on your account setup.

This integration guide describes how to use sectigo-ssl-entrypoint.py to provision SSL/TLS certificates from SCM to setup secure Docker containers. The following diagram illustrates the process.

Docker Sectigo integration

Prerequisites

The Docker integration has the following requirements:

  • The sectigo-ssl-config.txt file with configuration information

  • Python 2.7.x

Docker integration package

The Sectigo Docker integration package contains the following:

  • sectigo-ssl-entrypoint.py: A Python script which validates a certificate, generates a private key and CSR, enrolls and collects the SSL certificate, and saves it to the specified location.

  • sectigo-ssl-config.txt: This file contains the configuration information for sectigo-ssl-entrypoint.py.

  • Sample: This folder contains a sample Dockerfile, NGINX configuration file, index.html, and a Bash script to automate the deployment. For more information, see Understanding the Docker sample folder.

All commands must be run from inside the Sectigo-Docker-Integration directory.
Sectigo Docker integration package

Understanding the Docker sample folder

The Sample folder is comprised of the following parts:

  • Dockerfile: A sample Dockerfile that is used to spin up the Docker container that calls sectigo-ssl-entrypoint.py as an ENTRYPOINT. The Dockerfile uses Ubuntu 18.04 as a base image and installs Python version 3.x. Volumes to store the certificates can be configured as per actual usage.

  • Dockerfile-2x: A sample Dockerfile that is used to spin up the Docker container that calls sectigo-ssl-entrypoint.py as an ENTRYPOINT. The Dockerfile downloads the Ubuntu 16.04 image and installs Python version 2.x. Volumes to store the certificates can be configured as per actual usage.

  • server.conf: A pre-configured Nginx configuration file. The SSL configuration is the crucial part which contains the path of the .key and .crt files and port 443 configurations. The certificate and key files are generated as per the CERT_FILE_NAME parameter in the sectigo-ssl-config.txt file.

  • index.html: The home page that gets displayed when you access the URL for which you configured the certificates.

  • build.sh: This file automates the entire process of building the Dockerfile and getting the running the container. You can run this file from the projects root folder by executing the `bash Sample/build.sh`command.

Configuring the entrypoint

The sectigo-ssl-config.txt file contains user specific information that requires configuration before calling the entrypoint from your Dockerfile. It comes pre-populated with sample values—​replace all sample values with your actual values before running the script.

Parameters with their respective default values are stored as <key = value> pairs. The pairs must be separated by a return key or end-of-line. Note the following:

  • There should be a space between a key and value.

  • There should be no quotations added for values.

  • To specify an empty value, provide no value for a key.

  • Comments can be added in the config file by using hash (#) as the first character.

  • Blank lines are ignored.

The following table describes the parameters in the sectigo-ssl-config.txt file.

Parameter Description

Customer-specific parameters

SECTIGO_CA_BASE_URL

The base URL of the Sectigo Certificate Authority

CERT_DOMAIN

A single value for a domain which is included in the CN field of the certificate

CERT_SUBJECT

The certificate subject

CERT_SUBJECT_ALT

A single or comma-separated list of subject alternate names (SAN)

SECTIGO_CM_LOGIN

The user ID for accessing the customer URI

SECTIGO_CM_PWD

The password for accessing the customer URI

SECTIGO_CM_CUSTOMERURI

A customer-specific URI

SECTIGO_CM_ORGID

The customer’s Organization ID (numeric)

CERT_EXT_REQUESTER

A single or comma-separated list of email(s)

CERT_FILE_PATH

The location where the certificate file is stored.

CERT_FILE_NAME

The name of the SSL certificate file

Generic parameters with default values

CERT_TYPE

The type of the SSL certificate (numeric)

CERT_VALIDITY

The certificate validity period (numeric)

CERT_COMMENTS

Comments for certificate enrollment

SSL_CERT_TYPE

The type of the SSL certificate format

CERT_NUM_SERVERS

The number of server licenses (numeric)

SERVER_TYPE

The ID of the server type (numeric)

Using the sample Docker image

Before proceeding, make sure that:

  • The values in the sectigo-ssl-config.txt file reflect the correct domain and other parameter values for the use case being tested.

  • The <CERT_DOMAIN> value in the server.conf file has been replaced with your specific domain.

  • The server.conf file values match those in the sectigo-ssl-config.txt file. These values include the domain, SSL certificate file path, and names. Any changes made to these values in one file must be replicated in the other.

  • All relevant files are placed in a single directory. For example, if the files are located in the Sectigo-Docker-Integration/ directory, it becomes the project’s root directory.

  • The current running user has appropriate permission on Docker. You may also use the root or equivalent user to run the shell script. For more information on adding user permission for Docker, see Post-installation steps for Linux.

  • The bash script file has the execute permission.

Building and running the Docker image

Build the Docker image and run it using the shell program with the bash Sample/build.sh command from the root directory. The script triggers the underlying Docker commands, such as:

  1. Check and clean the existing running containers.

  2. Build the Docker image.

  3. Run the container with the necessary runtime parameters.

Due to the sequence of the commands stacked in the shell script, it shows the list of containers and the logs of the Docker container.

Mounting the certificates in a volume

If you need to mount the certificates in a volume, the build.sh script requires the following changes in the docker run command.

docker run -d -v /certs:/etc/ssl/ -p 80:80 -p 443:443 -name <container-name> -tid <container-image:tag> --env params_file_path="Sectigo-ssl-config.txt"

In the preceding command, -v /certs:/etc/ssl is an enablement of volume support to place certificates out of the container, where certs is a host machine directory that maps to /etc/ssl in the container directory.

It is assumed that ports 80 and 443 are not assigned to any service and are available for assignment in Docker. If these ports are already assigned, make the necessary changes to the command.

Investigating the Docker image

To investigate the Docker image, use the following commands.

docker logs <container-name>
docker exec -it <container-name> /bin/bash

While the docker logs command helps with debugging information on the entrypoint script, the docker exec enables running the command in the Docker container itself. With docker exec, commands can be executed to check the contents of various files and the status of services in the Docker container. For a complete list of Docker commands, see Docker CLI.