<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd">
%CustomDTD;
]>
<chapter id="ssl">
    <title>SSL Client Connections</title>
    
    <para>This chapter will shows you various security configurations 
    that can be used with Teiid in securing your data access. Note that data level
    security called as "data roles" are explained in Reference Guide. This chapter pertains to transport level security.</para>
    
    <section id="default_security">
        <title>Default Security</title>
        
        <para>By default all JDBC/Admin sensitive (non-data) messages between client and server 
        are encrypted using a <ulink url="http://en.wikipedia.org/wiki/Diffie-Hellman_key_exchange">Diffy-Hellman</ulink> 
        key that is negotiated per connection. This 
        encryption is controlled by <code>clientEncryptionEnabled</code> property in <code>JdbcSslConfiguration</code> and 
        <code>AdminSslConfiguration</code> sections in the &jboss-beans; file.</para>
        
        <para>If you are using a socket connection, then you may need to secure the channel more completely - especially if using ODBC, which currently only supports plain text authentication.</para>
    </section>
    
    <section id="ssl_modes">
        <title>SSL Modes</title>
        <para>Teiid supports SSL based channel between the client JDBC application and Teiid Server. Teiid supports the following
        SSL modes.</para>
        <orderedlist>
            <listitem><para>Anonymous  – No certificates are required, but all communications are still 
            encrypted using the TLS_DH_anon_WITH_AES_128_CBC_SHA SSL suite.</para></listitem>
            <listitem><para>1-way – Only authenticates the server to the client traffic.  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.</para></listitem>
            <listitem><para>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.</para></listitem>
        </orderedlist>
        
        <para>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 
        <link linkend="appendix-selfcerts">self-signed certificates</link> with their respective keystores and truststores.</para>
        <para>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.</para>
        
        <para><emphasis>1-way</emphasis> </para>
        <orderedlist>
            <listitem><para>server.keystore - has server's private key</para></listitem>
            <listitem><para>server.truststore - has server's public key</para></listitem>
        </orderedlist>

        <para><emphasis>2-way</emphasis> </para>
        <orderedlist>
            <listitem><para>server.keystore - has server's private key</para></listitem>
            <listitem><para>server.truststore - has server's public key</para></listitem>
            <listitem><para>client.keystore - client's private key</para></listitem>
            <listitem><para>client.truststore - has client's public key</para></listitem>
        </orderedlist>
    </section>
    
    <section id="configure_client">
        <title>Client SSL Settings</title>
        <para>The  
        following sections define the properties required for each SSL mode. Note that when 
        connecting to Teiid Server with SSL enabled, you <emphasis>MUST</emphasis> use 
        the <emphasis>"mms"</emphasis> protocol, instead of "mm" in the JDBC connection URL, for example</para>
        
        <para>jdbc:teiid:&lt;myVdb&gt;@<emphasis>mms</emphasis>://&lt;host&gt;:&lt;port&gt;</para>
        
        <para>There are two different sets of properties that a client can configure to enable 1-way or 2-way SSL.</para>
        
        <section>
            <title>Option 1: Java SSL properties</title>
            <para>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.</para>
            
            <example>
            <title>1-way SSL</title>
           <programlisting><![CDATA[-Djavax.net.ssl.trustStore=<dir>/server.truststore (required)
-Djavax.net.ssl.trustStorePassword=<password> (optional)   
-Djavax.net.ssl.keyStoreType (optional)]]></programlisting>
           </example>
           
           <example>
           <title>2-way SSL</title>
           <programlisting><![CDATA[-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)]]></programlisting>             
           </example>    
        </section>
        
        <section>
            <title>Option 2: Teiid Specific Properties</title>
            <para>Use this option for <emphasis>anonymous</emphasis> 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.</para>
            
            <para>In this scenario, a different set of Teiid-specific SSL properties can be set as system properties or defined inside 
            the "teiid-client-settings.properties" file. The "teiid-client-settings.properties" file 
            can be found inside the "teiid-&versionNumber;-client.jar" file at the root. 
            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-&versionNumber;-client.jar" file.</para>
            
            <para>SSL properties and definitions inside the "teiid-client-settings.properties" are shown below.</para>
            
           <programlisting><![CDATA[########################################
# 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.
#

#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

#
# Whether to allow anonymous SSL
# (the TLS_DH_anon_WITH_AES_128_CBC_SHA cipher suite)
# defaults to true
#

org.teiid.ssl.allowAnon=true]]></programlisting>           
           
           <example>
           <title>1-way SSL</title>
           <programlisting><![CDATA[org.teiid.ssl.trustStore=<dir>/server.truststore (required)]]></programlisting>
           </example>
           
           <example>
           <title>2-way SSL</title>
           <programlisting><![CDATA[org.teiid.ssl.keyStore=<dir>/client.keystore (required)
org.teiid.ssl.trustStore=<dir>/server.truststore (required)]]></programlisting>                
			</example>
			<example>
           <title>Anonymous</title>
           <programlisting><![CDATA[org.teiid.ssl.trustStore=NONE]]></programlisting>                
                     </example>      
        </section>
    </section>
</chapter>