Previous section   Next section

Using SSL/TLS with Caché

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:
  • From various client applications that interact with the Caché superserver (including ODBC, JDBC, and Studio). This also includes connections from Caché shadow destinations to Caché shadow sources.
  • From Telnet clients that interact with the Telnet server.
  • For use with TCP connections where a Caché instance is the client or server (or a Caché instance is at each end).
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 client has authenticated the server.
  • The server has authenticated the client. (If the client and the server have both authenticated each other, this known as mutual authentication.)
  • The client and server have agreed upon session keys. (Session keys are the keys for use with a symmetric-key algorithm that allow the entities to protect data during subsequent communications.)
  • Subsequent communication can be encrypted.
  • The integrity of subsequent communication can be verified.
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 configuration is the SSL/TLS Configurations page (System Administration > Security > SSL/TLS Configurations). To create a new configuration, click Create New Configuration, which displays the New SSL/TLS Configuration page; to edit an existing configuration, click Edit to the right of the name of the configuration. (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:
  • Configuration Name — The string by which the configuration is identified. Configuration names can contain any alphanumeric character and any punctuation except the “|” character. If you are creating a configuration for the Caché superserver, the configuration name must be
    %SuperServer
    ; for more information about this topic, see “Configuring the Caché Superserver to use SSL/TLS.”
  • Description — Any text.
  • Enabled — Whether or not the configuration is available for activation.
  • Type — Intended purpose for this configuration, where the choice is Client or Server; the default is Client. Clients initiate the use of the protocol and servers respond to the initial request. (The Caché superserver uses a server configuration; SSL/TLS clients, such as a shadow destination, use a client configuration.) The value chosen for this field determines:
    • Whether the next field is the Server certificate verification or Client certificate verification field. If the configuration is for a client, the next field is the Server certificate verification, which specifies the verification that may be required for the certificate of any server to which the client is connecting; if the configuration is for a server, the next field is the Client certificate verification, which specifies the verification that may be required for the certificate of any client that attempts to connect to the server.
    • The behavior of the File containing trusted Certificate Authority certificate(s) field.
  • Server certificate verification or Client certificate verification — Specifies whether or not the configuration requires the verification of the peer to which it is connecting.
    A configuration for a client must have a specified Server certificate verification and supports possible values of:
    • None — Continues under all circumstances.
    • Require — Continues only if certificate verification succeeds.
    A configuration for a server must have a specified Client certificate verification and supports possible values of:
    • None — Specifies that the server neither requests nor requires a client certificate.
    • Request — Allows the client to provide or not provide a certificate. If the client provides no certificate, then authentication proceeds; if the client provides a certificate and verification fails, then authentication fails.
    • Require — Specifies that the client must provide a certificate; authentication depends on verification of the certificate.
  • File containing trusted Certificate Authority certificate(s) — The path and name of a file that contains the X.509 certificate(s) in PEM format of the Certificate Authority (CA) or Certificate Authorities that this configuration trusts. The configuration uses the certificates of the trusted CA(s) to verify peer certificates. Typically, a production system uses certificates from commercial CAs with publicly available certificates.
    Regarding this field, note the following:
    • You can specify the path of the file as either an absolute path or as a path relative to the <install-dir>
      /mgr/
      directory.
    • For a server configuration with a Client certificate verification value of None, this field is not available, since there is no peer verification.
    • 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.
    • With mirroring, the configuration must also have enough information to verify its own certificate.
    For information on how these certificates are used, see the section “Establishing the Required Certificate Chain.” For information on file names for these certificates and how to verify a certificate chain, see the OpenSSL documentation on the verify command.
  • This client’s credentials or This server’s credentials — The files (if needed) containing the X.509 certificate and private key for the local configuration:
    • File containing this client’s certificate or File containing this server’s certificate — The full location of the configuration’s own X.509 certificate(s), in PEM format. This can be specified as either an absolute or a relative path. This can include a certificate chain. For information on how this is used for authentication, see the section “Establishing the Required Certificate Chain.” (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.)
    • File containing associated private key — The full location of the configuration’s private key file, specified as either an absolute or relative path.
    • Private key type — The algorithm used to generate the private key, where valid options are DSA (Digital Signature Algorithm) and RSA (Rivest, Shamir, and Adleman, for the algorithm’s inventors).
    • Private key password — An optional password for encrypting and decrypting the configuration’s private key.
      Note:
      If the private key is password-protected and you do not enter a value here, Caché cannot confirm that the private key and the certificate’s public key match each other; this can result in mismatched keys being saved as a key pair.
    • Private key password (confirm) — A retyping of the optional password to ensure that it is the intended string.
  • Cryptographic settings:
    • Protocols — Those communications protocols that the configuration considers valid, where the choices are one or more of SSLv3, TLSv1.0, TLSv1.1, and TLSv1.2. The protocols that are enabled by default are TLSv1.1 and TLSv1.2.
      Note:
      InterSystems recommends the use of TLSv1.1 or TLSv1.2 only. InterSystems recommends that you do not use SSLv3 or earlier versions.
    • Enabled ciphersuites — The set of ciphersuites used to protect communications between the client and the server. See the “Enabled Ciphersuites Syntax” section for more information on this topic.
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/TLS configurations.
To complete the process of creating or editing a configuration, use the following buttons, which appear at the top of this page:
  • Save — Dismisses the dialog, saving and then activating the configuration. This saves changes to an existing configuration or the configuration being created.
  • Cancel — Dismisses the dialog without saving changes to an existing configuration or without saving a configuration being created.
  • Test — Checks for valid configuration information. If the configuration’s role is as a client, selecting this button also prompts for a server (its host name, not its URL) and a port number; Caché then tries to establish a test connection to that server. (This button is not available when creating a server configuration.)
    Note:
    The Test button may not be able to successfully connect with all TLS servers, even if the configuration has no errors. This is because the connection test performs a TLS handshake followed by an HTTP request. If the server expects a StartTLS message before the handshake (such as for use with LDAP, SMTP, FTPS, or another protocol), then the test fails, even though the actual SSL/TLS connection to the server succeeds.

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/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 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 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 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:
  • 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 an SSL/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.”

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:
  • %MirrorClient
    — For a mirror member when acting as an SSL/TLS client. For more information on mirroring and SSL/TLS, see “Configuring Caché to Use SSL/TLS with Mirroring.”
  • %MirrorServer
    — For a mirror member when acting as an SSL/TLS server. For more information on mirroring and SSL/TLS, see “Configuring Caché to Use SSL/TLS with Mirroring.”
  • %SuperServer
    — For the Caché superserver when accepting connections from other Caché components. For more information about configuring the superserver to use SSL/TLS, see the next section.
  • %TELNET/SSL
    — For the Windows Telnet server when accepting connections protected by SSL/TLS. For more information on mirroring and Telnet, see “Configuring the Caché Telnet Server for SSL/TLS.”
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 SSL/TLS Configurations page, select Create New Configuration, which displays the New SSL/TLS Configuration page.
  3. On the New 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.”
  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 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.
  5. 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 SSL/TLS Configurations page, select Create New Configuration, which displays the New SSL/TLS Configuration page.
  4. On the New SSL/TLS Configuration page, create an SSL/TLS configuration with a configuration name of
    %TELNET/SSL
    .
  5. 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.
  6. 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:
  • If the Telnet client requires server authentication, then the server must provide a certificate and the client must have access to the server’s certificate chain.
  • If the Caché Telnet server requires client authentication, then the client must provide a certificate and the server must have access to the client’s certificate chain.
  • If the Caché Telnet server requests client authentication, then the client has the option of providing a certificate and a certificate chain to its certificate authority (CA). If the client does not provide a certificate, then authentication succeeds; if it provides a non-valid certificate or certificate chain, then authentication fails.
For information on how certificate and certificate chains are used for authentication, see the section “Establishing the Required Certificate Chain.”

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:
  • Whether or not the Caché server requires client authentication is determined by the choice for the Peer certificate verification level field on the Edit SSL/TLS Configuration page for that Caché instance’s “%SuperServer” SSL/TLS configuration. If the field has a value of
    Require
    , the client must have a certificate; if the field has a value of
    Request
    , the server checks a certificate if one is available.
  • The client and server agree upon a ciphersuite to use. This ciphersuite determines whether or not there is a client certificate, a key pair, or both. The enabled server ciphersuites are determined by the value of the Enabled ciphersuites field on the Edit SSL/TLS Configuration page for that Caché instance’s “%SuperServer” SSL/TLS configuration. The ciphersuites available to the client depend on the version of Java it is using.
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:
  • 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 SSL or TLS 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 (equivalent to version 3.1 of SSL).
    • TLSv1.1
      — Version 1.1 of TLS (equivalent to version 3.2 of SSL).
  • 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 = 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
  • The connection security level of 10 specifies that the client is attempting use SSL/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 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:
  • setConnectionSecurityLevel — This method takes a single argument: a connection security level of 10, which specifies that the client is attempting use SSL/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 “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 .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 verifying 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.)

Connecting from a Windows Client Using a Settings File

Topics in this section include:

Overview of the Process

If you are on Windows and are using Studio, ODBC, or Terminal as an SSL/TLS client, you can use a settings file to configure connections and configurations. This mechanism is available even if there is no instance of Caché on the host.
To use a settings file:
  1. Get the certificate authority (CA) certificate for the server. Store it on disk and note the location — you will use it later.
  2. Create a file containing connection definitions and configuration definitions, as described in the “About the Settings File” section.
  3. Name the file SSLDefs.ini and place it in the InterSystems\Cache directory in the directory for 32-bit common program files. Typically, this is the C:\Program Files (x86)\Common Files\InterSystems\Cache\ directory; if you need to locate the directory, check the value of the Windows environment variable CommonProgramFiles(x86) on 64-bit Windows or CommonProgramFiles on 32-bit Windows.
By creating the file and placing it in this location, it will automatically be used when you connect to a host and a port that match one of the connections listed in the file.
Note:
This feature is only for connections that use the cconnect.dll or cconnect64.dll executable (which are for 32-bit and 64-bit machines, respectively). Connections that use other mechanisms (such as for ADO) do not use the settings file.

About the Settings File

A settings file holds specifications for both connections to SSL/TLS servers and the SSL/TLS configurations that those connections use. For each Windows host that is an SSL/TLS client, a single file holds all its connections and configurations. The necessary information to create a file is:

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 an SSL/TLS connection and matches that connection to an SSL/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 SSL/TLS server and the connection to it:
Address
Required. The address of the SSL/TLS server. This can be an IP address, an unqualified host name in the local domain, or a fully-qualified hostname. (Note: The client only uses the specified configuration if the values of both Address and either Port or TelnetPort match the server to which the client application is connecting.)
Port
Required. The port number on which the SSL/TLS server accepts connections. (Note: The client only uses the specified configuration if the values of both Address and either Port or TelnetPort match the server to which the client application is connecting.)
TelnetPort
The port number on the SSL/TLS server that accepts SSL/TLS-protected connections for InterSystems Telnet. If you do not specify this value, connections using InterSystems Telnet do not support SSL/TLS. (Note: The client only uses the specified configuration if the values of both Address and either Port or TelnetPort match the server to which the client application is connecting.)
SSLConfig
Required. The SSL/TLS configuration that the client uses when connecting to the server specified in this definition. Each configuration is defined in its own section.

Configuration Definitions

Each settings file contains one or more configuration definitions, each of which specifies the properties of an SSL/TLS configuration; for more information on SSL/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
Required. The SSL/TLS protocol(s) that the configuration supports. The available protocols are:
  • SSLv3 — 2
  • TLSv1 — 4
  • TLSv1.1 — 8
  • TLSv1.2 — 16
where each protocol has a numeric value. To specify support for multiple protocols, use the sum of their values. Hence, to specify the use of TLSv1.1 and TLSv1.2, use:
Protocols=24
This property is equivalent to the Protocols field in the SSL/TLS configuration page in the Management Portal.
VerifyPeer
Required. Whether or not the client requires the verification of the server to which it is connecting:
  • 0 — Does not require (and does not perform) peer verification; the connection is established under all circumstances.
  • 2 — Requires peer verification; the connection is established only if verification succeeds. This is the recommended value; if you choose this value, you must specify a value for the CAFile property.
This property is equivalent to the Server certificate verification field in the SSL/TLS configuration page in the Management Portal.
VerifyHost
Whether or not the client checks if the Common Name or subjectAlternativeName fields of the server’s certificate match the host name or IP address as specified in the connection definition:
  • 0 — Does not check.
  • 1 — Checks.
This property does not have an equivalent in the Management Portal. However, it is the same type of check as the SSLCheckServerIdentity property of the %Net.HttpRequest class.
CipherList
Required. The set of ciphersuites that the client supports for encryption and hashing. This property uses the syntax described on the ciphers(1) man page at openssl.org.
InterSystems strongly suggests using a value of
ALL:!aNULL:!eNULL:!EXP:!SSLv2
. For more information about ciphersuites syntax in Caché and the default value, see the “Enabled Ciphersuites Syntax” section.
This property is equivalent to the Enabled ciphersuites field in the SSL/TLS configuration page in the Management Portal.
CertFile
The absolute path and name of the file that contains the client’s trusted certificate authority (CA) file; if the client does not have a CA, do not specify a value for this property. If specified, this is an X.509 certificate(s) in PEM format and can include a certificate chain. For information on how this value is used, see the section “Establishing the Required Certificate Chain.” (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.)
This property is equivalent to the File containing this client’s certificate field in the SSL/TLS configuration page in the Management Portal.
KeyFile
The absolute path and name of the configuration’s private key file; if the client does not have a private key, do not specify a value for this property.
This property is equivalent to the File containing associated private key field in the SSL/TLS configuration page in the Management Portal.
Password
The password for decrypting the configuration’s private key. If you are using a certificate with a password, this property is required; if you are not using a certificate for the client or if the private key does not have a password, do not specify a value for this property. (If the private key is password-protected and you do not provide a value here, Caché cannot decrypt and use the private key.)
This property is equivalent to the Private key password field in the SSL/TLS configuration page in the Management Portal.
KeyType
If the configuration has a private key and certificate, the format in which the configuration’s private key is stored:
  • DSA — 1
  • RSA — 2
This property is equivalent to the Private key type field in the SSL/TLS configuration page in the Management Portal.
CAfile
Required. The absolute path and name of the file that contains the server’s trusted certificate authority (CA) file. This is an X.509 certificate(s) in PEM format. Note that:
  • If you have specified a VerifyPeer value of 2, you must provide this value.
  • This is the certificate for CA of the server to which you are connecting, not the certificate for your CA.
This property is equivalent to the File containing trusted Certificate Authority certificate(s) field in the SSL/TLS configuration page in the Management Portal.

A Sample Settings File

The following sample file defines three connections and two configurations:
[MyServer1 SSL/TLS to an instance without SSL/TLS-protected InterSystems Telnet]
Address=127.0.0.1
Port=57777
SSLConfig=SSLConfig

[MyServer2 SSL/TLS to an instance with SSL/TLS-protected InterSystems Telnet]
Address=myserver2
Port=57778
TelnetPort=23
SSLConfig=SSLConfig

[MyServer3 SSL/TLS to an instance with SSL/TLS-protected InterSystems Telnet]
Address=myserver3.myexample.com
Port=57779
SSLConfig=SSLNoVerify

[SSLConfig]
Protocols=24
KeyType=2
VerifyPeer=2
CipherList=ALL:!aNULL:!eNULL:!EXP:!SSLv2
Password=
CertFile=c:\InterSystems\certificates\nopwclicert.pem
KeyFile=c:\InterSystems\certificates\nopwclikey.pem
CAfile=c:\InterSystems\certificates\cacert.pem

[SSLNoVerify]
Protocols=16
KeyType=2
VerifyPeer=0
CipherList=ALL:!aNULL:!eNULL:!EXP:!SSLv2
Password=
CertFile=c:\InterSystems\certificates\nopwclicert.pem
KeyFile=c:\InterSystems\certificates\nopwclikey.pem
CAfile=c:\InterSystems\certificates\cacert.pem

How It Works

Important:
This section describes how InterSystems products use a settings file to establish an SSL/TLS connection. By describing the mechanisms in use, it includes alternate means of creating an SSL/TLS connection. InterSystems recommends that you use the standard approach described above, rather than the alternatives mentioned here.
Caché uses the settings file as follows:
  1. When you attempt to establish an SSL/TLS connection, the InterSystems TCP/IP client connection library locates the settings file containing connection definitions and configurations. This file is cconnect.dll on 32-bit machines and cconnect64.dll on 64-bit machines. To do this:
    1. It checks the Windows registry for any SSL/TLS connection definitions.
    2. If there are no connection definitions in the registry, the library attempts to locate any SSL/TLS configurations that are stored in a settings file.
    3. If the ISC_SSLconfigurations environment variable exists, the library uses the value of that variable as the full path and file name of the settings file.
      Note:
      If you need to define the value of the ISC_SSLconfigurations environment variable, you may need administrator permissions.
    4. If the ISC_SSLconfigurations environment variable does not exist, the library uses the SSLdefs.ini file in the InterSystems\Cache directory under the 32-bit common program files directory identified by the Windows environment variables CommonProgramFiles(x86) on 64-bit Windows or CommonProgramFiles on 32-bit Windows.
  2. Once it has located the settings file, the library locates the relevant connection definition for the connection you are attempting to establish.
    To do this, it searches the sections of the file for one that contains Address and Port properties that match those of the connection you are attempting to establish. When it locates such a section, it uses the value of the SSLConfig property there to locate the matching SSL/TLS configuration section.
  3. In the specified SSL/TLS configuration section, the library uses the values of the configuration properties to specify the type of connection to initiate with the server.

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/TLS 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 the second failover member or an async member; for more information, see the “Authorize the Second Failover Member or Async (SSL/TLS Only)” 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 as Async page (System Administration > Configuration > Mirror Settings > Join 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
To disable SSL/TLS for an existing mirror, 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:
    • 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 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:
    • 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:
    • 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 SSL/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 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:
  • 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 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:
  • 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.

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/TLS with either the
    /SSL
    or
    /TLS
    parameter.
     OPEN MyConn:(SvrID:1000:/SSL="MyCfg")
    where
    • MyConn is the device previously specified
    • SvrID can be a string that is a resolvable DNS name or an IP address
    • MyCfg is a saved (and activated) SSL/TLS configuration
    This call opens a TCP connection to the loopback processor (that is, the local machine) on port 1000 using SSL. It uses SSL/TLS 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.
    Important:
    The ability to include a password when opening a TCP connection using SSL/TLS is for real-time interactive use only. You should never store a private key password persistently without protecting it. If you need to store such a password, use the PrivateKeyPassword property of the Security.SSLConfigs class.
    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
    • MyConn is the device previously specified
    • MyCfg is an SSL/TLS configuration
    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.
    Important:
    The ability to include a password when securing an existing TCP connection using SSL/TLS is for real-time interactive use only. You should never store a private key password persistently without protecting it. If you need to store such a password, use the PrivateKeyPassword property of the Security.SSLConfigs class.
    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:
  • Open a TCP socket specifying that this connection requires SSL or TLS.
  • Establish the requirement for the use of SSL or TLS on an already-existing socket.

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/TLS 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.
    Important:
    The ability to include a password when opening a TCP connection using SSL/TLS is for real-time interactive use only. You should never store a private key password persistently without protecting it. If you need to store such a password, use the PrivateKeyPassword property of the Security.SSLConfigs class.

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
    • MySocket is the device previously specified
    • MyCfg is an SSL/TLS configuration
    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.
    Important:
    The ability to include a password when securing an existing TCP connection using SSL/TLS is for real-time interactive use only. You should never store a private key password persistently without protecting it. If you need to store such a password, use the PrivateKeyPassword property of the Security.SSLConfigs class.
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/TLS.
    You must also specify values for the SSL/TLS Protocol, SSL/TLS Key Type, Require peer certificate verification, SSL/TLS Certificate File, SSL/TLS Private Key File, SSL/TLS CA Certificate File, and SSL/TLS Private Key Password fields. For more details on the fields on this page, see the “Configuring Server Access” section of the “CSP Gateway Operation and Configuration” chapter of the CSP Gateway Configuration Guide.

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:
  • The verifying entity must have access to all the certificates that constitute the certificate chain from the verified entity’s own certificate to a trusted CA’s self-signed root certificate. The certificates in the chain are obtained from the combination of the verified entity’s certificate file (the certificates are sent as part of the handshake protocol) and the verifying entity’s trusted CA certificate file.
  • The verifying entity must have the trusted CA’s self-signed root certificate in its CA certificate file.
  • The verified entity’s own certificate must be the first entry in its certificate file.
  • All intermediate CA certificates must be present.
  • The certificates in the certificate chain may be divided between the verified entity’s certificate file and the verifying entity’s trusted CA certificate file. However, each part must be a contiguous partial certificate chain, as described in the following example.
Suppose there are:
  • A verified entity (named “VE”) with a certificate signed by the certificate authority named “ICA1.”
  • A certificate for “ICA1” signed by the certificate authority “ICA2,” and a certificate for “ICA2” signed by “RootCA”.
  • A trusted CA (named “RootCA”) with a self-signed root certificate.
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
Previous section   Next section