Technical Guide Reference Guide Frequently Asked Questions Tutorials
Show menu

AS2 Protocol for EDI

AS2 Technical Documentation

AS2 Listener

The AS2 listener is used to receive and process AS2 messages. This involves a number of steps such as decryption and signature verification before finally converting the AS2 message to a ConnectMessage.

The following diagram gives an overview of the overall operation and structure of the AS2 listener and how the attribute values affect its execution. The boldface names are attribute names. The next sections will go into more detail about the individual steps.

  1. The AS2 message is received as an HTTP(S) POST request at a predetermined URL. The URL consists of Host:Port/Context Path. By default this is an HTTP connection. If you want an HTTPS connection, you will need to set the Enable TLS/SSL to true and provide a TLS Certificate Alias to a certificate in the Connectplaza keystore.
  2. Check if the message is encrypted. This happens automatically and does not require further configuration of the AS2 listener component.
  3. If the message is encrypted, decrypt it. See the section on decryption for more details.
  4. Check if the message is signed. This happens automatically and does not require further configuration of the AS2 listener component.
  5. If the message is signed, verify the digital signature. See the section on verifying the signature for more details.
  6. Check if a Message Disposition Notification (MDN) is requested. The MDN is a signed receipt that is sent to the sender as proof that the message has been received.
  7. If an MDN is requested, send it.
  8. Finally package the AS2 message into a ConnectMessage and send it down the flow for further processing. See the section on packaging AS2 messages for more details.

Note that for the sake of simplicity AS2 message decompression has been omitted. Some AS2 implementations support compressing and decompressing AS2 messages (see RFC 5402 for more details). This requires the additional steps of checking if the message is compressed and if so decompressing it. These steps might occur before or after signature verification.

A further simplification is the omission of various compatibility logic. This consists of attributes that can force decryption, verification, and decompression or explicitly disable it.

Decrypting AS2 Messages

The following diagram shows how messages are decrypted.

Decrypting AS2 messages only requires a single attribute, i.e., Receiver x509 Alias, which is used to retrieve the receiver’s private key. Consequently, this also requires for this key to be present in the keystore.

Note that it is not necessary to specify the algorithm that has been used by the sender to encrypt the message.

Verifying the Signature of AS2 Messages

The following diagram shows how a message is verified.

 

  1. Check whether a certificate in the body of the message is used to verify the signature or if we use a certificate that is present in the ConnectPlaza truststore. This check is performed by looking at the value of Verify Using Certificate in Body.
  2. Verify the signature using the certificate in the body.
  3. Verify the signature using the certificate in the ConnectPlaza truststore. The public key is looked up using the value of Sender x509 Alias. This requires the public key to be present in the truststore.

Note that it is not necessary to specify the algorithm which has been used by the sender to sign the message.

Packaging AS2 Messages into ConnectMessages

The following diagram shows how an AS2 message is packaged into a ConnectMessage.

  1. First the AS2 message’s payload is extracted. We need to know the character encoding (if applicable) of the message which is specified by the Charset attribute.
  2. The headers specified in the Mapped Request Headers attribute are extracted.
  3. A new ConnectMessagePart is created of a type specified by the MessagePart Content Type. MessageParts are not to be confused with a ConnectMessage. A ConnectMessage consists of one or more MessageParts.
  4. The payload of the MessagePart is set with the payload extracted at step 1.
  5. The headers of the MessagePart are set with the headers extracted at step 2.
  6. A new empty ConnectMessage is created.
  7. The MessagePart is added to the new ConnectMessage using the ID provided by the MessagePart attribute.

AS2 Gateway

The AS2 gateway is used to send AS2 messages and package the reply into a separate MessagePart. This involves a number of steps such as payload extraction, message signing and encryption before finally sending it.

The following diagram gives an overview of the overall operation and structure of the AS2 gateway and how the attribute values affect its execution. The boldface names are attribute names. The next sections will go into more detail about the individual steps.

  1. Create an AS2 message based on the incoming ConnectMessage. See the section on creating AS2 messages for more details.
  2. Check if signing is enabled by checking the value of the Enable Message Signing attribute.
  3. If signing is enabled, sign the message. See the section on signing AS2 messages for more details.
  4. Check if encryption is enabled by checking the value of the Enable Encryption attribute.
  5. If encryption is enabled, encrypt the message. See the section encrypting AS2 messages for more details.
  6. Send the AS2 message as an HTTP(S) POST operation to the URL specified by the AS2 URL attribute.
  7. Receive the Message Disposition Notification (MDN). The MDN is a signed receipt that is sent to the sender as proof that the message has been received.
  8. Finally package the MDN into a separate MessagePart and add it to the ConnectMessage before sending it downstream for further processing. The MessagePart ID is determined by the value of MessagePart Out.

Note that for the sake of simplicity AS2 message compression has been omitted. Some AS2 implementations support compressing and decompressing AS2 messages (see RFC 5402 for more details). This requires the additional steps of checking if compression is enabled and if so compressing the message. These steps might occur before or after signing the message.

Furthermore note that the AS2 sender is very similar to the AS2 gateway. The AS2 sender can optionally not request an MDN and either way does not do anything with the MDN.

Creating AS2 Messages

The following diagram shows how an AS2 message is created.

 

  1. Extract the relevant MessagePart from the ConnectMessage using the value of MessagePart In.
  2. Extract the payload from the MessagePart.
  3. Extract and create headers. See the following subsection for the details.
  4. Create a new empty AS2 message.
  5. Set the AS2 message payload extracted in step 1. The Charset attribute is used to provide a custom character encoding.
  6. Set the AS2 message headers that were created/extracted in step 2.

Extracting and Creating Headers

The following diagram shows how various headers are extracted and/or created.

 

  1. Extract MessagePart headers using the value of Mapped Headers.
  2. Check if a custom subject is requested using the value of Use Custom Subject.
  3. If a custom subject is requested, extract the subject header from the MessagePart. This header is identified by the value of Custom Subject Header.
  4. If a custom subject is not requested, use a default subject specified by Subject.
  5. Check if a custom filename is requested using the value of Use Custom Filename.
  6. If a custom filename is requested, extract the filename header from the MessagePart. This header is identified by the value of Custom Filename Header.
  7. If a custom filename is not requested, generate a filename.
  8. The filename is used to create the Content-Disposition header.
  9. Add in various other header values such as Content-Type, Content-Transfer-Encoding, etc...

Signing AS2 Messages

The following diagram shows how an AS2 message is signed.

 

  1. The first step in signing a message is calculating the message digest using a hashing algorithm specified by Signing Algorithm.
  2. Encrypt the message digest calculated in the previous step. The message digest is encrypted using the sender’s private key which is retrieved from the ConnectPlaza keystore using Sender x509 Alias.
  3. Check if the sender’s public key should be included in the message body.
  4. Include the certificate in the message body. This requires retrieving the public key from the ConnectPlaza keystore.

Encrypting AS2 Messages

The following diagram shows how an AS2 message is signed.

 

 

Encrypting a message requires two attribute values, i.e., Encryption Algorithm and Receiver x509 Alias. The Receiver x509 Alias is used to retrieve the intended receiver’s public key.

AS2 Sender

The AS2 sender is used to send AS2 messages. This involves a number of steps such as payload extraction, message signing and encryption before finally sending it.

The following diagram gives an overview of the overall operation and structure of the AS2 sender and how the attribute values affect its execution. The boldface names are attribute names. The next sections will go into more detail about the individual steps.

 

  1. Create an AS2 message based on the incoming ConnectMessage. See the section on creating AS2 messages for more details.
  2. Check if signing is enabled by checking the value of the Enable Message Signing attribute.
  3. If signing is enabled, sign the message. See the section on signing AS2 messages for more details.
  4. Check if encryption is enabled by checking the value of the Enable Encryption attribute.
  5. If encryption is enabled, encrypt the message. See the section encrypting AS2 messages for more details.
  6. Send the AS2 message as an HTTP(S) POST operation to the URL specified by the AS2 URL attribute.
  7. Receive the Message Disposition Notification (MDN). The MDN is a signed receipt that is sent to the sender as proof that the message has been received. Note this step is optional and is entirely skipped if Request MDN is set to false.

Note that for the sake of simplicity AS2 message compression has been omitted. Some AS2 implementations support compressing and decompressing AS2 messages (see RFC 5402 for more details). This requires the additional steps of checking if compression is enabled and if so compressing the message. These steps might occur before or after signing the message.

Furthermore note that the AS2 gateway is very similar to the AS2 sender. The AS2 gateway always requests an MDN whereas this is optional in the AS2 sender. Furthermore, the AS2 gateway packages the MDN into a separate MessagePart that gets added to the ConnectMessage. The AS2 sender simply disposes the MDN if it is requested.

Creating AS2 Messages

The following diagram shows how an AS2 message is created.

 

  1. Extract the relevant MessagePart from the ConnectMessage using the value of MessagePart.
  2. Extract the payload from the MessagePart.
  3. Extract and create headers. See the following subsection for the details.
  4. Create a new empty AS2 message.
  5. Set the AS2 message payload extracted in step 1. The Charset attribute is used to provide a custom character encoding.
  6. Set the AS2 message headers that were created/extracted in step 2.

Extracting and Creating Headers

The following diagram shows how various headers are extracted and/or created.

 

  1. Extract MessagePart headers using the value of Mapped Headers.
  2. Check if a custom subject is requested using the value of Use Custom Subject.
  3. If a custom subject is requested, extract the subject header from the MessagePart. This header is identified by the value of Custom Subject Header.
  4. If a custom subject is not requested, use a default subject specified by Subject.
  5. Check if a custom filename is requested using the value of Use Custom Filename.
  6. If a custom filename is requested, extract the filename header from the MessagePart. This header is identified by the value of Custom Filename Header.
  7. If a custom filename is not requested, generate a filename.
  8. The filename is used to create the Content-Disposition header.
  9. Add in various other header values such as Content-Type, Content-Transfer-Encoding, etc...

Signing AS2 Messages

The following diagram shows how an AS2 message is signed.

 

  1. The first step in signing a message is calculating the message digest using a hashing algorithm specified by Signing Algorithm.
  2. Encrypt the message digest calculated in the previous step. The message digest is encrypted using the sender’s private key which is retrieved from the ConnectPlaza keystore using Sender x509 Alias.
  3. Check if the sender’s public key should be included in the message body.
  4. Include the certificate in the message body. This requires retrieving the public key from the ConnectPlaza keystore.

Encrypting AS2 Messages

The following diagram shows how an AS2 message is signed.

 

Encrypting a message requires two attribute values, i.e., Encryption Algorithm and Receiver x509 Alias. The Receiver x509 Alias is used to retrieve the intended receiver’s public key.