Skip to main content
Table of contents

Create a network connection to the DCS

When making requests to the DCS, you send messages over HTTPS. These messages are secured by mutual Transport Layer Security (mTLS), which is sometimes referred to as ‘client certificate authentication’ or ‘X509 client certificate authentication’.

The DCS and your service use mTLS to prove to each other that they possess the private keys which correspond to their public certificates. This extra layer of authentication means the DCS can be confident it only sends information to authorised clients.

Prerequisites

Before setting up mTLS, you need to:

Test your connectivity to the DCS by making a GET request

You need to have network access to the DCS. You can check if you have this access by using a tool like curl or Postman to make a GET request to the DCS URL: https://dcs-integration.ida.digital.cabinet-office.gov.uk/checks/passport.

There are many ways to check if you have the correct access. For example, using the curl command line utility tool:

curl --cacert <path to CA bundle> \
     --cert <path to client certificate> \
     --key <path to private key> \
     -v https://dcs-integration.ida.digital.cabinet-office.gov.uk/checks/passport

You should get a response similar to this:

...
< HTTP/1.1 200 OK
< Server: nginx
< Date: Mon, 24 Feb 2020 15:51:42 GMT
< Content-Type: application/json
< Content-Length: 40
< Connection: close
< Vary: Accept-Encoding
< Strict-Transport-Security: max-age=31536000
<
* Closing connection 0
* TLSv1.2 (OUT), TLS alert, Client hello (1):
{"available":true,"scheduledOutages":[]}

If you see anything different, speak to the team that manages your infrastructure.

Choose a library to make HTTPS calls

You need a library in the language you’re using that supports:

  • TLS version 1.2
  • client certificates (so you can add your private and public keys)
  • a custom certificate chain (so you can use the DCS CA bundle, which includes certificates signed by the private GDS CA)

The DCS team have tested that you can make successful requests using these libraries:

Converting your private key to another format

Not all HTTPS libraries can process a key in Privacy Enhanced Mail (PEM) format. You might need to convert the private key into a format your library can use. For example, this command would convert the private key to PKCS 8 format:

openssl pkcs8 -in <path to private key file>.pem -nocrypt -out <new private key file>.pk8 -topk8 -outform DER

Check your connection works

To prove mTLS and your connection is working correctly, you can call the status endpoint.

Call the status endpoint

Configure your chosen language library to use:

  • the DCS CA bundle
  • your client certificate
  • your private key

Using the code you’ve written using your chosen library, make an HTTPS GET request to:

https://dcs-integration.ida.digital.cabinet-office.gov.uk/checks/passport

You should receive a response with an HTTP status of 200 and a JSON body as follows:

{
"available": true,
"scheduledOutages": []
}

This response shows mTLS is working and you can now make secure requests to the DCS.

Understand and resolve potential errors

You may receive error messages if you have supplied the wrong file to your HTTPS library.

What the error message says What this means
No required SSL certificate was sent You did not send the client certificate
SSL certificate error You sent the wrong client certificate
SSL certificate problem: unable to get local issuer certificate You did not use the correct CA bundle which means your service has not trusted the DCS certificates

If you have any of these errors and you cannot resolve them, contact the DCS helpdesk.

This page was last reviewed on 30 June 2020.