Generate keys and request certificates
To send requests to the Document Checking Service (DCS) you’ll need to generate separate keys and certificate requests for:
- mutual TLS Client Authentication (mTLS)
- JSON signing
- JSON encryption
You request the certificates by raising a certificate signing request (CSR).
You must enrol with the GDS Certificate Authority (CA) before you can raise a CSR.
It can take up to 2 working days to process the CSR.
This documentation gives examples of how you would follow this process using OpenSSL. You can use other methods if you prefer.
Keep your keys secure
You must make sure you:
- store your keys securely
- limit access to your key material
If you suspect your keys have been compromised:
- tell the DCS support team immediately
- stop using the compromised keys
You must handle your integration keys as securely as your production keys. The DCS integration environment is a live service.
Generate a private RSA key
Generate a private RSA key using OpenSSL by entering this code into a terminal:
$ openssl genrsa -out <private key filename>.pem 2048
Check you write the RSA key file to your current directory.
Create a Certificate Signing Request (CSR)
From your private RSA key, enter this code to create the CSR:
$ openssl req -new -sha256 -key <private key filename>.pem -out <CSR filename>.csr
You’ll see the following messages:
You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) : State or Province Name (full name) : Locality Name (eg, city) : Organization Name (eg, company) : Organizational Unit Name (eg, section) : Common Name (eg, fully qualified host name) : Email Address : Please enter the following 'extra' attributes to be sent with your certificate request A challenge password :my challenge phrase
You must enter information for the following fields:
Country(for example, UK)
challenge password- this can be any password you choose, but note this down as you’ll need to enter it again when submitting the CSR
You can leave the other fields blank.
Common Name, use the naming convention:
[Organisation name] [certificate purpose, i.e. ‘JSON Encryption’, ‘JSON Signing’ or ‘TLS’] [environment, for example ‘Integration’ or ‘Production’] [date CSR created]
Bob’s Widgets TLS Integration 2020-02-02
Once you’ve filled in the information, you will have created the CSR.
Check you write the CSR file to your current directory.
Submit the CSR to the Certificate Authority
To submit the CSR:
- Go to the GDS Certificate Authority (CA) - the DCS team will have emailed you a link and you can contact the helpdesk if you cannot find the link.
- Select Enrol.
- Upload your CSR file.
- Fill in the details on the enrolment form - some details will be pre-populated from data in the CSR, and you should not change these fields.
- When filling in the details, make sure you choose the correct ‘Certificate profile’ - choose either JSON signing, JSON encryption or TLS.
Use the challenge password you chose when you created the CSR.
Receive and save your certificates
- You’ll receive your certificate by email in Privacy Enhanced Mail (PEM) format.
- Copy the certificate text from the email.
- Save it to a file with a .crt extension.
Depending on the library you chose, you may need to convert the certificate you’ve received into a format your system can use. You can use tools such as OpenSSL for example, to convert the
PEM certificate into
$ openssl x509 -inform PEM -outform DER -text -in <pem filename> -out <der filename>
If you do not receive your certificate, contact the helpdesk.
Download DCS public certificates
Once you have your certificates, you will also want to get the DCS public certificates for the integration environment.
- Download the DCS public encryption certificate.
- Download the DCS public signing certificate.
- Download the DCS Certificate Authority (CA) certificate bundle.