Configuration for Message Signning and Secure Channel

Introduction

Under current implementation, H2O support PKCS#12 standard only. And a keystore is needed for H2O to retrieve key for message signing.
There is a keystore created for both ebMS and AS2 plugins once you finished H2O installation by installer.
(To learn more about PKI, please refer to PKI wikipedia, or article)





Configuration To Enable Message Signing

By default, H2O installer has placed a keystore for you under both ebMS plugin and AS2 plugin. You can use it directly, or make your own customized keystore. If you want to know how to create a keystore and generate a public certificate, pleaser refer to the later part of this article.

Setting On Core Module Configuration Xml

The configuration about the keystore are defined in the system module configuration file. The component named keystore-manager defines the specifics of the keystore.

  • AS2 : as2.module.core.xml.
  • ebMS: ebms.module.core.xml.

Here are the description of parameters for keystore-manager.

  • keystore-location
    • Where the keystore file can be found.
    There is a small difference between ebMS and AS2.
    In AS2, the keystore file is put in the "security" folder within the AS2 plugin and we only need to specify the filename of the keystore in this entry.
    But in ebMS, an absolute path is needed instead.
  • keystore-password
    • The password to access the keystore file.
  • key-alias
    • The value to specify which key in the keystore will be used for signing.
  • key-password
    • The password to access the private key (usually same as the keystore password).
  • keystore-type
    • The type of the keystore, currently, H2O can only support pkcs12.
  • keystore-provider
    • The class provider to handle the keystore, by default you should use org.bouncycastle.jce.provider.BouncyCastleProvider.

Partnership Setting On Receiver Side

For receiver to verify the signature, they need to upload the public certificate provided by the sender through the partnership maintenance page.

image

And the value of "Signing Required" have set to "true". For detail setting of the partnership, please refer to as2 partnership reference or ebMS partnership reference.

image



How-To Send Messages Through HTTPS

SSL Server Authentication

To enable sever authentication in Tomcat, we have to configure a trust-store and keystore separately in H2O and Tomcat configuration.

On the sender side, a truststore defined on corvus.properties.xml, which stores the certificate of the server it will trust. When sender H2O try to establish a secure connection, the receiver H2O will provide a public certificate to sender H2O to identify its identity. If this certificate is self-signed, it should be added to the truststore defined on the sender side.

On the receiver side, a keystore is needed. The location and specifics should be defined in the sever.xml of Tomcat. The keystore contains its private-key and public-certificate pair. If the keystore is self-signed, the certificate have to be exported, then imported to the truststore of sender H2O.
We will show you the detail procedures below.
If you have no idea about how to generate a keystore and export a public certificate, please refer to the later part of this article.



Receiver H2O Configuration

Once you have created the keystore, You need to modify the sever.xml to specify keystore parameters.
Uncomment the connector definition on port 8443. Add the attribute about the keystore configuration.

  • keystoreFile
    • You have to specify an absolute file path to the keystore file.
  • keystorePass
    • The password to access the keystore.
  • keystoreType
    • Either PKCS12 or JKS are supported, enter the one that the keystore belongs to.
  • keyalias
    • An optional attribute, if the keystore contains more than one key-pair, please specify the target key-pair by the alias.
  • clientAuth
    • Set it to FALSE to indicate only Sever Authentication is needed.



Sender H2O Configuration

As we mentioned before, we have to configure a truststore. We will use JKS format keystore to act as a truststore, as its much easier to import a self-signed certificate.

If there is no match keystore file found, the keytools will create a new keystore for you.

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

The program will print the certificate info and ask for confirmation. Just enter yes.

image

Open the corvus.properties.xml, the definition of the truststore could be found under the environment component.

Here are the description of parameters.

  • trustStore
    • You have to specify an absolute file path to keystore file.
  • trustStorePass
    • The password phrase to access the keystore.
  • trustStoreType
    • Either PKCS12 or JKS are supported, enter the one that the keystore belongs to.

If your receiver H2O returns an async reply. You have to make the same configuration on both H2O, but the role is reversed.

SSL With Client Authentication

In additional to sever authentication, you can apply client authentication on H2O. Hence, you can get a full secure connection for message delivery.

Once the sever authentication completed, the receiver H2O will ask sender H2O to show it's identity. The sender H2O provide the public certificate to the receiver H2O. Then, the receiver will check whether this certificate is trusted or not by looking into the truststore.



Sender H2O Configuration

To store the private key and public certificate pair of its identity, a keystore is needed. A complete SSL setting should be as follows.

Here are the description of parameters.

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



Receiver H2O Configuration

In order to store trusted certificate, a truststore should declare in tomcat server.xml.

Here is the description of the attributes.

  • keystoreFile
    • The absolute file path to the keystore file.
  • keystorePass
    • The password phrase to access the keystore.
  • keystoreType
    • Either PKCS12 or JKS are supported, enter the one that the keystore belongs to.
Last but not least, you have to set clientAuth to True to enforce client authentication.





How to generate PCS12 Keystore, and Certificate

You use use Keytool or OpenSSL to create keystore and certificate.
Here are the procedures to create keystore and certificate.

Using Keytool

Keytool, a tool provided along with Java SDK.

  1. Invoke keytool with parameters

    2. keytool -genkey -alias name-of-alias -keyalg RSA -keystore filepath-and-name-for-keystore -storetype pkcs12 -storepass password -keypass password

    Be reminded that, we are using the same password value on keypass and storepass in this command. so, we entered the command like this.


    image
  2. More detail information will be asked.

    3. You will be asked to provide information about your Organization Unit, City name, Country Code, etc.

    image

    After this, the keystore are created.
    You can now verify the keystore using keytool.
    keytool -list -keystore filepath-and-name-for-keystore -storetype pkcs12
    Password is needed to access the keystore, just use the password you specified in the "storepass" attribute.

    image
  3. Export Certificate With Keytool

    4. The private key are generated and stored in keystore, but you still need to make a public certificate for receiver verify your signature.

    keytool -exportcert -alias name-of-the-key -keystore filepath-and-name-for-keystore -storetype pkcs12 -file filepath-and-name-for-certificate

    You enter the password to access the keystore, again, the value should be same as the one you specified in the "storepass" attribute.

    image

    You can verify the certificate with the following command.
    keytool -printcert -file filepath-and-name-for-certificate

    image

Using OpenSSL

You can find OpenSSL on http://www.openssl.org/.
  1. Generate The Private Key

    2. Invoke openssl to enter the OpenSSL environment.
    And then, execute the following, genrsa -out filepath-and-name-of-key-file bit-of-length

    imageGenerate A Certificate Signing Request

    req -new -key filepath-and-name-of-key-file -out filepath-and-name-of-signing-request-file

    image
  2. Generating A Self-Signed Certificate

    3. X509 -req -days number-of-days-to-valid -in filepath-and-name-of-signing-request-file -signkey - -sha1 -out filepath-and-name-of-certificate-file

    image
  3. Export To Keystore File In PKCS12 Format

    4. pkcs12 -name name-of-key-alias -export -in filepath-and-name-of-certificate -inkey filepath-and-name-of-key -out filepath-and-name-of-keystore

    image


Discuss this in our forum

Posted by Ronnie Kwok on 07/15 at 06:33 PM