Differences

This shows you the differences between two versions of the page.

--- openas2_documentation [2023/03/02 10:36] – [11.1. SSL Certificates] kalaschnikow
+++ openas2_documentation [2023/03/02 11:48] (current) – [8.4. My Certificates] kalaschnikow
@@ Line 1: / Line 1: @@
+====== OpenAS2 Documentation ======
+This is a conspect of the OpenAS2 documentation "OpenAS2 Server Application", which can be found here:
+  * [[https://raw.githubusercontent.com/OpenAS2/OpenAs2App/master/docs/OpenAS2HowTo.pdf|in PDF]] ([[https://github.com/OpenAS2/OpenAs2App/tree/master/docs|see also]])
+  * [[https://openas2.sourceforge.net/|in HTML]] (seems to be a little bit older than PDF-version)
+===== 1. Introduction =====
+  * The AS2 implementation conforms with RFC4130 supporting the 1.1 specification.
+===== 2. Glossary =====
+  * EDI - Electronic Data Interchange
+  * MDN - Message Disposition Notification
+  * JCE - Java Cryptography Extension
+===== 3. Basic Functional Overview =====
+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.
+===== 4. Installing OpenAS2 =====
+==== 4.1 System Requirements ====
+  * 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!)
+==== 4.2 Installing Application ====
+  * 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''
+==== 4.3 Tuning Java ====
+  * Increase heap space
+    * ''-Xmx'' parameter
+  * Set G1 garbage collector
+    * ''–XX:+UseG1GC''
+===== 5. Configuration overview =====
+==== 5.1. Key Configuration Concepts ====
+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
+==== 5.2. Dynamic Configuration Changes ====
+  * 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.
+==== 5.3. “home” Configuration Parameter ====
+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''
+==== 5.4. Passing In Configuration Values ====
+The application supports 2 ways of passing in configuration parameters:
+=== 5.4.1. Environment Variables ===
+For instance, the password for the certificates file could be set like this in the ''config.xml'':
+<code>
+<certificates classname="org.openas2.cert.PKCS12CertificateFactory"
+filename="%home%/as2_certs.p12”
+password="$ENV{AS2_CERTIFICATE_PWD}"
+interval="300"/>
+</code>
+Then set the password in the environment as below before running the startup script:
+<code>
+export AS2_CERTIFICATE_PWD=my_secret_password
+</code>
+=== 5.4.2. System Properties ===
+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'':
+<code>
+<properties storageBaseDir="%home%/../data"
+</code>
+To:
+<code>
+<properties storageBaseDir="$ENV{storageBaseDir}"
+</code>
+===== 6. Application Configuration =====
+==== 6.1. System Level Properties ====
+==== 6.2. Sending Files ====
+=== 6.2.1. Directory Polling Configuration Attributes ===
+=== 6.2.2. Generic Send Directory Poller ===
+=== 6.2.3. Partnerships XML Defined Directory Poller ===
+Minimum required setting in a partnership is to enable a poller:
+<code>
+<pollerConfig enabled="true"/>
+</code>
+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.
+=== 6.2.4. Config XML Defined Directory Poller ===
+=== 6.2.5. Restricting Directory Files By Extension Or Name ===
+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:
+<code>
+fileextensionfilter="doc, docx, txt, edi"
+fileextensionexcludefilter="tmp"
+filenameexcluderegexfilter=".+Tmp[.]{1}.+"
+</code>
+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.
+=== 6.2.6. Auto Splitting Large Files ===
+==== 6.3. Receiving Files ====
+To receive and persist files over AS2 from a partner the following should be configured:
+  * network receiver module
+  * file handler module
+My current configuration:
+<code>
+      <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"/>
+</code>
+=== 6.3.1. Overriding Storage Location Per Partnership ===
+=== 6.3.2. Providing Default File Name ===
+==== 6.4. AS2 Message Tracking ====
+==== 6.5. Overriding Certificate Store Password ====
+==== 6.6. Resend Retry Configuration ====
+==== 6.7. Asynchronous MDN Response Wait Time ====
+==== 6.8. File Name Parsing ====
+==== 6.9. Using A Proxy Server ====
+==== 6.10. Health Check For High Availability Deployment ====
+=== 6.10.1. Healthcheck URI On Existing AS2 Listener ===
+=== 6.10.2. Dedicated Healthcheck Module ===
+=== 6.10.3. HTTP User Agent Header ===
+===== 7. Partner Configuration =====
+''config.xml'' :
+<code>
+   <partnerships classname="org.openas2.partner.XMLPartnershipFactory"
+                 filename="$properties.partnership_file$"
+                 interval="120"/>
+</code>
+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.
+==== 7.1. Partner Definition ====
+  * ''<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''
+==== 7.2. Partnership Definition ====
+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:
+<code>
+<attribute name="some_attrib_name" value="My value: $attribute.other_attrib"/>
+<attribute name="other_attrib" value="bingo"/>
+</code>
+=== 7.2.1. Signing ===
+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
+=== 7.2.2. Encryption ===
+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
+=== 7.2.3. MDN MIC Algorithm ===
+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:
+<code>
+<attribute name="as2_mdn_options"
+value="signed-receipt-protocol=optional, pkcs7-signature;
+signed-receipt-micalg=optional, $attribute.sign$"/>
+</code>
+If you need to send an unsigned MDN then set the attribute on the partnership as below:
+<code>
+<attribute name="as2_mdn_options" value="none"/>
+</code>
+=== 7.2.4. Reject Unsigned Messages ===
+It is possible to reject unsigned messages.\\
+Global configuration (in ''config.xml''):
+<code>
+reject_unsigned_messages="true"
+</code>
+Partnership-specific configuration (through an attribute of ''partnership'' tag in ''partnerships.xml''):
+<code>
+<attribute name="reject_unsigned_messages" value="true"/>
+</code>
+=== 7.2.5. Dynamic AS2 Url Configuration ===
+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
+==== 7.3. Example Multi-Partner Configuration ====
+==== 7.4. Configuring the AS2 Message ID ====
+The message ID used for uniquely identifying the message sent can be configured
+  * globally (in ''config.xml''):
+<code>
+<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$"
+...
+</code>
+  * partnership-specific (in ''partnerships.xml''). Example:
+<code>
+<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$"/></code>
+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''
+==== 7.5. Content Type ====
+It is possible to override the default value of Content-Type MIME header used in the body MIME part using the ''content_type'' attribute.
+<code>
+<attribute name="content_type" value="application/EDIFACT"/>
+</code>
+==== 7.6. Content Transfer Encoding ====
+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.
+==== 7.7. Supported Encoding Algorithms ====
+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
+==== 7.8. 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.
+==== 7.9. Custom Mime Headers ====
+Mime headers can be added to the outermost Mime body part for outbound messages and additionally added to the HTPP headers.\\
+...
+=== 7.9.1. Static Header Values ===
+...
+=== 7.9.2. Dynamic Header Values From File Name ===
+  * Delimiter Mode
+  * Regular Expression Mode
+=== 7.9.3. Adding Custom Headers To HTTP ===
+...
+==== 7.10. 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:
+  * ''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>$''
+...
+==== 7.11. HTTP Authentication ====
+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.
+===== 8. AS2 Certificate Configuration =====
+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)
+==== 8.1. Certificate Usage Overview ====
+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
+==== 8.2. Certificate Keystore Configuration ====
+In ''config.xml'':
+<code>
+   <certificates classname="org.openas2.cert.PKCS12CertificateFactory"
+                 filename="$properties.as2_keystore$"
+                 password="$properties.as2_keystore_password$"
+                 interval="300"/>
+</code>
+==== 8.3. Managing Certificate Keystore ====
+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)
+==== 8.4. My Certificates ====
+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.
+=== 8.4.1. Creating Certificates ===
+Third party tools can be used for this purpose:
+  * [[https://keystore-explorer.org/|KeyStore Explorer]] - seems to be the best/simplest tool with GUI
+  * [[https://portecle.sourceforge.net/|Portecle]] - also nice tool with GUI
+  * OpenSSL -> normally should be compiled by the user(!), but fortunately there are also already compiled packages like [[https://www.heise.de/download/product/win32-openssl-47316|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:
+<code>
+<INSTALL_DIR>/bin/gen_p12_key_par.bat
+</code>
+Running the script without arguments will show a usage description.
+=== 8.4.2. Creating Public Key For Sending To Partner ===
+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:
+<code>
+openssl pkcs12 -clcerts -nokeys -out <output file> -in <keystore file>
+</code>
+=== 8.4.3. Importing Into OpenAS2 Keystore ===
+To import certificates contained in the PKCS12 keystore with the help of OpenAS2 command processor (or remote OpenAS2 app):
+<code>
+cert import <alias> <path+filename> <keystore password>
+</code>
+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"
+=== 8.4.4. Supporting Multiple Certificates ===
+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).
+=== 8.4.5. Overlapping Old And New Certificates When Changing ===
+Use ''x509_alias_fallback'' attribute for it:
+<code>
+<partner name="MyCompany256" as2_id="MyCompany2_OID"
+x509_alias="MyCompanyCert256" x509_alias_fallback="MyNewCompanyCert256"
+email="me@MyCompany.com"/>
+</code>
+...
+==== 8.5. Partner Certificates ====
+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)
+=== 8.5.1. Replacing Existing Public Keys ===
+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:
+<code>
+cert delete <alias>
+</code>
+=== 8.5.2. Importing Public Keys ===
+The OpenAS2 command processor (or remote OpenAS2 app) import command for importing your partners certificate would be in this form:
+<code>
+cert import <alias> <path+filename>
+</code>
+=== 8.5.3. Shell Scripts For Certificate Management ===
+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>
+==== 8.6. Possible Issues With Older Certificates ====
+...
+==== 8.7. Suggested Steps For Certificate Setup ====
+  * 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.
+=== 8.7.1. My Certificates ===
+... //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)//  ...
+=== 8.7.2. Partner Certificates ===
+... //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)//  ...
+===== 9. Logging System =====
+Loggers are configured in the config.xml file using the “loggers” element.
+==== 9.1. Log Output Targets ====
+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
+=== 9.1.1. Console Logger ===
+The console logger is configured using this entry in the <loggers> element:
+<code>
+<logger classname="org.openas2.logging.ConsoleLogger" />
+</code>
+=== 9.1.2. File Logger ===
+The file logger is configured using this entry in the <loggers> element:
+<code>
+<logger classname="org.openas2.logging.FileLogger" filename="%home%/../logs/log-$date.yyyyMMdd.txt" />
+</code>
+=== 9.1.3. Email Logger ===
+...
+=== 9.1.4. Socket Logger ===
+...
+=== 9.1.5. Sentry Logger ===
+...
+==== 9.2. Log Level Configuration ====
+==== 9.3. Log Date Format Configuration ====
+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.
+==== 9.4. Suppressing Invalid HTTP Request Message ====
+...
+===== 10. MDN Configuration =====
+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:
+<code>
+<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$"/>
+</code>
+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.
+==== 10.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:
+  * ''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:
+<code>
+<module classname="org.openas2.processor.receiver.AS2MDNReceiverModule" port=”10081” />
+</code>
+==== 10.2. MDN Sender Configuration ====
+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:
+<code>
+<module classname="org.openas2.processor.sender.MDNSenderModule"/>
+</code>
+===== 11. SSL Certificates - Configuring HTTPS Transport =====
+  * 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
+==== 11.1. SSL Certificates ====
+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//.
+==== 11.2. Inbound Transfers ====
+...
+==== 11.3. Outbound Transfers ====
+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:
+<code>
+<partnership name="MyCompany-to-PartnerB">
+...
+  <attribute name="as2_url" value="https://as2.partnerb.com:8443"/>
+...
+</code>
+...
+If you are not intending to receive MDN responses over HTTP then disable that module by setting it to "false":
+<code>
+module.AS2MDNReceiverModule.http.enabled="false"
+</code>
+  * 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):
+<code>
+-Dorg.openas2.cert.TrustSelfSignedCN=<Common.Name1>,<Common.Name2>,...
+</code>
+===== 12. Running OpenAS2 =====
+==== 12.1. Starting OpenAS2 ====
+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
+==== 12.2. Command Entry ====
+Just press <ENTER> after start of OpenAS to get a visible prompt. Typing ''?'' will show possible commands.
+==== 12.3. Automated Launching As UNIX Daemon ====
+=== 12.3.1. INIT.D Service ===
+=== 12.3.2. SYSTEMD Service ===
+==== 12.4. Windows Service Management ====
+=== 12.4.1. Installing Service ===
+=== 12.4.2. Removing Service ===
+=== 12.4.3. Troubleshooting Windows Service ===
+===== 13. Testing OpenAS2 Transfers =====
+==== 13.1. Single Instance Testing ====
+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''
+==== 13.2. Multiple Instance Testing ====
+==== 13.3. Using HTTPS Transport ====
+===== 14. Troubleshooting OpenAS2 =====
+.1. Canonicalization For MIC Algorithm
+.2. Binary Encoding
+.3. HTTP Restricted Headers
+.4. CMS Algorithm Protection
+.5. Content Length Versus Chunked
+.6. SSL Certificate Exceptions
+.7. Java Versions Prior To 1.7
+.8. Mime Body Part Logging
+.9. TLSv1.2
+.10. HTTP Read Timeout Errors
+.11. Out Of Memory And File Size Issues
+.12. File System Issues
+.13. Header Folding
+===== 15. Partner AS2 Compatibility Settings =====
+===== 16. Remote Control =====
+==== 16.1. Socket Command Processor ====
+=== 16.1.1. Server Side Configuration ===
+=== 16.1.2. Client Side Configuration ===
+=== 16.1.3. Running on deployed server ===
+=== 16.1.4. Running on a separate server ===
+=== 16.1.5. Commands ===
+==== 16.2. REST API Command Processor ====
+=== 16.2.1. Server Side Configuration ===
+=== 16.2.2. Using the REST API ===
+===== 17. Dynamic Variables =====
+===== 18. Appendix: config.xml file structure =====
+===== 19. Appendix: partnership.xml file structure =====
+===== 20. Appendix: command.xml file structure =====
+===== 21. Appendix: Updating database structure =====
+===== 22. Appendix: Creating database DDL for external databases =====
+===== 23. Appendix: Upgrading =====
+===== 24. Appendix: Clustering and Load Balancing =====
+===== 25. Appendix: Maven Artifacts =====