Skip to main content
Table of contents

Message structure

Messages your client exchanges with the Document Checking Service (DCS) must be signed and encrypted using the following Internet Engineering Task Force (IETF) standards:

The JSON object in request and response bodies is protected by a signature and encryption wrapper.

To build the signature (JWS) and encryption (JWE) wrapper for your JSON object, you must:

  1. Sign your JSON object with your signing key using JWS.
  2. Encrypt your signed JSON object with your encryption key using JWE.
  3. Sign the encrypted content with your signing key using JWS.

Signing messages

Signing provides the receiver with assurance of who authored the message. The signature also guarantees that the message hasn’t been tampered with since the author signed it.

Your client signs requests with your private signing key. When receiving the request, the DCS uses your signing certificate to verify that the request came from your client.

Responses from the DCS are signed with the DCS’s private signing key. Your client uses the DCS’s signing certificate to verify that the response came from the DCS.

Signing keys and certificates

You must generate a private signing key and raise a certificate signing request to our Certificate Authority. Details about how to raise a certificate signing request with our Certificate Authority will follow after the expression of interest stage of the DCS pilot.

You will receive the DCS’s signing certificate from the DCS team.

Signing algorithms

Signatures in the JOSE message must use RSASSA-PKCS1-V1_5 with the SHA-256 hashing algorithm for RSA-based keys, as detailed in the JSON Web Algorithms specification.

The alg header in the JWS object must be set to RS256.

You must set the x5t and x5t#256 headers. The DCS uses these headers to confirm that the certificate used to sign the JWS object was signed by our Certificate Authority.

Encrypting messages

Encryption provides the sender with assurance that only the intended receiver can see the message.

Your client encrypts requests using the DCS’s encryption certificate. When receiving the request, the DCS uses its private encryption key to decrypt your request.

Responses from the DCS are encrypted with your encryption certificate. Your client then uses your private encryption key to decrypt the response from DCS.

Encryption keys and certificates

You must generate a private encryption key and raise a certificate signing request with our Certificate Authority. Details about how to raise a certificate signing request with our Certificate Authority will follow after the expression of interest stage of the DCS pilot.

You will receive the DCS’s encryption certificate from the DCS team.

Encryption algorithms

The encrypted component of the JOSE message must use:

The alg header in the JWE object must be set to RSA-OAEP.

The enc header in the JWE object must be set to A128CBC-HS256.

You must set the x5t and x5t#256 headers. The DCS uses these headers to confirm that the certificate used to encrypt the JWE object was signed by our Certificate Authority.

This page was last reviewed on 15 November 2019.