docs.intersystems.com
InterSystems IRIS Data Platform 2019.2  /  Security Administration Guide

Security Administration Guide
Using SSL/TLS with InterSystems IRIS
Previous section           Next section
InterSystems: The power behind what matters   
Search:  


This chapter describes the use of InterSystems IRIS™ with SSL (Secure Sockets Layer) and TLS (Transport Layer Security), its successor. InterSystems IRIS supports the use of SSL/TLS to secure connections of several types:
As a server, InterSystems IRIS accepts connections and establishes the use of SSL/TLS; as a client, InterSystems IRIS is able to connect to servers that require the use of SSL/TLS. In all cases, InterSystems IRIS uses what is called an SSL/TLS configuration, which specifies the various characteristics of an InterSystems IRIS 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 InterSystems IRIS, 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 InterSystems IRIS, 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 InterSystems IRIS 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
InterSystems IRIS 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, InterSystems IRIS 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 InterSystems IRIS 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/TLS configurations.
To complete the process of creating or editing a configuration, use the following buttons, which appear at the top of this page:
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 Cipher Suites Syntax
A configuration only allows connections that use its enabled cipher suites. To specify enabled cipher suites, you can either:
Both the list of cipher suite names and the syntax for specifying enabled cipher suites 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 an InterSystems IRIS configuration is ALL:!aNULL:!eNULL:!EXP:!SSLv2 which breaks down into the following group of colon-separated statements:
A Note on InterSystems IRIS Client Applications Using SSL/TLS
For certain activities, you can use InterSystems IRIS instances to support client applications that interact with the InterSystems IRIS superserver.
When using client applications that interact with the InterSystems IRIS 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
InterSystems IRIS 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 InterSystems IRIS Superserver to Use SSL/TLS
To use SSL/TLS for communications among components of InterSystems IRIS, configure the InterSystems IRIS 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 InterSystems IRIS Telnet to Use SSL/TLS
InterSystems IRIS offers several options for using SSL/TLS-protected Telnet connections:
Configuring the InterSystems IRIS Telnet Server to use SSL/TLS
You can configure the InterSystems IRIS to accept SSL/TLS-protected connections from Telnet clients. To do this, configure the InterSystems IRIS Telnet server to use SSL/TLS:
  1. If there is not already a %SuperServer SSL/TLS configuration associated with the InterSystems IRIS 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. Enable the Telnet service, %Service_Telnet:
    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.
  6. If you wish or need to require SSL/TLS connections, add the following line into the SYSTEM tag of the ^%ZSTART routine:
     set sc = $SYSTEM.Security.Users.SetTelnetSSLSetting(2)
    For more information about ^%ZSTART, see “Customizing Start and Stop Behavior with ^%ZSTART and ^%ZSTOP Routines” section of the “Customizing the InterSystems IRIS System” chapter of Specialized System Tools and Utilities.
Configuring Telnet Clients to Use SSL/TLS
InterSystems IRIS accepts SSL/TLS connections from both the InterSystems Telnet client and third-party Telnet clients.
Configuring the InterSystems Telnet Client to Use SSL/TLS
You can configure the InterSystems Telnet client to use an SSL/TLS connection. The process involves several steps:
  1. On the instance that is the Telnet client, configure the settings file according to the instructions in “Connecting from a Windows Client Using a Settings File.”
Configuring Third-Party Telnet Clients to Use SSL/TLS
You can configure third-party Telnet clients to connect to an InterSystems Telnet server. The required or recommended configuration actions depend on the software in use and the selected ciphersuites. 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 Java Clients to Use SSL/TLS with InterSystems IRIS
You can configure a Java client application to use SSL/TLS when it communicates with InterSystems IRIS. 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 InterSystems IRIS 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 InterSystems IRIS is:
  1. Determine if the client requires a keystore or a truststore. This depends on several factors: whether or not the InterSystems IRIS 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 InterSystems IRIS 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 = IRISJavaClient1
keyStore.1 = cjc1.ks
keyStorePassword.1 = cjc1kspw123&XtraChar$
trustStore.1 = cjc1.ts
trustStorePassword.1 = cjc1tspw[+0therNo|sechars]

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

name.3 = IRISJavaClient3
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.intersystems.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 IRISDataSource 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 InterSystems IRIS 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 InterSystems IRIS Java client to the InterSystems IRIS server. This is done in the call to the DriverManager.getConnection method. The form of this call is:
Connection conn = DriverManager.getConnection(IRISServerAddress, prop);
where IRISServerAddress is a string that specifies the address of the InterSystems IRIS 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 InterSystems IRIS Java connectivity, see Using Java JDBC with InterSystems IRIS.
Using the IRISDataSourceObject
With the IRISDataSource 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{
   IRISDataSource ds = new IRISDataSource();
   
   ds.setURL("jdbc:IRIS://127.0.0.1:51773/TESTNAMESPACE");
   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 “Using Connection Properties” section of the “Using the JDBC Driver” chapter of Using Java JDBC with InterSystems IRIS. The JavaDoc for com.intersystems.jdbc.IRISDataSource 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 an IRISDataSource object, if you want to specify an unnamed configuration, simply do not call setSSLConfigurationName.
Configuring .NET Clients to Use SSL/TLS with InterSystems IRIS
You can configure a .NET client application to use SSL/TLS when it communicates with InterSystems IRIS. 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 InterSystems IRIS 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 InterSystems Database” chapter of Using the InterSystems 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:
    IrisConnect.ConnectionString = 
        "Server=localhost; Port=51773; Namespace=TESTNAMESPACE; 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 InterSystems IRIS server to the .NET client and, optionally, authenticating the client to the server). Once the secure connection is established, the InterSystems IRIS 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 Studio to Use SSL/TLS with InterSystems IRIS
You can configure Studio to use an SSL/TLS connection. The process involves several steps:
  1. On the instance acting as an SSL/TLS server and accepting the connection from Studio:
    1. Set up the %SuperServer SSL/TLS configuration. For more information on this process, see “Configuring the InterSystems IRIS Superserver to Use SSL/TLS.”
    2. Enable SSL/TLS connections for superserver clients (because Studio is a superserver client).
      Specifically, 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.
  2. On the Windows machine where Studio is running (which is acting as an SSL/TLS client), configure the settings file for the connection from Studio to the SSL/TLS server instance. For more information on this process, see the next section, “Connecting from a Windows Client Using a Settings File.”
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 InterSystems IRIS 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\IRIS directory in the directory for 32-bit common program files. Typically, this is the C:\Program Files (x86)\Common Files\InterSystems\IRIS\ 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 irisconnect.dll or irisconnect64.dll executable (which are for 32-bit and 64-bit machines, respectively). Connections which 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:
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:
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:
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:
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 InterSystems IRIS 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, InterSystems IRIS 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:
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:
This property is equivalent to the File containing trusted Certificate Authority certificate(s) field in the SSL/TLS configuration page in the Management Portal. However, unlike the Portal, it does not support the use of the %OSCertificateStore string.
A Sample Settings File
The following sample file defines three connections and two configurations:
[MyServer1 SSL/TLS to an InterSystems IRIS instance without SSL/TLS-protected InterSystems Telnet]
Address=127.0.0.1
Port=57777
SSLConfig=SSLConfig

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

[MyServer3 SSL/TLS to an InterSystems IRIS 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.
InterSystems IRIS uses the settings file as follows:
  1. When you attempt to establish an SSL/TLS connection, the InterSystems IRIS TCP/IP client connection library locates the settings file containing connection definitions and configurations. This file is irisconnect.dll on 32-bit machines and irisconnect64.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\IRIS 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 InterSystems IRIS to Use SSL/TLS with Mirroring
This section covers the following topics:
For general information about InterSystems IRIS support for mirroring, see the “Mirroring” chapter of the 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 InterSystems IRIS system (such as to request journal file information or force InterSystems IRIS 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, InterSystems IRIS 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 InterSystems IRIS 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 InterSystems IRIS 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 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. (InterSystems IRIS 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 InterSystems IRIS 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:
    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 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:
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 InterSystems IRIS to Use SSL/TLS with TCP Devices
This section describes how to use SSL/TLS with an InterSystems IRIS 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 InterSystems IRIS SSL/TLS functionality depends on whether you are using InterSystems IRIS 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, InterSystems IRIS is part of the client and the TCP connection uses SSL/TLS from its inception. The procedure is:
If InterSystems IRIS 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"
  2. Open the connection, specifying the use of SSL/TLS 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/TLS. 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 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:
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)
  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.
    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 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, InterSystems IRIS is the server and the TCP socket uses SSL/TLS from its inception. The procedure is:
  1. 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"
  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 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:
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)
  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 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 Web Gateway to Connect to InterSystems IRIS Using SSL/TLS
You can use SSL/TLS to set up a secure, encrypted channel between the Web Gateway and the InterSystems IRIS 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 InterSystems IRIS 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 Web Gateway and the InterSystems IRIS server that is protected by Kerberos, see the “Setting Up a Kerberized Connection from the Web Gateway to InterSystems IRIS” section of the “Authentication” chapter.
The procedure is:
  1. If there is not already a %SuperServer SSL/TLS configuration associated with the InterSystems IRIS 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 Web Gateway’s Server Access page (System Administration > Configuration > Web 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 Web Gateway.
  6. On this page, configure the Web 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 “Web Gateway Operation and Configuration” chapter of the Web 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:
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


Previous section           Next section
Send us comments on this page
View this book as PDF   |  Download all PDFs
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-08-16 05:39:10