PDP Public Key Infrastructure (PKI) and cryptographic materials

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)

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.

1. The first party sends the second their public key certificate.
2. The second party can then create an OCSP request using the sender’s certificate number to query with a third party (OCSP responder server).
3. If the certificate is still valid, the third party will send a signed OCSP response.
4. 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.

The JWT will hold one or more claims about the holder or sender, enabling the receiving system to determine what permissions to grant.

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.

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.

Table 1: The attributes of the end user certificate

The certificate chain

The table below presents the attributes of the certificate chain.

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.

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.

Table 3: The contents of cryptographic material package

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).

Figure 4: Successful crypto download screen

Figure 5: Unsuccessful crypto download screen

In the event of an error with the crypto download process, the organisation will receive an email from the PDP support team within one working day.

Configuring mTLS

Within the PDP ecosystem, mTLS is established using client certificates generated by the PDP PKI and server certificates generated by a public Certificate Authority (for example, Let’s Encrypt, Digicert).

mTLS connections to the ecosystem require Elliptic Curve Cryptography (ECC) compatible algorithms to be used.

Example supported algorithms include:

• TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

For all interactions, the party acting as the client (dashboard, PDP CDA or pension provider, scheme or ISP) must present a client certificate issued by the PDP certificate authority. This certificate confirms they are part of the ecosystem and includes their identity in the subject. The party acting as the server must verify the validity of the client certificate presented through the interaction; that it is not expired and not revoked, and that it verifies against the PDP PKI certificate chain.

The certificates to be used in each interaction or API within the ecosystem are shown below.

find-requests (find) API

The find-requests API is hosted by pension providers and schemes. The purpose of the find-request API is to accept and act upon find requests issued by the CDA.

These requests contain the dashboard users’ personal data. When a pension provider or scheme receives a find request it must attempt to match it to their records.

In addition to the PII data, the find request will also provide a user account token. This user_account_token is used to retrieve a PAT (protection API token). The PAT is required by the pension providers and schemes to register and maintain PeI resources.

• Hosted by (Server): ISP, pension providers or schemes
• Called by (Client): CDA
• Server Certificate: Public CA
• Client Certificate: PDP PKI

token API

The token API is hosted by the CDA. It is used by pension providers and schemes and dashboard providers to obtain access tokens in the form of JWTs. The access token JWTs are used throughout the system to allow access to controlled resources.

The token endpoint is an implementation of the standard access token endpoint. This is described at https://datatracker.ietf.org/doc/html/rfc6749#section-3.2.

• Hosted by (Server): CDA
• Called by (Client): Pension providers or schemes or pensions dashboard providers
• Server Certificate: Public CA
• Client Certificate: PDP PKI

rreguri API

The rreguri API is hosted by the CDA. Pension providers and schemes use this API to register and maintain registered PeIs relating to pensions matched as a result of find-requests. The permitted states and transition paths are documented in the pensions identifier (PeI) status and transition section.

Once a PeI has been registered, responsibility for maintaining the PeI belongs with the pension providers or schemes. This responsibility remains with pension providers and schemes until they have deleted the registered PeI.

• Hosted by (Server): CDA
• Called by (Client): Pension providers or schemes or pensions dashboard providers
• Server Certificate: Public CA
• Client Certificate: PDP PKI

view-data API

The view-data API is hosted by Pension Providers or Schemes. It is called by dashboard providers to retrieve pension and pension illustration details. These details will be associated with a pension asset that has been registered under a PeI.

• Hosted by (Server): Pension providers or schemes
• Called by (Client): Pensions dashboard providers
• Server Certificate: Public CA
• Client Certificate: PDP PKI

introspect API

The introspect API is hosted by the CDA. It is used by pension providers and schemes to check whether access tokens provided in requests provide sufficient permissions to allow access to requested data. Specifically, the pension providers and schemes will check if an RPT provided in a view-data request grants sufficient access for the view data to be returned.

• Hosted by (Server): CDA
• Called by (Client): Pension providers or schemes
• Server Certificate: Public CA
• Client Certificate: PDP PKI

perm API

The perm (permissions) API is hosted by the CDA. It is used by pension providers and schemes to retrieve permission tokens. These permission tokens are returned to view-data API clients so that they can obtain the correct access token (RPT) to retrieve data that they have requested.

• Hosted by (Server): CDA
• Called by (Client): Pension providers or schemes
• Server Certificate: Public CA
• Client Certificate: PDP PKI

PeIs API

The PeIs (Pensions Identifiers) API is hosted by the CDA. It is used by dashboards to retrieve the list of PeIs and their descriptions for the citizen.

• Hosted by (Server): CDA
• Called by (Client): Pensions dashboard providers
• Server Certificate: Public CA
• Client Certificate: PDP PKI

mTLS configuration scenarios

The ecosystem interactions where mTLS is used can be categorised as:

1. Dashboard communicating with the PDP central digital architecture.
2. Dashboard communicating with a pension provider, scheme or ISP.
3. Pension provider, scheme or ISP communicating with the PDP central digital architecture.
4. PDP central digital architecture communicating with a pension provider, scheme or ISP.

1. Dashboard communicating with the PDP central digital architecture

Example scenario: Dashboard polling the CDA PeI endpoint

mTLS configuration notes:

• The dashboard needs to download its crypto material from PDP (via the connection portal). The crypto package contains a 'client' certificate for the dashboard.
• The 'client' certificate should be deployed to the dashboard technical solution, and used when initiating mTLS to the CDA. The CDA will validate this ‘client’ certificate through the mTLS setup process, including making a call to the CDA OCSP endpoint to check the revocation status of the certificate.
• The CDA presents a ‘server’ certificate generated from a public CA, which the dashboard will validate through the mTLS setup process. The dashboard will need to trust the public CA issuer of the ‘server’ certificate.

Figure 6: Dashboard communicating with the PDP central digital architecture

2. Dashboard communicating with a pensions provider, scheme or ISP

Example scenario: Dashboard submits a view request to the pension provider, scheme or ISP view API.

mTLS configuration notes:

• The dashboard needs to download its crypto material from PDP (via the connection portal). The crypto package contains a client certificate for the dashboard.
• The client certificate should be deployed to the dashboard technical solution, and used when initiating mTLS to the pension provider, scheme or ISP. This client certificate is generated from the PDP PKI, and thus the pension provider, scheme or ISP must trust it by installing the certificate chain included in the PDP crypto download. The pension provider, scheme or ISP must check the revocation status or the presented client certificate using the CDA OCSP endpoint.
• The pension provider, scheme or ISP must deploy a server certificate from a public CA to their technical solution (their API endpoint host). This will be presented to the dashboard and validated through the mTLS setup process. The dashboard will need to trust public CA issuer of the server certificate.

Figure 7:Dashboard communicating with a pensions provider, scheme or ISP

3. Pension provider, scheme or ISP communicating with the PDP central digital architecture

Example scenario: Pension provider, scheme or ISP registers a PeI with the CDA rreguri API.

mTLS configuration notes:

• The pension provider, scheme or ISP will need to download its crypto from PDP (via the connection portal). The crypto package contains a client certificate for the pension provider, scheme or ISP.
• The client certificate should be deployed to the pension provider, scheme or ISP technical solution, and used when initiating mTLS to the CDA. The CDA will validate this client certificate through the mTLS setup process, including making a call to the CDA OCSP endpoint to check the revocation status of the certificate.
• The CDA presents a server certificate generated from a public CA, which the pension provider, scheme or ISP will validate through the mTLS setup process. The pension provider, scheme or ISP will need to trust public CA issuer of the server certificate.

Figure 8: Pension provider, scheme or ISP communicating with the PDP central digital architecture

4. PDP central digital architecture communicating with a pension provider, scheme or ISP

Example scenario: CDA sends find request to the pension provider, scheme or ISP Find API.

mTLS configuration notes:

• The pension provider, scheme or ISP is required to deploy a server certificate from a public CA to their technical solution (their API endpoint host).
• The CDA presents a PDP client certificate when initiating the mTLS setup process. This certificate is generated from the PDP PKI, and thus the pension provider, scheme or ISP must trust it by installing the certificate chain included in the PDP crypto download. The pension provider, scheme or ISP must check the revocation status or the PDP client certificate using the CDA OCSP endpoint.
• The CDA will validate the server certificate presented by the pension provider/scheme/ISP through the mTLS setup process.

Figure 9: PDP central digital architecture communicating with a pensions provider, scheme or ISP

Configure JWT signing and verification

Within the PDP ecosystem, signed JWTs are used as a secure transport mechanism. They are signed using private keys generated by the PDP PKI and verified using the appropriate public key from the PDP PKI.

RS256 must be used as the algorithm to sign (and verify the signature) of JWTs.

There is a wide range of JWT libraries for the common development languages which can aid with generating, signing, verifying and parsing JWTs. A sample of such libraries is available via JSON Web Token Libraries - jwt.io. 

JWT signing and verification configuration scenarios

The ecosystem interactions where JWTs must be signed or verified can be categorised as either:

1. Pension provider, scheme or ISP communicating with a dashboard.
2. The PDP CDA communicating with a pension provider, scheme or ISP.

1. Pension provider, scheme or ISP communicating with a dashboard

Example scenario: A pension provider, scheme or ISP generates the view data token (JWT) to return to a dashboard as a result of a view pensions data request.

Prerequisite – obtain the crypto package

The pension provider, scheme or ISP will need to download its crypto from PDP (via the connection portal). The crypto package includes the private signing key and the Key ID (KID) for the pension provider, scheme or ISP.

Step 1 – signing the JWT

The private signing key provided in the crypto package is used to sign the JWT. This key ensures that the token in securely signed and can be verified by the recipient

Step 2 – adding the KID to the JWT header

The KID of the private signing key must be included in the header of the JWT. This allows the recipient to identify which key was used to sign the token and verify its authenticity.

Example of a JWT header:

Step 3 – using RS256 as the signing algorithm

The RS256 algorithm (RSA Signature with SHA-256) is used for signing the JWT. This algorithm provides a robust and secure method for signing tokens.

Step 4 – generate the signed JWT

Combine the header and payload, and sign them using the private key with the RS256 algorithm.

2. The PDP CDA communicating with a pension provider, scheme or ISP

Example scenario: The PDP CDA sends a find request, containing a signed user token (JWT), to a pension provider, scheme or ISP.

Prerequisite – access the public signing keys

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.

Step 1 – extract the KID from the JWT header

The JWT header of the user token contains the KID of the private key used to sign the token. This KID is essential for identifying the corresponding public key.

Step 2 – retrieve the public keys from the JWKS endpoint

The pension provider, scheme or ISP should call the PDP CDA JWKS endpoint to retrieve a list of all available public keys. The JWKS endpoint is called via a GET request with no parameters required. For example, GET https://[CDA URL]/ig/jwk_uri

The JWKS response returns all the available public keys (for all KIDs).

Example response:

Figure 10: Example JWKS response

Step 3 – parse the JWKS response

The pension provider, scheme or ISP should parse the JWKS response to retrieve the public key information corresponding to the KID stated in the JWT header. If a cached response is used and the KID is not found, this should trigger a refresh of the cache from the JWKS endpoint.

Step 4 – verify the Token signature

Using the retrieved public key, the pension provider, scheme or ISP can verify the signature of the JWT. This ensures that the token was indeed signed by a trusted entity and has not been tampered with.

By following these steps, the pension provider, scheme or ISP can securely verify the JWT signatures, ensuring the authenticity and integrity of the user tokens received as part of find requests.

Support