This guide will cover some of the common pitfalls in setting up AS2 connectivity with your partners, and ways to rectify those. Feel free to contact email@example.com for more details.
The Failure Reason column of the failed messages may contain an error similar to:
NoRouteToHostException: No route to host. Error occurred while attempting to connect to the partner URL
ConnectException: Error occurred while attempting to connect to remote address and port in the partner URL
Generally this error suggests an issue with making a POST request to the given partner URL. In order to troubleshoot this, we need to check if the partner’s domain and port is publicly accessible.
Say the partner URL is http://myas2partner.com:8082/as2. To make sure the partner domain and port is accessible to the public,
telnet command can be used.
telnet <host> <port>
telnet myas2partner.com 8082
If the output of the command is something similar to:
telnet: could not resolve myas2partner.com/8082: Name or service not known
The partner URL you have configured might be incorrect; perhaps there might be a typo. Therefore first make sure the hostname
and port in the partner URL (
8082 respectively, in the above example) is correct.
If the URL is correct, check with your partner regarding whether public DNS routing has been set up for myas2partner.com.
If the output is similar to:
telnet: Unable to connect to remote host: Connection timed out
telnet: Unable to connect to remote host: Connection refused
There might be a firewall blocking the requests coming from the AS2 Gateway. You’ll have to contact your partner to check
if it is actually the cause; if so, ask the partner to whitelist the AS2 Gateway IP 188.8.131.52, and try again once
the IP is whitelisted. If you continue to get the latter error (
Connection refused) when AS2 Gateway is whitelisted,
double-check whether the port (
8082 in the above example) in the partner URL is correct.
If you are running the
There might be cases where you are trying with your own IP address as the partner URL. In such cases make sure that the IP address you assign is a publicly accessible IP address. Note that IP addresses in the private address spaces will fail while attempting to connect.
This error suggests an error with the certificate which you are trying to upload. Most common scenarios where this could happen are as follows.
Attempting to import a PFX in place of a JKS
AS2 Gateway as of now only supports JKS (Java KeyStore) type keystores. Thus when a user tries to import a PFX (Windows-based file format for a password protected key and certificate bundle) formatted keystore in place of a keystore of type JKS a parsing error could occur. In this case, you would need to convert it to JKS format before uploading. You can find more details in this answer.
Attempting to upload an invalid certificate
Another case where parsing error would occur is when the certificate is not a valid one. One such case is when the certificate does not include the "Validity Period" which is a required field.
Attempting to upload a CSR instead of a certificate
This error is also quite common among the users who are getting started with AS2. A CSR file is a certificate signing request and is not equivalent to a certificate.
MDN for Message-ID: <123456ABCDEF.acme.com> From: MY_AS2_PARTNER To: MY_AS2_STATION Received on: Mon May 21 23:56:52 UTC 2018 Status: failed Comment: Message processing failed due to the following errors Errors encountered : error: Cannot validate message signers of : <123456ABCDEF.acme.com> - Cause : Trust anchor for certification path not found. - Signers : OU=COMODO SSL, OU=Domain Control Validated error: Signature verification failure
Note the root cause of the failure:
Trust anchor for certification path not found. - Signers : OU=COMODO SSL, OU=Domain Control Validated
This issue is related to AS2 Gateway not being able to build the trust anchor for the certificate of your partner. In most
cases the reason for this would be that your partner’s certificate is signed by a third party and the signer’s certificate is not
imported to the AS2 Gateway as a trusted certificate. One such third party which we have encountered in multiple cases is
COMODO RSA Domain Validation Secure Server CA
C=GB,ST=Greater Manchester,L=Salford,O=COMODO CA Limited,CN=COMODO RSA Domain Validation Secure Server CA).
Resolution for this would be to add the issuer (signer) certificate, as a trusted certificate. Please make sure to check with your partner to find out the intermediate certificates which need to be imported. Once you have the certificates, first, navigate to Certificates view and then click on the Import Certificates button from the top action pane. This will open a popup where you can pick the certificate files and submit them by clicking on the Import button.
This error generally occurs due to a small misconfiguration of the partner type. AS2 Gateway has two endpoints for incoming messages with one endpoint generally used for testing and the other being used for production. Which URL to use also depends on the partner type in the partner configuration. If you have set the partner type as TEST then you’ll have to use the test endpoint URL (http://test-service.as2gateway.com:8280/service/as2-receiver) and if you have set the partner type as PROD you’ll have to use the prod endpoint URL (http://service.as2gateway.com:8280/service/as2-receiver) when sending messages to the AS2 Gateway.
Decryption failure : Expected AS2 message for recipient with certificate serial number : 1234567890123456 issued by : CN=www.acme.com,O=acme solutions,OU=None,L=None,ST=None,C=None which is the local identity. However, the received message was intended for : Serial number : 17716044148874147374 issued by C=LK,ST=Some-State,O=AdroitLogic,OU=AS2-Gateway,CN=as2gateway.org,Efirstname.lastname@example.org , with error code 800 : Generic error, No payload in AS2 message, with error code 1100 : Generic error
The issue occurs when your partner has configured an incorrect encryption certificate for messages that are being sent to you. One common case we have encountered over the years is that sometimes the partner may mistakenly use the AS2 Gateway HTTPS certificate (which is also included in the partner configuration sharing email) as your encryption certificate. The sample error given above demonstrates such a scenario. You’ll need to check with your partner to rectify this issue.
Decryption failure : Error getting keypair for alias acme_alias-123456123456 from identity keystore
This error can occur if you uploaded a keystore during the AS2 station creation, providing a wrong password for the Key Password field. You can perform the following steps to verify this:
First, download the JKS file for your station, from the Certificates view.
Then use the command
keytool -export -alias acme_alias-123456123456 -file cert.crt -keystore identity.jks
to export the certificate from the key store.
Once you run the above command, your certificate will be exported to a file called
Navigate to the file’s location and try opening the file.
Provide the password when prompted. Note that if a password is not prompted, it means the certificate does not have a password set.
Most probably, you’ll notice a mismatch of the password.
If so, you’ll have to upload the keystore again, providing the correct password, to rectify the issue. You can do these as follows.
First navigate to the Stations view.
Find the particular station you are having the issue with and click on "Manage Station" button.
Then scroll down to the "Keystore" section and toggle the "Upload Existing Key Store" to true.
There you can fill in the details and upload the keystore again. More information on uploading a new keystore can be found here in the quick start guide.
Once the form is correctly filled click on "Save".