Exchange Certificate Configuration Details

Owned by Tran Tang
Last updated: Jul 30, 2019 by Paul Tambellini
3 min read

Overview

There are 3 sets of exchange certificate configurations in CONNECT, two for transport level security, and one for message level security. Each of these three configurations control different aspects of security within the CONNECT gateway.

Transport Level Security

CONNECT uses two different certificate configurations to accomplish transport level security; one for incoming, and one for outgoing SSL connections. This is not intended to be a feature allowing different certificates to be used on the initiating and responding sides, but is an artifact of different components of the CONNECT technology stack being responsible for each connection.

Application Server

Within installation instructions for the various application servers that CONNECT supports there are instructions making the container aware or allowing the container to manage a set of key stores and trust stores. In some application servers this comes along with configurations for https listeners. These configurations are required because when CONNECT is responding to requests, there is a layer of applications server processing which is listening on a given port and processing lower level protocols such as TCP, HTTP/HTTPS, as well as SSL. 

Java System Properties

In addition to the application server configurations, CONNECT installation instructions also refer to a set of java system properties:

-Djavax.net.ssl.keyStorePassword=changeit
-Djavax.net.ssl.keyStore=<path to keystore>/gateway.jks
-Djavax.net.ssl.keyStoreType=JKS
-Djavax.net.ssl.trustStorePassword=changeit
-Djavax.net.ssl.trustStore=<path to truststore>/cacerts.jks
-Djavax.net.ssl.trustStoreType=JKS
-DCLIENT_KEY_ALIAS=gateway

These properties are used by the CXF web services stack for initiating an SSL connection. CONNECT currently uses certificates for three purposes, SSL, SAML Assertion signatures, and EndorsingSupportingToken Signatures (timestamp signature). The use of java system variables for certificate configuration affects both the outbound SSL, and the SAML Assertion signature. There are multiple ways of configuring outbound SSL certificates in CONNECT, the current method is to create a set of TLSParameters from scratch passing in keystores and truststores. However the CONNECT team has proved that another method involving retrieving an SSLSocketFactory from the container's SSLContext is not only viable but works on all supported application servers.

Message Level Security

With the introduction of CXF in CONNECT 4.0, the CONNECT gateway instantly supported using separate certificates for SSL and Message level security, through CXF's inherent configuration. There are a set of properties files the CONNECT properties directory which allow adopters to configure message level security:

saml.properties

The saml.properties file contains a reference to the signature.properties file (which can be changed to a different name), as well as the key and key password to be used for XML Digital Signatures.

#Signature properties file
org.apache.ws.security.saml.issuer.cryptoProp.file=signature.properties
...
...
#The following are the new keystore alias and password
org.apache.ws.security.saml.issuer.key.name=gateway
org.apache.ws.security.saml.issuer.key.password=changeit

signature.properties

The signature.properties file contains locations for the key store used for XML Digital Signatures. The .file entry will look on the classpath for a file name but will also accept a fully qualified path. Although CONNECT by default configures .keystore.alias and .keystore.private.password, these entries are repeats of values in saml.properties and are not required.

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=jks
org.apache.ws.security.crypto.merlin.keystore.password=changeit
org.apache.ws.security.crypto.merlin.file=gateway.jks

truststore.properties

The truststore.properties file contains locations for the key store used for XML Digital Signatures. The .file entry will look on the classpath for a file name but will also accept a fully qualified path. CXF uses this trust store to determine if a particular key used to sign an incoming message is trusted. Failing this check does not mean the message is not trusted because there is not enough information in a public key to determine if the certificate which the public key belongs to has been signed by a certificate which does exist in the trust store. Failing this check would, result in requiring every exchange participants certificate as opposed to the chain of trust model. 

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=jks
org.apache.ws.security.crypto.merlin.keystore.password=changeit
org.apache.ws.security.crypto.merlin.file=cacerts.jks