Trading B2B documents using OpenAS2 with the WebSphere DataPower B2B Appliance XB60

AS2 is the industry standard protocol for trading B2B messages and OpenAS2 is an open-source project that implements AS2 in Java. This article shows you how to use OpenAS2 with the WebSphere DataPower B2B Appliance XB60 to create a test harness and trade B2B documents.

Bill Barrus (bbarrus@us.ibm.com), Senior Solutions Architect, IBM

Bill Barrus is a Senior Software Engineer and Certified IT Specialist on the WebSphere DataPower Level 2 Support team with IBM in Durham, NC, specializing in security and B2B. He began his IBM career performing mechanical design studies for the U.S. Navy F-14 avionics upgrade program, moved into mechanical computer-aided engineering, and then contributed to emerging business opportunities in CATIA Engineering Analysis, Lotus Workplace Client Technology Micro Edition, and WebSphere Voice Server. You can contact Bill at bbarrus@us.ibm.com



Peter J. Daly (cgi.web@gmail.com), WebSphere Consultant, IBM

Peter Daly has left IBM. At the time he wrote this article, he was a WebSphere Consultant on the WebSphere Software Services team with IBM UK. His areas of expertise include Unix, WebSphere DataPower, and WebSphere Process Server, and he co-authored IBM Redbooks on WebSphere DataPower and WebSphere Process Server. He holds Bachelors Degrees in Physics and Computer Science. You can contact Peter at cgi.web@gmail.com.



05 January 2011

Also available in Chinese

Introduction

OpenAS2 enables you to transmit and receive AS2 messages with EDI-X12, EDIFACT, XML, or binary payloads between trading partners. Since OpenAS2 documentation is sketchy, this article shows you to how to install, configure, and use OpenAS2 and create a reference model that you can adapt for different scenarios. The article then shows you how to use this OpenAS2 reference model to test B2B gateways by using it as a client to send messages to an IBM® WebSphere® DataPower® B2B Appliance XB60 (hereafter called an XB60).

Part 1. Installing OpenAS2

To be able to run the scenarios in this article, you will need to have Java™ installed -- the article uses Java 1.6. You will also need the OpenAS2 package and the Java Cryptography Extension (JCE) policy files, which you can download at the bottom of the article.

Figure 1. OpenAS2 installation folder structure
OpenAS2 installation folder structure
  1. Unzip the downloaded OpenAS2 package into a suitable location, which we will call <install_dir>. Typical values for <install_dir> are /opt/OpenAS2 under Linux® or C:\OpenAS2 under Microsoft® Windows®.
  2. Rename the file <install_dir>/lib/openAS2_<date>.jar to <install_dir>/lib/openas2-lib.jar (case sensitive). Figure 1 above shows the unzipped package after this renaming with the file highlighted. Your installation should look the same.
  3. For the encryption and certificate management to work correctly, you must have the proper JCE policy files installed in your version of Java. The downloaded zip archive contains the two files local_policy.jar and US_export_policy.jar. Install them into your Java location under <JAVA_HOME>/lib/security. Back up the existing files before installing these new ones.
  4. As a check, unzip the downloadable additional materials file that accompanies this article and copy the myCompany folder for your platform (Windows or Linux) to <install_dir>. Then run standalone.sh on Linux or standalone.cmd on Windows to start OpenAS2. Type exit to stop the software. You should see output similar to that in Figure 2 below. If you get any Java exceptions, you may need to add Java to your PATH. If these exceptions are SSL certificate related, you probably installed the JCE policies incorrectly.
Figure 2. Sample run of OpenAS2
Staring OpenAS2 with file myCompany.xml
OpenAS2 v0.9
Starting Server...
Loading configuration...
Registering Session to Command Processor...
Starting Active Modules...
OpenAS2 Started
07/14/10 12:03:57 OpenAS2Server: - OpenAS2 Started -
Loading Command Processor...[Thread[Thread-2,5,main], Thread[Thread-3,5,main]]
Loading Command Processor...[Thread[Thread-2,5,main], Thread[Thread-3,5,main]]
#>exit

Part 2. Configuring the OpenAS2 reference model

The following reference model will be used throughout this article. The port values are arbitrary, but these settings must be consistent on both sides for message exchange to take place. The scenario involves two trading partners, myCompany and myPartner, exchanging messages using OpenAS2. These trading partners are defined within OpenAS2; they are not the hostnames of the systems. Indeed, these trading partners could reside on the same physical hardware. The model is shown in Figure 3 below. An AS2 message from myPartner to myCompany is sent on port 10080 and the MDN received either synchronously or on port 20081 asynchronously. Conversely, an AS2 message is sent from myCompany to myPartner on port 20080 and the MDN received back either synchronously or on port 10081 asynchronously.

Figure 3. OpenAS2 reference model used here
OpenAS2 reference model

Configuring the reference model

Creating the reference model requires two trading partner configurations myCompany and myPartner, as shown in Figure 3 above. They can be Windows systems, Linux systems, or a mixture of the two, and they can even be on the same host. Be sure to use the correct file separator character -- "\" on Windows and "/" on Linux . As shown in Figure 3, four files control the behavior of a trading partner:

  • A key store to hold SSL certificates, which will be exchanged between trading partners.
  • A configuration file that controls the behavior of a trading partner ( myCompany.xml and myPartner.xml in Figure 3 above). It contains the properties of the trading partner and values for the partner with whom it will trade.
  • A partnerships file that defines a relationship between two trading partners. By default this file is called partnerships.xml
  • A command file called commands.xml that is part of the OpenAS2 distribution and does not need to be modified.

These files are provided as part of the download materials for Windows or Linux. They are supplemented with a Unix shell script and a DOS command file to run the software.

Part 3. Trading documents using preconfigured partners (Windows example)

You can start trading documents on Windows or Linux by using the files in the accompanying zip file. On Windows, in your OpenAS2 <install_dir>, copy the folders Windows\myCompany and Windows\myPartner from the unzipped files as shown in Figure 4 below (not all the OpenAS2 folders are shown). The only difference between Windows and Linux here is that standalone.cmd would be replaced with the standalone.sh shell script, and the myCompany and myPartner folders would have been copied from the Linux subdirectory in the unzipped package. The only difference between the myCompany.xml and myPartner.xml files between Windows and Linux is the file separator changing from backslash to forward slash.

Figure 4. OpenAS2 configuration for myCompany and myPartner
C:\OpenAS2 (<install_dir>)
+--lib
|  ...
+--myCompany
|  commands.xml
|  myCompany.p12
|  myCompany.xml
|  partnerships.xml
|  standalone.cmd
|
+--myPartner
|  commands.xml
|  myPartner.p12
|  myPartner.xml
|  partnerships.xml
|  standalone.cmd

You are now ready to trade! In the myCompany folder double-click on the standalone.cmd file. Assuming you have installed the JCE component, you should see OpenAS2 running as shown in Figure 5 below. In this folder the software has created subfolders called resend, To_any, To_myCompany and To_myParter, as well as a log file:

Figure 5. OpenAS2 running
OpenAS2 running

In the myPartner folder double-click on the standalone.cmd file. You will see the same folders and log file being created and a window similar to the one in the figure above. To send a document from myPartner to myCompany simply drop a file into the <install_dir>/myPartner/To_myCompany folder. The exchange is shown in the figures below (with highlighted messages). Where is the file delivered to? It will appear in a folder called inbox in the <install_dir>\myCompany directory.

Figure 6. Sending a document from myPartner to myCompany
Sending a document from myPartner to myCompany
Figure 7. myCompany sending a reply to myPartner
myCompany sending a reply to myPartner

For clarity, the output is shown in text form in Figure 8 below, mixing the two outputs to show the flow and highlighting the important parts:

  1. In the first block, myPartner polls the to_MyCompany folder, picks up the message, encrypts and signs it, and transmits it to myCompany using HTTP on port 10080.
  2. In the second block, myCompany receives the message, decrypts and verifies it, and then stores it in the myCompany folder along with the headers. It then sends the MDN synchronously, which we know because the first and last line of this middle block show the IP (127.0.0.1) and port (3216) to be the same.
  3. In the third block, myPartner receives the MDN, verifies it, and logs the fact that the message was sent and received and removes it from the to_myCompany folder.
Figure 8. Sending a document from myPartner to myCompany
myPartner: 07/28/10 10:19:19 DirectoryPollingModule: processing 
    C:\OpenAS2\myPartner\To_myCompany\inbound.EDIFACT
myPartner: 07/28/10 10:19:19 DirectoryPollingModule: file assigned to message 
    C:\OpenAS2\myPartner\To_myCompany\inbound.EDIFACT 
    [<OPENAS2-28072010101919+0100-7908@myPartner_myCompany>]
myPartner: 07/28/10 10:19:19 AS2SenderModule: message submitted 
    [<OPENAS2-28072010101919+0100-7908@myPartner_myCompany>]
myPartner: 07/28/10 10:19:19 AS2SenderModule: signed data 
    [<OPENAS2-28072010101919+0100-7908@myPartner_myCompany>]
myPartner: 07/28/10 10:19:20 AS2SenderModule: encrypted data 
    [<OPENAS2-28072010101919+0100-7908@myPartner_myCompany>]
myPartner: 07/28/10 10:19:20 AS2SenderModule: connecting to http://localhost:10080
    [<OPENAS2-28072010101919+0100-7908@myPartner_myCompany>]
myPartner: 07/28/10 10:19:20 AS2SenderModule: transferred 2778 bytes in 0.46 seconds 
    at 58.999 KBps [<OPENAS2-28072010101919+0100-7908@myPartner_myCompany>]

myCompany: 07/28/10 10:19:20 AS2ReceiverHandler: incoming connection 127.0.0.1 3216
myCompany: 07/28/10 10:19:20 AS2ReceiverHandler: received 2779 bytes in 0.78 seconds
    at 34.812 KBps 127.0.0.1 3216 
    [<OPENAS2-28072010101919+0100-7908@myPartner_myCompany>]
myCompany: 07/28/10 10:19:20 AS2ReceiverHandler: decrypting 
    [<OPENAS2-28072010101919+0100-7908@myPartner_myCompany>]
myCompany: 07/28/10 10:19:20 AS2ReceiverHandler: verifying signature 
    [<OPENAS2-28072010101919+0100-7908@myPartner_myCompany>]
myCompany: 07/28/10 10:19:20 MessageFileModule: stored message to C:\OpenAS2\myCompany\
    inbox\myPartner-myCompany-_OPENAS2-28072010101919-7908@myPartner_myCompany_ 
    [<OPENAS2-28072010101919+0100-7908@myPartner_myCompany>]
myCompany: 07/28/10 10:19:20 MessageFileModule: stored headers to
    C:\OpenAS2\myCompany\inbox\msgheaders\2010\07\myPartner-myCompany-_
    OPENAS2-28072010101919-7908@myPartner_myCompany_ 
    [<OPENAS2-28072010101919+0100-7908@myPartner_myCompany>]
myCompany: 07/28/10 10:19:20 AS2ReceiverHandler: sent MDN 
    [automatic-action/MDN-sent-automatically; processed] 127.0.0.1 3216 
    [<OPENAS2-28072010101919+0100-7908@myPartner_myCompany>]

myPartner: 07/28/10 10:19:20 AS2SenderModule: received MDN 
    [automatic-action/MDN-sent-automatically; processed] 
    [<OPENAS2-28072010101919+0100-7908@myPartner_myCompany>]
myPartner: 07/28/10 10:19:20 AS2SenderModule: mic is matched, 
    mic: nrpe5qz/n4GKdl+Cl+hgrrImyA4=, sha1 
    [<OPENAS2-28072010101919+0100-7908@myPartner_myCompany>]
myPartner: 07/28/10 10:19:20 AS2SenderModule: message sent 
    [<OPENAS2-28072010101919+0100-7908@myPartner_myCompany>]
myPartner: 07/28/10 10:19:20 DirectoryPollingModule: 
    deleted C:\OpenAS2\myPartner\To_myCompany\inbound.EDIFACT 
    [<OPENAS2-28072010101919+0100-7908@myPartner_myCompany>]

You have now traded a document from myPartner to myCompany. Trading in the other direction is simply a matter of dropping a file into the <install_dir>\myCompany\to_myPartner folder. Try it for yourself, and then shut down OpenAS2 by typing exit in both of the command windows.

Part 4. Trading documents with custom trading partner names (Linux example)

In the previous section you traded documents between preconfigured trading partners. This section shows you how to configure OpenAS2 for two arbitrary trading partners called partnerA and partnerB. You created the myCompany and myPartner profiles using this method. This new scenario uses Linux because it provides simpler management of SSL certificates using the OpenSSL package.

You can use the shell scripts in the downloadable materials to create the files required. OpenAS2 is installed in /opt/OpenAS2 and the downloaded files are in /tmp/Files. You can log in to your Linux system as any user; root is not required to run the software.

Creating the required configuration files

The download files are set up by default to assume Linux for both trading partners. If you want Windows for one or both trading partners, edit the createXML.sh file and change the value of the field separator for each partner as required (search for Partner1_FileSep and/or Partner2_FileSep). Here is the complete setup from unzip to trading:

cd /tmp
unzip Files.zip
cd /tmp/Files/Templates
sh ./createXML.sh partnerA partnerB

The result should be three new files: partnerA.xml, partnerB.xml, and partnerships.xml. Copy these files to the appropriate locations:

mkdir -p /opt/OpenAS2/partnerA
cp /tmp/Files/commands.xml /opt/OpenAS2/partnerA
cp /tmp/Files/standalone.sh /opt/OpenAS2/partnerA
chmod 755 /opt/OpenAS2/partnerA/standalone.sh
cp /tmp/Files/Templates/partnerA.xml /tmp/Files/Templates/partnerships.xml 
    /opt/OpenAS2/partnerA
mkdir -p /opt/OpenAS2/partnerB
cp /tmp/Files/commands.xml /opt/OpenAS2/partnerB
cp /tmp/Files/standalone.sh /opt/OpenAS2/partnerB
chmod 755 /opt/OpenAS2/partnerB/standalone.sh
cp /tmp/Files/Templates/partnerB.xml /tmp/Files/Templates/partnerships.xml 
    /opt/OpenAS2/partnerB

Use the scripts provided to create the key stores automatically. The script creates many files but the only ones you need are the p12 files:

cd /tmp/Files/SSL
sh ./createSSL.sh partnerA partnerB
cp /tmp/Files/SSL/partnerA.p12 /opt/OpenAS2/partnerA
cp /tmp/Files/SSL/partnerB.p12 /opt/OpenAS2/partnerB

Trading documents

You should now have two folders and five files in each folder, as shown in Figure 9 below:

Figure 9. OpenAS2 configuration for myCompany and myPartner
/opt/OpenAS2
+--partnerA
|  commands.xml
|  partnerA.p12
|  partnerA.xml
|  partnerships.xml
|  standalone.sh
|
+--partnerB
|  commands.xml
|  partnerB.p12
|  partnerB.xml
|  partnerships.xml
|  standalone.sh

Let's start trading! You will need three windows open: one for each trading partner and the third one to put files into the appropriate folders.

In the first window (PartnerA), run the standalone.sh script with partnerA.xml as a parameter:

cd /opt/OpenAS2/partnerA
sh ./standalone.sh partnerA.xml

In the second window (PartnerB) run the standalone.sh script with partnerB.xml as a parameter:

cd /opt/OpenAS2/partnerB
sh ./standalone.sh partnerB.xml

Finally, in the third window, drop a file into the appropriate location to send it between trading partners.

  • To send a file from partnerA to partnerB: cp /tmp/Files/partnerA.EDIFACT /opt/OpenAS2/partnerA/To_partnerB
  • To send a file from partnerB to partnerA: cp /tmp/Files/partnerB.EDIFACT /opt/OpenAS2/partnerB/To_partnerA

When you have finished sending files, type exit in both partner windows to stop OpenAS2. Figure 10 below shows the (mixed) output of sending a file from partnerA to partnerB. For clarity, unnecessary lines have been removed and replaced by ....

Figure 10. partnerA sending a document to partnerB
partnerA: 07/15/10 10:32:34 DirectoryPollingModule: 
     processing /opt/OpenAS2/partnerA/To_partnerB/inbound.EDIFACT
partnerA: 07/15/10 10:32:34 DirectoryPollingModule: file assigned to message ... 
    [<OPENAS2-15072010103234+0100-5611@partnerA_partnerB>]
partnerA: 07/15/10 10:32:34 AS2SenderModule: message submitted ... 
partnerA: 07/15/10 10:32:34 AS2SenderModule: signed data ... 
partnerA: 07/15/10 10:32:34 AS2SenderModule: encrypted data ... 
partnerA: 07/15/10 10:32:34 AS2SenderModule: connecting to http://localhost:20080 ... 
partnerA: 07/15/10 10:32:35 AS2SenderModule: transferred 2848 bytes 
    in 0.74 seconds at 37.598 KBps ... 

partnerB: 07/15/10 10:32:35 AS2ReceiverHandler: incoming connection 127.0.0.1 45530
partnerB: 07/15/10 10:32:35 AS2ReceiverHandler: received ... 127.0.0.1 45530 
     [<OPENAS2-15072010103234+0100-5611@partnerA_partnerB>]
partnerB: 07/15/10 10:32:35 AS2ReceiverHandler: decrypting ... 
partnerB: 07/15/10 10:32:35 AS2ReceiverHandler: verifying signature ... 
partnerB: 07/15/10 10:32:35 
    MessageFileModule: stored message to /opt/OpenAS2/partnerB/inbox ... 
partnerB: 07/15/10 10:32:35 
    MessageFileModule: stored headers to /opt/OpenAS2/partnerB/inbox/ ... 
partnerB: 07/15/10 10:32:35 
    AS2ReceiverHandler: sent MDN ... 127.0.0.1 45530 ... 

partnerA: 07/15/10 10:32:35 AS2SenderModule: received MDN ... 
    [<OPENAS2-15072010103234+0100-5611@partnerA_partnerB>]
partnerA: 07/15/10 10:32:35 AS2SenderModule: mic is matched, 
    mic: 3rv2s+RzWodgiK6DHiTJHPYjn+w=, sha1 ... 
partnerA: 07/15/10 10:32:35 AS2SenderModule: message sent ...
partnerA: 07/15/10 10:32:35 DirectoryPollingModule: 
    deleted /opt/OpenAS2/partnerA/To_partnerB/inbound.EDIFACT ...

What the configuration files do

This section explains the details of the configuration files and how they link together. It uses the myCompany files -- the discussion is the same for other trading partners. Recall that the configuration of a trading partner consists of four files -- in the case of myCompany they are myCompany.xml, partnerships.xml, commands.xml and myCompany.p12.

myCompany.xml (or myPartner.xml)

Determines the folders and ports to use to trade documents with a trading partner. Here are some of the significant nodes in this file:

  • The <certificates> stanza determines which SSL keystore to use and the password to access it.
  • The <loggers> stanza is used to log the running OpenAS2 software for problem determination. For this exercise, it logs to a simple text file and to the console window.
  • The <commandProcessors> stanza determines how commands are processed. Normally you do not need to change anything here, but if you run the two trading partners on the same host, you need to change the portId for one of them in order to avoid "Socket in use" errors. Just choose a portId value that is not in use.
  • The <processor> stanza contains <module> stanzas to change the behavior of OpenAS2. The classname attribute of the module specifies which values are to be used. Some of the class names are listed below:
    • The receiver.AS2DirectoryPollingModule class name determines which directory to poll for messages. For example:
      <module classname="org.openas2.processor.receiver.AS2DirectoryPollingModule"
      outboxdir="%home%/To_myPartner" errordir="%home%/To_myPartner/error"
      interval="5" defaults="sender.as2_id=myCompany, receiver.as2_id=myPartner"
      sendFilename="true" mimetype="application/EDIFACT"/>

      enables the OpenAS2 software to poll the folder %home%/To_myPartner for messages every five seconds. When a file is detected, it creates the AS2-To: and AS2-From: headers using the defaults attribute and sets the application mime type. The software then uses the details in the partnerships.xml file to send the actual data. In other words, it sets the headers "AS2-From: myCompany" and "AS2-To: myPartner," then checks the partnerships file for a stanza specifying "myCompany-myPartner," and then sends the data to the target in the as2_url of that partnership.
    • The receiver.AS2ReceiverModule and receiver.AS2MDNReceiverModule class names specify which ports to listen on for AS2 messages and asynchronous MDN alerts:
      <module classname="org.openas2.processor.receiver.AS2ReceiverModule" 
          port="10080"
      errordir="%home%\inbox\error" errorformat="sender.as2_id, receiver.as2_id, 
          headers.message-id"/> 
      <module classname="org.openas2.processor.receiver.AS2MDNReceiverModule" 
          port="10081"/>

      These port values are used for the attributes as2_url and as2_mdn_to in the partnerships.xml file.

partnerships.xml

This file defines the relationship between two trading partners. It consists of two main sections:

  • The <partner> stanza assigns various properties to the trading partner and therefore there are two of these nodes. The critical value is the x509_alias property, which is used to choose a specific certificate within the key store. A common mistake is to have a mismatch between this value and the certificates in the key store. An example line is: <partner name="myCompany" as2_id="myCompany" x509_alias="myCompany" email="myCompany@myCompany.com"/>
  • The <partnership> stanza is used to determine where to send documents that are being traded. There will be two of these nodes to trade to a partner and from a partner. The two significant attributes are as2_url and as2_mdn_to. Both are in the format of a URI, with the values being the target to send the message to:
    <partnership name="myPartner-myCompany">
    <sender name="myPartner"/>
    <receiver name="myCompany"/>
    <attribute name="protocol" value="as2"/>
    <attribute name="subject" value="From myPartner to myCompany"/>
    <attribute name="as2_url" value="http://localhost:10080"/> 
        <!-- This value is from the myCompany.xml file -->
    <attribute name="as2_mdn_to" value="http://localhost:10081"/> 
        <!-- This value is from the myCompany.xml file -->
    <attribute name="as2_mdn_options" value="signed-receipt-protocol=optional, 
        pkcs7-signature; signed-receipt-micalg=optional, sha1"/>
    <attribute name="encrypt" value="3des"/>
    <attribute name="sign" value="sha1"/>
    </partnership>

myCompany.p12 (or partner.p12)

This SSL key store is just a normal key store used by Java. It contains one self-signed certificate (for myCompany) and a signer certificate (for myPartner).

commands.xml

This file is taken from the OpenAS2 distribution and does not change, so we will not discuss it further.

Part 5. Trading using OpenAS2 and a DataPower XB60

In this part you configure an XB60 to act as myCompany and use OpenAS2 to act as the trading partner myPartner. The model is shown below. There are two scenarios:

  1. An inbound flow: myPartner (OpenAS2) sends a document to myCompany (XB60) and it is delivered to a back-end using FTP. FileZilla server is used as a simple FTP server to accept the document.
  2. An outbound flow: myCompany (XB60) receives a document via HTTP and sends it using AS2 to myPartner (OpenAS2).
Figure 11. Trading scenario with the XB60
Trading scenario with the XB60

Overview of build

  1. Create the myParter configuration for OpenAS2.
  2. Upload the myParter signer certificate to the XB60 and create a crypto object for it.
  3. Create a crypto key on the XB60 for myCompany
  4. Download the myCompany signer certificate from the XB60 to the myPartner folder.
  5. Import the myCompany signer certificate into the myProfile.p12 file in OpenAS2.
  6. Create a myCompany (internal) profile on the XB60 using the generated certificate and an FTP back-end destination.
  7. Create a myPartner (external) profile on the XB60 using the uploaded myPartner signer certificate and an AS2 back-end destination.
  8. Create a B2B gateway for these profiles with an AS2 front-side handler.
  9. Start trading!

1. Create myParter configuration for OpenAS2

You will need the myPartner folder from the zip file installed in OpenAS2. You do not need the myCompany part for OpenAS2 because that will be replaced by the XB60. Edit the partnerships.xml file and replace the value for localhost with the IP address of your XB60. You only need to do this in the <partnership name="myPartner-myCompany"> stanza.

Once you have created the myCompany profile on the XB60, you need to change the myPartner.p12 file. You also need the myPartner.crt signer certificate in the SSL folder of the ZIP file to upload to the XB60.

2. Upload myParter signer certificate to XB60 and create crypto object for it

In the XB60 GUI, navigate to Administration => Miscellaneous => Crypto Tools and click on the Import Crypto Object tab. Click the Upload button and browse to the myPartner.crt file in the unzipped files SSL folder. Once the upload is complete, select it in the "Input File Name" drop down list, enter "myPartnerCert" for the Object Name, and click Import Crypto Object. You will use this object later when you create the myPartner external profile on the XB60.

Make sure that the dates are ignored since you are only using a test rig. Navigate to Objects => Crypto Configuration => Crypto Certificates and click on myPartnerCert. Edit the panel and set Ignore Expiration Dates to On and then click Apply. Save your configuration:

Figure 12. Import the myPartner certificate
Import the myPartner certificate

3. Create a Crypto-key on the XB60 for myCompany

In the XB60 GUI, navigate to Administration => Miscellaneous => Crypto Tools and generate a certificate for myCompany using the password passw0rd, as shown below. The "State or Province," "Locality," and "Organization" do not matter. Enter your values and click Generate Key:

Figure 13. Creating the myCompany crypto key
Creating the myCompany crypto key

4. Download myCompany signer certificate from XB60 to myPartner folder

Once you have created the crypto key, you will find the following files in the temporary:/// folder: myCompany-privkey.pem, myCompany-sscert.pem, and myCompany.csr. Download the myCompany-sscert.pem file to your OpenAS2 myPartner folder.

5. Import myCompany signer certificate into myProfile.p12 file in OpenAS2

On the OpenAS2 side, you now have a certificate file called myPartner.p12 with the wrong myCompany certificate in it. Replace it with the one downloaded from the XB60. Start the OpenAS2 software in the myPartner folder and issue the following commands: (in bold):

Figure 14. Import myCompany certificate
Staring OpenAS2 with file myPartner.xml
OpenAS2 v0.9
Starting Server...
Loading configuration...
Registering Session to Command Processor...
Starting Active Modules...
OpenAS2 Started
07/12/10 15:15:51 OpenAS2Server: - OpenAS2 Started -
Loading Command Processor...[Thread[Thread-2,5,main], Thread[Thread-3,5,main]]
Loading Command Processor...[Thread[Thread-2,5,main], Thread[Thread-3,5,main]]

#>cert list
OK:
myPartner
myCompany

#>cert delete myCompany
OK:
deleted myCompany

#>cert import myCompany myCompany-sscert.pem
OK:
Certificate(s) imported successfully
...
(output truncated for brevity)
...
#>cert list
OK:
myPartner
myCompany

#>exit

6. Create myCompany (internal) profile on the XB60 using the generated certificate and an FTP back-end destination

  1. In the XB60 GUI, click B2B Partner Profile and create an internal profile called myCompany. In the Main tab, enter the Partner Business IDs:
    Figure 15. myCompany Internal Profile Main tab
    myCompany Internal Profile main tab
  2. On the AS Settings tab, create "Inbound Decryption Identification Credentials" and "Signing Identification Credentials" by clicking + and using the key you generated earlier:
    Figure 16. myCompany AS Settings tab
    myCompany Internal Profile AS Settings tab
  3. On the Destinations tab, you need to create a back-end to the FTP server of your choice. Since this is only a test scenario, you can specify the filename to save the document. In the real world you would expand Enable Advanced AS3/FTP Settings and click Generate unique filename on trailing slash, provided your FTP server supports the STOU command:
    Figure 17. myCompany Destinations tab
    myCompany Destinations tab
  4. After you click Apply within the tab, you will see the following summary:
    Figure 18. myCompany Destinations tab complete
    myCompany Destinations tab complete
  5. Click Apply at the top of the page to create your internal profile and save your changes.

7. Create a myPartner (external) profile on the XB60 using the uploaded myPartner signer certificate and an AS2 back-end Destination

  1. In the XB60 GUI, click Partner Profile and create an external profile called myPartner. In the Main tab, enter the Partner Business IDs:
    Figure 19. myPartner External Profile Main tab
    myPartner External Profile Main tab
  2. On the AS Settings tab, create "Inbound Security Validation Credentials" by clicking + and using the key you created earlier from the uploaded file:
    Figure 20. myPartner AS Settings tab
    myPartner Internal Profile AS Settings tab
  3. On the Destinations tab, enter the values for the AS2 listener in the OpenAS2 configuration:
    Figure 21. myPartner Destinations tab
    myPartner Destinations tab

    Click to see larger image

    Figure 21. myPartner Destinations tab

    myPartner Destinations tab
  4. After you click Apply within the panel, you will see the following summary:
    Figure 22. myPartner Destinations tab complete
    myPartner Destinations tab complete
  5. Click Apply at the top of the page to create the external profile and save your changes.

8. Create a B2B gateway for these profiles with an AS2 front-side handler

Create a new B2B gateway between the two trading partners:

  1. Attach the two previously created partner profiles (myCompany and myPartner).
  2. Add an AS2 front-side handler and an HTTP front-side handler:
    Figure 23. B2B Gateway Main tab
    B2B Gateway Main tab
  3. On the Archive tab, select Purge Only:
    Figure 24. B2B Gateway Archive tab
    B2B Gateway Archive tab

9. Start trading!

Running Scenario 1

To run scenario 1 and send a document to the XB60, start the OpenAS2 software in the myPartner folder and then drop the inbound.EDIFACT document into the to_myCompany folder:

Figure 25. Trading documents with the XB60
Staring OpenAS2 with file myPartner.xml
OpenAS2 v0.9
Starting Server...
Loading configuration...
Registering Session to Command Processor...
Starting Active Modules...
OpenAS2 Started
07/13/10 10:47:44 OpenAS2Server: - OpenAS2 Started -
Loading Command Processor...[Thread[Thread-2,5,main], Thread[Thread-3,5,main]]
Loading Command Processor...[Thread[Thread-2,5,main], Thread[Thread-3,5,main]]

07/13/10 10:47:49 DirectoryPollingModule: processing C:\OpenAS2\myPartner\
    To_myCompany\inbound.EDIFACT
07/13/10 10:47:49 DirectoryPollingModule: file assigned to message C:\OpenAS2\myPartner\
    To_myCompany\inbound.EDIFACT 
    [<OPENAS2-13072010104749+0100-7148@myPartner_myCompany>]
07/13/10 10:47:49 AS2SenderModule: message submitted 
    [<OPENAS2-13072010104749+0100-7148@myPartner_myCompany>]
07/13/10 10:47:50 AS2SenderModule: signed data 
    [<OPENAS2-13072010104749+0100-7148@myPartner_myCompany>]
07/13/10 10:47:50 AS2SenderModule: encrypted data 
    [<OPENAS2-13072010104749+0100-7148@myPartner_myCompany>]
07/13/10 10:47:50 AS2SenderModule: connecting to http://9.42.126.20:10080 
    [<OPENAS2-13072010104749+0100-7148@myPartner_myCompany>]
07/13/10 10:47:50 AS2SenderModule: transferred 2727 bytes in 0.46 seconds at 57. 915 KBps
    [<OPENAS2-13072010104749+0100-7148@myPartner_myCompany>]
07/13/10 10:47:54 AS2SenderModule: received MDN 
    [automatic-action/MDN-sent-automatically; processed] 
    [<OPENAS2-13072010104749+0100-7148@myPartner_myCompany>]
07/13/10 10:47:54 AS2SenderModule: mic is matched, mic: nrpe5qz/n4GKdl+Cl+hgrrImyA4=, 
    sha1 [<OPENAS2-13072010104749+0100-7148@myPartner_myCompany>]
07/13/10 10:47:54 AS2SenderModule: message sent 
    [<OPENAS2-13072010104749+0100-7148@myPartner_myCompany>]
07/13/10 10:47:54 DirectoryPollingModule: deleted C:\OpenAS2\myPartner\
    To_myCompany\inbound.EDIFACT 
    [<OPENAS2-13072010104749+0100-7148@myPartner_myCompany>]

In this run, you can see that the OpenAS2 poller has found the inbound.EDIFACT document in the To_myCompany folder and a message id to it. After signing and encrypting the data, it then connects to the XB60 (connecting to http://9.42.126.20:10080), transfers the file, and receives a MDN back. The software checks whether the MDN is valid, agrees that the message has been sent and received, and deletes it from the To_myCompany folder. The file is then placed on the FTP server as myFile.txt.

The trade in the B2B transaction viewer: as you can see, the message arrived using the URL as2://9.41.126.20:10080 and was sent to the back-end on ftp://9.164.169.14/MyFile.txt and a positive MDN was sent:

Figure 26. B2B Transaction Viewer
B2B Transaction Viewer

Running Scenario 2

To send a document to the XB60 and then enable the XB60 to send it to MyPartner (outbound flow) requires the curl program. Use the following command:

Figure 27. Scenario 2: Outbound flow from myCompany to myPartner
curl --data-binary @outbound.EDIFACT --header "AS2-To: myPartner" 
    --header "AS2-From: myCompany" http://9.42.126.20:30080

There is no output from this curl command. In the myPartner window, you should see a dialogue similar to the one below (important parts are highlighted). The transmitted document will appear in the inbox folder for the OpenAS2 partner:

Figure 28. Scenario 2 as received in OpenAS2 for myPartner
07/15/10 15:26:08 AS2ReceiverHandler: incoming connection 9.42.126.20 26319
07/15/10 15:26:08 AS2ReceiverHandler: received 3847 bytes 
    in 0.172 seconds at 21.862 KBps 9.42.126.20 26319 
    [<afdf926b-dd46-4a06-90a8-244e58a84d6a@9.42.126.20>]
07/15/10 15:26:08 AS2ReceiverHandler: decrypting 
    [<afdf926b-dd46-4a06-90a8-244e58a84d6a@9.42.126.20>]
07/15/10 15:26:08 AS2ReceiverHandler: verifying signature 
    [<afdf926b-dd46-4a06-90a8-244e58a84d6a@9.42.126.20>]
07/15/10 15:26:08 MessageFileModule: stored message to C:\OpenAS2\myPartner\inbox\
    myCompany-myPartner-_afdf926b-dd46-4a06-90a8-244e58a84d6a@9.42.126.20_ 
    [<afdf926b-dd46-4a06-90a8-244e58a84d6a@9.42.126.20>]
07/15/10 15:26:08 MessageFileModule: stored headers to C:\OpenAS2\myPartner\inbox\
    msgheaders\2010\07\myCompany-myPartner-_afdf926b-dd46-4a06-90a8-244e58a84d6a
    @9.42.126.20_ [<afdf926b-dd46-4a06-90a8-244e58a84d6a@9.42.126.20>]
07/15/10 15:26:09 AS2ReceiverHandler: sent MDN 
    [automatic-action/MDN-sent-automatically; processed] 9.42.126.20 26319 
    [<afdf926b-dd46-4a06-90a8-244e58a84d6a@9.42.126.20>]

Here is the Transaction Viewer record of this transaction. The document was received on http://9.42.126.20:30080 and transmitted to as2://9.164.169.14:20080, and a positive MDN was received:

Figure 29. B2B Transaction Log Viewer for this transaction
B2B Transaction Log Viewer for this transaction

Conclusion

You have configured OpenAS2 as a reference model that can be easily changed to suit different business partners, then configured a WebSphere DataPower B2B Appliance XB60 to trade documents with OpenAS2 using an inbound and an outbound flow. You can now use OpenAS2 as a test harness for DataPower XB60 Appliances.


Download

DescriptionNameSize
Code sampledownload.zip37 KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=606146
ArticleTitle=Trading B2B documents using OpenAS2 with the WebSphere DataPower B2B Appliance XB60
publish-date=01052011