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. The CONNECT team has an open issue to investigate using the application server configuration to both cut down on configuration required as well as support network deployments where file references to the key and trust stores aren't available.
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