(closed) Comments on "Piloting a REST API extension of CEF eDelivery: Project Scope v0.9, v1.0 & v1.1"

Drafting suggestions adopted, questions clarified.

General:

- Let me start by saying that I like the compact and clear format and structure of the document. It makes it highly readable.

Business Need/Problem:

- I think you can make this case even stronger by, in addition, referring to one of the policies of the ‘Shaping Europe’s digital future’ strategy namely: ‘From the Public Sector (PSI) Directive to the open data Directive’ https://ec.europa.eu/digital-single-market/en/public-sector-information-psi-directive-open-data-directive

Business Need/Problem:

- As another addition to your example, RESTful API’s are also used for integrating data-sources into a data process flow. Meaning when a clerk is processing data for whatever reason, the application s/he is using can directly access data from ‘external’ data sources by the use of RESTful API’s. The applications aren’t light applications.

‘Light application’ renamed to ‘light context’ and drafting expanded on envisaged architectural scenarios.

Opportunity:

- Suggestion for the first sentence:

The addition of a profile for direct data access to the eDelivery building block will extend its usability and thereby help its users, organisations across the EU.

- Suggestion for the last part of the second sentence:

...make the building block easier to adopt in projects where the eDelivery AS4 profile is not required.

Opportunity:

- Use: ‘RESTful API’ i.s.o. ‘Messaging RESTful API’, messaging is related to eDelivery AS4 with RESTful API data is being exchanged.

Document modified more widely to propose a richer REST API profile instead of one limited to messaging.

Solution:

- Use: ‘RESTful API’ i.s.o. ‘Messaging RESTful API’.

Analyse:

- Second part of first sentence, 'some of the characteristics embedded in the current eDelivery AS4 profile need to be revisited’, why is that needed we can leave the eDelivery AS4 profile as is, we are all very happy with it!

Document modified to clarify that REST API is to be a separate profile than the AS4 one, and not an alternative to it.

Goal clarified to address communication patterns in different areas than AS4, with no impact on the AS4 profile.

Message exchange patterns:

- With RESTful API you can only exchange data in a synchronous way, asynchronous will not be possible since one of the architectural constrains of RESTful is that it is stateless. Meaning no client context being stored on the server between requests and therefor an asynchronous reply cannot be generated.

Document modified to clarify that the asynchronous perspective considered is a business, not a technical one.

API signature/Signal messages/Error messages:

- It is a good idea to define the format of these type of messages to standardise is it within the use of API’s. However this is part of the layer on top of the RESTful API layer, since, as mentioned before, RESTful API is stateless.

Pilot:

The pilot will help us to get more experience with the use of the RESTful API profile within eDelivery.

Missing in the scope:

- Besides all the items discussed in this document there is also a need for the governance of the RESTful API’s used ‘under’ the eDelivery profile. First of all it would be nice to have an eDelivery RESTful API registry where you can find the API’s being used by the various institutions. Making it easier to access them, develop applications on top of them and help with developing new API’s. The can be centralised as well as a distributed register. It will also help us to standardise API’s within and between domains thereby providing easier access.

Document modified to clarify that the project scope is limited to metadata support for a service registry, not the creation of a service registry itself. The creation of a service registry, while necessary, is not within the mandate or possibilities of this ISA² action.

Then about the Possible Scenarios for the eDelivery – EBSI pilot:

Both scenarios look good, be aware that blockchains don’t have a great response time. So make sure that the interactions with the blockchain are not part of time critical processes within the message exchange. 

Ideally, the profile could be used as-is – without adaption - in different message/data exchange networks. It would enable publishing an API that's compliant with the profile through multiple channels without having to implement several channel specific versions of the same API. In this context, channels can be defined as different data exchange platforms where a service can potentially be published, e.g., eDelivery, X-Road, SDG, an API GW (e.g. Kong), etc. Quite often a single service or API must be published on different platforms and in the worst case the API needs to be adapted to some platform specific requirements. This may lead to a situation where multiple versions / flavours of the same API must be maintained side by side. Of course, this is something that should be avoided.

Definition of Light-Context and Security

The "light context" has a different approach to security compared to the AS4 profile. The eDelivery AS4 profile defines in detail how the message exchange is secured and the level of security between the access point is always the same regardless of the use case. In the light context the level of security may vary between different use cases and implementations - rather than being constant, the level of security is more flexible and can be adapted to the requirements of a particular use case. However, the eDelivery REST API profile should defined a framework for this - the profile must enable the use of different security levels instead of forcing everyone to use the same level.

Identity

In the AS4 4-corner model the identities of the message exchange parties are defined using the eDelivery ebCore Party ID profile. Possibility to include the identity of the client information system in a service request should be considered for the REST profile too. In a 3-corner model where corners 1 and 2 are presented by a lightweight REST client it would be beneficial for the corner 3 (access point) to be able to identify the client using the same identifier scheme that’s used by a corner 2 access point. In practice, the client identifier could be included in the request using an HTTP header. Of course, a more complicated question is how the corner 3 can verify the lightweight REST client’s identity – the corner 3 must be able to verify that the client really represents the organisation which identifier is included in the request.

For example, X-Road SOAP protocol uses SOAP headers and REST protocol HTTP headers to include the identifiers of the data exchange parties in requests/responses:

SOAP

https://github.com/nordic-institute/X-Road/blob/develop/doc/Protocols/pr-mess_x-road_message_protocol.md#22-message-headers

REST

https://github.com/nordic-institute/X-Road/blob/develop/doc/Protocols/pr-rest_x-road_message_protocol_for_rest.md#43-use-of-http-headers

In addition to defining how identifiers are transferred technically, even bigger challenge in a wider scope is how to map identifiers of different data exchange platforms to each other. For example, an eDelivery policy domain and an X-Road ecosystem are connected with each other using a gateway solution. Both platforms have their own identifier schemes both structurally and semantically.

Document modified to capture the topic of carrying the client identifier, as distinguished from verifying the client's identity.

Media types and Data types

Both JSON and XML are widely used content types in REST services. Wouldn't it make sense to aim for a content type agnostic profile or at least support both XML and JSON.

Document modified to state that proposed solutions will avoid constraining the payload to the largest extent possible.

Document modified to state preference for the use of HTTP features.

Integrity & confidentiality

Enforcing the use of a modern version of TLS (eg. 1.3) for integrity and confidentiality of the channel is OK. However, the same certificate that’s used for the channel, should not be used for encrypting and/or signing the payload. The following specification that defines a payload agnostic signature mechanism on HTTP could be considered:

Document modified to include the suggestion to analyse message-signing approaches in addition to TLS.

Document modified to include 'Signing HTTP Messages' in the list of standards to analyse.

n-Corners

Please consider that 2-Corner is valid for both REST and RPC.

Reference to RPC removed.

Full support for 4-corner model is out of scope.

As a general guideline, using SemVer, OpenAPI3+, the json media-type and json-schema as a schema descriptor are good starting points.

Definition of Light-Context

I am not sure about the definition of "light context": probably it's not related to the "non-enterprise" status of the provider but to the relation between the overall resources, the size of the workload and business goals. For example it could apply:

• when a more efficient approach is needed due to a large volume of transactions (high throughput scenario);
• in a cloud environment (is that an enterprise data centre?), to rationalize costs in order to provide free services for citizens.

Implementation Languages

The components table specifies the programming languages to be used: I think this choice should be deferred as we have currently different approaches to follow. Eg. for the mock-up server there are different opensource products specialized for this (eg. stoplight/prism in javascript or zalando/connexion in python); moreover serverless approaches eg. with AWS lambdas or GCP functions are quicker to implement and cost-efficient to run.

Similar considerations apply to the micro-service to be implemented.

Security and Identity

We should enable the support of different security requirements and in the long run consider the possibility of starting with a restricted framework using a subset of the mentioned technologies (eg. MTLS, OAuth2, ..).

Consider that Channel authentication (eg. MTLS) in a multiplexed environment is questioned by some security experts and criticized as a layer violation (See as an example RFC8740 and RFC7540#5.4.1), while an approach which authenticates each call is considered more secure. 

Nonetheless I am not sure that a REST architecture requires per-request authentication (we could ask Erik) and provided you avoid multiplexing requests or coalescing connections with different authentication/authorization scopes you can reuse the MTLS-authenticated HTTP connection and send multiple requests without re-authenticating.

About mentioned protocols, SAML and XACML are probably not very lightweight.

Document modified to state that the REST API profile should be designed to enable the use of different security levels instead of imposing a single, standard one.

While various options will analysed, lightweight ones will be preferred wherever possible.

Media types and Data types

Aiming at a more efficient resource usage (see above) I agree we should focus our attention on the application/json media-type, being careful of not inhibiting the usage of application/xml and or application/x-yaml. On the other hand I wouldn't stress the project to consider other general-purpose media-types.

For special cases (eg. binary data, encrypted or signed content, ...) in a REST context we should leverage HTTP features, including:

• media-type and content-negotiation;
• content-coding;
• range-requests;
• partial representations;

so we could constrain the media-type only if it is functional to achieve some business goals, e.g. to implement service-management policies like error serialization, rate-limiting or retry mechanisms. See for example:

• RFC7808 for serializing json and xml errors  https://tools.ietf.org/html/rfc7807 allows using an extensible registry of errors based on URI;
• I-D.polli.ratelimit-headers for conveying ratelimit information https://tools.ietf.org/html/draft-polli-ratelimit-headers-03 (note, I'm one of the editor but it has been implemented by Red Hat, Kong and others);

Document modified to state that proposed solutions will avoid constraining the payload to the largest extent possible.

Document modified to state preference for the use of HTTP features.

Document modified to include RFC 7807 in the list of standards to analyse.

Internet Protocols - IP / TCP / HTTP

I expect the PoC to work independently of the IP, TCP and HTTP version.

I'd avoid taking care of the network layers below HTTP/HTTPS - namely IP and TCP - unless they are useful to achieve specific goals. This is because our project should work:

• with both IP versions (IPv4, IPv6);
• with TCP and UDP, as HTTP/3 is based on UDP and implements its own reliability mechanisms;
• with different HTTP messaging versions (HTTP/1.1, HTTP/2 and their evolutions).

To be more clear, the HTTP protocol is described by two layered specifications:

• MESSAGING (what happens on the wire, under evolution HTTP/1.1, HTTP/2, HTTP/3 aka QUIC)
• SEMANTICS (this is/should be independent from MESSAGING).

While we should consider HTTP/2, it is important that the semantic aspects of our design work at the SEMANTIC layer so that we can work independently of the MESSAGING layer.

Removed protocols that should not be part of the REST API profile.

Introduced distinction between HTTP MESSAGING and SEMANTICS layers.

Integrity & confidentiality

Enforcing the use of a modern version of TLS (eg. 1.3) for integrity and confidentiality of the channel is ok: I think we could even shorten that part just stating it. Consider that TLS just covers the channel and it does not provide suitable means to exchange Public Keys nor encrypt the payload body: we should be aware that TLS certificates should not be used to encrypt or sign payloads to avoid cross-protocol attacks. 

To encrypt or sign the payload there are various specifications, and there is an interesting work of the IETF (based on a previous I-D) for providing a payload agnostic signature mechanism on HTTP which does not incur in some of the shortcomings of JWT and can add a signature without modifying the payload body: https://github.com/httpwg/http-extensions/blob/master/draft-ietf-httpbis-message-signatures.md It could be interesting to interact with them and evaluate this specification. Google specifications on providing signed exchanges is very interesting and provides mitigations on many threats and privacy issues

https://wicg.github.io/webpackage/draft-yasskin-http-origin-signed-responses.html 

Document modified to include the suggestion to analyse message-signing approaches in addition to TLS.

Document modified to include 'Signing HTTP Messages' and 'Signed HTTP Exchanges' in the list of standards to analyse.

Opportunity

The profile should work as-is, without the need for adaptation, in different contexts or data exchange platforms (eg. SDG, X-Road, ..): the interoperability should be provided via common semantics.

n-Corners

Please consider that 2-Corner is valid for both REST and RPC.

In Italy we are moving forward our existing 4-corner model adopted in 2008 to a more distributed, peer-to-peer, approach with a central platform to support trust between agencies without intermediating exchanges: we are interested in analysing approaches different from the 4-corners one.

Standards and Design

While MQTT is an interesting protocol and it's a valid choice in different sectors or for internal services, to expose public-sector endpoints you need to implement a custom semantic comparable to HTTP for supporting the same level of authentication, authorization, security and audit.

In Italy we decided that cross-domain interoperability should only work on HTTPS with the related semantics (method, status, URL) and to postpone the adoption of other protocols to future versions of the framework.

Terminology

The terminology of some sections should benefit from being aligned with the one in the HTTP specification: it's mainly an editorial work which includes referencing the relevant spec, including:

• RFC723x (httpbis) or the ongoing work (messaging https://tools.ietf.org/id/draft-ietf-httpbis-messaging-12.html and semantics https://tools.ietf.org/id/draft-ietf-httpbis-semantics-12.html ) 
• Websockets
• JWx

European Telecommunications Standards Institute Electronic Signatures and Infrastructures Technical Committee (ETSI ESI TC)

ESI-1

When you mention eDelivery, do you mean fully-fledged trust service as the Electronic Registered Delivery Service (ERDS) as defined in eIDAS, or something broader?

For instance, in the two-corner model is not clear whether a trust service provider is present.

By eDelivery we indeed cover something broader than ERDS; the building block is to be usable in a variety of situations, not limited to ERDS. Therefore, its use in a non-ERDS context is legitimate and expected.

However, (the) eDelivery (building block) aims to be aligned to the eIDAS regulation so that users aiming to establish an ERDS find eDelivery fit for purpose, understanding at the same time that eDeliovery on its own may not be sufficient to set up a fully-fledged ERDS solution. Further components may be required.

We document the relationship between the eDelivery and (Q)ERDS here. We note that the document is not applicable to the REST API profile that is the topic of this pilot, but to the existing eDelivery AS4 profile.

The relationship between the REST API profile and (Q)ERDS is not yet formally documented. This can only take place once the profile is finalised.

ESI-2

Solution - First bulleted list. Third bullet

Footnote 3 attached to “Secure data exchange” says: “Reliability may be relaxed in the REST API profile, but possible considered as an optional part thereof". I guess that this means that depending whether this reliability is implemented or not, a REST – eDelivery may or may not be an ERDS. So, not all the REST-EDS shall be ERDS.

ESI-3

No explicit mention is done to Evidence generated by ERDS providers

Proposed change: Include in the REST API scope the provisions for easy retrieve of ERDS evidence by clients and between ERDS providers.

It is not possible to state yet if the REST API profile can/should be tightly linked with ERDS (e.g., whether ERDS evidences should be handled in the REST API layer or considered business-specific and are therefore left unspecified as part of the profile). It will be evaluated whether or not a tight coupling is required.

This has been captured in a new section, ‘Use in (Q)ERDS context.’

ESI-4

Analyse

No mention is done to levels of authentication.

Proposed change: Include a brief mention to the fact that different levels of authentication shall be considered, specially in the context of provision of ERDS.

ESI-5

Analyse - Existing standards to be considered

No explicit mention to standards dealing with signatures appear here.

Proposed change: Add

For securing business messages and evidence:

• XAdES
• JAdES (under production)

ESI-6

Analyse - Existing standards to be considered

No mention is done to standards defining evidence

Proposed change: Add

For evidence by ERDS, ETSI EN 319 522-2

ESI-7

Specify - Security and traceability

The text says “Signing – to be analysed”

Proposed change: Propose examples of standards that will be explored: XAdES, JAdES

ESI-8

Specify - Security and traceability

Clause 2

Proposed change: Include a clause on Evidence in ERDS mentioning ETSI EN 319 522-2

ESI-9

Specify - Versioning of the profile

The bulleted list of items that shall be specified by the API version does not include anything related to Evidence.

Proposed change: Include in the bulleted list of items a mention to versions of evidence managed by the service when acting as an ERDS.

Business Need / Problem

REST API Architectural Style - unclear.

Business Need / Problem

Light context - unclear.

Opportunity

REST API Profile to be used as "light context" - unclear.

Opportunity

REST API Specification - unclear.

Opportunity

REST API Profile - unclear.

Opportunity

REST API Specification/Profile - unclear.

Opportunity

REST Clients - unclear.

Opportunity

REST Services - unclear.

Solution

REST API - unclear.

Solution

eDelivery-compliant data exchange - unclear.

Solution

REST request structure - unclear.

Pilot - Objectives of the Pilot

Draft REST API - unclear.

Constraints

Digital Government (d-Gov) REST-based architecture - unclear.