Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
112 lines (77 sloc) 4.26 KB
---
title: Create a network connection to the DCS
weight: 4.4
last_reviewed_on: 2020-03-18
review_in: 6 weeks
---
# 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 key which corresponds to the public certificate. This extra layer of authentication means the DCS can be confident it only sends information to authorised clients.
## Prerequisites
Before setting up mTLS, you’ll need:
* to [generate a private key and request a GDS-signed certificate](/generate-keys-and-request-certificates) - it can take up to 2 working days for the DCS to issue a certificate
* the DCS Certificate Authority (CA) bundle - [request it from the DCS pilot helpdesk](/support) if you have not received it already
## 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](https://curl.haxx.se/) or [Postman](https://www.postman.com/) to make a GET request to the DCS URL.
[Contact the DCS helpdesk](/support) if you do not have the DCS URL.
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 <DCS URL>/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](https://www.ncsc.gov.uk/guidance/tls-external-facing-services)
* 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)
Your standard library may support these features.
### Convert 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:
```<DCS URL>/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](/support).
<%= partial "partials/links" %>
You can’t perform that action at this time.