> # Using SSL Encryption

> If your SequeLink environment requires greater data privacy than that provided by fixed-key DES, fixed-key 3DES, or byteswap, you can use SSL to encrypt data exchanged between the JDBC Client and the SequeLink Server. This assumes that the communication between the SequeLink Client machine (for applets, the Web server from which the applets are downloaded) and the SequeLink Server machine is secure, meaning that:

> - Only authorized persons can obtain login access to the Web server machine.
> - Only authorized persons can eavesdrop on (or monitor) the communication (physical communication lines and any intermediate routers) between the Web server host and the database server host. Because the data on your Intranet is not encrypted, you also must ensure that only authorized access to internal communication lines and internal routers is permitted.

> NOTE: SequeLink data scrambling (fixed-key DES, fixed-key 3DES, and byteswap) can work with SSL, resulting in a completely secure combination between the SequeLink Client for JDBC and the SequeLink Server.

> Using SSL with a Java application running on your Intranet, you can secure data over your entire network by installing the SequeLink Proxy Server on the same machine as the SequeLink Server (as shown in Figure 14-2) and specifying `localhost` as the host name of the SequeLink Server in the proxy server configuration file. The cleartext messages that are sent between the SequeLink Proxy Server and the SequeLink Server do not leave the machine.

> Figure 14-2. Using SSL with the SequeLink Proxy Server Installed on the SequeLink Server

> NOTE: SequeLink Proxy Server uses the IETF TLS (Transport Layer Security) 1.0 standard, the successor to the SSL 3.0 protocol.

> ### SSL Cipher Suites

> SSL cipher suite definitions have the format:

> SSL_KeyExchangeMethod_WITH_DataTranserCipher_DigestFunction

> The following cryptographic strong SSL cipher suites are supported by SequeLink when using SSL with the SequeLink Proxy Serve.

> - SSL_DH_anon_WITH_RC4_128_MD5
> - SSL_DH_anon_WITH_3DES_EDE_CBC_SHA
> - SSL_DH_anon_WITH_DES_CBC_SHA
> - SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
> - SSL_DHE_DSS_WITH_DES_CBC_SHA
> - SSL_DHE_DSS_WITH_RC4_128_SHA
> - SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
> - SSL_DHE_RSA_WITH_DES_CBC_SHA
> - SSL_RSA_WITH_3DES_EDE_CBC_SHA
> - SSL_RSA_WITH_DES_CBC_SHA
> - SSL_RSA_WITH_RC4_128_MD5
> - SSL_RSA_WITH_RC4_128_SHA

> ### Cryptographic Characteristics of Key Exchange Algorithms

> Table 14-1 lists the cryptographic characteristics of SSL key exchange algorithms, including a description, the key-size limit, and the type of situation for which specific algorithms are most appropriate.

> Table 14-1. Cryptographic Characteristics of Key Exchange Algorithms
> Key Exchange Algorithm | Description | When to Use
> --- | --- | ---
> DH_anon | The Diffie-Hellman parameters are generated during session establishment. | When there is no risk of man-in-the-middle attacks.
> DHE_DSS | The Diffie-Hellman parameters are generated during session establishment. They are signed by the DSS certificate. | When the DSS certificate of the server is used for signing only and not used for key exchange.
> DHE_RSA | The Diffie-Hellman parameters are generated during session establishment. They are signed by the RSA certificate. | When the RSA certificate of the server is used for signing only and not used for key exchange.
> RSA | The public key from the RSA certificate is used for key exchange. | When the server uses an RSA certificate.

> ### Cryptographic Characteristics of Data Transfer Ciphers

> Table 14-2 lists the cryptographic characteristics of data transfer ciphers, including the algorithm used and the effective key size.

> Table 14-2. Cryptographic Characteristics of Data Transfer Ciphers
> Data Transfer Cipher | Algorithm | Effective Key size
> DES_CBC | DES in cipher block chaining mode | 56
> 3DES_EDE_CBC | Triple DES in cipher block chaining mode | 168
> RC4 | RC4 from RSA | 128

> ### Configuring SSL Encryption for the SequeLink® Proxy Server

> You configure SSL encryption in the proxy server configuration file by adding the keyword=value pairs:

>     Network=ssl
>     CipherSuites=value

> NOTES:

> 1. The Network and CipherSuites keywords in the proxy server configuration file are case-sensitive.
> 2. If you do not want to use SSL, specify `Network=socket` in the proxy server configuration file or omit the Network keyword from the configuration file.
> 3. The value of the CipherSuites keyword is a list of cipher suites to use, in order of preference. The listed cipher suites are separated by commas with no blank spaces allowed. You must specify cipher suites that use the same type of certificate. For example, you cannot specify a combination of RSA cipher suites and DSS cipher suites. See "SSL Cipher Suites" for a list of supported cipher suites.
> 4. For cipher suites that require a DSS or RSA certificate, you must specify the X.509 certificate (with the public key) and the corresponding private key in the proxy server configuration file. See Table 14-3 for a list of the keyword=value pairs you can specify in the proxy server configuration file for each key exchange algorithm.
> 5. When the JDBC Client and the SequeLink Proxy Server agree on a cipher suite that requires a certificate, the JDBC Client must specify the certificate checker class that will be used to verify the certificate chain the SequeLink Proxy Server sends to the JDBC Client. See "Verifying the SequeLink® Proxy Server Certificate" for more information on certificate checker classes.

> Table 14-3 lists the key exchange algorithms you can use and the keyword=value pairs you can specify in the proxy server configuration file when using a particular key exchange algorithm.

> Table 14-3. Key Exchange Algorithms and Keyword/Value Pairs for
> the SequeLink Proxy Server
> Key Exchange Algorithm | Keyword | Value
> --- | --- | ---
> DHE_DSS | DSSCertificate | Name of the file with the DSS certificate in DER format or a PKCS #7 certificate chain.
> | DSSPrivateKey | Name of the file with the DSS private key in PKCS #8 encrypted format.
> | PassPhrase | Pass phrase with which the private key file is encrypted. If this keyword is unspecified, the Proxy Server will prompt for the pass phrase.
> | UsePassPhraseDialog | To be prompted for the pass phrase using the standard input/output instead of a dialog box, set this keyword to `No`. Remember that the pass phrase will be shown on the screen as you type.
> DHE_RSA | RSACertificate | Name of the file with the RSA certificate in DER format or a PKCS #7 certificate chain.
> | RSAPrivateKey | Name of the file with the RSA private key in PKCS #8 encrypted format.
> | PassPhrase | Pass phrase with which the private key file is encrypted. If this keyword is unspecified, the Proxy Server will prompt for the pass phrase.
> | UsePassPhraseDialog | To be prompted for the pass phrase using the standard input/output instead of a dialog box, set this keyword to `No`. Remember that the pass phrase will be shown on the screen as you type.
> RSA | RSACertificate | Name of the file with the RSA certificate in DER format or a PKCS #7 certificate chain.
> | RSAPrivateKey | Name of the file with the RSA private key in PKCS #8 encrypted format.
> | PassPhrase | Pass phrase with which the private key file is encrypted. If this keyword is unspecified, the Proxy Server will prompt for the pass phrase.
> | UsePassPhraseDialog | To be prompted for the pass phrase using the standard input/output instead of a dialog box, set this keyword to `No`. Remember that the pass phrase will be shown on the screen as you type.

> ### Using Private Keys with the SequeLink® Proxy Server

> The SSL cipher suites that use server authentication require a valid server certificate and associated private key. The SequeLink Proxy Server must access the private key from a private key file. Because it is not safe to store the private key as cleartext in a file, the SequeLink Proxy Server expects the private key to be stored in PKCS #8 format, which is a standard method of storing encrypted private keys when the encryption key is derived from a pass phrase.

> #### Providing the Pass Phrase for the SequeLink® Proxy Server

> The SequeLink Proxy Server requires the pass phrase to start. The private key can be retrieved in either of the following ways:

> - When the SequeLink Proxy Server starts, it prompts for the private key. In graphical user interface (GUI) environments, a dialog box may appear. For example:

> Type the pass phrase in the appropriate field of the dialog box and click OK.

> In situations without a GUI, such as when the SequeLink Proxy Server is running in a terminal session on a UNIX machine, specify `UsePassPhraseDialog=No` in the proxy server configuration file. The SequeLink Proxy Server will use the standard input/output of your environment to prompt for the private key. When you type the pass phrase and press ENTER, the pass phrase displays on your standard output. When you are finished, make sure to scroll the output window so that unauthorized persons cannot see the pass phrase on your screen.

> - Code the pass phrase in the proxy server configuration file. Add the keyword=value pair:

> PassPhrase=`pass_phrase`

> where `pass_phrase` is the pass phrase required to access the private key. Leading and trailing blanks are stripped from the value when the pass phrase is retrieved from the configuration file; therefore, the pass phrase cannot have leading or trailing blanks in the configuration file. Make sure that only trusted accounts have access to the configuration file.

> NOTE: If the SequeLink Proxy Server will be started as a Windows service, you must specify the pass phrase in the configuration file because the SequeLink Proxy Server cannot prompt for the pass phrase.

> #### Storing the Private Key in PKCS #8 Format

> If your private key is in cleartext format, you can use the encrypt.bat utility (on Windows) or the encrypt.sh shell script (on Linux/UNIX) to store the key in a file in PKCS #8 format.

> The private keys are encrypted with triple DES with a 168-bit key derived from the pass phrase using a one-way hash function (SHA).

> To provide sufficient randomness in the generated keys, you must provide sufficient randomness in the pass phrase. The English language has approximately 1.3 bits of randomness for each character; therefore, to provide 168 random bits for the two keys, you must have 130 characters (conservatively) of English text. Using punctuation characters and a mix of upper and lowercase letters, you can construct pass phrases that have more randomness with fewer characters.

> #### Using the Encryption Tool

> On Windows servers:

>     encrypt [-v virtual_machine] infile outfile

> where:

> `virtual_machine` | is the executable name of the JVM that is installed on the machine where you encrypt the key. By default, this BAT file uses the J2SE JVM. If you want to use the Microsoft JVM, specify the optional parameter `-v jview`.
> `infile` | is the name of the cleartext file.
> `outfile` | is the name of the encrypted file.

> On UNIX:

>     encrypt.sh infile outfile

> where:

> `infile` | is the name of the cleartext file.
> `outfile` | is the name of the encrypted file.

> You may want to run the encryption tool on a machine other than the one running the SequeLink Proxy Server and transfer the encrypted file to the SequeLink Proxy Server host to avoid writing a copy of the private key in cleartext on the SequeLink Proxy Server host. Make sure that you transfer the complete proxy/lib directory to the machine on which you want to run the encryption tool.

> The proxy server installation directory also contains a decryption tool that can be used to decrypt a file that has been encrypted with the encryption tool. The encryption and decryption tools prompt for the pass phrase and show it on the screen as you type, so make sure that you close the terminal session window after you have encrypted or decrypted the file to prevent unauthorized people from viewing it.

> #### Using the Decryption Tool

> On Windows servers:

>     decrypt [-v virtual_machine] infile outfile

> where:

> `virtual_machine` | is the executable name of the JVM that is installed on the machine where you encrypt the key. By default, this BAT file uses the J2SE JVM. If you want to use the Microsoft JVM, specify the optional parameter `-v jview`.
> `infile` | is the name of the encrypted file.
> `outfile` | is the name of the cleartext file.

> On UNIX:

>     decrypt.sh infile outfile

> where:

> `infile` | is the name of the encrypted file.
> `outfile` | is the name of the cleartext file.

> #### Verifying the SequeLink® Proxy Server Certificate

> When you use a cipher suite that specifies server authentication, the SSL handshake protocol ensures that the server knows the private key that corresponds to the public key in the certificate. Subsequently, the client application must verify that the server is indeed the server with which it wants to communicate by verifying that the received certificate is the certificate that it expects from the server.

> The JDBC application or applet provides the JDBC Client with a class that implements the com.ddtek.sequelink.cert.CertificateCheckerInterface interface. If you do not supply a class that implements this interface, the connection will be refused.

> This interface is defined as:

>     package com.ddtek.sequelink.cert;
>     public interface CertificateCheckerInterface
>        {
>        public void CheckCertificate(byte [][] certChain)
>           throws SecurityException;
>        }

> The JDBC driver calls this method and passes the X.509 certificate chain that it received during the SSL handshake to the method. All certificates are DER encoded and the server certificate is the first certificate in the array. The checkCertificate method must verify that the received certificate is trusted and is, for example, signed by a trusted authority. If the certificate is not trusted, the method must throw a Security Exception. You specify the name of the class that implements this interface in the certificateChecker keyword in the JDBC connection URL or the data source.

> The driver/examples subdirectory contains the Java source files listed in Table 14-4 as examples of classes that implement CertificateCheckerInterface.

> Table 14-4. Java Source Files Implementing CertificateCheckerInterface
> Java Source File | Description
> --- | ---
> CheckAgainstCertificateFromJar.java | Adapt and use for downloaded applets.
> CheckAgainstCertificateFromFile.java | Adapt and use for Java applications on a client machine.
> KeyStoreCertificateChecker.java | Adapt and use for Java applications that use a Java keystore to verify that the provided certificate chain is trusted.

> These classes retrieve the server certificate from a JAR file, or local file, and compare it with the certificate that is passed as the first element of the certChain parameter to the checkCertificate method. You can change these files as appropriate for your environment.

> Coding the certificate you want to compare other certificates against in the downloaded applet is safe only if no one tampers with the applet while it is being downloaded from your Web server. You must use signed applets and you must configure your Web browser to explicitly check the signer of downloaded applets. Alternatively, you can use a secure and authenticated SSL connection to the web server when downloading the applet.

> ### Using the Demo Certificates, Certificate Checker, and Private-Key Format Conversion Tool

> SequeLink provides some demo applications in the installdir/proxy/demos directory, where installdir is your installation directory, that allow you to create or convert certificates.

> #### Demo Certificates

> The demo certificates that SequeLink provides are intended for testing purposes only and cannot be used to provide secure connections. Table 14-5 lists the private key files and describes the corresponding certificates.

> Table 14-5. Demo Certificates
> File | Descriptions
> --- | ---
> demo-DSA-CA.cer | Demo Certificate Authority with a DSS X.509 certificate. This certificate is self signed.
> demo-DSA-CA.pk8 | Corresponding (PKCS #8 encrypted) private key of the public key provided by the certificate demo-DSA-CA.cer.
> demo-DSA-server.p7b | Demo DSS server X.509 certificate signed with the public key provided by the certificate demo-DSA-CA.cer.
> demo-DSA-server.pk8 | Corresponding (PKCS #8 encrypted) private key of the public key provided by the certificate demo-DSA-server.cer.
> demo-RSA-CA.cer | Demo Certificate Authority with an RSA X.509 certificate. This certificate is self signed.
> demo-RSA-CA.pk8 | Corresponding (PKCS #8 encrypted) private key of the public key provided by the certificate demo-RSA-CA.cer.
> demo-RSA-server.p7b | Demo RSA server X.509 certificate signed with the public key provided by the demo-RSA-CA.cer.
> demo-RSA-server.pk8 | Corresponding (PKCS #8 encrypted) private key of the public key provided by the certificate demo-RSA-server.cer.

> NOTES:

> - To use the demo certificates, you must add slssl.jar (if you are using J2SE 1.3) or slssl14.jar and iaik_jce_full.jar (if you are using J2SE 1.4 or higher) to your CLASSPATH variable.
> - You can re-generate demo certificates by running the following Java program in the installdir/proxy/ directory, where installdir is your installation directory:

> java com.ddtek.sequelink.demo.GenerateDemoCertificates

> - You can customize the generation of these demo certificates by editing the demo.properties file in the installdir/proxy/demos/com/datadirect/sequelink/demo directory, where installdir is your installation directory.

> The following examples show how to use the demo certificates:

> Example A: Using SSL with an RSA Server Certificate

> 1. Start the SequeLink Proxy Server with the following configuration:

> Port=9500

> AdminPort=9600

> Host=SequeLinkhost

> ServerPort=SequeLinkport

> Network=ssl

> CipherSuites=SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA,SSL_
> DHE_RSA_WITH_DES_CBC_SHA,SSL_RSA_WITH_3DES_EDE_CBC_
> SHA,SSL_RSA_WITH_DES_CBC_SHA,SSL_RSA_WITH_RC4_128_MD5,
> SSL_RSA_WITH_RC4_128_SHA

> RSACertificate=cert/demo-RSA-server.p7b

> RSAPrivateKey=cert/demo-RSA-server.pk8

> PassPhrase=Demo Pass Phrase

> where `SequeLinkhost` is the TCP/IP host name or address of the SequeLink Server and `SequeLinkport` is the port on which the SequeLink Server is listening for connection requests.

> 2. Make a connection to the SequeLink Server, for example, using DataDirect Test:

> jdbc:sequelink:ssl://proxyserverhost:9500;
> cipherSuites=SSL_RSA_WITH_RC4_128_MD5;
> certificateChecker=com.ddtek.sequelink.cert.
> AcceptAllCertificateChecker

> where proxyserverhost is the IP address or symbolic host name of your proxy server host.

> If successful, the following message appears:

> Certificate accepted by

> AcceptAllCertificateChecker.

> *** ONLY FOR TESTING PURPOSES ***

> Certificate chain:

> 1: O=SequeLink Demo Certificates, OU=Demo RSA

> Server Certificate, CN=demo.ddtek.sequelink.com

> 2: O=SequeLink Demo Certificates, CN=Demo RSA CA

> Certificate

> Example B: Using SSL with a DSS Server Certificate

> 1. Start the proxy server with the following configuration:

> Port=9500

> AdminPort=9600

> Host=SequeLinkhost

> ServerPort=SequeLinkport

> Network=ssl

> CipherSuites=SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA,SSL_

> DHE_DSS_WITH_DES_CBC_SHA,SSL_DHE_DSS_WITH_RC4_128_SHA

> DSSCertificate=cert/demo-DSA-server.p7b

> DSSPrivateKey=cert/demo-DSA-server.pk8

> PassPhrase=Demo Pass Phrase

> where `SequeLinkhost` is the TCP/IP host name or address of the SequeLink Server and `SequeLinkport` is the port on which the SequeLink Server is listening for connection requests.

> 2. Make a connection to the SequeLink Server, for example, using DataDirect Test:

> jdbc:sequelink:ssl://proxyserverhost:9500;
> cipherSuites=SSL_DHE_DSS_WITH_DES_CBC_SHA;
> certificateChecker=com.ddtek.sequelink.cert.
> AcceptAllCertificateChecker

> where `proxyserverhost` is the IP address or symbolic host name of your proxy server host.

> If successful, the following message appears:

> Certificate accepted by

> AcceptAllCertificateChecker.

> *** ONLY FOR TESTING PURPOSES ***

> Certificate chain:

> 1: O=SequeLink Demo Certificates, OU=Demo DSA

> Server Certificate, CN=demo.sequelink.ddtek.com

> 2: O=SequeLink Demo Certificates, CN=Demo DSA CA

> Certificate

> Example C: Using SSL with Anonymous Cipher Suites (No Server Authentication)

> 1. Start the proxy server with the following configuration:

> Port=9500

> AdminPort=9600

> Host=`sequeLinkhost`

> ServerPort=`sequelinkport`

> Network=ssl

> CipherSuites=SSL_DH_anon_WITH_3DES_EDE_CBC_SHA,SSL_

> DH_anon_WITH_DES_CBC_SHA,SSL_DH_anon_WITH_RC4_128_MD5

> where `sequeLinkhost` is the TCP/IP host name or address of the SequeLink Server and `sequelinkport` is the port on which the SequeLink Server is listening for connection requests.

> 2. Make a connection to the SequeLink Server, for example, using DataDirect Test:

> jdbc:sequelink:ssl://proxyserverhost:9500;
> cipherSuites=SSL_DH_anon_WITH_DES_CBC_SHA

> where `proxyserverhost` is the IP address or symbolic host name of your proxy server host.

> #### Demo Certificate Checker

> SequeLink provides a demo certificate checker that accepts all server certificates. It displays on the screen a warning and a description of the certificate the client received from the server through the SSL handshake. This certificate checker is implemented by the com.ddtek.sequelink.cert.AcceptAllCertificateChecker class.

> #### Demo Private-Key Format Conversion Tool

> SequeLink provides a private-key format conversion tool that can perform the following tasks:

> - Export a private key and X.509 certificate from a Java keystore (JKS) to an encrypted PKCS #8 private-key file and DER-encoded certificate file
> - Export a private key and X.509 certificate from a PKCS #12 keystore

> The private-key format conversion tool is a command-line tool that uses the following syntax:

>     java.com.ddtek.sequelink.demo.KeyTool
>     [-keystore keystore]
>     [-alias alias]
>     -certfile certfile
>     -keyfile keyfile
>     [-storetype storetype]
>     [-storepass storepass]
>     [-keypass keypass]

> where:

> Parameter | Java Keystore (JKS) Export | PKCS #12 Keystore Export | Description
> --- | --- | --- | ---
> `keystore` | X | X | The file name of the JKS or the PKCS #12 keystore.
> `alias` | X |  | The alias in the JKS. If supplied, it is assumed that the keystore parameter is a JKS.
> `certfile` | X | X | The DER-encoded X.509 certificate file.
> `keyfile` | X | X | The PKCS #8 encoded private key. The private key ends with the same password as the JKS or the PKCS #12 keystore.
> `storetype` | X | X | The type of JKS. The default is jks. This parameter is optional.
> `storepass` | X |  | The password used to protect the JKS or the PKCS #12 keystore. If omitted, you will be prompted for this password.
> `keypass` | X |  | The password that protects the JKS key entry. This parameter is required when the password for the key entry is different from the keystore password.

> To use the demo private-key format conversion tool, you must add slssl14.jar and iaik_jce_full.jar to your CLASSPATH variable.