A Beginner’s Guide To Figuring Out AS2 Message With AS2 Gateway

AS2, despite being the most popular secure B2B communication protocol, is fairly complicated for a beginner, regardless of how mature he may be in the actual business domain. Not to mention the various operational caveats of maintaining an in-house AS2 server.

That is exactly why we built AS2 Gateway, making it super-easy for even a five-year-old to send AS2 messages to any partner in the other corner of the world.

Hmm...is it actually that easy?

(Are you kidding me? Partners, stations, certificates, encryption certificates, sign certificates, cert chains, async MDN, signed MDN... sounds like a foreign language to me! Where am I even supposed to start?)

Relax. Let's go one step at a time.

Vocabulary first.

AS2 is all about sending and receiving messages (documents; POs, invoices, shipments, you name it) securely, between "partners" (yup, business partners). The format or content of the messages (EDI, X12, ebXML, heck, even plaintext, images, or videos) doesn't matter; as long as it's a file, AS2 can deliver it and produce a receipt (MDN) as well (so the sender can be sure that the recipient got it, securely and untampered).

(So, we have partners. But what about me? Am I a partner, too?)

Yes, you are, from the viewpoint of other partners, but we love you and want you to stand out from the crowd, so in AS2G, you are a station, not a plain old partner. You could have multiple stations (and, hence, multiple identities) for trading with different partners. Messages received from partners to your different "identities" would appear under the corresponding stations, just like having multiple mail accounts configured on the same browser.

(Alright, so I'm a station. How do I send a message to a partner?)

Well, you just:

• Click the New Message button (rocket) on any page, 
• Pick the intended partner
• Pick your station
• Key in a message subject
• Upload or drag-n-drop the files
• Click "Send."

Just like in the mail, except you don't have to type a message body, but you do have to select your own identity (station); in the case of mail, you already did the latter (kind of) when you picked your mail account.

That is if you have already set up your partner.

(Aha, so that's the catch! How do I set up a partner?)

Well, for that, we need to go back to the vocabulary lesson — or, more precisely, dive a bit into the world of AS2.

As you may already know, AS2 is all about security and reliability in document transfer. To achieve this, an AS2 software has to perform quite a bit on your behalf:

• For outgoing messages: encrypting, signing, and compressing the content
• For received messages: decrypting, decompressing, and signature verification, generating (and optionally signing) the receipt if one has been requested

While AS2G is already a champion in all this stuff, it still needs to know the expectations of your partner (the "partner configuration") in order to perform them. That is why you need to head over to the partner's page (ensure you are logged in before clicking the URL), click the "New Partner" button at the top, and carefully fill up the resulting form.

(Huh, you make it sound like it's a piece of cake! If I knew how to fill in that form, why would I be reading your article right now?)

Calm down, folks, almost there. Let's go field-by-field. Except for the partner name, type, and description, everything else in the form should be provided by your partner, so it basically boils down to bothering your partner until he gives up all the pieces of the puzzle to fill in the blanks in the form.

• The name is, as you have guessed, the name you would like to call your partner (just for display and auditing purposes).
• Partner Type is usually Production unless you specifically want to do a kind of "test bed" configuration; if you pick Test, you would have to make further changes when you are ready to go for production (for actual business messages), so it's better to stick to Production.
• AS2 Identifier is an AS2 protocol-level magic word that uniquely identifies your partner. Your partner should provide this to you during the setting-up stages, just like you should send your AS2 ID to him/her; chill out, it's just a piece of text and maybe digits (alphanumeric, in tech jargon) — you only have to ensure that no other partners of your partner are using the same token, because otherwise, your partner may mix up the messages sent by you, with those from other partners.
• The description is, again, just a blurb of text for your convenience in picking your partners apart.

Okay, that was easy enough. Now, the geeky stuff.

• The URI is the HTTP/S address at which your partner is accepting incoming AS2 messages. (If this happens to be HTTPS (i.e., begins with https://), you have a bit more work coming up later in the Advanced Options section)
• An encryption certificate is a file (containing a "key" — a public key, to be exact) provided by your partner, which you can use to "unlock" (decrypt) messages received from him/her. Before sending, your partner will "lock" his/her messages with his/her own private key, and they can only be "unlocked" by the above public key. Since the latter can only decrypt messages encrypted by the former, it ensures that the message did actually originate from your partner and guarantees that no evil force would be able to make any sense of the message while it is in transit (since it is "locked" (encrypted)).
• Using a different certificate as a signed certificate is a bit of an advanced option, which allows your partner to use a different "key" (file) to generate a "signature" of the message content (which is also sent to you, along with the message, for verification purposes). If your partner does not provide this, he/she would probably be using the same certificate (let's call it "cert") for encryption and signing; if he/she does provide one, just upload it here. Either way, not much to worry about!
• Sign/encrypt chain certificates are for establishing trust to indicate that the certs provided by your partner actually do belong to that partner (otherwise, a third party could impersonate your partner and send you their certs and details and capture all your messages that you are sending to your partner). If you don't get it, don't worry; if your partner provides these files, just upload them here!
• Message subject, again, is a down-to-earth field that specifies a default subject for messages you send out to this partner (so you don't have to tire your fingers typing it every time).

In some cases, you may be able to get away with the above lot; however, if your partner mentions anything about:

• Encryption algorithm,
• Signing or digest algorithm,
• Sign or digest encryption,
• Compression,
• ASYNC MDN or signed MDN

It may be time to open up that Advanced Options section as well.

Here, we see four main "categories" of options (although there is no visual demarcation), the first being encryption:

• Encrypt messages indicate whether your partner expects you to "lock" (encrypt) messages that you are sending out to him/her, just like the ones he/she is sending to you. This time, you will have to send your own "key" (public cert) to your partner so that he/she can "unlock" your messages; more on that later!
• The encryption algorithm is the locking "mechanism" that you (AS2G, to be exact) will be used for messages being sent out to your partner — as requested by your partner, of course.

Next comes signing:

• Sign messages, similarly, indicate whether your partner expects a "signature" (a verifiable, summarized blurb representing the payload) along with each of your messages.
• The sign digest algorithm should be set to your partner's preferred mechanism for producing the abovementioned "signature blurb."
• The sign encrypt algorithm is the locking mechanism that your partner expects you to use upon the abovementioned signature (as opposed to the payload that was mentioned previously). With this, both your message and its signature would be in encrypted form during transit.

And compression:

• Compress the messages before signing should be enabled only if your partner likes to see the incoming message in compressed form (primarily to save network overhead and speed up the transfer).
• Compress the messages after signing is similar to above but applies to both the message (which may already have been compressed!) and its signature combined.

And, finally (phew!), MDN:

• Request MDN decides if you should demand your partner to send back a "receipt" (disposition notification) for every message that you send. The MDN mechanism in AS2 is cleverly crafted such that being able to receive and process an MDN guarantees that the message exchange was successful.
• Request asynchronous MDN, if you have enabled the above option, indicates that your partner should send back the MDN in a separate channel (i.e., you send your message in one path (HTTP request), to which the partner simply acknowledges; later on, your partner generates and sends the MDN back to you in a newly initiated path (new HTTP request; to which you send another acknowledgment).
• Request digitally signed MDN demands your partner to send a signature along with the MDN, just like you (might have) signed the message itself when sending it to him/her.

To clarify things a bit, let's have a look at an example configuration of a trading partner:

• Called My Awesome Partner
• With AS2 ID AWSMPTNR,
• Who accepts messages at the URL http://as2.acme.com/as2/inbound

Where the messages need to be:

• Compressed right at the beginning (before signing/encryption),
• Encrypted with AES-256-CBC using the AWSMPTNR-encrypt.pem cert,
• Signed with SHA-256 using the same cert,
• The signature itself is encrypted again, using RSA and
• Compressed again (after signing and encryption),

And you wish the partner to:

Applying the above barricade of rules, our partner would appear as follows:

Here, we have requested our awesome partner to reply with a signed, async MDN (receipt) for every message that we send him.

If you assume, for a moment, that AWSMPTNR later happens to need to use an HTTPS URL for receiving messages:

The top (HTTPS-related) portion of your Advanced Options section may look like this:

You don't trust this third-party guy who signed your partner's HTTPS cert, but the third party has its own cert signed (verified) by another CA that you do trust — which forms a trust chain wherein you trust the third party's cert because it is signed by a known CA, and in turn, you trust your partner's cert because it has been signed by someone that you do trust now.

Trust chains. Now, how sick is that?

Going a bit further, what would you see if your partner starts using a different sign certificate AWSMPTNR-sign.pem, verified by a third party, verified by another third (fourth!) party, verified by another (fifth!) party, where you (luckily) trust the last one?

In case you lost it entirely, those two certs uploaded under Sign/Encrypt Chain Certificates are the "third" and "fourth" parties, which helps AS2G build the trust chain from the top-level trusted CA all the way down to your partner's sign cert.

If the above stuff seems totally foreign to you (and rightly so!), feel free to contact the team to get things in order.

Phew, finally, we have our partner in all his glory, ready to roll.

With me so far? 

If not, just take a deep breath and read through the stuff again, slowly and carefully (maybe skipping the techy innards if you feel better that way); it will eventually make sense.

Though we have our partner, we don't have a station yet. So, let's go ahead and create one.

Head over to the station page and click the New Station button.

You'll end up in another form, just like the partner configuration thing, but much simpler.

Here, you can define how your partners should send messages to you. This includes:

• Name: again, just a name for your convenience.
• AS2 identifier: a unique identifier for yourself, just like in the case of a partner, kind of like your own NIC or Social Security Number.
• Email: the email address you would like to associate with this station just for email notifications of incoming messages.
• Enable email notifications: by default, AS2G will notify you via email as soon as your station receives a new message from one of your partners; you can disable this feature using this switch if it becomes too annoying.
• Description: again, just a blurb of text for your convenience

Now begins the (thankfully, much shorter) list of geeky stuff, primarily for defining your station's keystore (where AS2G would be storing all the keys and certificates that allow you to communicate securely with your partners, similar to what you saw in the partner configurations):

1. Generate a new keystore on the house! (whose fragments you can later share with your partner) — obviously, it's the easiest option!
2. Upload an existing keystore from your computer handy if you are migrating stuff from a different station (or an entirely different AS2 platform) but don't want to bother your partner; i.e., your partner will see you in exactly the same way as he/she did before, although you are now using a new station! (Note, however, that this won't work if your new station's name differs from that of the old station)
3. Select one that has already been uploaded and is available in your certificate store right now.

• Common name: This is the only mandatory field; put in either your own name or maybe your station's name.
• Organization unit and organization: kinda like your department and the parent organization name
• City, state, country: address (you get it)

The last two options are straightforward (upload a file or pick one from a list), so let's have a closer look at the first one (which you would be picking anyways). You would have to fill in some details of the newly generated keypair for your brand new keystore, which is standard to the X.509 format.

• Key length: the size of the key; generally, the bigger the key, the more secure your encrypted message is — and the slower the encryption/decryption process would be. Generally, 1024 or 2048 would suffice.
• Keystore password: a password for the new keystore so you can inspect it later on if required
• Certificate password: a password for your key itself (private keys need to be stored with great care)

Now the geeky stuff (again!):

Now, you have configured your side of the bargain, but your partner also needs to configure a "partner" on his/her own system that corresponds to you (since you, after all, are his/her business partner). Hence, you need to somehow pass your details through to him/her so that his/her partner configuration is compatible with your station configuration.

Now, how do you do that?

Lucky for you, AS2G can do it for you!

(Really? Finally, something cool.)

Once you open your brand new station from the Stations page, enter the email address of your partner in the Share this configuration text field, and click Send. Your partner will receive your station configuration via email and can configure your partner profile on his side accordingly.

Now follows another wait (hopefully not too long!) until your partner confirms that he/she has added your info to his/her AS2 system, just like we did for him/her.

Now, for the first time in history, you are ready to send your first message!

Go ahead, click that rocket icon, pick your partner, select your files, and click Send!

From this point onwards, AS2G is as simple as that!

For a brief time, you may see your message in a "queued" (pending) state:

Usually, however, AS2G will pick it up and send it out within seconds:

In the unlikely event that your message decides to play a trick on you and fails to be sent out, you will see under the "Failed" tab of the message view, along with the failure cause:

In that case, you can open up the failed message and use the various controls to navigate through its metadata and failure details.

Oh, and did I mention that you can learn more details and more importantly, about how to avoid failure in the future?

Now that you know the basics, things are going to get easier, way more useful, and way more fun!

Got a new partner? Add a new one on the Partners page, share your station details with him/her, and pick the new partner from the Partner drop-down when sending your messages!

Partner not happy with your station config? Just create a new station with different, more partner-friendly configs, share it with your partner, and select the new station from the Station drop-down when sending it to that partner!

See all your inbound and outbound messages in your message view, along with corresponding acknowledgments (MDNs), just like your mailbox.

Whenever you need to analyze a message in depth or troubleshoot a failure, just level headers, error metadata, and retry information. Or, if you feel adventurous, dive down into the details yourself with the above-mentioned detailed message view, including transport.

Thank you!