About the Settings File

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

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.