Secure Client Connections using SSL in Teiid

By default all sensitive (non-data) messages between client and server are encrypted using a Diffy-Hellman key that is negotiated per connection. This encryption is controlled by the following property in "<teiid-install>/deploy.properties" file.

 

# Setting to enable the use of a per connection 128 bit AES key 
# to encrypt sensitive client server traffic (default true) 
client.encryption.enabled=true

 

The encryption is anonymous - the identity of both the client and server are not verified by the key exchange. If you require all traffic to be secured, have specific encryption strength requirements, or need to have 1 or 2 way certificate based authencation, then SSL should be used.

 

Teiid supports the following SSL modes.

SSL Modes

  • Anonymous  – No certificates are required, but all communications are still encrypted using the TLS_DH_anon_WITH_AES_128_CBC_SHA SSL suite.
  • 1-way – Only authenticates the server to the client.  Requires a private key keystore to be created for the server and a truststore at the client that authenticates that key.  The SSL suite is negotiated.
  • 2-way  – Mutual client and server authentication. The server and client applications each have a keystore for their private keys and each has a truststore that authenticates the other.

Depending upon the SSL mode, follow the guidelines of your organization around creating/obtaining private keys.  If you have no organizational requirements, then follow this guide to create self-signed certificates with their respective keystores and truststores.

 

The following keystore and truststore combinations are required for different SSL modes. The names of the files can be chosen by the user. The following files are shown for example purposes only

 

1-way

  server.keystore - has server's private key

  server.truststore - has server's public key

 

2-way

  server.keystore - has server's private key

  server.truststore - has server's public key

  client.keystore - client's private key

  client.truststore - has client's public key

 

  or

  server.keystore - has server's private key, client's pulic key

  client.keystore - client's private key, and server's public key

 

Configuring SSL in Teiid Server

 

The Teiid's configuration file "<teiid-install>/deploy.properties", contains the following properties to configure SSL.

# SSL Settings
ssl.enabled=true
ssl.protocol=SSLv3
ssl.keystoretype=JKS
ssl.authenticationMode=1-way
#ssl.keymanagementalgorithm=
ssl.keystore.filename=server.keystore
ssl.keystore.Password=changeme
#ssl.truststore.filename=teiid.truststore
#ssl.truststore.Password=<encrypted value>

 

ssl.enabled= true|false  - SSL usage either turned ON or OFF .

 

ssl.protocol - Type of SSL protocol to be used. Default is SSLv3

 

ssl.keystoretype - Keystore type created by the keytool. Default "JKS" is used.

 

ssl.authenticationMode=anonymous|1-way|2-way - Type of SSL mode, see  above about different SSL modes available.

 

ssl.keymanagementalgorithm - Type of key algorithm used. Default is based upon the VM, e.g. "SunX509"

 

ssl.keystore.filename - The file name of the keystore, which contains the private key of the Server. This must be placed inside the "<teiid-installl>/deploy" directory, or must be available in the classpath of Teiid Server.

 

ssl.keystore.password - password for the keystore. Unless encryption is disabled, you should encrypt passwords using the techniques defined here.

 

ssl.truststore.filename - if "ssl.authenticationMode" is chosen as "2-way", then this property must be provided. This is the truststore that contains the public key for the client. Depending upon how you created the keystore and truststores, this may be same file as defined under  "ssl.keystore.filename" property.

 

ssl.truststore.password - password for the truststore.  Unless encryption is disabled, you should encrypt passwords using the techniques defined here.

 

Once all the properties are defined, make sure the certificates are in the right place, then restart the Teiid server to start accepting connections using SSL.

 

Configuring SSL in Teiid's Client

 

Configuring any Java client program with SSL involves modifying scripts that launch the client programs to define few Java VM  system properties using "-Dkey=value" format. The following sections define the system properties required for each SSL mode. Note that when connecting to Teiid Server with SSL enabled, you must use the "mms" protocol, instead of "mm" in the JDBC connection URL, for example

 

    jdbc:teiid:<myVdb>@mms://<host>:<port>

 

There are two different sets of properties that a client can configure to enable  1-way or 2-way SSL.

 

Option 1: Java SSL properties (recommended)

These are standard Java defined system properties to configure the SSL under any JVM, Teiid is not unique in its use of SSL. Provide the following system properties to the client VM process.

 

1-way SSL
-Djavax.net.ssl.trustStore=<dir>/server.truststore (required)
-Djavax.net.ssl.trustStorePassword=<password> (optional)   
-Djavax.net.ssl.keyStoreType (optional)

 

2-way SSL
-Djavax.net.ssl.keyStore=<dir>/client.keystore (required)
-Djavax.net.ssl.keyStrorePassword=<password> (optional)
-Djavax.net.ssl.trustStore=<dir>/server.truststore (required)
-Djavax.net.ssl.trustStorePassword=<password> (optioanl)
-Djavax.net.ssl.keyStroreType=<keystore type> (optional)

Option 2: Teiid Specific Properties

Use this option for "anonymous" mode or when the above "javax" based properties are already in use by the host process. For example if your client application is a Tomcat process that is configured for https protocol and the above Java based properties are already in use, and importing Teiid-specific certificate keys into those https certificate keystores is not allowed.

 

In this scenario, a different set of Teiid-specific SSL properties can be defined inside the "teiid-client-settings.properties" file, such that they do not override the VM specific SSL properties specified for host process. The "teiid-client-settings.properties" file can be found inside the "teiid-{version}-client.jar" file at the root directory location. Extract this file, or make a copy, change the property values required for the chosen SSL mode, and place this file in the client application's classpath before the "teiid-{version}-client.jar" file.

 

SSL properties inside  "teiid-client-settings.properties" are ( read more property comments inline)

 

########################################
# SSL Settings
########################################

#
# The key store type.  Defaults to JKS
#

org.teiid.ssl.keyStoreType=JKS

#
# The key store algorithm, defaults to 
# the system property "ssl.TrustManagerFactory.algorithm"
#

#org.teiid.ssl.algorithm=

#
# The classpath or filesystem location of the
# key store.
# 
# This property is required only if performing 2-way
# authentication that requires a specific private 
# key.
#

#org.teiid.ssl.keyStore=

#
# The key store password (not required)
#

#org.teiid.ssl.keyStorePassword=

#
# The classpath or filesystem location of the
# trust store.
# 
# This property is required if performing 1-way
# authentication that requires trust not provided
# by the system defaults.
#
# Set to NONE for anonymous authentication using
# the TLS_DH_anon_WITH_AES_128_CBC_SHA cipher suite 
#

#org.teiid.ssl.trustStore=

#
# The trust store password (not required)
#

#org.teiid.ssl.trustStorePassword=

#
# The cipher protocol, defaults to SSLv3
#

org.teiid.ssl.protocol=SSLv3

provide the following required properties for different SSL modes.

1-way SSL

        

org.teiid.ssl.trustStore=<dir>/server.truststore (required)
2-way SSL

org.teiid.ssl.keyStore=<dir>/client.keystore (required)
org.teiid.ssl.trustStore=<dir>/server.truststore (required)

 

Anonymous
org.teiid.ssl.trustStore=NONE