Importing and configuring a certificate

One option to use certificates in Zowe is to import and configure existing certificates. Use the procedure that applies to the type of certificate you wish to import.

Required roles: system programmer, security administrator

Choose from the following certificate importing options:

• Importing a file-based PKCS12 certificate
• Importing a JCERACFKS certificate
• Importing a certificate stored in an MVS data set into a Zowe key ring.

Importing an existing PKCS12 certificate

To import a PKCS12 certificate, it is first necessary to import a certificate authority (CA). There are two options for importing a CA:

• Manually importing a certificate authority into a web browser
• Importing a local CA certificate on Linux

Once you have imported your CA, you can configure the zowe.yaml according to Scenario 2: Use a file-based (PKCS12) keystore and import a certificate generated by another CA described in the article Certificate configuration scenarios.

For PKCS12 certificate users, specify the following parameters in the zowe.yaml file:

Parameter	Description
zowe.setup.certificate.pkcs12.import.keystore	Specify this parameter if you acquired one or more certificates from another CA, stored them in PKCS12 format, and now want to import the certificate(s) into the Zowe PKCS12 keystore.
zowe.setup.certificate.pkcs12.import.password	Specify this password value for the keystore defined in zowe.setup.certificate.pkcs12.import.keystore.
zowe.setup.certificate.pkcs12.import.alias	This value is the original certificate alias defined in zowe.setup.certificate.pkcs12.import.keystore.
zowe.setup.certificate.pkcs12.name	The imported certificate is saved under the alias specified in it.

Configure zowe.yaml for a PKCS12 certificate:

zowe:
  setup:
    certificate:
      type: PKCS12
      pkcs12:
        directory: /var/zowe/keystore
        lock: true
          name: localhost     # Optional, default value is localhost.
          password: password  # Optional, default value is password.
        import:
          keystore: ""
          password: ""
          alias: ""
      importCertificateAuthorities:
        - ""

note

Due to the limitation of the RACDCERT command, the importCertificateAuthorities field can contain a maximum of two entries.

You can now use your imported PKCS12 certificate. See next steps.

Importing a certificate Authority (CA)

Importing a certificate authority (CA) is a prerequisite to importing a PKCS12 certificate. Use the method that applies to your use case.

• Manually importing a certificate authority into a web browser
• Importing a local CA certificate on Linux

Manually importing a certificate authority into a web browser

To avoid the browser untrusted CA challenge, import Zowe certificates into the browser.

Trust in the API ML server is a necessary precondition for secure communication between the browser or API Client application. Ensure this trust by installing a Certificate Authority (CA) public certificate. By default, API ML creates a local CA. Import the CA public certificate to the truststore for REST API clients and to your browser. You can also import the certificate to your root certificate store.

tip

If a SAF keyring is used and set up with ZWEKRING JCL, the procedure to obtain the certificate does not apply. In this case, we recommended that you work with your security system administrator to obtain the certificate.

The public certificate in PEM format is stored in a USS directory a defined in the zowe.yaml configuration file in the section zowe.certificate.pem.certificateAuthorities. The certificate is stored in UTF-8 encoding so you need to transfer the certificate as a binary file. Since this is the certificate to be trusted by your browser, it is recommended to use a secure connection for transfer.

note

Windows currently does not recognize the PEM format. For Windows, use the P12 version of the local_cer.

Importing commands according to your operating system

To import the certificate to your root certificate store and trust it, follow the applicable procedure based on your operating system.

For Windows, click here for command details.

certutil -enterprise -f -v -AddStore Root" localca.cer

Note: Ensure that you open the terminal as administrator. This operation installs the certificate to the Trusted Root Certification Authorities.

For macOS, click here for command details.

$ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain localca.cer

For Firefox, click here for command deails.

Manually import your root certificate via the Firefox settings, or force Firefox to use the Windows truststore. As a default, Firefox uses its own certificate truststore.

Create a new Javascript file firefox-windows-truststore.js at C:\Program Files (x86)\Mozilla Firefox\defaults\pref with the following content:

/* Enable experimental Windows truststore support */
pref("security.enterprise_roots.enabled", true);

tip

To avoid requiring each browser to trust the CA that signed the Zowe certificate, you can use a public certificate authority to create a certificate. Optional public certificate authorities include Symantec, Comodo, Let's Encrypt, or GoDaddy. Certificates generated by such public CAs are trusted by all browsers and most REST API clients. This option, however, requires a manual process to request a certificate and may incur a cost payable to the publicly trusted CA.

After successfully manually importing a certificate authority into a web browser, you can now import an existing PKCS12 certificate.

Importing a local CA certificate on Linux

Zowe also supports importing certificates to make REST HTTPS curl request from the command line.

Follow these steps to import local_ca.cer from the path .../zowe/keystore/local_ca.

note

Steps are verified with Ubuntu 20.04.6 LTS.

1. Rename local_ca.cer with local_ca.crt and copy to the shared ca-certificates path.

   $ cp local_ca.cer /usr/local/share/ca-certificates/zowe_local_ca.crt

2. Execute a ca-certificate store update by running the following command:

   $ sudo update-ca-certificates

3. Verify that the new expected certificate was added (the newest will be at the bottom of the list which contains an extended list of concatenated CAs).

   $ cat /etc/ssl/certs/ca-certificates.crt

4. Run a basic curl HTTPS request from the command line. For example, run the following command:

curl --request 'GET'
--url 'https://tvt6092.svl.ibm.com:7554/jobs/api/v1?owner=ibmuser&prefix=*'
--header 'Authorization: Basic ************'

After successfully importing your local CA certificate on Linux, you can now import an existing PKCS12 certificate.

Importing an existing JCERACFKS certificate

To import a JCERACFKS certificate, use the example yaml according to Scenario 4: Use a z/OS keyring-based keystore and connect to an existing certificate in the article Certificate configuration scenarios.

To use a JCERACFKS certificate, specify the following parameters in the zowe.yaml file:

Parameter	Description
zowe.setup.certificate.keyring.connect.user	This is a required parameter that specifies the owner of existing certificate. This field can have value of SITE or a user ID.
zowe.setup.certificate.keyring.connect.label	This is a required parameter that sets the label of an existing certificate.

Configure zowe.yaml for a JCERACFKS certificate:

zowe:
  setup:
    certificate:
      type: JCERACFKS
      keyring:
        name: ZoweKeyring
        connect:
          user: IBMUSER
          label: ""
      importCertificateAuthorities:
        - ""

note

Due to the limitation of the RACDCERT command, the importCertificateAuthorities field can contain a maximum of two entries.

You can now use your imported JCERACFKS certificate. See next steps.

Importing a certificate stored in an MVS data set into a Zowe key ring

To import a certificate that is stored in a data set into a key ring, configure the zowe.yaml according to the example yaml in Scenario 5: Use a z/OS keyring-based keystore and import a certificate stored in a data set

To use a JCERACFKS certificate, specify the following parameters in the zowe.yaml file.

Parameter	Description
zowe.setup.certificate.keyring.connect.dsName	This is a required parameter which specifies the data set where the certificate stored.
zowe.setup.certificate.keyring.connect.password	This parameter specifies the password when importing the certificate.
zowe.setup.certificate.keyring.label	This parameter specifies that label of the certificate that is imported.

Configure zowe.yaml for a JCERACFKS certificate stored in an MVS data set:

zowe:
  setup:
    certificate:
      type: JCERACFKS
      keyring:
        name: ZoweKeyring
        label: localhost  # Optional, default value is localhost.
      import:
        dsName: ""
        password: ""

The configuration of zowe.setup.certificate populates information to be used by the subcommand zwe init certificate of zwe init.

Next steps

Once your certificate is successfully imported, review the documentation about how to use certificates in a Zowe production environment.