-
Notifications
You must be signed in to change notification settings - Fork 107
TLS SSL Certificates
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:
- Create a new key and CSR
- Open a ticket in Service Now and attach the CSR
- 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).
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.
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
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
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.
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.