This document is licensed under
Creative Commons Attribution 4.0 International Public License
This ADR Module contains the requirements for ADR-HTTP Message and payload signing with JAdES
This module is based on the ISA² IPS REST API Profile v1.0 section 5.2.2 Message And Payload Level Security
This is a proposed version approved by the technical commitee. Comments regarding this document may be shared through GitHub: https://github.com/Geonovum/KP-APIs/issues
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:
The following algorithms found in [RFC7518] are selected for this profile, to be used in the following form:
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 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 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}
The DSS (Digital Signature Service) project is an open-source software library, aimed at providing implementation of the standards for Advanced Electronic Signature creation, augmentation and validation in line with European legislation and the eIDAS Regulation in particular.
https://ec.europa.eu/digital-building-blocks/DSS/webapp-demo/doc/dss-documentation.html
Libraries implementing JWT and the JOSE specs JWS, JWE, JWK, and JWA are listed here.
https://openid.net/developers/jwt-jws-jwe-jwk-and-jwa-implementations/
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MUST and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.