Step-by-step guide: Use a PKCS12 (file-based) keystore with Zowe generated certificate

Published in

Zowe

8 min readOct 6, 2023

{Core} In our last blog, we introduced how to use an existing JCERACFKS certificate in Open Mainframe Project’s Zowe. If you are using a key ring to configure Zowe and getting confused, that blog is made for you! In this one, we will talk about another scenario — using a PKCS12 keystore with Zowe generated certificate. Following this guide, you will learn how to smoothly configure your Zowe configuration file to use a PKCS12 certificate. We will soon bring up other scenarios in the following blogs. Now, let’s dig in.

Before we start

What is keystore?

The keystore is the location where Zowe stores certificates that Zowe servers present to clients and other servers. In the simplest case, the keystore contains one private key and a certificate pair, which can then be used by each Zowe server.

What is PKCS12?

PKCS12 is a file format that allows a Zowe user to hold many crytopgrahic objects in one encrypted, passworded file. This file format is well-supported across platforms but because it is just a file, you can prefer to use z/OS key rings instead of PKCS12 certificates for ease of administration and maintenance.

We also have a blog talking about Zowe key ring, if you are using a keyring, read this blog for details.

3 steps to use a PKCS12 file-based certificate:

Customize your zowe.yaml file in section zowe.setup.certificate: set up the USS directory which holds the keystore, truststore, certificate files, and details of the certificate alias, the certificate authority alias, the keystore and truststore passwords, certificate distinguished name(dname), and the IP host name and address.
Run `zwe init certificate` command to create the USS the directory and the files that we set up in Step 1.
Verify the certificate and use it: get started with the newly generated certificate and launch Zowe.

Step 1: Customize your zowe.yaml file

What we want to do is to create a new certificate to be used in Zowe. To do this, we can leverage Zowe’s helper utility through the zwe init certificate command. The input that the command (and other zwe commands) can execute is from the zowe.yaml file.

In this file, we specify everything to generate a new certificate in the zowe.setup.certificate section. To create a new PKCS12 file-based keystore (what we are trying to do in this blog), we need to configure the parameters in Certificate setup scenario 1, namely PKCS12 (keystore) with Zowe generate certificates.

Now we can uncomment the scenario 1. By default, the example-zowe.yaml file template that you copied to create zowe.yaml will have the scenario 1 zowe.setup.certificateuncommented. We need to double-check and make sure the right section is uncommented.

*Notes: Be careful with lines 107, 111, 114 and 118 (see the screenshot below) starting with ** COMMONLY_CUSTOMIZED** as when uncommenting the whole block these may need to be re-commented back with the leading “#” character.

Then we need to update the parameters in this section.

zowe.setup.certificate.type: to be PKCS12 to indicate this is a keystore certificate.
zowe.setup.certificate.pkcs12.directory: to be a directory to store the certificate artifacts within. For this blog, we’ve used /u/winchj/pkcs12 as an example. This directory does not need to exist and will be created as part of the zwe init certificate command.
zowe.setup.certificate.pkcs12.name: to be the certificate name, in our case, localhost_jw.
zowe.setup.certificate.pkcs12.password: to be the password used to protect access to the .p12 keystore.
zowe.setup.certificate.pkcs12.caAlias: to be the certificate signing authorities (CA) for the certificate, in this case, local_ca_jw.
zowe.setup.certificate.pkcs12.caPassword: to be the password of the keystore that stored self-signed certificate authority.

The following parameters are optional, and here are the values that we use in this blog.

zowe.setup.certificate.pkcs12.dname.caCommonName: to be"Zowe PKCS12 Cert" in this case.
zowe.setup.certificate.pkcs12.dname.orgUnit: to be "Zowe PKCS12 Org Unit.
zowe.setup.certificate.pkcs12.dname.locality: to be "Hursley".
zowe.setup.certificate.pkcs12.dname.state: to be "HA".
zowe.setup.certificate.pkcs12.dname.country: to be "England".
zowe.setup.certificate.pkcs12.san: to be the Subject Alternative Name which should include all of the domain names and IP numeric addresses that are secured by the certificate. This will be the hostname and IP address used by Zowe clients (web browsers or CLI profiles) to securely access the Zowe servers.

Configure the values in the Certificate setup scenario 1

*Notes: in the screenshots above, we are using the Zowe Explorer plugin for Visual Studio Code with coloring the content of zowe.yaml. So we can see comments in green, keywords in blue, values in brown, …. Be careful if you are using tools like ISPF or vi in OMVS or iShell to edit your zowe.yaml file, because it’s easy to make mistakes. For example, having an extra space, so the columns don’t line up correctly, or a line you think is runtime syntax is commented out or vice versa.

Now you are good to go to the next step with these values configured.

Step 2: Run the command to generate the certificate

The whole zowe.setup.certificatesection in Zowe configuration yaml file is all customized for scenario 1, we can run the zwe init certificate command.

By running this command, you can generate the Unix System Service directory containing the keystore.p12 file, truststorep12 file, certificate.cer file, and .pem files.

The screen recording shows the process when we are running zwe init certificate -c ./zowe.yaml. It will likely take a minute or so to complete because of the computation. So please be patient.

After running the command zwe init certificate, you will see that your certificate is successfully created and the values to be updated for thezowe.certificate section in zowe.yaml file.

Update the values in the `zowe.certificate` section

Copy and paste the following code block to have a try!

zowe:
  certificate:
    keystore:
      type: PKCS12
      file: "u/winchj/pkcs12/localhost_jw/localhost_jw.keystore.p12"
      password: "password"
      alias: "localhost_jw"
    truststore:
      type: PKCS12
      file: "u/winchj/pkcs12/localhost_jw/localhost_jw.truststore.p12"
      password: "password"
    pem:
      key: "u/winchj/pkcs12/localhost_jw/localhost_jw.key"
      certificate: "u/winchj/pkcs12/localhost_jw/localhost_jw.cer"
      certificateAuthorities: "u/winchj/pkcs12/local_ca_jw/local_ca_jw.cer"

… and then you need to paste the values and pass them into zowe.yamlfile as shown below.

Update the syntax by pasting the values to the `zowe.certificate` section

If you are updating your zowe.yaml file for the first time you’ve copied it from the default template inexample-zowe.yaml, you’ll find there is already a zowe.certificate section. Overwrite this with the nice new syntax, telling Zowe that we want to generate a new PKCS12 file-based certificate.

zowe.certificate.keystore.type: to be PKCS12.
zowe.certificate.keystore.file: to be the path that you store the keystore, /u/winchj/pkcs12/localhost_jw/localhost_jw.keystore.p12.
zowe.certificate.keystore.alias: to be the certificate label, localhost_jw. Spaces are allowed, and the value is case-sensitive.
zowe.certificate.truststore: these repeat the values for zowe.certificate.keystore:.
zowe.certificate.pem.certificateAuthorities: should point to the path of the signing chain of the certificate, /u/winchj/pkcs12/localhost_ca_jw/localhost_ca_jw.cer.

The updated values in the `zowe.certificate` section

Next, you can save the changes from these values and move to Step 3.

Step 3: Verify the certificate and use it

Now let’s take a look at the certificate that you create, which is located in /u/winchj/pkcs12/localhost_jw/localhost_jw.keystore.p12.

If you want to check the certificate details, you can leverage the keytool command to do so. So first move, you need to navigate to the directory where the certificate is located, /u/winchj/pkcs12/localhost_jw, in the terminal.

Navigate to the directory where the certificate is located

When you arrive here, you can leverage the keytool command to dig into the certificate that we create. So what you need to do is to run keytool -v -list -keystore localhost_jw.keystore.p12 and enter the password.

Run the `keytool` command to check the details

With this command execution, you will see details of this certificate, including the entries, alias name, domain name, IP address, and many other parameters that you set up in the zowe.setup.certificate section in Step 1.

Apart from the keystore, you are also capable to use the keytool command to look into the truststore file.

Run the `keytool` command to look inside the truststore

Here you might be confused about the keystore and truststore. The keystore is to hold certificates with public keys and private keys used for outbound encryption. While the truststore is to hold the certificate authorities of the certificate.

Seems everything looks good! Then you can move to the last step — get your Zowe started with the newly generated certificate!

Now let’s go back to the Unix System Services directory to run the zwe start -c ./zowe.yaml and start Zowe. And you can see the job ZWEJRW2P is started. Please note that the STC name of Zowe main serviceZWEJRW2P is set up in the zowe.security section in the zowe.yaml file.

Since the job is on, you can have a look at ZWEJRW2P so that you can make sure the job is started with the certificate you just create.

Then let’s check the service status and see if all services are started. You can search the ZWEJRW2P job with the job prefix under the JOBS section. Then you can check the details in ZWEJRW2P:SYSPRINT. Then you can search the keyword “ZWEAM00I” to see the status for each service.

Next, let’s log into the API gateway with the certificate that you generate previously.

The API gateway port number is set up in the zowe.components.gateway section, and it’s 17554 in our blog.

When you are trying to log into the gateway, the browser might warn you that the connection is not private because you are using a self-signed certificate.

To have the browser trust your certificate, you can click the Advanced button and select to proceed to the gateway link as shown below.

And if you want to double confirm the certificate you are using in this browser, you can click the Not secure button beside the link input field on the top. Then you can see the details of this certificate just as what you set up in the zowe.yaml file in Step 1.

Check the certificate details in your browser

Find out more

If you enjoyed this blog, checkout more Zowe blogs here. Or, ask a question and join the conversation on the Open Mainframe Project Slack Channel #zowe-cli or #zowe-onboarding. If this is your first time using the Open Mainframe Slack Channel register here.

Zowe is owned and managed by the Open Mainframe Project which is a Linux Foundation project.

Zowe™, the Zowe™ logo, and the Open Mainframe Project™ are trademarks of The Linux® Foundation. Linux is a registered trademark of Linus Torvalds.