OpenAS2 Server Application

 

Table of Contents

1. Introduction

2. Glossary

3. Installing OpenAS2

3.1. System Requirements

3.2. Installing Application

3.3. Tuning Java

4. Configuration

4.1. Application Configuration

4.1.1. Overriding Certificate Store Password

4.1.2. Resend Retry Configuration

4.2. Partner Configuration

4.2.1. Partner Definition

4.2.2. Partnership Definition

4.2.3. Transfer Encoding

4.2.4.

4.2.5.

4.2.6.

4.2.6.1. Static Header Values

4.2.6.2.

Delimiter Mode

Regular Expression Mode

4.2.6.3. Adding Custom Headers To HTTP

4.2.7.

4.3. Certificate Configuration

4.3.1. Creating And Importing

4.3.2. Supporting Multiple Private Certificates

4.4. Logging System

4.4.1. Log Level Configuration

4.4.2. Email Logging Configuration

4.5. MDN Configuration

4.5.1. Asynchronous MDN Receiver Configuration

4.5.2. Asynchronous MDN Sender Configuration

4.6. Configuring HTTPS Transport

4.6.1. Inbound Transfers

4.6.2. Outbound Transfers

4.7. Message State Tracking

5. Running OpenAS2

5.1. Starting OpenAS2

5.2. Command Entry

5.3. Automated Launching As UNIX Daemon

5.3.1. INIT.D Service

5.3.2. SYSTEMD Service

6. Testing OpenAS2 Transfers

6.1. Using HTTPS Transport

7. Troubleshooting OpenAS2

7.1. Canonicalization For MIC Algorithm

7.2. Binary Encoding

7.3. HTTP Restricted Headers

7.4. CMS Algorithm Protection

7.5. SSL Certificate Exceptions

7.6. Java Versions Prior To 1.6

7.7. Mime Body Part Logging

7.8. TLSv1.2

8. Partner AS2 Compatibility Settings

9. Remote Control

10. Dynamic Variables

11. Appendix: config.xml file structure

12. Appendix: partnership.xml file structure

13. Appendix: command.xml file structure

 

1. Introduction

The OpenAS2 application enables you to transmit and receive AS2 messages with EDI-X12, EDIFACT, XML, or binary payloads between trading partners. The AS2 implementation conforms with RFC4130.

This document describes how to install, configure and use OpenAS2. In this document a partner can be either your own company or a company you will be exchanging data with using AS2.

The sample configurations in this document are based on Unix type OS but in general the only significant difference is that it may be necessary to use “\” instead of “/” for folder name separators on Windows based machines but because the application is Java it should work fine leaving the “/” for the most part as Java will do the conversion if necessary.

This document is valid for version 2.1.0 and up.

2. Glossary

EDI – Electronic Data Interchange

MDN - Message Disposition Notification

3. Installing OpenAS2

3.1. System Requirements

To be able to run the OpenAS2, you will need:

  1. 1.Java™ installed on the machine you intend to run the OpenAS2 server on – this document  uses Java 1.6. 

  2. 2.The OpenAS2 package version you wish to use. The downloadable packages can be found here: https://sourceforge.net/projects/openas2/files 

  3. 3.Java Cryptography Extension (JCE) policy files - you can download the correct version from the Java website. Search “Java Cryptography Extension Unlimited Strength“ to find the right cryptography extension for your version of Java. The current link for Java8 is here. 

3.2. Installing Application

The following steps will provide an installed app on a target machine:

  1. 1.Unzip the downloaded OpenAS2 package into a suitable location, which we will call <install_dir>.  

    NOTE: Typical values for  <install_dir> locations  are /opt/OpenAS2 under Linux®/Unix or C:\OpenAS2 under Microsoft® Windows®.
     

  2. 2.For the encryption and certificate management to work correctly, you must have the proper JCE policy files installed in your version of Java (see system requirements above). The downloaded zip archive contains the two files local_policy.jar and US_export_policy.jar. Install them into your Java location under <JAVA_HOME>/lib/security. Back up the existing files before installing these new ones. There are numerous detailed articles on the web for installing these files if you need more information. 

The file structure will look something like the figure below without the data and logs folders which are created automatically by the server when it starts based on configuration if they do not exist.

 

3.3. Tuning Java

The default settings for the Java virtual machine in the startup script (start_openas2.sh or start_openas2.bat) will work for installations on most machines for low volume/small file size transfers. However, if your system will be transferring large files you will need to increase memory allocation. If you expect to support very high AS2 traffic you will need to increase memory allocation and possibly tune the garbage collector to get reasonable performance.

How much you can increase memory allocation to Java will depend on how much RAM is installed on the system running OpenAS2 and how many other processes will be running concurrently that will also require memory.  Most systems deploy with at least 8GB RAM these days so increasing memory allocation from the default amount in the startup script should not cause adverse affects to the system.

To increase memory allocation you need to increase the heap space. This is set using the -Xmx option. You could increase this from the 384m (m = MB) default setting to 1g or 2g to get good performance for large files or busy systems and for very large files given enough RAM you can set it to 6g or 8g. Search for “-Xmx” in the startup script and adjust accordingly.

For garbage collection you may want to allocate a more appropriate garbage collector than the default parallel collector that is the default in Java. In Java 7 and up, the G1 collector is ideal if you use large heap space allocation. To enable it add this to the command line parameter:

 –XX:+UseG1GC  

4. Configuration

This section explains the details of the configuration files and how they link together.

The OpenAS2 server uses four files to configure and execute:

  1. 1.config.xml – configures the application 

  2. 2.partnerships.xml – configures the partners 

  3. 3.as2_certs.p12 – stores the PKCS12 certificates for all partners 

  4. 4.commands.xml – stores the commands that the application will support. This file should not be modified 

IMPORTANT: A restart of the application is required to load any configuration changes.

The folder containing the config.xml file defines the home configuration parameter that can be used to reference other files on the file system relative to a known base folder in the app. This is done by encapsulating home in percentage signs (%home%). All files can be referenced relative to this parameter and it is how the default config.xml file defines the location of other configuration and data file locations used by the OpenAS2 application.

4.1. Application Configuration

The file named “config.xml” configures the modules that will be activated by the AS2 server when it starts up. This file can be located anywhere within the disk subsystem on which the OpenAS2 application runs as it is passed into the application as a startup parameter.

Some of the key configuration settings in the config.xml file are:

See appendices for a detailed definition of the config.xml file structure.

There are 2 listening ports for inbound connections (see partnerships.xml config for outbound connections) used for:

  1. 1.receiving messages and synchronous MDN's – default port number 10080 

  2. 2.receiving asynchronous MDN's - default port number 10081  

The port numbers are arbitrary and defaulted to a number above 1024 that does not require root access to listen on (normally on Unix type systems any port below 1024 requires root access). The port values are important to the partner you will be communicating with if they will be sending AS2 messages to your system. For outbound only systems, it is only necessary to have a listener for asynchronous MDN's if using that mechanism for MDN's.

Each module has a number of attributes that can be configured on the module element to control and change how the module behaves.

4.1.1. Overriding Certificate Store Password

The certificate store password is stored as an XML attribute “password” on the <certificates> element. This can be overridden using the system property “org.openas2.cert.Password”. For improved security, it may not be desired to store the password in the XML file.

This can be passsed into the application by adding the following to the java command:

This can be set by using an additional parameter to the batch script file so that it can be set as part of invoking the script. The UNIX shell script will support the password as a parameter. The Windows bat file will need to be enhanced.

4.1.2. Resend Retry Configuration

When failures occur transferring a message to a trading partner, the system will automatically try to resend the message. By default the system will retry indefinitely.

Restricting the retry attempts can be done at the processor level (applies to all partnerships configured on the server) and at the partnership level. Partnership configuration will override processor settings.

To define the processor level retry count, set the “resend_max_retries” attribute on the processor element to a valid integer.

Example snippet:

 <processor classname="org.openas2.processor.DefaultProcessor"

     pendingMDN="%home%/../data/pendingMDN3"

     pendingMDNinfo="%home%/../data/pendinginfoMDN3"

            resend_max_retries="10" >

To define the partnership level retry count, set an attribute element on the partnership with name attribute value as “resend_max_retries” and a value attribute element to a valid integer.

Example snippet:

 <partnership name="OpenAS2A-to-OpenAS2B">

  <attribute name="resend_max_retries" value="3"/>

  <sender name="OpenAS2A"/>

 

4.2. Partner Configuration

The file named partnerships.xml configures all the information relating to the partners you will be exchanging data with. See the appendix for information on the structure of this file.

It is important to keep in mind that the word partner refers to any entity specified as a recipient or sender of AS2 messages and includes your own company that you might be configuring the application for.

 

Each partner will require the following entries in the file:

4.2.1. Partner Definition

The <partner> element requires 3 attributes to enable AS2 partner identification:

  1. 1.partner name – this is the key to connect partnerships to a partner definition  

  2. 2.AS2 identifier – this is the key for identifying the target/source partner and is included in AS2 message headers to allow the receiving partner to identify the source of the message and verify the target partner for the AS2 message. It is also used by the general directory polling module to look up the partner names and hence the partnership definition where the as2_id of the sender and receiver are part of the transferred file name. 

  3. 3.X.509 certificate alias – identifies the alis of the certificates for this partner in the keystore. The encryption and decryption of messages requires the partners public or private key as appropriate 

4.2.2. Partnership Definition

The <partnership> element identifies a specific direction of AS2 message transfer from one partner to another. The “name” attribute on the <partnership> element is not important but should be used to clearly identify the intended use of the partnership definition. It is suggested the name value uses the names of the source and destination partners something like xxx-to-yyy.

The <partnership> element encapsulates a number of child elements that are necessary to properly configure a partnership:

4.2.3. Transfer Encoding

As of version 1.3.7, the default content transfer encoding uses “binaryif not explicitly overwritten in the configuration. The default can be changed using the “content_transfer_encoding” attribute in the partnership.xml file. If you experience issues with failing to verify a partners AS2 inbound message because the message contains CR/LF data in it then you should switch to using “binary” for the transfer encoding. The sample partnership file sets the transfer encoding to “binary” for both partners.

4.2.4. Supported Encoding Algorithms

The currently supported encoding algorithms are:

4.2.5. Message Compression

The application supports inbound compression automatically. There is no configuration for this option. To enable outbound compression requires setting “compression_type” attribute on the partnership definition for the outbound configuration.  The only supported compression/decompression at this time is “ZLIB”. The default is no compression of sent messages.

By default compression will occur on the message body part prior to signing. The compression can be configured to occur after signing using the “compression_mode” attribute on the partnership definition for the outbound configuration. Set the attribute to “compress-after-signing” to enable this.

See partnership.xml appendix for configuration details.

4.2.6. Custom Mime Headers

Mime headers can be added to the outermost Mime body part for outbound messages and additionally added to the HTPP headers. The outermost Mime body part will depend on configuration of the partnership and could be the compressed, signed or encrypted part. In the case of the encrypted part being the outermost mime body part, the HTTP headers will not be visible until after decryption of the body part since encryption protects the content and the headers.

4.2.6.1. Static Header Values

Custom headers can be added as statically defined name/value pairs in a partnership attribute where the name and the value are separated by a colon. Multiple static headers are added using a semi-colon separated list between each name/value pair. The attribute name for this is “custom_mime_headers” and a sample entry of 2 static headers is shown below:

<attribute name="custom_mime_headers" value="X-CustomRoute: X1Z34Y ; X-CustomShape:oblong"/>

        Note that spaces before or after the “;” and “:” separators will be excluded.

4.2.6.2. Dynamic Header Values From File Name

Dynamic headers require 2 attributes to configure their behaviour and there are 2 different modes of  operation for extracting the value(s) for the defined header(s) from the file name:

  1. 1.delimiter mode 

  2. 2.regular expression mode 

 Delimiter mode is relatively simple and does not require any special knowledge but regular expression mode may require someone with regular expression skills. Regular expression mode provides far greater flexibility for extracting the value(s) from a file name where specific character sequences or character counts are required.

Both modes use an attribute named “custom_mime_header_names_from_filename” to enter the list of header names but the format for the two are slightly different. The second attribute required has a different name for each of the modes, custom_mime_header_name_delimiters_in_filename” for delimiter mode and “custom_mime_header_names_regex_on_filename” for regular expression mode.

IMPORTANT: if both delimiter mode and regular expression mode attributes are entered into a partnership then delimiter mode will be chosen irrespective.

Delimiter Mode

In delimiter mode, the values in the file name are separated by specifiying one or more delimiters and the entire file name is parsed into a list of values using the delimiter(s) defined. In order to accommodate file names that have more than just the values required for the custom headers, the list of header names are defined with a prefix that designates if the value in the list will be used as a header value or not. For an entry to be added as a header it must have the prefix “header.”. Any other prefix will cause that entry to be ignored. There must be as many header names defined as there are string sequences that would result from splitting the file name string by the delimiter(s) otherwise the system will throw an error.

Below is an example of a delimiter based configuration.

<attribute name="custom_mime_header_names_from_filename"

        value="header.X-Header1,header.Y-Header2, junk.extraStuff"/>

        <attribute name="custom_mime_header_name_delimiters_in_filename" value="-_"/>

Using this configuration, given a file name ABC-123-INVOICES.csv there would be 2 headers added as:
X-Header1   value ABC
Y-Header2   value 123

If the file name was ABC-123-H4FT_INVOICES.csv the system would throw an error as there would be 4 string sequences extracted so you could fix this by appending junk.moreStuff to the “custom_mime_headers_from_filename” attribute.

Another example of delimiter mode in the partnership:

<attribute name="custom_mime_header_names_from_filename"

        value="header.X-Header1, other.string1,header.Y-Header2"/>

        <attribute name="custom_mime_header_name_delimiters_in_filename" value="-"/>

Using this configuration, given a file name ABC-123_TEST-INVOICES.csv there would be 2 headers added as:
X-Header1   value ABC
Y-Header2   value
INVOICES

 

Regular Expression Mode

Regular expression based mode uses Java regular expressions and requires that the regular expression is constructed in grouping mode where the number of groups in the regular expression exactly matches the number of header names in the “custom_mime_header_names_from_filename” attribute. The regular expression will be used to parse the file name to extract the values for the defined names in the attribute named “custom_mime_header_names_regex_on_filename”. Regular expressions can become extremely complex and this document will show some simple examples but there are many sites that provide regular expression tutorials if you need a complicated soultion.

An example for a regular expression mode configuration is shown below:

<attribute name="custom_mime_header_names_from_filename" value="X-Header1,Y-Header2"/>

        <attribute name="custom_mime_header_names_regex_on_filename" value="([^-]*)-([^.]*).csv"/>

Using this configuration, given a file name ABC-123-INVOICES.csv there would be 2 headers added as:
X-Header1   value ABC
Y-Header2   value 123-INVOICES

If the file name was ABC-123-H4FT_INVOICES.csv there would be 2 headers added as:
X-Header1   value ABC
Y-Header2   value 123—HFT_INVOICES

If the file name was ABC-123-H4FT_INVOICES.txt or ABC_123.csv the system would throw an error since there would be no match.

 

Another example for a regular expression mode configuration is shown below:

<attribute name="custom_mime_header_names_from_filename" value="X-Header1,Y-Header2"/>

        <attribute name="custom_mime_header_names_regex_on_filename" value="([^-]*)-([^.]*).csv"/>

Using this configuration, given a file name ABC-123-INVOICES.csv there would be 2 headers added as:
X-Header1   value ABC
Y-Header2   value 123-INVOICES

 

4.2.6.3. Adding Custom Headers To HTTP

The following attribute set to  value of “true” will additionally add the headers to the HTTP headers for both static and dynamic header mechanisms:

<attribute name="add_custom_mime_headers_to_http" value="true"/>

4.2.7. Setting Dynamic Attributes From File Name

Partnership attributes can be added to the partnership definition based on parsing the file name of the document to be sent  using a regular expression. Dynamic attributes require 2 partnership attributes to configure their behaviour for extracting the value(s) for the defined attribute(s) from the file name.

  1. 1.attribute_names_from_filename”  - when added to a partnership it must contain a list of comma separated attribute names 

  2. 2.attribute_names_regex_on_filename” - defines the regular expression  

The extracted name/value pairs can then be referenced in config using the format:

$attributes.<attribute name>$

 

Regular expressions uses Java regular expressions and requires that the regular expression is constructed in grouping mode where the number of groups in the regular expression exactly matches the number of attribute names in the “attribute_names_from_filename” attribute.  Regular expressions can become extremely complex and this document will show some simple examples but there are many sites that provide regular expression tutorials if you need a complicated solution.

 

An example for a regular expression mode configuration is shown below:

<attribute name="attribute_names_from_filename" value="X-attribute1,Y-attribute2"/>

        <attribute name="attribute_names_regex_on_filename" value="([^-]*)-([^.]*).csv"/>

Using this configuration, given a file name ABC-123-INVOICES.csv there would be 2 attributes added as:

X-attribute1   value ABC
Y-attribute2   value 123-INVOICES

 

If the file name was ABC-123-H4FT_INVOICES.csv there would be 2 attributes added as:

X-attribute1   value ABC
Y-attribute2   value 123—HFT_INVOICES

If the file name was ABC-123-H4FT_INVOICES.txt or ABC_123.csv the system would throw an error since there would be no match.

 

Another example for a regular expression mode configuration is shown below:

<attribute name="attribute_names_from_filename" value="X-attribute1,Y-attribute2"/>

        <attribute name="attribute_names_regex_on_filename" value="([^-]*)-([^.]*).csv"/>

Using this configuration, given a file name ABC-123-INVOICES.csv there would be 2 attributes added as:

X-attribute1   value ABC
Y-attribute2   value 123-INVOICES

 

The above attributes could be referenced in config to set a more dynamic subject using something like this:

        <attribute name="subject" value="Target product: $attributes.X-attribute1$ Sequence Count: $attributes.Y-attribute2$"/>

This would produce a subject looking like this:

 Target product: ABC Sequence Count: 123-INVOICES

4.3. Certificate Configuration

NOTE: SHA1 certificates are no longer supported and are rapidly being phased out so you should use SHA256 for all partners that do support SHA256 certificates.

4.3.1. Creating And Importing

The certificate store used by default is a PKCS12 key store and stores all X.509 certificates for all trading partners. The location and name of the certificate keystore is defined in “filename” attribute of the certificates element in the config.xml file. The default deployment uses the file <installDir>/config/as2_certs.p12

 

The key store must contain the private key of your own X.509 certificate and the public key for each of your trading partners X.509 certificates.

The certificates must be stored with the matching alias as specified in the partner definition of each partner in the partnership.xml file.

 

There is a shell file to help generating certificates: bin/gen_p12_key_par.sh

An excellent open source visual keystore manager that will run on any OS and will allow importing and managing certificates in your keystore can be found here: http://portecle.sourceforge.net/

 

The following steps will create an X509 self signed certificate using OpenSSL:
openssl req -x509 -newkey rsa:4096 -keyout priv.key -out selfcert.crt -days 3650 -sha256

The generated certificate (selfcert.crt in the above command) can then be imported into the PKCS12 keystore using a command like this in the OpenAS2 command mode that is the default when starting openas2 from the command line or via the OpenAS2 remote app:

cert import <alias> <path+filename>

To create the public key for sending to the partner you can use this:

openssl x509 -pubkey -noout -in selfcert.crt > pubkey.cer

The file containing the public key will be pubkey.cer

If you wish to import the public and private key then you create the PKCS12 key store from the certificates:
openssl pkcs12 -export -in selfcert.crt -inkey priv.key -out certs.p12 -name my_new_partner_alias

The PKCS12 keystore now contains both public and private keys and can be imported into the keystore via the command interface or simply by replacing the existing keystore with the new one and setting the appropriate attributes in the config.xml file. It is important to use the ".p12" extension when importing certificates from a PKCS12 keystore as the importer requires the “.p12” extension to detect that you are not importing a certificate directly but rather the certificates in a PKCS12 keystore.

The OpenAS2 command processor (or remote OpenAS2 app) import command for a PKCS12 keystore would be in this format:

cert import <alias> <path+filename> <keystore password>

4.3.2. Supporting Multiple Private Certificates

In the case where you need to support multiple certificates such as when one partner needs SHA1 and another needs SHA256 or when you want to set up different certificates per partner, follow these steps below.

The key to supporting multiple certificates is ensuring you use a separate as2_id and x509_alias attribute.

In the partnership.xml you would add another partner element pointing to a different certificate.

If for example you have a <partner> element definition for your company as below:

<partner name="MyCompany" as2_id="MyCompany_OID" x509_alias="MyCompanyCert" email="me@MyCompany.com"/>

For each additional certificate you support, you then add another <partner> element. If for instance you have SHA1 already deployed and working with existing partners and you create a SHA256 certificate to support a new partner, you add a new <partner> element something like this:

<partner name="MyCompany256" as2_id="MyCompany2_OID" x509_alias="MyCompanyCert256" email="me@MyCompany.com"/>

In your partnership definition for the partners using the SHA256 certificate you set the "sender" and "receiver" attribute as appropriate to point to the correct partner definition ("MyCompany256" per the example above) along with changing the SHA1 to SHA256 in the other relevant attributes as shown in the snippet below.

   <partnership name="MyCompany256-to-MyPartner256">

        <sender name="MyCompany256"/>

        <receiver name="MyPartner256"/>

        <attribute name="protocol" value="as2"/>

        ...

    </partnership>

 

Import the new certificate into the existing p12 keystore using the alias as defined in the x509_alias attribute above ( "MyCompany2Cert256" ) and send the partner the matching public key for the new certificate along with the as2_id "MyCompany256_OID" that they will need to use so you can differentiate your target definition in the partnership file containing the SHA1 certificate from the SHA256 certificate.  See the previous section for importing certificates into your existing keystore.

4.4. Logging System

Logging supports 6 levels that can be controlled by configuration. The logging output can be directed to to multiple destinations including:

All log classes can be overridden or custom logger classes can be coded and included via confioguration

 

4.4.1. Log Level Configuration

The logging system supports the use of either or both the commons-logging.properties file or a file named openas2log.properties to control the logging level. Properties in openas2log.properties will override commons-logging.properties entries. There is a commons-logging.properties file in the bin directory which is part of the classpath specified in the script file described in the section on running the application.

 

The properties in the openas2log.properties file should be prefixed by “org.openas2.logging.

The following are the logging levels supported by the application in order of lowest(finest) to highest:

"TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL"

The logging levels are turned off by specifying the level you want on and all other levels higher than that level will also be turned on.

The default level is INFO and therefore WARN, ERROR and FATAL are also turned on by default.

By adding a property level=DEBUG in the common-logging.properties file will result in DEBUG logging being enabled along with INFO, WARN, ERROR and FATAL

The same can be achieved by adding org.openas2.logging.openas2log.level=DEBUG in the openas2log.properties file.

4.4.2. Email Logging Configuration

The email logger uses the javax mail API to send ERROR level log messages. Some of the basic email configuration parameters are supported via config in the config.properties file as indicated in the appendix. The rest of the mail properties as listed in the Javamail API  can be set by passing them as system properties on the command line by modifying the start-openas2.sh or start-openas2.bat file as appropriate or using the javax.mail.properties.file attribute on the email logger element.

 

The configuration values can overwrite each other depending on the source of the configurtion value. The order of priority is as follows:

  1. 1.values set in the logger element attributes  

  2. 2.entries in the file identified by javax.mail.properties.file  

  3. 3.entries using system properties 

 

For example, to pass the port for connection you could add this to the command line: -Dmail.smtp.port=529

 

To point to a properties file containing all the relevant information you would add something like this:

                <logger classname="org.openas2.logging.EmailLogger"

                        javax.mail.properties.file="%home%/java.mail.properties"

                        from="openas2"

                       

 

4.5. MDN Configuration

MDN's can be sent synchronously or asynchronously. By default the system will use synchronous MDN mechanism. Per the AS2 specification, an MDN will only be sent on receipt of an AS2 message if the “Disposition-Notification-Toheader is present in the received message with a non-empty value. Although this value is specified to be configured with an email address, it is not utilized for any purpose in the AS2 protocol other than to indicate an MDN is required so can in fact be any random string. To set the  “Disposition-Notification-To“ header in an outbound message, the “as2_mdn_to” attribute must be set on the partnership.

The other attribute that must be set is the “as2_mdn_options”. This defines the encryption algorithm and other MDN settings as specified by the AS2 protocol and the value entered for this attribute will be sent in the “Disposition-Notification-Options” header of the AS2 message. Generally changing the encryption algorithm to suit the trading partner should be sufficient on this attribute.

4.5.1. Asynchronous MDN Receiver Configuration

In order to specify an asynchronous MDN response from a partner requires setting the following attribute on the partnership element in the partnership configuration:

Receiving an asynchronous MDN  requires the “AS2MDNReceiverModule”  module. This module declaration requires a port parameter in addition to the class and can be entered as a child member of the processor node in the config file as shown below:

<module classname="org.openas2.processor.receiver.AS2MDNReceiverModule" port=”10081” />

4.5.2. Asynchronous MDN Sender Configuration

Sending an asynchronous MDN  requires the “AsynchMDNSenderModule”  module. This module declaration does not require any parameters other than the class and can be entered as shown below as a child member of the processor node in the config file:

<module classname="org.openas2.processor.sender.AsynchMDNSenderModule" />

4.6. Configuring HTTPS Transport

HTTPS transport using SSL is configured separately for inbound and outbound connectivity.

4.6.1. Inbound Transfers

Configuration for inbound is in the config.xml file. The requirements for receiving AS2 files using HTTPS are:

The key attributes that configure HTTPS are:

See the appendix for details on the attributes.

4.6.2. Outbound Transfers

The partnership definition for the connection URL will also have to be set to the appropriate host name.

The key attributes that configure HTTPS are:

 

If asynchronous MDN is in use and requires HTTPS then a As2MDNReceiverModule module needs to be configured in the same way as for the As2ReceiverModule class above.

If the target system being connected to uses self signed certificates, the following system property will have to be passed to the application in the java command line with a comma separated list (no spaces before or after comma) of the “Common Name” (CN) in the self signed certificate that will be returned by the target system:

-Dorg.openas2.cert.TrustSelfSignedCN=<Common.Name1>,<Common.Name2>,…

4.7. Message State Tracking

As of version 2.1.0 the system will track key events in the message transmission and reception process and write them to an embedded H2 database. The database default location is:

<install_dir>/config/DB

The database can be accessed by a JDBC client whilst the OpenAS2 app is running using the parameters shown in the table below.

Item

Default Value

Database name

openas2

Database user name

sa

Database password

OpenAS2

JDBC connect string

jdbc:h2:

There is a file named db_ddl.sql file located in the config folder that can be used to create the necessary table structure if your DB becomes corrupted. The simplest way to recreate the database table is using this command whilst OpenAS2 is running:

java -cp [path to OpenAS2 install]/lib/h2-1.4.192.jar org.h2.tools.RunScript -user sa -password OpenAS2 -url jdbc:h2:tcp://localhost:9092/openas2 -script [path to OpenAS2 install]/config/db_ddl.sql

The above is for the version of H2 deployed with OpenAS2 version 2.1.0. If you use a different version of H2 then change the jar name to reflect this.

5. Running OpenAS2

OpenAS2 can be started from the command line in any operating system that supports Java or can be configured to run as a daemon using the appropriate mechanisms for the operating system.

The default deployment for OpenAS2 has a console logger enabled which means that all logging will be visible in the command line window that OpenAS2 is started from. The server can also be configured from the command line once the application is running by simply typing in commands once it has started. Because the logging will appear in the window it may make command entry difficult if there are active transfers at the time you try to enter commands and it may be desirable to switch off the console logger if you have no need for it.

5.1. Starting OpenAS2

The default install of the application is as in the figure below from a windows PC.

 

There are 2 executable script files in the bin folder of the AS2 application root as indicated in the screenshot above:

  1. 1.start-openas2.sh – for UNIX based systems 

  2. 2.start-openas2.bat – for Microsoft Windows based system 

It is not necessary to modify these files for the default install to work. If you choose to put the config.xml file in a different location than the default then you will need to edit the appropriate script file and set the path to the config.xml file appropriately.

Simply execute the script file and an AS2 server will start up. It will create the following folders along with sub folders when it starts assuming no change to the default config:

In Microsoft Windows you should be able to double click the start-openas2.bat file and a command window will open as below.

 

For Unix based systems such as Linux and OSX, open a terminal window and change directory to the “bin” folder of the install. The start_openas2.sh file should have execute permissions in which case simply type the name and press enter. If no execute permissions are set, either set the execute permission as needed or use “sh” to run the script:

/opt/OpenAS2:>sh opensas2.sh

The output in a Unix based system will be identical to that in a Windows based system.

5.2. Command Entry

After startup of the OpenAS2 application, no command prompt is shown in the command line window initially but you can enter a command or just press <ENTER> to get a visible prompt. Typing ? Will show possible commands. Each command will list sub commands they require if you try to enter them without the appropriate parameters.

 A screenshot showing command entry is shown below.

Command Entry

 

5.3. Automated Launching As UNIX Daemon

Although the application will launch as a daemon without any change to the default config, it is recommended that the following configuration changes are made to reduce unnecessary processing by modules that are redundant in this mode and filling the system logs with unwanted logging:

  1. 1.Remove the console logger – remove the element in the <loggers> element as shown below
    <logger classname="org.openas2.logging.ConsoleLogger"/> 

  2. 2.Remove the stream command processor in the <commandProcessors> element as shown below
    <commandProcessor classname="org.openas2.cmd.processor.StreamCommandProcessor"/>
     

 

5.3.1. INIT.D Service

A sample “openas2.d” is provided in the bin directory of the install package. It provides support for starting and stopping the OpenAS2 application as a daemon using the init.d mechanism. Use the appropriate tool for the NIX operating system you are using to install the script in the /etc/init.d folder and create the soft links to launch the OpenAS2 application when the system starts.

First modify the openas2.d file to reflect the path where you have installed OpenAS2 then follow one of the options below.

On Redhat based systems as root:

$ cp <srcDir>/bin/openas2.d /etc/init.d/

$ chkconfig --add openas2.d

$ chkconfig --level 2345 openas2.d on

On Debian/Ubuntu based systems as root:

$ cp <srcDir>/bin/openas2.d /etc/init.d/

$ chmod 750 /etc/init.d/openas2.d

$ update-rc openas2.d defaults

5.3.2. SYSTEMD Service

A sample file openas2.service is provided in the bin folder of the install package.

First modify the openas2.d file to reflect the path where you have installed OpenAS2 then follow the steps below.

$ cp <srcDir>/bin/openas2.service /etc/systemd/system/

$ systemctl daemon-reload

$ systemctl enable openas2.service

Test that it works using the below commands:

 
$ systemctl enable openas2.service
$ systemctl start openas2.service
$ systemctl stop openas2.service

 

6. Testing OpenAS2 Transfers

The default configuration of the OpenAS2 configuration is set up for two partners named “OpenAS2A” and “OpenAS2B”. The system will effectively send messages to itself between the 2 configured partners. You can simply start the OpenAS2 server without any changes and then copy a file into the appropriate outbox as defined by the relevant module using the  org.openas2.processor.receiver.AS2DirectoryPollingModule classes “outboxdir” attribute to send  the file to the desired partner.

The default configuration provides for 2 partners OPENAS2A and OPENAS2B and will create outbox folders <installDir>/data/toOpenAS2A and <installDir>/data/toOpenAS2B for explicitly targeting a partner for any file dropped in one of those folders.

If you wish to run 2 OpenAS2 servers on the same machine then the ports on the 2nd instance of OpenAS2 as configured in the config.xml must be different to those configured on the first instance (see Application Configuration above). If using asynchronous MDN, the URL entry for the attribute “as2_receipt_option” in the partnerships.xml file for the 2nd instance must match the values configured in the 1st instances config.xml for hist name and port and vice-versa.

6.1. Using HTTPS Transport

To test on a local machine using the supplied sample self signed SSL certificate (config/ssl_certs.jks) you should create a localhost DNS entry. The sample certificate was generated for “www.openas2.localhost”.

This site will help in how to set up a local DNS: http://www.selfsignedcertificate.com/development_tips.php

The As2ReceiverModule module element should be configured correctly. The key attributes that will work with the supplied sample certificate are already in the sample config file and should just be uncommented:

The partnership definition for the connection URL will also have to be set to the appropriate host name and use “https” instead of “http”:

        <attribute name="as2_url" value="https://www.openas2.localhost:10080"/>

If asynchronous MDN is used then the as2_receipt_option attribute must be configured for SSL as well:

        <attribute name="as2_receipt_option" value="https://www.openas2.localhost.com:10081"/>

 

The following system property will have to be passed to the application in the java command line:

-Dorg.openas2.cert.TrustSelfSignedCN=www.openas2.localhost

 

If you experience problems with SSL, try adding this to the startup command in the script file: -Djavax.net.debug=SSL

7. Troubleshooting OpenAS2

This section provides some help in identifying issues with AS2 transfers or configuration and execution of the OpenAS2 application. Experience has shown that not all systems properly implement the AS2 specification or have an interpretation of the specification that is different to the OpenAS2 default implementation. To accommodate these differences, the OpenAS2 application has some configuration parameters to change the default behaviour on a per partnership basis that may help to accommodate the implementation anomalies for various other AS2 systems.

7.1. Canonicalization For MIC Algorithm

Some systems (including OpenAS2 prior to V1.3.7) do not canonicalize the MimeBodyPart as specified in the RFC when content transfer encoding is not “binary” (the OpenAS2 default is “binary” but can be set to other values using the “content_transfer_encoding” attribute on the prtnership). This manifests as errors that cause signature authentication failure that may specifically mention a mismatched MIC. To cater for this set the following attribute on the partnership:

<attribute name="prevent_canonicalization_for_mic" value="true"/>

7.2. Binary Encoding

If using a content transfer encoding algorithm other than “binary” results in authentication failures, try setting the attribute on the partnership:

<attribute name="content_transfer_encoding" value="binary"/>

7.3. HTTP Restricted Headers

Depending on the version of Java you are running, the HTTP class handling sending AS2 messages over HTTP that is part of the core Java distribution will automatically remove any restricted HTTP headers (see here for a discussion: http://stackoverflow.com/questions/11147330/httpurlconnection-wont-let-me-set-via-header).

This should not be a problem for modern AS2 implementations that OpenAS2 communicates with but there are reports that some systems respond with an HTTP 400 error code and reject the message if the “Content-Transfer-Encoding” header that is a restricted header (see section 19.4.5 here: https://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html), is not present in the HTTP headers (it is present in the mime body part headers of the AS2 message).

To solve this uncomment the line in the startup script file containing this entry

-Dsun.net.http.allowRestrictedHeaders=true

 

IMPORTANT NOTE: This change cannot be made partner specific due to the way it is implemented in Java so all configured partners will then receive restricted HTTP headers so they may fail as a result of this change. Your only way around this is to run separate OpenAS2 instances.

7.4. CMS Algorithm Protection

Some AS2 systems do not support RFC6211.

The partner system will most likely not provide detailed information that this OID is the issue unless you request detailed logging from the partner but will manifest as authentication failures of some sort. Currently known systems that do not support this are IBM Sterling Integrator.

To disable the OID from being sent add this attribute to the partnership (from a security point of view to include it wherever possible as it plugs a security issue in CMS signed messages):

<attribute name="remove_cms_algorithm_protection_attrib" value="true"/>

7.5. SSL Certificate Exceptions

Sometimes a partner uses a certificate that has intermediate providers not registered in your Java security keystore. Generally this will be manifested by an exception something like this:

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

 at sun.security.ssl.Alerts.getSSLException(Alerts.java:192)

 at sun.security.ssl.SSLSocketImpl.fatal(SSLSocketImpl.java:1917)

 at sun.security.ssl.Handshaker.fatalSE(Handshaker.java:301)

 at sun.security.ssl.Handshaker.fatalSE(Handshaker.java:295)

 at sun.security.ssl.ClientHandshaker.serverCertificate(ClientHandshaker.java:1369)

In this case you will need to set up a local trusted certificate provider keystore containing the root or chained (intermediate) certificates that are missing.

Steps:

  1. 1.Run the class embedded in the OpenAS2 library jar:

    java -cp <pathToOpenAS2LibFolder>/openas2-server.jar CheckCertificate <host name>[:port] <localKeystoreFile> [passphrase] 

    "<host name>[:port]" should be the same as what you have in the partnerships "as2_url" attribute EXCLUDING the "https://" 

 

  1. "<localKeystoreFile>" is the name you want to give to your local keystore (e.g jssechaincerts)

    "[passphrase]" is the password for the keystore - it will default to "changeit" if you do not provide one`

    NOTE: If there is no existing keystore you want to add it to then leave out the password otherwise it will throw an error. You can use the keytool utility that comes with java to change the keystore password if you wish but since it does not contain any private keys there is little point in changing the password but if you do then you will have to pass the new password in to the OpenAS2 app using the javax.net.ssl.trustStorePassword property.

    If the class only receives a single certificate as response from the remote host it generslly indicates that the root certificate is not trusted and will need installing into a keystore for use by the OpenAS2 application.
    The output from the class should make it clear it was unable to successfully complete an SSL handshake and it will import the certificate (root or chain  as necessary) into the keystore.

  2. 2.Add the local cert store to the OpenAS2 startup by adding this to the startup command in the relevant batch file you are using to start OpenAS2:
    -Djavax.net.ssl.trustStore=<pathToKeystore>/<localKeystoreFile> 

 

7.6. Java Versions Prior To 1.6

Prior to java 1.6, the Javabeans Activation Framework is NOT included in the standard Java install. Download the 1.1.1 version and extract from the zip file from this web page: http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-java-plat-419418.html#jaf-1.1.1-fcs-oth-JPR
The activation.jar must be placed into the “lib” folder of the OpenAS2 server install and added to the class path in the shell or batch file as appropriate.

7.7. Mime Body Part Logging

Sometimes it may be necessary to see what is actually in the mime body parts received from a partner. OpenAS2 provides a mechanism to enable logging of either received message mime body parts or receieved MDN mime body parts. These are enabled using OpenAS2 startup variables in the startup script in combination with TRACE level logging. Both the DOS and Unix scripts provide these variables but are commented out near the top of the batch file and you can simply uncomment and start the application.

IMPORTANT: this could produce large log files so use sparingly and disable as soon as possible.

The startup variables are:
logRxdMsgMimeBodyParts=true
logRxdMdnMimeBodyParts=true

7.8. TLSv1.2

It appears that although Java7 does support TLSv1.2 it is not enabled by default (refer here: https://blogs.oracle.com/java-platform-group/entry/diagnosing_tls_ssl_and_https)

If you need to use the protocol, add the following to the top of the batch shell script that starts OpenAS2:

Windows: set EXTRA_PARMS=%EXTRA_PARMS% -Dhttps.protocols=TLSv1.2

Linux/Unix/OSX: EXTRA_PARMS=$EXTRA_PARMS -Dhttps.protocols=TLSv1.2

8. Partner AS2 Compatibility Settings

The below table provides configuration settings for other AS2 systems that are known to work based on user feedback.

PLEASE FEEL FREE TO PROVIDE SETTINGS FOR ANY SYSTEMS THAT REQUIRE A CHANGE FROM THE DEFAULT PROVIDED WITH THE OPENAS2 INSTALL PACKAGE TO COMMUNICATE WITH OTHER AS2 SYSTEMS.  

Where the field is left blank, the setting is unknown and the default that comes with OpenAS2 will probably work.

AS2 System

Allow Restricted Headers
(startup script property: sun.net.http.allowRestrictedHeaders)

Prevent Canonicalization For MIC

(partner attribute: prevent_cononicalization_for_mic)

Remove CMS Algorithm Protection
(partner attribute:  remove_cms_algorithm_protection_attrib)

IBM Sterling

false

 

true

IBM Datapower

false

 

true

Mendelson

false

true

 

Seeburger

?

?

?

Oracle Integration B2B

false

false

false

 

9. Remote Control

By default the OpenAS2 server application will start up a command processor as a socket listener allowing remote connection to the OpenAS2 server to execute commands. The OpenAS2 remote application is part of the application package but is not necessary to use it if you have no remote access requirement and should be disabled in the config.xml file if not using it by removing or commenting out the <commandProcessor> element with classname value org.openas2.cmd.processor.SocketCommandProcessor  

You can set the port that the command processor listens on using the portId parameter.  

        <commandProcessor classname="org.openas2.cmd.processor.SocketCommandProcessor"  portId="14321"  userid="userID" password="pWd"/>

The remote control application will need to connect to the specified port with the specified user ID and password.

The connection uses an anonymous secure socket cipher and may require changing this if your Java implementation does not support the default cipher which is TLS_DH_anon_WITH_AES_256_CBC_SHA for the latest release. This cipher is not available in older Java versions and it may be necessary to switch to SSL_DH_anon_WITH_RC4_128_MD5

To switch cipher you will need to start the OpenAS2 server and the remote command client passing the cipher name as a system property using the -D switch that can be added to the batch script that starts the application. The property must be named  “CmdProcessorSocketCipher”.

e.g java -DCmdProcessorSocketCipher=SSL_DH_anon_WITH_RC4_128_MD5 …

10. Dynamic Variables

Variables can be used in configuration files for real time replacement of strings. Some variables are specific to certain processor modules. The variables used in the configuration files are as follows:

    1. 1.$msg.sender.as2_id$ - retrieves the AS2 ID of the sender of the message 

    2. 2.$msg.receiver.as2_id$ - retrieves the AS2 ID of the receiver of the message 

    3. 3.$msg.attributes.yyy$ - used to access any attribute on the message where the attribute identifier is used in place of “yyy
      for example  

    4. 4.$msg.headers.yyy$ - used to access any header on the message where the header identifier is used in place of “yyy 

    5. 5.$msg.content-disposition.yyy$ - used to access any content-disposition attribute in the message content disposition where the attribute identifier is used in place of “yyy
      Some attriutes commonly found in an AS2 message content disposition include 

 

11. Appendix: config.xml file structure

 

12. Appendix: partnership.xml file structure

This file describes your company and your trading partners. This file requires modification to work with your application

13. Appendix: command.xml file structure

List of commands available to the OpenAS2 server Application.