AS2 Guide

AS2 (Applicability Statement 2) is a specification about how to transport data securely and reliably over the Internet. Security is achieved by using digital certificates and encryption. The AS2 support in the UltraESB allows AS2 flows to be integrated with any other systems in an enterprise using the in-built support of the UltraESB to support multiple transports, message formats and external systems. Although a simple UltraESB configuration could be used to setup a simple AS2 station, the real power of using an ESB will be available when the UltraESB is used to integrate AS2 communications with other enterprise systems.

AS2 Technical Overview

The AS2 protocol is based on HTTP and S/MIME. It was the second AS protocol developed and uses the same signing, encryption and MDN (as defined by RFC3798) conventions used in the original AS1 protocol. In other words:

  • Files are encoded as "attachments" in a standardized S/MIME message (an AS2 message).

  • AS2 messages are always sent using the HTTP or HTTPS protocol and usually use the "POST" method

  • Messages can be signed, but do not have to be.

  • Messages can be encrypted, but do not have to be.

  • Messages may request a Message Disposition Notification [MDN] back if all went well, but do not have to request such a message.

  • If the original AS2 message requested an MDN:

    • Upon the receipt of the message and its successful decryption or signature validation (as necessary) a "success" MDN will be sent back to the original sender. This MDN is typically signed but never encrypted (unless temporarily encrypted in transit via HTTPS).

      • Upon the receipt and successful verification of the signature on the MDN, the original sender will "know" that the recipient got their message (this provides the "Non-repudiation" element of AS2)

    • If there are any problems receiving or interpreting the original AS2 message, a "failed" MDN may be sent back. However, part of the AS2 protocol states that the client must treat a lack of an MDN as a failure as well, so some AS2 receivers will simply not return an MDN in this case.

Like any other AS file transfer, AS2 file transfers typically require both sides of the exchange to trade SSL certificates and specific "trading partner" names before any transfers can take place. AS2 trading partner names can usually be any valid phrase.

AS2 Support of the UltraESB

The UltraESB supports AS2 message processing and thus presents an extremely simple, yet powerful mechanism to integrate AS2 communications with the rest of the enterprise, unlike standalone AS2 communication software systems. Some of the key features includes:

  • Support for HTTP and HTTPS (including 2-way authentication)

  • HTTP authentication - Basic/Digest/NTLM

  • Seamless integration with any other transport or message format supported by the UltraESB

    • Transports: HTTP/S, JMS, AMQP, File, S/FTP, FTPS, Email, JDBC, MLLP/S, Scheduled Jobs, TCP/S etc

    • Message formats: SOAP, REST, JSON, XML/POX, CSX, Binary/Custom formats, text, fixed width, Hessian, FI, Protocol Buffers etc

  • Support for optional AS2 profiles

    • Multiple Attachments (e.g. used by the petroleum industry)

    • Filename Preservation (e.g. used by the banking industry)

  • Support for both synchronous and asynchronous MDNs

  • Signature, Encryption and Compression support

  • etc

as2 overview

AS2 Manager Interface

The AS2 support in the UltraESB has been developed as a separate and optional layer to the core ESB functionality, and operates over messages already accepted over or being prepared for sending via HTTP/S transports. The HTTP/S transport configurations (e.g. ports, certificates etc) and any authentication (e.g. Basic/Digest authentication etc) are thus separately configured as per standard procedure, for a Proxy service dealing with AS2 messages. The AS2Manager interface is the main interaction point between the AS2 processing code and the UltraESB and the methods it exposes to the mediation logic performs the AS2 processing. The AS2Manager Interface consists of the following methods. Please refer to the AS2 Package Javadocs for more details

Receiving Files via AS2

processIncomingAS2Message(Message)

Once a raw HTTP/S message has been accepted by a HTTP/S based proxy service, and any authentication has completed, invoke the AS2Manager.processIncomingAS2Message(Message) method to perform the AS2 incoming processing. Note that the AS2 URL your trading partners should invoke would be the URL of the proxy service you configure with this API call. In the sample #352, the proxy service "AS2Receiver" accepts messages over HTTP on port 8280, and invokes this API call from its inSequence. This will return the processing result in a bean of type ReceiveInfo which will allow the mediation code to determine if the partner requested for a synchronous MDN and it was already sent, or if the partner requested for an asynchronous MDN and sending it is now pending.

Note that if the sending partner requested for a synchronous MDN, it would have been already sent by the time the processIncomingAS2Message() method returns. If an async MDN was requested, the method would have closed the incoming transport (i.e. by sending an appropriate HTTP response code) as well. To detect a pending async MDN and to subsequently send it, refer to the following code sample.

Processing Incoming AS2 Messages

ReceiveInfo rcvInfo = mediation.getAS2Manager().processIncomingAS2Message(msg);
if (rcvInfo.isAsyncMDNRequested() && !rcvInfo.isMDNSent()) {
     Message asyncMdn = msg.cloneMessage();
     mediation.getAS2Manager().prepareAsyncMDNForSend(asyncMdn, rcvInfo);
     mediation.sendToEndpoint(asyncMdn, "async-mdn-ep");
}

prepareAsyncMDNForSend(Message, ReceiveInfo)

This method should be passed a new Message object to be populated with the required async MDN payload and headers as per information already held on the ReceiveInfo bean from the receipt of the original message. For an incoming message, usually a msg.cloneMessage() could be passed as shown in the code sample above. This API call will set the asynchronous MDN reply URL sent by the partner as the destination URL of the created message. Note that this method does NOT actually perform any message sending, but merely marks the async MDN as being prepared for sending. Hence a "default" address type endpoint could now send this message along to the URL specified by the trading partner.

Default Address Endpoint definition for Async MDNs

<u:endpoint id="async-mdn-ep">
     <u:address type="default"/>
</u:endpoint>

processAsyncMDNSendResult(Message)

This API method should be invoked from the outSequence of the proxy service sending out an async MDN. The outSequence which receives the response to the async MDN will then accordingly report to the AS2Manager on the outcome of the async MDN delivery.

recordSendFailure(Message)

This API method should be invoked from the errorSequence of the proxy service sending out an async MDN. The errorSequence which will handle a send failure could then appropriately report back to the AS2Manager of the outcome.

Sending Files via AS2

prepareAS2MessageForSend(Message, Partner or "<partner-id>")

This API call is used to create an AS2 level message using the current payload and any attachments and target it for the selected Partner. This method can accept the Partner as an Object, or as the unique AS2 identifier already stored by the persistence service along with other information about the partner. Note that this method does not perform any automatic sending of the message, but merely records in the AS2Manager that the message has been prepared for sending. The message is set to the AS2 URL of the specified partner, and hence a "default" address endpoint could be used to perform the actual send.

processSyncResponse(Message)

This API call should be used in the outSequence of a proxy service sending out AS2 messages, and would process the synchronous responses received back from the trading partner. A synchronous response could contain an MDN, or simply a closure of the transport. This information is them recorded by the AS2Manager. The errorSequence should invoke the recordSendFailure(Message) API call to inform the AS2Manager that a send operation failed.

Asynchronous MDN Receipt

Where asynchronous MDNs are requested from a trading partner when sending out an AS2 message, an appropriate proxy service should be setup to accept such MDN messages. Such messages should be notified to the AS2Manager using the processAsyncMDN(Message) method, which will return a bean AsyncMDNInfo containing information about the asynchronous MDN received. Once an async MDN is received for a message sent out, the AS2Manager will record that the send operation has successfully completed.

AS2 Persistence Service

The AS2 Manager used may optionally be configured with a Persistence Service implementation. The purpose of a PersistenceService is to persist AS2 message exchange meta data and optionally the actual application level AS2 message payloads for auditing, logging and error recovery or manual intervention etc. The persistence service will perform the persistence independent of any mediation specific persistence or processing during mediation, and will deal at the AS2 level message meta information and payloads received or sent. The default persistence service maybe replaced with a custom implementation, if the user requires persistence to a custom database schema and or other mechanism such as NoSQL/cloud storage etc.

In this topic
In this topic
Contact Us