Verify credentials securely
GOV.UK Wallet implements the ISO/IEC 18013-5 specification for reader authentication. It will operate a Certificate Authority (CA) that will establish a chain of trust to make sure only authorised and registered Digital Verification Services (DVS) can consume and verify credentials.
As an authorised DVS, you will be able to:
- use your own CA and issue end-entity certificates to trusted clients
- read and process data from the GOV.UK Wallet sandbox and production environments
This page will help you to understand how to:
- connect to GOV.UK Wallet’s chain of trust and root certificate
- operate your own certificate authority
- issue end-entity verifier certificates
When GOV.UK Wallet releases reader authentication, you must have valid verifier certificates for GOV.UK Wallet to authenticate your requests for data.
Connect to GOV.UK Wallet’s chain of trust and root certificate
The Government Digital Service (GDS) publishes a root certificate that will be pinned to the GOV.UK Wallet app. The root certificate establishes the chain of trust that authenticates your request for data from a holder’s verifiable credentials. All your verifier certificates must connect to this chain and land on the root.
Operate your own certificate authority
GOV.UK Wallet CA will issue you with an intermediate sub-CA certificate that you can use to operate your own CA. You’ll need to request this certificate by sending a Certificate Signing Request (CSR). Once received, you need to install this certificate into your own X.509 CA so you can issue your own end-entity verifier certificates.
Issue end-entity verifier certificates
You can use your sub-CA certificate to issue end-entity verifier certificates to your apps, devices and trusted clients. This lets your clients consume and verify credentials in person. In the future, they’ll be able to verify online.
Your issued end-entity verifier certificates will form a part of the chain of trust with the root certificate. When a verifier starts the in-person sharing flow, they’ll present their end-entity verifier certificate and the chain of certificates will authenticate their request.
It’s your responsibility as a DVS to manage your CA and issue end-entity verifier certificates according to industry standards for data security. You should follow the National Cyber Security Centre (NCSC) guidance on managing certificates and developing a public key infrastructure (PKI).
Follow end-entity certificate requirements
You will only be able to issue end-entity verifier certificates one level down from your own. Your intermediate sub-CA certificates will be revoked if you:
- are removed from the digital identity and attributes trust framework
- breach the agreed terms with your engagement manager
- are otherwise compromised
The sub-CA certificate GOV.UK Wallet CA issues to you has a NameConstraints extension that restricts the end-entity certificates you can issue. The Organisation Name O= in the Subject Distinguished Name of any end-entity certificates you issue must match the Organisation Name O= in your sub-CA certificate.
Include a privacy policy in your issued certificates
Every time you request information from a user, GOV.UK Wallet must show users a link to your privacy policy. GOV.UK Wallet expects the link to be part of your issued certificate, and will reject any certificates without a privacy policy link.
You must add your privacy policy in the Subject Information Access extension of your certificates. You must use the GDS Object Identifier (OID) of 1.3.6.1.4.1.66559.1.1 to specify your URI.
Your URI must:
- be a full URL and not a relative path
- use the
httpsscheme, ignoring case - include a host name
- not contain user information (for example,
user:pass@) - use ASCII characters with no spaces
- be no more than 2048 characters long
This is an example of a correctly formatted privacy policy URI in a certificate, shown as openssl output:
Subject Information Access:
1.3.6.1.4.1.66559.1.1 - URI:https://www.example.com/privacy