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.
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.
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:
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.
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:
- Click the button labeled "Partner" (or go to File → Partner).
- Fill out the forms. The rest of this should be fairly obvious, but to go over it:
- AS2 ID
- email address - a contact
- 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.
- Click Ok
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:
Conversely, the messages will be received on:
Copy and run. The main windows on client and server will show their respective progresses.
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.
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.
- Post #3 of the "quick start guide" on the mendelson forums
- Mendelson Project Page
- Web browser interface not working
- Windows linefeed in mec_as2_start/stop.sh scripts
- SSL Problems
- b27 start error on Linux (solved)
- Default password in the Keystore password?
- HTTPS Communications Difficulty
- Message digest mismatch in signature