Configuring Zowe certificates in a key ring (**Beta Technical Preview**)
Beginning with Zowe 1.15 release, 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 https://git.com/zowe/community. It is expected that in a future release keyring support will be made available as a fully supported feature.
To configure Zowe certificates in a key ring, run the ZWEKRING
JCL which contains the security commands to create the key ring and manage the certificates that Zowe will use. The ZWEKRING
JCL is provided as part of the PDS sample library SZWESAMP
that is delivered with Zowe.
Before you submit the JCL, you must customize it and review it with a system programmer who is familiar with z/OS certificates and key rings.
After you run ZWEKRING
successfully, you must run the script zowe-setup-certificates.sh
which will create the keystore directory KEYSTORE_DIRECTORY
in USS. Depending on how you have customized the ZWEKRING
member, you need to customize the configuration file zowe-setup-certificates.env
that is used to create the KEYSTORE_DIRECTORY
.
#
ScenariosThe ZWEKRING
JCL helps you create a key ring that contains a certificate and a local certificate authority that is used to self-sign the certificate.
Other scenarios (such as importing an existing certificate into the ZoweKeyring) are described in the ZWEKRING
JCL with the commands commented out) but are not currently documented and have not been fully tested. If you find any issues, please raise a GitHub issue in the zowe-install-packaging repo. Future releases of Zowe will provide documentation and support for more key ring scenarios.
#
Customizing the ZWEKRING JCLTo customize the ZWEKRING
JCL, edit the JCL variables at the beginning of the JCL and carefully review and edit all the security commands that are valid for your security manager. Review the information in this section when you customize the JCL.
PRODUCT
variable#
The PRODUCT
variable specifies the z/OS security manager. The default value is RACF
. Change the value to ACF2
or TSS
if you are using Access Control Facility CA-ACF2 or CA Top Secret for z/OS as your z/OS security manager.
HOSTNAME
and IPADDRESS
#
The Zowe certificate is used on the northbound edge of the API Mediation Layer to encrypt data between web browser and other client applications such as the Zowe command line interface. These client applications will validate that the network TCP/IP address that they have accessed the encrypted data from matches the network address in the certificate. If the address does not match, the browser will not continue as it will consider the site as unsecure.
To ensure that the browser is able to establish a secure connection, set the HOSTNAME
and IPADDRESS
in the ZWEKRING
JCL member to match the hostname and TCP/IP address of the Zowe API Mediation Layer.
ZOWERING
and LABEL
labels#
The ZOWERING
label is used for the name of the key ring created. The default value is ZoweKeyring
. The LABEL
label specifies the certificate name and defaults to localhost
.
- The value of the
ZOWERING
label should match the value of theZOWE_KEYRING
variable in thezowe-setup-certificates.env
file. - The value of the
LABEL
label should match the value of theKEYSTORE_ALIAS
variable in thezowe-setup-certificates.env
file.
ROOTZFCA
label#
The ROOTZFCA
label connects the root CA of the z/OSMF certificate with the Zowe key ring.
When to set this label?
The value of the parameter VERIFY_CERTIFICATES
in the zowe-certificates.env
file in the KEYSTORE_DIRECTORY
controls whether Zowe's servers validate the authenticity of any southbound certificates at runtime. If the value is true
, then the certificate must be signed by a recognized certificate authority (CA), and if the value is false
then self-signed certificates are allowed. This section of the keystore configuration is only required if you are using VERIFY_CERTIFICATES=true
.
When you set VERIFY_CERTIFICATES=true
, then Zowe will validate the authenticity of the z/OSMF certificate, so the root CA of the z/OSMF certificate must be connected with the Zowe key ring. You can connect them by setting the label ROOTZFCA
.
If you are unsure of the root CA you can find it by listing the chain of the z/OSMF certificate using the following commands:
- RACF
- Top Secret
- ACF2
#
ResultsWhen the ZWEKRING
JCL runs successfully, it will create a key ring named ZoweKeyring
owned by ZWESVUSR
containing the following:
- The Zowe certificate (called
localhost
) - The local CA (called
ZoweCert
) - The certificate used to encrypt the JSON Web Token (JWT) required for single sign-on (called
jwtsecret
)
When the zowe-setup-certificates.sh
script executes successfully, it will generate the USS KEYSTORE_DIRECTORY
that contains the file zowe-certificates.env
. This file is used in the Zowe instance configuration step. See Creating and configuring the Zowe instance directory.