OpenAS2 Documentation

This is a conspect of the OpenAS2 documentation “OpenAS2 Server Application”, which can be found here:

• in PDF (see also)
• in HTML (seems to be a little bit older than PDF-version)

• The AS2 implementation conforms with RFC4130 supporting the 1.1 specification.

• EDI - Electronic Data Interchange
• MDN - Message Disposition Notification
• JCE - Java Cryptography Extension

The OpenAS2 application provides the following mechanisms for sending and receiving files:

• Files to be sent are placed in folders that are detected by polling modules.
  • These files and sent to the relevant AS2 partner using AS2 protocol.
    • target partner is determined by
      • folder name
      • file name patterns
    • If configured for MDN response, the MDN response will be stored in a folder defined by the MDN storage module
  • Received files are placed in a location defined in the message storage module
    • Default configuration creates dedicated inbox folders per partnership
    • If configured for an MDN response, the application will automatically send an MDN that is by default signed.

All sent and received files are tracked in a database tracking system that updates the progress of the message state in the database at key points in the life cycle of message.

• 1. Java
• 2. OpenAS2 package (https://sourceforge.net/projects/openas2/files)
• 3. Java Cryptography Extension (JCE) policy files
  • Download from Oracle (Oracle user account necessary!)

• 1. Unzip OpenAS2 package
  • Normally under C:\OpenAS\
• 2. Install proper JCE policy files
  • Copy local_policy.jar and US_export_policy.jar to <JAVA_HOME>/lib/security

• Increase heap space
  • -Xmx parameter
• Set G1 garbage collector
  • –XX:+UseG1GC

OpenAS2 server uses four files for configuration:

• config.xml
  • types of modules that are started
  • the logging systems
  • command processors
  • global properties
• partnership.xml
  • partners and partnerships
  • signing and encryption algorithms
  • message compression
  • MDN handling
• as2_certs.p12
  • a PKCS12 keystore which stores SSL certificates to secure communication for all partners
  • contains:
    • primary key of your company
    • public key for all partners
• commands.xml
  • contains commands which the application will support
  • normally this file should NOT be modified

• The system will monitor the partnership configuration file and the as2 certificates file for any changes to the files after the application has started.
• the config.xml file is NOT monitored for changes and will require a restart of the application for any changes.

The folder containing the config.xml file defines the home configuration parameter %home%. All files can be referenced relative to this parameter. This means the default home location for %home% with the current default OpenAS2 folder structure will be [InstallDir]/config

The application supports 2 ways of passing in configuration parameters:

For instance, the password for the certificates file could be set like this in the config.xml:

<certificates classname="org.openas2.cert.PKCS12CertificateFactory"
filename="%home%/as2_certs.p12”
password="$ENV{AS2_CERTIFICATE_PWD}"
interval="300"/>

Then set the password in the environment as below before running the startup script:

export AS2_CERTIFICATE_PWD=my_secret_password

Environment variable replacement occurs BEFORE system properties so you can use environment variables to set properties in the config.xml which in turn are used for other config values. For instance, you can change this in the <properties> section of the config.xml:

<properties storageBaseDir="%home%/../data"

To:

<properties storageBaseDir="$ENV{storageBaseDir}"

Minimum required setting in a partnership is to enable a poller:

<pollerConfig enabled="true"/>

The default configuration (set in config.xml) will be overriden by this setting.

If you want to override any of the attributes from the pollerConfigBase element, you simply put the relevant attribute you want to override into the pollerConfig element in the partnership.

The directory polling module can be configured to only use files with a specific extension and/or exclude files with a specific extension and/or exclude files based on a regular expresssion match on the entire file name. The following attributes are relevant:

• fileextensionfilter
• fileextensionexcludefilter
• filenameexcluderegexfilter

Example:

fileextensionfilter="doc, docx, txt, edi"
fileextensionexcludefilter="tmp"
filenameexcluderegexfilter=".+Tmp[.]{1}.+"

The attributes are evaluated as an AND function so if any of the filters excludes a file it ignores the other filters and excludes the file from processing.

To receive and persist files over AS2 from a partner the following should be configured:

• network receiver module
• file handler module

My current configuration:

      <module enabled="$properties.module.MessageFileModule.enabled$"
              classname="org.openas2.processor.storage.MessageFileModule"
              filename="$properties.module.MessageFileModule.filename$"
              header="$properties.module.MessageFileModule.header$"
              protocol="as2"
              tempdir="$properties.storageBaseDir$/temp"/>
      <module enabled="$properties.module.AS2ReceiverModule.http.enabled$"
              classname="org.openas2.processor.receiver.AS2ReceiverModule"
              port="$properties.module.AS2ReceiverModule.http.port$"
              errordir="$properties.storageBaseDir$/inbox/error"
              errorformat="sender.as2_id, receiver.as2_id, headers.message-id"/>

config.xml :

   <partnerships classname="org.openas2.partner.XMLPartnershipFactory"
                 filename="$properties.partnership_file$"
                 interval="120"/>

Where $properties.partnership_file$ configured as %home%/partnerships.xml.

So all other stuff is configured in partnerships.xml.

Each partner will require the following entries in the file:

• a <partner> element – key information defining the partner
• a <partnership> element - key information for defining a partnership between 2 partners
  • Separate <partnership> elements are required for inbound and outbound data for a specific partner pairing.

• <partner> element requires 3 attributes:
  • name - the key to connect partnerships to a partner definition
  • as_id - the AS2 identifier that uniquely identifies the partner in the AS2 protocol
    • 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.
  • x509_alias - X.509 certificate alias
    • can be verified with cert list command. The certificate names MUST match the X.509 certificate alias in the partnerships.xml

The <partnership> element (in partnerships.xml) identifies a specific direction of AS2 message transfer from one partner to another.

The <partnership> child elements that are necessary to properly configure a partnership:

• <sender name=“xxx”> - identifies the sending partner definition such that xxx must match the “name” attribute of a <partner> element
• <receiver name=“yyy”> - identifies the receiving partner definition such that yyy must match the “name” attribute of a <partner> element
• <as2_url> - a fully qualified URI that provides the connection string to the remote partner for sending AS2 messages. If sending to another OpenAS2 server then the port number must match the value configured in the config.xml file of the remote OpenAS2 server.
  • NOTE: This attribute supports Dynamic Variables and can be used to target modify the URL dynamically. See the section “Dynamic AS2 Url Configuration” for more information.
• <as2_mdn_to> - neccesary if an MDN response is required and can be any random string but is most commonly configured with an email address

The partnership element attribute values supports using a key value string that can be used to reference other attributes within the same partnership element to ensure consistent configuration. The value field in an attribute can use the format $attribute.XXX$ to reference the value of the attribute name “XXX”.

Example:

<attribute name="some_attrib_name" value="My value: $attribute.other_attrib"/>
<attribute name="other_attrib" value="bingo"/>

Signing is controlled by the “sign” attribute in the “partnership” element. Remove this element from the partnership to send a message without signing.

Supported signing algorithms are: md2, md5, sha1, sha224, sha256, sha384, sha512

Encryption is controlled by the “encrypt” attribute in the “partnership” element. Remove this element from the partnership to send a message without encryption.

Supported algorithms are: 3des, cast5, rc2_cbc, aes128, aes192, aes256

The MDN must be signed using the same algorithm that the sent message was signed with. The recipient partner is told the signature algorithm via a field in the as2_mdn_options attribute and the value uses the $attribute.sign$ dynamic variable to ensure it matches the “sign” attribute as shown in the example below:

<attribute name="as2_mdn_options"
value="signed-receipt-protocol=optional, pkcs7-signature;
signed-receipt-micalg=optional, $attribute.sign$"/>

If you need to send an unsigned MDN then set the attribute on the partnership as below:

<attribute name="as2_mdn_options" value="none"/>

It is possible to reject unsigned messages.
Global configuration (in config.xml):

reject_unsigned_messages="true"

Partnership-specific configuration (through an attribute of partnership tag in partnerships.xml):

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

There are 3 ways to set message attributes that can be used in the for dynamic URL’s:

• 1. Parsed from file name
  • typically used for a generic directory polling module)
• 2. Explicitly set in the directory polling modules “defaults” attribute.
  • Using this mechanism you would need different directories (ie multiple DirectoryPollingModule instances) per URL you want to use.
• 3. Combination of both methods above

The message ID used for uniquely identifying the message sent can be configured

• globally (in config.xml):

<properties storageBaseDir="%home%/../data"
  log_date_format="yyyy-MM-dd HH:mm:ss.SSS"
  sql_timestamp_format="yyyy-MM-dd HH:mm:ss.SSS"
  as2_message_id_format="$date.yyyyMMddHHmmssZ$-$rand.123$-$msg.sender.as2_id$_$msg.receiver.as2_id$_$msg.attributes.filename$"
...               

• partnership-specific (in partnerships.xml). Example:

<partnership name="MyCompany-to-PartnerA">
  <sender name="MyCompany"/>
  <receiver name="PartnerA"/>
  <attribute name="protocol" value="as2"/>
  <attribute name="content_transfer_encoding" value="binary"/>
  <attribute name="as2_message_id_format" value="ACME-$date.yyyyMMddHHmmssZ$-
$rand.UUID$"/>

The same can be done with the MDN message ID:

• globally (in custom.xml) with property as2_mdn_message_id_format
• partner-specific (in partnerships.xml) with partnership attribute as2_mdn_message_id_format

It is possible to override the default value of Content-Type MIME header used in the body MIME part using the content_type attribute.

<attribute name="content_type" value="application/EDIFACT"/>

As of version 1.3.7, the default content transfer encoding uses binary if not explicitly overwritten in the configuration. The default can be changed using the content_transfer_encoding attribute in the partnerships.xml file.

The currently supported encoding algorithms are:

• MD5
• SHA1
• SHA224
• SHA256
• SHA384
• SHA512
• CAST5
• 3DES
• IDEA
• RC2_CBC
• AES128 (CBC mode)
• AES192 (CBC mode)
• AES256 (CBC mode)
• AES256_WRAP

• 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.

Mime headers can be added to the outermost Mime body part for outbound messages and additionally added to the HTPP headers.
…

…

• Delimiter Mode
• Regular Expression Mode

…

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:

• attribute_names_from_filename - when added to a partnership it must contain a list of comma separated attribute names
• attribute_values_regex_on_filename - defines the regular expression

The extracted name/value pairs can then be referenced in config using the format: $attributes.<attribute name>$

…

For partners that require HTTP authentication when connecting to their system use the following parameters in the partnership:

• http_user – the name of the HTTP user for authentication
• http_password – the name of the HTTP password for authentication

For sending files this is in the partnership where the partner is the receiver.

IMPORTANT: This section does NOT cover SSL certificates. SSL certificates are a completely separate set of certificates to the AS2 certificates (for SSL config for HTTPS see the appropriate section in this document)

Two different sets of certificates used in OpenAS2 and they are stored separately:

• AS2 (supports X.509 certificates for sending and receiving)
• SSL (for HTTPS)

Import the private and public keys and associated certificate into the OpenAS2 keystore and share the public key with the partner(s).

All trading partners will need to send you their public certificate that must be imported into the AS2 certificate keystore under a unique alias that identifies the particular trading partners public key in your keystore.

Encryption is done using the public key of an X.509 certificate and signing uses a private key. All certificates are stored in a single PKCS12 keystore and identified by their unique alias.

The communication flow for example for communication between “MyCompany” and “PartnerA”:

• “MyCompany” side
  • fetch file to send
  • encrypt the message with “Partner” public key
  • sign the message with “MyCompany” private key
  • transmit message
• “PartnerA” side
  • verify signature with “MyCompany” public key
  • decrypt with “PartnerA” private key
  • extract file from received message

In config.xml:

   <certificates classname="org.openas2.cert.PKCS12CertificateFactory"
                 filename="$properties.as2_keystore$"
                 password="$properties.as2_keystore_password$"
                 interval="300"/>

Three strategies:

• 1. Command line scripts provided with OpenAS2 installation
  • <INSTALL_DIR>/bin/import_public_cert.sh
  • <INSTALL_DIR>/bin/import_alias_from_keystore.sh
• 2. Use a third party tools (like Portecle, OpenSSL or Java Keytool)
• 3. Use the OpenAS2 certificate management commands provided in the console command processor or via remote command processor
  • this way is good when OpenAS2 is running as service (because the console is not available)

You can have:

• multiple certificates per trading partner (each partner is sent a unique certificate and there is a matching private and public key for each certificate in your keystore).
• single certificate for all trading partners (all partners are sent the same public key and there is only one private key in your keystore to match).

For increased security it is highly recommended you use multiple certificates.

Third party tools can be used for this purpose:

• KeyStore Explorer - seems to be the best/simplest tool with GUI
• Portecle - also nice tool with GUI
• OpenSSL → normally should be compiled by the user(!), but fortunately there are also already compiled packages like OpenSSL binaries compiled for Windows

This documentation describes only OpenSSL commands. But the same can be done with other tools (e.g. with KeyTool Explorer).

The other option is to use scripts that are included in the installation package. For example this windows DOS shell script:

<INSTALL_DIR>/bin/gen_p12_key_par.bat

Running the script without arguments will show a usage description.

The public key must be exported from PKCS12 keystore that you created when generating a self signed certificate as described in the previous section. You can export the public key using this command against the keystore:

openssl pkcs12 -clcerts -nokeys -out <output file> -in <keystore file>

To import certificates contained in the PKCS12 keystore with the help of OpenAS2 command processor (or remote OpenAS2 app):

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

It is also possible to use third party keystore manager for this task. Then simply replace existing keystore with the new one (which should contain the new certificates).

IMPORTANT: the file should have the extension “.p12”

The key to supporting multiple certificates for the same partner is ensuring you use a separate as2_id and x509_alias attribute (⇒creating multiple partners).

Use x509_alias_fallback attribute for it:

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

…

The certificate(s) that you will obtain from your partner(s) will need to be imported into the keystore you have created for your own certificate. Your partner should send you the public key for their certificate and should be a single file usually with a “.cer” or “.der” extension.

To import partner public keys into the keystore you can either use:

• the OpenAS2 command interface
• a 3rd party tool
  • KeyStore Explorer can do it (I tested it)

If your partner certificate has expored or is about to expire and they send you a new certificate, you will need to delete the existing one from the keystore before importing the new one. The OpenAS2 command processor (or remote OpenAS2 app) import command for importing your partners certificate would be in this form:

cert delete <alias>

The OpenAS2 command processor (or remote OpenAS2 app) import command for importing your partners certificate would be in this form:

cert import <alias> <path+filename>

The script uses the Java keytool command and can be found here:

• <INSTALL_DIR>/bin/import_public_cert.sh — nix shell script
• <INSTALL_DIR>/bin/import_public_cert.bat — windows DOS shell script

</code>

…

• Do the “My Certificates” process first followed by the “Partner Certificates” when you receive partner certificates.
• It is recommended that you create separate certificates per trading partner as this makes it much easier to manage upgrades when the certificate expires as you will only have to coordinate with 1 partner at a time.

… Here is described ho to import the own certificates with the help of shell scripts provided with OpenAS2 installation. I think it is possible to do the it with the help of 3rd party tools (like KeyTool Explorer) …

… Here is described ho to import the partner certificates with the help of shell scripts provided with OpenAS2 installation. I think it is possible to do the it with the help of 3rd party tools (like KeyTool Explorer) …

Loggers are configured in the config.xml file using the “loggers” element.

The logging output can be directed to to multiple destinations including:

• System console
• File system log files
• Email – log messages are emailed to a configured email address.
• Socket – log messages are written to a socket supporting remote logging
• Sentry – support for the Sentry logger that provides logging management for exceptions

The console logger is configured using this entry in the <loggers> element:

<logger classname="org.openas2.logging.ConsoleLogger" />

The file logger is configured using this entry in the <loggers> element:

<logger classname="org.openas2.logging.FileLogger" filename="%home%/../logs/log-$date.yyyyMMdd.txt" />

…

…

…

The default format for the timestamp prefixed to all log entries is the international standard including millisecond precision as of version 2.3.1 (yyyy-MM-dd HH:mm:ss.SSS).
The format can be changed by setting the attribute named log_date_format in the properties element of the config.xml with the desired format.

…

MDN's can be sent or received synchronously or asynchronously.

• For sending MDN’s, OpenAS2 will automatically use the mode requested by the sending partner.
• For receiving MDN responses from your partner, the default configuration for a partnership will use the synchronous MDN mode. To set a particular partnership to request the reveiver partner to respond with an asynchronous MDN, the as2_mdn_options and as2_receipt_option attributes must be set on the partnership:

<attribute name="as2_mdn_options" value="signed-receipt-protocol=optional,pkcs7-signature;signed-receiptmicalg=
optional,$attribute.sign$"/>
<attribute name="as2_receipt_option" value="$properties.as2_async_mdn_url$"/>

Per the AS2 specification, an MDN will only be sent on receipt of an AS2 message if the “Disposition-Notification-To” header 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.

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

• as2_receipt_option – set to the URL of the asynchronous MDN receiver to target the asynchronous MDN receiver module configured in the config file (ie. this is the URL that the partner will send the MDN to).
  • The value set in this attribute will be sent in the “Receipt-Delivery-Option” header of the AS2 message to the trading partner.
  • For testing using the default config file that comes with the OpenAS2 installation package, set this to: http://localhost:10081

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” />

Sending an asynchronous or synchronous MDN requires the “MDNSenderModule” module. Thismodule 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.MDNSenderModule"/>

• HTTPS transport using SSL is configured separately for inbound and outbound connectivity.
• You can have both HTTP and HTTPS running concurrently but they must be configured on different ports.
• If you are sending messages to your partner or your partner is using Asynchronous MDN to send messages to you, you do NOT need to obtain SSL certificates from your partner for HTTPS transport – most SSL certificate providers have their trusted certificates installed in the trusted security keystore that comes with your Java installation.
  • ⇒ so it is not necessary to obtain SSL certificates from aktivbank (because they use only synchronous MDN's and we do not receive AS2 messages from them)
    • ⇒ TODO: test it

In order to support inbound HTTP connections over HTTPS to the OpenAS2 application you will need to set up the SSL certificates.

There are 2 possible inbound connections that can be made to OpenAS2:

• 1. Partner sends files – the request is initiated by the partner and connects to your server
• 2. You send files to a partner but request an ASYNC MDN response in which case the partner initiates the MDN connection to your server to return an MDN after receiving your AS2 message

If you are NOT using ASYNC MDN mode for any outbound transfers and you are NOT receiving any AS2 messages that require using HTTPS ⇒ then you DO NOT need any SSL certificates.

…

The partnership definition for the connection URL to your partners AS2 receiver will also have to be set to the appropriate URL with their host name and prefixed with https:

<partnership name="MyCompany-to-PartnerB">
...
  <attribute name="as2_url" value="https://as2.partnerb.com:8443"/>
...

…

If you are not intending to receive MDN responses over HTTP then disable that module by setting it to “false”:

module.AS2MDNReceiverModule.http.enabled="false"

• NOTE: 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 (TODO: check whether it is necessary for aktivbank):

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

There are 2 executable script files in the bin folder of the AS2 application root:

• 1. start-openas2.sh – for UNIX based systems
• 2. start-openas2.bat – for Microsoft Windows based system

The startup script will create the following folders along with sub folders when it starts assuming no change to the default config:

• logs – contains the normal program logging
• data – contains all the transferred files and any AS2 specific headers associated with AS2 transfers. This folder will have a number of sub folders for outbound and inbound files for different partners

Just press <ENTER> after start of OpenAS to get a visible prompt. Typing ? will show possible commands.

The default configuration of the OpenAS2 configuration is set up for three partners named:

• MyCompany
• PartnerA
• PartnerB
  • However, PartnerB does not have a certificate set up so cannot be actively used unless you create and import a certificate for that partner.

In the default configuration:

• To send something to PartnerA simply put the file, that should be sent to the folder <INSTALL_DIR>\data\outbox\PartnerA_OID
  • In my case: C:\OpenAS2\data\outbox\PartnerA_OID

14.1. Canonicalization For MIC Algorithm 14.2. Binary Encoding 14.3. HTTP Restricted Headers 14.4. CMS Algorithm Protection 14.5. Content Length Versus Chunked 14.6. SSL Certificate Exceptions 14.7. Java Versions Prior To 1.7 14.8. Mime Body Part Logging 14.9. TLSv1.2 14.10. HTTP Read Timeout Errors 14.11. Out Of Memory And File Size Issues 14.12. File System Issues 14.13. Header Folding