After you complete the Zowe certificates configuration questionnaire to determine your specific configuration use case, choose from the five scenarios presented in this article to configure Zowe for automatic certificate setup. Examples of the zowe.yaml files are provided for each scenario.
Required roles: system programmer, security administrator
tip
To assist you with determining the specific certificate configuration scenario that applies to your use case, see Zowe certificates configuration questionnaire. This questionnaire guides you through quetions that lead to a specific configuration scenario presented in this article.
Zowe servers require both a keystore to store the certificates and a truststore to validate certificates.
For use of Zowe on z/OS, the keystore and truststore can either be Unix file-based (PKCS12) or z/OS keyring-based.
Both the keystore and truststore can automatically be created by Zowe regardless of which storage type is used. Keystores and truststores can be populated either with certificates that the user chooses, or with self-signed certificates generated by Zowe.
This automation can be performed by defining and customizing the zowe.setup.certificate section of your Zowe YAML configuration.
Zowe can then automate the certificate setup via the zwe init certificate command.
note
Automated generation of certificates is an option, but is not required. If you already have a keystore that contains a valid certificate *, and the corresponding private key of the certificate, along with a truststore which validates the certificate and any other certificates you expect to encounter, then you also have the option to directly define the parameter zowe.certificate, which specifies the location of each of these certificates and their storage objects. Note that this parameter should not be confused with the parameter zowe.setup.certificate.
A valid certificate for use in Zowe conforms to one of the following two options:
The certificate does not contain the Extended Key Usage section.
The certificate does contain the Extended Key Usage section, and also includes the Server and Client authentication fields.
Considerations for certificate scenario selection
Consider the scenario that best suits your use case:
Do you plan to use a file-based (PKCS12) certificates, or z/OS keyrings?
Do you plan to enable Zowe to create self-signed certificates, or will Zowe be using pre-made certificates which you are providing?
If you are providing certificates to Zowe and using a keyring, does the certificate already exist in your security database, or are you importing it via a dataset?
There are five scenarios/use cases for configuring certificates.
Use the applicable certificate configuration scenario according to your needs.
Each scenario described in this article provides the configuration details via code snippets which you can use to edit your Zowe YAML configuration within the zowe.setup.certificate section.
Ensure that all alias values for all scenarios use only lower-case.
Scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates
Use this procedure to configure the zowe.setup.certificate section in your yaml file to enable Zowe to use generated PKCS12 certificates to be used with a keystore directory to store your certificates.
Click here for details.
Set the type of the certificate storage to PKCS12.
Customize the keystore directory in the following format:
/var/zowe/keystore
Lock the keystore directory so it is accessible only to the Zowe runtime user and group:
lock: true
Customize the certificate alias name. The default value is localhost.
Set the keystore password. The default value is password.
Set the alias name of self-signed certificate authority. The default value is local_ca.
caAlias: local_ca
Set the password of the keystore stored self-signed certificate authority. The default value is local_ca_password.
caPassword: local_ca_password
(Optional) Specify the distinguished name for Zowe generated certificates.
Set the validity in days for the Zowe generated certificates
validity: 3650
Set the domain names and IPs specified in nested subsection SAN. If this field is not defined, the zwe init command uses the value zowe.externalDomains.
san: sample domain name - dvipa.my-company.com sample IP address - 12.34.56.78
note
A bug in Java SDK 8.0.8.10 has been discovered that makes configuration scenario 1 non-operational. If you see the following message when running the zwe init certificate command, upgrade or downgrade your Java version:
keytool error (likely untranslated): java.lang.IllegalArgumentException: java.util.Vector incompatible with [Ljava.lang.Object;
For more information, see this article in IBM Support.
Your yaml file is now configured to enable Zowe to use generated PKCS12 certificates.
For more information about using a file-based PKCS12 certificate in Zowe services, see the video tutorials on YouTube. More information about this certificate configuration scenario is also availabe in this Medium blog post.
Scenario 2: Use a file-based (PKCS12) keystore and import a certificate generated by another CA
Use this procedure to configure the zowe.setup.certificate section in your yaml file to enable Zowe to use a file-based PKCS12 keystore to import a certificate generated by another CA.
Click here for details.
Set the type of the certificate storage to PKCS12.
Customize the keystore directory in the following format:
/var/zowe/keystore
Lock the keystore directory so it is accessible only to the Zowe runtime user and group:
lock: true
Customize the certificate alias name. The default value is localhost.
Set keystore password. The default value is password.
Set the existing PKCS12 keystore which holds the certificate issued by an external CA.
keystore: "<your-keystore-value>"
Set the password of the keystore set in step 6.
password: "<your-password-value>"
Specify the alias of the certificate to be imported.
alias: "<your-alias-value>"
Set the path to the certificate authority that signed the certificate to be imported.
importCertificateAuthorities:
note
PEM format certificate authorities can be imported and trusted.
Your yaml file is now configured to enable Zowe to use a file-based PKCS12 keystore to import a certificate generted by another CA.
Scenario 3: Use a z/OS keyring-based keystore with Zowe generated certificates
Use this procedure to configure the zowe.setup.certificate section in your yaml file to enable Zowe to use a z/OS keyring-based keystore with Zowe generated certificates.
Click here for details.
Set the type of the certificate storage to one of the following keyring types:
JCEKS
JCECCAKS
JCERACFKS
JCECCARACFKS
JCEHYBRIDRACFKS
Add the parameter createZosmfTrust and set to true.
createZosmfTrust: true
Under the nested subsection keyring:, specify the following keyring values:
keyring name
name: ZoweKeyring
Label of Zowe certificate. The default value is localhost.
label: localhost
Label of Zowe CA certificate. The default value is localca.
caLabel: localca
The distinguished name for Zowe generated certificates.
Your yaml file is now configured to enable Zowe to use a z/OS keyring-based keystore with Zowe generated certificates.
Scenario 4: Use a z/OS keyring-based keystore and connect to an existing certificate
Use this procedure to configure the zowe.setup.certificate section in your yaml file to use a z/OS keyring-based keystore and connect to an existing certificate.
Click here for details.
Set the type of the certificate storage to one of the following keyring types:
JCEKS
JCECCAKS
JCERACFKS
JCECCARACFKS
JCEHYBRIDRACFKS
Under keyring:, specify the keyring name:
name: ZoweKeyring
Under the nested subsection connect:, specify the following parameters:
The current owner of the certificate. Possible values can be SITE or a user ID.
user: IBMUSER
The label of the existing certificate to be connected to the Zowe keyring.
label: ""
All certificate authorities you want to be trusted in the Zowe keyring.
importCertificateAuthorities: - ""
note
Due to the limitation of RACDCERT command, this field should contain a maximum of 2 entries.
The following example uses an existing JCERACFKS certificate for Zowe's z/OS components. For more information about configuration in this scenario, see this Medium blog post, or the video tutorials in this YouTube playlist.
If you would like to use this example in your Zowe configuration YAML file, replace the following four fields with your own values:
Replace ZoweKeyringZOSMF with the your own key ring name.
Replace IZUSVR with the user name who is the owner of the existing certificate.
Replace DefaultzOSMFCert.IZUDFLT with the label of the existing certificate you are connecting to (which is owned by the previously referenced user ID).
Replace zOSMFCA with the certificate authority that is used to sign the certificate.
Your yaml file is now configured to use a z/OS keyring-based keystore and connect to an existing certificate.
Scenario 5: Use a z/OS keyring-based keystore and import a certificate stored in a data set
Use this procedure to configure the zowe.setup.certificate section in your yaml file to use a z/OS keyring-based keystore and import a certificate stored in a data set.
Click here for details.
Set the type of the certificate storage to one of the following keyring types:
JCEKS
JCECCAKS
JCERACFKS
JCECCARACFKS
JCEHYBRIDRACFKS
Under keyring:, specify the following keyring values:
keyring name
name: ZoweKeyring
Label of Zowe certificate. The default value is localhost.
label: localhost
Under the nested subsection import: specify the following parameters:
The name of the data set holds the certificate issued by another CA. This data set should be in PKCS12 format and contain private key.