DIRECTORATE-GENERAL
INFORMATICS
Information systems Directorate
European Commission
e-TrustEx Interface Control Document
Version: / 0.007
Authors: / Sonia Tafaro, Alice Vasilescu, D'Orazio Sandro
Revised by: / Maarten Daniels, Fausto Rubino
Approved by:
Public:
Reference Number:
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 16
2.3. Security considerations 18
2.3.1. Confidentiality 19
2.3.2. Integrity 20
2.3.3. Availability 23
2.3.4. Authenticity 23
2.3.5. Authorisation 24
2.3.6. Logging and monitoring 24
2.4. Communication modes 27
2.5. The Send/Receive interaction scenario 28
2.6. WS Addressing and “Store-and-Forward” 30
2.6.1. “Store-and-Forward” 30
2.6.2. WS-Addressing 30
2.7. Reusable Schema Definitions 31
2.8. Document processing considerations 32
2.8.1. Maximum Message Size 32
2.8.2. Maximum Binary file size and total storage capacity 32
2.8.3. Unique Message ID and Reliable Message Delivery 32
2.9. Service versioning 34
2.9.1. Backward compatible evolution (most likely for Read Services) 35
2.9.2. Semi-backward compatible evolution (most likely for Write Services) 35
2.9.3. Backward incompatible evolution (most likely for Write Services) 35
3. Services 37
3.1. Overview 37
3.2. Detailed description per service 37
3.2.1. Pre-conditions 37
3.2.2. Submit Document Bundle service 40
3.2.3. Store Document Wrapper service 43
3.2.4. Delete Document Wrapper service 44
3.2.5. Submit Application Response 46
3.2.6. Retrieve Document Wrapper service 48
3.2.7. Inbox Request service 49
3.2.8. Retrieve Request service 50
3.2.9. Retrieve Interchange Agreement 50
3.2.10. Query Request 51
3.2.11. Status Request 52
3.2.12. View Request 53
3.2.13. Submit Document Bundle Justice Request 54
3.2.14. Query Justice Request 55
TABLE OF FIGURES
Figure 1 e-TrustEx platform 7
Figure 2 – e-TrustEx at a glance 14
Figure 3 Component Relationships View 15
Figure 4 – The Interchange Agreement 17
Figure 5 Encryption of sensitive information using an Applet 20
Figure 6 Two-phased document validation 21
Figure 7 Data integrity supported - design description 22
Figure 8 Signed Document Bundle 23
Figure 9 – Synchronous communication mode interactions 28
Figure 10 – Asynchronous communication mode interactions 28
Figure 11 – Send/Receive Communication scenario 29
Figure 12 WS-Addressing and Store-and-Forward 31
Figure 13 UBL Documents Architecture 32
Figure 14 Document bundle communication workflow 41
LIST OF TABLES
Table 1 Data classification 18
Table 2 Design description 22
Table 3 Events to be logged 25
Table 4 Devices in scope 26
Table 5 Devices out of scope 26
Table 6 Communication modes 27
Table 7 Send/Receive interaction scenario 29
Table 8 Service versioning 34
Table 9 Backward Compatible Change 35
Table 10 Incompatible evolution 36
Table 11 e-TrustEx services 37
Table 12 Authentication, Authorisation and Id related errors 38
Table 13 Submit Document Bundle - Ack 40
Table 14 Document Bundle possible errors 42
Table 15 Store Document Bundle errors 44
Table 16 Store Document Wrapper - Ack 45
Table 17 Delete Document Wrapper - errors 46
Table 18 Delete Document Wrapper - Ack 46
Table 19 Submit Application Response - Ack 47
Table 20 Submit Application Response - errors 48
Table 21 Retrieve Document Wrapper - errors 50
Table 22 Inbox Request - errors 51
Table 23 Retrieve Request - errors 51
Table 24 Retrieve Interchange Agreement - errors 52
Table 25 Query Request - errors 53
Table 26 Status Request - errors 54
Table 27 View Request - errors 55
Table 27 Submit Technical Ack 55
Document History
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
0.006 / 13/12/2013 / Update of Ack and error tables / As required
0.007 / 09/12/2013 / Internal review – migration to the new architecture / 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 the Justice domain, it enables citizens through the use of the Justice portal to submit cross border claims.
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 Administrations. Its main elements, coarse grained view, are shown in the model below.
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’ state[1].
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 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 / Descriptione-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.
e-TrustEx Interface Control Document - Page 10
Document Version 0.007 dated 13/12/2013
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] / DocumentWrapper xsd / XML schema for the Document Wrapper.
[REF14] / DocumentWrapperRequest xsd / XML schema for the Document Wrapper request.
[REF15] / InboxRequest xsd / XML schema for the Inbox request.
[REF16] / InboxResponse xsd / XML schema for the Inbox response.
[REF17] / RetrieveRequest xsd / XML schema for the Retrieve request.
[REF18] / RetrieveResponse xsd / XML schema for the Retrieve response.
[REF19] / Ack xsd / XML schema for the technical Aknowledgment
[REF20] / Fault xsd / XML schema for the SOAP faults.
[REF21] / e-TrustEx software architecture document / eTrustEx SAD
[REF22] / e-PRIOR Interface Control Document / e-PRIOR documentation
[REF23] / OASIS Universal Business Language v2.0 / Universal Business Language v2.0
[REF24] / XML Schema 1.1 / XML Schema
[REF25] / ISO Schematron / ISO/IEC 19757 – 3 : 2006
[REF26] / Delete Document Wrapper Use Case / e-TrustEx use case which describes the deletion of a Document Wrapper.
[REF27] / Submit Application Response Use Case / e-TrustEx use case which describes the deletion of a Document Wrapper.
[REF28] / Application Response wsdl / WSDL which describes the Application Response.
[REF29] / Application Response xsd / XML schema for the Application Response.
[REF30] / Retrieve Interchange Agreement Use Case / e-TrustEx use case which describes the retrieval of the Interchange Agreement.
[REF31] / RetrieveInterchangeAgreement wsdl / WSDL which describes the Retrieve Interchange Agreement.
[REF32] / RetrieveInterchangeAgreementRequest xsd / XML schema for the Retrieve Interchange Agreement Request.
[REF33] / RetrieveInterchangeAgreementResponse xsd / XML schema for the Retrieve Interchange Agreement Response.
[REF34] / Query Request Use Case / e-TrustEx use case which describes the Query Request.
[REF35] / QueryRequest wsdl / WSDL which describes the Query Request.
[REF36] / QueryRequest xsd / XML schema for the Query Request Request.
[REF37] / QueryResponse xsd / XML schema for the Query Request Response.
[REF38] / Rational Unified Process version 7.5 / RUP roles that are part of the target audience.
[REF39] / EC_CodeList_e-TrustEx.xls / Code list tables
[REF40] / Status Request Use Case / e-TrustEx use case which describes the Status Request.
[REF41] / Status Request wsdl / WSDL which describes the Status Request.
[REF42] / StatusRequest xsd / XML schema for the Status Request.
[REF43] / StatusResponse xsd / XML schema for the Status Response.
[REF44] / ETSI TS 101 903 V1.3.2 / ETSI Standard for XML Advanced Electronic Signature (XAdES)
[REF45] / View Request Use Case / e-TrustEx use case which describes the View Request.
[REF46] / View Request wsdl / WSDL which describes the View²² Request.
[REF47] / ViewRequest xsd / XML schema for the View Request.
[REF48] / Submit Justice Bundle Use Case / e-Codex Use Case which describes the specific submit bundle service
[REF49] / Submit Bundle Justice WSDL / WSDL that describes the e-codex submit bundle
[REF50] / Query Request Justice Use Case / e-codex Use Case that describes the specific Query request
[REF51] / Query Request Justice WSDL / WSDL that describes the e-codex specific Submit Query Request
[REF52] / DocumentBundleJustice XSD / XSD that describes the document bundle for e-codex
[REF53] / QueryRequestJustice XSD / XSD that describes the the query request for ecodex
[REF54] / QueryResponseJustice XSD / XSD that describes the the query response for ecodex
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.