Getting Started With AS2 Protocol Using AS2Gateway and OpenAS2

Most of the large retail providers and consumer product suppliers such as Walmart, Amazon, Morgan Foods, etc. have decided to go with AS2 protocol in the last few years. Based on this trend, all of their suppliers are asked to send their invoices, purchase orders, and other B2B trading messages over AS2. Because of that, the trend for usage of AS2 has been significantly increased over the last couple of years. In this blog, I’m going to explain how to get started with AS2 protocol and how you send and receive AS2 messages using two software applications which provide AS2 capabilities.

What Is AS2?

In simple terms, the Applicability Statement 2 or AS2 specification defines a mechanism for secure and reliable transfer of structured business data over the Internet. In contrast to other traditional B2B trading protocols, AS2 offers a secure, efficient, and simple to use trading environment without a need for proprietary devices, software, or expensive private networks or value added networks. If you are new to AS2 protocol, I highly recommend you read this description of AS2 protocol before going to use it in your production requirements. It describes what AS2 is, why we need AS2, and its key benefits in simple terms, and you don’t have to have a technical background to understand it. If you have some technical background and you want to know how the protocol operates over the HTTP/S protocol, you can refer to this and get a better understanding of the implementation of the AS2 protocol.

There are a few software applications (on-premise and SaaS) which provide AS2 capability. For this exercise, I have used AS2Gateway and OpenAS2 to explain how to configure these two applications to send messages back and forth.

What Is OpenAS2?

OpenAS2 is a Java-based implementation of the AS2 standard which supports XML file-based configuration — user interface configuration is not yet implemented, but it’s there on their roadmap. You can download OpenAS2 from the above location. Make sure you download the latest version to minimize the effect of already fixed issues.

What Is AS2Gateway?

AS2Gateway is a SaaS application which implements the AS2 specification while providing the ability to configure AS2 stations and trading partners from a nice and simple user interface. Compared to OpenAS2, it’s quite easy to configure AS2Gateway for your AS2 requirements - especially if you are a user who doesn’t have a good technical background and are not familiar with server type applications working without a graphical UI. You will understand the difference while reading this blog. Since it has a GUI, it provides additional utility functionalities for advanced requirements on AS2, such as certificate management, SFTP integration, and much more.

In this exercise, I’m using two hypothetical organizations — Company X and Company Y, which expect to send and receive AS2 messages back and forth based on their B2B trading requirements. Company names will be important here, because I’m going to use AS2 identifiers based on the company name; for Company X, the AS2 identifier will be company-x-as2-id and for Company Y, it company-y-as2-id. Company X uses OpenAS2 as the AS2 software, while Company Y uses AS2Gateway as its AS2 software.

First, I’ll explain how Company X should configure its AS2 Station and trading partners in OpenAS2 and then explain the same on the AS2Gateway.

Set Up OpenAS2

First, you need to install OpenAS2 on your machine.

Installation

You just need to download and extract the ZIP file for the installation. Once it’s extracted, you can start the AS2Server by executing the bin/start-openas2.sh file. Make sure scripts are executable.

Configuration

In OpenAS2, there isn’t a concept called AS2 Station. It identifies both station and partner as two different partners and configures their relationship as a partnership. There are two main configuration files that you need to focus on basic AS2 options.

The first one is the config/config.xml. In this file, you can configure modules for AS2 message handling. You need to configure a set of AS2DirectoryPollingModule modules to fetch files to send to different partner. For each partnership between two partners, you need to have an AS2DirectoryPollingModule module element to send files from one partner to another.

The second one is the config/partnership.xml. There you need to configure declarations of each partner and relationships between those declared partners. To declare partners, you should have a partner type XML element with partner name, partner AS2 ID, partner x509 alias (for certificate management) and email — just focus on partner name, AS2 ID, and partner alias.

All the relationships between each partner should be defined as a partnership XML element in the partnerships.xml file. This element represents one-way relationships between one partner to another. If you want to send messages in both sides, you have to configure two partnership XML elements.

The next main important thing is certificate management which is the tricky part. Here you have to import and export your certificates manually to/from your keystore. By default, it uses config/as2_certs.p12 as the keystore. You can configure the keystore path by changing the filename attribute of the certificates XML element in the config/config.xml file. In the default keystore, there are two keys for two default partners — openas2a and openas2b.

For keystore configuration, there are two things you have to do:

1. Import your trading partner’s certificate into keystore using a keystore managing software or keytool — you can get the certificate of the AS2Gateway station (company-y-as2-id) using “View partner configuration” option in the AS2Gateway.
2. Export certificate chain of the key of your side partner (or in other words, your AS2 station — in this example, this should be the key of AS2 station with AS2 ID company-x-as2-id) and use it to configure your trading partner at the other end (in this example, the other end is the Company Y).

To configure OpenAS2, as explained in the following section, you need information about the AS2Gateway side station. You can get this information from the “Partner Configuration” view of your AS2 station — AS2Station view -> View Partner Configuration. This view will have all the required information to configure AS2Gateway side station in some other AS2 server as a trading partner. Generally, users’ of the AS2Gateway will use this and send this information to their trading partners via Share Configuration option in the Partner Configuration view page

Configure OpenAS2 for the Example Use Case

From the OpenAS2 side, sending party would be AS2Station with AS2 ID — company-x-as2-id and receiving party AS2 ID should be company-y-as2-id.

1. For this, you first have to configure partnerships.xml file as below — from the Company X point for view, Company X is the AS2 station and Company Y is the trading partner.

<partnerships>
    <partner name="CompanyXStation"
             as2_id="company-x-as2-id"
             x509_alias="company-x"
             email="companyx@gmail.com"/>
    <partner name="CompanyYPartner"
             as2_id="company-y-as2-id"
             x509_alias="company-y"
             email="companyy@gmail.com"/>

    <partnership name="CompanyXStation-to-CompanyYPartner">    <!-- partnership to send messages from CompanyXStation to CompanyYPartner -->
        <sender name="CompanyXStation"/>   <!-- sending party name-->
        <receiver name="CompanyYPartner"/>  <!-- receiving party name-->
        <attribute name="protocol" value="as2"/>
        <attribute name="content_transfer_encoding" value="8bit"/> <!-- content transfer encoding - seems like this is not working as expected -->
        <attribute name="compression_type" value="ZLIB"/>  <!-- compression type to used to compress AS2 message -->
        <attribute name="subject" value="From OpenAS2A to OpenAS2B"/>
        <attribute name="mdnsubject" value="Your requested MDN response from $receiver.as2_id$"/>
        <attribute name="as2_url" value="http://service.beta.as2gateway.com:8280/service/as2-receiver"/>   <!-- This should be the CompanyXStation message receiving URL -->
        <attribute name="as2_mdn_to" value="http://receipt.beta.as2gateway.com:8284/service/as2-async-mdn-receiver"/>   <!-- This should be the CompanyXStation MDN receiving URL -->
        <attribute name="as2_mdn_options" value="signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, sha-256"/>   <!-- configure how do you want to get MDN - whether it should be signed or not etc. This will be added directly to Disposition-Notification-Options transport header without any modification -->
        <attribute name="encrypt" value="3DES"/>    <!-- Encryption algorithm-->
        <attribute name="sign" value="SHA1"/>    <!-- Sign digest algorithm-->
        <attribute name="resend_max_retries" value="3"/>
        <attribute name="prevent_canonicalization_for_mic" value="false"/>   <!-- should verify the mic -->
        <attribute name="no_set_transfer_encoding_for_signing" value="false"/>  <!-- better to go with the default values for the rest of the configurations -->
        <attribute name="no_set_transfer_encoding_for_encryption" value="false"/>
        <attribute name="rename_digest_to_old_name" value="false"/>
        <attribute name="remove_cms_algorithm_protection_attrib" value="false"/>
    </partnership>

    <partnership name="CompanyYPartner-to-CompanyXStation">  <!-- partnership to send messages from CompanyYPartner to CompanyXStation -->
        <sender name="CompanyYPartner"/>
        <receiver name="CompanyXStation"/>
        <attribute name="protocol" value="as2"/>
        <attribute name="content_transfer_encoding" value="8bit"/>
        <attribute name="subject" value="From OpenAS2B to OpenAS2A"/>
        <attribute name="as2_url" value="http://my-public-ip:10080"/>  <!-- AS2 message receiving URL at the OpenAS2 side. IP of this URL should be replaced with your public IP. This IP should be publically reachble. If you are using default configuration, then use above IP together with your IP -->
        <attribute name="as2_mdn_to" value="http://my-public-ip:10081"/>  <!-- AS2 message receiving URL at the OpenAS2 side. IP of this URL should be replaced with your public IP. This IP should be publically reachble. If you are using default configuration, then use above IP together with your IP -->
        <attribute name="as2_mdn_options" value="signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, sha256"/>
        <attribute name="encrypt" value="3DES"/>
        <attribute name="sign" value="SHA256"/>
        <attribute name="prevent_canonicalization_for_mic" value="false"/>
        <attribute name="remove_cms_algorithm_protection_attrib" value="false"/>
        <attribute name="no_set_transfer_encoding_for_signing" value="false"/>
        <attribute name="no_set_transfer_encoding_for_encryption" value="false"/>
        <attribute name="rename_digest_to_old_name" value="false"/>
        <attribute name="remove_cms_algorithm_protection_attrib" value="false"/>
    </partnership>
</partnerships>

2. Next, you need to configure config/config.xml file for file polling configurations — OpenAS2 gets input files (to send out as an AS2 message), by polling directories configured from following XML elements.

<partnerships>
    <partner name="CompanyXStation"
             as2_id="company-x-as2-id"
             x509_alias="company-x"
             email="companyx@gmail.com"/>
    <partner name="CompanyYPartner"
             as2_id="company-y-as2-id"
             x509_alias="company-y"
             email="companyy@gmail.com"/>

    <partnership name="CompanyXStation-to-CompanyYPartner">    <!-- partnership to send messages from CompanyXStation to CompanyYPartner -->
        <sender name="CompanyXStation"/>   <!-- sending party name-->
        <receiver name="CompanyYPartner"/>  <!-- receiving party name-->
        <attribute name="protocol" value="as2"/>
        <attribute name="content_transfer_encoding" value="8bit"/> <!-- content transfer encoding - seems like this is not working as expected -->
        <attribute name="compression_type" value="ZLIB"/>  <!-- compression type to used to compress AS2 message -->
        <attribute name="subject" value="From OpenAS2A to OpenAS2B"/>
        <attribute name="mdnsubject" value="Your requested MDN response from $receiver.as2_id$"/>
        <attribute name="as2_url" value="http://service.beta.as2gateway.com:8280/service/as2-receiver"/>   <!-- This should be the CompanyXStation message receiving URL -->
        <attribute name="as2_mdn_to" value="http://receipt.beta.as2gateway.com:8284/service/as2-async-mdn-receiver"/>   <!-- This should be the CompanyXStation MDN receiving URL -->
        <attribute name="as2_mdn_options" value="signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, sha-256"/>   <!-- configure how do you want to get MDN - whether it should be signed or not etc. This will be added directly to Disposition-Notification-Options transport header without any modification -->
        <attribute name="encrypt" value="3DES"/>    <!-- Encryption algorithm-->
        <attribute name="sign" value="SHA1"/>    <!-- Sign digest algorithm-->
        <attribute name="resend_max_retries" value="3"/>
        <attribute name="prevent_canonicalization_for_mic" value="false"/>   <!-- should verify the mic -->
        <attribute name="no_set_transfer_encoding_for_signing" value="false"/>  <!-- better to go with the default values for the rest of the configurations -->
        <attribute name="no_set_transfer_encoding_for_encryption" value="false"/>
        <attribute name="rename_digest_to_old_name" value="false"/>
        <attribute name="remove_cms_algorithm_protection_attrib" value="false"/>
    </partnership>

    <partnership name="CompanyYPartner-to-CompanyXStation">  <!-- partnership to send messages from CompanyYPartner to CompanyXStation -->
        <sender name="CompanyYPartner"/>
        <receiver name="CompanyXStation"/>
        <attribute name="protocol" value="as2"/>
        <attribute name="content_transfer_encoding" value="8bit"/>
        <attribute name="subject" value="From OpenAS2B to OpenAS2A"/>
        <attribute name="as2_url" value="http://my-public-ip:10080"/>  <!-- AS2 message receiving URL at the OpenAS2 side. IP of this URL should be replaced with your public IP. This IP should be publically reachble. If you are using default configuration, then use above IP together with your IP -->
        <attribute name="as2_mdn_to" value="http://my-public-ip:10081"/>  <!-- AS2 message receiving URL at the OpenAS2 side. IP of this URL should be replaced with your public IP. This IP should be publically reachble. If you are using default configuration, then use above IP together with your IP -->
        <attribute name="as2_mdn_options" value="signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, sha256"/>
        <attribute name="encrypt" value="3DES"/>
        <attribute name="sign" value="SHA256"/>
        <attribute name="prevent_canonicalization_for_mic" value="false"/>
        <attribute name="remove_cms_algorithm_protection_attrib" value="false"/>
        <attribute name="no_set_transfer_encoding_for_signing" value="false"/>
        <attribute name="no_set_transfer_encoding_for_encryption" value="false"/>
        <attribute name="rename_digest_to_old_name" value="false"/>
        <attribute name="remove_cms_algorithm_protection_attrib" value="false"/>
    </partnership>
</partnerships>

3. Then you have to configure certificates and your keystore. For that, you first have to create a key pair for your Company-X side station. You can easily do that using a tool like Portacle. Since we have configured CompanyXStaion partner’s x509 alias as company-x, you have to give the entry name/alias for the key pair that you’re going to create for your Company-X.

4. Then you can export your OpenAS2 station’s certificate chain, as shown in the below screenshot. You just have to select the correct key and export the certificate chain via keystore management utility — Portacle.

5. Then, you have to import your CompanyYPartner’s certificate to your OpenAS2 side trust store. For that, you have to get this from the Company-Y side. In this case, you can get this certificate from the AS2Gateway.

With this, you are done with the OpenAS2 side configuration.

Set Up the AS2 Gateway

For AS2Gateway, you just have to sign up as a free user and get an evaluation period of one month with the exact same features, like a premium/paid user. For the registration, you don’t have to provide any credit card information, you just need a valid email address for that. You can sign up/register for AS2Gateway from here. Go to that link and click on Create Account option to create a new account for you.

From the configuration point of view, I think I don’t have to introduce anything for that. Since there is a user interface and it’s self-explainable, you should be able to identify key components of that. For our example, you just have to create a Station with AS2 ID company-y-as2-id and trading partner for Company X. I’ll explain this in next steps.

Configure AS2Gateway for the Example Use Case

As per our example, Company-Y should configure AS2Gateway to send/ receive messages with Company-X. From the AS2 point of view, we should send messages to AS2 station with AS2 ID, company-y-as2-id to the trading partner with AS2 ID, company-x-as2-id. Go through following steps to configure AS2Gateway.

1. Assuming that you have already registered with AS2Gateway, you just have to create AS2Station using the graphical UI. You can easily navigate to Stations view using left navigation menu of the AS2Gateway. Click on New Station button at the top of the page. Then you just have to give an AS2 ID for your station. In our example, AS2 ID should be company-y-as2-id. And then click the Save button.

2. Then you should create a Partner within the AS2Gateway to represent your trading partner — in our case, Company-X is the trading partner for Company-Y. For that, you just have to go to the Partner view using left navigation menu and then click on New Partner button at the top of the page.

3. In partner creation page, you have to specify the AS2 ID of the partner — company-x-as2-id in our example.

4. Specify the URI to be used while sending messages to this partner. In our example, this URI should be “http://my-public-ip:10080" — my-public-IP part should be replaced with your current public IP and it makes sure it’s publicly reachable.

5. Then you have to upload your partner’s certificate for the Encryption Certificate field. This should get from the OpenAS2 side (as explained in the following section you have to export certificate chain of your OpenAS2 side station) since it’s the partner for this example.

6. Optionally, you can configure a subject to be included while sending messages to this partner. Then click on the Save button to complete the partner creation.

Now it’s all done and you should be able to send and receive AS2 messages between AS2Gateway and OpenAS2. To send messages from the AS2Gateway side, you just have to navigate to the messages view using left navigation menu, and send a new message using the Compose Message option. All the received messages to the AS2Gateway will be there in the Inbox tab of the messages view and you can see all the information including transport headers, MDN related information and message payload using the view message option.

To send a message from OpenAS2 side to AS2Gateway, you have placed an input file to the configured input file folder. As per above configuration, it should be the

data/toAS2GStation. Received MDNs will be saved in data/OpenAS2A-to-AS2GStation/mdn folder. Received messages from AS2Gateway to OpenAS2, should be saved to the data/AS2GStation-to-OpenAS2A/inbox folder.

As you have already felt, configuring AS2Gateway for AS2 communication is much easier since it has a simple user interface and utility functionalities for certificate management and SFTP integration.

I hope you have enjoyed the blog and it’s useful to you. If you have any comments or suggestions, feel free to share in the comments.