Rotating keys and certificates
When the certificates containing public keys are due to expire, they must be replaced with new keys and certificates. We call this process certificate rotation. There are 2 sets of keys and certificates:
- the keys you create and the associated certificates
- the keys the Document Checking Service (DCS) creates and the associated certificates
Rotating your keys and certificates
When the certificates containing your public keys are due to expire, you must rotate them. If you do not, your connection to the DCS will stop working.
- The DCS team will contact you to let you know that you need to rotate your certificates.
- Follow the process to generate keys and request certificates. You must generate new keys. Do not reuse old keys.
- When you receive the new certificates, contact the DCS to inform us that you’re ready to start using your new keys and certificates.
- Wait for confirmation that the DCS is ready to start using your new certificates.
- When the DCS team has confirmed we are ready, you can update your configuration to use the new keys and certificates.
Rotating the DCS certificates
When the DCS needs to rotate its certificates, the DCS team will contact you. You’ll need to use the new DCS signing certificate, and the new DCS encryption certificate. If you do not, your connection to the DCS will stop working.
The DCS team will give you at least one month’s notice of the date when we’ll perform the rotation.
At least one week before the scheduled rotation, we’ll send you the new signing and encryption certificates. There are different processes for:
- using the new DCS signing certificate
- using the new DCS encryption certificate
Using the new DCS signing certificate
If you’re able to dual-run signing certificates in your service, you can start using the new DCS signing certificate as your secondary certificate straight away. However, you need to keep using the old certificate as your primary certificate until we rotate to the new key.
The DCS will start using its new signing key at the scheduled time. The DCS team will let you know when we have rotated to the new key. After the DCS has rotated to the new key, you can remove the old certificate.
If you’re not able to dual-run signing certificates, you’ll need to join a coordinated rotation with us on the day. This means you’ll need to join a conference call with us in which, simultaneously:
- we deploy a release of the DCS which uses its new signing key to sign messages
- you deploy a release of your service which uses the new DCS signing certificate
Using the new DCS encryption certificate
You can start using the new DCS encryption certificate straight away, as the DCS can dual-run encryption keys. This means the DCS can accept messages which have been encrypted using either the old or new encryption certificate.
If you’re joining us for a coordinated rotation of your signing certificate, we recommend rotating your encryption certificate at the same time.
We’ll remove the old encryption key shortly after switching the signing key during the scheduled call, so make sure you’re using the new encryption certificate before then.
Enable dual running of the DCS signing certificates
To avoid having to coordinate the rotation of a DCS signing certificate, we recommend that you implement dual running for this certificate in your code. If you’re not using a library with built-in support for this, you’ll need to implement it yourself.
- Make it possible to configure 2 DCS signing certificates.
- Generate certificate thumbprints for these certificates.
- Store the certificates in a map or dictionary using the thumbprint as the key.
- Use the certificate thumbprint from the DCS response to select which certificate to use.