How to import a public SSL certificate into AWS Certificate Manager on Windows
Introduction
If you are not using a standard Modernisation Platform domain for your app, you will need to import your SSL certificate into your AWS account and apply it to your infrastructure. This guide does not cover the infrastructure element of this, only the import of SSL certificates into your AWS account.
This assumes you have read how to configure DNS and have a basic understanding of SSL concepts, and access to openssl on the command line.
The steps are:
- Generate a certificate signing request (CSR)
- Request a certificate using that CSR
- Complete the certificate request
- Export the complete certificate
- Import the exported certificate data to your AWS account
- Apply the certificate ARN to your app
If you already have your exported SSL certificate in PFX format, skip direct to step 5 (certificate data extraction).
This guide was written using Windows to generate a certificate signing request (CSR) and complete the request. For Mac / Linux, the process will be similar, but you will need to research the commands for creating and completing a CSR, and ideally raise a PR to update this documentation to help other users.
There may be a better way. If so, let us know!
1. Generate the CSR (Certificate Signing Request)
Use PowerShell to execute the certreq -new command.
(The performance-hub repo has a PowerShell script which wraps the certreq -new command to generate a CSR and save it to a text file: .\lib\generateCSR.ps1)
2. Request certificate
Email certificates@digital.justice.gov.uk with the CSR(s) and domain(s), and they will send the certificates.
Note these will be plain text files with the body of the PEM-formatted server certificate from your certificate authority - no private key, and no certification chain (this is important later). The body of the PEM-formatted server certificate is an identity certificate that has been digitally signed using the private key of the certificate authority.
3. Local certificate import
In PowerShell, complete the certificate request, e.g. certreq -accept .\hmpps-your-app.service.justice.gov.uk.crt.txt
You should see something like:
Installed Certificate:
Serial Number: a6700xxxxxxxxde8f8002
Subject: CN=hmpps-your-app.service.justice.gov.uk (DNS Name=hmpps-your-app.service.justice.gov.uk, DNS Name=www.hmpps-your-app.service.justice.gov.uk)
NotBefore: 21/03/2022 00:00
NotAfter: 15/04/2023 23:59
Thumbprint: fad171bxxxxxxxx27d40f
4. Local certificate export
Use the Windows Certificate Manager MMC to export the certificate. It should be in “Personal”.
- Say “Yes” to export the private key
- Use .PFX as the format
- Check “include all certificates in the certification path if possible”
- Specify a password (not a Windows user) for security
- Export to a file
TODO This step describes the GUI method. Investigate using PowerShell Export-PfxCertificate command (https://docs.microsoft.com/en-us/powershell/module/pki/export-pfxcertificate?view=windowsserver2022-ps)
5. Certificate data extraction to plaintext
In a terminal, use this command to extract the certificate and private key: Openssl pkcs12 -in prod-2022.pfx -out prod-cert.txt -nodes
Where “prod-2022.pfx” is the exported PFX file from the previous step, and “prod-cert.txt” is the output file containing plaintext certificate data. You will be prompted for the password you specified in the previous step.
The certificate block in this file should match the certificate block from step 2, but now the file will also contain a private key, and additional blocks for the certificate trust chain. “Your” certificate block will have your domain in the metadata.
6. AWS import
In AWS Certificate Manager, import the certificate using the data in the exported plaintext file from the previous step (certificate body, certificate private key, and full certificate chain).
Developer access has permission to import certificates, so this can be done yourself through the console. Instructions on how to do this are in https://docs.aws.amazon.com/acm/latest/userguide/import-certificate-api-cli.html
You can use the AWS Parameter Store to share the cert and key data with the Modernisation Platform team. The total length of the private key, certificate and chain exceeeds the 4096 character limit for parameters, so we suggest creating multiple parameters:
- One for the private key
- One for your main certificate block
- One parameter each for each block in the certificate chain
If you are renewing an existing certificate, note that AWS Certificate Manager also allows you to re-import an existing certificate with new values. We suggest you avoid this in case something goes wrong. Importing a new certificate with the same domain as an existing certificate is allowed.
When importing the certificate, AWS may tell you that the trust chain is optional, but it’s not. All of the additional certificate blocks (except your “main” cert) must be pasted into this field.
It’s fine to include the metadata (e.g. “bag attributes”) when pasting certificate data into the import fields.
7. Attach new certificates
Copy the ARN of your new certificate, edit the certificate ARN in Terraform, raise a PR and re-deploy the environment(s) to apply the new certificate.
modernisation-platform-environments\terraform\environments\your-app\application_variables.json (it’s the cert_arn value)
Test that your app working correctly, and check that the certificate expiry date reflects your new certificate.
8. Cleanup
Clean up any copies of your certificate data (plaintext or otherwise). Remove:
- local copies of certificates from your cert store
- local copies of certificate data in text files
- certificate data in AWS parameter store