AS2 Introduction

AS2 Security Capabilities

The AS2 protocol permits a variety of security features including digital signatures, encryption, SSL, and MDN receipts. These features, when used in combination, offer the same reliability you would expect from a VAN:

All of these security features are implemented using X.509 certificates. You may, at your option, use certificates verified by a trusted CA (Certificate Authority), or generate your own certificates for use in Internet EDI.

Configuring Certificates

To trade business documents securely, you will need to use digital certificates. The CertMgr component and demo application, included with the package, allow you to manage, import, export, and create certificates.

Certificates come in two basic types: private key certificates and public key certificates. You should use private key certificates for yourself, and obtain public key certificates from your trading partner.

Your Personal Certificates

Before trading business documents you will need to obtain a certificate with a private key. Typically, these are purchased from a Certificate Authority such as Verisign or Thawte. In Internet EDI, it is also common to use self-signed certificates. In either case, such certificates allow you to prove your identity by signing documents, or decrypt documents prepared for you.

Certificates with private keys may be stored in several ways. One common way is to use a file in PKCS12 format (typically with a .pfx or .p12 extension. If you have your certificate stored in a PKCS12 file you can set it as follows:

Setting a Signing Certificate (PFX File, Sender) as2.SigningCert = new nsoftware.IPWorksEDI.Certificate(CertStoreTypes.cstPFXFile, // File type "\\mypfx.pfx", // File name "password", // Password "CN=My Certificate"); // Subject

(Note that the code on the receiver side is analogous.)

You can also store the contents of a PKCS12 file in a byte array. In this case you would set the store type to cstPFXBlob, and set the store to the entire PFX contents.

In Windows, another common way to use certificates is to install them into the operating system. If you double-click on a PKCS12 file, this is exactly what Windows will do.

Certificates imported to the Windows certificate store can be used by the component, but be sure to mark the private key as exportable. If you don't, the private key cannot be used to perform the digital signing.

Setting a Signing Certificate (System Store, Sender) as2.SigningCert = new nsoftware.IPWorksEDI.Certificate(CertStoreTypes.cstUser, // Store type "MY", // Store name "", // Password "CN=My Certificate"); // Subject

Note that Windows has user and machine stores, and you can use certificates from either.

Your Trading Partner's Certificates

You will also need to obtain certificates from your trading partners. These will be in PKCS#7 or Base-64 encoded format, and will contain public keys only. Typically, these certificates will have extensions such as .cer, .crt, or .der.

To load a partner's public key from file, use the following:

Setting an Encryption Certificate (Sender) as2.RecipientCert = new Certificate("\\myPartner.cer");

The RecipientCert, ReceiptSignerCert, and SSLAcceptServerCert properties on the sender side, and the SignerCert property on the receiver side follow this format. Please see Configuring Message Security for information on how to use these properties.

Configuring Message Security

In AS2 message security is always applied at the option of the sender. When you send outgoing messages, you need to configure the AS2Sender control to apply the appropriate message security. On the server side, the appropriate message security will automatically be applied based on the client's request. If you want to enforce message security on the server side, you can determine which security options were used by the client, and reject the request if needed.

Signing

On the sender side, you instruct the component to sign outgoing documents by setting the SigningCertStore and related properties (see "Using Certificates" for details).

Encryption

Encryption is applied by setting the RecipientCert property. That certificate will then be used for encryption. You may also configure the algorithm used with EncryptionAlgorithm. The default of "3DES" is highly recommended; however you may also select "AES", "RC2", "DES", or "" (no encryption).

SSL

You may use SSL (transport-layer encryption) by posting to an HTTPS URL. If your trading partner is using a commercial certificate, no additional configuration is necessary; if your trading partner is using a self-signed certificate, you will need to set SSLAcceptServerCert.

Compression

Outgoing messages may also be compressed by setting CompressionFormat.

Requesting a Receipt

You may request an MDN-based receipt by setting MDNTo. The receipt options are given in MDNOptions, and by default the component will request a signed receipt. If you prefer an unsigned receipt, you may set MDNOptions to an empty string.

You should set ReceiptSignerCert to your partner's signing certificate if it is different than RecipientCert, or if you are not encrypting.

Server-Side Security

On the server side, you always should set your signing and decryption certificate with Certificate, and your trading partner's (signing) certificate with SignerCert. If you use a different certificate for signing and decryption, you will need to set Certificate to your signing certificate after calling ParseRequest.

When you call ProcessRequest (or ParseRequest), the component will determine the message security used, if any. The encryption type will be stored in EncryptionType, and the signature type will be stored in SignatureType. If an MDN was requested, the appropriate parameters will be set in MDNTo, RequestedSigningProtocol, and ReceiptDeliveryOption.

If an MDNReceipt was generated successfully, you can call SendResponse to deliver it to the sender. If not, you could, for example, return an HTTP error code instead of calling SendResponse.

Client-Side Processing

Client-side processing of AS2 messages is easily done with the AS2Sender object. To send messages with AS2, you will need to follow the following steps:

1. Specify the needed AS2 identifiers, i.e., AS2From and AS2To.

2. Specify the appropriate certificates and message security, if needed (see "Configuring Message Security" for more details on how to do this).

3. Set MDNTo, if you would like to receive a receipt. You can request a signed or unsigned receipt; you can also request synchronous or asynchronous delivery. See "Configuring Message Security" and "Synchronous and Asynchronous Receipts" for more details.

4. Set your EDI data, using EDIData and EDIType.

5. Set LogDirectory, if you would like to produce detailed logs.

6. Set the URL and post. If you requested a synchronous receipt, it will automatically be checked for and validated (if you requested an asynchronous receipt, more work will be required on your end).

See the AS2Client Demo for an example.

Server-Side Processing

Server-side processing of AS2 messages is accomplished with the AS2Receiver object. The .NET Edition is designed to interoperate with IIS and ASP.NET. The Java Edition is designed to work with HTTP servlets and a web server such as Apache Tomcat. You may also use the AS2Receiver with your own web server if you prefer, or use it to process signed and/or encrypted AS2 data offline.

To use the receiver in ASP.NET or with servlets, follow the following steps:

1. Set LogDirectory, if you would like to produce detailed logs.

2. Call ReadRequest. This will examine the request headers, validate that the incoming message is a valid message, and determine AS2From and AS2To.

3. Look up the originator in your database, make sure he/she is one of your valid trading partners, and set up the appropriate certificates (see "Using Certificates In AS2").

4. Call ProcessRequest to process the incoming data and generate an MDN receipt.

5. Optionally, catch any exceptions thrown by ProcessRequest. In particular, if there were any problems with the incoming transmission, the component will prepare an MDN with an appropriate error response before throwing an exception. If you want to send this MDN, you will need to handle this exception (otherwise, your application will generate an HTTP error.)

6. Optionally, check the message security used, to make sure it was what you were expecting.

7. Save the EDI data.

8. Invoke SendResponse. This will send either a synchronous or asynchronous MDN (or nothing), depending on what was requested.

See the AS2Server Web Form Demo for an example.

Synchronous and Asynchronous Receipts

When requesting receipts you may request either a synchronous or an asynchronous receipt. A synchronous receipt is always returned in the same HTTP connection as the original request. An asynchronous receipt, however, will be returned via HTTP or e-mail over a separate connection. Processing asynchronous receipts requires more effort, but prevents your HTTP connections from waiting on the server's processing of your data. Requesting asynchronous receipts may be useful if you want to send large documents.

Both synchronous and asynchronous receipts are supported. On the receiver side it requires no effort on your part: the receipt will automatically be returned as requested by the client. On the sender side, requesting asynchronous receipts is a bit more difficult, because you will need to provide a server to process them, and coordinate the sent data to the received receipts.

Please see the Asynch MDN Web Form Demo for more information on receiving asynchronous receipts.