Configuring Zowe certificates

As a system administrator, review this article to learn about the key concepts of Zowe certificates.

Zowe uses a certificate to encrypt data for communication across secure sockets. An instance of Zowe references a USS directory referred to as a KEYSTORE_DIRECTORY which contains information about where the certificate is located.

Northbound Certificate

The Zowe certificate is used by the API Mediation Layer on its northbound edge when identifying itself and encrypting https:// traffic to web browsers or REST client applications. If the Zowe Command Line Interface (CLI) is configured to use the Zowe API Mediation Layer, then the CLI is a client of the Zowe certificate. For more information, see Using the Zowe Command Line Interface, Integrating with the API Mediation Layer.

Southbound Certificate

As well as being a server, Zowe itself is a client to services on the southbound edge of its API Mediation Layer. Zowe communicates to these services over secure sockets. These southbound services use certificates to encrypt their data, and Zowe uses a trust store to store its relationship to these certificates. The southbound services that are started by Zowe itself and run as address spaces under its ZWESVSTC started task (such as the API discovery service, the explorer JES REST API server) re-use the same Zowe certificate used by the API Mediation Layer on its northbound client edge.

Trust store

In addition to Zowe using the intra-address space of certificates, Zowe uses external services on z/OS (such as z/OSMF or Zowe conformant extensions that have registered themselves with the API Mediation Layer) to encrypt messages between its servers. These services present their own certificate to the API Mediation Layer, in which case the trust store is used to capture the relationship between Zowe's southbound edge and these external certificates.

To disable the trust store validation of southbound certificates, set the value VERIFY_CERTIFICATES=true to false in the zowe-setup-certificates.env file in the KEYSTORE_DIRECTORY. A scenario when this is recommended is if the certificate presented to the API Mediation Layer is self-signed, such as from an unknown certificate authority. For example, the z/OSMF certificate may be self-signed. In this case, Zowe API Mediation Layer does not recognize the signing authority.

To enable certificate validation without hostname validation, set NONSTRICT_VERIFY_CERTIFICATES=true. Using this setting, the certificate Common Name or Subject Alternate Name (SAN) is not checked. This facilitates deployment to environments where certificates are valid but do not contain a valid hostname. This configuration is for development purposes only and should not be used for production.

The utility script zowe-setup-certificates.sh or the ZWEKRING JCL can help you import z/OSMF certificate authority into trust store. If you are not using Zowe to generate certificates or want to trust other external services, you can customize zowe-setup-certificates.env or ZWEKRING JCL to import them as external certificate authorities.

A proper setup of trust store is mandatory to successfully start Zowe with VERIFY_CERTIFICATES or NONSTRICT_VERIFY_CERTIFICATES enabled in zowe-setup-certificates.env and used by zowe-setup-certificates.sh.

Certificates in the Zowe architecture

The Zowe architecture diagram shows the Zowe API Mediation Layer positioned on the client-server boundary between applications such as web browsers or the Zowe CLI accessing z/OS services. The following diagram is a section of the architecture annotated to describe the role of certificates and trust stores.

The lines shown in bold red are communication over a TCP/IP connection that is encrypted with the Zowe certificate.

• On the northbound edge of the API gateway, the certificate is used between client applications such as web browsers, Zowe CLI, or any other application wishing to access Zowe's REST APIs.
• On the southbound edge of the API Gateway, there are a number of Zowe micro services providing HTML GUIs for the Zowe desktop or REST APIs for the API Catalog. These also use the Zowe certificate for data encryption.

The lines in bold green are external certificates for servers that are not managed by Zowe, such as z/OSMF itself or any Zowe conformant REST API or App Framework servers that are registered with the API Mediation Layer. For the API Mediation Layer to be able to accept these certificates, they either need to be signed by a recognized certificate authority, or else the API Mediation Layer needs to be configured to accept unverified certificates. Even if the API Mediation Layer is configured to accept certificates signed by unverified CAs on its southbound edge, client applications on the northbound edge of the API gateway will be presented with the Zowe certificate.

Keystore versus key ring

Zowe supports certificates that are stored in a USS directory Java KeyStore format.

Beginning with release 1.15, Zowe is including the ability to work with certificates held in a z/OS Keyring. Support for Keyring certificates is currently incomplete and being provided as a beta technical preview for early preview by customers. If you have any feedback using keyrings please create an issue in the zowe-install-packaging repo. It is expected that in a future release keyring support will be made available as a fully supported feature.

Keystore directory creation

The KEYSTORE_DIRECTORY is created by running the script <RUNTIME_DIR>/bin/zowe-setup-certificates.sh. This script has a number of input parameters that are specified in a configuration file whose location is passed as an argument to the -p parameter.

The configuration file <RUNTIME_DIR>/bin/zowe-setup-certificates.env is provided for setting up a Keystore directory that contains the Zowe certificate in JavaKeystore format. The configuration file <RUNTIME_DIR>/bin/zowe-setup-certificates-keyring.env is provided for setting up a Keystore directory that references the Zowe certificate held in a z/OS keyring.

The .env configuration file should be customized based on security rules and practices for the z/OS environment. Once the script has been successfully executed and the KEYSTORE_DIRECTORY is created successfully, it is referenced by a Zowe launch instance.env file. A KEYSTORE_DIRECTORY can be used by more than one instance of Zowe. See Creating and configuring the Zowe instance directory for more information.

The Zowe launch diagram shows the relationship between a Zowe instance directory, a Zowe runtime directory, the Zowe keystore directory, and (if used to store the Zowe certificate) the z/OS keyring.

You create a KEYSTORE_DIRECTORY in USS by using the script zowe-setup-certificates.sh (1) with a -p argument that specifies a .env configuration file.

• If the -p argument file zowe-setup-certificates.env (2) is used, the KEYSTORE_DIRECTORY will contain the certificate, the certificate authority, the trust store, and the JWT Secret.
• If the -p argument file zowe-setup-keyring-certificates.env (3) is used, the KEYSTORE_DIRECTORY contains no certificates and is a pass-through to configure a Zowe instance to use a z/OS keyring.

The JCL member ZWEKRING (4) is used to create a z/OS Keyring to hold the Zowe certificate and its signing certificate authority.

At launch time, a Zowe instance is started using the script <INSTANCE_DIR>/bin/zowe-start.sh which takes configuration arguments from <INSTANCE_DIR>/instance.env. The argument (5) KEYSTORE_DIRECTORY=<KEYSTORE_DIRECTORY> specifies the path to the keystore directory that Zowe will use.

Note: If you generated your own server certificate, and you want to enable Client Authentication for it, 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. Additionally, the Digital signature and/or key agreement must also be set as extension value in the Key Usage section. For more information, see key usage extensions and extended key usage.

For more information on the Zowe launch topology, see Topology of the Zowe z/OS launch process.