ADR-HTTP Message and payload signing with JAdES

This module specifies the use of JAdES signatures for HTTP message and payload siging. The module is directly based on the ISA² IPS REST API Profile v1.0 (which was a result of the REST API Pilot project for eDelivery)

Use Cases

This module is applicable when there is a need for assurance of end to end message integrity and authenticity between client application and server application. In the context of HTTP messages signing header elements (for example HTTP operation (GET/POST/UPDATE/DELETE) and resource path / parameters, or timestamps) together with payload provides an extra level of protection against manipulation of the message.

In a complex IT landscape the path between client and server can go over several intermediary components/systems in which case end to end integrity and authenticity can be especially relevant. (In this case TLS is terminated in each step on the path and does not protect the http-message in transport fully end to end).

This module enforces the use of JWS detached signatures following the HTTP Headers Mechanism of the ETSI ESI JAdES specification [ETSI-JADES].

This structure is enforced for the following reasons:

• JWS, being a simple JSON Structure, can be supported by clients in a light context, while specifications like the ETSI ESI ASIC containers are more difficult to do.
• JWS in detached form does not change the payload structure, meaning that a client not supporting the validation of signature can continue to operate as if there was no signature applied.
• JWS Detached can be transported using an HTTP header, making its presence unintrusive and easily transportable.

The following algorithms found in [RFC7518] are selected for this profile, to be used in the following form:

• The RSASSA-PSS Algorithm MUST be supported, with a key length of at least 256 bits. The value "PS256" for the alg parameter MUST be used in this case as defined in [RFC7518].

Payload signing ensures the integrity and authenticity of the payload part of the message. When payload signing is considered, the Detached JSON Web Signatures following the JAdES specification [ETSI-JADES] MUST be applied with the following restrictions:

• The JWS content (Data to be Signed) MUST be detached from the signatures as defined in [RFC7515] Appendix F.
• The signed SigD parameter object MUST be present in the JWS headers, denoting the use of the JAdES detached header profile.
• The value of the mId parameter MUST be set to "http://uri.etsi.org/19182/HttpHeaders".
• The pars array of the SigD MUST contain only the element "digest", denoting that for the calculation of the signature only the digest of the HTTP payload must be taken into account, according to [RFC3230].
• The alg parameter MUST be set to the correct value depending on the algorithm used (see above).

The JWS structure shall be carried in HTTP header field named nlgov-adr-payload-sig. The header field can be used in both requests and responses. The header field MUST not appear more than once in a message; if a message contains multiple nlgov-adr-payload-sig header fields, the receiver MUST consider the signature invalid.

The Introduction section of [DRAFT-IETF-HTTPSBIS-MSG-SIGS] details why message integrity and authenticity are critical to the secure operation of many HTTP/REST applications. When Message-Level Security is considered, the HttpHeaders Mechanism of the JAdES Specification [ETSI-JADES] MUST be used, with the following restrictions applied:

• The JWS content (Data to be Signed) MUST be detached from the signatures as defined in [RFC7515] Appendix F.

• The signed SigD parameter object MUST be present in the JWS headers, denoting the use of the JAdES detached header profile.

• The value of the mId parameter MUST be set to "http://uri.etsi.org/19182/HttpHeaders".

• The pars array of the SigD MUST contain at least the following elements:

  • the element "(request-target)", for containing the HTTP Request URI
  • the element "host", for containing the host the message was submitted to, if present
  • the element "origin", for containing the scheme, hostname, and port from which the request was initiated, if present
  • the element "content-encoding", if present
  • the element "content-type", if present
  • the element "content-length", if present
  • the element "digest", for taking into account the Digest header that contains the hash value of the HTTP payload.

• The alg parameter MUST be set to the correct value depending on the algorithm used (see above).

Implementations that make use of the HTTP Header fields for data representation SHOULD also include these header fields in the pars array. The JWS structure MUST be carried in HTTP header field named nlgov-adr-message-sig. The header field can be used in both requests and responses. The header field MUST not appear more than once in a message; if a message contains multiple nlgov-adr-message-sig header fields, the receiver MUST consider the signature invalid.

The folowing example is strictly informative !

openapi: 3.1.0
info:
    title: JAdES Signatures
    summary: An example showcasing JAdES signatures
    description: An example showcasing JAdES signatures as JWS detached signatures for securing a sample REST endpoint (/certificate)
    termsOfService: https://domain.server.io/terms-of-service
    license:
        name: EUPL-1.2 or later
        url: https://eupl.eu/1.2/en/
    version: 1.0.0
externalDocs:
   description: The ISA² IPS REST API Core Profile
   url: https://joinup.ec.europa.eu/collection/api4dt/document/isa2-ips-rest-api-profile
servers:
- url: https://domain.server.io/v2
tags:
- name: DetachedPayloadSignature
  description: Operations using payload security
- name: DetachedMessageSignature
  description: Operations using message-level security
paths:
    /openapi:
        get:
            summary: Returns the OpenAPI Document for the API
        ...
        responses:
        200:
            description: ...
            content: {
               $ref: 'https://spec.openapis.org/oas/3.1/schema/2021-05-20'
               ...
            }
    /certificate:
    get:
      tags:
      - DetachedMessageSignature
      summary: Get a Certificate
      securitySchemes:
        OAuth2:
           type: oauth2
        flows:
           authorizationCode:
              authorizationUrl: https://example.com/api/oauth/dialog
              scopes:
                 send:message: send a message
       ...
      responses:
      200:
         headers:
            nlgov-adr-message-sig:
               $ref: '#/components/headers/nlgov-adr-message-sig'
          description: List of Certificates
          content: { ... }
components:
   headers:
      nlgov-adr-payload-sig:
         schema:
             $ref: '#/components/schemas/JwsCompactDetached'
      nlgov-adr-message-sig:
         schema:
             $ref: '#/components/schemas/JwsCompactDetached'
   schemas:
      JwsCompactDetached:
         title: The format for the message-level and payload signature
         description: Defines the string pattern as a regular expression that
         MUST be followed to represent detached JWS compact tokens
        "$id": https://raw.githubusercontent.com/isa2-api4ips/rest-api-profile/main/api-core-profile/components/schemas/jws-compact-detached.json
        "$schema": https://json-schema.org/draft/2020-12/schema
         type: string
         format: jws-compact-detached
         pattern: ^[A-Za-z0-9_-]+(?:(\\.\\.)[A-Za-z0-9_-]+){1}