API Design Rules Module: Signing

Abstract

This document is part of the Nederlandse API Strategie.

The Nederlandse API Strategie consists of a set of distinct documents.

Status	Description & Link
Informative	Inleiding NL API Strategie
Informative	Architectuur NL API Strategie
Informative	Gebruikerswensen NL API Strategie
Normative	API Design Rules (ADR v2.0)
Normative	Open API Specification (OAS 3.0)
Normative	NL GOV OAuth profiel
Normative	Digikoppeling REST API koppelvlak specificatie
Normative module	GEO module v1.0

Before reading this document it is advised to gain knowledge of the informative documents, in particular the Architecture.

This ADR Module contains the requirements for ADR-HTTP Message and payload signing with JAdES digital signatures.

This module is based on the ISA² IPS REST API Profile v1.0 section 5.2.2 Message And Payload Level Security.

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)

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 [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.

Design rules are technical rules, which should be tested automatically.

List of technical rules

/signing/algorithm: Support the RSASSA-PSS Algorithm
/signing/payload: Apply JAdES detached signatures for payload signing
/signing/message: Apply JAdES HttpHeaders Mechanism for message-level security

technical

/signing/algorithm: Support the RSASSA-PSS Algorithm

Statement: 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 as defined in [RFC7518].

technical

/signing/payload: Apply JAdES detached signatures for payload signing

Statement

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 [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 2.2 Cryptographic Algorithms).

The JWS structure shall be carried in HTTP header field named Payload-Signature. 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 Payload-Signature header fields, the receiver MUST consider the signature invalid.

The Introduction section of [RFC9421] details why message integrity and authenticity are critical to the secure operation of many HTTP/REST applications.

technical

/signing/message: Apply JAdES HttpHeaders Mechanism for message-level security

Statement

When Message-Level Security is considered, the HttpHeaders Mechanism of the JAdES Specification [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 Message-Signature. 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 Message-Signature header fields, the receiver MUST consider the signature invalid.

This section is non-normative.

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}

API Design Rules Module: Signing

Logius Standard
Draft December 15, 2025

Status of This Document

Conformance

Abstract

1. Introduction

1.1 Use Cases

1.2 JWS detached signatures

2. Normative Design Rules

2.1 Summary

List of technical rules

2.2 Cryptographic Algorithms

2.3 Payload signing

2.4 Message signing

A. Signature Representations

B. Tooling

B.1 Digital Signature Service

B.2 JWT, JWS, JWE, JWK, and JWA Implementations

C. References

C.1 Normative references

API Design Rules Module: Signing

Logius Standard Draft December 15, 2025

Status of This Document

Conformance

Abstract

1. Introduction

1.1 Use Cases

1.2 JWS detached signatures

2. Normative Design Rules

2.1 Summary

List of technical rules

2.2 Cryptographic Algorithms

2.3 Payload signing

2.4 Message signing

A. Signature Representations

B. Tooling

B.1 Digital Signature Service

B.2 JWT, JWS, JWE, JWK, and JWA Implementations

C. References

C.1 Normative references

Logius Standard
Draft December 15, 2025