Hola, AS2! (a.k.a. Your First AS2 Message, with AS2Gateway)

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 AS2Gateway, making it super-easy for even a five-year-old to send AS2 messages to any partner in the other corner of the world... or so we boast.

Hmm... wait... is it actually that easy?

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

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

(Okay.)

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 there we have partners. But how 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. Whatever. I don't care. 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, and

  

• click Send.

Just like in mail, except that you don't have to type a message body, but do have to select your own identity (station); in case of mail, the latter you already did (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 gotta 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, AS2 softwares have to perform quite a bit on behalf of you:

• for outgoing messages: encrypting and 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 partners 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 sound like it's a piece of cake! If I knew how to fill in that form, why the heck would I be reading your article right now?!)

Calm down folks, almost there. Let's go field-by-field. Except 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 pieces of the puzzle to fill the blanks in the form.

• 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 kind of a "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.
• 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.

• 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!)
• 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. Before sending, your partner will "lock" his messages with his 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)).
• Use different certificate as sign 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 would probably be using the same certificate (let's call it "cert", okay?) for encryption and signing; if he 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 (believe you) are sending to your partner!) If you don't get it, not to 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 indicates whether your partner expects you to "lock" (encrypt) messages that you are sending out to him; just like the ones he is sending to you. This time, you will have to send your own "key" (public cert) to your partner so that he can "unlock" your messages; more on that later!
• Encryption Algorithm is the locking "mechanism" that you (AS2G, to be exact) will be using for messages being sent out to your partner—as requested by your partner, of course.

Next comes signing:

• Sign Messages, similarly, indicates whether your partner expects a "signature" (a verifiable, summarized blurb representing the payload) along with each of your messages.
• Sign Digest Algorithm should be set to your partner's preferred mechanism for producing the abovementioned "signature blurb".
• 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 acknowledgement).
• 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.

Okay, take a deep breath. Count from one to twenty-five. Whatever. Just keep calm.

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,
• and the signature itself encrypted again, using RSA, and
• compressed again (after signing and encryption),

and you wish the partner to:

• send back a receipt (MDN), which is
• asynchronous and
• signed

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 a HTTPS URL for receiving messages:

• https://as2.acme.com/as2/inbound
• protected by a AWSMPTNR-https.pem HTTPS certificate
• which has been verified by a third-party certification authority (CA) whose chain certificate has also been sent to you,

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

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 Greek (or Chinese, gibberish, whatever) to you (and rightly so!), feel free to consult AdroitLogic for getting things in order; or, if you feel adventurous, go ahead and mess around with the switches and drop-downs your own :) It's highly unlikely that you're going to break anything!

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 would 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.

(I knew it... Another form. How many more of those until I get to actually send a message?)

Just this one, I promise.

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):

• Key Store: here, AS2G allows you to either

1. generate a new keystore, on the house! (whose fragments you can later share with your partner)—obviously 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 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.

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 are standard to the X.509 format (now, now, no need to google it!).

• 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)

Now the geeky stuff (again!):

• 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 you have configured your side of the bargain. But your partner also needs to configure a "partner" on his own system, that corresponds to you (since you, after all, are his business partner). Hence you need to somehow pass your details through to him, so that his 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 has added your info to his AS2 system; just like we did for him. Yup, patience is a virtue.

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 sends it out within seconds:

In the unlikely (Or likely, maybe? After all, this is your first message!) 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 contact the AS2G Team anytime to learn more details, and more importantly, about how to avoid the failure in the future?

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

Got a new partner? Add a new one on the Partners page, share your station details with him, 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 to that partner!

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

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

AS2G has a lot more in store for you; so, my dear folks, it's time to get going!