-
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 and 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/staging 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.
Once generated, upload the .key file to Google Drive. Use Drive's file versioning feature to update the existing file rather than creating a new one (right-click and select Manage Versions).
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. You can inspect the CSR for this information:
$ openssl req -text -noout -in gen-csr-out/data.gov.csr
Some additional fields not in the CSR:
| Field | Value |
|---|---|
| Enhanced Key Usage | Server Authentication (1.3.6.1.5.5.7.3.1) |
| Responsible SSO | Federal Acquisition Services (Q) |
| FISMA System | Data.gov |
| Application Team | FCS Team Approval |
Submit the form. Once the request is created you can attach the CSR. Note: On May 20th, 2020 it was not accepting .csr extensions, so I appended .txt before I could upload the CSR.
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. Make sure the certificate and key are uploaded to Google Drive.
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.