The Government has restated its commitment to delivering pensions dashboards in a written statement.
PDP Public Key Infrastructure (PKI) and cryptographic materials
Guidance for pension providers, schemes and integrated service providers (ISPs).
Overview
This document:
- presents a high-level overview of the Pensions Dashboards Programme (PDP) Public Key Infrastructure (PKI) service
- explains how to use the cryptographic (crypto) materials provided by the PKI service through the PDP connection processes
The PDP PKI governs the issuance of crypto material to provide unique digital identities for the software systems that will participate in the pensions dashboards ecosystem (the ecosystem). It is used to secure end-to-end communications, and to assign an identity to keys so the recipients can identify the issuer.
The PDP PKI provides to ecosystem participants:
- private and public keys for the client applications to sign and verify the signature of JWTs
- client X.509 digital certificates for the client applications to establish a mutual TLS connection with the PDP ecosystem (central digital architecture and pension provider, scheme and ISP endpoints)
The PDP PKI does not provide server certificates for pension provider, scheme and ISP endpoints (for example, certificates to deploy to API host endpoints). Organisations that are hosting endpoints (pension providers, schemes or ISPs) need to provide their own certificate, signed by a public certificate authority.
Back to top
Secure communication technologies used in the ecosystem
PKI concepts and hierarchy
A public key infrastructure is a set of management routines, software and often hardware that allows the management of X509 digital certificates (creation, verification, rotation and expiry). A digital certificate will have identifying content in it (such as name and organisation unit) to identify who is being authenticated. These implementations:
- allow the encryption of digital information in transit (and often at rest)
- ensure that two or more parties communicating with each other can do so securely
- allow the timespan of this security to be checked before communication takes place
Mutual TLS (mTLS)
Transport Layer Protocol (TLS) is a cryptographic mechanism that provides security in communications exchanges over a network – most commonly in email and HTTPS. This protocol allows one or more clients to communicate with and authenticate a server without any third parties being able to see or alter the content.
mTLS uses public key certificates to reciprocally establish authentication between two parties. It does this by using the public key to encrypt messages and each party’s private key to decrypt the messages. In all cases, the messages will be abandoned if the format or timestamp is incorrect (the expiry date is stored in the certificate) or if the certificate has been revoked.
Online Certificate Status Protocol (OCSP)
OCSP is used to obtain the revocation status of an X.509 certificate. This builds on the mutual TLS process when one party wants to communicate with a second party securely.
- The first party sends the second their public key certificate.
- The second party can then create an OCSP request using the sender’s certificate number to query with a third party (OCSP responder server).
- If the certificate is still valid, the third party will send a signed OCSP response.
- The second party can then check this response and, if valid, complete communications with the first party.
JSON Web Tokens (JWTs)
JWT is an open standard (RFC 7519) that defines a secure way to transmit information between two parties as a JSON object over the internet. JWT can be used for authentication or information exchange and consists of 3 parts: a header, a payload, and a signature. Each part is encoded using Base64 and separated by dots.
For example: HEADER.PAYLOAD.SIGNATURE
The JWT will hold one or more claims about the holder or sender, enabling the receiving system to determine what permissions to grant.
Back to top
Use of PKI within PDP
The PDP central digital architecture (CDA) hosts a private Certificate Authority (CA) to generate the certificates and public/private key pairs for PDP ecosystem participants. This is used to:
- create encrypted TLS communication channels
- authenticate systems and API endpoints
- cryptographically sign tokens
Client certificates
End-entity certificates are issued on behalf of pension providers, schemes and ISPs. These are client certificates to support mTLS client authentication.
Unique client certificates are provided for each pension provider, scheme and ISP.
The issued client certificates are based on Elliptic Curve Cryptography (ECC). They remain valid for 1 year, which will soon change to 3 years. PDP will send a reminder to renew certificates before the certificate expires. New certificates are requested through the connection portal.
Revocation
This is managed by Online Certificate Status Protocol (OCSP). The OCSP endpoint will be defined in the Authority Information Access extension for each certificate. The PDP CDA exposes the OCSP endpoint to allow consumers to verify the revocation status of PDP PKI issued client certificates.
Client certificate attributes
The table below presents the attributes of the end user certificates.
| Attribute | Value |
|---|---|
| Common name | <legal name of the provider> |
| Subject name | O=MAPS, OU=<environment>, OU=<PDP issued account ID>, CN=<legal name of the provider> |
| Expiration date | <zoned timestamp> |
| Signature algorithm | sha512ECDSA |
| Signature hash algorithm | sha512 |
| Public key | ECC (256 bits) |
| Public key parameters | ECDSA_P256 |
| Private key algorithm and key length | EC_secp384r1 |
| Supported signing algorithm | SHA256withRSA |
| Issuer | Pensions Dashboards Programme Issuing CA |
| Issuer country | UK |
| Issuer organisation | PensionsDashboardsProgramme |
| Issuer organisational Unit | PKI |
| Issuer common name | Pensions Dashboards Programme Issuing CA |
Table 1: The attributes of the end user certificate
The certificate chain
The table below presents the attributes of the certificate chain.
| Attribute | Value |
|---|---|
| Common name | Pensions Dashboards Programme Issuing CA |
| Subject name | O=MAPS, OU=PKI, CN=Pensions Dashboards Programme Issuing CA |
| Expiration date | <zoned timestamp> |
| Signature algorithm | sha512ECDSA |
| Signature hash algorithm | sha512 |
| Public key | ECC (256 bits) |
| Public key parameters | ECDSA_P256 |
| Issuer | Pensions Dashboards Programme Root CA |
| Issuer country | UK |
| Issuer organisation | PensionsDashboardsProgramme |
| Issuer organisational Unit | PKI |
| Issuer common name | Pensions Dashboards Programme Issuing CA |
Table 2: The attributes of the certificate chain
JWT signing key pairs
Public-private key pairs are issued to pensions providers, schemes and ISPs to be used for signing and verifying the signature of JWTs.
Unique public-private key pairs are provided for each pension provider, scheme and ISP.
The public-private key pairs utilise RS256 (RSA Signature with SHA-256).
All public signing keys used within the PDP ecosystem are available via the PDP CDA JWKS endpoint. The URL of this endpoint is provided in the connection URL guidance.
Signing keys should be changed every 90 days. The primary technical contact (PTC) will be notified by email that they need to request a new key pair on the connection portal.
Participant certificate ZIP file (crypto download)
Through the PDP connection processes, PTCs will need to request cryptographic material, initially for the test environment to support integration testing, and later for the live environment. Different crypto material will be issued for test and live.
The crypto material is delivered as an archived directory and should be securely processed and stored. The table below presents the contents of the package.
| Name | Format | Purpose |
|---|---|---|
| certificate | PEM | An X.509 transport certificate for mTLS connections. |
| certificateChain | PEM | An ordered list of the SSL certificate and the CA certificate is required for the receiver to authenticate the CA that issues the rest of the X.509 certificates. |
| certPrivateKey | PEM | The private key used to sign the CSR that was used to generate the transport certificate (key pair with the certPublicKey). |
| certPublicKey | PEM | The certificate public key (key pair with the certPrivateKey). |
| jwtPrivateKey | PEM | A private key used to sign JWTs (key pair with the jwtPublicKey). |
| jwtPublicKey | PEM | The public key to enable verification of JWT payload signing (key pair with the jwtPrivateKey). It will also be available at the central JWKS endpoint. |
| kid | GUID | The key id of the jwtPublicKey in the central JWKS endpoint. |
Table 3: The contents of cryptographic material package
Back to top
Requesting crypto material
Pensions providers, schemes and ISPs need to download and deploy the crypto materials for the test and live environments. The relevant crypto materials must be deployed to the correct pension provider, scheme or ISP environment.
Requesting and downloading the crypto material
The crypto material generation is initiated by PDP on behalf of the pension provider, scheme or ISP. The crypto material is then made available for download through the ‘Download test crypto materials’ and ‘Download live crypto materials’ connection processes.
The user journey for the ‘Download test crypto materials’ process is shown in the following screenshots. The live crypto download process follows the same high level journey.
At the relevant stage of the connection journey, following the “Prerequisites” stage for the test crypto and the “Live endpoints” stage for the live crypto, the home screen will present the “Start process” button to initiate the crypto download process.
Figure 1: Connect portal home screen, ready to initiate the “Download test crypto” process
Clicking the “Start process” button takes the user to the “Download test crypto” screen. Clicking “Download” on this screen will initiate the crypto download process.
Figure 2: “Download test crypto” screen
Figure 3: Download dialog box
The connect user interface then confirms if the crypto file has been downloaded successfully (figure 5) or if the download has failed (figure 6).