Configuring a primary z/OSMF for communicating with secondary instances

z/OSMF can be configured to communicate with another instance of z/OSMF in a remote sysplex. This capability is important because it allows z/OSMF tasks to work with systems on other sysplexes in your enterprise. To enable z/OSMF-to-z/OSMF communication, you must configure a primary z/OSMF for communicating with secondary instances, as described in this topic. The key requirement is to enable the sharing of digital certificates between instances.

This information assumes the use of RACF. If you use another external security manager, consult the vendor for more information.

Each z/OSMF instance includes a server runtime and digital certificates

During the configuration process, z/OSMF creates a certificate authority (CA), optionally, and a server certificate, to be used for enabling Secure Sockets Layer (SSL) connections between z/OSMF instances. z/OSMF also creates a SAF key ring, and stores the CA and server certificate in the key ring.

These constructs are named, as follows:

Key ring name is IZUKeyring.IZUDFLT
CA name is:
CN(’z/OSMF CertAuth for Security Domain’) OU(’SAF_PREFIX’)) WITHLABEL(’zOSMFCA’)

z/OSMF creates the CA and the server certificate if you uncomment the following commands for creating certificates in the IZUSEC job:

//* Create the CA certificate for the z/OSMF server                  *
 RACDCERT CERTAUTH GENCERT +
   SUBJECTSDN(CN('z/OSMF CertAuth for Security Domain') +
   OU('IZUDFLT')) WITHLABEL('zOSMFCA')  +
   TRUST NOTAFTER(DATE(2023/05/17))
 RACDCERT ADDRING(IZUKeyring.IZUDFLT) ID(IZUSVR)

//* Create the server certificate for the z/OSMF server              *
 RACDCERT ID( IZUSVR ) GENCERT SUBJECTSDN(CN('PEV051.POK.IBM.COM') +
   O('IBM') OU('IZUDFLT')) WITHLABEL('DefaultzOSMFCert.IZUDFLT') , +
   SIGNWITH(CERTAUTH LABEL('zOSMFCA')) NOTAFTER(DATE(2023/05/17)) 
 RACDCERT ALTER(LABEL('DefaultzOSMFCert.IZUDFLT')) ID(IZUSVR) TRUST
 RACDCERT ID( IZUSVR ) CONNECT (LABEL('DefaultzOSMFCert.IZUDFLT') +
   RING(IZUKeyring.IZUDFLT) DEFAULT)
 RACDCERT ID( IZUSVR ) CONNECT (LABEL('zOSMFCA') +
   RING(IZUKeyring.IZUDFLT) CERTAUTH)

Planning for secure communication between instances

In the sections that follow, the z/OSMF instance that initiates communication is considered to be the primary instance. It serves as the repository for the data that is generated by the z/OSMF instances running in your installation. When planning to enable communication between instances of z/OSMF, first determine which of the instances is to be the primary.

The primary instance communicates with other z/OSMF instances through Secure Sockets Layer (SSL) connections. Each SSL connection requires an exchange of digital certificates, which are used to authenticate the z/OSMF server identities. For the SSL connection to be successful, the primary instance must be configured to trust the server certificates from the secondary instances.

For signing the server certificates, each instance uses a certificate authority (CA) certificate. Establishing a trust relationship between instances will require knowing which CA certificate is used to sign each secondary instance server certificate.

Another consideration is whether the instances share the same security database or use separate security databases. Using a shared database can simplify the process of enabling secure communications if the same CA certificate is used by all participating systems. Sharing a RACF database is not feasible for every installation, however. If your installation uses separate security databases, you must ensure that the appropriate certificates are shared by the participating z/OSMF instances.

For more information about digital certificates, see z/OS Security Server RACF Security Administrator's Guide.

Strategies for sharing CA certificates

This topic describes two scenarios for sharing CA certificates between multiple instances: You might choose to use one common CA certificate for all of the instances, or a different CA certificate for each instance. A third situation is also described, wherein the existence of identically named CA certificates can complicate certificate sharing.

If you have not yet created any secondary instances of z/OSMF, you might find it easier to create one CA certificate and use it to sign all of the server certificates in the primary and secondary instances. Using this approach, you export the CA certificate from the primary system and add it to each of the secondary system security databases. Then, you configure the additional instances of z/OSMF on each secondary system. Here, you should not run the IZUSEC job certificate commands on the secondary systems, as mentioned in Each z/OSMF instance includes a server runtime and digital certificates. Instead, use the certificate that you have from the primary system. As a result, the same CA certificate is used to sign the server certificate for each instance. This approach is shown in Scenario 1: SSL connections using the same CA certificate.

If you have already created one or more secondary instances of z/OSMF, and you want to enable them for communication with the primary, determine whether the secondary systems were configured to use identically-named CA certificates or uniquely-named CA certificates. If you created each of the secondary instances with unique SAF prefix values, each secondary instance uses a uniquely named CA certificate. To allow SSL connections in this case, you can make available the secondary system CA certificates on the primary system key ring (that is, export, add, and connect them). As a result, the primary system will trust the secondary system server certificates, and be able to establish SSL connections with those systems. This approach is shown in Scenario 2: SSL connections using different CA certificates.

A third possibility exists. If you created the secondary instances using the default z/OSMF security execs, it is likely that you have identically named CA certificates on each secondary system— and a problem. The CA certificates have identical names (that is, label name and distinguished name), but different key ring material. The reason is that the default z/OSMF commands for creating the CA certificates all specify the same label name and distinguished name, but the resulting CA certificates contain system-specific key ring material.

The differences in key ring material prevent the primary system from trusting the server certificates from the secondary systems, unless the corresponding CA certificates can be added to the primary system key ring. However, you cannot add the secondary system CA certificates to the primary system key ring, because of naming conflicts; those different CA certificates are not "unique" enough to be added to the same database. Attempting to add a certificate into a database that already has a same-named certificate will result in an error and a message such as: IRRD109I The certificate cannot be added… already defined.

This potential problem can be avoided if the same CA certificate (from the primary system) is used by all of the instances (primary and multiple secondaries). Or, if the secondary instances are created with unique cell names, thus ensuring that each system’s CA certificate can be added to the same security database.

Scenario 1: SSL connections using the same CA certificate

In this scenario, you use the primary system CA to generate a common CA certificate, and distribute this CA certificate to the secondary systems. This approach is recommended if the secondary instances do not already exist.

For example, in Figure 1, both the primary z/OSMF and the secondary instances are identified by server certificates that were created using the same CA (Jupiter).

This image shows the trust relationship that is established when the z/OSMF server certificates are signed by the same CA certificate. — Figure 1. Trust relationship when server certificates are signed by the same CA certificate

Using the same CA to sign the server certificate for each system eliminates the need to import CA certificates from the secondary systems into the primary system security database.

Scenario 2: SSL connections using different CA certificates

In this scenario, each secondary instance of z/OSMF uses its own certificate authority and CA certificate to sign its server certificates. To enable SSL connections in this scenario, you must add each secondary system CA certificate to the primary system security database. This approach is recommended if the secondary instances already exist, and were created to use uniquely named CA certificates.

For example, in Figure 2, the primary z/OSMF:

Is identified by a server certificate created by the Jupiter CA
Holds (in its security database) the CA certificates from CA Saturn and CA Mars, for the secondary instances, System X and System Y, respectively.

This image shows the trust relationship that is established when the z/OSMF server certificates are signed by different CA certificates. — Figure 2. Trust relationship when the server certificates are signed by different CA certificates

To enable SSL connections between instances in this scenario, you would do the following:

Export the CA certificate from each secondary system
Import the CA certificates into the primary system security database
Connect the CA certificates to the primary system.