Skip to content

TLS SSL Certificates

Aaron D Borden edited this page Sep 27, 2019 · 29 revisions

Note: This document mostly applies to the BSP environment. For AWS Sandbox environments, public certificates are automatically provisioned through AWS. Host certificates are self-signed.

For Data.gov, we use GSA provisioned certificates in the BSP environment. Site certificates cover "public" network facing components like load balancers or CDNs. Host certificates are installed on each host to provide transport encryption between hosts within the network, which is required for security compliance.

Production site certificates are external GSA certificates while non-production site certificates are internal GSA certificates. All host certificates are internal GSA certificates.

The process for getting (or updating) a certificate is as follows:

  1. Create a new key and CSR
  2. Open a ticket in Service Now and attach the CSR
  3. Install the certificate and key

Each environment will need a site certificate and a host certificate. Wildcard certificates are not allowed by GSA, so we include all hosts/domains via Subject Alternate Names (SANs).

1. Generate a key and CSR

datagov-deploy contains a few scripts to automate the process and reduce the chance for mistakes or missing a host.

gen-csr.sh reads Subject Alternative Names (SANs) from stdin to create a single certificate. Files are generated in gen-csr-out, including the key and CSR.

SANs for site certificates

There should be a text file next to gen-csr.sh for production and staging.

$ cd ansible
$ bin/gen-csr.sh data.gov < bin/production-sans.txt

ansible/gen-csr-out/data.gov.csr will be attached to the Service Now request. Save the key file for later, it will be installed to the load balancers and CDNs once the certificate is provisioned by GSA.

You can inspect the CSR with openssl.

$ openssl req -text -noout -in gen-csr-out/data.gov.csr

SANs for host certificates

Host certificates get the SANs from the Ansible inventory. Run the gen-csr.sh with the inventory name and feed the hostnames from ansible-inventory to stdin.

$ cd ansible
$ bin/gen-csr.sh $inventory < <(ansible-inventory -i "inventories/$inventory" --list | jq -r '.[].hosts[]?' | sort | uniq)

You can inspect the CSR with openssl.

$ openssl req -text -noout -in gen-csr-out/$inventory.csr

2. Requesting the certificate

Open a Service Now ticket for GSA SSL certificate request. Fill out the required information.

For production site certificates, you want to request an external certificate. For all other certificates, you want to request an internal certificate.

You will be filling in a lot of redundant information that is included in the CSR.

Attach the CSR to the ticket.

3. Installing the certificate and key

Provisioning the certificate may take a few days. Once provisioned, the certificate will be attached to the Service Now ticket. The GSA certificate is in PEM format and should be installed with the key generated in step 1.

Host certificate and keys should be added to the ansible inventory as default_tls_host_certificate and default_tls_host_key, respectively.

Site certificate and keys are installed manually to load balancers, CDNs, and WAFs. You may need to open BSP tickets to get these installed.

Clone this wiki locally