Skip to main content

Configuring TLS

InterSystems IRIS® data platform can support multiple configurations, each of which specifies a named set of 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 TLS configurations is the SSL/TLS Configurations page (System Administration > Security > SSL/TLS Configurations).

Create or Edit a TLS Configuration

The page for creating or editing a 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 TLS, see “Configuring InterSystems IRIS to Use TLS with Mirroring.”)

When creating or editing a 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.

  • 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 InterSystems IRIS superserver uses a server configuration; TLS clients 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 certificate 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.

    • On Windows and macOS, you can specify that the configuration uses the list of trusted CA certificates that the local operating system provides. To do so, specify the string %OSCertificateStore as the value of this field.

      On Windows, InterSystems IRIS is compatible with the Microsoft Root Certificate Program that uses Windows Update to fetch additional certificates on demand. For more information about how to configure certificate updating, see Configure Trusted Roots and Disallowed CertificatesOpens in a new tab on the Microsoft website.

    • 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 PEM-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 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 verifyOpens in a new tab 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). This must be PEM encoded and 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 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.)

    • 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, InterSystems IRIS 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:

    • Minimum Protocol Version — The earliest version of the TLS protocol that this configuration supports. This is a drop-down menu that lists all the versions that the instance can support and is TLS v1.2 by default. See note below.

    • Maximum Protocol Version — The most recent version of the TLS protocol that this configuration supports. This is a drop-down menu that lists all the versions that the instance can support and is TLS v1.3 by default. See note below.

    • Enabled cipherlist (TLSv1.2 and below) — The set of ciphers used to protect communications between the client and the server, if you are using TLS v1.2 or an earlier version. See Supported Ciphers Syntax for more information on this topic.

    • Enabled ciphersuites (TLSv1.3) — The set of ciphers used to protect communications between the client and the server, if you are using TLS v1.3. See Supported Ciphers Syntax for more information on this topic.

    • Diffie Hellman Bits — (Servers only) The size in bits of the key that the Diffie Hellman ciphers use. The minimum key size varies by operating system. The Auto option specifies a key size that is at least the minimum required for the local operating system. Note that the Open Web Application Security Project (OWASP) recommends a minimum key size of 2048 bitsOpens in a new tab.

    Note:

    As described in Which TLS Versions Does My Instance of InterSystems IRIS Support?, the versions of TLS that may be available depend on the version of the underlying OpenSSL libraries that are in use. InterSystems IRIS checks what OpenSSL libraries are in use and attempts to present only the relevant available versions of TLS. A system may, however, be configured in ways that InterSystems IRIS cannot account for. For example, Ubuntu 20.04 ships with a configuration of OpenSSL that has been modified from the default to disallow TLS 1.0 and TLS 1.1. In cases like this, InterSystems IRIS error message and logging are designed to help you determine if there is a conflict between the OpenSSL configuration and the InterSystems IRIS configuration; contact the InterSystems Worldwide Response Center (WRC)Opens in a new tab or your operating system vendor if you encounter unexpected behavior.

  • OCSP Settings:

    • OCSP Stapling — Whether or not the configuration supports OCSP stapling.

      If you enable OCSP stapling for a client, then the client requests it; if the server does not provide a stapled OCSP response or the response fails validation, then the handshake fails. If OCSP stapling is enabled for a server, then the server provides a stapled OCSP response when it receives a request from a client.

      InterSystems IRIS creates the OCSP response file if it doesn't exist when you save the TLS configuration. An expired OCSP response automatically updates when you save the TLS configuration or when the server receives a request. Additionally, the CertCheck System Sensor (%SYS.Monitor.SystemSensors::CertCheck()) updates the response periodically. IRIS background jobs and any jobs that initiate a TLS server connection must have read/write permission on the OCSP response file. You can grant read/write access to the InterSystems IRIS effective group to satisfy these requirements.

      Regardless of whether you enable OCSP stapling, any user who can create a server-side TLS socket can do so with any enabled TLS configuration.

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 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; InterSystems IRIS 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 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 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 PEM-encoded X.509 format, not the default of DER encoded binary X.509. All certificates must be PEM encoded regardless of file extension.

Enabled Cipher Suites Syntax

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

  • Provide a list of individual cipher suites, using each one’s name

  • Use OpenSSL syntax to specify which cipher suites to enable and disable

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

The default set of cipher suites for an InterSystems IRIS 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

For more information, see the OpenSSL documentation on the ciphersOpens in a new tab command.

A Note on InterSystems IRIS Client Applications Using 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 TLS, the following aspects of the configuration require particular attention:

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

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

  • Ciphersuites — The specified cipher suites 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 Establishing the Required Certificate Chain.

Delete a Configuration

The page for deleting a 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.

Update Certificates for Existing Configurations

InterSystems IRIS provides a way for updating the associated certificates for a TLS configuration. After obtaining the new certificates, you can update them in the TLS configuration. The changes take effect with a new network connection. Many connections are dropped and reestablished quickly so the change can be immediate. However, certain connections can remain open for longer, for example, mirroring and certain interoperability interface connections. To ensure that the updated certificates take effect, InterSystems recommends you drop and reestablish these connections.

Mirroring environments require an additional step after reestablishing connections. Please see Authorizing X.509 DN Updates for more details.

Reserved and Required Configuration Names

InterSystems IRIS reserves several 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 TLS to function properly, you must use the exact case for each configuration name as it appears here.

Creating, Editing, and Deleting TLS Configurations Programmatically

To manage TLS configurations programmatically, use:

Next sectionManaging Superservers
Previous sectionApplications
FeedbackOpens in a new tab