Link Search Menu Expand Document

Adding an AS2 Partner

1 What is an AS2 Partner

An AS2 Partner definition within the AS2Gateway specifies details about a trading partner, with which your Organization would be exchanging messages using AS2. Similar to an AS2 Station, a Partner has a unique AS2 ID, URL and certificates. You will select the Partner, when sending AS2 messages through the AS2Gateway. When messages are received into your AS2 inbox, they will also list the Partner from whom they have been received.

2 Creating an AS2 Partner

Partners need to be added/declared on AS2 Gateway, before you can send, as well as receive, messages from them. Declaring a Partner requires some information from the respective remote party, such as its AS2 ID, URL and certificate/s. (These are the information of the remote trading station corresponding to the ‘Partner Configuration’ that we saw on our local trading station page in the previous section).

To add a partner, first go to the partners view using the ‘Partners’ icon on the left navigation menu. Then click the ‘New Partner’ button.

Partner Listing and Creation
Partner Listing and Creation

2.1 Basic information of a Partner

Provide the required information to configure the trading partner you are about to add. Your Partner would be sending you this information, usually through email.

Partner Creation Basic
Partner Creation Basic
  1. Specify a name for the trading partner. This is a textual identifier for you to easily distinguish this partner from others in the system. This will be very helpful when your partners use cryptic AS2 identifiers, such as 08925485US00 by Walmart. The name will not be used within the AS2 communications.
  2. Specify the AS2 Identifier of the partner, which will be provided to you by your Partner.
  3. Specify the partner URL that your Partner will provide you. It will be used to send messages to this partner, and the partner would be listening on this URL for incoming messages.
  4. Provide a default message subject (similar to an email subject line) which will be used if a subject has not been specified when sending messages. A subject line is optional, and you can leave this to its default value.
  5. Opening the ‘Advanced Options’ section below if you would be needing to configure any advanced configuration options
  6. Upload the partner’s public certificate, which will be provided by your Partner. AS2 Gateway will use this to encrypt messages (if encryption has been enabled for outgoing messages), so that they can only be decrypted on the partner’s end, using the corresponding private key.
  7. Click the Save button to submit the form.

Once the partner has been created, you will land back in the partner list view. Now that we have a station and a partner, we can proceed to sending our first message!

2.2 Advanced configuration for an AS2 Partner

While most AS2 partners use the same certificate and key-pair for both encryption and digital signatures, there are some partners who use two different ones. If your partner uses two certificates, slide the ‘Use different certificate as sign certificate’ to enable you to upload a separate certificate for digital signatures. In addition, if your partner requires a custom SSL certificate to be trusted to establish a TLS/SSL connection, you can upload it by opening the ‘HTTPS (TLS/SSL)’ section and uploading the SSL certificate and any Chain certificates.

Partner Creation Advanced Options
Partner Creation Advanced Options

2.2.1 Encrypt Messages

Specifies if messages should be encrypted, and if so using which algorithm. Encryption would generally be enabled for all partners, as its one of the key advantages of the AS2 protocol. AES 256 or Triple DES are most commonly used.

The following encryption algorithms are currently supported in AS2 Gateway:

  • Triple DES (168-bit): DES_EDE3_CBC
  • AES (128-bit): AES128_CBC
  • AES (192-bit): AES192_CBC
  • AES (256-bit): AES256_CBC
  • Camellia (128-bit): CAMELLIA128_CBC
  • Camellia (192-bit): CAMELLIA192_CBC
  • Camellia (256-bit): CAMELLIA256_CBC
  • CAST5/CAST-128 (128-bit): CAST5_CBC
  • RC2/ARC2 (40-bit): RC2_CBC
  • SEED (128-bit): SEED_CBC

2.2.2 Sign Messages

Specifies if messages should be digitally signed, and if so using what sign digest algorithm. Digital signatures are generally enabled for all partners, as its one of the key advantages of the AS2 protocol. SHA-256 or SHA-1 is most commonly used

The following signing (digest) algorithms are currently supported in AS2 Gateway:

  • SHA1
  • MD5
  • MD2
  • SHA224
  • SHA256
  • SHA384
  • SHA512

2.2.3 Compress Messages

You can specify if compression should be used, especially if your Partner has requested so. If your Partner supports compression, large EDI or text files could be compressed well for transmission as smaller payloads.

You can choose to run the compression:

  • Before signing and/or encryption i.e. on the original set of files that you included in the message; in this case, the partner would need to first decrypt/verify the payload, and then decompress it
  • After signing and/or encryption i.e. compression would be the last (outermost) action or “layer” on the payload; in this case, the partner would need to first decompress the payload, and then decrypt/verify the content

2.2.4 Request MDN

You can choose to request a MDN, which is the default and most widely used option, or, choose to turn it off if your partner has specifically informed you to.

2.2.5 Request Asynchronous MDN

You can also specify if messages sent to this Partner should request an asynchronous MDN. By default, this is off, and the AS2 Gateway will be requesting a synchronous MDN. However, if your Partner specifies that it will be issuing an asynchronous MDN, you would need to switch this on.

In this case, AS2 Gateway will inform the partner system where (the URL/endpoint) to send the asynchronous MDN, by including an additional Receipt-Delivery-Option HTTP header on each AS2 message. This URL is usually http://service.as2gateway.com:8284/service/as2-async-mdn-receiver (or the test-service.as2gateway.com variant); Note that HTTPS is not supported.

2.2.6 Request Digitally Signed MDN

You can choose to request a digitally signed MDN for non-repudiation, a key advantage of the AS2 protocol. By saving the receiving MDN, you can prove that the Partner had received the exact version of the message that was sent. By default, this is enabled, as its widely used.

2.2.7 Partner Type

This is an advanced feature, which allows two configurations (i.e. Testing and Production) to share the same AS2 IDs. By default, the partner type is set to Production and it should be left unchanged. Even if your partner has a Testing and Production configuration - but with two distinct AS2 ID’s, this feature is NOT required. Please refer the Partner Types reference for more details.

2.2.8 Description

Specify a description of your trading partner; mainly just for identification purposes within your AS2 Gateway account.

2.2.9 Message Subject

Specify a default message subject, which will be used if a subject is not specified when sending a message (e.g. via SFTP outbox uploads, or API-based submissions without a subject query parameter)

2.2.10 Custom Headers

Some trading partners require you to send additional HTTP headers along with a standard AS2 message (e.g. for authentication or routing purposes). You can use this option to add one or more such headers as key-value pairs.

For example, to add the two headers

X-Cyclone-Routing-Key: ACME_PROD
Authorization: Basic abcdefgh1234
  • Click +, to add a new key-value pair.
  • Enter X-Cyclone-Routing-Key (excluding the colon and space, : ) on the Header Key field.
  • Enter ACME_PROD on the Header Value field.
  • Repeat above steps for the second header: key Authorization, value Basic abcdefgh1234.

To remove an already defined header, click the dustbin-icon button against that row.

Note:

  • Header keys cannot be left empty. If you submit an entry with an empty header key, it will be ignored.
  • Headers will be included in the AS2 message (HTTP request) in the order they are defined.

Using Basic Authentication

If your partner provides you with a username/password pair to use as basic authentication, you need to derive the header value as:

"Basic "base_64_encode(username":"password)

E.g. for username foo and password bar, the header would be:

  • Header Key: Authorization
  • Header Value: Basic Zm9vOmJhcg==

Once added, these headers will be included in every AS2 message that you send to this partner. If you have any advanced requirement, contact AS2 Gateway support for more information.

2.2.11 Transmission Timeout

After sending an AS2 message, AS2 Gateway waits for a finite amount of time to receive the network-level (HTTP) response for the transmission. If the response is not received within this time, the transmission is considered as a failure.

If your partner’s AS2 system generally tends to take a long time to respond, you may start getting many such “connection timed out” errors. In such cases, you can try increasing this Transmission Timeout value to tolerate such large delays, instead of failing at the default 60-second (1-minute) timeout.

The transmission timeout does not apply to asynchronous MDNs; if you send a message requesting an asynchronous MDN, and the partner sends the HTTP-level response (network acknowledgement) within the time-out period, all would be fine - regardless of how long the partner may take to send the final MDN. Even if the MDN gets delayed by several hours, AS2 Gateway will continue retaining the message in “MDN pending” status until it is received.

2.2.12 Custom Integration Flows

These are additional features that you can enable, based on the nature of the partner or of the transmitted files/messages; for example,

  • FDA: when this integration is enabled on a FDA partner (e.g. ZZFDA), submissions you make will be automatically tracked and tagged using correlation information available in received messages/responses (e.g. FDA Core-ID). Refer to the FDA communication reference for more details.