Certificate configuration scenarios

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.

* What is a valid certificate in Zowe?

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.

• Scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates
• Scenario 2: Use a file-based (PKCS12) keystore and import a certificate generated by another CA
• Scenario 3: Use a z/OS keyring-based keystore with Zowe generated certificates
• Scenario 4: Use a z/OS keyring-based keystore and connect an existing certificate
• Scenario 5: Use a z/OS keyring-based keystore and import a certificate stored in a data set

note

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.

1. Set the type of the certificate storage to PKCS12.

2. Customize the keystore directory in the following format:

   /var/zowe/keystore

3. Lock the keystore directory so it is accessible only to the Zowe runtime user and group:

   lock: true

4. Customize the certificate alias name. The default value is localhost.

5. Set the keystore password. The default value is password.

6. Set the alias name of self-signed certificate authority. The default value is local_ca.

   caAlias: local_ca

7. Set the password of the keystore stored self-signed certificate authority. The default value is local_ca_password.

   caPassword: local_ca_password

8. (Optional) Specify the distinguished name for Zowe generated certificates.

   dname:
     caCommonName: ""
     commonName: ""
     orgUnit: ""
     org: ""
     locality: ""
     state: ""
     country: ""

9. Set the validity in days for the Zowe generated certificates

   validity: 3650

10. 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.

Example zowe yaml for scenario 1:

   certificate:
     type: PKCS12
     pkcs12:
       directory: /var/zowe/keystore
       lock: true
       name: localhost
       password: password
       caAlias: local_ca
       caPassword: local_ca_password
       dname:
         caCommonName: "Zowe Instances CA"
         commonName: "Zowe Server"
         org: "My Company"
         locality: "Prague"
         state: "Prague"
         country: "CZ"
       validity: 3650
       san:
         - system.my-company.com
         - 12.34.56.78

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.

1. Set the type of the certificate storage to PKCS12.

2. Customize the keystore directory in the following format:

   /var/zowe/keystore

3. Lock the keystore directory so it is accessible only to the Zowe runtime user and group:

   lock: true

4. Customize the certificate alias name. The default value is localhost.

5. Set keystore password. The default value is password.

6. Set the existing PKCS12 keystore which holds the certificate issued by an external CA.

   keystore: "<your-keystore-value>"  

7. Set the password of the keystore set in step 6.

   password: "<your-password-value>"

8. Specify the alias of the certificate to be imported.

   alias: "<your-alias-value>"

9. 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.

Example zowe yaml for scenario 2 (PKCS12):

certificate:
  type: PKCS12
  pkcs12:
    directory: /var/zowe/keystore
    lock: true
    name: localhost
    password: password
    import:
      keystore: /certs/system.keystore.p12
      password: password
      alias: server
  importCertificateAuthorities:
    - /certs/extca.1.cer
    - /certs/extca.2.cer

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.

1. Set the type of the certificate storage to one of the following keyring types:

   • JCEKS
   • JCECCAKS
   • JCERACFKS
   • JCECCARACFKS
   • JCEHYBRIDRACFKS

2. Add the parameter createZosmfTrust and set to true.

   createZosmfTrust: true

3. 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.

     dname:
         caCommonName: ""
         commonName: ""
         orgUnit: ""
         org: ""
         locality: ""
         state: ""
         country: ""

4. Set the validity in days for the Zowe generated certificates

   validity: 3650

5. Set the domain names and IPs specified in the certificate SAN. If this field is not defined, the zwe init command uses the value zowe.externalDomains.

   san:
     - dvipa.my-company.com
     - 12.34.56.78

note

Due to the limitation of the RACDCERT command, this field should contain exactly two entries with the domain name and IP address.

Example zowe yaml for scenario 3:

certificate:
  type: JCERACFKS
  keyring:
    name: ZoweKeyring
      label: localhost
      caLabel: local_ca
    dname:
      caCommonName: "Zowe Instances CA"
      commonName: "Zowe Service"
      org: "My Company"
      locality: "Prague"
      state: "Prague"
      country: "CZ"
    validity: 3650
    san:
      - system.my-company.com
      - 12.34.56.78

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.

1. Set the type of the certificate storage to one of the following keyring types:

   • JCEKS
   • JCECCAKS
   • JCERACFKS
   • JCECCARACFKS
   • JCEHYBRIDRACFKS

2. Under keyring:, specify the keyring name:

   name: ZoweKeyring

3. 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.

Example zowe yaml for scenario 4:

 # >>>> Certificate setup scenario 4
 # z/OS Keyring and connect to existing certificate
 certificate:
   type: JCERACFKS
   keyring:
     name: ZoweKeyringZOSMF
     connect:
       user: IZUSVR
       label: "DefaultzOSMFCert.IZUDFLT"
   importCertificateAuthorities:
     - "zOSMFCA"

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.

1. Set the type of the certificate storage to one of the following keyring types:

   • JCEKS
   • JCECCAKS
   • JCERACFKS
   • JCECCARACFKS
   • JCEHYBRIDRACFKS

2. Under keyring:, specify the following keyring values:

   • keyring name

     name: ZoweKeyring
   • Label of Zowe certificate. The default value is localhost.

     label: localhost

3. 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.

     dsName: ""
   • The password for the PKCS12 data set.

     password: ""

Example zowe yaml for scenario 5:

 # >>>> Certificate setup scenario 5
 # z/OS Keyring and connect to existing certificate
 certificate:
   type: JCERACFKS
   keyring:
     name: ZoweKeyring
     import:
       dsName: PRODUCT.X.CERT.P12
       password: password

Your yaml file is now configured to use a z/OS keyring-based keystore and import a certificate stored in a data set.