Skip to main content
Table of contents

Sign and encrypt a DCS payload

To build the JSON Web Signature (JWS) and JSON Web Encryption (JWE) wrapper for your JSON object, you must:

  1. Choose a library to use for JWS and JWE.
  2. Build a plain JSON payload.
  3. Create JWS headers.
  4. Sign your JSON payload to get a JWS object.
  5. Encrypt your JWS object to get a JWE object.
  6. Sign your JWE object to complete the process.

The diagram shows the steps you must take to build the signing and encryption wrapper for your JSON object. It shows you start with a plain JSON object. You then sign this object to get a JWS object. You then encrypt this JWS object to get a JWE object. Finally, the diagram shows you sign your JWE object. This will give you a final payload which has been signed, encrypted, and signed again.

Choose a library to use for JWS and JWE

Use a well-maintained library for your language to help you build JWS and JWE objects.

The DCS team have tested that you can make successful DCS checks using these libraries:

Build a plain JSON payload

Create a JSON object containing the details of the passport you want to check, for example:

{
  "correlationId": "21206c34-4d97-47c4-8aee-6fb0d80b311b",
  "requestId": "e1651f51-5db8-4e8c-9cf7-68fd4063404e",
  "timestamp": "1997-07-16T19:20:30.45+01:00",
  "passportNumber": "123456789",
  "surname": "Smith",
  "forenames": [
    "Bob",
    "Dave"
  ],
  "dateOfBirth": "1950-02-13",
  "expiryDate": "2020-01-01"
}

You must generate the following fields in your application:

  • correlationId
  • requestId
  • timestamp

Most programming languages support generating RFC 4122-compliant universally unique identifiers (UUIDs), and ISO 8601-compliant timestamps.

We recommend using version 4 UUIDs as they are based on random input.

Create JWS headers

The JWS headers contain information about how you have signed the payload, along with certificate thumbprints which allow the DCS to look up which certificate you’re using.

For the DCS, you need to set the following headers:

  1. x5t contains the SHA1 thumbprint of your certificate.
  2. x5t#S256 contains the SHA256 thumbprint of your certificate.
  3. alg must be set to one of: RS256, RS384, RS512, PS256, PS384, or PS512.

You must set the x5t and x5t#S256 headers. To set them, you’ll need to have generated thumbprints for your signing certificate.

Depending on the library you use, you might have to manually construct the JWS header. Your header should look like this:

{
  "x5t":"K9gFum5l_xYyHwCniYljJ4Lh_vY",
  "x5t#S256":"gGzb5v_MNfiC0QHur40xZpZyKCVzy7KeZyzFCVi_BrI",
  "alg":"RS256"
}

Sign your JSON payload to get a JWS object

To sign your JSON payload, you’ll need to configure your chosen JWS library. You need to use:

  • the JWS headers you created
  • your signing private key

Encrypt your JWS object to get a JWE object

Encrypting your JWS object using the JWE protocol produces a JWE object. You need to download the DCS public encryption certificate.

The JWE headers contain information about how the payload is encrypted.

You must set the following headers:

  • enc must be set to a value permitted by RFC 7518, for example A128CBC-HS256
  • alg must be set to RSA-OAEP-256
  • typ must be set to JWE
  • x5t contains the SHA1 thumbprint of the DCS encryption certificate
  • x5t#S256 contains the SHA256 thumbprint of the DCS encryption certificate

You must set the x5t and x5t#S256 headers. To set them, you’ll need to have generated thumbprints for the DCS encryption certificate. The DCS will not accept the JWS or JWE objects without these headers.

Your header should look like this:

{
  "enc":"A128CBC-HS256",
  "alg":"RSA-OAEP-256",
  "typ":"JWE",
  "x5t":"xiWgxFMOIw1M4m9LYCnKZk5eHJs",
  "x5t#S256":"PJLEl_B6MFKaMEG6HK7BBdaueJc7e-SiimQfvEpTYj4"
}

Using encryption algorithms

The encrypted component of the JSON Object Signing and Encryption (JOSE) message must use:

You can learn more about these in the JSON Web Algorithms specification.

Sign your JWE object to complete the process

You signed your JSON payload for the first time before you encrypted the payload.

After creating your JWE object, you need to use JWS to sign your payload for a second time.

In your library, you should use the same JWS tools and headers you created when you first signed your JSON payload.

This page was last reviewed on 30 June 2020.