4. TECHNICAL INFORMATION EXCHANGE SPECIFICATIONS
Emplacement : Documentation ICS2 > Interface Control Document
The ICS2 Trader Interface (TI) uses AS4 as a message exchange protocol as profiled in the eDelivery AS4 specifications (formerly known as e-SENS AS4). The following sections give an overview of the high-level messaging functionality of the eDelivery AS4 profile used by the ICS2 Trader Interface.
The first section introduces the protocol based on the eDelivery AS4 specifications. More information can be found in eDelivery AS4 specifications ([R01]), the OASIS ebXML Messaging Services specifications ([R07]) and AS4 Profile of ebMS 3.0 ([R07]). The second section details all elements of the user message, while the subsequent sections cover the signal message, routing and finally security aspects.
- Select the Message Exchange Pattern (section
https://mgi-team.atlassian.net/wiki/spaces/DOCI5/pages/3347120133/4.+TECHNICAL+INFORMATION+EXCHANGE+SPECIFICATIONS#Message-Exchange-Pattern ) Configure the Processing Mode (P-Mode) as defined by ICS2 (see sectionhttps://mgi-team.atlassian.net/wiki/spaces/DOCI5/pages/3347120133/4.+TECHNICAL+INFORMATION+EXCHANGE+SPECIFICATIONS#Processing-Mode and more details inhttps://mgi-team.atlassian.net/wiki/spaces/DOCI5/pages/3347841043/Annexes#Annex-2.-P-MODES-SUMMARY ) Follow the message specific configuration as defined by ICS2 (sectionshttps://mgi-team.atlassian.net/wiki/spaces/DOCI5/pages/3347120133/4.+TECHNICAL+INFORMATION+EXCHANGE+SPECIFICATIONS#USER-MESSAGE andhttps://mgi-team.atlassian.net/wiki/spaces/DOCI5/pages/3347120133/4.+TECHNICAL+INFORMATION+EXCHANGE+SPECIFICATIONS#SIGNAL-MESSAGE ) Configure the correct handling of the TLS certificates that cannot be expressed as a P- Mode parameter but is nevertheless an AS4 configuration element (see sectionhttps://mgi-team.atlassian.net/wiki/spaces/DOCI5/pages/3347120133/4.+TECHNICAL+INFORMATION+EXCHANGE+SPECIFICATIONS#SECURITY )
DELIVERY AS4 OVERVIEW
Compliance hierarchy
ICS2 uses the AS4 protocol which supports a standardized, secure, and reliable exchange of messages, containing one (or multiple) payload(s). The ICS2 interface as defined in this document is compliant to 3 specifications in a hierarchical structure:
Figure 10. Compliance hierarchy * The AS4 Profile of ebMS 3.0 ([R07]) is the baseline of the specifications. * The eDelivery AS4 Profile ([R01]) is more specific, choices made here have priority over the above. * The ICD (this document) adds extra requirements, choices made here have top priority over the above.
AS4 Profile
The following are the key features of the AS4 profile used by the Trader Interface:
- Interoperable: AS4 is defined as an OASIS standard. It is built on top of existing standards, which have proven interoperability in the past: MIME, SOAP and WS- Security;
- Secure: AS4 uses a subset of the WS-Security features including digital certificate sealing in order to assure message non-repudiation and data confidentiality;
- Reliable: AS4 guarantees once-and-only-once delivery, via the exchange of acknowledgments and additional requirements on both send and receive side;
- Payload agnostic: AS4 can exchange any kind of payloads and supports multiple payloads being sent in one AS4 message. In the case of TI message exchanges will be limited to one XML payload per message.
eDelivery AS4 Profile
The eDelivery AS4 Profile defines a mandatory Common Profile that selects, extends and profiles the AS4 ebHandler Conformance Profile and AS4 Additional Features and provides a common Usage Profile. The ICS2 Trader Interface further constrains these by following the eDelivery profile as described in the sections below. This profile can be implemented using open source or closed source AS4 software implementations that conform to eDelivery specifications [R08].
ICS2 features
On top of the AS4 ebHandler Conformance Profile, the eDelivery AS4 profile used as a baseline by ICS2 updates or adds some functionality:
- Algorithms specified for securing messages at the Message Layer are updated to current guidelines and use of electronic signature for sealing is mandatory;
- There is an added requirement to support Two Way Message Exchange Patterns (MEPs);
- Transport Layer Security, if handled in the AS4 handler, is profiled and is mandatory;
- The WS-Security version is the 1.1.1;
- Support for IPv4 and IPv6 is explicitly required.
It also adapts some requirements:
- The Pull mode is profiled in the eDelivery AS4 profile and ICS2 will support it;
- The single XML payload is exchanged in a separate MIME part, never in the SOAP body;
- Technical receipts and errors are reported synchronously only;
- Electronic sealing is using the WS-Security specification using the X.509 Token Profile, which allows certificates to be used to seal the payload to ensure the data origin and integrity. Throughout the remainder of the document the term sealing will be used as representing the AS4 signature mechanism defined in the AS4 documentation;
Message encryption is currently mandatory in the eDelivery AS4 profile. ICS2 will deviate from the eDelivery AS4 profile on this aspect and not apply AS4 encryption as it relies already on encryption at the transport level (TLS/SSL)9.
In the context of the Trader Interface of the ICS2 system, the eDelivery AS4 profile is further specified through the definition of Processing Mode (P-Mode) configuration values with the aim of clarifying and removing any ambiguity. Refer to
Messaging Model
The following key concepts and terminology from the ebMS 3 core specification ([R07]) are used to model message exchanges as shown in the figure below. The message flow is reversed when the exchange is initiated by Customs.
Figure 11: Message model * A Messaging Service Handler (MSH) is an entity that is able to generate or process messages that conform to the ebMS specification, and to act as a sender or receiver role. This can be any eDelivery conformant AS4 access point [R08] on the Economic Operator’s side; * A Producer is an entity (e.g. business application) that constructs the functional payload and interacts with a Sending MSH (i.e. an MSH in the Sending role) to initiate the sending of a user message; * A Consumer is an entity that interacts with a Receiving MSH (i.e. an MSH in the Receiving role) to consume the functional payload from a received user message.
The interaction between these components is defined in abstract operations, such as Submit, Send, Receive, Deliver and Notify. The communication between a Producer/Consumer and an MSH can be done in an implementation specific way, which is out of scope for the AS4 usage profile.
A Message is a logical unit which consists of User Messages or Signal Messages.
- The User Message contains the actual business payload that is exchanged amongst the business applications of two parties (an eb:Messaging/eb:UserMessageXML structure). From a business application perspective, only these categories of messages must be specified;
-
Signal Messages (an eb:Messaging/eb:SignalMessage XML structure) have a supporting role in establishing message exchange patterns, non-repudiation and reliability. They are restricted to the sending and receiving MSH. There are 3 types of Signal Messages:
- The Receipt is a positive acknowledgment. It indicates that the receiving MSH could parse the incoming message without an exception. This ensures the Received operation was successful;
- The Error is a negative acknowledgment. It indicates that the receiving MSH encountered an issue during the parsing of the incoming message;
- The Pull Request is in support of the pull message exchange pattern described below. While part of the AS4 specifications, the current version of the eDelivery AS4 profile does not use the Pull pattern.
Message Exchange Pattern
General Definition
An ebMS Message Exchange Pattern (MEP) defines a typical choreography of ebMS User Messages which are all related using the referencing feature (RefToMessageId). Each message of an MEP instance refers to a previous message of the same instance, unless it is the first one to occur. Messages are associated with a label (e.g. "request", "reply") that precisely identifies their direction between the parties involved and their role in the choreography.
The ICS2 system will only use One-Way MEPs which govern the exchange of a single User Message Unit unrelated to other User Messages. Its label is "oneway" and is identified by the URL http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/oneWay.
It should be noted that MEP definitions are primarily concerned with the transfer of ebMS User Message Units. Instances of such MEPs may involve or cause the transfer of additional messages (e.g. ebMS signal messages or units such as errors, receipts) but these are not taken into account in the MEP definition.
A message exchange pattern binds with the underlying transport channel to transfer messages, and this dictates how each message transfer is initiated over the underlying protocol.
One-Way/Push MEP
This transport-channel-bound MEP involves the transfer of a single ebMS User Message unit (label: "oneway"). When performed over a Two-way underlying transport protocol (HTTP request/response), the response message MAY carry an ebMS Signal Message, such as an error message. However, the response message MUST NOT carry an ebMS User Message that refers to the request message.
Figure 12: One-way/Push MEP This Push binding supported by the eDelivery AS4 profile, which maps an MEP User message to the 1st leg of an underlying 2-way transport protocol or of a 1-way protocol. This binding is identified by the URI: http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/push.
One-way/Pull MEP
This transport-channel-bound MEP involves the transfer of a single ebMS User Message unit (label: "oneway"). This MEP is initiated by the Receiving MSH, over a two-way underlying transport protocol. The first leg of the protocol exchange carries a Pull Signal message. The second leg returns the pulled User Message unit. The pulled User Message unit does not include an eb:RefToMessageId element. This MEP is identified by the URI: http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/pull.
Figure 13: One-way/Pull MEP Message Partition Channels (MPC) allow for partitioning the flow of messages from the sender MHS (DG TAXUD) to the receiving MSH (the trader system). The sending DG TAXUD MSH MUST be able to determine whether a submitted message should be pulled or pushed, and to which Message Partition Channel (MPC) it must be assigned. Similarly, the Receiving Trader MSH is aware of which MPC(s) should be pulled from, and which ones will be used for push. This knowledge is based on an agreement shared between parties prior to the exchanges, and modelled in this specification as the P-Mode operation set (see
The processing model for a pulled message is as follows, for a typical and successful instance of One-Way/Pull MEP:
- The TI submits message data to the DG TAXUD MSH, intended for the trader system. The message is associated with an MPC. If no MPC name is provided by the submitter, or if the MSH implementation has not been provided with a way to determine this association by itself, the default MPC is used. The MEP associated with this message is a One-Way/Pull;
- On the trader system MSH side: Sending of a PullRequest signal by the MSH. The PullRequest signal specifies the MPC from which to pull messages;
- On the DG TAXUD responding MSH side: Reception of the PullRequest signal. For every PullRequest signal received it selects a previously submitted message according to a FIFO policy with respect to the Submit operation. If there is no user message available in the specified MPC for sending, a warning signal with short description: "EmptyMessagePartitionChannel" (see
https://mgi-team.atlassian.net/wiki/spaces/DOCI5/pages/3347841043/Annexes#Annex-4.-EBMS-ERRORS ) will be sent back instead. The selected message is sent over the SOAP Response to the PullRequest; - On the trader system MSH side: the pulled message is available for processing by the MSH. The header @mpc attribute indicates from which MPC it has been pulled and is the same as the value of @mpc in the corresponding PullRequest signal.
ICS2 Scenarios
The Trader Interface allows using both types of MEPs. The One-Way/Push Message Exchange Pattern is used when the responding MSH is a permanently connected AS4 access point. The One-Way/Pull Message Exchange Pattern is used to allow intermittently connected Trader Access Points to have full control to initiate asynchronous transfers with the Trader Interface in both directions, engaging in a client-server type of interaction.
- A Trader Sender Party has to declare its choice as a configuration asset to the TI with regards to the mode of operation for the eu_ics2_ct2 service. It is configured One Way/Push or One- Way/Pull.
Processing Mode
A Processing Mode (P-Mode) is the contextual information that governs the processing of a particular message (this is basically a set of configuration parameters). The P-Mode associated with a message determines, among other things, which security and/or which reliability protocol and parameters, as well as which MEP is being used when sending a message. The technical representation of the P-Mode configuration is implementation-dependent.
The MSH implementing the Harmonised Trader Interface will be REQUIRED to use the P-Mode parameters defined in the current document (see
- A Trader Sender Party has to follow the P-Mode parameters as defined in Annex 2.
Message Packaging
AS4 uses SOAP with Attachments as a message format. This is a MIME payload (multi-part), which contains a SOAP envelope as the first MIME part. This SOAP envelope holds the User Message, Receipt or Error. In the case of ICS2 User Messages, the single business payload is in a SOAP Attachment (read MIME part), The SOAP body is always empty. Gzip compression of the payloads in the SOAP Attachments will be used as supported by AS4.
A User Message consists of:
- MessageInfo contains the unique MessageId and the timestamp of the message;
- PartyInfo identifies the sender and receiver of the message;
- CollaborationInfo describes the business context through a service and action parameter;
- MessageProperties offer an extension point to add additional business information;
- PayloadInfo makes a reference to the payloads in the Attachments. A Signal Message consists of:
- MessageInfo contains the unique MessageId, the MessageId of the referenced User
Message and the timestamp of the message.
For a more detailed description of the message packaging and content for User Message and Signal Message refer to sections 4.2 and 4.3 respectively.
USER MESSAGE
The AS4 message structure provides a standard message header that addresses B2B requirements and offers a flexible packaging mechanism based on SOAP and MIME enveloping. The more specific eDelivery AS4 structure is illustrated below. Dashed lines style is used for optional message components.
Figure 14: Detailed eb:UserMessage structure This section identifies the different data elements present in the AS4 message header for which the business application will have to provide specific values for each individual message exchange.
In addition to these elements the AS4 message header contains other technical elements which are not to be provided by the business application but are derived from the P-Mode configuration or indirectly derived from other data elements specified (e.g. certificate of a party).
Eb:Messaging/eb:UserMessage/eb:MessageInfo
The eb:MessageInfo element has the following children:
- eb:Timestamp (REQUIRED) – A value representing the date at which the message header was created, and is conforming to a dateTime. It MUST be expressed as UTC. Indicating UTC in the Timestamp element by including the 'Z' identifier is optional;
- For all elements that contain timestamps, the values should be expressed in UTC format. This expression is the GMT zone followed by letter “Z”. No local time zones or central European time should be used in that expression. An alternative way could be to use the local time followed by an offset (which points out the difference of that local time from the GMT).
- eb:MessageId (REQUIRED) – A value representing – for each message - a globally unique identifier conforming to the message identifier (msg-id) specification defined in section 3.6.4 of RFC 2822 [R10]. To ensure the global uniqueness of message identifiers, the value of eb:MessageId must be structured using a UUID on the left side and the fully qualified domain name of the sender’s access point on the right side. The sender must ensure the UUID is unique across its access point domain;
- eb:RefToMessageId (optional) – when present, it must contain the eb:MessageId value of the message to which this message relates. The ICS2 message exchanges will make use of this field when a functional reply message can be traced back to a specific original AS4 message that triggered the reply. This feature is especially useful in the context of error handling, as described in section
https://mgi-team.atlassian.net/wiki/spaces/DOCI5/pages/3347120133/4.+TECHNICAL+INFORMATION+EXCHANGE+SPECIFICATIONS#ERROR-HANDLING .
eb:Messaging/eb:UserMessage/eb:PartyInfo
The eb:PartyInfo provides the identification of the Sender and the Receiver of the message in two mandatory child elements eb:From and eb:To. For each of the parties (From and To) two mandatory child elements have to be provided. The first one is the eb:PartyId and allows for the actual identification of the party. The second one is the eb:Role element and defines the role the party has in the message exchange.
Note that the Sender and Receiver identified in the eb:PartyInfo refers to the party sending and receiving the AS4 message. These could be different from the actual Person filing when an intermediate IT service provider is involved in the message exchange with Customs. This aspect is further described in section
eb:PartyId
The content of this element is a string value that provides an identification for the given party.
Namespaces
The namespace for content values of this element is specified by the eb:PartyId@type attribute. The ICS2 TI uses two complementary namespaces
- one that allows the identification of an economic operator
- a second one allows the identification of a Customs STI/NTI.
The defined namespaces follow the convention for naming identifiers domains as defined in the e-SENS ebCore Party Id 1.3 specification ([R11]), and use 'unregistered' namespace domains.
This implies that the domain namespaces will have a structure as follows:
- urn:oasis:names:tc:ebcore:partyid-type:unregistered:eu-customs:auth
- urn:oasis:names:tc:ebcore:partyid-type:unregistered:eu-customs:EORI Authority namespace
In the authority namespace the partyId of the ICS2 STI is sti-taxud.
Nevertheless, there is a possibility that a member state will create their own NTI. In the case of a MS setting up an NTI (which is not the case yet), the partyId of an NTI will be nti-
EO namespace
In the EORI namespace the partyId is typically the EORI number.
- In case that an EO implements its own access point, then the EO holds both Sender and Declarant roles and should use its unique EORI number, in order to register its certificate and also use it in the functional payload (ENS filing); In case that an EO uses ITSP services, then the IT Service Provider holds the Sender role and should register a certificate with its own EORI number. However, the EO still holds the Declarant role and should use its own EORI number for the ENS filing.
Nevertheless, a more complex structure is possible to allow a given party (mandatory having an EORI number) to have multiple partyId's defined, if this would be needed. This allows for the party to have/use multiple AS4 message handlers (MSH) depending on the business domain or geographical region.
The structure of the partyId is
xml
where the first and third part are optionally to be used. So possible alternations are:
xml
The following table explains the elements of this partyID
- EORI — Description : The EORI to be used is that of the System Owner responsible of implementing and operating the Access Point. An EORI or Economic Operators Registration and Identification number is an identification number that is unique in the European customs union, and can be received by registering at the following URL: https://ec.europa.eu/taxation_customs/business/customs- procedures-import-and-export/customs-procedures/economic- operators-registration_en
- System identifier (optional) — Description : The system identifier part is an alphanumerical string with a maximum length of 12 characters and is free to choose by the given party as long as uniqueness is ensured within the given party. Such system identifier is only needed in case the Sender wants to operate multiple logical distinct AS4 access points.
- MS (optional) — Description : The optional member State is an iso 3166-1 Alpha2 code indicating the Member State where the Certificate used in the message is registered in UUM&DS. This is only required in the rare cases where the certificate is registered in UUM&DS in another Member State as where the EORI number is registered.
Example values are:
- NL0987654321 for a single system
- system1@NL0987654321 and system2@NL0987654321 for a trader using multiple systems
- system3@NL0987654321@FR for a Dutch trader using a certificate registered in France
It should be noted that the initiator of message exchange (i.e. the Sender) must have a mapping at its disposal between the Receiver (To) PartyId and the physical address of the message handler to be addressed to reach this party to be able to initiate the exchange. Refer to section
eb:Role
The Trader Interface defines two generic roles 'Trader' and 'Customs'.
eb:Messaging/eb:UserMessage/eb:CollaborationInfo
The eb:CollaborationInfo element contains the following child data elements:
- eb:AgreementRef (REQUIRED) – is a string that identifies the entity or artefact governing the exchange of messages between the parties;
- eb:Service (REQUIRED) – is a string identifying the service that acts on the message;
- eb:Action (REQUIRED) – is a string identifying an operation or an activity within a service that may support several of these;
- eb:ConversationId (REQUIRED) – is a string that allows for an identification of multiple messages exchanged in a conversation between Parties.
xml
In the next subsection we describe the values of these elements for ICS2.
eb:AgreementRef
The eb:AgreementRef element is mandatory in ICS2 TI exchanges and serves the additional purpose of identifying a version of the Trader Interface common specifications. The current version for ICS2 Release 2 and Release 3 is EU-ICS2-TI-V2.0. Section
As per ebMS 3 specification ([R07]), the eb: AgreementRef element will be qualified by a @type attribute with a value of “ics2-interface-version”, to allow such values in the content of the data element.
As a result of ICS2 change management updates to the specifications can occur that have an impact on the HTI specifications. Whenever required, an updated value for the eb:AgreementRef element will be associated to this new version of the specifications. For a pre-defined transitional period, defined on a case-by-case basis at the moment of change, a TI shall potentially be required to support two concurrent versions.
eb:Service
As described in section
- eu_ics2_t2c – identifies the flow from trader to customs (i.e. from trader to TI);
- eu_ics2_c2t – identifies the flow from customs to trader ((i.e. from TI to trader).
As per ebMS 3 specification, the eb:Service element will be qualified by a @type attribute with a value of eu-customs-service-type, to allow such values in the content of the data element.
eb:Action
The ICS2 TI will use as action name the Message ID of the information exchange as defined in the common functional specification.
eb:ConversationId
The Trader Interface exchanges do not make use of the eb:ConversationId in the context of ICS2 but according to standards , if none is provided, an MSH is expected to set the value “1”. For the trader interface, any value present in an incoming message will be ignored.
eb:Messaging/eb:UserMessage/eb:MessageProperties
This element has zero or more eb:Property child elements.
An eb:Property element is of xs:anySimpleType (e.g. string, URI) and has a required @name attribute and an optional @type. This allows expressing business context specific properties in the AS4 header allowing more efficient monitoring, correlating, dispatching and validating functions without requiring payload access.
The eDelivery AS4 profile used by ICS2 does not require the usage of message properties and this element will not appear in eb:UserMessage.
eb:Messaging/eb:UserMessage/eb:PayloadInfo
The eb:PayloadInfo element illustrated below identifies payload data associated with the message. Its purpose is:
- to make it easier to extract payload parts associated with this ebMS Message;
- to allow an application to determine whether it can process these payload parts, without having to parse them.
Figure 15: Payload info In ICS2 messages the eb:PayloadInfo element will contain a single eb:PartInfo referencing the single business payload included as a MIME attachment, and optionally a number of eb:PartInfo referencing the binary attachments (if there are binary attachments allowed in the business payload, please see section
- The ICS2 business payload and attachments must be sent using the MIME multipart format. The example in Figure 15 shows how this must be done. The PayloadInfo element attribute href refers to the MIME part Content-ID (orange arrow on the figure).
This eb:PartInfo has an @href attribute whose value is the [RFC2392] Content-ID URI of the payload object referenced. It also has one eb:PartProperties child element that contains zero or more eb:Property elements.
As per eDelivery AS4 specification the following applies to eb:PayloadInfo:
- Compliant eDelivery AS4 message always has an empty SOAP Body meaning that message payload must be exchanged in a separate payload Mime Part. This implies that the eb:PayloadInfo is mandatory;
- The ebMS3 mechanism of supporting "external" payloads via hyperlink references (as mentioned in section 5.2.2.12 of the ebMS3 Core Specification [R07]) must not be used;
Payload parts must be compressed using gzip. Refer to [R07] for the handling of already compressed payloads.
Packaging requirements in the context of ICS2 for the single business payload eb:PayloadInfo:
- An eb:PartInfo/eb:PartProperties/eb:Property/@name="MimeType" value is required to identify the MIME type of the payload before compression was applied. Only “application/xml” is allowed;
- An eb:PartInfo/eb:PartProperties/eb:Property/@name="CharacterSet" value is recommended to identify the character set of the payload before compression was applied. Only “utf-8” is allowed. Even if the value is not set, the character set of the payload before compression must be UTF-8;
- An eb:PartInfo/eb:PartProperties/eb:Property/@name="CompressionType" with the value “application/gzip” is required;
- It must be possible for the producer to set the value of the @href attribute and this value must be passed on to the final consumer. It might be that in the context of ICS2 this can be generated by the sending MSH as it does not have a business meaning.
Packaging requirements in the context of ICS2 for the optional attachment eb:PayloadInfo elements:
- An eb:PartInfo/eb:PartProperties/eb:Property/@name="MimeType" value is required to identify the MIME type of the payload before compression was applied. It cannot be of MIME type application/xml. The allowed MIME types for attachments are application/pdf, image/jpeg;
- An eb:PartInfo/eb:PartProperties/eb:Property/@name="CompressionType" with the value “application/gzip” is required;
- An eb:PartInfo/eb:PartProperties/eb:Property/@name="CompressionType" with value “application/gzip” is required;
- The @href attribute value of the attachment must be the same the as […]/BinaryFile/identification XML element in the business payload.
Message Payload
The eDelivery AS4 communication used by the ICS2 Trader Interface is used to support the ENS filing related processes. The actual payload of each user message is one of the messages listed in the table in
The specifics of how a message producer (i.e. trader’s business application) submits a business payload to the sending MSH depends on the interface(s) provided by the eDelivery AS4 conformant solution used and are out of the scope of this document.
However, the following requirements apply to ICS2 business message payloads:
- Each user message has one and only one business message payload, and optionally a number of binary attachment payloads or extra related business message payloads (notifications in the context of
https://mgi-team.atlassian.net/wiki/spaces/DOCI5/pages/3307536393/3.+Functional+information+exchange+specifications#Consult-ENS-(IE3Q05) ); - Each user message originates from a single Person filing;
- The business message is sent as payload MIME part and not in the soap body;
- The business message must be a schema valid xml message as per Technical Service Specifications [R06] and matching the AS4 service/action as per
https://mgi-team.atlassian.net/wiki/spaces/DOCI5/pages/3347841043/Annexes#Annex-1.-SERVICE-OPERATIONS and sectionhttps://mgi-team.atlassian.net/wiki/spaces/DOCI5/pages/3347120133/4.+TECHNICAL+INFORMATION+EXCHANGE+SPECIFICATIONS#eb%3AMessaging%2Feb%3AUserMessage%2Feb%3ACollaborationInfo ; - The business message maximal size recommended is 100MB uncompressed. The following requirements apply to ICS2 attachment payloads:
Due to limitations in other parts of the ICS2 system, the message maximal size recommended in the system is 20MB compressed, this is the sum of the compressed base64 encoded binary attachments and the compressed business message payload. To this end, large images and PDF documents will be resized in the TI or NES before dispatching to the Common Repository.
SIGNAL MESSAGE
The ebMS Signal Message Unit is represented by the XML infoset eb:Messaging/eb:SignalMessage. Its role is to activate a specific function in the Receiving MSH. It is not intended to be delivered to a message Consumer.
It has two child elements:
-
eb:Messaging/eb:SignalMessage/eb:MessageInfo
- This REQUIRED element is similar to eb:MessageInfo as defined for user messages (see section
https://mgi-team.atlassian.net/wiki/spaces/DOCI5/pages/3347120133/4.+TECHNICAL+INFORMATION+EXCHANGE+SPECIFICATIONS#Eb%3AMessaging%2Feb%3AUserMessage%2Feb%3AMessageInfo );
- This REQUIRED element is similar to eb:MessageInfo as defined for user messages (see section
-
eb:Messaging/eb:SignalMessage/eb:[SignalName]
- This REQUIRED element defines the nature of the ebMS signal. There is only one eb:[SignalName] child element when [SignalName]=Receipt. There may be several children elements when [SignalName]=Error.
An ebMS signal does not require any SOAP Body: if the SOAP Body is not empty, it MUST be ignored by the MSH, as far as the interpretation of the signal is concerned.
A signal message has the following structure.
Figure 16: Signal message
eb:Messaging/eb:SignalMessage/eb:Receipt
A receipt signal message is the acknowledgment that the receiving MSH successfully processed the AS4 message, i.e. it was able to apply the expected P-Mode and is able to deliver the message to the consumer. The value of eb:MessageInfo/eb:RefToMessageId MUST refer to the message for which this signal is a receipt.
eb:Messaging/eb:SignalMessage/eb:Error
Error generation and error reporting are orthogonal concepts in ebMS V3. While the generation of errors is a matter of conformance, the reporting of errors may be subject to an agreement. Consequently, the way errors are to be reported is specified in the P-Mode (P- Mode.ErrorHandling feature) that results from such an agreement. The eDelivery profile specifies that errors must be reported and transmitted synchronously (using the HTTP Response) to the Sender and should be reported (Notify operation in the messaging model) to the Consumer and Producer.
An ebMS Error is represented by an eb:Error XML infoset, regardless of the way it is reported. The ICS2 TI makes use of the following properties:
- origin (optional attribute);
- category (optional attribute);
- errorCode (required attribute);
- severity (required attribute);
- refToMessageInError (required if error(s) related to a particular ebMS message);
- shortDescription (optional attribute);
- Description (optional element);
- ErrorDetail (optional element).
In
It is important to note that only technical errors related to the communication over AS4 are sent in this way. Business validation failures are sent back to the sender using the already mentioned information exchange message IE3N01 and IE3N99 using a user message, in the context of One- Way/Push or Two-Way/Push-and-Push Message Exchange Pattern.
eb:Messaging/eb:SignalMessage/eb:PullRequest
When the trader system is using the One-Way/Pull MEP, the messages will be delivered after sending of a PullRequest signal by its MSH, as explained in section
- @mpc=urn:fdc:ec.europa.eu:2019:eu_ics2_c2t/EORI/
where partyId is defined as in section https://mgi-team.atlassian.net/wiki/spaces/DOCI5/pages/3347120133/4.+TECHNICAL+INFORMATION+EXCHANGE+SPECIFICATIONS#eb%3APartyId .
MESSAGE ROUTING
The eDelivery AS4 specification covers message exchanges with the abstract concepts of sending and receiving MSH where each actor in the exchange can take the receiving and sending roles alternatively.
To be able to address the correct MSH when sending an ICS2 message to an EO, the Trader Interface needs a way to match functional information to the P-Mode configuration and URI of the corresponding access point.
Destination resolution
The eDelivery access point of an EO needs to be configured to address predetermined and established Trader Interface access points (Shared TI, National TI) while a Trader Interface acts as a central node and must be able to send messages to many parties. To be able to participate in
ICS2 exchanges an Economic Operator’s Access point must enroll and pass conformance testing as described in section
Section
For ENS Filings or Arrival Notifications received by a TI the functional reply will be sent to the AS4 access point from which the initial filing was sent. Other functional messages, referring to a previously assigned MRN, will be sent to the access point of the person filing who sent the message that this MRN was assigned to.
This means the Trader Interface must keep track of the eb:From/eb:PartyId in the AS4 header information in relation to the unique functional identifier of the message (LRN or MRN) in the functional message payload (see FunctionalReferenceID in section
In some notification scenarios, the Trader Interface needs to notify an EO other than the Person filing in which case the access point and PartyId to be used are different ones. In this case the TI access point will use the preferences provided by the target EO at enrolment time (see section
IT Service Provider
There may be cases where a Person filing is using an IT service provider that constructs the technical compliant message and subsequently delivers this message to a Customs authority by addressing the appropriate STI/NTI.
Exactly as in the case of an EO, to be able to send ICS2 messages, an IT Service Provider must enroll the Access Point with customs authorities and provide the configuration of the access point in the same way as described above (and in chapter
ERROR HANDLING
Errors handling depends on the type of error encountered when connecting to the ICS2 system. Typically, the errors can be categorised as Connectivity issues, Technical Exceptions, Validation errors and Lifecycle validation errors.
Connectivity issues
Before anything else, connectivity with the ICS2 system must be ensured. For this purpose, the EBMS3 protocol defines a server test feature that allows a party to "Ping" a communication partner. The feature is based on messages with the values of:
- eb:UserMessage/eb:CollaborationInfo/eb:Service set to http://docs.oasis- open.org/ebxml-msg/ebms/v3.0/ns/core/200704/service
- eb:UserMessage/eb:CollaborationInfo/eb:Action set to http://docs.oasis- open.org/ebxml-msg/ebms/v3.0/ns/core/200704/test
This feature allows communication partners to perform a basic test of the communication configuration (including security at network, transport and message layer, and reliability) in any environment, including the production environment. The selected conformant AS4 implementation of the trader must implement this feature, allowing the trader to test the connectivity with the conformance or production version of ICS2.
Technical errors
Technical errors that occur during the AS4 protocol (incorrect AS4 headers, etc.) are handled using the appropriate AS4 mechanism and the error signal message. The mechanism of signal messages is explained in section
Validation errors
Nevertheless, as the ICS2 interactions with traders are asynchronous, validation of an incoming message can result in functional errors being detected after the reception. In that case a functional error message is asynchronously sent to the sender. This message is defined as IE3N99 for a general validation error.
The message structure of the IE3N99 is defined as pictured below. The IE3N01 has a similar structure.
Figure 17: IE3N99 message structure The following list explains this message:
FunctionalReferenceID is used to correlate the error message to the original message on a business (or functional) level. As the error messages are asynchronous, it is important that the EO system can correlate the error to the original message. The functional reference of the original message will be used here, as follows:
- IE3Fxx — Message description : ENS Filing ; Reference element : LRN
- IE3Axx — Message description : ENS Filing Amendment ; Reference element : MRN
- IE3Q04 — Message description : Invalidation Request ; Reference element : MRN
- IE3Q05 — Message description : ENS Consultation ; Reference element : MRN
- IE3N06 — Message description : Arrival Notification ; Reference element : LRN
- IE3R02 — Message description : Additional Information Response ; Reference element : MRN
- IE3R03 — Message description : High Risk Cargo & Mail screening response ; Reference element : MRN
Nevertheless the AS4 message header element will also contain a technical correlation id referring to the AS4 messageId of the original message. This is useful in the case the original message was unparsable or the functional reference id is not unique (for example in case of consultations);
- NotificationDate: is the timestamp of the validation of the message;
- Representative: the legal representative as indicated in the original message will be used if available;
- TransportDocument: the document number of the original message will be used if available;
- Declarant: the declarant as identified in the original message will be used if available;
- CustomsOfficeOfFirstEntry: the location as identified the original message will be used if available;
-
Error: The cardinality of the errors is 1 up to 999. If the message is syntactically correct, the error message will list all possible semantical errors found in a message, and not stop at the first error;
- The technical error message gives more info about the error if relevant. In the case of syntactical errors, the more detailed parser exception (such as “missing element Identification Number”) will be found in the description. This description is not translated, only English will be used;
- The description gives a human readable description of the error in English only;
- The ValidationCode is defined by a code list defined in ICS2 Information Exchange Message Specifications [R04] containing the code and the description;
- The pointer of the error contains the location of the error defined by an XPath location in the XML document.
The above message will be sent over AS4 following that protocol. To allow the sender to correlate the error message to the original message, the AS4 correlation mechanism is used. That means that the eb:RefToMessageId is used and will always contain in this case the AS4 message id of the original message.
Lifecycle validation errors
Similar to the above, an IE3N01 is sent to the trader system in case of a lifecycle validation error. The message structure of the IE3N01 has a similar structure as above.
SECURITY
The security requirements of the ICS2 Trader Interface include confidentiality, integrity, authentication and authorisation. These are catered for at different levels of the communication layers (network, transport or message layer).
Confidentiality is ensured by applying transport level encryption. Message level encryption is considered redundant11, deviating from the eDelivery specifications on this.
To ensure integrity and authentication, the TI makes use of the mechanisms and standards specified in the eDelivery AS4 profile applicable to the message layer. These rely on the use of electronic certificates to seal the messages and from which it can be guaranteed that the message was not modified during its transport and provides proof of the identity of the person delivering the message.
The above security measures cover the so-called non-repudiation capability which is a major benefit of the use of AS4 protocol. This means that both sender and receiver have the full guarantee and proof of message being delivered by an identified party with integrity and in full confidentiality.
To ensure only registered and authorised parties can deliver and receive messages to and from the TIs, the TI uses a registration and authorisation mechanism based on UUM&DS. This happens at the functional level. These are represented in figure 16 and further described below.
Figure 18: TLS vs Message security An additional measure was assessed in order to provide via the UUM&DS system the opportunity for the EOs to give explicit permission to one or more IT Service Providers to deliver and receive ICS2 related messages on their behalf12. The extent of this measure was analysed and considered too burdensome both to trade and to the MS forcing the EOs into an additional registration procedure and the MS to establish the administrative procedure for this objective.
Having the party exchanging the ENS messages explicitly identified, registered and authorised ensures that any responsibility for misuse of the system can be clearly located and traced; also the introduction of the cited measure does not add to the prevention of the potential misuse of the system. For this reason this measure is currently not planned to be implemented13.
The following table summarises the modes of implementation, prerequisites and types of certificates required for the different Communication Requirements:
- Communication — Layer : Network ; Protocol Specifications : TCP/IP ; Implementation : Open Internet ; Certificate CA : N/A
- Encryption — Layer : Transport ; Protocol Specifications : 2 Way TLS (SSL) ; Implementation : Network Infrastructure ; Certificate CA : Trusted CA
- Message Integrity (seal) — Layer : Message ; Protocol Specifications : AS4 ; Implementation : Trader interface AS4 Access Point
- Identification (seal)
- Authorisation (register) — Layer : Functional ; Protocol Specifications : UUM&DS ; Implementation : N/A
- Each Sender should obtain: A TLS (Transport Layer Security) certificate from a trusted Certificate Authority to be used at the transport layer (https) for identifying itself following the 2-way TLS security mechanisms. A Trusted CA in the TLS context can be a commercial CA trusted by DG TAXUD. The CA used need to be notified to DG TAXUD, but the certificate does not require registration. A digital certificate to be used for sealing at message layer, which should be registered in the National UUM&DS Application or in the Central UUM&DS Application. In case that an EO is not a Sender, and uses the services of an ITSP, then this EO does not need to register these certificate since it will be done by its ITSP.
Transport Layer Security
Within the ICS2 project the usage of 2-Way Transport Layer Security (TLS) is mandatory to provide message confidentiality and authentication. The 2-way TLS covers on the one hand the Server authentication: using a server certificate, allows the client to make sure the HTTPS connection is set up with the right server; and on the other hand the Client Authentication: using a client certificate, allows the server to make sure the HTTPS connection is set up with a non- anonymous client.
The TLS should be implemented according to recent security standards. If TLS is not handled by the AS4 message handler itself, but by another component (such as a firewall, proxy server or router), these requirements are to be addressed by that component.
The eDelivery AS4 specifications ([R01] section 3.8.1. Transport Layer Security) define the following minimal requirements:
- Products compliant with this profile must support TLS 1.2 [RFC5246];
- It must be possible to configure accepted TLS cipher suites in the AS4 message handler. Products must support cipher suites included in the subset considered future-proof (see [R13], section 5.1.2). Vendors must add support for newer, safer cipher suites, as and when such suites are published by IANA/IETF;
- Support for SSL 3.0 and for cipher suites that are not currently considered secure should be disabled by default;
- Perfect Forward Secrecy, which is required in [BSITLS], is supported by the TLS_ECDHE_* and TLS_DHE_* cipher suites, which are therefore preferred and should be supported.
Transport Layer client authentication authenticates the Sender (when used with the Push MEP binding) and the Receiver (when used with Pull). Since this profile uses WS-Security for message authentication, the use of client authentication at the Transport Layer can be considered redundant. However, the Trader Interface will use 2-Way TLS Authentication as it blocks anonymous access to the system already at the transport layer.
For this purpose, a certificate will be required to be provided by a Certificate Authority included in a list of trusted CAs14 that will include any CA accepted by the Customs Authority of the Member States as recognised for this purpose. If the certificate is valid according to a trusted CA access is granted at transport layer.
Message Layer Security
The ICS2 Trader Interface relies on the message layer security features provided by the eDelivery AS4 specifications. In particular it uses the X.509 Certificate Token Profile to support the sealing of all AS4 messages. As illustrated in Figure 18 above, the private key of the sending MSH certificate is used to seal the message. The receiving MSH uses the public key of the sender’s certificate to verify the origin (identity) and integrity of the message.
For AS4 message implementation, a certificate will be required to be provided by a Certificate Authority included in a list of trusted CAs that will include any CA accepted by the Customs Authority of the Member States as recognised for this purpose.
Only certificates delivered by a CA approved by a Member State or included in the Europa List of Trusted Lists15 will be accepted. The UUM&DS system will facilitate the identification of MS approved CAs and verification of a given certificate being delivered by an approved Certificate Authority.
- The digital certificate for message sealing must be issued by a CA that is on the official EU wide LOTL (https://webgate.ec.europa.eu/tl-browser/#/) or on the National Customs alternate list of the Member State to whom National UUM&DS would like to register this certificate. The Certificate Authorities (CAs) on the LOTL can be divided into two categories: CAs that issue qualified certificates: LOTL link CAs on the LOTL that issue non-qualified certificate for e-signature/sealing: LOTL link Both categories (qualified and non-qualified certificates) of the LOTL can be registered for ICS2 message sealing. Alternatively, an EO can use a certificate issued by other CAs as long as the CA is present on the “National Customs Alternate List”. The National Customs Authority of registration should be consulted before acquiring a certificate of a CA not present in the LOTL; the NA will decide if the CA can be added to its alternate list.
This sealing is based on the W3C XML Signature recommendation and must use the precise configuration parameters defined by eDelivery AS4 for the usage of these standards (specific digest and signature algorithms) based on identifiers defined in this recommendation (see P-Mode parameters
To avoid the additional burden to Economic Operators of double registering MSH certificates also in the DG TAXUD environment, the Dynamic Receiver profile enhancement will be used as detailed in section 4.3 of the eDelivery AS4 profile [R01]. This means that AS4 messages sent by traders will have to contain the certificate chain used to seal the messages in a BinarySecurityToken element16. For interoperability and efficiency the full certificate path must be included with the signature, rather than just the leaf certificate. This means that the Sending MSH MUST use the X509PKIPathv1 Token Type option. In this option the wsse:BinarySecurityToken includes an ordered list of X.509 certificates packaged in a PKIPath. Use of this token type MUST be indicated as indicated in the following table:
- Trader AS4 message — Element : wsse:BinarySecurityToken ; Attribute : ValueType ; Value : http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509PKIPathv1
- Trader AS4 security policy file — Element : sp:X509Token ; Attribute : sp:IncludeTo ken ; Value : http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient
The X509v3 Token Type and PKCS7 Token Type SHOULD NOT be used. A BinarySecurityToken token reference MUST be used to reference the signing token.
- In the messages sent to TAPAS, most EOs/ITSPs erroneously include the leaf certificate instead of the full certificate chain. The receipt messages sent from an EO to TAPAS, it is observed to be wrongly signed (the empty SOAP body is not part of the signature). The receipt message occurs when an EO receives a user message from TAPAS. Then, the EO responds back with a receipt message indicating that it has successfully received the user message from TAPAS. The SOAP Body of this receipt message should be signed, otherwise TAPAS fails to validate the receipt messages received back and finally considers that the initial user message was never sent to EO.
Refer to
Authorisation security controls
To ensure that the Sender access point delivering AS4 messages containing ENS filings has the authorisation to do so, the ICS2 trader Interface requires the registration and validation of the Sender delivering messages to the TI. This is to be implemented via an authorisation mechanism that relies on the UUM&DS system.
The Sender parties to be authorised for exchanging messages with the TI need to register their identification number (EORI) and the certificate that will be used for sealing the AS4 messages.
The parameters taken into account for these security controls are:
- The eb:From/eb:PartyId of the sender of the AS4 message;
- The certificate used for sealing the AS4 message (sealing certificate of the sending access point, matching parameter PMode[1].Security.X509.Signature.Certificate);
- The list of parties as registered in UUM&DS (incl. EORI and associated certificates) for exchanging messages with the TI in ICS2 (there may be more than one certificate for one economic operator).
The trader interface (TI) access point will implement validation of the certificate used for message sealing by the sender against information available through UUM&DS:
- Sender’s certificate is checked for validity against accepted Certificate Authorities;
- Sender’s PartyId is checked via UUM&DS to verify it has the authorisation to send messages to ICS2. To do so, the association between the sender’s PartyId (EORI) and the certificate used for sealing will be validated versus the registered ones by the Customs Authorities.
The particulars of enrolling for the exchange of messages with ICS2 and registering the EORI and the certificates required for sealing and for TLS are detailed in the operational section below.
It must be noted that the certificate to be used for sealing the messages is that of the Sender. This is the legal person responsible for operating the Access Point. In many cases this is the Person filing itself; however in case of use of ITSP services it is the certificate of the IT Service Provider that is used. This implies also the fact that authorisation mechanisms explained above apply to the ITSP also.
Notes
- 9 In the context of the STI Project Group it was concluded that double encryption was an unnecessary and redundant measure adding a burden to the performance of the system and that it would be enough to rely on encryption at Transport level only. An additional operational complexity would also arise due to the fact that it requires the management of the certificates used for encryption at the receiving access point.
- 10 When the value of this element is http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/test, then the eb:Service element MUST have the value http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/service. Such a value for the eb:Action element only indicates that the user message is sent for testing purposes and does not require any specific handling by the MSH.
- 11 In the context of the STI Project Group it was concluded that double encryption was an unnecessary and redundant measure adding a burden to the performance of the system and that it would be enough to rely on encryption at Transport level only.
- 12 In the context of the STI Project Group (STIPG) it was observed that this measure is implemented in the current ICS systems by a minority of the STIPG participating MS; and some of those currently implementing it agree on not including it for ICS2. The remaining MS however expressed concerns on the lack of direct technical authorisation to the system by the Person filing.
- 13 Nevertheless the measure is technically feasible and could be introduced if there is common agreement by the MS on this necessity. The main impact to the system would be the addition of a field in our use of the AS4 protocol (OriginalSender) and the implementation of extra functionalities and interfaces in UUM&DS; these on top of potential administrative procedures to be stablished by MS for trade.
- 14 A Trusted CA in the ICS2 context is any CA trusted by the Customs Authorities of any Member State. The verification if a certificate was issues by a trusted CA will be done by UUM&DS at the moment of registration of the certificate in Customs.
- 15 The Europa List of Trusted Lists is described at Europa Trusted Lists.
- 16 The required configuration for this purpose is product specific but all products conformant to eDelivery should support it.
Source : https://mgi-team.atlassian.net/wiki/spaces/DOCI5/pages/3347120133