Caché Security Administration Guide
Using SSL/TLS with Caché
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter describes the use of Caché with SSL (Secure Sockets Layer) and TLS (Transport Layer Security), its successor. Caché supports the use of SSL/TLS to secure connections of several types:

Important:
To use SSL/TLS with ODBC, Caché Studio, or the InterSystems Telnet client, contact the InterSystems Worldwide Response Center (WRC).
As a server, Caché accepts connections and establishes the use of SSL; as a client, Caché is able to connect to servers that require the use of SSL. In all cases, Caché uses what is called an SSL/TLS configuration, which specifies the various characteristics of a Caché instance as part of an SSL/TLS connection.
This chapter has the following sections:
About SSL/TLS
SSL/TLS provides strong protection for communication between pairs of entities. It allows you to perform authentication, data integrity protection, and data encryption.
SSL was created at Netscape in the mid nineteen-nineties. Version 3.0, which is still in use, was released in 1996. TLS was created as a standardization of SSL 3.0 and version 1.0 was released in 1999. The current version of TLS is 1.2. Among the supported versions of SSL/TLS for Caché, InterSystems recommends the use of the latest version available.
The process by which an SSL/TLS connection is established between two entities is known as the SSL/TLS handshake, and it uses a client/server model. Completion of the handshake means that, according to the requirements of the client and the server:
The ciphersuites of the client and server specify how these activities occur as part of the handshake or are supported for a protected connection. Specifically, a peer’s ciphersuites specify what features and algorithms it supports. The client proposes a set of possible ciphers for use; from among those proposed, the server selects one. (If there are no common ciphers between the client and server, the handshake fails.)
To perform the handshake, SSL/TLS typically uses public-key cryptography (though it can use other means, such as the Diffie-Hellman protocol). With public-key cryptography, each peer (either the client or the server) has a public key and a private key. The private key is a sensitive secret value and the public key is a widely published value; typically, the public key is encapsulated in a certificate, which also contains identifying information about the holder, such as a name, organization, location, issuer validity, and so on. For Caché, an SSL/TLS configuration (described in the section About Configurations) specifies a named set of SSL/TLS-related values, including a certificate file, a private key file, and an optional set of ciphersuites.
If successful, the handshake creates session keys that are used to protect subsequent communications.
While Caché and applications require various interactions with SSL/TLS, the end-user typically has no such direct interactions. For example, a browser uses SSL/TLS to establish a secure connection with a specified web site by requiring that the site (the server, in this case) authenticate itself to the browser (which occurs unbeknownst to the browser’s user) and the lock icon that appears in the browser is designed to indicate that SSL/TLS is protecting the connection.
About Configurations
Caché can support multiple configurations, each of which specifies a named set of SSL/TLS-related values. All its existing configurations are activated at startup. When you create a new configuration from the Management Portal, Caché activates it when you save it. The page for managing SSL/TLS configurations is the SSL/TLS Configurations page ([System Administration] > [Security] > [SSL/TLS Configurations]).
This section covers the following topics:
Creating or Editing an SSL/TLS Configuration
The page for creating or editing an SSL/TLS configurations is the SSL/TLS Configurations page ([System Administration] > [Security] > [SSL/TLS Configurations]). To create a new configuration, click Create New Configuration; to edit an existing configuration, click Edit to the right of the name of the configuration. Both these choices display the Edit SSL/TLS Configuration page. (You can also create a new set of configurations for a mirror member by clicking Create Configurations for Mirror; for more information on mirroring and SSL/TLS, see Configuring Caché to Use SSL/TLS with Mirroring.”
When creating or editing an SSL/TLS configuration, the following fields are available:
Note:
The required fields vary, depending on whether the configuration is to be a client or server and on the desired features. Not all fields are required for all SSL configurations.
At the bottom of this page are three buttons:
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 SSL 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:
Both the list of ciphersuite names and the syntax for specifying enabled ciphersuites is described on the ciphers(1) man page 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 for a Caché configuration is TLSv1:SSLv3:!ADH:!LOW:!EXP:@STRENGTH which breaks down into the following group of colon-separated statements:
A Note on Caché Client Applications Using SSL/TLS
For certain activities, you can use Caché instances to support client applications that interact with the Caché superserver. For example, when using SSL/TLS to protect a shadowing connection, a Caché instance serving as a shadow destination would be an SSL/TLS client.
When using client applications that interact with the Caché superserver using SSL/TLS, the following aspects of the configuration require particular attention:
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.”
Deleting a Configuration
The page for deleting an SSL/TLS configuration is the SSL/TLS Configurations page ([System Administration] > [Security] > [SSL/TLS Configurations]). To delete a configuration, click Delete to the right of the name of the configuration. The Portal prompts you to confirm the action.
Reserved Configuration Names
Caché reserves several SSL/TLS configuration names for use with particular features. When using such a feature, you must use the reserved configuration name(s). The reserved configuration names are:
Important:
For SSL/TLS to function properly, you must use the exact case for each configuration name as it appears here.
Configuring the Caché Superserver to Use SSL/TLS
To use SSL/TLS for communications among components of Caché, configure the Caché superserver to use SSL/TLS. To do this, the procedure is:
  1. From the Management Portal home page, go to the SSL/TLS Configurations page ([System Administration] > [Security] > [SSL/TLS Configurations]).
  2. On the Edit SSL/TLS Configuration page, create an SSL/TLS server configuration with a configuration name of %SuperServer (using the exact case as specified here). For details about creating an SSL/TLS configuration, see the section Creating or Editing an SSL/TLS Configuration.”
  3. On the System-wide Security Parameters page ([System Administration] > [Security] > [System Security] > [System-wide Security Parameters]), for the Superserver SSL/TLS Support field, choose Enabled. This specifies that the superserver supports (but does not require) SSL/TLS-secured connections.
    Note:
    If you wish to configure the superserver to require SSL/TLS-secured connections, first specify that SSL/TLS is simply enabled. Once you have verified that this works, consult with the WRC about properly configuring the instance to require SSL/TLS.
  4. Set up clients to use SSL/TLS as appropriate (see the next section).
Configuring the Caché Telnet Service to Use SSL/TLS
The Caché Telnet service (%Service_Telnet) supports SSL/TLS-protected connections. To establish the use of SSL/TLS for the Telnet service, the steps are:
Configuring the Caché Telnet Server for SSL/TLS
To configure the Caché Telnet server to use SSL/TLS, the procedure is:
  1. If there is not already a %SuperServer SSL/TLS configuration associated with the Caché server, create one as described in the section Creating or Editing an SSL/TLS Configuration.”
  2. From the Management Portal home page, go to the SSL/TLS Configurations page ([System Administration] > [Security] > [SSL/TLS Configurations]).
  3. On the Edit SSL/TLS Configuration page, create an SSL/TLS configuration with a configuration name of %TELNET/SSL.
  4. On the System-wide Security Parameters page ([System Administration] > [Security] > [System Security] > [System-wide Security Parameters]), for the Superserver SSL/TLS Support field, choose Enabled. This specifies that the Telnet server supports (but does not require) SSL/TLS-secured connections.
    Note:
    Even if you plan to configure the superserver to require SSL/TLS-secured connections, first specify that SSL/TLS is simply enabled. Once you have verified that this works, consult with the WRC about properly configuring the instance to require SSL/TLS.
  5. Make sure the Telnet service, %Service_Telnet, is enabled. To do this:
    1. On the Services page ([System Administration] > [Security] > [Services]), click %Service_Telnet to display the Edit Service page for the Telnet service.
    2. On the Edit Service page, check Service Enabled if it is not already checked.
    3. Click Save to save the settings and to return to the Services page.
Configuring Telnet Clients for SSL/TLS
Caché accepts SSL/TLS connections from third-party Telnet clients. The required or recommended actions for configuring Telnet clients and servers depend on the selected ciphersuites and vary widely.
Important:
To use SSL/TLS with the InterSystems Telnet client, contact the InterSystems Worldwide Response Center (WRC).
The following guidelines apply:
For information on how certificate and certificate chains are used for authentication, see the section Establishing the Required Certificate Chain.”
Configuring .NET Clients to Use SSL/TLS with Caché
This section describes how to configure a .NET client application to use SSL/TLS when it communicates with Caché. This communication occurs through the superserver, so a related required step is setting up the superserver to use SSL/TLS; the process of creating or editing a configuration generally is described in the section Creating or Editing an SSL/TLS Configuration and that of setting up a superserver to use SSL/TLS is described specifically in the section Configuring the Caché Superserver to Use SSL/TLS.”
The process for establishing a .NET connection that uses SSL/TLS is:
  1. Ensure that you have installed any relevant CA certificates for validating the server certificate. The location for these is the current user’s certificate store (Certificates – Current User\Trusted Root Certification Authorities).
  2. Establish a connection to a server, based on the format of the connection string as described in the Creating a Connection section of the “Connecting to the Caché Database” chapter of Using the Caché Managed Provider for .NET. In addition to the name-value pairs for the server, port, and namespace, include the SSL keyword and specify its value as true. For example, a connection that uses SSL/TLS protection might have a connection string of the form:
    CacheConnect.ConnectionString = 
        "Server=localhost; Port=1972; Namespace=SAMPLES; SSL=true;"
        + "Password=SYS; User ID=_SYSTEM;";
    
    The true value of the SSL keyword specifies that SSL/TLS secures the client-server connection (by authenticating the Caché server to the .NET client and, optionally, authenticating the client to the server). Once the secure connection is established, the Caché server uses the User ID and Password keywords to authenticate the identity of the user connecting through the .NET client. (Note that the connection string does not specify anything related to mutual authentication; it merely specifies a server, which in turn may request or require client authentication.)
Configuring Java Clients to Use SSL/TLS with Caché
This section describes how to configure a Java client application to use SSL/TLS when it communicates with Caché. This communication occurs through the superserver, so a related required step is setting up the superserver to use SSL/TLS; this is described in the section Configuring the Caché Superserver to Use SSL/TLS.” Java clients can be implemented using either JDBC or object bindings.
The process for configuring a Java client application to use SSL/TLS with Caché is:
  1. Determine if the client requires a keystore or a truststore. This depends on several factors: whether or not the Caché server requests or requires client authentication; whether server authentication is required; and the ciphersuites in use. See Determining the Need for a Keystore and a Truststore for more information.
  2. Create a configuration file with properties in it to provide those features. See Creating a Client Configuration for more information.
  3. In the code for the client application, optionally specify the name of the client configuration; if you do not specify a name, Java uses the default configuration information. See Specifying the Use of the Client Configuration for more information.
Determining the Need for a Keystore and a Truststore
A keystore serves as a repository for the client’s private key, public key certificate, and any Certificate Authority (CA) information. This information is needed (1) if the Caché server requires client authentication or (2) if the ciphersuite in use requires a client key pair:
If the client has a private key and certificate, these are stored in the client’s keystore; the keystore can also hold the client’s root CA certificate and any intermediate CA certificates. To authenticate the server, the client may need to have the root CA certificate for the server and any intermediate CA certificates, these can be stored either in the client’s truststore or along with client certificate information in the keystore. For more information on keystores and truststores, see the section “Keystores and Truststores” in the Java Secure Socket Extension (JSSE) Reference Guide.
Creating a Client Configuration
The behavior of a Java client depends on the values of properties in its configuration. The configuration gets these values from what is known as a “configuration file,” either from the configuration file’s default values or from its configuration-specific values. The following sections describe how configuration files work:
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:
A Sample Configuration File
The following is a sample configuration file for use with a Java client:
debug = true
protocol = SSLv3
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.SSL.ConfigFile to the name of the file. The code checks for the file in the current working directory.
Specifying the Use of the Client Configuration
Once a configuration has been defined, client application code invokes it when connecting to the server. You can do this either with calls for the DriverManager object or the CacheDataSource object.
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
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 SSL/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:
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 “SSL 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.
Configuring Caché to Use SSL/TLS with Mirroring
This section covers the following topics:
For general information about Caché support for mirroring, see the Mirroring chapter of the Caché High Availability Guide.
About Mirroring and SSL/TLS
To provide security within a mirror, you can configure its nodes to use SSL/TLS. This provides for both authentication of one node to another, and for encrypted communication between nodes. As sensitive data passes between the failover members (and to an async member), it is recommended to encrypt the communication to prevent data theft or alteration over the network. Additionally, since a failover member has the ability to request an ISCAgent to take action on another Caché system (such as to request journal file information or force Caché down), it is important to protect such communication between the failover members of a mirror (and their corresponding ISCAgent processes).
Note:
If the failover members use database (or journal) encryption, then SSL/TLS is required for communications between them and with any async members. (Specifically, Caché checks if either member has an encryption key activated; if so, the instance requires that the user enable SSL/TLS with mirroring.) For more details on database encryption and journal file encryption, see the chapter Managed Key Encryption.”
To both participate in mirroring (either as a failover member or as an async member) and use SSL/TLS, an instance must have two Caché SSL/TLS configurations – one of type server and the other of type client; each of these must have an X.509 SSL/TLS certificate issued by a trusted Certificate Authority. The certificates should contain a unique identifier in the Common Name (CN) component of the certificate, such as the fully qualified domain name (FQDN) of the instance plus the member’s Caché node name; because the CN is a field in a certificate’s distinguished name (DN), establishing a unique CN ensures that the certificate’s DN uniquely identifies the member. To create an instance’s mirroring configurations, follow the procedure in the next section.
When SSL/TLS is enabled, the following actions occur:
  1. Server authentication: When the client connects to the server, it requires the server to authenticate itself. This authentication verifies that the DN for the server’s certificate matches the DN for a system configured in the client’s mirror configuration. If there is no match, the client drops the connection.
  2. Client authentication: When the server accepts a connection from a client, it requires the client to authenticate itself. This authentication also verifies that the DN for the client’s matches the DN for a system configured in the server’s mirror configuration. Again, if there is no match, the server drops the connection.
  3. Encryption: The SSL protocol automatically uses the server’s certificate to establish an encrypted channel between the client and the server, so that any data passing through this channel is encrypted and thereby secured.
InterSystems strongly recommends using SSL/TLS with a mirror.
Note on Configuring an Async Member with SSL/TLS
If a mirror uses SSL/TLS, then in addition to enabling SSL/TLS for the mirror and creating the configurations for each member (described in the following section), there are special steps that must be taken when configuring an async member. These are part of the procedure described in the Adding Authorized Async Members to Mirrors section of the “Mirroring” chapter of the Caché High Availability Guide. Specifically, for each failover member, on the Mirror Monitor page, you need to enter the DN (distinguished name) in the ID listed as DN in member’s X.509 credentials field; you can copy the value of the DN from X.509 Distinguished Name field of the Join Mirror as Async page ([System Administration] > [Configuration] > [Mirror Settings] > [Join Mirror as Async]) for the async member. (Caché populates the X.509 Distinguished Name field based on the information in the async member’s certificate.)
Note on Disabling SSL/TLS for a Mirror
If you need to disable SSL/TLS for an existing mirror, first disable it on the secondary and async members, then disable it on the primary member.
Important:
Use of SSL/TLS with mirroring is highly recommended. Disabling SSL/TLS for a mirror is strongly discouraged.
Creating and Editing an SSL/TLS Configuration for a Mirror
To use SSL/TLS with a mirror, each member (failover or async) uses a pair of SSL/TLS configurations that are called %MirrorClient and %MirrorServer; the Portal allows you to create and edit these configurations.
Note:
These configurations must already exist on each member when SSL/TLS is enabled for the mirror.
Creating an SSL/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:
  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. This displays the Create SSL/TLS Configurations for Mirror page.
  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 an SSL/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:
    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 SSL/TLS Configurations for a Mirror Member
If you have already created a member’s %MirrorClient and %MirrorServer configuration, you can edit them on the Edit SSL/TLS Configurations for Mirror page. To do this, on the SSL/TLS Configurations page ([System Administration] > [Security] > [SSL/TLS Configurations]), click Edit Configurations for Mirror, which displays the Edit SSL/TLS Configurations for Mirror page: 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 SSL/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 SSL/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:
Similarly, if the Extended Key Usage extension is present, then it must specify both:
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 SSL/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:
Configuring Caché to Use SSL/TLS with TCP Devices
This section describes how to use SSL/TLS with a Caché TCP connection. The process is:
  1. Creating an SSL/TLS configuration that specifies the characteristics you want.
  2. Opening a TCP connection or open a socket for accepting such connections.
  3. Securing the connection using SSL/TLS. This can occur either as part of opening the connection/socket or afterwards.
How you invoke the Caché SSL/TLS functionality depends on whether you are using Caché as a client or server and whether you are creating an initially-secured TCP connection or adding SSL/TLS to an existing connection.
This section addresses the following topics:
Configuring a Client to Use SSL/TLS with a TCP Connection
To establish a secure connection from a client, the choices are:
Opening an SSL/TLS-secured TCP Connection from a Client
In this scenario, Caché is part of the client and the TCP connection uses SSL/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.
If Caché is a client, then it connects to the server via the client application. The connection uses the specified configuration to determine its SSL-related behavior.
Opening a TCP Connection Using SSL/TLS
This involves opening a named connection that uses SSL/TLS and communicates with a particular machine and port number. The procedure is:
  1. Specify the device that you are connecting to:
     Set MyConn = "|TCP|1000"
    The TCP string specifies that this is a TCP device. For more information on initiating a TCP connection, see the section OPEN Command for TCP Devices in the “TCP Client/Server Communication” chapter of the Caché I/O Device Guide.
  2. Open the connection, specifying the use of SSL with either the /SSL or /TLS parameter.
     OPEN MyConn:(SvrID:1000:/SSL="MyCfg")
    where
    This call opens a TCP connection to the loopback processor (that is, the local machine) on port 1000 using SSL. It uses SSL according to the characteristics specified by the MyCfg configuration.
    Optionally, the call can include a password for the private key file:
     OPEN MyConn:(SvrID:1000:/SSL="MyCfg|MyPrivateKeyFilePassword")
    Here, all the arguments are as above and MyPrivateKeyFilePassword is the actual password.
    For more information on opening a TCP device, see OPEN and USE Command Keywords for TCP Devices in the “TCP Client/Server Communication” chapter of the Caché I/O Device Guide.
Once the connection is established, you can then use it in the same manner as any other TCP connection.
Adding SSL/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.
Securing an Existing TCP Connection Using SSL/TLS
This involves adding SSL/TLS to an already-existing connection to a particular machine and port number. The procedure is:
  1. Determine the name of the device to which there is a connection. For example, this might have been established using the following code:
     SET MyConn="|TCP|1000"
     OPEN MyConn:("localhost":1000)
    The TCP string specifies that this is a TCP device. For more information on initiating a TCP connection, see the section OPEN Command for TCP Devices in the “TCP Client/Server Communication” chapter of the Caché I/O Device Guide.
  2. Specify the use of SSL/TLS as follows with either the /SSL or /TLS parameter:
     USE MyConn:(::/TLS="MyCfg")
    where
    Optionally, the call can include a password for the private key file:
     USE MyConn:(::/TLS="MyCfg|MyPrivateKeyFilePassword")
    Here, all the arguments are as above and MyPrivateKeyFilePassword is the actual password.
    For more information on opening a TCP device, see OPEN and USE Command Keywords for TCP Devices in the “TCP Client/Server Communication” chapter of the Caché I/O Device Guide.
Having added SSL/TLS security to the connection, you can continue to use it in the same manner as before.
Configuring a Server to Use SSL/TLS with a TCP Socket
To enable a socket to require a secure connection from a client, you can either:
Establishing an SSL/TLS-secured Socket
In this scenario, Caché is the server and the TCP socket uses SSL/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 SSL/TLS.
This socket requires the use of SSL/TLS from clients connecting to it. When a client attempts to connect to the server, the server attempts to negotiate a connection that uses SSL/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.
Opening a TCP Socket Requiring SSL/TLS
To open a socket that requires SSL/TLS, the procedure is:
  1. Specify the device that is accepting connections:
     SET MySocket = "|TCP|1000"
    The TCP string specifies that this is a TCP device. For more information on initiating a TCP connection, see the section OPEN Command for TCP Devices in the “TCP Client/Server Communication” chapter of the Caché I/O Device Guide.
  2. Open the connection, specifying the use of SSL with either the /SSL or /TLS parameter.
     OPEN MySocket:(:1000:/TLS="MyCfg")
    Optionally, the call can include a password for the private key file:
     OPEN MySocket:(:1000:/TLS="MyCfg|MyPrivateKeyFilePassword")
    This call opens a TCP socket on port 1000 using TLS. For more information on opening a TCP device, see OPEN and USE Command Keywords for TCP Devices in the “TCP Client/Server Communication” chapter of the Caché I/O Device Guide.
Adding SSL/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.
Securing an Existing TCP Connection to the Socket Using SSL/TLS
This involves adding SSL/TLS to an already-existing connection to a socket on a particular machine and port number. The procedure is:
  1. Determine the name of the device on which the socket is open. For example, this might have been established using the following code:
     SET MySocket = "|TCP|1000"
     OPEN MySocket:(:1000)
    The TCP string specifies that this is a TCP device. For more information on initiating a TCP connection, see the section OPEN Command for TCP Devices in the “TCP Client/Server Communication” chapter of the Caché I/O Device Guide.
  2. Specify the use of SSL/TLS as follows with either the /SSL or /TLS parameter:
     USE MySocket:(::/SSL="MyCfg")
    where
    Optionally, the call can include a password for the private key file:
     USE MySocket:(::/SSL="MyCfg|MyPrivateKeyFilePassword")
    For more information on opening a TCP device, see OPEN and USE Command Keywords for TCP Devices in the “TCP Client/Server Communication” chapter of the Caché I/O Device Guide.
Having added SSL/TLS security to the socket, you can continue the connection to it in the same manner as before.
Configuring the CSP Gateway to Connect to Caché Using SSL/TLS
You can use SSL/TLS to set up a secure, encrypted channel between the CSP Gateway and the Caché server. To do this, you need an SSL/TLS certificate and private key that represents the Gateway. The Gateway can then establish an encrypted connection to the Caché server (which has its own certificate and private key), so that all information is transmitted through the connection.
Note:
For information on setting up a connection between the CSP Gateway and the Caché server that is protected by Kerberos, see the Setting Up a Kerberized Connection from the CSP Gateway to Caché section of the “Authentication” chapter.
The procedure is:
  1. If there is not already a %SuperServer SSL/TLS configuration associated with the Caché server, create one as described in the section Creating or Editing an SSL/TLS Configuration.”
  2. On the Portal’s System-wide Security Parameters page ([System Administration] > [Security] > [System Security] > [System-wide Security Parameters]), for the Superserver SSL/TLS Support choice, select Enabled (not Required).
  3. Go to the CSP Gateway’s Server Access page ([System Administration] > [Configuration] > [CSP Gateway Management]).
  4. On that page, under Configuration, select Server Access.
  5. Next, select Edit Server and click Submit. This displays the configuration page for the CSP Gateway.
  6. On this page, configure the CSP Gateway to use SSL/TLS. Specifically, for the Connection Security Level field, select SSL.
Establishing the Required Certificate Chain
For a connection to be successfully established using a ciphersuite that uses certificates and keys, the client must be able to verify the server’s certificate chain from the server’s own certificate to a self-signed certificate from a trusted certificate authority (CA), including intermediate certificates (if any). If the server is authenticating the client user, then the server must also be able to verify the client user’s certificate chain from the client user’s own certificate to a trusted CA’s self-signed certificate, including intermediate certificates (if any).
Since authentication can be bidirectional, the requirements for certificate chains refer to the verifying entity (the side requiring the authentication) and the verified entity (the side being authenticated), rather than the client and the server.
For authentication to be possible, the following conditions must be met:
Suppose there are:
The following are valid distributions of certificates between the verified entity and the verifying entity:
Valid Certificate Distribution Schemes
Certificates in the Verified Entity’s Certificate File Certificates in the Verifying Entity’s Trusted CA Certificate File
VE ICA1, ICA2, RootCA
VE, ICA1 ICA2, RootCA
VE, ICA1, ICA2 RootCA
Note that it is not valid to have VE and ICA2 in the verified entity’s certificate file and ICA1 and RootCert in the verifying entity’s trusted CA certificate file