Overview

AS2 is a wire protocol for transferring files between two organizations. This guide explains how to get the mendelson open source as2 server up and running. The instructions are slanted towards set up on a Debian box, though set up on any *NIX system or Windows should be very similar.

The goal in this guide will be to set up two independant machines, one for test and one for production, and get them talking to one another.

Finally, this guide was developed and tested with mendelson AS2 version 1.1 and Debian 5.0.

Installation

Get the zip file from the Mendelson AS2 sourceforge page. No installation is needed (though an installer is provided for Microsoft Windows boxen), just unpack the files in some location. What I did, was:

  • create a separate user to run the AS2 software (named, cleverly enough, as2user)
  • Unpack the software in a directory in the as2user's home directory.
  • Run the software in a GNU Screen session
  • For the GUI portion, run a lightweight window manager (IceWM was my choice) and a VNC server.

As always, your mileage may vary. Out of the box, the mendelson as2 server is configured to interact with the mendelson test server, and nothing else. The next step is to set up the keys.

Configuring Keys

This process can be done with Portecle, keyman, or the OpenSSL toolchain. The most user-friendly of these is Portecle, which is also the one that Mendelson recommends. Because Portecle is pretty straightforward (and, if you choose one of the other tools, you almost certainly know what you are doing anyway), we will skip the exact sequence of clicks or commands needed for this.

Mendelson AS2 stores its keys in the certificates.p12 file in the root of the install directory. The password for this store is, incidentally, test. The first thing we need to do is recreate the private keys. What we do is delete the keys (or delete the store and create it afresh with new keys with this name) and create new ones. The names of the keys are Key1 and Key2.

After creating the private keys on both machines, we need to export certificates for each, then exchange them. If mendelson AS2 is running, the certificates and keys can always be reloaded by clicking File → reload key store.

Patching the Scripts

Mendelson AS2 comes with DOS Batch files and Bash scripts to launch the AS2 server on Windows and *nix machines, respectively. Not to be degrading or anything, but the bash scripts do not appear to have been well tested. I had to make the following changes to them:

  • Both the mendelson_as2_start.sh and mendelson_as2_stop.sh files used Windows line endings, instead of UNIX. The dos2unix script (available in the Debian and Ubuntu package managers) fixed this problem.
  • Make both of the aforementioned files executable
  • At the top of the mendelson_as2_start.sh file, there is a line setting the CLASSPATH. I had to modify it to CLASSPATH=as2.jar:jetty/start.jar:jetty/lib/servlet-api-2.5-6.1.1.jar

Once the appropriate changes have been made to the start scripts, just run:

./mendelson_as2_start.sh

from the install directory.

Configuring the Local Station

Before the server can receive messages, it must be configured as a local station. By default, a local station will already be set up. The parameters just need to be adapted to match the actual environment. Pretty much, all you will have to change right off the bat is the MDN (URI), which is set to a mendelson domain. While here, you will also need to select the keys you generated above for the local station under the Security tab.

Configuring Partners

After a minute or two, the GUI will pop up. It is here that the AS2 partners must be set up before files can be exchanged. Take the following steps:

  1. Click the button labeled "Partner" (or go to File → Partner).
  2. Fill out the forms. The rest of this should be fairly obvious, but to go over it:
    • Misc
      • Name
      • AS2 ID
      • email address - a contact
      • comments
    • Keys - if you imported the keys above, the certificate for the trading partner should be available from the drop down. Select it or bad things will happen—I promise.
    • MDN - the URI of the recipient.
  3. Click Ok

Sending Messages

This part is easy. Copy a file to the intended recipient’s directory on the server. By default, mendelson is set to poll for new files every 10s (a little inotify support here would rock). In general, from the mendelson install directory, the location will look like:

/messages/ /outbox

Conversely, the messages will be received on:

/messages//inbox

Copy and run. The main windows on client and server will show their respective progresses.

Configuring HTTPS

At this point, if everything has gone according to plan, messages can be exchanged in plain HTTP. In many situations, however, we want to exchange messages over HTTPS for added security. To do this, we must:

  • Configure Mendelson AS2 to use HTTPS
  • Generate new keys for the HTTPS store
  • On the sender, import the certificates for the recipient

This may sound a little confusing, given that we discussed generating keys above. It turns out that Jetty (the HTTP server & client that Mendelson AS2 uses) has its own separate, independent keystore for sending over HTTPS. Moreover, the keys are expired, which is probably just as well because it makes us generate fresh ones.

Under the main Mendelson AS2 directory, there is a directory named jetty/etc containing Jetty’s configuration files. Jetty itself uses jetty.xml and an example configuration for SSL is in jetty-ssl.xml. Copy the following code from jetty-ssl.xml into jetty.xml:


  
    
      8443
      30000
      /etc/keystore
      OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
      OBF:1u2u1wml1z7s1z7a1wnl1u2g
      /etc/keystore
      OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4

You’ll notice that it references the defunct keystore. Create a new keystore, populated with two keys from the following commands:

keytool -genkey -alias Key1 -keypass changeit -keysize 1024 -keystore my.keystore -keyalg RSA -storepass changeit

keytool -genkey -alias Key2 -keypass changeit -keysize 1024 -keystore my.keystore -keyalg RSA -storepass changeit

where my.keystore is the filename of the new keystore and changeit is the password for the store.

For password, keyPassword, and trustPassword, put the values corresponding to those used in the keytool commands.

From the destination, export a certificate and import it into the keystore that was just created.

Conclusion

Once you have the AS2 server up and running, the process of adding real life partners is fairly similar. The only other parting tip I can offer (thanks to the forums) is that if, at any step, something goes wrong the start up script can be patched to provide a lot more debugging information by changing the last line of mendelson_as2_start.sh to read:

java -Xmx192M -Xms92M -classpath $CLASSPATH -Djavax.net.debug=all de.mendelson.comm.as2.AS2

the addition is -Djavax.net.debug=all. As implied this will dump all sorts of goodies to the terminal.

Appendix - Signed MDNs

As of Mendelson AS2 1.1 - build 29, there is a bug that causes verifcation errors with signed MDNs sent by mendelson AS2 to non-mendelson AS2 servers. The solution is to get the b29 source module from CVS (on Sourceforge), change all occurrences of "\n" in the message strings to "\r\n" in MDNText.java, then navigate to de/mendelson/comm/as2/message and run:

javac -classpath /path/to/as2.jar MDNText.java

this will create a new MDNText.class file. Unzip the jar somewhere that will not trample anything, replace the MDNText.class file, and create a new jar. This updated file should solve the problem. At least, it did for me. Your mileage may vary, of course.

Sources