Home / 

AS2

Updated December 16, 2022

By default, Stedi AS2 is not available in your account yet. If you would like to try it out, please contact us and we’ll enable it for you.

For now, you have to access Stedi AS2 using the Stedi CLI or the Stedi AS2 SDK.

Stedi AS2 is not available in your account by default. Please contact us and we’ll enable it for you.
  • Error messages can be a bit cryptic. If you feel stuck at any time, contact us and we’ll give you hands-on assistance.

Introduction to AS2

The main feature of the AS2 protocol is to guarantee that messages you receive are from who you think they are. AS2 uses digital certificates to accomplish this. Each trading partner will need two certificates.

  • A certificate for signing allows your trading partner to verify that you sent the message.
  • A certificate for encryption ensures that the message you sent hasn’t been tampered with.

Setting up AS2 is mostly a matter of getting the certificates right. A certificate consists of two parts.

  • A private key, that you should keep to yourself.
  • A public key, that you share with your trading partner.

In a moment, we’ll take a look at how you create a certificate. Once that’s done, you need to send your public key to your trading partner and your trading partner needs to send you their public key. The AS2 protocol does not provide a way to do this. Since you’re already in direct contact with your trading partner, you should be able to agree on a way to exchange keys safely.

Prerequisites

  • The Stedi CLI to send commands to Stedi AS2.
  • An API key.
  • A bucket for storing the files you receive.

Install Stedi CLI

To install the Stedi CLI, run the following command.

npm install -g @stedi/cli

API key

You can create your own Stedi API key if you don’t have one yet. We recommend that you create a local .stedirc file that looks similar to this:
{
    "api-key": "<YOUR_API_KEY_HERE>"
}
Just make sure you never commit .stedirc to source control.
You can also pass the API key to the CLI using the -a option, but that becomes tedious pretty fast. This rest of this page assumes you have the environment variable set.

Bucket

The files you receive need to be stored somewhere. Stedi AS2 uses Stedi Buckets for this. You can use any bucket in your account for this. Typically, you’ll create a specific bucket for all your AS2 needs. Here’s how you can do that with the CLI. Note that bucket names need to be globally unique, so you’ll need to change the name.
stedi buckets create-bucket --bucket-name <YOUR_BUCKET_NAME_HERE>

Certificates

As mentioned before, you’ll need two certificates: one for signing and one for encryption. We also recommend that you create separate certificates for each of your trading partners. Certificates expire and when that happens, you need to coordinate with your trading partner to switch to the new certificates. Doing that for all your trading partners at once is a hassle you don’t need, hence the separate certificates for each trading partner.

Creating certificates

Let’s assume your trading partner is called Minicorp and create the certificates you need. We’ll start with the certificate you use for signing messages.

openssl req -x509 -newkey rsa:4096 -keyout minicorp-signing-private.pem -out minicorp-signing-public.pem -sha256 -days 365 -nodes

You’ll be asked for information that identifies your organization. You don’t need to fill out all fields, but you should specify what you can.

This will create two files: minicorp-signing-private.pem and minicorp-signing-public.pem. You’re free to name these files anything you want, but the naming convention used here makes it clear what each one contains.

Create the certificate for encryption is the same except for the file names.

openssl req -x509 -newkey rsa:4096 -keyout minicorp-encryption-private.pem -out minicorp-encryption-public.pem -sha256 -days 365 -nodes

Importing certificates

You just created the certificates on your local system, but Stedi AS2 doesn’t know about them yet. You’ll need to import them. You tell Stedi AS2 what the certificate is used for using the --usage option. For the signing certificate:
stedi as2 import-certificate --name me-to-minicorp-signing --description "" --usage SIGNING --private-key file://minicorp-signing-private.pem --certificate file://minicorp-signing-public.pem

For the encryption certificate:

stedi as2 import-certificate --name me-to-minicorp-encryption --description "" --usage ENCRYPTION --private-key file://minicorp-encryption-private.pem --certificate file://minicorp-encryption-public.pem

The description is required, but at the moment you can’t use spaces in your description. Since the name is already descriptive of what the certificate is for, you can leave the description empty.

That’s your own certificates taken care of, but you need the certificates of your trading partner as well, otherwise you can’t verify their signature or decrypt their messages. Stedi AS2 expects certificates in PEM format, but sometimes a trading partner will send you their certificate in binary format. In that case, you should convert it from binary to PEM.

openssl x509 -inform der -in certificate.cer  -out certificate.pem
Put the certificates in files called from-minicorp-signing.pem and from-minicorp-encryption.pem. Your trading partner will only send you their public keys, so no need to specify that in the file name. Importing the certificates is similar to what you did before, just without specifying a private key.
stedi as2 import-certificate --name minicorp-to-me-signing --usage SIGNING --description "" --certificate file://from-minicorp-signing.pem
stedi as2 import-certificate --name minicorp-to-me-encryption --usage ENCRYPTION --description "" --certificate file://from-minicorp-encryption.pem

Profiles

Profiles combine a party’s signing certificate and encryption certificate with an AS2 ID. Each organization has their own AS2 ID. You can pick one for yourself, as long as you make sure no one else in the world is using it. There’s no central registry or anything like that. Alas.

There are two types of profiles.

  • A local profile contains your own certificates and AS2 ID.
  • A partner profile contains the certificates and AS2 ID of one of your trading partners.

When you create a profile, you’ll need to pass the IDs of the certificates you created earlier. Those IDs were shown to you at the time, but you can also retrieve them using the CLI.

stedi as2 list-certificates
stedi as2 describe-certificate --name me-to-minicorp-signing

You can create a local profile using the following command, after you replaced all the IDs.

stedi as2 create-profile --name me-to-minicorp --profile-type LOCAL --as2-id my-as2-id --certificate-ids cert-0a690995f51d4e4d8,cert-713f493b02b044308

The command to create a partner profile is just like the previous one. Just make sure you use the certificate IDs that have the public keys of your trading partner. You need to ask your trading partner for their AS2 ID.

stedi as2 create-profile --name minicorp-to-me --profile-type PARTNER --as2-id minicorp --certificate-ids cert-ee767b7f5a444e9ea,cert-ff65cfe14f5743d79

Receiving messages

If you want to receive AS2 messages from you trading partner, you’ll need a server and an agreement.

Server

Creating a server is straightforward, but it can take a couple of minutes to complete. I suggest you go get a cup of tea, but I won’t hold it against you if you prefer coffee.

stedi as2 create-server --name my-stedi-as2-server

You don’t have to create a separate server for each trading partner. You can use one server for all of them.

Agreement

An agreement binds all the information necessary for receiving AS2 messages. It combines the following.

  • A local profile (containing your certificates and your AS2 ID).
  • A partner profile (containing your trading partner’s certificated and their AS2 ID).
  • Your server.
  • The bucket and directory where incoming files will be stored.

You’ll need the IDs of the profiles you created earlier.

stedi as2 list-profiles
stedi as2 describe-profile --name me-to-minicorp
stedi as2 describe-profile --name minicorp-to-me

Same thing for the server ID.

stedi as2 list-servers
stedi as2 describe-server --name my-stedi-as2-server
You specify the bucket and a directory in that bucket with a single path. We recommend using a directory specific to your trading partner. If your bucket was called unique-as2-bucket, the path would look like /unique-as2-bucket/minicorp.

Put all of that together and creating an agreement looks like this:

stedi as2 create-agreement --name minicorp --base-directory "/unique-as2-bucket/minicorp" --description "" --local-profile-id p-1b4b270132c14657b --partner-profile-id p-ae344c247bb647318 --server-id s-d1bfcba6f26349968 --status ACTIVE

Server URL

You’re now ready to receive AS2 messages from your trading partner. All they need is your public keys (don’t send them your private keys!), your AS2 ID, and the server URL.

Oh right, the server URL. Try this.

stedi as2 describe-server --name my-stedi-as2-server
The field serverUrl is almost what you need. You just need to put http:// in front of it and :5080 after. It’ll look something like http://s-d1bfcba6f26349968.server.transfer.us-east-1.amazonaws.com:5080.

Sending messages

If you want to send messages to your trading partner, you’ll need a connector. You don’t need a server or an agreement, unless you also want to receive messages.

Connector

The connector combines all information that’s necessary to send messages to a trading partner. It contains:

  • A local profile (containing your certificates and your AS2 ID), used to sign and encrypt your messages.
  • A partner profile (containing your trading partner’s certificated and their AS2 ID), used to verify and decrypt your trading partner’s responses.
  • The URL of your trading partner’s AS2 URL.

You’ll need the IDs of the profiles you created earlier.

stedi as2 list-profiles
stedi as2 describe-profile --name me-to-minicorp
stedi as2 describe-profile --name minicorp-to-me

You’ll need to obtain the server URL from your trading partner.

Stedi AS2 doesn’t support URLs that start with https://; they must start with http://. We’re working on it.
stedi as2 create-connector --name minicorp-connector --url "http://as2.minicorp.com:5080" --local-profile-id p-1b4b270132c14657b --partner-profile-id p-ae344c247bb647318 --mdn-response SYNC

File transfer

You are now ready to send files to your trading partner. You can send any file that’s in any of your buckets. You do need the ID of the connector you just created.

stedi as2 list-connectors
stedi as2 describe-connector --name minicorp-connector

Fill in the correct values in the following command and you’re good to go.

stedi as2 start-file-transfer --connector-id c-314029f30995489aa --send-file-paths "/this-bucket-of-mine/outbox/minicorp/sample.edi"

Clean up

If you decide you don’t like your trading partner anymore, you can get rid of all AS2 resources related to them.

stedi as2 delete-connector --name minicorp-connector
stedi as2 delete-agreement --name minicorp
stedi as2 delete-profile --name minicorp-to-me
stedi as2 delete-profile --name me-to-minicorp
stedi as2 delete-certificate --name from-minicorp-encryption
stedi as2 delete-certificate --name from-minicorp-signing
stedi as2 delete-certificate --name minicorp-encryption-private
stedi as2 delete-certificate --name minicorp-encryption-public
stedi as2 delete-certificate --name minicorp-signing-private
stedi as2 delete-certificate --name minicorp-signing-public

You might want to keep your server for other trading partners, but if you’re sure you’re done with it, you can delete that as well.

stedi as2 delete-server --name my-stedi-as2-server
Introduction to AS2PrerequisitesCertificatesProfilesReceiving messagesSending messagesClean up