AS2 Connector

Usage

An AS/2 Connector sends and receives business messages and receipts in accordance with Applicability Statement 2 (AS2).

In AS2 rules for the secure exchange of structured MIME business messages using the HTTP protocol in a peer-to-peer network are defined. AS2 defines how the connection is established and how business messages are validated, sent, and acknowledged using MDNs (Message Disposition Notifications).

The message’s ownership and authenticity is validated by using a digital signature, and data security is ensured by means of encryption. Upon receipt of the message, the sender gets a digital Message Disposition Notification (MDN) as proof of timely delivery.

The messages are packaged in an envelope using standard MIME structures for sending.

The business messages can exist in XML format, EDI format (e.g. in ANSI X12, UN/EDIFACT), or in any other structured format.

For the IETF-AS2 specification, refer to https://www.ietf.org/rfc/rfc4130.txt.

The AS2 Connector has been successfully tested with the following products:

  • Compinia ComAS2

  • OpenAS2

  • IP*Works AS2 Connector

Module Variables

Variables of the AS2 Connector

The table contains all variables that are set by an AS2 Connector during its execution, irrespective of whether the connector is an input or output connector. The variables are available for the rest of the workflow’s execution:

Name Value

AS2Subject

Value of the HTTP header Subject in the input message.

ASMessageMDNOptions

Value of the HTTP headers for Disposition-Notification-Options in the input message.

ASMessageMIC

Value of the calculated check sum of the input message.

ASMessageMICALG

Name of the algorithm which was used for calculating the check sum.

Only for sending/receiving the AS message, but not for sending/ receiving the AS message disposition notification (MDN)

You can set the MIC algorithm using the variables mapping and override the value set for the message.

For this purpose, create the text module property ASMessageMICALG and set a value, e.g. SHA1 SHA-1 or SHA-256.

ASArchivePath

Defines the path to the archive directory in the file system for the Message Archive Configuration: refer to Dialog Message Archive Configuration.

If no value is defined for the variable, the cache is used.

CMS.Algorithm.Identifier.Disabled

To disable the Cryptographic Message Syntax algorithm (CMS algorithm) using the variable mapping, refer to Workflow Variables and Mappings.

If this variable is set to true, the CMS algorithm is disabled.

If this variable is set to false (default), the CMS algorithm is enabled.

Variables of the AS2 Input Connector

The table contains all variables (module variables and workflow variables) that are set by the AS2 Input Connector:

Variable Value

ASMessageID

ID of incoming AS message

ASMessageTo

AS2 ID of receiver

ASMessageFrom

AS2 ID of sender

ASMessageError

Error message, including one of the following:

  • authentication-failed: If the signature check for the incoming message failed.

  • decryption-failed: If decryption failed.

  • sender-equals-receiver: If the sender and receiver are identical.

For other error messages, refer to AS2 specification.

ASMessageDate

Timestamp of receipt in the format EEE, d MMM yyyy HH:mm:ss Z.

The letters signify the following:

E = work day (Monday to Sunday)

d = day of the month (1 to 31)

M = abbreviation of the month name

y = Year (0 to 9)

H = hour of the day (0 to 23)

m = minute (0 to 59)

s = second (0 to 59)

Z = time zone (specification in accordance with RFC 822)

ASMessageFailure

Error message. Refer to AS2 specification.

ASMessageWarning

Warning. Refer to AS2 specification.

isEncrypted

Information whether the message is encrypted (isEncrypted=true) or not (isEncrypted=false)

KeyEncryptionAlgorithm

Key encryption algorithm used to exchange symmetric keys necessary to encrypt the content

KeyEncryptionHashAlgorithm

Hashing algorithm used for the key encryption algorithm RSAES-OAEP

EncryptionAlgorithm

Content encryption algorithm used to encrypt the message content

isSigned

Information whether the message is signed (isSigned=true) or not (isSigned=false)

SignatureAlgorithm

Signature algorithm used for the message

HashingAlgorithm

Signature hash algorithm used for the message

MDNSignature

Information whether the MDN signature is valid (MDNSignature=true) or not (MDNSignature=false)

MDNIsSigned

Information whether the MDN is signed (MDNIsSigned=true) or not (MDNIsSigned=false)

MDNSignatureAlgorithm

Signature algorithm used for MDN

MDNHashingAlgorithm

Signature hash algorithm used for MDN

MDNMICALG

MIC algorithm used in the incoming MDN message

RFC5751Format

To use SHA1 of older RFC conform behavior, add module property RFC5751Format in the AS2 Listener Connector and set the static value as false. Otherwise, SHA-1 is used.

Variables of the AS2 Output Connector

The table contains all variables that are set by the AS2 Input Connector:

Module variable Value

Mime.Signature.Algorithm

Value of the signature algorithm

Mime.Key.Algorithm

Value of the key algorithm

Mime.Rsaoaep.Hashing.Algorithm

Value of the hashing algorithm selected for the RSAES-OAEP key encryption algorithm

ASMessageLog

If this variable is set to true, the MDN and AS raw data are transferred to the workflow variable as ASMessageRequest and ASMessageMDNResponse.

Refer to Workflow Variables and Mappings

Receiving, Sending and Verifying AS2 Messages

AS2 provides secure data transmission protocols via its secure transmission loop with asymmetric encryption. Thereby, messages can be encrypted as well as signed and, additionally, acknowledgements can be requested.

For encryption and decryption both sender and recipient of a message have a key pair consisting of a public and private key and have shared their public keys with each other. This means that both sender and recipient have the public key of the other communication partner and each have their own private key that they never share.

MIME Structure

When sending a message, the structure/packaging is built according to the following procedure, which depends on the respective configuration.

When sending a message, you must adhere to the sequence of the steps, whereas, when receiving a message, you can execute the steps in any order.

  1. The original MIME message is compressed optionally. You can control the content transfer encoding using the hidden messageEncoding property. By default, binary is set.

  2. The MIME message is signed optionally. You can change the digest algorithm of the S/MIME signature using the hidden Mime.Sign.Digest property. SHA1 (default), SHA384, SHA-512, and SHA-256 are supported.

    The value specified in Mime.Hashing.Algorithm is overwritten when using the hidden module property Mime.Sign.Digest.

  3. The MIME message is encrypted optionally.

  4. The MIME message is sent using the HTTP protocol.

If no content transfer encoding is supported, you can deactivate it using the module property skipHTTPEncoding=true.

Workflow Examples

The following workflows illustrate sending and receiving an AS2 message and its acknowledgement (Message Disposition Notification, MDN). It is an example for asynchronous message transmission.

module guide 943 1

The modules are configured as follows:

  1. SendMessagesRequireMDN

    The Output Connector encrypts the data to be transmitted using the public key of the receiver, sends the data and requests an asynchronous MDN as signed acknowledgement of receipt of the encrypted data from the receiver. The message contains (amongst others)

    • an ID which is stored in a directory, because it will be required later for identifying the MDN,

    • the address to which the MDN is to be sent,

    • a check sum of the message’s content.

  2. ReceiveMessages

    The Input Listener waits for incoming messages. As soon as a message arrives, the Connector decrypts it using its private key and starts the workflow.

  3. StoreMessages

    The File Connector saves the message on the recipient’s side.

  4. SendMDN

    The Output Connector automatically creates the MDN, if one was requested.

    The MDN contains the ID of the message, a check sum of the message’s content and a signature.

    The signature is created by using the private key of the message recipient and guarantees that the MDN really was send by the message’s recipient. The ID, address and check sum are automatically transferred via variables from the Input to the Output Connector.

    The Output Connector sends the MDN back to the sender.

    If an error occurred when receiving a message, both module variables ASMessageError and ASMessageErrorMessage are set.

    Both variables must have been set before using the workflow variables mapping, refer to Defining Module Variables.

    If both variables were set, the AS2 Connector will send a negative MDN, for example:

    Disposition: automatic-action/MDN-sent-automatically; processed/Error: authentication-failed
Error: no partner found for incoming message

    In this example, the variables are set as follows:

    The AS2 module sending the MDN must be the last module in the technical workflow.

  5. ReceiveMDN

    The Input Listener waits for the MDN. As soon as it arrives, the ID contained in the MDN is stored into the directory, into which the ID was already stored when sending the message. The ID is used to find the data of the corresponding AS2 message which was stored in the file system.

    The check sums are compared with each other in order to guarantee that the message has arrived completely and correctly at the receiver.

    Additionally, the sender can check the signature by using the public key of the receiver. The Input Listener generates an XML output message according to the following structure:

    <?xml version="1.0" encoding="UTF-8"?>
<MDNReport>
  <MDNIsSigned>true</MDNIsSigned>
  <MDNSignature>true</MDNSignature>
  <MDN-From>receiver</MDN-From>
  <MDN-To>sender</MDN-To>
  <MDN-Message-ID><ab536c2c-9e6e-48ee-b5c9-0c669ea2f478@MDN_sender></MDN-Message-ID>
  <MDN-Message-Date>Tue, 19 Mar 2019 11:36:13 GMT</MDN-Message-Date>
  <MIC>true</MIC>
  <Error>decryption-failed</Error>
</MDNReport>

    The elements have the following meanings:

    • <MDNIsSigned>

      Information whether the MDN is signed or not

      • true if MDN/receipt is signed.

      • false if MDN/receipt is not signed.

    • <MDNSignature>

      Information whether the MDN signature is valid or not

      • true if the signature is valid.

      • false if the result of the signature check shows an error.

    • <MIC>

      (Message Integrity Check) True or false depending on whether the checksums and the content match.

    • <Error>

      Placeholder for the following error elements:

      • Failure, Error, Warning: Contain a short error message described in the AS2 specification.

      • FailureMessage, ErrorMessage, WarningMessage: Contain detailed error messages (rarely supported).

Refer to IETF-AS2 specification.

For synchronous message transmission, the Input Listener (ReceiveMDN) is not necessary because the Output Connector workflow (SendMessageRequireMDN) pauses until it receives a response.

Dialog Descriptions

Dialog AS2 Configuration - Input Listener Connector

(Input Listener Connector)

In the AS2 configuration dialog you define whether the connector should receive messages or acknowledgements.

Dialog AS S/MIME Configuration

(Message Receipt with Input Listener Connector)

This dialog offers the following options:

Verify signature

If this option is selected, then signatures of all incoming messages are verified. For verification, you need the public key of that business partner, whose message you are receiving.

  • Upload truststore or certificate (button)

    Opens a file explorer for uploading the public key. After having uploaded the public key, its validity, serial number, and subject are displayed above the button.

  • Incoming message must be signed

    If selected, then incoming, unsigned messages cause an error.

Decryption

If this option is selected, then all incoming messages are decrypted. For this, you need your private key.

  • Upload keystore (button)

    Opens a file explorer for uploading the key. After having uploaded the public key, its validity, serial number, and subject are displayed above the button.

  • Incoming message must be encrypted

    If selected, then incoming, unsigned messages generate an error.

Dialog AS2 Listener Configuration - Receiving Messages with Listener

(Output Connector/Input Listener)

This dialog offers the following options:

Server configuration

  • URL

    URL of the Server where the INUBIT Process Engine with the AS2 Input Connector is installed. Per default, the URL follows the pattern:

    https://<server>:<port>/ibis/servlet/IBISHTTPUploadServlet/<module name>

    If required, adjust the address of the server.

  • Authentication

    If authentication is required for your server, specify the relevant data here.

Dialog Message Archive Configuration

(MDN Receipt with Input Listener)

If asynchronous messages are sent, check information of the message are filed. Based on the checking information, the message receipt (MDN) is clearly determined and correctly assigned to the send message. As soon as the message receipt is filed, the check information is deleted.

  • In a filesystem

    The check information of the send message is filed in the archive directory of the filesystem. A path to the archive directory must be set.

    The parallel processing of the workflow may cause access conflicts, if the filesystem is chosen as storage.

Refer to Module Variables.

Dialog AS MDN Validator

(Output Connector/MDN Receipt with Input Listener)

Refer to Module Variables.

Dialog AS2 Listener Configuration - Receiving MDN with Listener

(Receiving MDN with Listener/Sending Messages with Output Connector)

In the dialog for the configuration of the AS2 Listener you define the settings of the server to which incoming messages should be sent.

Server configuration

Dialog AS2 Configuration - Output Connector

(Output Connector)

In the dialog for the configuration of the output connector you specify whether the output connector should send messages or message acknowledgements.

Dialog AS Message Configuration

(Sending Messages with Output Connector)

This dialog offers the following options:

  • Sender/Receiver (AS ID)

    Specify the sender and receiver AS ID (character string with max. 128 characters). You have to agree the sender and receiver AS IDs with your business partner prior to the first exchange of messages.

  • Subject

    Meaningful description of the message.

  • Encoding

    Select one of the encodings which corresponds to the encoding of your AS2 messages.

    If you want to transmit binary files such as multimedia data, leave this blank.

  • MIME type

    Select a MIME type you which corresponds to the type of your AS2 message. If the type required is not provided here, enter it manually.

Refer to https://www.iana.org/assignments/media-types/ for a list of MIME media types.

  • File name

    Optionally, you can enter a name for the message content of the AS2 message, which is integrated into the Content-Disposition message header as filename parameter.

  • Accept

    You can configure the accept header parameter. By default, the value is set to: text/html, image/gif, image/jpeg, *; q=.2, /; q=.2

    If the value is set via user interface or module property, the updated value is considered.

  • Enable content type folding

    If selected, then the Content-Type header parameter of your AS2 message is displayed without line breaks.

Dialog S/MIME Configuration

(Sending Messages with Output Connector)

You use the dialog for AS S/MIME configuration to define if messages are to be signed, encrypted and/or compressed.

Sign

If selected, then all outbound messages are signed with their private keys.

  • Hashing Algorithm

    Choose the hashing algorithm to ensure data integrity during the encryption and signature processes. This algorithm transforms message content into fixed-size hash values, providing essential verification during encryption and signature processes.

  • Signature Algorithm

    If not selected, the signature algorithm configured in the certificate is considered by default.

    Choose the signature algorithm, which involves asymmetric cryptography, such as RSA and ECDSA. This algorithm is utilised to authenticate message contents and sender identity, generating digital signatures to ensure data integrity during the encryption and signature processes.

    You can set/override the selected value by changing the Mime.Signature.Algorithm module variable to RSASSA-PSS, RSASSA-PKCS1-v1_5 or ECDSA.

  • Valid until

    Displays the key’s validity date, serial number, and subject after loading the key.

  • Upload keystore (button)

    Opens a file explorer for loading the key.

Encrypt

If encryption is selected, then all outbound messages are encrypted with the public key of your business partner.

If your business partner does not use the INUBIT AS2 Connector to receive AS2 messages, ask your business partner which encryption algorithm is used by the partner’s AS2 software beforehand. This is necessary because not all products support all algorithms.

  • Encryption algorithm

    For selection of the encryption algorithm. DES_EDE3_CBC is default, since this is the most common method. On the receiver side, the procedure used to encrypt the message is automatically detected. Other encryption algorithms are available in the drop-down list.

  • Key Encryption algorithm

    If not selected, the key encryption algorithm configured in the certificate is considered by default. The key encryption algorithm selected in the drop-down list can be different from the certificate.

    Choose the key encryption algorithm. It is essential for encrypting and decrypting cryptographic keys, ensuring their security using methods such as RSA and ECC.

    You can set/override the selected value by changing the Mime.Key.Algorithm module variable to RSAES-OAEP, RSAES-PKCS-v1 5 or ECDH.

  • Hashing Algorithm

    If you have selected the RSAES-OAEP key encryption algorithm, you can choose a hashing algorithm from the drop-down list.

    SHA-1 is set by default.

    You can set/override the hashing algorithm by using the Mime.Rsaoaep.Hashing.Algorithm module property.

  • Valid until

    Displays the validity date, serial number, and subject after uploading the key.

  • Upload truststore or certificate (button)

    Opens a file explorer for loading the public key.

Compress

When activated, then messages are compressed corresponding to the S/MIME specification.

Dialog AS MDN Configuration

(Sending Messages with Output Connector)

In this dialog, you define if you expect acknowledgments (MDN) from the receiver. Per default, synchronous acknowledgments are required.

The recipient sends synchronous acknowledgments immediately when the corresponding messages have arrived. The acknowledgments are sent via HTTP to the address which is contained in the message. The Output Connector waits until the MDN has arrived. For storing the acknowledgments, add a File Connector to the workflow behind the Output Connector.

Alternatively, you can state that you rather expect asynchronous acknowledgments and/or signed acknowledgments:

  • Signed message disposition notification required

    If this option is selected, the recipient must sign the MDN which is sent back and validated by the MDN listener.

  • Asynchronous MDN

    Asynchronous acknowledgments are sent temporally independently from the message. For receiving the MDN, you need an AS2 Input Listener.

    Enter the URL to which the MDN is to be sent. The URL is either transmitted without encryption via HTTP or with encryption via HTTPS together with the message. Both options are open to you.

Dialog HTTP/HTTPS Server Configuration

(Sending Messages with Output Connector)

In this dialog, you specify settings for the server to which the AS2 message is to be sent.

Server configuration

Connection test

  • Test connection

    For testing whether the connection can be successfully established using your configuration.

Dialog AS MDN Shipping Configuration - Sending MDN with Output Connector

Refer to Module Variables.

For loading the key store you need its alias and password!

Sign

If selected, then all outbound messages are signed with their private keys.

  • Hashing Algorithm

    Choose the hashing algorithm from the drop-down list.

  • Signature Algorithm

    If not selected, the signature algorithm configured in the certificate is considered by default.

    Choose the signature algorithm from the drop-down list.

    You can set/override the selected value by changing the Mime.Signature.Algorithm module variable to RSASSA-PSS or RSASSA-PKCS1-v1_5.

  • Valid until

    Displays the key’s validity date, serial number, and subject after loading the key.

  • Upload keystore (button)

    Opens a file explorer for loading the key.

Header parameters

  • Enable content type folding

    If selected, then the Content-Type header parameter of your AS2 MDN message is displayed without line breaks.

Press Esc to exit full screen
Modal image placeholder
Press Esc to exit full screen