TLS and Windows with .ini File

Connecting from a Windows Client Using a Settings File

If you are on Windows and are using Studio, ODBC, or the Terminal as a 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® data platform on the host.

To use a settings file:

Get the certificate authority (CA) certificate for the server. Store it on disk and note the location — you will use it later.
Create a file containing connection definitions and configuration definitions, as described in the About the Settings File section.
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:

Use of the settings file (SSLDefs.ini) has the following restrictions:

The settings file is only for connections that use the irisconnect.dll or irisconnect64.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.
Connections from a Windows client to InterSystems IRIS that use the settings file do not support Kerberos authentication.

About the Settings File

A settings file holds specifications for both connections to TLS servers and the TLS configurations that those connections use. For each Windows host that is a 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 a TLS connection and matches that connection to a TLS configuration. The first line of a connection definition is its identifier, which appears in brackets. After the identifier, there are multiple lines specifying information about the TLS server and the connection to it:

Address

Required. The address of the 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 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 TLS server that accepts TLS-protected connections for InterSystems Telnet. If you do not specify this value, connections using InterSystems Telnet do not support 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 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 a TLS configuration; for more information on TLS configurations, see “About Configurations.” The first line of a configuration definition is its identifier, which appears in brackets; if the configuration identifier appears as the value of a connection definition’s SSLConfig property, the connection uses the configuration to specify its behavior. After the identifier, there are multiple lines specifying the value of each of the configuration’s properties:

Protocols

Deprecated. Use TLSMinVersion and TLSMaxVersion instead.

The versions of the TLS protocol(s) that the configuration supports, where each version of the protocol has a numeric value as listed in TLSMinVersion and TLSMaxVersion. To specify support for multiple versions of the protocol, use the sum of their values. Hence, to specify support for TLS v1.1 and TLS v1.2, use a value of 24.

This property is equivalent to the Protocols field in the TLS configuration page in the Management Portal.

TLSMinVersion

Required for configurations that support v1.3. The earliest version of the TLS protocol that this configuration supports, where each version of the protocol has a numeric value and supported versions are:

TLS v1 — 4
TLS v1.1 — 8
TLS v1.2 — 16
TLS v1.3 — 32

This property is equivalent to the Minimum Protocol Version field in the TLS configuration page in the Management Portal.

TLSMaxVersion

Required for configurations that support v1.3. The most recent version of the TLS protocol that this configuration supports, where each version of the protocol has a numeric value and supported versions are:

TLS v1 — 4
TLS v1.1 — 8
TLS v1.2 — 16
TLS v1.3 — 32

This property is equivalent to the Maximum Protocol Version field in the TLS configuration page in the Management Portal.

VerifyPeer

Required. Whether or not the client requires the verification of the certificate 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.
1 — 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 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.HttpRequestOpens in a new tab class.

CipherList

Required for configurations that support connections using TLS v1.2 or earlier. The set of cipher suites that the client supports for encryption and hashing. For information on this property’s syntax, see the OpenSSL documentation on the ciphersOpens in a new tab command.

The default value is ALL:!aNULL:!eNULL:!EXP:!SSLv2, and InterSystems strongly suggests using this value. For more information about this syntax in InterSystems IRIS, see Enabled Cipher Suites Syntax.

This property is equivalent to the Enabled ciphersuites field in the TLS configuration page in the Management Portal.

Ciphersuites

Required for configurations that support connections using TLS v1.3. The set of ciphers that the client supports for encryption and hashing. For information on this property’s syntax, see the OpenSSL documentation on the ciphersOpens in a new tab command.

InterSystems strongly recommends using a value of TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256, which is the default. For more information about this syntax in InterSystems IRIS, see Enabled Cipher Suites Syntax.

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 Establishing the Required Certificate Chain. (Note that certificates from the Windows Certificate Export Wizard must be in PEM-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 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 TLS configuration page in the Management Portal.

Password

The password for decrypting the configuration’s private key. If you are using a private key 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 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 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 1, 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 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 two connections and two configurations:

[MyServer1 TLS to an InterSystems IRIS instance with TLS-protected InterSystems Telnet]
Address=myserver1
Port=57777
TelnetPort=23
SSLConfig=TLSConfig

[MyServer2 TLS to an InterSystems IRIS instance using TLSv1.2]
Address=myserver2.myexample.com
Port=57777
SSLConfig=TLSv1.2only

[TLSConfig]
TLSMinVersion=16
TLSMaxVersion=32
CipherList=ALL:!aNULL:!eNULL:!EXP:!SSLv2
Ciphersuites=TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
KeyType=2
VerifyPeer=1
Password=
CertFile=c:\InterSystems\certificates\nopwclicert.pem
KeyFile=c:\InterSystems\certificates\nopwclikey.pem
CAfile=c:\InterSystems\certificates\cacert.pem

[TLSv1.2only]
TLSMinVersion=16
TLSMaxVersion=16
CipherList=ALL:!aNULL:!eNULL:!EXP:!SSLv2
KeyType=2
VerifyPeer=1
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 a TLS connection. By describing the mechanisms in use, it includes alternate means of creating a 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:

When you attempt to establish a 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 TLS connection definitions.
2. If there are no connection definitions in the registry, the library attempts to locate any 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.
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 TLS configuration section.
In the specified 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 TLS with Mirroring

TLS with Studio