AS2

AS2 Connector

The AS2 Connector supports sending and receiving messages via the secure and reliable AS2 protocol.

Overview

An AS2 connection is configured in two modes. AS2 Server and AS2 Client. As AS2 Server the profile section should be configured with a local AS2 identifier, private certificates, and other information that is global among all AS2 connections.

Then, each AS2 Connector should be configured with connection settings specific to a single trading partner. When an input file is processed by an AS2 Connector, it is packaged and sent to the specified trading partner.

When Justransform receives a file over AS2, it attempts to route the file to a specific AS2 Connector. The application uses the AS2 identifiers in the AS2 message to determine which AS2 Connector should receive the file. When a file is routed to an AS2 Connector, that file is delivered to the “Inbound Business Process” associated with the connection and the message gets processed as per the flow defined in the associated Business Process.

Profile Configuration

The AS2 Profile must be configured before connections can be established with individual AS2 Connectors.

AS2 Common Connection Details:

Refer to Common Connection Modules

Protocol Config

AS2 From

AS2 To

Subject

Message Polling Interval

URL

Encryption Algorithm

MIME Type

MDN Required

MDN Security

MDN Delivery

Outgoing Message Security

Incoming Message Security

Certificate

JT Server Information

AS2 Server

URL:http://localhost:8080/justransform/as2/receive

AS2 Certificate

What Happens in an AS2 Exchange

For all of its complexity in terms of its applications, AS2 boils down to two basic parts: A document is sent from an AS2 sender to an AS2 receiver via HTTP, a very flexible client-server protocol that serves as the backbone of the World Wide Web. The receiver acknowledges the transfer by providing the sender with a receipt.

The following illustration demonstrates the different steps that are taken in further detail.

Step 1: EDI Document Preparation

In an AS2 exchange, any type of document can be sent, from a text file to a PDF. Typically, however, most trading partners implement a standard for specific document types.

The most common document types are electronic data exchange (EDI) X12 documents (.x12 or .edi files), , Electronic Data Interchange for Administration, Commerce and Transport (EDIFACT) documents (.edifact files), or XML files (.xml files) The preparation of the document takes place before the AS2 communication begins.

EDI (Electronic Data Interchange) is a general term for the transfer of documents between trading partners and the standards that are adhered to. It is also represented as EDI over the Internet (EDIINT)

Step 2: AS2 Packaging

The AS2 document is prepared for sending. This consists of three types of document transformation. If the document consists of data that is compressible (that is, not binary data), the document may be compressed using the zlib compression algorithm to reduce the size of the transported data. The data is typically signed using the private key of the sender to ensure the sender’s identity as the creator of the document (usually with the SHA-1 signing algorithm). Finally, the data may be encrypted using the receiver’s public key so only the trading partner can read the data (usually using the 3DES encryption algorithm). This step may be skipped if the data is going to be delivered by a secure transport mechanism, such as HTTPS.

S/MIME is the set of standards used for encryption and signing of a message/document. It not only governs the functions of signing and encryption, but it also provides standards for the formatting of the final message so that a compliant reader can easily identify the structure of the message.

Step 3: HTTP/S Delivery

The prepared document is then delivered to the trading partner over the Internet to the trading partner’s Web server over the HTTP or HTTPS protocol.

Step 4: AS2 Unpackaging

The receiver of the prepared document then un-packages to retrieve the EDI document. If the data was encrypted, the prepared document is then decrypted using the receiver’s private key. If the data was signed, the signature on the document is verified using the sender’s public key to ensure the identity of the sender. If the document has been compressed, the prepared document is then decompressed to produce the original EDI document.

Step 5: EDI Processing

At this point, the AS2 receiver passes the un-packaged EDI document to any back-end process that handles the data to perform any additional business logic. Now, the EDI document is parsed and the receiver may even initiate a new AS2 transaction where the roles of sender and receiver are reversed. In particular with EDI-X12 documents, a 997 Functional Acknowledgment is often sent to the original sender to signify that the original EDI document was processed in the back-end business logic.

Step 6: MDN Reply

The receiver sends back an message delivery notification (MDN) to the sender, in most cases signed with the receiver’s private key. The MDN is a receipt that is returned in an AS2 exchange and used to report to the sender what was received and whether or not it was received successfully.

The MDN contains information about whether or not the document was successfully un-packaged, as well as a message digest that is calculated over the received payload. The MDN is then returned to the sender in one of two ways, depending on how the sender asked for the MDN to be delivered. In a synchronous transaction, the receiver returns the MDN in the HTTP reply from the receiver’s Web server. In an asynchronous transaction, the HTTP reply contains a simple acknowledgment (200 OK), and the MDN is returned over a separate connection (this is usually the case if the un-packaging of the AS2 transmission is expected to take a while).

Step 7: MDN processing

When the sender receives the MDN from the receiver, the MDN signature is verified if the MDN was signed. The status of the MDN is checked to see if the receiver was successful in processing the transaction, or if they encountered an error that was reported in the MDN. Finally, the message digest reported in the MDN is matched against a message digest that was calculated over the EDI data that was sent. With a signed MDN, the sender can verify that the receiver of the message received the entire contents of the EDI document as it was intended to be delivered.

Certificates

The AS2 Connector makes use of both private key certificates and public key certificates.

Private Key Certificates

The AS2 Connector allows you to specify certificates in PKCS#12 format (a .pfx file or a .p12 file). Private key certificates are used to perform the two operations that only the holder of the private key should be able to perform:

Signing data to provide proof of your identity.
Decrypting data that was intended for you.

Public Key Certificates

Public key certificates are given to you by your trading partner. The AS2 Connector allows you to specify public key certificates in X.509 format (a .cer or .der file). Public key certificates are used to work in reverse of the operations that require a private key. These operations include:

Verifying signatures created by your trading partner.
Encrypting data so that only your trading partner can read it.

Common Errors

Below is a list of common errors, their causes, and the recommended solution. Please contact support@Justransform.com for more information.

ERROR:

“The receipt signature could not be verified: Message digest mismatch in signature”

Cause

MDN receipt signatures contain a message digest that ensures the content of the message has not been altered in transit. A digest mismatch could suggest that the MDN was altered before being received, or was not generated properly on the partner’s end.

Sometimes this error can be caused by Anti-Virus or File Security software improperly stripping part of the MDN response. There is a known issue with ESET’s Application Protocol Filtering feature where folded MDN headers may be invalidated due to whitespace removal.

Resolution

First, take a look at the MDN returned by the partner for apparent issues. Download the .mdn file for the transaction where this error is thrown and either send it to support@Justransform.com along with a description of the issue, or investigate independently.

It may also be helpful to reach out to the trading partner to confirm what AS2 solution they use. Justransform is interoperable with any Drummond-certified AS2 solution.

ERROR:

“The receipt signature could not be verified: The certificate specified does not match the signature”

Cause

MDN receipt are signed with a private key, and this signature is validated with the corresponding public key. This error suggests that the public key configured to verify signatures from this partner is incorrect.

Resolution

Often, the same public key certificate that is used for encryption is also used to verify signatures. In this case, check the certificate in the AS2 Connector to make sure it is correctly configured for this trading partner.

Sometimes, trading partners will use a separate certificate for signatures. In this case, set the Signing Certificate setting to the public key certificate that matches the partner’s signing key.

ERROR:

“The receipt signature could not be verified: Message digest was encrypted with unknown algorithm”

Cause

This is a known issue in older versions of the application that only supported SMIME encryption v3.1. If an MDN contains a message digest encrypted with SMIME 3.2, this error will be thrown.

Resolution

All current versions of Justransform, including the final published build of v2016, support SMIME 3.2. Older versions will require and upgrade to resolve this error.

ERROR:

“MDN Error: Authentication failed”

OR

ERROR:

“MDN Error: Signature Authentication failed: Could not authenticate signer’s identity”

Cause

This error is included as part of the MDN response, indicating that the trading partner could not verify the signature in the AS2 request. This suggests a general certificate mismatch between the trading parties.

Resolution

Check that the private certificate configured in Justransform’s AS2 profile is correct, and that the trading partner has configured the matching public key certificate on their end.

ERROR:

“MDN Error: Unexpected processing error”

Cause

This error is thrown by the trading partner’s system and is returned as part of the MDN to indicate a failure to process the AS2 request. This error is a general error, thrown when the problem is not related to signing, encryption, or compression.

Resolution

Since this error does not include specific debugging information, the trading partner should be contacted for further information about what caused the failure.

ERROR:

“System error: Connection refused”

Cause

This network error indicates a general connectivity problem. It is thrown when a connection attempt is made to a server that is not actively listening. This may indicate the server has gone down, or that the connection attempt is being made to the wrong URL.

Resolution

Check that the target URL is correct. If the error persists, contact the server administrators for the target system to see if the server has gone down, or if they have more information about the issue.

ERROR:

“Connection failed: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond”

OR

ERROR:

“Connection timed out”

Cause

This network error indicates a general connectivity problem. It is thrown when the connection attempt to the server goes unanswered for a period of time (typically 60 seconds). This is often the result of firewall interference with the server’s response, but it may also indicate incorrect connection parameters.

Resolution

Check that firewalls are not preventing the server’s response from being returned. If the server is also behind a firewall, check that the IP from which the AS2 messages are being sent is whitelisted in the server’s firewall.

If firewalls have been ruled out, check that the target URL is correct.

ERROR:

“Synchronous MDN expected but not received”

Cause

This is a general error indicating that the response to the AS2 request was not an MDN. This may indicate that the AS2 request was not sent to an AS2 server as expected. This error can also be thrown if an MDN was returned, but it was corrupted such that Justransform cannot appropriately recognize it as an MDN.

Resolution

Check that the target URL is correct. Then, check to see if a firewall may be stripping contents from the MDN, preventing Justransform from parsing it correctly. If the issue with the MDN is not clear, find the .mdn file associated with the failed transaction and provide it to support@Justransform.com along with a description of the issue.

ERROR:

“Unsigned MDN received, but signed MDN requested”

Cause

This error is thrown when the MDN received from the trading partner does not include a signature block as expected. The signature status in the MDN can be toggled within an AS2 Connector.

Resolution

If the trading partner is seeing this error, make sure the MDN Receipts option is set to Signed. If Justransform is seeing this error, this indicates a configuration issue in the trading partner’s system. Contact the trading partner and ensure that they are signing MDN receipts as requested.

ERROR:

“Unable to find valid certification path to requested target”

Cause

This error is thrown in the Java edition by the underlying Java security provider. It indicates that the SSL server certificate presented by the target web server is not trusted by the system.

Resolution

The SSL Server Certificate trust can be overridden in the AS2 Connector Please contact support@Justransform.com for more information..

ERROR:

“Key does not exist”

Cause

This is a known issue in the Windows CryptoAPI when multiple threads are attempting to access the same private key. By default, Justransform uses the Windows CryptoAPI to perform security operations like loading private certificates.

Resolution

Justransform comes with an internal implementation of crypto operations, and this managed implementation can be enabled to workaround the Windows CryptoAPI limitation. Please contact support@Justransform.com for more information.

ERROR:

“Input string was not in a correct format”

Cause

This indicates that string validation failed for some aspect of the AS2 Connector configuration. Typically the Receiving URL setting or or some string processing in the Events scripts are the source of the error.

Resolution

Check that the target URL is with a valid HTTP prefix (‘http://’ for plaintext connections or ‘https://’ for SSL connections) and does not contain any unintended whitespace.

If scripts are present in the Events of the connector (e.g. BeforeSend, AfterReceive) then check that invalid string processing is not being performed. It may be easiest to provide the scripts directly to support@Justransform.com to confirm whether the scripts are causing the issue.

ERROR:

“500 Internal Server Error”

Cause

This HTTP error indicates a general server-side failure. The AS2 message was successfully received, but some error occurred when processing the message and no further debugging information is available.

Resolution

The only client side setting that could be related to this issue is the target URL. If this is correct, then server-side logs must be consulted to learn more about what caused the processing failure. Consult with the trading partner to see if these server logs are available.

ERROR:

“404 Not Found”

Cause

This HTTP error indicates that no resource could be found at the target URL. This usually indicates that the first half of the URL is correct (host, port) but that the second half of the URL (the resource path) is not recognized.

Resolution

Check that the resource path in the target URL is correct. It may be worth confirming with the trading partner what the expected resource path should be.

ERROR:

“401 Unauthorized”

Cause

This HTTP error indicates that authorization is required to reach the specified URL. This may be SSL Client Authentication or HTTP Authentication.

Resolution

If SSL Client Authentication is required, Please contact support@Justransform.com for more information.

ERROR:

“Incoming request did not match a configured trading partner profile”

Cause

When an AS2 message is received by Justransform, the application attempts to route the message to a specific AS2 Connector based on the configured AS2 identifiers. This error indicates that no connector could be found where the AS2 identifiers for sender and receiver match the values present in the AS2 message.

Resolution

Check the AS2 identifiers configured in both the AS2 Profile section of Justransform and the AS2 Connector configured for the specific trading partner affected by this error.

ERROR:

“Error during handshake: The token supplied to the function is invalid”

Cause

This is one of several SSL errors returned by the WinSock library (Windows Sockets). Often, this error occurs when an HTTP connection is attempted with a server that expects HTTPS connections.

Resolution

Confirm with the trading partner whether the AS2 connection should be over HTTP or HTTPS, and check that the target URL has the appropriate prefix and port.

ERROR:

“Error during handshake: the buffer supplied to a function was too small”

Cause

This is one of several SSL errors returned by the system WinSock library, and is a known bug with the Windows CryptoAPI on certain server OS’s. The issue occurs when using TLS 1.2 and two specific cipher suites:

TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 RLS_DHE_RSA_WITH_AES_256_GCM_SHA384

Resolution

Justransform comes with an internal implementation of crypto operations, and this managed implementation can be enabled to workaround the Windows CryptoAPI limitation. Please contact support@Justransform.com for more information.

ERROR:

“Error during handshake: the function requested is not supported”

Cause

This is one of several SSL errors returned by the system WinSock library, and indicates a mismatch in the supported SSL/TSL versions between client and server.

Resolution

TLS versions can be enabled within the AS2 ConnectorPlease contact support@Justransform.com for more information.