About Mirroring and TLS
For general information about InterSystems IRIS® data platform support for mirroring, see Mirroring.
To provide security within a mirror, you can configure its nodes to use TLS. This provides for both authentication of one node to another, and for encrypted communication between nodes. As sensitive data passes between the failover members (and to an async member), it is recommended to encrypt the communication to prevent data theft or alteration over the network. Additionally, since a failover member has the ability to request an ISCAgent to take action on another InterSystems IRIS system (such as to request journal file information or force InterSystems IRIS down), it is important to protect such communication between the failover members of a mirror (and their corresponding ISCAgent processes).
Note:
If the failover members use database (or journal) encryption, then TLS is required for communications between them and with any async members. (Specifically, InterSystems IRIS checks if either member has an encryption key activated; if so, the instance requires that the user enable TLS with mirroring.) For more details on database encryption and journal file encryption, see Encryption Guide.
To both participate in mirroring (either as a failover member or as an async member) and use TLS, an instance must have two InterSystems IRIS TLS configurations – one of type server and the other of type client; each of these must have an X.509 TLS certificate issued by a trusted Certificate Authority. InterSystems recommends that each mirror host has its own set of certificates and that the certificates contain a unique identifier in the Common Name (CN) component of the certificate, such as the fully qualified domain name (FQDN) of the instance plus the member’s InterSystems IRIS node name; because the CN is a field in a certificate’s distinguished name (DN), establishing a unique CN ensures that the certificate’s DN uniquely identifies the member. To create an instance’s mirroring configurations, follow the procedure in the next section.
When TLS is enabled, the following actions occur:
-
Server authentication: When the client connects to the server, it requires the server to authenticate itself. This authentication verifies that the DN for the server’s certificate matches the DN for a system configured in the client’s mirror configuration. If there is no match, the client drops the connection.
-
Client authentication: When the server accepts a connection from a client, it requires the client to authenticate itself. This authentication also verifies that the DN for the client’s matches the DN for a system configured in the server’s mirror configuration. Again, if there is no match, the server drops the connection.
-
Encryption: The TLS protocol automatically uses the server’s certificate to establish an encrypted channel between the client and the server, so that any data passing through this channel is encrypted and thereby secured.
InterSystems strongly recommends using TLS with a mirror.
Note on Configuring an Async Member with TLS
If a mirror uses TLS, then in addition to enabling TLS for the mirror and creating the configurations for each member (described in the following section), there are special steps that must be taken when configuring the second failover member or an async member; for more information, see Authorize the Second Failover Member or Async (TLS Only). Specifically, for each failover member, on the Mirror Monitor page, you need to enter the DN (distinguished name) in the ID listed as DN in member’s X.509 credentials field; you can copy the value of the DN from X.509 Distinguished Name field of the Join as Async page (System Administration > Configuration > Mirror Settings > Join as Async) for the async member. (InterSystems IRIS populates the X.509 Distinguished Name field based on the information in the async member’s certificate, making this field unavailable for manual editing.)
Note on Disabling TLS for a Mirror
To disable TLS for an existing mirror, disable it on the primary member.
Important:
Use of TLS with mirroring is highly recommended. Disabling TLS for a mirror is strongly discouraged.
Create and Edit a TLS Configuration for a Mirror
To use TLS with a mirror, each member (failover or async) uses a pair of TLS configurations that are called %MirrorClient and %MirrorServer; the Portal allows you to create and edit these configurations.
Note:
These configurations must already exist on each member when TLS is enabled for the mirror.
Create a TLS Configuration for a Mirror Member
To create the configurations, the procedure is:
-
Enable mirroring for that instance of InterSystems IRIS if it is not already enabled. To do this, use the Edit Service page for the %Service_Mirror service; on this page, select the Service Enabled check box. You can reach this page by either of two paths:
-
On the Mirror Settings page (System Administration > Configuration > Mirror Settings), select Enable Mirror Service.
-
On the Services page (System Administration > Security > Services), select %Service_Mirror.
-
Go to the Create SSL/TLS Configurations for Mirror page. You can do this either by:
-
On the SSL/TLS Configurations page (System Administration > Security > SSL/TLS Configurations) select Create Configurations for Mirror.
-
On the Create Mirror page (System Administration > Configuration > Mirror Settings > Create Mirror) select Set up SSL/TLS.
-
On the Create SSL/TLS Configurations for Mirror page, complete the fields on the form. The fields on this page are a subset of those on the New SSL/TLS Configuration page (as described in Create or Edit a TLS ConfigurationOpens in a new tab). Since this page creates both server and client configurations that mirroring automatically enables (%MirrorClient and %MirrorServer), there are no Configuration Name, Description, or Enabled fields; also, for the private-key password, this page allows you to enter or replace one (Enter new password), specify that none is to be used (Clear password), or leave an existing one as it is (Leave as is).
Since both configurations need the same X.509 credentials, completing this form saves both configurations simultaneously. The fields described in Create or Edit a TLS ConfigurationOpens in a new tab on this page are:
Once you complete the form, click Save.
For general information about configuring mirror members, see Creating a Mirror.
Edit TLS Configurations for a Mirror Member
If you have already created a member’s %MirrorClient and %MirrorServer configurations, you can edit them on the Edit SSL/TLS Configurations for Mirror page (System Administration > Security > SSL/TLS Configurations; click Edit Configurations for Mirror). This page displays the same fields as the Create SSL/TLS Configurations for Mirror page, as described in the previous section.
Special Considerations for Certificates for Mirror Members
When using TLS with mirroring, the %MirrorClient and %MirrorServer configurations must use the same certificate and private key. Hence, the certificate in use by both configurations must be usable as both a server and a client certificate.
There are certain certificate extensions that are specific to TLS clients or servers. Because the certificate in use with mirroring must be able to serve both uses (as both a client and a server), if any of these extensions appear in a certificate, then the extensions for client and server must both be present. For example, this is true for the Key Usage and Extended Key Usage extensions. If the Key Usage extension is present, then it must specify both of the following:
Similarly, if the Extended Key Usage extension is present, then it must specify both:
If both extensions are present, then each must specify both values. Of course, it is also valid to have neither extension present.
If a certificate only specifies one value (either client or server), the TLS connection for mirroring fails with an error such as:
error:14094413:SSL routines:SSL3_READ_BYTES:sslv3 alert unsupported certificate
The way to eliminate this error depends on how you obtained your certificates:
-
If you are using self-signed certificates, create new certificates (such as with the OpenSSL library) that adhere to these conditions.
-
If you are using a commercial certificate authority tool (such as Microsoft Certificate Services), create new certificates that adhere to these conditions and use the tool to sign your certificate signing requests (CSRs).
-
If you are purchasing certificates from a commercial certificate authority (such as VeriSign), include a request along with your CSRs that they adhere to these conditions.
