Installing Hermes

Introduction

The Hermes installer is packaged in the form of a self-extracted java archive (JAR). Upon proper invocation, you will see an installation wizard, either in graphical or text format. Following the steps will install the following components:

  • Hermes core
  • Hermes plugins (AS2 / AS2 Plus / ebMS)
  • Database tables of Hermes plugins for one of the following database:
    • Postgres 9.2 or later
    • Oracle 11gR2 or later
    • MySQL 5.5 or later with InnoDB storage engine supported
  • Web service usage sample

Prerequisite

  1. Java SE Development Kit 8

  2. Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files

    1. Download the JCE Unlimited Strength Jurisdiction Policy Files for JDK 8 from

      http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html

    2. Unzip the downloaded file

      unzip jce_policy-8.zip

    3. Replace the two jar files local_policy.jar and US_export_policy.jar in the directory /usr/lib/jvm/java-8-oracle/jre/lib/security with the corresponding jar file unzipped in the previous step.

      cd UnlimitedJCEPolicyJDK8
sudo cp local_policy.jar /usr/lib/jvm/java-8-oracle/jre/lib/security/local_policy.jar
sudo cp US_export_policy.jar /usr/lib/jvm/java-8-oracle/jre/lib/security/US_export_policy.jar

  3. Tomcat 8.5 or above with port 8080

    1. Change the access permissions, the owner and the group of <TOMCAT_HOME>/webapps after Tomcat is installed.

      sudo chmod 775 <TOMCAT_HOME>/webapps
sudo chown tomcat:<OWNER_GROUP> <TOMCAT_HOME>/webapps

    2. Edit /etc/systemd/system/tomcat.service. Change Environment=JAVA_HOME=/usr/lib/jvm/java-1.8.0-openjdk-amd64/jre to Environment=JAVA_HOME=/usr/lib/jvm/java-8-oracle/jre

    3. Restart Tomcat

    Note

    To access the admin page, you will need to have a Tomcat user with an admin role. One way to do this is to define the user in tomcat-users.xml. Please refer to the Realm Configuration section in the Tomcat documentation for more details.

    Sample of tomcat-user.xml:

    <?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
    <role rolename="tomcat"/>
    <role rolename="admin"/>
    <role rolename="api"/>
    <user username="corvus" password="corvus" roles="tomcat,admin,api"/>
</tomcat-users>

  4. One of the following databases installed on any server:

    • PostgreSQL 9.2 or later. <POSTGRES_HOME> is referring to the home directory of PostgreSQL in the remaining parts of the document.
    • MySQL 5.5 or later. <MYSQL_HOME> is referring to the home directory of MySQL in the remaining parts of the document.
    • Oracle 11gR2 or later. <ORACLE_HOME> is referring to the home directory of Oracle in the remaining parts of the document.

Installation

Step 1 – Environment setup

Install all the prerequisite items. The rest of this guide assumes that they are all running on the same machine.

Step 2 – Database Configuration

Postgres

  1. Create a database user with username corvus and password corvus.
    1. Open a command prompt
    2. Go to <POSTGRES_HOME>/bin
    3. Type createuser -A -d -P -U <POSTGRES_ADMIN> corvus where <POSTGRES_ADMIN> represents the name of an administrator/super-user in the PostgreSQL database. This value is postgres if not specified. This may require a super user or Postgres owner to execute in Linux.
    4. Enter the password corvus
    5. Enter the password again for confirmation
    6. Enter the PostgreSQL administrator password for creating a new user role.
  2. Create two databases named as2 and ebms with the corvus user.
    1. Open a command prompt
    2. Go to <POSTGRES_HOME>/bin
    3. Type createdb –U corvus –W as2
    4. Enter the password corvus
    5. Repeat steps 2.3 - 2.4 for the ebms database.

MySQL

  1. Create two databases named as2 and ebms with username corvus and password corvus.

    1. Open a command prompt

    2. Go to <MYSQL_HOME>/bin

    3. Type mysql –u <MYSQL_ADMIN> -p where <MYSQL_ADMIN> represents the name of an administrator/super-user in the MySQL database. This is root by default. This may require super user or MySQL owner to execute in Linux.

    4. Enter the command below to create the as2 database. Note that specifying collate to latin1_general_cs is essential.

      create database as2 collate=latin1_general_cs;

    5. Enter the command below to create and assign access privileges to user corvus.

      grant all on as2.* to 'corvus'@'localhost' identified by 'corvus';

    6. Repeat steps 1.4 – 1.5 for the ebms database.

Oracle

Oracle database creation involves a number of steps and custom parameters for different requirements for the database server. We propose the following reference as a guideline for creating an Oracle database for Hermes:

https://docs.oracle.com/cd/E11882_01/server.112/e10897/install.htm#ADMQS0232

Step 3 – Hermes Deployment

  1. Execute the installer

    • For Windows, open a command prompt and type java –jar hermes2_installer.jar or if java is not set in your environment path, specify the full path.
    • For Unix/Linux, open xterm and follow the same procedure as above.

    Or:

    • Test For Windows, you can execute the installer by double-clicking on the .jar file or right-clicking and selecting open with ‣ javaw (located where you installed java, in the bin folder).
    _images/3-4-1-hermes-2-0-text-installer.png _images/3-4-1-hermes-2-0-opensource-installer.png

    Click Next until you get to Step 1 of the installation.

  2. Step 1 - Configure Hermes Core

    _images/3-4-1-step-1-configure-hermes-2-core.png _images/3-4-1-step-1-h2o-installer.png

    Descriptions of the settings:

    Web Application Folder Folder to place the web application (e.g webapps) in Tomcat.
    Hermes Home Location to place the Hermes core library and some related files.
    JDBC Driver

    Specify which database vendor to connect to. One of the following 3 database vendors can be selected:

    • Postgres
    • Oracle
    • MySQL
    Hermes ebMS Plugin Optional. Install the ebMS component.
    Hermes AS2 Plugin Optional. Install the AS2 component.
    Web Service Usage Sample Optional. Install the sample program of web service client.

    Click Next and press Yes if the installer prompts you to create a new directory.

  3. Step 1.1 - Configure Database Driver

    Oracle and MySQL drivers need to be downloaded manually. Once this is done, specify the location of the driver:

    _images/3-4-1-step-1-1-configure-database-driver.png _images/3-4-1-step-1-1-h2o-installer.png

    Descriptions of the settings:

    JDBC Driver Folder (.jar) Directory of the downloaded JDBC driver.

  4. Step 2 - Configure Database for ebMS Plugin (Optional)

    _images/3-4-1-step-2-configure-database-for-ebms-plugin.png _images/3-4-1-step-2-h2o-installer.png

    Descriptions of the settings:

    Database URL The URL address of the database server. Port number may be attached to the address with the format <HOST_ADDRESS>:<PORT> where <HOST_ADDRESS> is the address of the database server and <PORT> is the port number of the database server address.
    Database Name/SID For Postgres and MySQL, please specify the name of the database. For Oracle, please specify the Oracle System ID (SID).
    Username Username to access the database.
    Password Password to access the database.
    Re-create Tables

    Optional. Re-create all the tables in the specified database.

    Important Notes:

    • If this is your first time installing Hermes, please check this option.
    • If you choose to re-create the tables, all of the existing data in the specified database will be removed during installation. Please backup all the data in the selected database before choosing to re-create the tables.

    If you followed the prerequisite installation procedures above, you can just leave it as the default. Click Next when you have finished the configuration.

  5. Step 3 - Configure Database for AS2 Plugin (Optional)

    _images/3-4-1-step-3-configure-database-for-as2-plugin.png _images/3-4-1-step-3-h2o-installer.png

    Descriptions of the settings:

    Database URL The URL address of the database server. Port number may be attached to the address with the format <HOST_ADDRESS>:<PORT> where <HOST_ADDRESS> is the address of the database server and <PORT> is the port number of the database server address.
    Database Name/SID For Postgres and MySQL, please specify the name of the database. For Oracle, please specify the Oracle System ID (SID).
    Username Username to access the database.
    Password Password to access the database.
    AS2 Plugin

    AS2: Original AS2 plugin certified by Drummond Group Inc.

    AS2 Plus: Built based on AS2 plugin with new/enhanced features.
    Re-create Tables

    Optional. Re-create all the tables in the specified database.

    Important Notes:

    • If this is your first time installing Hermes, please check this option.
    • If you are switching from AS2 to AS2 Plus or vice versa, we highly recommend you check this option.
    • If you choose to re-create the tables, all of the existing data in the specified database will be removed during installation. Please backup all the data in the selected database before choosing to re-create the tables.

    If you followed the prerequisite installation procedures above, you can just leave it as the default. Click Next when you have finished the configuration.

  6. Click on Install and you’re done!

Step 4 – Start Hermes2

  1. Checklist:

    • Java JDK 8 or above with Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 7.
    • Apache Tomcat 8.5 or above Servlet/JSP Container.
    • Database server is running with ebMS and/or AS2 database instances and the tables are created.
    • If you are running Unix/Linux, make sure that at least read permissions are set to the core directory and read/write for the AS2 repository directory in <HERMES2_HOME>.
    • Start Tomcat.

  2. To verify that Hermes is running, access the following URL from a web browser:

    The welcome page should be displayed as below:

    _images/3-5-step-4-welcome-page.jpeg

  3. To access the admin page, go to the following URL. The login user and password are the same as the Tomcat user with admin privileges specified in Prerequisite.

  4. Once you have gained access to the admin page, you should see the Hermes Administration Console page:

    _images/3-5-step-4-administration-console-page.png

That’s it! Hermes should now be up and running. You can test your setup by running our web service usage sample in next section.

Partnership Maintenance and Web Service Usage Sample

A tool kit called Web Service Usage Sample was installed under the <HERMES2_HOME>/sample folder. It contains tools to test the installed Hermes.

Directory Organization

Directory/File Description
config/* Contains the configuration file for the sample programs. The folders inside this directory contain related files for specific sample programs.
config/ebms-partnership.xml config/as2-partnership.xml These two files contain partnership settings for ebMS and AS2 that are used by the sample programs.
logs/* A set of logs that contain the output from each sample program.
lib/* The library files required for the sample programs.
*.bat/*.sh The scripts for executing the sample programs.

Preparation

Windows environment

  1. Set environment variable JAVA_HOME to the directory where Java is located.

    Note

    To run the sample program, Administrator privilege is required.

UNIX environment

  1. Set environment variable JAVA_HOME to the directory where Java is located.

  2. Change the owner and the group of <HERMES2_HOME> and <TOMCAT_HOME>/webapps/corvus with the following commands:

    sudo chown -R tomcat:<OWNER_GROUP> <HERMES2_HOME>
sudo chown -R tomcat:<OWNER_GROUP> <TOMCAT_HOME>/webapps/corvus

  3. Change the permissions of all files in <HERMES2_HOME> and <TOMCAT_HOME>/webapps/corvus to 775 with the following command:

    sudo chmod -R 775 <HERMES2_HOME>
sudo chmod -R 775 <TOMCAT_HOME>/webapps/corvus

Partnership Maintenance

Users need to define a partnership, which contains the messaging details between sender and recipient. It is required to identify the sender and the recipient when transporting messages.

A web service sample program is provided to manage partnerships (add, update or delete). The partnership configuration for the AS2/ebMS loopback test is placed in <HERMES2_HOME>/sample/config/<as2/ebms>-partnership.xml.

Program Purpose
as2-partnership / ebms-partnership Maintains a specified AS2/ebMS partnership in Hermes.

Creating an AS2 Partnership

To create the partnership required to perform the AS2 messaging loopback test using AS2 Web Service Usage Sample, you need to execute the script as2-partnership.

Or:

Access http://localhost:8080/corvus/admin/as2/partnership to configure the partnership manually. Below is a simple loopback configuration sample:

_images/4-3-1-create-as2-partnership.png
Partnership ID as2-loopback
AS2 From as2loopback
AS2 To as2loopback
Disabled No
Subject none
Recipient Address http://127.0.0.1:8080/corvus/httpd/as2/inbound
Hostname Verified in SSL? No
Request Receipt? No
Signed Receipt? No
Asynchronous Receipt? No
Receipt Return URL http://127.0.0.1:8080/corvus/httpd/as2/inbound
Message Compression Required? No
Message Signing Required? No
Signing Algorithm sha1
Message Encryption Required? No
Encryption Algorithm rc2
Certificate For Encryption none
MIC Algorithm sha1
Maximum Retries 1
Retry Interval (ms) 30000
Message Signature Enforced? No
Message Encryption Enforced? No
Certificate For Verification none

Creating an AS2 Plus Partnership

Please follow the same procedure listed in Creating an AS2 Partnership .

Creating an ebMS Partnership

To create the partnership required to perform the ebMS messaging loopback test using ebMS Web Service Usage Sample, you need to execute the script ebms-partnership.

Or:

Access http://localhost:8080/corvus/admin/ebms/partnership to configure the partnership manually. Below is a simple loop-back configuration sample:

_images/4-3-3-ebms-plugin.png
Partnership ID ebms-loopback
CPA ID cpaid
Service http://localhost:8080/corvus/httpd/ebms/inbound
Action action
Disabled No
Transport Endpoint http://localhost:8080/corvus/httpd/ebms/inbound
Hostname Verified in SSL? No
Sync Reply Mode none
Acknowledgement Requested never
Acknowledgement Signed Requested never
Duplicate Elimination never
Message Order NotGuaranteed
Signing Required? No
Encryption Required? (Mail Only) No
Certificate For Encryption none
Maximum Retries 1
Retry Interval (ms) 30000
Certificate For Verification none

Web Service Usage Sample Flow

In order to validate the installation of Hermes, a web service usage sample program is provided. It can be executed by running the following scripts in a command prompt.

Program Purpose
as2-send / ebms-send Send an AS2/ebMS message to the installed Hermes.
as2-history / ebms-history Show the message history of Hermes. This program will list the inbox and outbox messages in the data storage of Hermes. The user can view the details of the inbox and outbox. For inbox messages, the user can also download the payload in the repository of Hermes, if available.

In order to test whether Hermes has been installed successfully or not, we suggest running the sample programs in the following steps:

  1. Send a message to the local Hermes by running ebms-send/as2-send.
  2. Check the status of the sent message by running ebms-history/as2-history and select the message from the outbox.
  3. Check the received message by running ebms-history/as2-history and select the message from the inbox to download the payload.

AS2 Web Service Usage Sample

Before executing the following AS2 web service usage sample, the partnership from Creating an AS2 Partnership must be created.

  1. Send a message to the local Hermes using the script as2-send.

    This program creates and sends a request attached with the payload named testpayload under the directory <HERMES2_HOME>/sample/config/as2-send to Hermes.

    Upon successful execution, you should be able to see the similar output shown as follow:

    _images/as2-send.png

  2. Check the sent message using the script as2-history.

    This program retrieves the list of sent/received message from Hermes.

    _images/as2-history.png

    Enter 0 to check the sent message. A display similar to the following will appear:

    _images/as2-history-0.png

  3. Check the received message and download the payload.

    From the select message screen of as2-history, enter 1 to select the inbox message and it will display Please provide the folder to store the payload(s):. Press enter to save the payload in the current folder. A file named as2.<timestamp>@127.0.1.1.Payload.0 will be downloaded, where <timestamp> is the time as2-send was executed. Open that file and you will see the follow content:

    _images/4-4-1-smaple-message.png

ebMS Web Service Usage Sample

Before executing the following ebMS web service usage sample, the partnership from Creating an ebMS Partnership must be created.

  1. Send a message to the local Hermes server using the script ebms-send.

    This program creates and sends a request attached with the payload named testpayload under the directory <HERMES2_HOME>/sample/config/ebms-send to Hermes.

    Upon successful execution, an output similar to the following will be displayed:

    _images/ebms-send.png

  2. Check the sent message using the script ebms-history.

    This program retrieves the list of sent/received message from Hermes.

    _images/ebms-history.png

    Enter 0 to check the sent message and a screen similar to the following will be displayed:

    _images/ebms-history-0.png

  3. Check the received message and download the payload.

    From the select message screen of ebms-history, enter 1 to select the inbox message and it will display Please provide the folder to store the payload(s):. Press enter to save the payload in the current folder. A file named ebms.<timestamp>@127.0.1.1.Payload.0 will be downloaded, where <timestamp> is the time ebms-send was executed. Open that file and you will see the following content:

    _images/4-4-1-smaple-message.png

Configuration for Secure Messaging & Secure Channels

In order to store a private key for message signing, a keystore is needed. Under current implementation, only PKCS12 keystore is supported. If Hermes was installed using the installer, there are keystore files placed in the folder called security under both ebMS and AS2/AS2 Plus plugins.

Message Signing

To enable message signing, please configure the plugin with a corresponding keystore. A default keystore setting can be set through the installer or you can create a new customized keystore. To learn more about generating a keystore, please refer to How to generate a PKCS12 keystore and certificate.

Sender Settings for Message Signing

To instruct Hermes to perform message signing with the correct private key, the corresponding Keystore Manager should be configured with the correct parameters.

Here are descriptions of the parameters:

keystore-location Absolute file path pointing to the keystore file.
keystore-password Password to access to keystore.
key-alias Name of the private key.
key-password Password to retrieve the private key. (PKCS12 standard: key-password is equal to keystore-password)
keystore-type The type of the keystore. This must be PKCS12.
keystore-provider The class provider to handle the keystore. org.bouncycastle.jce.provider.BouncyCastleProvider
ebMS Sender Settings

Open the configuration file named ebms.module.xml that is placed in the conf folder of the ebMS plugin. A component named keystore-manager-for-signature is defined to manage the keystore.

<component id="keystore-manager-for-signature"
           name="Key Store Manager for Digital Signature">
  <class>hk.hku.cecid.piazza.commons.security.KeyStoreManager</class>
    <parameter name="keystore-location"
               value="/corvus/plugins/hk.hku.cecid.ebms/security/corvus.p12" />
    <parameter name="keystore-password" value="password" />
    <parameter name="key-alias" value="corvus" />
    <parameter name="key-password" value="password" />
    <parameter name="keystore-type" value="PKCS12" />
    <parameter name="keystore-provider"
               value="org.bouncycastle.jce.provider.BouncyCastleProvider" />
</component>
AS2/AS2 Plus Sender Settings

Open the configuration file named as2.module.core.xml that is placed in the conf folder of the AS2/AS2 Plus plugin. A component named keystore-manager is defined to manage the keystore.

<component id="keystore-manager" name=" AS2 Key Store Manager">
  <class>hk.hku.cecid.piazza.commons.security.KeyStoreManager</class>
  <parameter name="keystore-location" value="corvus.p12" />
  <parameter name="keystore-password" value="password" />
  <parameter name="key-alias" value="corvus" />
  <parameter name="key-password" value="password" />
  <parameter name="keystore-type" value="PKCS12" />
  <parameter name="keystore-provider"
             value="org.bouncycastle.jce.provider.BouncyCastleProvider" />
</component>

Receiver Settings for Message Signing

For a receiver to verify the signature, a public certificate should be provided by the sender through the partnership maintenance page.

_images/5-1-2-1.png

Set the value of Signing Required to true. For detailed settings of the partnership, please refer to Setting Up AS2 Partnerships or Setting Up ebMS 2.0 Partnerships.

_images/5-1-2-2.png

Message Tranfer with Secure Channels

To further ensure the security of message transfers, secure channels are preferable. For more details on the required configuration, please see How to send messages using HTTPS.

FAQ

Hermes Deployment

Q1. The corvus.log shows:

hk.hku.cecid.piazza.commons.spa.PluginException: Error in processing activation by handler:
hk.hku.cecid.ebms.spa.EbmsProcessor which is caused by java.io.IOException: exception decrypting data - java.lang.SecurityException: Unsupported keysize or algorithm parameters

A1. Please ensure the Java 2 SDK files have been replaced by the JCE files.

Q2. Some log files show the following error:

hk.hku.cecid.piazza.commons.dao.DAOException: Unable to begin transaction.

A2. Ensure PostgreSQL/MySQL/Oracle was installed properly and check the following files:

For AS2:

<HERMES2_HOME>/plugins/hk.hku.cecid.edi.as2/conf/hk/hku/cecid/edi/as2/conf/as2.module.core.xml. There is a tag in this file named parameter with the attribute name=url. Check the value attribute to see if it references the correct server address. The format of the value attribute is the same as the JDBC connection string.

For ebMS:

<HERMES2_HOME>/plugins/hk.hku.cecid.ebms/conf/hk/hku/cecid/ebms/spa/conf/ebms.module.xml. There is a tag in this file named parameter with the attribute name=url. Check the value attribute to see if it references the correct server address. The format of the value attribute is the same as the JDBC connection string.

Web Service Usage Sample

Q1. The following exception is thrown:

Exception in thread "main" java.lang.UnsupportedClassVersionError: xxx (Unsupported major.minor version 49.0)

A1. It is very likely you are using an incompatible Java version. The web service usage sample requires J2SE 5.0 or above to run properly. In the command prompt, enter java –version to check the Java version.

Q2. The following error occurs:

Sending ebMS/AS2 sending request ...
java.net.ConnectException: Connection refused: connect

A2. Check that the Application Container (Tomcat) has been started.