Using a Custom CA Certificate

Motivation

Each DC/OS Enterprise cluster has its own DC/OS certificate authority (CA). By default, that CA uses a globally unique root CA certificate generated during the installation of DC/OS. That root CA certificate is used for signing certificates for the components of DC/OS, such as Admin Router. In lieu of using the auto-generated root CA certificate, you can configure DC/OS Enterprise to use a custom CA certificate, which is either a root CA certificate or an intermediate CA certificate. (see examples below)

The benefits of using a custom CA certificate for your DC/OS Enterprise cluster include:

Ensuring that all X.509 certificates used within the DC/OS cluster (for both signing and encrypting) derive from your organization’s X.509 certification hierarchy.

Controlling security properties of the key pair (such as type and strength) used for signing DC/OS component certificates.

The structure of this document page

To facilitate the reading of this page we start out by providing a glossary for general definition of terms, followed by an in-depth configuration parameter reference. An installation walkthrough is provided in section Installing DC/OS Enterprise with a custom CA certificate. Section Example use cases then provides example file contents for the custom CA certificate configuration files for three popular use cases.

What is supported and what is not

Only custom CA certificates that have an associated RSA-type key pair are supported. Other types of certificates, such as those using ECC-type key pair, are currently not supported. Support for ECC-type key pairs will be added in the future.

Custom CA certificates are only supported for a fresh installation of DC/OS Enterprise 1.10 or higher. Older versions of DC/OS are not supported, and it is not possible to add a custom CA certificate during an upgrade.

Glossary of the terms used in this documentation

Custom CA certificate: Your custom CA certificate in the PEM format, which will be used to issue certificates for DC/OS components such as Admin Router. The custom CA certificate is either an intermediate CA certificate (issued by another CA) or a root CA certificate (self-signed by the custom CA).

Private key associated with the custom CA certificate: The private key in the PKCS#8 format associated with the custom CA certificate.

Certificate chain associated with the custom CA certificate: The complete CA certification chain required for end-entity certificate verification. It must include the certificates of all parent CAs of the intermediate custom CA up to and including the root CA certificate. If the custom CA certificate is a root CA certificate, the chain must be empty.

Installation directory: The directory on the bootstrap node where the DC/OS installer resides. It is denoted with $DCOS_INSTALL_DIR in this document.

Configuration: The set of the configuration parameters that governs the specific aspects of the installation procedure. The configuration is stored in the DC/OS configuration file.

DC/OS configuration file: The file which contains the DC/OS configuration parameters. The DC/OS configuration file is normally called config.yaml and must be present in the $DCOS_INSTALL_DIR/genconf/ directory on the bootstrap node during the installation. It is used by the DC/OS installer.

Requirements

In order to install DC/OS Enterprise with a custom CA certificate you will need:

For security reasons, the installer will not copy the private key from the bootstrap node to the master nodes.
The private key associated with the custom CA certificate must be distributed manually to every DC/OS master node before starting the installation.

The filesystem path for the private key file must be /var/lib/dcos/pki/tls/CA/private/custom_ca.key.
The directory /var/lib/dcos/pki/tls/CA/private/ can be created manually with the following command before putting the file custom_ca.key in the directory on every DC/OS master node:

mkdir -p /var/lib/dcos/pki/tls/CA/private

Furthermore, the file containing the private key custom_ca.key corresponding to the custom CA certificate must be owned by the root Unix user and have 0600 permissions set.

If you copy the private key file over the network onto the master nodes, the network channel must be adequately protected.
An example of copying the CA private key is given below. The commands are executed on the bootstrap node. The W.X.Y.Z below indicates the IP address of a master node:

Specifying the locations of the custom CA certificate, the associated private key and the certificate chain files in the DC/OS configuration file

The filesystem paths to the custom CA certificate, associated private key and certificate chain files in the $DCOS_INSTALL_DIR/genconf/ directory on the bootstrap node must be specified in the DC/OS configuration file using, respectively, the ca_certificate_path, ca_certificate_key_path and ca_certificate_chain_path parameters.
The paths must be relative to $DCOS_INSTALL_DIR.

Configuration parameter reference

ca_certificate_path

Path (relative to the $DCOS_INSTALL_DIR) to a file containing a single X.509 CA certificate in the OpenSSL PEM format. For example: genconf/dcos-ca-certificate.crt. It is either a root CA certificate (“self-signed”) or an intermediate CA certificate (“cross-certificate”) signed by some other certificate authority.

If provided, this is the custom CA certificate. It is used as the signing CA certificate, i.e., the DC/OS CA will use this certificate for signing end-entity certificates (the subject of this certificate will be the issuer for certificates signed by the DC/OS CA). If not provided, the DC/OS cluster generates a unique root CA certificate during the initial bootstrap phase and uses that as the signing CA certificate.

The public key associated with the custom CA certificate must be of type RSA.

ca_certificate_key_path

Path (relative to the $DCOS_INSTALL_DIR) to a file containing the private key corresponding to the custom CA certificate, encoded in the OpenSSL (PKCS#8) PEM format. For example: genconf/CA_cert.key.

Note: this is highly sensitive data. The configuration processor accesses this file only for configuration validation purposes, and does not copy the data. After successful configuration validation this file needs to be placed out-of-band into the file system of all DC/OS master nodes to the path /var/lib/dcos/pki/tls/CA/private/custom_ca.key before most DC/OS systemd units start up. The file must be readable by the root user, and should have have 0600 permissions set.

Required if ca_certificate_path is specified.

ca_certificate_chain_path

Path (relative to the $DCOS_INSTALL_DIR) to a file containing the complete CA certification chain required for end-entity certificate verification, in the OpenSSL PEM format. For example: genconf/CA_cert_chain.pem.

The parameter must be left undefined if ca_certificate_path points to a root CA certificate.
Required if ca_certificate_path is specified and if the custom CA certificate is an intermediate CA certificate.

For an intermediate CA, this needs to point to a file containing all CA certificates comprising the complete sequence starting precisely with the CA certificate that was used to sign the custom CA certificate and ending with a root CA certificate (where issuer and subject are equivalent), yielding a gapless certification path. The order is significant and the list must contain at least one certificate.

Installing DC/OS Enterprise with a custom CA certificate

Starting point

Based on the requirements described above, this is the starting point for the installation:

The installation of DC/OS Enterprise via the Advanced Installer has been prepared according to the corresponding documentation. (up to the section Install DC/OS of that documentation)

On the bootstrap node, the files carrying custom CA certificate, the associated private key and, optionally, the CA certificate chain have been placed into the $DCOS_INSTALL_DIR/genconf/ directory. (see the section above for more detailed description)

The private key associated with the custom CA certificate has been securely placed on all DC/OS master nodes (refer to this section for more details). Example (command issued on one of the DC/OS master nodes):

The configuration parameters ca_certificate_path, ca_certificate_key_path and ca_certificate_chain_path are specified in the DC/OS configuration file $DCOS_INSTALL_DIR/genconf/config.yaml and point to the relevant locations in the file system. Example (commands issued on the bootstrap node):

Note that ca_certificate_chain_path must not be present when setting up DC/OS Enterprise with a root certificate as the custom CA certificate.

Installation

Proceed with the installation as described in the documentation of the Advanced Installer.
Note that the current working directory when executing dcos_generate_config.ee.sh must be the $DCOS_INSTALL_DIR directory.

Verify installation

One method of verifying that the DC/OS Enterprise cluster was installed properly with the custom CA certificate is to initiate a TLS connection to Admin Router which, after installation, will present a certificate signed by the custom CA.

In order to do that you first need to obtain the DC/OS CA bundle of the deployed cluster. This page shows how you can do that.

Provided you have obtained the DC/OS CA bundle and stored it in a file named dcos-ca.crt, issue the following command in the directory containing the dcos-ca.crt file in order to check that Admin Router on a master node uses a certificate signed by the custom CA:

Example use cases

This section describes how the three configuration parameters ca_certificate_path, ca_certificate_key_path and ca_certificate_chain_path must be specified in the $DCOS_INSTALL_DIR/genconf/config.yaml DC/OS configuration file for the most common use cases of a custom CA certificate hierarchy.

Use case 1: The custom CA certificate is a root CA certificate

In this case the custom CA certificate is a (self-signed) root CA certificate. The CA does not have a “parent” CA, hence the CA certificate chain is empty.

Since the custom CA certificate is a root CA certificate and the corresponding CA certificate chain is empty, we must omit the ca_certificate_chain_path parameter in the DC/OS configuration file. The configuration parameters must be specified as follows in the $DCOS_INSTALL_DIR/genconf/config.yaml file on the bootstrap node: