EDelivery

From DE4A
Revision as of 17:52, 9 March 2023 by Mpttfp eduardo.moreno (talk | contribs) (Update eDelivery)
Jump to navigation Jump to search

The exchange of a single document between a DE and a DO always requires two eDelivery exchanges: the first one initiated by DE and targeted for DO, and the second one is initiated by DO and targeted for the DE. Technically speaking both transmissions are “requests” even though their semantics are “request” and “response”.

The foundation of the document exchange is the so called “4-corner model”, which differentiates between the business sender of a document (Corner 1 aka C1), the technical sender of a document (Corner 2 aka C2), the technical receiver of a document (Corner 3 aka C3) and the business receiver of a document (Corner 4 aka C4). Depending on the order of a message exchange, the assignment of the corner varies. In DE4A the “DE4A Connector” (sometimes just “Connector”) can play the role of both DR and DT and therefore acts as C2 or C3, depending on whether a message is sent or received.

eDelivery business request from DE to DO

The figure above depicts the structural message exchange initiated by DE (C1), sent by DR (C2), received by DT (C3) and forwarded to DO (C4). The message exchange between C1 and C2 as well as the message exchange between C3 and C4 are not specified by eDelivery, even though AS4 may be used for this, but they must be defined by the DE4A Connector.

If DO sends a message back to DE, the order of the messages change as well as the corner assignment, as shown in the following figure where the DO becomes C1, forwarding the response to DT which is now C2. The AS4 transmission targets DR as C3 who in turn forwards the payload to DE which is the C4 in this scenario.

eDelivery business response from DO to DE

This duality of the message exchange means, that each of the named nodes (DE, DR, DT and DO) requires both sending and receiving capabilities.

For the sake of clarity, the rest of the document only shows images with messages flowing from DE to DO because it seems easier to understand, even though the image would be perfectly valid for the return direction from DO to DE (except when stated differently).

The eDelivery message exchange in DE4A uses the so called “Dynamic Discovery” which is an extension of the basic eDelivery in the sense that it adds the usage of SML and SMP. Both components as well as the lookup process are described below.

Identification of components

Each C1 and C4 of a message exchange is called a “Participant” and is uniquely identified by a “Participant Identifier”. The nodes C2 and C3 are not participants and have no respective identifier, they are only accessed by URLs.

Different types of documents exchanged via eDelivery are classified via “Document Type Identifiers”. The orchestrations in which document types are exchanged are classified via “Process Identifiers”.

There is a separate policy document on the usage of identifiers within its network. This document, called DE4A Policy for use of identifiers.pdf, contains the details about the following identifier types:

  • Participant Identification
  • Type Identification
  • Process Identification
  • Transport Profile Identification

Each Participant ID, Document Type ID and Process ID consists of two separate parts – one “scheme” part and one “value” part. A scheme defines the layout and constraints of the value. This allows to add new types of identifiers in different scenarios, without interfering with existing used identifiers.

This document was heavily inspired by the “Peppol Policy for use of Identifiers”, the identifier reference document of the Peppol network.

Additional to the guiding document, the project also created a set of Code Lists, that contains the allowed values.

SML/DNS

The SML and DNS are often used synonymously but they serve different purposes. The SML is the registry of all known SMPs and Participants from any project or service that use the dynamic discovery mode of eDelivery and is responsible for creating DNS entries in a specific DNS zone. For every Participant a unique DNS entry is created. Only SMPs interacts with the SML. Other components will never explicitly interact with the SML.

During the main message exchange between C2 and C3 the DNS is queried for the SMP URL of C3. The SML is neither queried in the message exchange nor before or after. Due to the distributed nature of DNS, this message exchange is performed without a single point of failure, which is one of the key benefits of eDelivery.

The SML is operated centrally by the European Commission. Its service is gratefully offered free of charge to the DE4A project.

The SML creates DNS records for each SMP itself (see SMP) and for each Participant (aka Service Group; see SMP) pointing to the owning SMP. These DNS NAPTR records need to be read by the sending party (the DE4A Connector), to determine the URL of the SMP that needs to be queried.

The SML and the DNS are centralized third-party components for DE4A. For the SMPs to be able to communicate with the SML, a Client Certificate is needed (see Certificates), so only legitimate requestors can create DE4A participants in the SML.

SML query process in DE4A

DE4A only uses the production SML and the dedicated domain de4a.edelivery.tech.ec.europa.eu. for its purposes.

The lookup process from the Connector solely requires the Participant Identifier (see Identification of components) of the receiver. Using a SHA-256 hash value of the Participant Identifier, a unique domain name is created, which will be looked up from the DNS using the “NAPTR” record query type. This NAPTR record then contains the base path of the SMP to be queried. The details of the SMP query are described in chapter 3.1.4.5.

The structure of the Participant IDs used in DE4A is described in chapter 3.1.3.2.

A real-life example for looking up the Participant Identifier iso6523-actorid-upis::9915:de4atest looks like this:

  • Apply the following algorithm to the Participant Identifier:
    • strip-trailing (base32 (sha256 (lowercase (ID-VALUE))), "=") + "." + ID-SCHEME + "." + SML-ZONE-NAME
    • In the above example identifier, the “ID-SCHEME” is “iso6523-actorid-upis” and the “ID-VALUE” is “9915:de4atest”.
  • The created domain name is: 54VMPCQA26DNZS74VHQOKJ7U6IRBBI5KPMQ6AO3KVCQC3F6YR2YA.iso6523-actorid-upis.de4a.edelivery.tech.ec.europa.eu
  • The look up can be done with the “dig” tool on the command line:
  • The relevant part of the response is "!.*!https://de4a-smp.usp.gv.at!" that contains the link to the SMP of this particular Participant Identifier that can be queried for the details, embedded into a regular expression as defied by the NAPTR record specification.
  • Using the extracted URL https://de4a-smp.usp.gv.at the regular SMP query process, as described in chapter 3.1.4.5, can be performed.

As can be seen from this description, the SML system itself is not invoked in the lookup – only the DNS system is involved. Because the DNS system is inherently replicated, a fast and fail-safe operation is guaranteed.

Domains and types of Participant IDs used in DE4A

In DE4A, there are two types of participants:

  • Imaginary participants: participants for whom example evidence and fake data have been made up to be used for testing purposes.
  • Real participants: the actual DE4A partners participating in the pilots of the project.

At the same time, for the real participants, there are also two “domains”:

  • Test domain: only fake data is used for test purposes. It is the domain related to the DE4A Playground, where participants return datasets from test sources.
  • Pilot domain: where real data from real citizens and companies are expected to be used. It is the environment used for the running phase of the pilots, where participants access to their real registries and return real evidence from them.

Finally, the project is divided into two pilots iterations where each of them needs a copy of those two domains, and where some overlap between them occurs.

As the DE4A project uses the dynamic discovery of eDelivery, to query the DNS there cannot be duplicate participant IDs targeting to different SMPs (depending on the domain concerned). Thus, a different participant ID schema per each domain has been defined:

  • PRE1a: Imaginary participants used for testing during iteration 1 of the project. The related evidence is stored in the Mocked DO of the Playground iteration 1.
    • Scheme identifier used: “9999”.
    • ­Suffix used: “-it1”.
    • ­E.g. iso6523-actorid-upis::9999:ess2833002e-it1
  • PRE1b: Real participants queried about testing data through the Playground iteration 1. Simulated data will be returned when querying for the participants. The related evidence is located in each partner’s infrastructure, within their test domains.
    • Scheme identifier used: “99XX”, where “XX” depends on the identifier each participant is using.
    • Suffix used: “-it1”.
    • E.g. iso6523-actorid-upis::9920:ess2833002e-it1
  • PRO1: Real participants queried about actual data during the execution of phase 1 of the pilot. The related evidence is located in each partner’s infrastructure, within their pilot domains.
    • Scheme identifier used: “99XX”, where “XX” depends on the identifier each participant is using. It is the “real” participant ID.
    • Suffix used: none, since there is no overlap between phases 1 and 2 of the pilots.
    • E.g. iso6523-actorid-upis::9920:ess2833002e
  • PRE2a: Imaginary participants used for testing during iteration 2 of the project. The related evidence is stored in the Mocked DO of the Playground iteration 2.
    • Scheme identifier used: “9999”.
    • Suffix used: “-mock-it2”.
    • E.g. iso6523-actorid-upis::9999:ess2833002e-mock-it2
  • PRE2b: Real participants queried about testing data through the Playground iteration 2 Simulated data will be returned when querying for the participants. The related evidence is located in each partner’s infrastructure, within their test domains.
    • Scheme identifier used: “99XX”, where “XX” depends on the identifier each participant is using.
    • Suffix used: “-test-it2”.
    • E.g. iso6523-actorid-upis::9920:ess2833002e-test-it2
  • PRO2: Real participants queried about actual data during the execution of phase 2 of the pilot. The related evidence is located in each partner’s infrastructure, within their pilot domains.
    • Scheme identifier used: “99XX”, where “XX” depends on the identifier each participant is using. It is the “real” participant ID.
    • Suffix used: none, since there is no overlap between phases 1 and 2 of the pilots.
    • E.g. iso6523-actorid-upis::9920:ess2833002e

These different participant IDs must be stored in their corresponding IDK components and SMPs and configured to return the proper information:

  • PRE1a: Imaginary participants during the first iteration
    • IDK: none (for these participants, the DemoUI of the Playground knows which the imaginary participants are and which DO to query, namely, the Mocked DO of the first iteration).
    • SMP: shared SMP of the Playground IT1. It returns the routing information of the targeted Connector (DR/DT) of the Playground IT1.
  • PRE1b: Simulated data from real participants during the first iteration
    • IDK: Mocked IDK of the Playground IT1.
    • SMP: shared SMP of the Playground IT1. It returns the routing information of the targeted Connector (DR/DT) of the requested participant.
  • PRO1: Real data from real participants during the first iteration
    • IDK: Mocked IDK of the pilot running environment.
    • SMP: national SMP of the requested participant. It returns the routing information of the targeted Connector (DR/DT) of the requested participant.

For the first pilot running phase, partners who had not deployed their own SMPs were able to use a shared SMP provided by one of the partners with an available SMP. In such cases, the routing information of those partners was stored in that shared SMP.

  • PRE2a: Imaginary participants during the second iteration
    • IDK: Central IAL. Its information is automatically updated and fed from the SMPs connected to it.
    • SMP: shared SMP of the Playground IT2. It returns the routing information of the targeted Connector (DR/DT) of the Playground IT2.
  • PRE2b: Simulated data from real participants during the second iteration
    • IDK: Central IAL. Its information is automatically updated and fed from the SMPs connected to it.
    • SMP: national SMP of the requested participant. It returns the routing information of the targeted Connector (DR/DT) of the requested participant.
  • PRO2: Real data from real participants during the second iteration
    • IDK: Central IAL. Its information is automatically updated and fed from the SMPs connected to it.
    • SMP: national SMP of the requested participant. It returns the routing information of the targeted Connector (DR/DT) of the requested participant.

SMP

The Service Metadata Publisher (SMP) is a decentralized registry with routing information. For DE4A a solution that is compatible with the OASIS BDXR SMP v1 specification must be used, as indicated by the eDelivery specification.

The SMP is responsible for maintaining the relationship between a Participant Identifier and its technical addressing details, such as the AS4 endpoint URL and the X.509 certificate. Every SMP must implement a standardized REST API for querying.

All SMPs MUST provide the two REST APIs mandated by the specification, identified as /{participantID} and /{participantID}/services/{docTypeID}. The first API returns a list of all document types the participant is capable to receive (which may be an empty list) and the second API returns the details on the receiving “Endpoints” including the endpoint URL and the X.509 certificate of the receiver. Both APIs can only return XML content, and only the second API response is digitally signed with the SMP certificate of the SMP maintainer. Each of the response data structures contain an optional Extension element that could be used for additional content.

Each SMP MUST have one Certificate from the SMP PKI configured (see Certificates), independent of the number of Participants it manages. This certificate is used as a client certificate for the communication with the SML (see SML/DNS), as a client certificate for the communication with the DE4A Directory and as an XML signing certificate for its REST responses.

An SMP MUST be registered once in the SML before it can be used in the network.

AS4

Retrieved from ‘https://wiki.de4a.eu/index.php?title=EDelivery&oldid=5921’