Matching Service Adapter encryption
If your connection to GOV.UK Verify involves a Matching Service Adapter (MSA), you are responsible for keeping its encryption and signing certificates up to date.
You must update the certificates containing your MSA’s public keys before they expire. If you do not, your users will not be able to access your service using GOV.UK Verify.
Rotate your MSA encryption key and certificate
Step 1. Create a new self-signed encryption certificate
Use your preferred method to generate a new private key and self-signed certificate pair.
Make sure the private key is PKCS #8 formatted and DER encoded.
The self-signed certificate must be:
- valid for one year
- in X.509 format and PEM encoded
The terminal will prompt you for information. You must provide a The There is no mandatory naming convention for For example, the common name could be
See an example
# generate your key and self-signed certificate
openssl req -x509 -newkey rsa:2048 -days 365 -nodes -sha256 \
-keyout <private-key>.key -out <certificate>.crt
# convert your MSA key to use DER encoding
openssl pkcs8 -topk8 -nocrypt \
-in <private-key>.key -out <private-key>.pk8 -outform DER
Common Name. All other information is optional.
Common Name is the part of the certificate metadata that helps you identify that certificate more easily. You can use the
Common Name to check you’ve uploaded the right certificate when using the GOV.UK Verify Manage certificates service.
Common Name, but it’s useful during troubleshooting if you include the:
Common Name must not contain underscores.
The terminal will prompt you for information. You must provide a
There is no mandatory naming convention for
For example, the common name could be
Step 2. Add the new encryption key and certificate to your MSA configuration
Add a second list item containing the details for your new key and self-signed certificate under
encryptionKeys in your MSA configuration.
Restart the MSA to implement the configuration changes.
encryptionKeys: - publicKey: certFile: msa_encryption_2016.crt name: MSA Encryption 2016 privateKey: keyFile: msa_encryption_2016.pk8 - publicKey: certFile: msa_encryption_2017.crt name: MSA Encryption 2017 privateKey: keyFile: msa_encryption_2017.pk8
||The name of the
||A meaningful name for your certificate which is published in your MSA’s metadata|
||The name of the
Restart the MSA to implement the configuration changes. The MSA can now use both the new and old keys to decrypt SAML messages.
Step 3. Upload the new encryption certificate
Upload your new encryption certificate to the GOV.UK Verify Manage certificates service.
This starts a deployment process to replace your old MSA encryption certificate with the new one in the GOV.UK Verify Hub configuration. During deployment the GOV.UK Verify Hub will continue to use your old certificate. The deployment process does not cause any connection downtime.
When the deployment is complete, the GOV.UK Verify Hub will be using your new certificate to encrypt messages for your service.
The deployment process takes approximately 10 minutes. You will receive an email confirmation when the GOV.UK Verify Hub starts using your new encryption certificate. You can also check the deployment status on the GOV.UK Verify Manage certificates service dashboard.
Wait for deployment confirmation before moving to the next step.
Step 4. Delete the old MSA encryption key and certificate
The email from the GOV.UK Verify team confirms that GOV.UK Verify Hub is now using your new certificate to encrypt messages for your service. This means you can remove the old encryption key from your MSA configuration.
Delete the old encryption key and certificate from your MSA's configuration. Restart the MSA to implement the configuration changes. While both old and new keys are in use, you may see error messages in the logs with the description `Unwrapping failed`. These messages appear because the MSA attempts to decrypt the SAML message using each key in turn. You can safely ignore these messages. However, do not ignore any other error messages related to SAML decryption.
Once you’ve removed the old encryption key, your MSA only uses the new encryption key to decrypt messages from GOV.UK Verify Hub.