Configuring Secure Messaging

How to send messages using HTTPS

SSL server authentication

To enable server authentication in Tomcat, a truststore and a keystore have to be configured in Hermes and Tomcat respectively.

On the sending side, a truststore is defined in corvus.properties.xml, which is where the certificates of trusted servers are stored. When the sending Hermes tries to establish a secure connection, the receiving Hermes will provide a public certificate for the sender to identify their identity. If this certificate is self-signed, it should be added to the truststore defined on the sending side.

On the receiving side, a keystore is defined in the server.xml of Tomcat. The keystore contains its paired private key and public certificate. If the keystore is self-signed, the certificate has to be exported, then imported to the trustore of the sending Hermes.

The details of this procedure are shown below. For information about how to create a keystore and generate a public certificate, please refer to the section How to generate a PKCS12 Keystore and Certificate.

Receiver configuration

Once a keystore has been created, server.xml needs to be modified to specify the keystore parameters.

  1. Uncomment the connector definition on port 8443.
  2. Add the following attributes for keystore configuration.
keystoreFile An absolute file path to the keystore file.
keystorePass The password to access the keystore.
keystoreType The type of keystore. Both PKCS12 and JKS are supported.
keyalias Optional. If the keystore contains more than one key pair, specify the target key-pair with an alias.
clientAuth Set this to false to indicate only Server Authentication is needed.

Sender configuration

As mentioned before, a truststore needs to be configured. In this example, a JKS keystore is used as a truststore as it is much simpler to import a self-signed certificate.

If there is no keystore file found, Keytool can be used to create a new keystore:

keytool -importcert -file {filepath-and-name-of-certificate} -alias {key-alias} -keystore {filepath-and-name-of-keystore} -storetype jks -storepass {password}

The program will display the certificate information and ask for confirmation. Enter yes after verifying the details.

_images/keytool_truststore.png

Open corvus.properties.xml. The definition of the truststore can be found under the environment component.

Here are descriptions of the parameters:

trustStore The absolute file path to the keystore.
trustStorePass The password to access the keystore.
trustStoreType The type of the keystore. Both PKCS12 and JKS are supported.

If asynchronous replies are enabled for the receiving partnership, the same configuration needs to be made for Hermes on both sides, however the roles are reversed.

SSL client authentication

In addition to server authentication, client authentication can also be applied to Hermes to achieve secure connections for message deliveries.

Once the server authentication is complete, the receiving Hermes will ask for the identity of the sending Hermes. The sender will provide a public certificate to the receiver, which will be compared to the trusted certificates in the truststore.

Receiver configuration

In order to store trusted certificates, a truststore needs to be declared in the server.xml of Tomcat.

Here are descriptions of the attributes:

keystoreFile The absolute file path to the keystore.
keystorePass The password to access the keystore.
keystoreType The type of the keystore. Both PKCS12 and JKS are supported.
clientAuth Set this to true to enforce client authentication.

Sender configuration

To store the private key and public certificate pair that identifies the sender, a keystore is needed.

Here are descriptions of the parameters:

javax.net.ssl.keyStore The absolute file path to the keystore.
javax.net.ssl.keyStorePassword The password to access the keystore.
javax.net.ssl.keyStoreType The type of the keystore.

How to generate a PKCS12 keystore and certificate

To create a keystore and certificate, Keytool or OpenSSL can be used.

Using Keytool

Keytool is provided with Java SDK.

  1. Invoke keytool with parameters.

    keytool -genkey -alias {key-alias} -keyalg RSA -keystore {filepath-and-name-of-keystore} -storetype pkcs12 -storepass {password} -keypass {password}

    The same password value is used for keypass and storepass in this command.

    _images/keytool_command.png

  2. Input more detailed information.

    _images/keytool_command_detail.png

    After entering the information, a keystore will be created. It can be verified using Keytool.

    keytool -list -keystore {filepath-and-name-of-keystore} -storetype pkcs12

    The password specified in the storepass attribute is needed to access the keystore.

    _images/keytool_list_keystore.png

  3. Export certificate.

    The private key has been generated and stored in the keystore, but a public certificate is still needed for the receiver to verify signatures.

    keytool -exportcert -alias {key-alias} -keystore {filepath-and-name-of-keystore} -storetype pkcs12 -file {filepath-and-name-of-certificate}

    Enter the password specified in the storepass attribute to access the keystore.

    _images/keytool_generate_certificate.png

    The certificate can be verified with the following command:

    keytool -printcert -file {filepath-and-name-of-certificate}
    _images/keytool_printcert.png

Using OpenSSL

OpenSSL can be found here.

  1. Generate private key.

    Invoke openssl to enter the OpenSSL environment, then execute the following:

    genrsa -out {filepath-and-name-of-key} {length-in-bits}
    _images/openssl_genrsa_1024.png

  2. Generate certificate signing request.

    req -new -key {filepath-and-name-of-key} -out {filepath-and-name-of-signing-request}
    _images/openssl_create_csr.png

  3. Generate self-signed certificate.

    x509 -req -days {number-of-days-valid} -in {filepath-and-name-of-signing-request} -signkey {filepath-and-name-of-key} -sha1 -out {filepath-and-name-of-certificate}
    _images/openssl_gen_cert.png

  4. Export to keystore in PKCS12 format.

    pkcs12 -name {key-alias} -export -in {filepath-and-name-of-certificate} -inkey {filepath-and-name-of-key} -out {filepath-and-name-of-keystore}
    _images/openssl_pkcs12.png

Supported Parameters

The following key pair algorithms and signature algorithms have been tested:

Key pair algorithm (keyalg)

DSA Generates keypairs for the Digital Signature Algorithm
RSA [1] Generates keypairs for the RSA algorithm (Signature/Cipher)
[1]RSA has been test with keysize= 1024, 2048, 4096.

Signature algorithm (sigalg)

SHA1withRSA The signature algorithm with SHA-* and the RSA encryption algorithm as defined in the OSI Interoperability Workship, using the padding conversions described in PKCS1.
SHA256withRSA
SHA512withRSA
MD5withRSA The MD2/MD5 with RSA encryption algorithm which users the MD2/MD5 digest algorithm and RSA to cread and verify RSA digital signatures as defined in PKCS1.
MD2withRSA
SHA1withDSA The DSA with SHA-1 signature algorithm which uses the SHA-1 digest algorithm and DSA to create and verify DSA digital signatures as defined in FIPS PUB 186.

Parameter combinations

The following combinations of algorithms and parameters have been tested with ebMS and AS2:

ebMS

tool Keytool OpenSSL
keysize 1024 2048 4096 1024 2048 4096
RSA SHA1 ok ok ok ok ok ok
SHA256 ok ok ok ok ok ok
MD5 ok ok ok ok ok ok
SHA512 not supported ok not supported not supported ok not supported
MD2 not supported ok not supported not supported not supported not supported
DSA SHA1 ok not supported not supported ok not supported not supported

AS2

tool Keytool OpenSSL
keysize 1024 2048 4096 1024 2048 4096
RSA SHA1 ok ok ok ok ok ok
SHA256 ok ok ok ok ok ok
MD5 ok ok ok ok ok not supported
SHA512 not supported ok not supported not supported ok not supported
MD2 not supported ok not supported not supported not supported not supported
DSA SHA1 not supported not supported not supported not supported not supported not supported