Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
78 lines (45 sloc) 3.72 KB
---
title: Message structure
weight: 4
last_reviewed_on: 2019-11-15
review_in: 6 weeks
---
# 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:
- [JavaScript Object Notation (JSON)][JSON]
- [JavaScript Object Signing and Encryption (JOSE)][JOSE]
- [JSON Web Signature (JWS)][JWS]
- [JSON Web Encryption (JWE)][JWE]
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.
<%= image_tag "dcs-message-structure.svg" %>
## 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][jws-alg-header] must be set to `RS256`.
You must set the [`x5t`][jws-x5t-header] and [`x5t#256`][jws-x5t256-header] 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:
* [RSAES-OAEP] as the algorithm, detailed in the [JSON Web Algorithms specification][JWA]
* [A128CBC-HS256] as the encryption method, detailed in the [JSON Web Algorithms specification][JWA].
The [`alg` header in the JWE object][jwe-alg-header] must be set to `RSA-OAEP`.
The [`enc` header in the JWE object][jwe-enc-header] must be set to `A128CBC-HS256`.
You must set the [`x5t`][jwe-x5t-header] and [`x5t#256`][jwe-x5t256-header] headers. The DCS uses these headers to confirm that the certificate used to encrypt the JWE object was signed by our Certificate Authority.
<%= partial "partials/links" %>
You can’t perform that action at this time.