Certificate configuration scenarios

As a system programmer, review the different scenarios for configuring Zowe for automatic certificate setup. Examples are provided for each scenario.

Zowe servers require both a keystore to store the certificates as well as a truststore to validate these certificates and any other certificates that are encountered.

For use of Zowe on z/OS, 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. This command is run as a subcommand of zwe init.

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 certificate's corresponding private key, along with a truststore which validates the certificate and any other certificates you expect to encounter, then you also have the option of directly defining the parameter zowe.certificate which specifies the location of each of these 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 is required to have one of the following attributes, regardless of the format:

• A certificate that does not contain the Extended Key Usage section.
• A certificate that contains the Extended Key Usage section and also includes the "Server" and "Client" authentication fields.

Considerations for certificate scenario selection

When configuring Zowe for certificates, consider the scenario that best suits your use case:

• Will you be using file-based (PKCS12) certificates, or z/OS keyrings?
• Will you be letting Zowe 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

Scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates

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.
   Note: Use all lower case as an alias.

5. Set keystore password. Customizing this value is highly recommended. The default value is password.

6. Set the alias name of self-signed certificate authority. The default value is local_ca.
   Note: Use all lower case as an alias.

   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

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

Scenario 2: Use a file-based (PKCS12) keystore and import a certificate generated by another CA

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.
   Note: Use all lower case as an alias.

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: ""  

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

   password: ""

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

   alias: ""

   Note: Use all lower cases as an alias.

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

Scenario 3: Use a z/OS keyring-based keystore with Zowe generated certificates

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 2 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

Scenario 4: Use a z/OS keyring-based keystore and connect to an existing certificate

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 blog post.

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.

Scenario 5: Use a z/OS keyring-based keystore and import a certificate stored in a data set

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 PKS12 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