e-trustex interface control document - circabc - …€¦ · web viewe-trustex interface control...

EUROPEAN COMMISSIONDIRECTORATE-GENERALINFORMATICSInformation systems Directorate

European Commission

e-TrustEx Interface Control Document

Date: 13/07/2012

Version: 0.005

Authors: Sonia Tafaro, Alice Vasilescu

Revised by:

Approved by:

Public:

Reference Number:

Commission européenne, B-1049 Bruxelles / Europese Commissie, B-1049 Brussel - Belgium. Telephone: (32-2) 299 11 11.

Commission européenne, L-2920 Luxembourg. Telephone: (352) 43 01-1.

TABLE OF CONTENTS

1. INTRODUCTION................................................................................................................7

1.1. Background.................................................................................................................... 7

1.2. Purpose of the Interface Control Document...................................................................8

1.3. Scope............................................................................................................................. 8

1.4. What is a service............................................................................................................ 8

1.5. Audience........................................................................................................................ 9

1.6. Definitions, Acronyms and Abbreviations........................................................................9

1.7. References................................................................................................................... 11

2. PRINCIPLES AND MECHANISMS......................................................................................14

2.1. E-TrustEx overview.......................................................................................................14

2.2. Interchange Agreement...............................................................................................15

2.3. Security considerations................................................................................................16

2.3.1. Confidentiality........................................................................................................... 17

2.3.2. Integrity.................................................................................................................... 18

2.3.3. Availability................................................................................................................ 22

2.3.4. Authenticity............................................................................................................... 22

2.3.5. Authorisation............................................................................................................ 22

2.3.6. Logging and monitoring.............................................................................................23

2.4. Communication modes.................................................................................................25

2.5. The Send/Receive interaction scenario.........................................................................26

2.6. Reusable Schema Definitions........................................................................................29

2.7. Document processing considerations...........................................................................30

2.7.1. Maximum Message Size............................................................................................30

2.7.2. Maximum Binary file size and total storage capacity..................................................30

2.7.3. Unique Message ID and Reliable Message Delivery....................................................30

2.8. Service versioning........................................................................................................32

2.8.1. Backward compatible evolution (most likely for Read Services)..................................32

2.8.2. Semi-backward compatible evolution (most likely for Write Services)........................32

2.8.3. Backward incompatible evolution (most likely for Write Services)..............................33

3. SERVICES.........................................................................................................................34

3.1. Overview...................................................................................................................... 34

3.2. Detailed description per service...................................................................................34

3.2.1. Pre-conditions........................................................................................................... 34

3.2.2. Submit Document Bundle service..............................................................................37

3.2.3. Store Document Wrapper service..............................................................................40

e-TrustEx Interface Control Document - Document Version 0.004 dated 13/07/20122

3.2.4. Delete Document Wrapper service............................................................................41

3.2.5. Submit Application Response.....................................................................................43

3.2.6. Retrieve Document Wrapper service.........................................................................45

3.2.7. Inbox Request service................................................................................................46

3.2.8. Retrieve Request service...........................................................................................46

3.2.9. Retrieve Interchange Agreement...............................................................................47

3.2.10. Query Request.........................................................................................................48

3.2.11. Status Request.........................................................................................................49

3.2.12. View Request..........................................................................................................49


TABLE OF FIGURESFigure 1 e-TrustEx platform...................................................................................................7

Figure 3 – e-TrustEx at a glance...........................................................................................14

Figure 4 – The Interchange Agreement................................................................................15

Figure 5 Encryption of sensitive information using an Applet...............................................18

Figure 6 Two-phased document validation..........................................................................19

Figure 7 Data integrity supported - design description.........................................................20

Figure 8 Signed Document Bundle.......................................................................................21

Figure 9 – Synchronous communication mode interactions.................................................26

Figure 10 – Asynchronous communication mode interactions.............................................26

Figure 11 – Send/Receive Communication scenario.............................................................27

Figure 12 UBL Documents Architecture...............................................................................29

Figure 13 Document bundle communication workflow........................................................38

LIST OF TABLESTable 1 Data classification...................................................................................................16

Table 2 Design description..................................................................................................20

Table 3 Events to be logged.................................................................................................23

Table 4 Devices in scope......................................................................................................24

Table 5 Devices out of scope...............................................................................................24

Table 6 Communication modes...........................................................................................25

Table 7 Send/Receive interaction scenario..........................................................................27

Table 8 Service versioning...................................................................................................32

Table 9 Backward Compatible Change.................................................................................32

Table 10 Incompatible evolution.........................................................................................33

Table 11 e-TrustEx services.................................................................................................34

Table 12 Authentication and Authorisation errors...............................................................35

Table 13 Submit Document Bundle - Ack.............................................................................37

Table 14 Document Bundle possible errors..........................................................................39

Table 15 Store Document Bundle errors..............................................................................40

Table 16 Store Document Wrapper - Ack.............................................................................41

Table 17 Delete Document Wrapper - errors.......................................................................42

Table 18 Delete Document Wrapper - Ack...........................................................................42

Table 19 Submit Application Response - Ack........................................................................43

Table 20 Submit Application Response - errors....................................................................44

Table 21 Retrieve Document Wrapper - errors....................................................................45


Table 22 Inbox Request - errors...........................................................................................46

Table 23 Retrieve Request - errors......................................................................................47

Table 24 Retrieve Interchange Agreement - errors..............................................................47

Table 25 Query Request - errors..........................................................................................48

Table 26 Status Request - errors..........................................................................................49

Table 27 View Request - errors............................................................................................50


Document History

Version Date Comment Modified Pages

0.001 24/05/2010 Creation All

0.002 06/06/2011 Section about security added

Section about versioning added

Other changes according to internal review

§2.3

§2.7

See track changes

0.003 15/09/2011 Section about the reusable schema definitions 2.6

0.004 20/06/2012 “Background”, “What is a service” section added

Updated 2.3. Security Considerations

Updated 3.2. Detailed description per service

As required

0.005 13/07/2012 View Request services added As required


1. INTRODUCTION

1.1. Background

The e-TrustEx action was launched by DIGIT in 2010 to support public administrations in the implementation of EU policies by offering them a platform for secure information exchange. At the time this document is written, e-TrustEx is already being used in 3 business domains:

In the procurement domain, it enables the European Commission and Member States to exchange procurement documents in digital format with their Suppliers.

In the competition domain, it enables the organisations involved in competition cases to exchange documents with the European Commission;

In the legislative domain, it enables the parliaments in the EU to exchange legislative documents with the European Commission.

In all cases, e-TrustEx plays the role of interoperable mediator between the back-offices of exchange parties.

The e-TrustEx platform is already available on Joinup (European Commission, 2011) in Open Source so that it can be freely reused by Public Administration. Its main elements, coarse grained view, are shown in the model below.

Capabilities Layer

Application Server

Valid

atio

n

Profi

le

Rend

erin

g &

Tran

sfor

mat

ion

Arch

iving

Rout

ing

e-TrustEx core exchange platform

Services Layer

Database Layer

Applications Layer

Secu

rity f

eatu

res

Web Application

Cross Sector Services

Admin Services

Module(s)

Sector Specific Service(s)

Mediators Layer

Access Points

Figure 1 e-TrustEx platform

The e-TrustEx core exchange platform is divided into the following interface-mediated layers:

Services Layer: Set of services of e-TrustEx which can be directly accessed, via well-defined interfaces, by the application and mediators layers. Information exchanged


across the service layer is wrapped within, structured or semi-structured, message structures. The services included in this layer are categorised as follows:

o Cross Sector Services: Highly reusable, cross-cutting services which can be used in several sectors and do not change very regularly over time e.g. inbox service, retrieve document service, etc;

o Sector Specific Services: These services are created and directly associated with a specific business process of a given business sector e.g. submit invoice. They therefore change more regularly and have less reuse potential across sectors than the cross sector services. Nonetheless, these services are usually highly reusable within their specific sector.

o Administration Services: These services are used by administrators to administer and configure e-TrustEx.

Capabilities Layer: Services often perform similar functions such as validation, archiving, etc. As opposed to implementing these capabilities in the services themselves, they are implemented in this layer so that they can be reused. These capabilities can be thought as internal services that are not visible to the application and mediators layers.

1.2. Purpose of the Interface Control Document

The purpose of this document is to detail the interfaces provided by e-TrustEx platform - Trusted Exchange Platform. This document describes the different possible interactions, the services involved in these interactions and the messages exchanged.

1.3. Scope

The scope of this document covers the documentation of e-TrustEx interfaces.

It describes the possible interactions, the services involved and the messages exchanged.

Related references to the technical endpoint definitions (WSDL), use cases and document structures (XSD) are also provided in this document for each interaction.

1.4. What is a service

For the purpose of the ICD, a service is defined as an abstract resource that performs specific actions (a.k.a. business-level operations, or simply, operations) in the scope of one or several business processes. Within the context of e-TrustEx, the most natural and familiar way for a service to operate is via the exchange of documents between the entity providing the service and the entity requesting its use (and vice-versa). Therefore, each business process can be decomposed in a set of services made up of one or more atomic operations. The operands of each operation are documents which are exchanged and processed by these entities. Each Operation will either finish in a ‘success’ or ‘error’ state1.

The ICD details the what (i.e. what services are available and what should be expected from each service from a functional and non-functional viewpoint) and the how (i.e. how these

1 For the sake of transparency and reliability, e-TrustEx enables the users to follow-up the state of each operation using the StatusRequest service. For more information on the states of a request the reader should consult Error: Reference source not found Error: Reference source notfound.


services are implemented from a technical viewpoint and how they should be used to yield the expected result) about the services exposed by the e-TrustEx platform.

1.5. Audience

The ICD is intended for a diverse audience and is aimed at everyone interested in understanding the interface of e-TrustEx from a functional or a technical viewpoint. The target audience for this document includes business domain and technical experts.

According to RUP (see [REF40]), the roles listed hereunder are part of the target audience:

Implementers of the services of e-TrustEx, for an understanding of the interface provided by the service and the behaviour its clients should expect.

Implementers of the consumers of these services, for an understanding of the technical interface exposed by e-TrustEx, the inputs required by each service and also their outputs. Additional information is also available about the evolution of these services.

Designers of services, in understanding the relationship between specifications and the relationship between services and the specifications they implement.

Testers of the services, to understand the functionality and quality aspects of the service model.

1.6. Definitions, Acronyms and Abbreviations

Term Description

e-PRIOR Exchange platform developed by the European Commission, DG-Informatics, in the context of the e-Procurement processes.

e-TrustEx Name of the Trusted Exchange Platform currently being developed by the European Commission, DG-Informatics.

HTTP (Hyper Text Transfer Protocol)

A TCP-based application-layer protocol used for communication between Web servers and Web clients.

HTTPS Secure version of the HTTP protocol. A different default port and an additional encryption/authentication layer between HTTP and TCP are used.

Receiver A Party which is referred to as the recipient of a message sent through e-TrustEx.

Sender A Party which is referred to as the origin of a message sent through e-TrustEx.

SOA (Service Oriented Architecture)

An architectural style where existing or new functionalities are accessible by means of services, without knowing the underlying technology.

SOAP (Simple Object Access Protocol

A lightweight XML-based messaging protocol used to encode the information in Web service request and response messages before sending them over a network.

SSL (Secure Sockets Layer)

A protocol for transmitting private information via the Internet by means of a cryptographic system.


UBL Universal Business Language (UBL) is a library of standard electronic XML business documents such as purchase orders and Invoices. UBL was developed by an OASIS Technical Committee with participation from a variety of industry data standards organizations. UBL is designed to plug directly into existing business, legal, auditing, and records management practices. It is designed to eliminate the re-keying of data in existing fax- and paper-based business correspondence and provide an entry point into electronic commerce for small and medium-sized businesses. UBL version 2.0 was approved as an OASIS Committee Specification in October 2006 and has been publicly released.

WS (Web Service)

A Web service is a software system designed to support interoperable machine-to-machine interaction over a network. It has an interface described in a machine-process able format (specifically WSDL).

WSDL WSDL (Web Service Description Language) is an XML-based service description on how to interface using a web service.

XML XML (Extensible Markup Language) is the standard messaging format for business communication, allowing companies to connect their business systems with those of customers and partners using the existing Internet infrastructure.

XSD XML schema definition language describes the structure of an XML document.


1.7. References

# Document Contents outline

[REF1] Submit Document Bundle Use Case e-TrustEx use case which describes the submission of a Document Bundle.

[REF2] Store Document Wrapper Use Case e-TrustEx use case which describes the submission of a Document Wrapper.

[REF3] Retrieve Document Wrapper Use Case e-TrustEx use case which describes the retrieval of a Document Wrapper.

[REF4] Inbox Request Use Case e-TrustEx use case which describes the request for Inbox.

[REF5] Retrieve Request Use Case e-TrustEx use case which describes the retrieve request.

[REF6] User Access Use Case e-TrustEx use case which describes the authentication and authorization of users.

[REF7] Fault Events e-TrustEx SOAP faults description.

[REF8] DocumentBundle wsdl WSDL which describes the SubmitDocumentBundle service.

[REF9] DocumentWrapper wsdl WSDL which describes the StoreDocumentWrapper and RetrieveDocumentWrapper services

[REF10] InboxRequest wsdl WSDL which describes the Inbox service.

[REF11] RetrieveRequest wsdl WSDL which describes the Retrieve request.

[REF12] DocumentBundle xsd XML schema for the Document Bundle message.

[REF13] DocumentBundleReceived xsd XML schema for the canonical form of Document Bundle message.

[REF14] DocumentWrapper xsd XML schema for the Document Wrapper.

[REF15] DocumentWrapperReceived xsd XML schema for the canonical form of Document Wrapper.

[REF16] DocumentWrapperRequest xsd XML schema for the Document Wrapper request.

[REF17] InboxRequest xsd XML schema for the Inbox request.

[REF18] InboxResponse xsd XML schema for the Inbox response.

[REF19] RetrieveRequest xsd XML schema for the Retrieve request.

[REF20] RetrieveResponse xsd XML schema for the Retrieve response.


[REF21] Ack xsd XML schema for the technical Aknowledgment

[REF22] Fault xsd XML schema for the SOAP faults.

[REF23] e-TrustEx software architecture document

eTrustEx SAD

[REF24] e-PRIOR Interface Control Document e-PRIOR documentation

[REF25] OASIS Universal Business Language v2.0 Universal Business Language v2.0

[REF26] XML Schema 1.1 XML Schema

[REF27] ISO Schematron ISO/IEC 19757 – 3 : 2006

[REF28] Delete Document Wrapper Use Case e-TrustEx use case which describes the deletion of a Document Wrapper.

[REF29] Submit Application Response Use Case e-TrustEx use case which describes the deletion of a Document Wrapper.

[REF30] Application Response wsdl WSDL which describes the Application Response.

[REF31] Application Response xsd XML schema for the Application Response.

[REF32] Retrieve Interchange Agreement Use Case

e-TrustEx use case which describes the retrieval of the Interchange Agreement.

[REF33] RetrieveInterchangeAgreement wsdl WSDL which describes the Retrieve Interchange Agreement.

[REF34] RetrieveInterchangeAgreementRequest xsd

XML schema for the Retrieve Interchange Agreement Request.

[REF35] RetrieveInterchangeAgreementResponse xsd

XML schema for the Retrieve Interchange Agreement Response.

[REF36] Query Request Use Case e-TrustEx use case which describes the Query Request.

[REF37] QueryRequest wsdl WSDL which describes the Query Request.

[REF38] QueryRequest xsd XML schema for the Query Request Request.

[REF39] QueryResponse xsd XML schema for the Query Request Response.

[REF40] Rational Unified Process version 7.5 RUP roles that are part of the target audience.

[REF41] EC_CodeList_e-TrustEx.xls Code list tables

[REF42] Status Request Use Case e-TrustEx use case which describes the Status Request.


http://www.ibm.com/developerworks/rational

http://www.schematron.com/

http://www.w3.org/XML/Schema

http://docs.oasis-open.org/ubl/cs-UBL-2.0/UBL-2.0.html

https://webgate.ec.europa.eu/CITnet/svn/digit-elnvoicing/trunk/03-Development/01%20e-PRIOR/0006%20Deployment

https://webgate.ec.europa.eu/CITnet/svn/digit-elnvoicing/trunk/03-Development/03%20e-TrustEx/0003%20Analysis%20&%20Design/eTrust_ARCH.doc

https://webgate.ec.europa.eu/CITnet/svn/digit-elnvoicing/trunk/03-Development/03%20e-TrustEx/0003%20Analysis%20&%20Design/eTrust_ARCH.doc

[REF43] Status Request wsdl WSDL which describes the Status Request.

[REF44] StatusRequest xsd XML schema for the Status Request.

[REF45] StatusResponse xsd XML schema for the Status Response.

[REF46] ETSI TS 101 903 V1.3.2 ETSI Standard for XML Advanced Electronic Signature (XAdES)

[REF47] View Request Use Case e-TrustEx use case which describes the View Request.

[REF48] View Request wsdl WSDL which describes the View²² Request.

[REF49] ViewRequest xsd XML schema for the View Request.


http://uri.etsi.org/01903/v1.3.2/XAdES.xsd

2. PRINCIPLES AND MECHANISMS

2.1. E-TrustEx overview

E-TrustEx (electronic Trusted Exchange) is the acronym of the service oriented platform developed by the European Commission, DIGIT allowing secure document exchange between European Commission and national parliaments, permanent delegations, local governments, businesses, citizens, other EU institutions.

E-TrustEx aims at enabling the exchange of electronic documents, reducing the use of paper documents, and increasing the trust, security and interoperability of these processes in a cross-border environment.

Another purpose of e-TrustEx is to guarantee equal treatment to all 3rd parties who need or want to exchange documents with the European Commission, and will replace in future phases, when needed and possible, notification by traditional means (via the post) with legally equivalent electronic interactions.

In order to meet those goals, the e-TrustEx platform re-uses the building blocks of the existing e-PRIOR platform [REF24] hence taking full advantage of its re-usability and extensibility. In this context, some of the e-PRIOR services had to be adapted in order to increase the generality of the platform and better comply with current and future needs from sectors other than e-Procurement.

e-TrustEx

Back-Office HTTPS

Back-Office

GUI user 1 GUI user 2

Back-Office

Back-Office

Institution 1

Institution 2

European Commission

Figure 2 – e-TrustEx at a glance

The diagram depicts two different types of interactions: i) either via back-end communication or ii) via a web interface (a.k.a. e-TrustEx GUI) enabling any user without a back-office (e.g. citizens, small businesses) to also use e-TrustEx to exchange information with the EU institutions.


Both interaction types may use the services exposed by e-TrustEx described in the present document.

2.2. Interchange Agreement

Before using the e-TrustEx services an agreement between the requesting parties and the platform owner must be reached. The abstract representation of the agreement is a logical entity called Interchange Agreement. This logical entity describes which parties can have a communication channel via e-TrustEx and which types of services (e.g. Store Document Wrapper, Submit Document Bundle) the aforementioned parties allowed to use. The communication channel consists of:

A Party Agreement which authorises an authenticated User to use the system on behalf of a Party. Each Organisation may use one or several third parties which will lead to the creation of as many Party Agreements as representatives.

An Interchange Agreement which enables the aforementioned Party to communicate with another Party as a Sender or a Receiver. In case both sending and receiving channels are needed, two separate Interchange Agreements will be created where each Party will be Sender and Receiver alternately.

Figure 3 – The Interchange Agreement

The system is able to deliver messages from an information system to another based on routing keys according to preconfigured interchange agreements. The information exchanged is subject to data classification (for more information see Information System Security Policy C(2006) 3602 (European Commission, 2006)).

Classification (or assessment of security needs) is the process of establishing the business impacts for the Commission of a loss of confidentiality, integrity and availability of its information and of synthesising them in classification levels.

Therefore in order to be able to manage the security of exchanged information, the Interchange Agreements will contain all the necessary information related to the data classification of the communication channel as shown in the below table:


Table 1 Data classification

Classification criteria

Information levels

Confidentiality TOP SECRET UE/EU TOP SECRET

SECRET UE

CONFIDENTIEL UE

RESTREINT UE

Unclassified information levels

LIMITED HIGH

LIMITED BASIC

PUBLIC

Integrity MODERATE

CRITICAL

STRATEGIC

Availability MODERATE

CRITICAL

STRATEGIC

The creation of Party and Interchange Agreements is an operational procedure coordinated between DIGIT and the involved Parties.

The following rules must be followed:

At a given moment in time, a PartyID MAY be part of different Party Agreements.

Two Parties Agreements involved in the same Interchange Agreement MUST represent one of the Sender or Receiver roles each.

One Party Agreement MUST NOT be linked to another Party Agreement within more than one Interchange Agreement for the same role (Sender or Receiver) and profile (Document Bundle).

To summarise, the following rule must be respected:

Each Interchange Agreement must have a unique combination of Sender Party Agreement, Receiver Party Agreement and Profile.

2.3. Security considerations

The e-TrustEx platform will allow secure information exchange between information systems

that have different security levels and security requirements. In order to be able to fulfil


these heterogeneous security requirements that depend on the information systems

connected, the e-TrustEx platform will:

1. Provide a set features to ensure different confidentiality, integrity, availability, non-

repudiation and authenticity in the information exchange process

2. Be easily configurable at run-time for each connected party, in order to guarantee

the different security levels (based on the Confidentiality, Integrity and Availability

levels detailed in Error: Reference source not found )

3. Provide a security solution that is transferable to the open source version

2.3.1. Confidentiality

The design of the data confidentiality solution is currently able to support the following two levels:

LIMITED HIGH - for information systems or information reserved for a limited number of persons on a need to know or need to access principle and whose disclosure to unauthorised persons would cause consequential prejudice to the Commission, other institutions, Member states or other parties, but not to an extent serious enough to merit EU classification.

LIMITED BASIC - for information systems or information reserved for a limited number of persons on a need to know or need to access principle and whose disclosure to unauthorised persons would cause moderate prejudice to the Commission, other institutions, Member states or other parties, but not to an extent serious enough to merit EU classification.

For more information on the possible values of the data confidentiality the reader should consult the Code table of e-TrustEx. (see [REF41] )

As the data is transferred from one system to another using the exchange platform, the following layers have been defined, for which the confidentiality requirements must be met:

Transport Layer: how the right level of confidentiality is met when data is delivered and exchanged between software components.

Application Layer: how the right level of confidentiality is met when data is handled by the single software components.

Storage Layer: how the right level of confidentiality is met when data is stored in databases or network accessible storage devices.

In the case of “LIMITED BASIC” confidentiality level, the software components, that process and store the exchanged messages and are part of e-TrustEx, are considered trusted. The messages are encrypted in Transport Layer using TLS/SSL.

In the case of “LIMITED HIGH” confidentiality level, the messages are encrypted at least in transport and storage. The e-TrustEx exchange platform will enforce the encryption at Transport and Storage Layer by:

Encrypting the message on the fly ( e.g. SSL) Encrypt the messages at the database level using symmetric encryption.


In order to support one of the security requirements concerning the access to sensitive information, known as access on a “need-to-know basis”, end-to-end confidentiality principle is used. The end-to-end confidentiality principle is about preserving the privacy and integrity of the data exchange across networks through which the data is transferred.

The end-to-end confidentiality principle will be achieved by using end-to-end encryption. In this scenario, the originator of the message will encrypt the sensitive message using the public key of the receiver. Consequently only the intended receiver can decrypt and read the message.

As briefly described above, for the encryption of the sensitive message, a solution based on asymmetric algorithms has been selected. The exchange platform provides the originator of the sensitive message with the public key of the receiver, which will be further used to encrypt the sensitive message. The public key is retrieved using the “RetrieveInterchangeAgreement” ([REF32]).

Concerning the encryption algorithm, for performance reasons, a hybrid algorithm is highly recommended.

The picture below shows an example of how the originating party, using an Applet, encrypts the message before the submission.

Loop for each file

Applet ETX - Node

generate AES256 key

encrypt file with AES256

encrypt AES256 key with PublicKey

generate SHA512 hash

retrieve ICA

ICA (includes PublicKey for enc)

Submit Document Wrapper

Sign and Submit Message Bundle

build Document Wrapper (encrypted file + encrypted AES256 key)

Figure 4 Encryption of sensitive information using an Applet

2.3.2. Integrity

The design of the data integrity solution is currently able to support the following two levels:


MODERATE - for information or information systems the loss of integrity of which might threaten2 the internal working of the Commission.

STRATEGIC - for information or information systems the loss of integrity of which might threaten the position of the Commission with regard to other Institutions, Member States or other parties.

In the case of “MODERATE” integrity level, the two-phase document validation is used as described in the picture below:

Figure 5 Two-phased document validation

In the case of “STRATEGIC” integrity level the approach used is the “point-to-point integrity”, where the security safeguard is enforced by every component involved in the communication. Whenever a component submits a message to another component, the message must be electronically signed by the sender. The receiving component must validate the digital signature. (more details of the flow in Error: Reference source not found)

The data that will be subject to integrity safeguards is the XML document as SOAP 1.1 document fragments (Header + Body). The Header part is composed of two parts, Business Header (mandatory element) and the Technical Header (optional element which will carry in the digital signature).

In the case of the communication channels between the node and other components, XAdES standard will be used and based on the EC Directive 2011/130/EU and it has to meet the following requirements:

The signature is conform with the W3C XML Signature specifications ( 2 )

The signature MUST at least be a XAdES-BES (or -EPES) signature form as specified in the ETSI TS 101 903 XAdES specifications ( 3 ) and complies with all the following additional specifications:

2 At the maximum, so that "no impact" is also classified as MODERATE.


The ds:CanonicalizationMethod that specifies the canonicalization algorithm applied to the SignedInfo element prior to performing signature calculations identifies one of the following algorithms only:

Canonical XML 1.0 (omits comments): http://www.w3.org/TR/2001/REC-xml-c14n-20010315

Canonical XML 1.1 (omits comments): http://www.w3.org/2006/12/xml-c14n11

Exclusive XML Canonicalization 1.0 (omits comments): http://www.w3.org/2001/10/xml-exc-c14n#

Figure 6 Data integrity supported - design description

Table 2 Design description

Step Component Description

1 Request generator

On the requestor side, the Request generator identifies the security constraints of the outgoing SOAP request message based on the ICA security level of the communication channel (ICA policy).

In the context of data integrity, the Request generator will identify the need to digitally sign the SOAP message to comply with the data integrity requirement.

2 Request consumer

On the responder side, the Request consumer identifies the security constraints of the incoming SOAP request message based on the ICA security level of the communication channel (ICA policy).

In this particular case the Request consumer identifies the need to ensure that the received SOAP message has not been accidentally or deliberately corrupted, therefore the message MUST be digitally signed and the signature is valid.

Once the message has been received, the component stores the digital signature for non-repudiation purposes.


In addition to the previously mentioned solutions, the eTrustEx exchange platform can offer an extra feature, known as the data integrity supported. The feature can be used in convergence with any of the previously defined integrity levels.

This feature falls in the category of “end-to-end integrity”, where the security safeguard is enforced by the end points. In order to achieve “end-to-end integrity” the current xml structure will be extended to include digital signature. The digital signature will be included in the payload and will be re-used in the context of e-Signature for business purposes. The xml document subject to digital signature will be the DocumentBundle that will include the unique identifiers of the DocumentWrappers with their associated hash values.

Figure 7 Signed Document Bundle

XAdES standard will be used and based on the EC Directive 2011/130/EU and it has to meet the following requirements:

The signature is conform with the W3C XML Signature specifications ( 2 )

The signature MUST at least be a XAdES-BES (or -EPES) signature form as specified in the ETSI TS 101 903 XAdES specifications ( 3 ) and complies with all the following additional specifications:

The ds:CanonicalizationMethod that specifies the canonicalization algorithm applied to the SignedInfo element prior to performing signature calculations identifies one of the following algorithms only:

Canonical XML 1.0 (omits comments): http://www.w3.org/TR/2001/REC-xml-c14n-20010315

Canonical XML 1.1 (omits comments): http://www.w3.org/2006/12/xml-c14n11

Exclusive XML Canonicalization 1.0 (omits comments): http://www.w3.org/2001/10/xml-exc-c14n#


http://www.w3.org/2001/10/xml-exc-c14n#

Concerning the data model for the XAdES signature, the reader should consult ETSI standard [REF46].

2.3.3. Availability

To be completed.

2.3.4. Authenticity

The boundary that separates the service caller and e-TrustEx can be seen as a boundary between the external world and the internal system of DIGIT. To cross the boundary, a service caller needs to authenticate himself to e-TrustEx. Authentication is the process of determining if the service caller is who he/she claims it is.

Depending on the security level required for the service caller, different factors for authentication are used.

For systems with “LIMITED BASIC” as confidentiality level and “MODERATE” as integrity level the HTTP basic authentication is being used (username/password).

For systems with “LIMITED HIGH” as confidentiality level and “STRATEGIC” as integrity level authentication based on a digital signature is being used. The claimant signs the message using the secret key. The claimant’s digital certificate3together with the signature, stand as a proof that the claimant is who he/she claims to be.

2.3.5. Authorisation

After the service caller has been authenticated the authorisation process starts. The authorisation process is about determining if someone can be given permission to do or to have something.

The following information is being used for the authorisation:

Authentication data: The user identity together with the Sender Party ID (found in the SOAP header) enables the system to link the User to a Party Agreement.

The User and Sender Party ID is joint in the form of a Party Agreement which, when valid, enables the User to access the data linked to the specific Party Agreement (and only this one) via Read Services.

The Party Agreement together with the Receiver ID (also found in the authorisation header) generates the Interchange Agreement. This logical entity authorises the use of Write services between two parties referred to as Sender and Receiver in the message header.

2.3.6. Logging and monitoring

In the context of security, logging is the process where systems create and store records of events for further analysis of security breaches. As a result, logging can help minimise the impact of the following security threads:

Software malfunction3 All the connected systems that are authenticated based on digital signature, must have the

digital certificate configured in e-TrustEx


Unauthorised use of equipment

Corruption of data

Illegal processing of data

Error in use

Abuse of rights

Forging of rights

Denial of action

An event is any observable occurrence in a system and/or network, usually involving an attempted state change. Events sometimes provide indication that an incident is occurring.

The table below summarises the type of events that will be logged by the e-TrustEx platform:

Table 3 Events to be logged

Event category Event sub-category

End-user registration

[when eTrustEx GUI is used]

Request access

Assign party to user

Validate party/ ECAS assignment

User access GUI for the first time

Party registration Create Party Id

Create system user

Update user password

Create Sender/Receiver Party agreement

Create interchange agreement

Enable logs

End-user management Update user information

Disable user

Delete user

Party management Update party information

Disable party

Delete party

ICA management Update party information

Disable ICA

Delete ICA

Access control Successful login

Failed attempt

Locked accounts

User access termination


Segregation of duties violations

Access to sensitive data and systems

Access to data and systems by privileged users

Privileges management

Session information Session information

Transaction information Transaction information

Log security Overwrite

Delete

Update

The table below summarises the different types of computer devices or applications that are part of the scope:

Table 4 Devices in scope

Authentication servers

Authentication requests, including username and originating application/server

Proxy servers Proxy requests including results (accepted / rejected + reason etc.)

Application software

As per the section above on "Non-personal devices" but at the application level

Changes to sensitive application data

Out of the scope of the solution described in this document are the following devices:

Table 5 Devices out of scope

Personal firewalls Network traffic to and from the host computer as defined by the system owner (no specific requirements but see section Error: Reference source not found below for rules on network firewalls)

Administrative logins

Configuration changes

Firewall service start-up & shutdown

Intrusion detection / prevention systems

Information security events to be determined during device configuration4

4 IDS/IPS log contents are too complex and proprietary to be detailed in this standard.


Anti-malware software

Virus definitions and software updates

Manual scan launches and results

Malware incidents

Remote access software

Remote user logins & logouts

Registration, modification or deletion of user access tokens (where used)

Vulnerability management software

Scans for updates

Successful or failed installation of updates

Routers and switches

[No additional requirements]

2.4. Communication modes

E-TrustEx uses two main communication modes:

Table 6 Communication modes

Communication mode

Functional description Technical protocol

Type of requests

(1) Synchronous Allows the User to quickly know the result of Read Requests requiring fast processing and where e-TrustEx passes the results to the requester without delay, or Write requests where no response from the receiver is expected (cf. the sending of a binary file)

Request – Response SOAP web service over HTTP

Read Requests

Write request not requiring an application response

(2) Asynchronous Usually used for Write Requests for which e-TrustEx needs a significant processing time. During this period the User benefits from read requests to periodically check the message status (2: Read Request), and ultimately fetch and process them (3: Read Request).

Request – Response SOAP web service over HTTP

Write Requests

The different interactions involved for those communication modes are depicted in the diagrams below:


Figure 8 – Synchronous communication mode interactions

Figure 9 – Asynchronous communication mode interactions

2.5. The Send/Receive interaction scenario

The following scenario depicts the most common use of e-TrustEx by both Senders and Receivers.


e-TrustEx

Store Document Wrapper

Ack WorkA

Submit Document Bundle

Ack

Work

B

Submit Inbox Request

Inbox Response CWorkWork

Submit Retrieve Request

Retrieve Response

WorkWork D

Submit Retrieve Document Wrapper Request

Retrieve Document Wrapper Response EWorkWork

SENDER RECEIVER

Figure 10 – Send/Receive Communication scenario

Table 7 Send/Receive interaction scenario

Step ID Description Communication mode

A The Sender submits a Document Wrapper containing the binary file to be further attached and sent via a Document Bundle.

E-TrustEx responds with an Aknowledgment meaning that the Document Wrapper has been successfully stored onto the server.

This step can be repeated as many times as necessary since the Document Bundle can reference up to 500 Document Wrappers.

Synchronous


Step ID Description Communication mode

B The Sender prepares and submits a Document Bundle which encloses the reference(s) to the previously sent Document Wrapper(s).

E-TrustEx responds synchronously with a technical Aknowledgment (Ack) meaning that the message is accepted for processing, and closes the connection.

Asynchronous

C The Receiver checks its Inbox via an Inbox Request.

E-TrustEx synchronously responds with the Inbox Response containing all documents addressed to the Receiver and still not retrieved by the Receiver.

Synchronous

D The Receiver retrieves the received Document Bundle by invoking the Retrieve service.

The references to the attached binary files are found in the Document Bundle and shall be used to perform the next step.

Synchronous

E The Receiver can download the files that have been received as part of the Document Bundle by invoking the Retrieve Document Wrapper service for each of the binaries referenced thereby.

Synchronous

Section Error: Reference source not found describes the processing of messages in more details for each of the services mentioned in the above table.


2.6. Reusable Schema Definitions

According to the work of CEN/ISSS WS/BII, the Universal Business Language (UBL, see [REF25]) by OASIS is the framework used in, the definition of the documents to be exchanged. According to this specification:

“The UBL Library is based on a conceptual model of information components known as Business Information Entities (BIEs). These components are assembled into specific document models. These document assembly models are then transformed in accordance with the UBL Naming and Design Rules into W3C XSD schema syntax.”

This means that a well-defined library of reusable data components will be used throughout several documents enabling an enterprise-wide semantic model instead of a per-document silo definition. The diagram below shows the dependencies among the several schema modules of most UBL XML document schemas (see [REF26])

Figure 11 UBL Documents Architecture

eTrustEx implements a two-phase document validation for maximum flexibility in configuring and updating business rules (such as compliance to predefined code-lists – see ICD\Annexes\002_Data_Dictionary\000_CodeTables).

In the first validation phase, the UBL instance is checked against its XSD. In the second validation phase, documents are checked against specific business rules mostly implemented using a Schematron XSLT (see [REF27]). This second phase has no impact on the schemas.


2.7. Document processing considerations

2.7.1. Maximum Message Size

The messages submitted to e-TrustEx must not exceed 5 MB. If a message larger than 5 MB is submitted, the HTTP connection will be closed with a HTTP 413 code (Request Entity Too Large) without further notice (neither a synchronous fault response nor an asynchronous application response).

2.7.2. Maximum Binary file size and total storage capacity

Binary files attached to a message must not exceed 100MB each. If a larger binary file is submitted the SLA rules5 are broken and a specific synchronous SOAP fault will be generated (see section Error: Reference source not found).

Similarly when a submitted binary file increases the total storage capacity beyond the maximum allowed limit the SLA rulesError: Reference source not found are broken and a specific synchronous SOAP fault will be generated (see section Error: Reference source notfound).

2.7.3. Unique Message ID and Reliable Message Delivery

Reliable message delivery is required to avoid that Write Request Messages (i.e. Document Bundles, Document Wrappers…) are processed more than once. Duplication of messages may happen due to error, multiple retries following a communication failure and similar situations. The design of the endpoints of the Write services aims at a situation where repeated executions of the same request have the same effect as a single execution of the request, avoiding the processing of duplicate instances of the same message (idempotent endpoints). It should be noticed that Read Requests are naturally idempotent since the submission of multiple instances of the same request does not have side effects apart from the unnecessary consumption of resources.

The natural consequence, of the above, is that every Write Request should be processed, by e-TrustEx, once-and-once-only. This point requires some additional reflection. Every message will be checked regarding multiple aspects not only its uniqueness (this is an important rule to keep in mind). These checks can be summed up in:

Validity of the Payload Type via the SOAP Body Wrapper element;

Validity according to the message XSD; and

The uniqueness of the message ID per document type, Sender Party and in the relevant cases the Receiver Party. If the same Write Request is sent more than once, the second attempt (and other) will generate a duplicate message ID exception. This will prevent that multiple instances of the same request are processed by e-TrustEx.

The first point to keep in mind is that the detection of duplicate requests is made via the unique message ID. The second point to keep in mind is that the above steps are sequential. The next section will look closer to the message ID and its role in the reliable delivery of the message and the idempotent behaviour of the end-point.

Putting it all together this means that:

1) The ID is part of the payload of the message provided by the Sender i.e. the Sender manages the IDs of the message, not e-TrustEx.

5 See Error: Reference source not found for exact details about SLA rules


2) The structure of the ID is the Sender's responsibility. The following rules are imposed:

Any blanks in the right or left side of the ID will be trimmed so that the instances below are understood as the same one:

1

1

1

Only characters from the 7-bit ASCII table will be allowed in the message ID to prevent any issues with special characters. This full list of allowed characters is as follows (in addition to the space character):

Alphabetic characters ABCDEFGHIJKLMNOPQRSTUVWXYZ

abcdefghijklmnopqrstuvwxyz

Numeric characters 0123456789

Other characters !"#$%&'()*+,-./:;<=>?@ [\]^_`{|}~

Messages IDs which contain invalid characters, such as shown in the below examples, will not be accepted by e-TrustEx.

<cbc:ID>BUNDLE N° 575197</cbc:ID> (because of °)

<cbc:ID>Bundle 9300015023 - Référence 7052</cbc:ID> (because of é)

<cbc:ID>2ième partie</cbc:ID> (because of è)

3) The message ID will be the surrogate for any informational service on the Write Request submitted by the caller. This can be status request, a retrieve request of other.

The following keys will be used to define the unique ID per message type:

A Document Bundle is uniquely identified thanks to its:

ID Type Sender Party Receiver Party

A Document Wrapper is uniquely identified thanks to its:

ID Type Sender Party


2.8. Service versioning

There are countless reasons why Services need to evolve after being live. A few of them include:

Bugs may need to be fixed. Changing requirements. Different flavours of a Service may be desirable.Whatever the cause, over time, the service will evolve and this will mandate the versioning of the interface’s XML Documents beyond construction.

The most important aspects of the evolution are captured in the table below:

Table 8 Service versioning

Type of Evolution Re-use of the document’s namespace

names?

Required migration of old versions?

Backwards compatible evolution Yes No

Backwards semi-compatible evolution Yes Yes

Backwards incompatible evolution No Yes

2.8.1. Backward compatible evolution (most likely for Read Services) An evolution is Backward compatible when the newer version of a service interface can be rolled-out without breaking its existing consumers. Examples of such changes are provided in the table below:

Table 9 Backward Compatible Change

Artefact Backward Compatible Change

XSD Adding optional elements or attributes to a namespace Increasing the maximum allowed number of occurrences of an element

or attribute.Schematron Adding business rules which only produce warnings.

Extending the content of a Code Table.WSDL Adding a SOAP Header Block which can be ignored.

This means that the service’s interface is extended in a way that its previous versions continue to be supported.

When the new version of the service supports its usage by old and new versions of its consumers, the optimal evolution strategy is simply to update the service when required. This scenario is most likely to be case for the evolution of the Read Services.

In this case the re-use of the document’s namespace names is possible. If a backward compatible change is made to a service exposed by e-TrustEx, then the old namespace name is used.

2.8.2. Semi-backward compatible evolution (most likely for Write Services) An evolution is semi-backward compatible when the newer version of a service imposes additional mandatory constraints to existing consumers.


Artefact Incompatible Change

Business Rules

Restricting the content model via a hard constraint. Restricting the content of a Code Table.

In this case the re-use of the documents’ namespace names is possible. If a semi-backward compatible change is made to a service exposed by e-TrustEx, then the old namespace name is used.

2.8.3. Backward incompatible evolution (most likely for Write Services) An evolution is incompatible when the newer version of a service interface imposes additional mandatory constraints to existing consumers. Examples of such changes are provided in the table below:

Table 10 Incompatible evolution

Artefact Incompatible Change

XSD Adding of mandatory elements to an XML Schema. Restricting the XSDs content model, such as changing a choice to a

sequence in XML. Removing mandatory elements to an XML Schema. Significant semantic changes to existing core components.

WSDL Adding a SOAP Header Block which must be understood.

When the new version of the service impacts the interpretation and validation of the old interface’s XML Documents, the service can no longer be used by old consumers. In this case multiple versions of the service will be kept running in the same runtime environment until the old one is made unavailable. In this case two (or more) versions of the same service coexist.

In this case the XML parser linked to the new version of the service will require that the new version and related schemas are used. Therefore, users will be required to adapt their implementation of the interface before the service is made unavailable.


3. SERVICES

3.1. Overview

The table below provides a list of services provided by e-TrustEx.

Table 11 e-TrustEx services

Read/Write Service Service Name Communication mode

Write Submit Document Bundle Asynchronous

Store Document Wrapper Synchronous

Delete Document Wrapper Synchronous

Submit Application Response Asynchronous

Read Retrieve Document Wrapper Synchronous

Inbox Request Synchronous

Retrieve Request Synchronous

Retrieve Interchange Agreement Synchronous

Query Request Synchronous

Status Request Synchronous

View Request Synchronous

3.2. Detailed description per service

3.2.1. Pre-conditions

Before having access to any service the service caller has to be authenticated and authorised by the system.

Authentication constitutes the process of verifying the claimed identity of a User. The factors used for the authentication depend on the level of security required for this communication channel. For more details, the reader should revise the chapter Error: Reference source notfound Error: Reference source not found.

Authorisation constitutes the process of assertion whether the service caller can be given permission to do have access to the Read and/or Write services. For more details, the reader should revise the chapter Error: Reference source not found Error: Reference source notfound.

The following table lists the potential errors returned during the authentication and authorisation process.


Table 12 Authentication and Authorisation errors

Error Cause

– An HTTP Error with the code “401 – Unauthorised”.

The 401 “Unauthorized” Client Error may occur in one of the following circumstances:

The authentication data is incorrect

The authentication data is missing

A SOAP Fault is returned with:

– Response code = 2– Description = "Undefined operation"

The XML integrity check failed because the message Body does not contain only one direct child element.


– Response code = 1Description = "Undefined incoming message"

The XML integrity check failed because the XML wrapper element does not contain one and only one element.



– Response code = 5– Description = " Unauthorized Access "

SOAP fault that may occur in one of the following circumstances:

The Sender Party Agreement does not exist or it cannot be retrieved.

Envelope lacks header elements in the header block.

The security parameter for integrity is higher than MODERATE and the digital signature is missing.

The security parameter for integrity is higher than MODERATE and the certificate is not trusted.

The Interchange Agreement does not exist or cannot be retrieved by the System.

The Interchange Agreement exist however it is not active (Start Date of the Interchange Agreement is in the future).

The security parameter for integrity is higher than MODERATE and the digital signature is missing.

The security parameter for integrity is higher than MODERATE and the digital signature is not valid.

The security parameter for integrity is higher than MODERATE and the digital certificate used for the digital signature is not trusted.

The user tried to consume a service for which it does not have permission.


– Description = " Server Error "

The system cannot process the message because of an anomalous condition.

The security parameters cannot be retrieved


– Response code = 6Description = " Message has been corrupted "

The security parameter for integrity is higher than MODERATE and the digital signature is not valid.


3.2.2. Submit Document Bundle service

Operation Name SubmitDocumentBundle UC reference: [REF1]

Endpoint Type HTTP SOAP Web Service WSDL reference: [REF8]

Input schema DocumentBundle XSD reference: [REF12]

Output schema Ack XSD reference: [REF21]

The processing of a Submit Document Bundle request is divided in two distinct parts:

Firstly a synchronous part is going to provide direct feedback to the caller:

In case of success the system responds with a technical acknowledgment (a.k.a. Ack) with the indicator set to “TRUE”. The technical acknowledgment is digitally signed. The following table lists the main elements contained in the technical acknowledgment:

Table 13 Submit Document Bundle - Ack

Element Xpath

ID The ID of the Acknowledgement

AckIndicator AckIndicator – Boolean value

ID of the Bundle message

AcknowledgedDocumentReference.DocumentReference.ID

DocumentTypeCode AcknowledgedDocumentReference.DocumentReference.DocumentTypeCode ( “BDL”)

SenderPartyID AcknowledgedDocumentReference.DocumentReference.SenderParty.EndpointID – the Sender Party ID from the business header of the SubmitDocumentBundleRequest

ReceiverPartyID AcknowledgedDocumentReference.DocumentReference.ReceiverParty.EndpointID - the Receiver Party ID from the business header of the SubmitDocumentBundleRequest

DocumentHashMethod AcknowledgedDocumentReference. DocumentHashMethod – the hash method used to hash the received Bundle message

DocumentHash AcknowledgedDocumentReference. DocumentHash – the hash value of the received Bundle message

DocumentCanonicalizationMethod

AcknowledgedDocumentReference. DocumentCanonicalizationMethod – the canonicalization method used before the hashing of the received Bundle message

If a problem is detected, a SOAP Fault is returned according to the Submit Document Bundle UC [REF1] and the Fault Events document [REF7].

Secondly an asynchronous part is going to perform all the necessary checks for successful delivery.


In case of success, the state of the document is set to “RECEIVED”

If a problem is detected during the second asynchronous part, an error message is delivered to the Sender's inbox as described in Error: Reference source not found.

Figure 12 Document bundle communication workflow

In addition to the processing described above, there is an extra step related to the Receiver Party Processing. In the case where the Receiver Party consumes the Document Bundle, the state of the document changes to “READ”. The state change is triggered when the Receiver Party submits an Application Response (for the Application Response code, please see REF[41]).


The following table lists the potential errors returned during the processing of the message.

Table 14 Document Bundle possible errors

Error Cause

Sync

hron

ous p

art

An HTTP Error with the code “503 – Service Unavailable”.

At the time of the service call, the system is down.


– Description = " Server Error "

A technical error occurs when the message is being submitted to the queue.

An error message of type "Application Response" is stored in the Sender's inbox with:

– Response code = BDL:3– Type = 301 (for Application Response).

Another message with the same message ID has been already submitted.


– Response code = BDL:4– Type = 301 (for Application Response)

The Application Response may occur in one of the following circumstances:

At least one business rule of hard severity has been violated.

The message is invalid against the input schema.



The referenced parent (bundle) document doesn't exist.

An error message of type "Application Response" is stored in the sender's inbox with:


The message must reference Document Wrapper(s) that don't exist (not stored in the system).

In case of error, the Document Bundle is neither stored nor delivered to the recipient.


If the message passes all the checks, it is stored in the inbox of the Recipient with:

Type = BDL (for Bundle Document)

No response code

Status = RECEIVED

3.2.3. Store Document Wrapper service

Operation Name StoreDocumentWrapper UC reference: [REF2]


Input schema DocumentWrapper XSD reference: [REF14]


The processing of a Store Document Wrapper request is fully synchronous and should be considered as a single, atomic step.

If a problem is detected a SOAP Fault is returned according to the Store Document Wrapper UC [REF2] and the Fault Events document [REF7]. In case of error, the Document Wrapper is not stored onto the e-TrustEx platform.


Table 15 Store Document Bundle errors

Error Cause



A SOAP fault is returned with:

– Response code = 1

– Description of the non conforming XML

The message is not valid against the input schema.


– Response code = DWR:4

– Description of the failed rule




– Description of the failed check

The message ID has already been received previously.




An error occurred while trying to persist the binary file




The message breaks one of the SLA rules (as per Error: Reference source not found)


If the message passes all the checks, it is stored in database with:

Type = value provided by the Sender in the message payload

Reference to the binary file

In addition a positive acknowledgment (Ack) is returned. The technical acknowledgment is digitally signed. The following table lists the main elements contained in the technical acknowledgment:

Table 16 Store Document Wrapper - Ack

Element Xpath



Timestamp The timestamp, used to offer long-term and independent proof that the information existed at a particular point in time and has not been altered since and can be expressed as :

A digital signature

RFC3161TimeStampToken

ID of the DocumentWrapper message


SenderPartyID AcknowledgedDocumentReference.DocumentReference.SenderParty.EndpointID – the Sender Party ID from the business header of the Store Document Wrapper Request

ReceiverPartyID AcknowledgedDocumentReference.DocumentReference.ReceiverParty.EndpointID - the Receiver Party ID from the business header of the Store Document Wrapper Request

DocumentHashMethod AcknowledgedDocumentReference. DocumentHashMethod – the hash method used to hash the received Store Document Wrapper message

DocumentHash AcknowledgedDocumentReference. DocumentHash – the hash value of the received Store Document Wrapper message


AcknowledgedDocumentReference. DocumentCanonicalizationMethod – the canonicalization method used before the hashing of the received Store Document Wrapper message

3.2.4. Delete Document Wrapper service

Operation Name deleteDocumentWrapperRequest UC reference: [REF28]


Input schema DocumentWrapperRequest XSD reference: [REF14]



The processing of a Delete Document Wrapper request is fully synchronous and should be considered as a single, atomic step.

If a problem is detected a SOAP Fault is returned according to the Delete Document Wrapper UC [REF28] and the Fault Events document [REF7].


Table 17 Delete Document Wrapper - errors

Error Cause








– Description = "Hard business rule violated"




Description = " Document Wrapper cannot be deleted because it doesn't exist "

When trying to delete a Document Wrapper, the Document Wrapper does not exist.



– Description = " Document Wrapper cannot be deleted because it is already linked to a Document Bundle "

When trying to delete the Document Wrapper, the Document Wrapper is linked to a Document Bundle.


Description = “Server Error”

An unexpected error occurred during the processing of the message

If the request processing is successful, a positive acknowledgment (Ack) digitally signed is returned. The following table lists all the elements of the acknowledgment.

Table 18 Delete Document Wrapper - Ack

Element Xpath



ID of the Bundle message


SenderPartyID AcknowledgedDocumentReference.DocumentReference.SenderPart


y.EndpointID – the Sender Party ID from the business header of the Delete Document Wrapper Request

ReceiverPartyID AcknowledgedDocumentReference.DocumentReference.ReceiverParty.EndpointID - the Receiver Party ID from the business header of the Delete Document Wrapper Request

DocumentHashMethod AcknowledgedDocumentReference. DocumentHashMethod – the hash method used to hash the received Delete Document Wrapper message

DocumentHash AcknowledgedDocumentReference. DocumentHash – the hash value of the received Delete Document Wrapper message


AcknowledgedDocumentReference. DocumentCanonicalizationMethod – the canonicalization method used before the hashing of the received Delete Document Wrapper message

3.2.5. Submit Application Response

Operation Name SubmitApplicationResponseRequest UC reference: [REF29]


Input schema ApplicationResponse XSD reference: [REF31]


The processing of a Submit Application Response request is divided in two distinct parts:

Firstly a synchronous part is going to provide direct feedback to the caller:

In case of success the system responds with a technical acknowledgment (a.k.a. Ack) with the indicator set to “TRUE”. The technical acknowledgment is digitally signed. The following table lists the main elements contained in the technical acknowledgment:

Table 19 Submit Application Response - Ack

Element Xpath



ID of the ApplicationResponse message


DocumentTypeCode AcknowledgedDocumentReference.DocumentReference.DocumentTypeCode ( “301”)

SenderPartyID AcknowledgedDocumentReference.DocumentReference.SenderPart


y.EndpointID – the Sender Party ID from the business header of the SubmitApplicationResponseRequest

ReceiverPartyID AcknowledgedDocumentReference.DocumentReference.ReceiverParty.EndpointID - the Receiver Party ID from the business header of the SubmitApplicationResponseRequest

DocumentHashMethod AcknowledgedDocumentReference. DocumentHashMethod – the hash method used to hash the received Bundle message

DocumentHash AcknowledgedDocumentReference. DocumentHash – the hash value of the received ApplicationResponse message


AcknowledgedDocumentReference. DocumentCanonicalizationMethod – the canonicalization method used before the hashing of the received ApplicationResponse message

If a problem is detected, a SOAP Fault is returned according to the Submit Document Bundle UC [REF1] and the Fault Events document [REF7].

Secondly an asynchronous part is going to perform all the necessary checks for successful delivery.

In case of success, the document is being persisted

If a problem is detected during the second asynchronous part, an error message is delivered to the Sender's inbox as described in the below table :

Table 20 Submit Application Response - errors

Error Cause




– Description = “Server Error”

An unexpected error occurred during the processing of the message.


– Response code = 301:4

– Description = “Hard business rule violated”




– Description = “Hard business rule violated”





– Description = “Parent document ID does not exist”

The parent document of the Application Response does not exist.



– Description = “Parent document state is wrong”

The parent document of the Application Response is not in the correct state.



Description = “Application Response ID already exists”

Another Application Response with the same ID has already been submitted.

3.2.6. Retrieve Document Wrapper service

Operation Name RetrieveDocumentWrapperRequest UC reference: [REF3]


Input schema DocumentWrapperRequest XSD reference: [REF16]

Output schema DocumentWrapper XSD reference: [REF14]

The processing of a Retrieve Document Wrapper request is fully synchronous and should be considered as a single, atomic step.

If a problem is detected a SOAP Fault is returned according to the Retrieve Document Wrapper UC [REF3] and the Fault Events document [REF7].


Table 21 Retrieve Document Wrapper - errors

Error Cause















If the request processing is successful, a RetrieveDocumentWrapperResponse is returned with:

The Document Wrapper (might be empty if not matching document was found)

The binary file attached in the MIME multipart

No response code

3.2.7. Inbox Request service

Operation Name InboxRequest UC reference: [REF4]


Input schema InboxRequest XSD reference: [REF17]

Output schema InboxResponse XSD reference: [REF18]

The processing of an Inbox request is fully synchronous and should be considered as a single, atomic step.

If a problem is detected a SOAP Fault is returned according to the Inbox Request UC [REF4] and the Fault Events document [REF7].


Table 22 Inbox Request - errors

Error Cause










If the request processing is successful, a RetrieveInboxResponse is returned with:

The set of matching documents (might be empty if not matching document was found)

3.2.8. Retrieve Request service

Operation Name RetrieveRequest UC reference: [REF5]


Input schema RetrieveRequest XSD reference: [REF19]

Output schema RetrieveResponse XSD reference: [REF20]

The processing of a Retrieve request is fully synchronous and should be considered as a single, atomic step.


If a problem is detected a SOAP Fault is returned according to the Retrieve Request UC [REF5]and the Fault Events document [REF7].


Table 23 Retrieve Request - errors

Error Cause














If the request processing is successful, a RetrieveRequestResponse is returned with:

The single matching document (potentially none).

3.2.9. Retrieve Interchange Agreement

Operation Name submitRetrieveInterchangeAgreementsRequest

UC reference:[REF32]

Endpoint Type HTTP SOAP Web Service UC reference: [REF33]

Input schema RetrieveInterchangeAgreementsRequestRequest

UC reference: [REF34]

Output schema RetrieveInterchangeAgreementsRequestResponse

UC reference: [REF35]

The processing of a Retrieve Interchange Agreement is fully synchronous and should be considered as a single, atomic step.

If a problem is detected a SOAP Fault is returned according to the Retrieve Interchange Agreement UC [REF32] and the Fault Events document [REF7].


Table 24 Retrieve Interchange Agreement - errors

Error Cause

– An HTTP Error with the code “503 – Service Unavailable”.














If the processing finishes successfully, a RetrieveInterchangeAgreementsRequestResponse is returned. The response contains information about one or more matching Interchange Agreements.

3.2.10. Query Request

Operation Name submitQueryRequest UC reference: [REF36]


Input schema QueryRequest XSD reference: [REF38]

Output schema QueryResponse XSD reference: [REF39]

The processing of a Query request is fully synchronous and should be considered as a single, atomic step.

If a problem is detected a SOAP Fault is returned according to the Query Request UC [REF36] and the Fault Events document [REF7].


Table 25 Query Request - errors

Error Cause

– An HTTP Error with the code “503 – Service Unavailable”.














If the processing finishes successfully, a QueryResponse is returned with the matching documents (0 or more).

3.2.11. Status Request

Operation Name StatusRequest UC reference: [REF42]

Endpoint Type HTTP SOAP Web Service WSDL reference:[REF43]

Input schema StatusRequest XSD reference: [REF44]

Output schema StatusResponse XSD reference: [REF45]

The processing of a Status request is fully synchronous and should be considered as a single, atomic step.

If a problem is detected a SOAP Fault is returned according to the Status Request UC [REF42] and the Fault Events document [REF7].


Table 26 Status Request - errors

Error Cause


Response code = 1




– Description = " The Sender Party Endpoint ID and the Receiver Party Endpoint ID must be present in the message payload "




Description = " The Sender Party Endpoint ID and the Receiver Party Endpoint ID must be present in the message payload The Sender Party Endpoint ID or the Receiver Party Endpoint ID must be equal to the Sender Party Endpoint ID specified in the Business Header "


If the request processing is successful, a StatusRequestResponse is returned with:

The single matching document (potentially none).

3.2.12. View Request

Operation Name ViewRequest UC reference: [REF47]

Endpoint Type HTTP SOAP Web Service WSDL reference:[REF48]


Input schema ViewRequest XSD reference: [REF49]

Output schema XSD reference:

The processing of a View request is fully synchronous and should be considered as a single, atomic step.

If a problem is detected a SOAP Fault is returned according to the View Request UC [REF47] and the Fault Events document [REF7].


Table 27 View Request - errors

Error Cause




Response code = 1


The request processing is successful finished if:

A Single document matches the previously mentioned criteria

The MIME type specified in the system is text/html

As a result a business document is returned in HTML format.
