Skip to main content

About Configurations

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).

This topic covers the following:

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. If you are creating a configuration for the InterSystems IRIS superserver, the configuration name must be %SuperServer; for more information about this topic, see “Configuring the InterSystems IRIS Superserver to use 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 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 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.

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

    • 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 Supported Ciphers Syntax 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 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 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:

  • 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 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:

  • 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 ciphers 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.

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.

Feedback