Configuring the z/OSMF key ring and certificate

The sample job IZUSEC provides RACF commands for creating a certificate authority (CA) and a server certificate. Your installation can use these authorizations for enabling Secure Sockets Layer (SSL) connections between z/OSMF instances. IZUSEC also contains commands for creating a SAF key ring, and storing 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. Replace 'XXXX.XXX.XXX.XXX' with the local host name.

//* 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('XXXX.XXX.XXX.XXX') +
   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)

In your configuration, if the key ring is owned by the z/OSMF server, and the certificate is signed by a local certificate authority (CA), you might find that the commands in IZUSEC are sufficient for your needs. If so, follow the steps in Key ring and certificate is used by the z/OSMF server only to configure the key ring and certificate. However, if you plan to share key ring and certificate with other z/OSMF or Liberty servers in your enterprise, follow the steps in Using a shared key ring and certificate for the z/OSMF server. For more considerations, see Tips for proper set-up.

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

Key ring and certificate is used by the z/OSMF server only

In this scenario, you create a certificate and key ring for use by the z/OSMF server. The certificate is signed with local CA.

Follow these steps:

Update the parameter KEYRING_NAME in the IZUPRMxx parmlib member.
```
KEYRING_NAME('IZUKeyring.IZUDFLT')
```

Grant the z/OSMF started task user ID READ access to the key ring and the certificate. By default, the server user ID is IZUSVR.

PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(IZUSVR) ACCESS(READ)
PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ID(IZUSVR) ACCESS(READ)

Add the key ring to your external security manager, such as RACF.
```
RACDCERT ADDRING(IZUKeyring.IZUDFLT) ID(IZUSVR)
```

Add the CA and the certificate. This example shows the use of the local CA. If you want to use a certificate that is signed by another CA, see the topic "Scenario 1: Secure server with a certificate signed by a certificate authority" in z/OS Security Server RACF Security Administrator's Guide.

/* Create the local 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))

/* Create the server certificate for the z/OSMF server            */
/* Change HOST NAME in CN field into real local host name         */
/* Usually the format of the host name is 'XXXX.XXX.XXX.XXX'      */

RACDCERT ID(IZUSVR) GENCERT SUBJECTSDN(CN('HOST NAME')  O('IBM') OU('IZUDFLT')) 
WITHLABEL('DefaultzOSMFCert.IZUDFLT') SIGNWITH(CERTAUTH LABEL('zOSMFCA')) NOTAFTER(DATE(2023/05/17))

RACDCERT ALTER(LABEL('DefaultzOSMFCert.IZUDFLT')) ID(IZUSVR) TRUST

Connect the certificate to the keyring.

RACDCERT ID(IZUSVR) CONNECT (LABEL('DefaultzOSMFCert.IZUDFLT') +
RING(IZUKeyring.IZUDFLT) DEFAULT)

RACDCERT ID(IZUSVR) CONNECT (LABEL('zOSMFCA') +
RING(IZUKeyring.IZUDFLT) CERTAUTH)

Using a shared key ring and certificate for the z/OSMF server

Suppose that you have an existing key ring and certificate that is shared by multiple Liberty or z/OSMF servers. This scenario shows how to use shared key ring and certificate for the z/OSMF server.

In this scenario:

Certificate is signed by an external CA.
Key ring name is RING01.
Certificate and key ring are owned by BBGSRV, which is the Liberty server user ID.

For information about obtaining this certificate and keyring, see the topic "Scenario 7: Sharing one certificate among multiple servers" in z/OS Security Server RACF Security Administrator's Guide.

To permit the z/OSMF server ID to access the keyring, certificate, and private key, you can use either the FACILITY class or the RDATALIB class, as follows:

To use the FACILITY class:
1. Grant the z/OSMF server user ID UPDATE access to the key ring. Because the key ring is associated with the Liberty server user ID (BBGSRV), not the z/OSMF server user ID (IZUSVR), the z/OSMF server user ID needs this access.
```
PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(IZUSVR) ACCESS(UPDATE)
```
2. If the FACILITY class is not already active, activate and RACLIST it:
```
SETROPTS CLASSACT(FACILITY) RACLIST(FACILITY)
```
3. If the FACILITY class is already active and RACLISTed, refresh it:
```
SETROPTS RACLIST(FACILITY) REFRESH
```
4. Permit the z/OSMF server to access the private key. It needs CONTROL access to IRR.DIGTCERT.GENCERT.
```
PERMIT IRR.DIGTCERT.GENCERT CLASS(FACILITY) ID(IZUSVR) ACCESS(CONTROL)
```

To use the RDATALIB class:

Define the RDATALIB class:

RDEFINE RDATALIB BBGSRV.RING01.LST UACC(NONE)
PERMIT BBGSRV.RING01.LST CLASS(RDATALIB) ID(IZUSVR) ACCESS(CONTROL)

If the RDATALIB class is not already active, activate it and RACLIST it, as follows:
```
SETROPTS CLASSACT(RDATALIB) RACLIST(RDATALIB)
```
If the RDATALIB class is already active and RACLISTed, refresh it, as follows:
```
SETROPTS RACLIST(RDATALIB) REFRESH
```

To configure the shared key ring for the z/OSMF server, specify it on the KEYRING_NAME parameter in the IZUPRMxx parmlib member. Because the owner is not the z/OSMF started task user ID, you must create an override file that is named local_override.cfg in the user configuration directory, which is /global/zosmf/configuration/ by default. In the override file, add the following option:

BOOTSTRAP_OPT=izu.ssl.key.store.owner.userid=BBGSRV

Tips for proper set-up

Observe the following considerations:

The IZUSEC sample job provides commands for defining the z/OSMF server certificate and its local signing CERTAUTH certificate (a RACF defined CA). If you prefer, you can use an external CA instead of the local CA. If so, you must import the external CA (which is used to sign the server certificate) into the key ring instead of the local CA.
The key ring must contain a personal certificate that is owned by the z/OSMF server started task user ID, which is IZUSVR by default. If this is a SITE certificate, the usage must be PERSONAL when it is connected to keyring, and the z/OSMF server started task user ID must have authority to extract the private key. See Using a shared key ring and certificate for the z/OSMF server.
The certificate must be marked TRUST. A NOTRUST certificate is ignored and is not loaded on server start-up.
If multiple PERSONAL or SITE certificates exist in the keyring, the last created certificate in the list is used by the z/OSMF server.
If you use a PERSONAL certificate that is not owned by z/OSMF, you must take one of following actions:
- Remove the certificate from the keyring.
- Mark the certificate NOTRUST.
- Grant update access to the z/OSMF server started task user ID for the following resource in the RDATALIB class:
```
<ringOwner>.<ringName>.LST
```