Using TLS with Caché

Required Information for Certificates

When a client authenticates a server, the client needs to have the full certificate chain from the server’s own certificate to the server’s trusted CA certificate — including all intermediaries between the two.

There is an issue when setting up a server TLS configuration and the server’s trusted CA certificate is not a root certificate. In order for authentication to work properly, the client needs to have access to all the certificates that constitute the certificate chain from the server’s personal certificate to a self-signed trusted CA certificate. This chain can be obtained from the combination of the server’s certificate file (sent during the handshake) and the client’s trusted CA certificate file. The self-signed trusted root CA certificate must be in the client’s CA certificate file, and the server’s personal certificate must be the first entry in the server’s certificate file. Other certificates may be divided between the two locations. The same constraints apply in reverse when a client authenticates to a server.

Regarding certificate formats, note that certificates from the Windows Certificate Export Wizard must be in base-64 encoded X.509 format, not the default of DER encoded binary X.509.

Enabled Ciphersuites Syntax

A configuration only allows connections that use its enabled ciphersuites. To specify enabled ciphersuites, you can either:

• Provide a list of individual ciphersuites, using each one’s name.

• Use OpenSSL syntax for specifying which ciphersuites to enable and disable.

Both the list of ciphersuite names and the syntax for specifying enabled ciphersuites is described on the ciphers(1) man pageOpens in a new tab at openssl.org. This syntax allows you to specify guidelines for requiring or proscribing the use of various features and algorithms for a configuration.

The default set of cipher suites for a Caché configuration is ALL:!aNULL:!eNULL:!EXP:!SSLv2 which breaks down into the following group of colon-separated statements:

• ALL — Includes all cipher suites except the eNULL ciphers

• !aNULL — Excludes ciphers that do not offer authentication

• !eNULL — Excludes ciphers that do not offer encryption

• !EXP — Excludes export-approved algorithms (both 40- and 56-bit)

• !SSLv2 — Excludes SSL v2.0 cipher suites

A Note on Caché Client Applications Using TLS

For certain activities, you can use Caché instances to support client applications that interact with the Caché superserver. For example, when using TLS to protect a shadowing connection, a Caché instance serving as a shadow destination would be a TLS client.

When using client applications that interact with the Caché superserver using TLS, the following aspects of the configuration require particular attention:

• Configuration Name — While there are no constraints on the name of clients, this information is required to configure the connection.

• Type — Because the instance is serving with a TLS client, the type must be specified to be of type Client.

• Ciphersuites — The specified ciphersuites need to match those required or specified by the server.

It is also necessary to ensure that the client and the server are configured so that each may verify the other’s certificate chain, as described in the section “Establishing the Required Certificate Chain.”

Configuration Files, Configurations, Properties, Values, and Defaults

Each configuration file specifies values for the properties that one or more configurations use. The file includes both default values and configuration-specific values, in the form of name-value pairs. Generally, unversioned property names specify default values for properties and versioned property names specify configuration-specific values.

If a configuration file contains only one configuration definition, that single configuration can use unversioned properties. However, it cannot have an associated name property. Without a named configuration, invoke the configuration without specifying a name (as described in “Specifying the Use of the Client Configuration” and “Specifying a Configuration without a Name”).

If a configuration file contains multiple configurations, each configuration is defined by the existence of a numbered version of the name property of the form name.n, where n is the number of the configuration. The names of a configuration’s other properties use the same version number as the name property, so that they have a form of propertyname.n where propertyname is the name of the property and n is the number of the configuration.

The definitions in a configuration file are case-sensitive. Their use of spaces is flexible. The order of property definitions is also flexible.

To specify the default value of a property for use by all configurations, specify an unversioned property name and its value in the following form:

propertyName = propertyValue

For example, to specify the default value for the keyStoreType property as pkcs12, the form is:

keyStoreType = pkcs12

To override the default value for a property, specify a versioned property name, such as:

keyStoreType.1 = jceks

If a configuration file contains multiple configuration definitions, then these versions must use sequential ordering; if client application code refers to a configuration that follows a sequential gap, then an error results. For example, suppose that a configuration file has three versioned name properties: name.1, name.2, and name.4; the configuration associated with the name.4 property will not ever be created and a reference to it will fail with an error.

Java Client Configuration Properties

The properties are:

• cipherSuites — A comma-delimited list of ciphersuites, in order of preference for their use. The available ciphersuites depend on the JRE (Java Runtime Environment) on the machine. [Optional]

• debug — Whether or not debugging information is logged to the Java system.err file. This property can have a value of true or false (false is the default). The setting of this property has no effect on exception handling. [Optional]

• keyRecoveryPassword — Password used to access the client’s private key; this was created at the same time as the private key pair. [Required if the private key has password protections and application code is not passing in the private key as an input parameter.]

• keyStore — The file for storing the client private key and certificate information. The keystore can also hold the content typically associated with the truststore. [Optional]

• keyStorePassword — Password to gain access to the keystore. [Required if a password was specified when the keystore was created.]

• keyStoreType — The format of the keystore file, if one is specified. [Optional]

  Supported formats are:

  • jks — Java KeyStore, the Java proprietary format. [Default]

  • jceks — Java Cryptography Extension KeyStore format.

  • pkcs12 — Public Key Certificate Standard #12 format.

• logFile — The file in which Java records errors. [Optional]

• name — A versioned identifier for the Java client configuration. (Each name property must be versioned. Any unversioned name property is not meaningful and is ignored.)

  If the configuration file specifies only a single configuration and only uses unversioned property names, the name property is not required (as described in “Specifying the Use of the Client Configuration”). For information about specifying multiple configurations with a single configuration file, see the section “Configuration Files, Configurations, Properties, Values, and Defaults”). [Optional]

• protocol — [Required] The protocol to be used for the connection. The options and the protocols they specify are:

  • SSL — Some variant of SSL.

  • SSLv3 — Version 3 of SSL.

  • TLS — Some variant of TLS. [Default]

  • TLSv1 — Version 1 of TLS.

  • TLSv1.1 — Version 1.1 of TLS.

  • TLSv1.2 — Version 1.2 of TLS.

• trustStore — The file for storing the server’s root CA certificate; it can also hold the certificates for any intermediate CAs. (This information can also be placed in the keystore.) [Optional]

• trustStorePassword — Password to gain access to the truststore. [Required if a password was specified when the keystore was created.]

• trustStoreType — The format of the truststore file, if one is specified. [Optional]

  Supported formats are:

  • jks — Java KeyStore, the Java proprietary format. [Default]

  • jceks — Java Cryptography Extension KeyStore format.

  • pkcs12 — Public Key Certificate Standard #12 format.

A Sample Configuration File

The following is a sample configuration file for use with a Java client:

debug = true
protocol = TLSv1.2
cipherSuites = SSL_RSA_WITH_RC4_128_MD5
keyStoreType = JKS
trustStore = ca.ts
trustStoreType = JKS

name.1 = CacheJavaClient1
keyStore.1 = cjc1.ks
keyStorePassword.1 = cjc1kspw123&XtraChar$
trustStore.1 = cjc1.ts
trustStorePassword.1 = cjc1tspw[+0therNo|sechars]

name.2 = CacheJavaClient2
keyStore.2 = cjc2.ks
keyStoreType.2 = pkcs12

name.3 = CacheJavaClient3
debug.3 = false
cipherSuites.3 = TLS_RSA_WITH_AES_128_CBC_SHA

Naming the Configuration File

Either save the configuration file with the name SSLConfig.properties or set the value of the Java environment variable com.intersys.SSLConfigFile to the name of the file. The code checks for the file in the current working directory.

Using the DriverManager Object

With DriverManager, this involves the following steps:

1. Creating a Java Properties object.

2. Setting the value for various properties of that object.

3. Passing that object to Java Connection object for the connection from the client to the Caché server.

To specify information for the connection, the first part of the process is to create a Properties object from a configuration file and set the values of particular properties in it. In its simplest form, the code to do this is:

java.util.Properties prop = new java.util.Properties();
prop.put("connection security level", "10");
prop.put("SSL configuration name",configName);
prop.put("key recovery password",keyPassword);

where

• The connection security level of 10 specifies that the client is attempting use TLS to protect the connection.

• configName is a variable whose value holds the name of Java client configuration. If the configuration file has only default values and these are being used for a single configuration, do not include this line; see the following section, “Specifying a Configuration without a Name”, for details.

• keyPassword is the password required to extract the client’s private key from the keystore.

Once the Properties object exists and has been populated, the final step is to pass it to the connection from the Caché Java client to the Caché server. This is done in the call to the DriverManager.getConnection method. The form of this call is:

Connection conn = DriverManager.getConnection(CacheServerAddress, prop);

where CacheServerAddress is a string that specifies the address of the Caché server and prop is the properties object being passed to that string.

If this call succeeds, the TLS-protected connection has been established. Typically, application code containing calls such as those described in this section includes various checks for success and protection against any errors. For more details about using the Caché Java binding, see Using Java with Caché.

Using the CacheDataSource Object

With the CacheDataSource object, the procedure is to create the object, call its methods to set the relevant values, and establish the connection. The methods are:

• setConnectionSecurityLevel — This method takes a single argument: a connection security level of 10, which specifies that the client is attempting use TLS to protect the connection.

• setSSLConfigurationName — This method takes a single argument: a variable whose value holds the name of Java client configuration. If the configuration file has only default values and these are being used for a single configuration, do not include this line; see the following section, “Specifying a Configuration without a Name”, for details.

• setKeyRecoveryPassword — This method takes a single argument: the password required to extract the client’s private key from the keystore.

In its simplest form, the code to do this is:

try{
   CacheDataSource ds = new CacheDataSource();
   
   ds.setURL("jdbc:Cache://127.0.0.1:1972/Samples");
   ds.setConnectionSecurityLevel(10);
   ds.setSSLConfigurationName(configName);
   ds.setKeyRecoveryPassword(keyPassword);

   Connection dbconnection = ds.getConnection();
}

For a complete list of the methods for getting and setting properties, see the “CacheDataSource” section of the “Caché JDBC Compliance” chapter of Using Caché with JDBC. The JavaDoc for com.intersys.jdbc.CacheDataSource is under <install-dir>/dev/java/doc/index.html

Specifying a Configuration without a Name

If a configuration file contains only one configuration definition, that single configuration can use unversioned properties. However, it cannot have an associated name property.

When working with a DriverManager object, the Properties object uses only the default values from the configuration file. The code for creating this object differs from the typical case in that there is no call to specify a value for the “TLS configuration name” key:

java.util.Properties prop = new java.util.Properties();
prop.put("connection security level", "10");
prop.put("key recovery password",keyPassword);

When working with a CacheDataSource object, if you want to specify an unnamed configuration, simply do not call setSSLConfigurationName.

The Syntax of the Settings File

The settings file contains one ore more connection definitions and one or more configuration definitions:

• Each definition begins with an identifier for the connection or configuration. This appears in brackets on its own line, such as:

  [MyConfiguration]
  

  The identifier can include spaces and punctuation, such as:

  [MyOtherConfiguration, which connects outside of my local network]
  

• Each definition ends either with the next bracketed identifier or the end of the file.

• Each definition includes multiple key-value pairs. All of these use the syntax:

  key=value
  

• The group of key-value pairs specify the properties of a connection definition or configuration definition.

• The value in each key-value pair appears unquoted.

Connection Definitions

Each settings file contains one or more connection definitions, each of which specifies the properties a TLS connection and matches that connection to a TLS configuration. The first line of a connection definition is its identifier, which appears in brackets. After the identifier, there are multiple lines specifying information about the TLS server and the connection to it:

Configuration Definitions

Each settings file contains one or more configuration definitions, each of which specifies the properties of a TLS configuration; for more information on TLS configurations, see “About Configurations.” The first line of a configuration definition is its identifier, which appears in brackets; if the configuration identifier appears as the value of a connection definition’s SSLConfig property, the connection uses the configuration to specify its behavior. After the identifier, there are multiple lines specifying the value of each of the configuration’s properties:

Protocols=24

Creating a TLS Configuration for a Mirror Member

To create the configurations, the procedure is:

1. Enable mirroring for that instance of Caché if it is not already enabled. To do this, use the Edit Service page for the %Service_Mirror service; on this page, select the Service Enabled check box. You can reach this page either of two paths:

   • On the Mirror Settings page (System Administration > Configuration > Mirror Settings), select Enable Mirror Service.

   • On the Services page (System Administration > Security > Services), select %Service_Mirror.

2. Go to the Create SSL/TLS Configurations for Mirror page. You can do this either on the SSL/TLS Configurations page (System Administration > Security > SSL/TLS Configurations) by clicking Create Configurations for Mirror or on the Create Mirror page (System Administration > Configuration > Mirror Settings > Create Mirror) by clicking Set up SSL/TLS.

3. On the Create SSL/TLS Configurations for Mirror page (System Administration > Security > SSL/TLS Configurations > Create SSL/TLS Configurations for Mirror), complete the fields on the form. The fields on this page are analogous to those on the New SSL/TLS Configuration page (as described in the section “Creating or Editing a TLS Configuration”). Since this page creates both server and client configurations that mirroring automatically enables (%MirrorClient and %MirrorServer), there are no Configuration Name, Description, or Enabled fields; also, for the private-key password, this page allows you to enter or replace one (Enter new password), specify that none is to be used (Clear password), or leave an existing one as it is (Leave as is).

   Since both configurations need the same X.509 credentials, completing this form saves both configurations simultaneously. Fields on this page are:

   • File containing trusted Certificate Authority X.509 certificate(s)

     Note:

     This file must include the certificate(s) that can be used to verify the X.509 certificates belonging to other mirror members. If the file includes multiple certificates, they must be in the correct order, as described in Establishing the Required Certificate Chain, with the current instance’s certificate first.

   • File containing this configuration's X.509 certificate

     Note:

     • The certificate’s distinguished name (DN) must appear in the certificate’s subject field.

     • If the certificate to be used includes either Key Usage or Extended Key Usage extensions, see the following section, “Special Considerations for Certificates for Mirror Members.”

   • File containing associated private key

   • Private key type

   • Password

     If you select Leave as is, the page displays two additional fields, for entering and confirming a new password for the private key associated with the certificate.

   • Protocols

   • Enabled ciphersuites

   Once you complete the form, click Save.

For general information about configuring mirror members, see the “Creating a Mirror” section of the “Mirroring” chapter of the Caché High Availability Guide.

Editing TLS Configurations for a Mirror Member

If you have already created a member’s %MirrorClient and %MirrorServer configurations, you can edit them on the Edit SSL/TLS Configurations for Mirror page (System Administration > Security > SSL/TLS Configurations; click Edit Configurations for Mirror). This page displays the same fields as the Create SSL/TLS Configurations for Mirror page, as described in the previous section.

Special Considerations for Certificates for Mirror Members

When using TLS with mirroring, the %MirrorClient and %MirrorServer configurations must use the same certificate and private key. Hence, the certificate in use by both configurations must be usable as both a server and a client certificate.

There are certain certificate extensions that are specific to TLS clients or servers. Because the certificate in use with mirroring must be able to serve both uses (as both a client and a server), if any of these extensions appear in a certificate, then the extensions for client and server must both be present. For example, this is true for the Key Usage and Extended Key Usage extensions. If the Key Usage extension is present, then it must specify both of the following:

• The Digital Signature key usage (for clients)

• The Key Encipherment key usage (for servers)

Similarly, if the Extended Key Usage extension is present, then it must specify both:

• The Client Authentication key usage

• The Server Authentication key usage

If both extensions are present, then each must specify both values. Of course, it is also valid to have neither extension present.

If a certificate only specifies one value (either client or server), the TLS connection for mirroring fails with an error such as:

error:14094413:SSL routines:SSL3_READ_BYTES:sslv3 alert unsupported certificate

The way to eliminate this error depends on how you obtained your certificates:

• If you are using self-signed certificates, create new certificates (such as with the OpenSSL library) that adhere to these conditions.

• If you are using a commercial certificate authority tool (such as Microsoft Certificate Services), create new certificates that adhere to these conditions and use the tool to sign your certificate signing requests (CSRs).

• If you are purchasing certificates from a commercial certificate authority (such as VeriSign), include a request along with your CSRs that they adhere to these conditions.

Opening a TLS-secured TCP Connection from a Client

In this scenario, Caché is part of the client and the TCP connection uses TLS from its inception. The procedure is:

1. Make sure that the configuration you wish to use is available. If it was created before Caché was last started, it is activated and ready for use; otherwise, you can create a new one or edit an existing one.

2. Open a TCP connection using TLS.

If Caché is a client, then it connects to the server via the client application. The connection uses the specified configuration to determine its TLS-related behavior.

Adding TLS to an Existing TCP Connection

This scenario assumes that the TCP connection has already been established. The procedure is:

1. Make sure that the configuration you wish to use is available. If it was created before Caché was last started, it is activated and ready for use; otherwise, you can create a new one or edit an existing one.

2. Secure the existing TCP connection using TLS.

Establishing a TLS-secured Socket

In this scenario, Caché is the server and the TCP socket uses TLS from its inception. The procedure is:

1. Make sure that the configuration you wish to use is available. If it was created before Caché was last started, it is activated and ready for use; otherwise, you can create a new one or edit an existing one.

2. Open a TCP socket that requires the use of TLS.

This socket requires the use of TLS from clients connecting to it. When a client attempts to connect to the server, the server attempts to negotiate a connection that uses TLS. If this succeeds, the connection is available for normal use and communications are secured using the negotiated algorithm. If it fails, there is no connection available for the client.

Adding TLS to an Existing Socket

This scenario assumes that a connection to the TCP socket has already been established. The procedure is:

1. Make sure that the configuration you wish to use is available. If it was created before Caché was last started, it is activated and ready for use; otherwise, you can create a new one or edit an existing one.

2. Use TLS to secure the existing TCP connection to the socket.