Skip to main content

TLS with TCP Devices

Configuring InterSystems IRIS to Use TLS with TCP Devices

This section describes how to use TLS with an InterSystems IRIS® data platform TCP connection. The process is:

  1. Creating a 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 TLS. This can occur either as part of opening the connection/socket or afterwards.

How you invoke the InterSystems IRIS 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 TLS to an existing connection.

This section addresses the following topics:

Configure a Client to Use TLS with a TCP Connection

To establish a secure connection from a client, the choices are:

Open a TLS-secured TCP Connection from a Client

In this scenario, InterSystems IRIS is part of the client and the TCP connection uses TLS from its inception. The procedure is:

  1. Make sure that the configuration you wish to use is available. If it was created before InterSystems IRIS was last started, it is activated and ready for use; otherwise, you can create a new one or edit an existing oneOpens in a new tab.

  2. Open a TCP Connection Using TLS.

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 TLS-related behavior.

Open a TCP Connection Using TLS

This involves opening a named connection that uses 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"

    The TCP string specifies that this is a TCP device. For more information on initiating a TCP connection, see OPEN Command for TCP Devices.

  2. Open the connection, specifying the use of TLS with the /TLS parameter.

     OPEN MyConn:(SvrID:1000:/TLS="MyCfg")

    where

    • MyConn is the device previously specified

    • SvrID can be a string that is a resolvable DNS name or an IP address

    • MyCfg is a saved (and activated) TLS configuration

    This call opens a TCP connection to the loopback processor (that is, the local machine) on port 1000 using TLS. It uses 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:/TLS="MyCfg|MyPrivateKeyFilePassword")

    Here, all the arguments are as above and MyPrivateKeyFilePassword is the actual password.

    Important:

    The ability to include a password when Open a TCP Connection Using 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.SSLConfigsOpens in a new tab class.

    For more information on opening a TCP device, see OPEN and USE Command Keywords for TCP Devices.

Once the connection is established, you can then use it in the same manner as any other TCP connection.

Add TLS to an Existing TCP Connection

This scenario assumes that the TCP connection has already been established. The procedure is:

  1. Make sure that the configuration you wish to use is available. If it was created before InterSystems IRIS was last started, it is activated and ready for use; otherwise, you can create a new one or edit an existing oneOpens in a new tab.

  2. Securing the existing TCP connection using TLS.

Secure an Existing TCP Connection Using TLS

This involves adding 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)

    The TCP string specifies that this is a TCP device. For more information on initiating a TCP connection, see OPEN Command for TCP Devices.

  2. Specify the use of TLS as follows with the /TLS parameter:

     USE MyConn:(::/TLS="MyCfg")

    where

    • MyConn is the device previously specified

    • MyCfg is a TLS configuration

    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 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.SSLConfigsOpens in a new tab class.

    For more information on opening a TCP device, see OPEN and USE Command Keywords for TCP Devices.

Having added TLS security to the connection, you can continue to use it in the same manner as before.

Configure a Server to Use TLS with a TCP Socket

To enable a socket to require a secure connection from a client, you can either:

  • Open a TCP socket specifying that this connection requires TLS.

  • Establish the requirement for the use of TLS on an already-existing socket.

Establish a TLS-secured Socket

In this scenario, InterSystems IRIS is the server and the TCP socket uses TLS from its inception. The procedure is:

  1. Make sure that the configuration you wish to use is available. If it was created before InterSystems IRIS was last started, it is activated and ready for use; otherwise, you can create a new one or edit an existing oneOpens in a new tab.

  2. Open a TCP socket that requires the use of TLS.

This socket requires the use of TLS from clients connecting to it. When a client attempts to connect to the server, the server attempts to negotiate a connection that uses 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.

Open a TCP Socket Requiring TLS

To open a socket that requires TLS, the procedure is:

  1. Specify the device that is accepting connections:

     SET MySocket = "|TCP|1000"

    The TCP string specifies that this is a TCP device. For more information on initiating a TCP connection, see OPEN Command for TCP Devices.

  2. Open the connection, specifying the use of TLS with the /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.

    Important:

    The ability to include a password when opening a TCP connection using 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.SSLConfigsOpens in a new tab class.

Add TLS to an Existing Socket

This scenario assumes that a connection to the TCP socket has already been established. The procedure is:

  1. Make sure that the configuration you wish to use is available. If it was created before InterSystems IRIS was last started, it is activated and ready for use; otherwise, you can create a new one or edit an existing oneOpens in a new tab.

  2. Use TLS to secure the existing TCP connection to the socket.

Secure an Existing TCP Connection to the Socket Using TLS

This involves adding 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)

    The TCP string specifies that this is a TCP device. For more information on initiating a TCP connection, see OPEN Command for TCP Devices.

  2. Specify the use of TLS as follows with the /TLS parameter:

     USE MySocket:(::/TLS="MyCfg")

    where

    • MySocket is the device previously specified

    • MyCfg is a TLS configuration

    Optionally, the call can include a password for the private key file:

     USE MySocket:(::/TLS="MyCfg|MyPrivateKeyFilePassword")

    For more information on opening a TCP device, see OPEN and USE Command Keywords for TCP Devices.

    Important:

    The ability to include a password when securing an existing TCP connection using 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.SSLConfigsOpens in a new tab class.

Having added TLS security to the socket, you can continue the connection to it in the same manner as before.

Next sectionTLS with the Web Gateway
Previous sectionConfiguring InterSystems IRIS to Use TLS with Mirroring
FeedbackOpens in a new tab