Setting up secure communication for UMS

Edit online

By default, Unified Management Server uses the keystore and truststore that are specified in the zowe.yaml configuration file for Zowe. You can use a different keystore or truststore by specifying its location and type in the ZWEYAML member to be used to configure UMS.

Before you begin

Note: The certificate and key rings discussed in this section are for the Unified Management Server. To set up certificates and key rings for UMS DBA users, see Specifying the default UMS DBA user.

Confirm in which USS directory the Zowe configuration YAML file (zowe.yaml) for the Zowe instance to be used for your UMS server installation is located. For details of the Zowe configuration for keystore and truststore, see YAML configurations - certificate and Zowe certificate configuration.

About this task

The setup procedure described in this section is required only when you want to use a keystore or truststore that is different from the one used by Zowe components. The parameters that can be specified in the UMS PARMLIB member ZWEYAML are as follows:

components.izp.security.certificate.keystore.location
components.izp.security.certificate.keystore.type
components.izp.security.certificate.keystore.alias
components.izp.security.certificate.truststore.location
components.izp.security.certificate.truststore.type

Zowe supports Public Key Cryptography Standards #12 (PKCS12) and SAF key rings of JCERACFKS keystore types for both keystores and truststores. Unified Management Server supports the Java KeyStores (JKS) type for both keystores and truststores in addition to PKCS12 and JCERACFKS-type key rings. It also supports the Java keystore type JCECCARACFKS. For details, see Using the Java keystore type JCECCARACFKS.

Recommendation: For any environment other than proof-of-concept testing environments, it is highly recommended to use key rings for both keystores and truststores.

Important:

If you are using a key ring as the UMS keystore, the certificate that is connected to the key ring with PERSONAL usage must be a trusted SITE certificate that is not associated with any valid user ID.
If you are using a key ring as the UMS keystore, the Zowe started task user ID requires RDATALIB class authority to access the private key of the certificate that is connected to the key ring with PERSONAL usage at UMS runtime. Since the certificate is owned by SITE, the Zowe started task user ID needs to have CONTROL access to the profile <keyring_owner>.<keyring_name>.LST in the RDATALIB class, where <keyring_owner_ID> is the user ID that owns the key ring and <keyring_name> is the name of the key ring.
The keystore that will be used for the Unified Management Server must include only one personal certificate, which has a specified label. You must not include another personal certificate, such as an UMS DBA user certificate. For a DBA user certificate, you must use a separate key ring for the DBA user ID. For details on preparing a key ring for a DBA user certificate, see Configuring the DBA user by using a certificate.
If you are sharing the keystore between Zowe and Unified Management Server, check whether the requirements on Extended Key Usage (EKU) and Subject Alternate Name (SAN) described in the Zowe certificate requirements section of the Zowe documentation are satisfied for the certificate, which will be commonly used by all Zowe components, including UMS. If any of these requirements are not satisfied, connection errors can occur during Zowe server startup.

For TLS connection requests sent to a UMS server, the UMS server acts on the "server" side and the "client" is either one of the following:

The Zowe App Server
The Zowe API Gateway
A REST API client that does not use the API Gateway

For TLS connection requests sent from a UMS server, the UMS server acts as a "client" and the "server" in this case is one of servers running on z/OS. Those z/OS servers include the following:

A Zowe ZSS server
A z/OSMF server
A Db2 subsystem
A SQL Tuning Services server for Db2
An Administration Services server for Db2 Analytics Accelerator

Keystores and truststores are used in TLS communications. They are repositories that contain cryptographic artifacts like certificates and private keys that are used for cryptographic protocols. The procedure below describes how to set up these repositories to enable TLS communications for UMS.

Procedure

Specify key ring or file-based keystore parameters.

Using a key ring as a keystore

The most secure and recommended method of storing certificates is using a key ring. If you are using your own keystore, you must specify that in the following ZWEYAML items, and manage it as per your security procedures:
1. components.izp.security.certificate.keystore
2. components.izp.security.certificate.keystore.type
3. components.izp.security.certificate.keystore.alias
4. components.izp.security.certificate.keystore.location
- Know the PARMLIB member that contains the Unified Management Server configuration parameters. This was first edited when you installed Unified Management Server. The default is {components.izp.dataset.parmlib}(ZWEYAML).
- If you self-generated your server certificate and you want to enable client authentication, your server certificate must contain the TLS Web Client Authentication (1.3.6.1.5.5.7.3.2) value in the extended key usage section.
To add the server certificate and the certificate authority used to sign it to your key ring, run the following commands.
Note: The default UMS started task ID is the same as the Zowe started task ID, which is referred to as <zowe_started_task_id> in the example below.
```
RACDCERT CONNECT(ID(<zowe started task id>) LABEL(‘<SERVER_CERTIFICATE_LABEL>’) RING(<RINGNAME>) USAGE(PERSONAL) DEFAULT) ID(<zowe started task id>)
RACDCERT CONNECT(CERTAUTH LABEL(‘<CA_LABEL>’) RING(<RINGNAME>) USAGE(CERTAUTH))  ID(<zowe started task id>)
SETROPTS RACLIST(DIGTCERT,DIGTRING) REFRESH
```
You can set up the key ring for UMS and Zowe.
Creating a key ring with a private key stored in ICSF PKDS
Create a key ring KEY_RING.

Create and/or import a new SITE certificate SITE_CERTIFICATE and store the private key in ICSF.

Note: To store the private key in ICSF, you need to specify the PKDS option with a label in the RACDCERT ADD command. For example,
RACDCERT ADD('[location_of_certificate_in_dataset]') ID([certificate_owner]) TRUST WITHLABEL('[certificate_label]') PKDS([pkds_label])
Setting up RACF permissions for accessing the key ring and the private key
Create a profile in CSFKEYS class CSFKEYS_PROFILE with the label name of the SITE_CERTIFICATE private key.

Create a new group GROUP to provide permissions to relevant classes and profiles.

Grant profiles in class CSFSERV with READ access to group GROUP.

Grant profile CSFKEYS_PROFILE in class CSFKEYS with READ access to group GROUP.

Connect Zowe started task user to group GROUP.

Connect requires certificates to key ring KEY_RING.

Create profile RDATALIB_PROFILE with the following naming convention: <Zowe_Started_Task_User>.<KEY_RING>.LST in RDATALIB.

Grant profile RDATALIB_PROFILE with CONTROL access to <Zowe_Started_Task_User>.
Using a file-based keystore

To use a file-based keystore, you must import your certificates into the Zowe file-based keystore, which is used by default. Zowe provides a certificate import function. For details, see Zowe documentation.
Specify key ring or file-based truststore parameters.
Using a key ring as a truststore
In order to facilitate secure communication between UMS and z/OSMF, you must add the certificate authority (CA) of z/OSMF to the UMS truststore. To enable access to UMS during runtime, the key ring must be accessible by the <ZOWE_STARTED_TASK_ID>. You can use the same key ring for your truststore and keystore. If you have not created a key ring, run the following commands:
```
RACDCERT ADDRING(<RINGNAME>) ID(<ZOWE_STARTED_TASK_ID>) 
SETROPTS RACLIST(DIGTRING) REFRESH 
```
To add certificate authority of z/OSMF to your key ring, run the following commands:
```
RACDCERT CONNECT(CERTAUTH LABEL(‘<ZOSMF_CA_LABEL>’) RING(<RINGNAME>) USAGE(CERTAUTH)) 
ID(<ZOWE_STARTED_TASK_ID>)
SETROPTS RACLIST(DIGTCERT,DIGTRING) REFRESH 
```
Using a file-based truststore

By default, when UMS launches, it will use the truststore specified in the zowe.yaml by key zowe.certificate.truststore.file.

The Zowe started task ID may not have access for UMS to import certificates to the Zowe location, so you must import Db2 certificates or a certificate authority into the Zowe truststore. If you are using SQL Tuning Services or Db2 Analytics Accelerator Administration Services, you must also import certificates for the services into that same truststore. If the z/OSMF certificate is not present in the Zowe truststore, you must add it.

If you specify your own location for truststore in components.izp.security.certificate.truststore.location, UMS will use that location when launching, but you must separately import certificates for services, including z/OSMF.

If you specify the location as components.izp.workspaceDirectory/conf/cacerts, then UMS will automatically import the certificates for z/OSMF, SQL Tuning Services, and Db2 Analytics Accelerator Administration Services during the Zowe configure step. You must use root or a user with group access to import the Db2 certificate into the conf/cacerts file. The conf/cacerts file requires ownership by the Zowe started task user. The password to conf/cacerts is "password".
You can use the Java program keytool for certificate import:
```
$JAVA_HOME/bin/keytool -noprompt -keystore truststoreLocation -importcert -alias anyAlias -file certificateFile
```
For troubleshooting information, refer to Issues with key store or trust store.

What to do next

Notes:

Applicable to Db2 experiences

Users are required to create connection profiles for the SQL Tuning Service. If you are using SSL encryption for the Db2 connectivity, UMS will pass the name of the UMS truststore to the SQL Tuning Service when the profile is created.

UMS will automatically create Db2 connection profiles for the Db2® Analytics Accelerator Administration Services. Again, if you are using SSL encryption for Db2 connectivity, UMS will pass the name of the UMS truststore when the profile is created.

Using a file-based keystore
If you are using a file-based keystore with UMS, ensure that the SQL Tuning Service started task user ID and the Db2 Analytics Accelerator Administration Services started task user ID have read permissions on the UMS truststore file.
Using a key ring as a truststore
If you are using key rings with UMS, SQL Tuning Service started task user ID and the Db2 Analytics Accelerator Administration Services started task user ID also need access to read the UMS key ring. You can select one of the following options:
- Define and permit UPDATE on IRR.DIGTCERT.LISTRING in class FACILITY to the SQL Tuning Service and the Db2 Analytics Accelerator Administration Services started task user IDs. This action permits those user IDs the authority to read any key ring on the system.
- Define and permit CONTROL on <UMS keyring owner>.<UMS keyring name>.LST in class RDATALIB to the UMS, SQL Tuning Service, and the Db2 Analytics Accelerator Administration Services started task user IDs.
- Create the connection profiles outside UMS and pass the name of a truststore already used for the SQL Tuning Service and the Db2 Analytics Accelerator Administration Services started tasks. Make sure to connect the appropriate Db2 Root CAs to the key ring specified in components.izp.security.certificate.truststore.location, or if blank, the key ring specified in zowe.certificate.truststore.file so the services can connect securely to Db2.