EUROPEAN COMMISSION DIRECTORATE-GENERAL INFORMATICS Information systems Directorate European Commission e-TrustEx Interface Control Document Date: 13/07/2012 Version: 0.25 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.
63
Embed
e-TrustEx Interface Control Document - CIRCABC - …€¦ · Web viewe-TrustEx Interface Control Document Date: ... Figure 5 Encryption of sensitive information using an Applet
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
EUROPEAN COMMISSIONDIRECTORATE-GENERALINFORMATICSInformation systems Directorate
e-TrustEx Interface Control Document - Page 5Document Version 0.004 dated 13/07/20122
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
e-TrustEx Interface Control Document - Page 6Document Version 0.004 dated 13/07/20122
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
e-TrustEx Interface Control Document - Page 7Document Version 0.004 dated 13/07/20122
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.
e-TrustEx Interface Control Document - Page 8Document Version 0.004 dated 13/07/20122
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.
e-TrustEx Interface Control Document - Page 9Document Version 0.004 dated 13/07/20122
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 10Document Version 0.004 dated 13/07/20122
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.
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.
e-TrustEx Interface Control Document - Page 14Document Version 0.004 dated 13/07/20122
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:
e-TrustEx Interface Control Document - Page 15Document Version 0.004 dated 13/07/20122
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
e-TrustEx Interface Control Document - Page 16Document Version 0.004 dated 13/07/20122
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.
e-TrustEx Interface Control Document - Page 17Document Version 0.004 dated 13/07/20122
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.
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:
e-TrustEx Interface Control Document - Page 18Document Version 0.004 dated 13/07/20122
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.
e-TrustEx Interface Control Document - Page 19Document Version 0.004 dated 13/07/20122
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.
e-TrustEx Interface Control Document - Page 20Document Version 0.004 dated 13/07/20122
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#
e-TrustEx Interface Control Document - Page 21Document Version 0.004 dated 13/07/20122
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
e-TrustEx Interface Control Document - Page 22Document Version 0.004 dated 13/07/20122
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
e-TrustEx Interface Control Document - Page 23Document Version 0.004 dated 13/07/20122
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
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.
e-TrustEx Interface Control Document - Page 24Document Version 0.004 dated 13/07/20122
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:
e-TrustEx Interface Control Document - Page 25Document Version 0.004 dated 13/07/20122
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 Interface Control Document - Page 26Document Version 0.004 dated 13/07/20122
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
e-TrustEx Interface Control Document - Page 27Document Version 0.004 dated 13/07/20122
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.
e-TrustEx Interface Control Document - Page 28Document Version 0.004 dated 13/07/20122
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.
e-TrustEx Interface Control Document - Page 29Document Version 0.004 dated 13/07/20122
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
e-TrustEx Interface Control Document - Page 30Document Version 0.004 dated 13/07/20122
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
e-TrustEx Interface Control Document - Page 31Document Version 0.004 dated 13/07/20122
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.
e-TrustEx Interface Control Document - Page 32Document Version 0.004 dated 13/07/20122
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.
e-TrustEx Interface Control Document - Page 33Document Version 0.004 dated 13/07/20122
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.
e-TrustEx Interface Control Document - Page 34Document Version 0.004 dated 13/07/20122
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 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:
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.
e-TrustEx Interface Control Document - Page 37Document Version 0.004 dated 13/07/20122
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]).
e-TrustEx Interface Control Document - Page 38Document Version 0.004 dated 13/07/20122
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.
A SOAP Fault is returned with:
– 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:
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.
The following table lists the potential errors returned during the processing of the message.
Table 15 Store Document Bundle errors
Error Cause
An HTTP Error with the code “503 – Service Unavailable”.
At the time of the service call, the system is down.
A SOAP fault is returned with:
– Response code = 1
– Description of the non conforming XML
The message is not valid against the input schema.
A SOAP fault is returned with:
– Response code = DWR:4
– Description of the failed rule
At least one business rule of hard severity has been violated.
A SOAP fault is returned with:
– Response code = DWR:3
– Description of the failed check
The message ID has already been received previously.
A SOAP fault is returned with:
– Response code = DWR:6
– Description of the failed check
An error occurred while trying to persist the binary file
A SOAP fault is returned with:
– Response code = DWR:7
– Description of the failed check
The message breaks one of the SLA rules (as per Error: Reference source not found)
e-TrustEx Interface Control Document - Page 40Document Version 0.004 dated 13/07/20122
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
ID The ID of the Acknowledgement
AckIndicator AckIndicator – Boolean value
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 :
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
DocumentCanonicalizationMethod
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]
Endpoint Type HTTP SOAP Web Service WSDL reference: [REF9]
e-TrustEx Interface Control Document - Page 41Document Version 0.004 dated 13/07/20122
Output schema Ack XSD reference: [REF21]
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].
The following table lists the potential errors returned during the processing of the message.
Table 17 Delete Document Wrapper - errors
Error Cause
An HTTP Error with the code “503 – Service Unavailable”.
At the time of the service call, the system is down.
A SOAP fault is returned with:
– Response code = 1
The message is not valid against the input schema.
A SOAP Fault is returned with:
– Response code = DWR:4
– Description = "Hard business rule violated"
At least one business rule of hard severity has been violated.
A SOAP Fault is returned with:
– Response code = DWR:8
Description = " Document Wrapper cannot be deleted because it doesn't exist "
When trying to delete a Document Wrapper, the Document Wrapper does not exist.
A SOAP Fault is returned with:
– Response code = DWR:9
– 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.
A SOAP fault is returned with:
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.
e-TrustEx Interface Control Document - Page 42Document Version 0.004 dated 13/07/20122
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
DocumentCanonicalizationMethod
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]
Endpoint Type HTTP SOAP Web Service WSDL reference: [REF30]
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:
e-TrustEx Interface Control Document - Page 43Document Version 0.004 dated 13/07/20122
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
DocumentCanonicalizationMethod
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
An HTTP Error with the code “503 – Service Unavailable”.
At the time of the service call, the system is down.
A SOAP fault is returned with:
– Description = “Server Error”
An unexpected error occurred during the processing of the message.
A SOAP fault is returned with:
– Response code = 301:4
– Description = “Hard business rule violated”
The message is not valid against the input schema.
A SOAP fault is returned with:
– Response code = 301:4
– Description = “Hard business rule violated”
At least one business rule of hard severity has been violated.
e-TrustEx Interface Control Document - Page 44Document Version 0.004 dated 13/07/20122
A SOAP fault is returned with:
– Response code = 301:5
– Description = “Parent document ID does not exist”
The parent document of the Application Response does not exist.
A SOAP fault is returned with:
– Response code = 301:6
– Description = “Parent document state is wrong”
The parent document of the Application Response is not in the correct state.
A SOAP fault is returned with:
– Response code = 301:3
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]
Endpoint Type HTTP SOAP Web Service WSDL reference: [REF9]
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].
The following table lists the potential errors returned during the processing of the message.
Table 24 Retrieve Interchange Agreement - errors
Error Cause
– An HTTP Error with the code “503 – Service Unavailable”.
At the time of the service call, the system is down.
e-TrustEx Interface Control Document - Page 47Document Version 0.004 dated 13/07/20122
A SOAP fault is returned with:
– Description = “Server Error”
An unexpected error occurred during the processing of the message
A SOAP fault is returned with:
– Response code = 1
– Description of the non conforming XML
The message is not valid against the input schema.
A SOAP fault is returned with:
– Response code = 21:4
– Description of the failed rule
At least one business rule of hard severity has been violated.
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]
Endpoint Type HTTP SOAP Web Service WSDL reference: [REF37]
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].
The following table lists the potential errors returned during the processing of the message.
Table 26 Status Request - errors
Error Cause
A SOAP fault is returned with:
Response code = 1
The message is not valid against the input schema.
A SOAP Fault is returned with:
– Response code = 21:4
– Description = " The Sender Party Endpoint ID and the Receiver Party Endpoint ID must be present in the message payload "
At least one business rule of hard severity has been violated.
A SOAP Fault is returned with:
– Response code = 21:4
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 "
At least one business rule of hard severity has been violated.
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]
e-TrustEx Interface Control Document - Page 49Document Version 0.004 dated 13/07/20122
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].
The following table lists the potential errors returned during the processing of the message.
Table 27 View Request - errors
Error Cause
An HTTP Error with the code “503 – Service Unavailable”.
At the time of the service call, the system is down.
A SOAP fault is returned with:
Response code = 1
The message is not valid against the input schema.
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.
e-TrustEx Interface Control Document - Page 50Document Version 0.004 dated 13/07/20122