Pre-configured AS2 Host Quick-Start
Document Version 2.2, October 19, 2004 Copyright 2004 Cleo Communications
Refer to the Cleo website at http://www.cleo.com/products/lexihubs.asp for the current list of available hosts.
In this section…
Process Map Overview
Obtain Your Local Host Address Configure Your Client-Side Firewall Determining Your URL Information Certificate Creation and Exchange Generating Self-Signed Certificates Exchanging Certificates
The Local Listener Host Configuration Mailbox Configuration
Overriding Certificates at the Mailbox Level Configuring the Mailbox / HTTP Parameters
Note: VersaLex is the underlying AS2 engine that drives your Cleo product. The term "VersaLex" will be used throughout this document to refer to your Cleo product.
If just getting started with VersaLex, refer to Section 3, ‘Getting Started’ of the User’s Guide which is included as part of your installation, or you may obtain it from Cleo's documentation web site through your VersaLex product by clicking on the support link under the 'Help>Links' option. Then follow these steps to set up your pre-configured AS2 host:
Obtain your local host address from your system administrator (page 3).
Configure your client-side firewall (page 3).
Create a new self-signed certificate or import an existing certificate into VersaLex (page 5).
Send your certificate to your trading partner (page 7).
Activate the Pre-configured Host (page 9).
Local Listener (page 9).
Host (page 10).
Mailbox (page 12)
The AS2 standard provides the ability to securely transport EDI (and other data, including binary and XML) to a remote host, guarantees that the message has not been changed in-transit and is received and can be read only by the intended recipient. A returned MDN receipt (Message Disposition Notification) further guarantees that the intended recipient has received the message.
AS2 uses the HTTP protocol as its transport mechanism to send files over the Internet. VersaLex uses the PUT (HTTP POST) action command to transport the secure data to the remote host.
The pre-configured AS2 Host and the Local Listener are provided to allow you to quickly set up your AS2 installation. Pre-configured hosts are already pre-defined with the correct specifications for exchanging messages with a specific trading partner or VAN. You only need to define a couple parameters specific to your installation.
Obtain Your Local Host Address
A static visible external IP address (or qualified host name which includes your domain address) for the system (your local host) where you have installed VersaLex must be obtained. You will use this address or host name to properly configure VersaLex and to exchange URL information with your trading partner.
Contact your systems administrator if you do not know your external IP address or host name or obtain it from the following link: http://www.cleo.com/whoami
Configure Your Client-Side Firewall
Note: this section refers to your firewall settings, and not settings within VersaLex. You may want to contact your systems administrator with questions pertaining to your firewall.
If your server is behind a firewall, it will be necessary to configure your firewall to allow VersaLex to properly exchange messages with the remote AS2 server. Depending on the type of firewall you have, the following settings in your firewall should be modified:
1. Incoming and outgoing messages should be allowed from and to your remote trading partner’s IP addresses or qualified host name.
2. The port for your trading partner’s remote server should be opened for outgoing messages.
3. The port(s) that you configured for your Local Listener should be opened to allow incoming messages.
Refer to the host-specific information to determine the specific firewall settings for your trading partner’s pre-configured host. Additional firewall information for a pre-configured host may be included in the Host 'Notes' tab. To aid in determining the ports that will need to be opened, you may also generate a report of the currently used inbound and outbound ports through your VersaLex product by clicking on the 'Tools>TCP/IP Port Usage…' option.
Determining Your URL Information
Before you can begin a trading relationship, you must provide your trading partner with your URL information, which will be in the form:
your-host is Local Host Address value you have obtained from your systems
administrator (page 3) and will be entered on your Local Listener AS2 Service tab. This will be either a fully qualified host name or an IP address. Refer to Section 6 (Local Listener) of the User’s Guide for more detailed information.
port is the HTTP Port # you will be entering on your Local Listener HTTP panel.
A port setting of 5080 is suggested; however any port between 1024 and 65535 may be used.
your-resource-path is the value that is specified in the Resource Path field on the
Local Listener AS2 Service tab. By default, this value is set to “/as2” for new AS2 installations and “/” for existing installations. If your-resource-path is anything other than “/”, your trading partners must include this resource path in the URL when sending you AS2 messages.
As an example, if your local host address is myhost.com, your port is 5080 and your resource path is “/as2”, the URL you would provide to your trading partner would be: http://myhost.com:5080/as2/.
Certificate Creation and Exchange
Certificates must be exchanged before the trading relationship can be established. Either a new self-signed certificate will need to be created or an existing CA (Certificate Authority) certificate must be registered in VersaLex.
To acquire a CA-signed certificate, a self-signed user certificate must first be generated. VersaLex provides an integrated Certificate Manager, which may be used to create a self-signed certificate. See the section, Certificate Manager: Reference, of the User’s Guide for more detailed information.
Note: You may use the same self-signed certificate for multiple trading relationships (which is configured on the Certificates tab of the Local Host) or a different self-signed certificate may be used for each trading relationship (which is configured on the Certificates tab at the Mailbox level and described on page 14).
Generating Self-Signed Certificates
Select the Certificates icon at the top of the panel:
1. Right-click the Users store in the tree pane and select ‘Generate>Self-signed User Certificate…’
2. Enter the required information. The above is an example.
Note: Be sure to record your User Alias and Password, as they will be required later to configure the AS2 Listener.
User Alias An arbitrary name for the certificate (e.g. ‘CLEO’) Common Name A user name for client-style certificates; a fully qualified
computer name (or registered IP address) for server-style certificates (e.g. ‘cleo.com’).
Email e.g. ‘firstname.lastname@example.org’
Organization Unit This could be a company department (e.g. ‘Cleo Engineering’, or ‘Cleo Production’)
Organization Official company name (e.g. ‘Cleo Communications, Inc.’) City Complete city name (e.g. ‘Loves Park’)
State State name (e.g. ‘IL’)
Country Two characters only (e.g. ‘US’). (This is available through a pull down menu.)
Algorithm Either MD5 or SHA-1. Cleo suggests SHA-1
DigitalSignature Set if certificate is to be used for SSL client or S/MIME (AS2) signing. This field should generally be checked.
KeyEncipherment Set if certificate is to be used for SSL server or S/MIME (AS2) encryption. This field should generally be checked. Valid For The number of months that this certificate will be valid. By
default, it is set to 24 months, but may be increased up to 96 months.
Private Key Size 512-bit or 1024-bit (1024 bit size is recommended as it provides stronger encryption)
Password This is an arbitrary password. This is a case sensitive value. Make sure you remember this password. You will need it in order to associate the Server ID to a Host.
Re-enter the private key password.
3. After all the required information is entered, click OK. Because the generation of a self-signed certificate involves public-private key pair generation, this process may take some time. After the key-pair and certificate are created, the certificate is added under Users in the tree pane.
Once you have a self-signed certificate or third-party CA certificate that you want to use for this trading relationship, export it from VersaLex to a file using the following process:
1. Right-click on the certificate you just added under Users in the tree pane and select ‘Export>User Certificate…’
Enter a filename for your certificate, e.g. myCert. When the certificate is exported, the file extension ‘.cer’ will automatically be added to the filename you enter. By default the certificate will be stored in the VersaLex home directory. You may choose to store your certificate file in another directory by first clicking the Browse… button and choosing a new directory before entering your certificate name.
(Remember the name of your certificate and the folder where you stored it, you’ll need it for the next step.) Click the Export button to complete the export and save your certificate.
3. Follow the procedure provided by your trading partner to exchange certificates. Refer to the host-specific information for your pre-configured host for additional information.
4. VersaLex provides certificates for some of the pre-configured hosts and are already installed for you as part of your installation. Some trading partners require that you obtain their certificate directly from them. Refer to the host-specific information for your pre-configured host for additional information.
If you are required to obtain a certificate from your trading partner, you must register it in VersaLex. You may register the certificate you receive by saving the certificate file in the certs\ directory (under the VersaLex home directory) or by using Certificate Manager’s Import command. Refer to the User’s Guide for information on using the Import feature. In the section, you will be instructed on how to configure VersaLex to use this certificate.
Note: You may view your trading partner’s certificate by searching for it under the Root or Intermediate branch under Trusted CAs in the tree pane.
Activate the AS2 pre-configured host:
1. Click the Preconfigured tab in the
2. Find the host that you wish to activate in the list of pre-configured hosts and right-click on it.
3. Select ‘Clone and Activate’.
The Active tab will automatically be selected in the tree pane and the entire pre-configured host branch will be copied and made active and the new active host will automatically be selected in the tree. The new active host alias may be appended with a number, if necessary, to make it unique. The original pre-configured host will remain in the Preconfigured tree.
Now you’ll configure your local listener branch and define a few parameters for your trading partner’s pre-configured host.
The Local Listener Configuration
The Local Listener receives and handles all inbound requests to your VersaLex product. Inbound requests include unsolicited and asynchronous AS2/HTTP trading partner messages and VersaLex web browser user requests (supported only on Unix and Windows platforms). The Local Listener must be configured properly in order for your trading partner and remote user requests to be
A detailed description of the necessary steps for configuring the Local Listener for receiving AS2 messages may be found in Section 6 (Local Listener) of the User’s Guide. You may view the latest User’s Guide online at either
http://www.cleo.com/lexicomdoc or http://www.cleo.com/vltraderdoc. You will need to provide your product serial number in order to access this site which may be found through the Tools>License… menu option.
tree pane and select Wizard... or click the wizard button in the Local Listener content pane.
A host describes the remote server to which files will be sent. The host’s
parameters specify its location and how it is reached. The settings for each of the Host Configuration tabs have been pre-defined based on the requirements of each pre-configured host. Tabs that are fully pre-configured with parameters that should not be changed are not displayed in this document. However, if you have specific file naming requirements, you may set them under the AS2 tab.
In the AS2 tab:
a. The only MIME format currently supported by VersaLex is S/MIME.
b. The Folded Headers checkbox is used to enable/disable automatic line
wrapping of HTTP headers exceeding 76 characters. (By default headers are not folded since some non-VersaLex remote hosts using Microsoft Internet Information Server (IIS) cannot handle folded headers properly.) Unless your
host has been pre-configured to enable “Folded Headers”, leave this field unchecked!
c. The Store Raw Sent checkbox is used to save the content of the HTTP
header and raw (unprocessed) message sent to the remote host. The files are stored in the as2\sent\ directory under the VersaLex home directory. These files may be useful in diagnosing problems, but should be disabled if disk space needs to be conserved.
d. The Overwrite duplicate file names checkbox allows for unique naming of stored files. When this checkbox is selected, any files that exist in the specified “Inbox” will be overwritten. When not selected, incoming files with the same name as one that already exists will be appended with a unique number beginning with 1 and incremented each time a new file is saved.
e. The Use default file name checkbox allows the incoming file to be given the name specified in its associated field.
This feature is useful in situations where the received file name must be something other than its original file name. (This is common for AS/400 platforms where the file name must be specified with a .mbr extension.) f. The Add Content-Type Directory to Inbox checkbox allows for sorting of
incoming messages based on content-type to a subdirectory (under the
Inbox specified on the General tab). You specify each of the Content-Types
that you want directed to specific subdirectories by entering a name in the Directory field.
Directory entries may be made for Content-Types of: EDIFACT, X12, XML, Binary, Plain Text, and Other (a default catch-all for messages with all other Content-Types you may receive.) The same subdirectory may be used for multiple Content-Types. You may also leave Directory entries blank which will cause any received messages of that Content-Type to be stored in the Inbox specified on the General tab.
the message. VersaLex does not check the actual content of the message to
determine its content type.
If the Recipient’s Encryption Certificate field has already been pre-configured with a certificate name, you may skip this section. Otherwise, it will be necessary to populate this field with the name of the encryption certificate that you received from your trading partner for this trading relationship. This is the name of your trading partner’s certificate to be used for encrypting the messages that you send. (You should have received this file as discussed earlier in the section on Exchanging Certificates.) For pre-configured hosts, you may also find additional host specific information in the 'Notes' tab.
In the Certificates tab:
Specify the name of the file containing the Recipient’s Encryption Certificate by clicking the [Browse…] button.
For the purposes of this demonstration, assume that you have either received an attachment via email or downloaded a file from your trading partner called TradingPartnerCert.cer. You have also either copied this file to the “certs” folder under the VersaLex home directory or have imported it into VersaLex through the Certificate Manager. (See the section, Certificate Manager: Reference, of the User’s Guide for more detailed information.)
You will see a screen similar to the one that follows. Find the certificate that matches the one you received from your trading partner (in this example it is
TradingPartner.cer) and click
The Encryption Certificate field will be filled in with the path to your trading partner’s certificate:
certificate store to determine if the signature of the incoming data message is trusted. To limit validation to a specified signing certificate (i.e., the incoming data message is required to be signed with that certificate), select the Signing Certificate checkbox and browse for the certificate to be used for validating message signatures:
If your trading partner is using the same certificate for signing and encryption (which is the general practice among most trading partners), select the Use encryption certificate checkbox to automatically populate the Signing Certificate field with the same certificate as was selected in the Encryption Certificate field:
Overriding Certificates at the Mailbox Level
VersaLex provides the ability to specify a signing, and optionally an encryption certificate, for each (or for any specified) trading relationship. When you override your signing and encryption certificates at the mailbox level, the certificate(s) that you originally specified on the Local Listener panel will not be used for this trading relationship. Instead, the alternate certificate(s) that you specify will be used for signing your outbound messages and decrypting inbound messages from this trading partner.
By default, each mailbox uses the same certificates specified at the Local Listener level and are displayed and grayed out at the mailbox level:
To choose an alternate certificate (that you have previously created through the Certificate Manager or have obtained from a third-party Certificate Authority) for this trading relationship, select the Override Local Listener Certificates checkbox. This will cause the Signing and Encryption Certificate Alias and Password fields to be cleared out and enabled:
Now repeat the process of entering the Signing Certificate Alias and Password, and optionally, the Encryption Certificate Alias and Password. The procedure for selecting the certificate at the mailbox level is the same as that described in the User's Guide for the Local Listener.
Configuring the Mailbox / HTTP Parameters
The mailbox HTTP tab allows you to assign your company's AS2 name, your trading partner's AS2 name as well as the Subject and Content-Type of the documents to be transferred.
In the HTTP tab:
For pre-configured hosts, the settings you see on this tab may vary widely based on host specific requirements. Any variation to the defaults shown here are those that have been predefined in the Host HTTP tab (a hidden tab by default.) For pre-configured hosts, you can refer to the 'Notes' tab for details about setting the respective values on this tab.
Examples of pre-configured hosts that have different pre-set values:
Sterling Commerce AS2 VAN Mailbox / HTTP Configuration In the HTTP tab:
• In the field to the right of the username label, enter the user name provided to you by Sterling Commerce.
• In the field to the right of the password label, enter the password provided to you by Sterling Commerce.
• Enter your AS2-Name in the AS2-From field. This is a name that you have submitted to Sterling Commerce that will uniquely identify your organization in this trading relationship, e.g. CLEOAS2. Sterling’s AS2-Name is “SIBSERVICE1005” and has already been configured for you in the AS2-To field.
Note: AS2 names are case and space sensitive. The AS2 name that you provide must match exactly with the AS2 name that you have created.
Wal-Mart Mailbox / HTTP Configuration In the HTTP tab:
• Enter your AS2-Name in the AS2-From field. This is a name that you have submitted to Wal-Mart that will uniquely identify your organization in this trading relationship, e.g., CLEOAS2.
• Select the Wal-Mart AS2-Name in AS2-To field based on the country where you’re trading. A pull-down list like the one shown above is provided for easy selection. By default, the U.S./Puerto Rico AS2-Name has already been selected.