From 6cdbfed4b24b253b0a367b9e3dd782a5b231e071 Mon Sep 17 00:00:00 2001 From: MarkAckert <35308966+MarkAckert@users.noreply.github.com> Date: Wed, 21 Jan 2026 16:01:52 -0500 Subject: [PATCH 01/26] initial draft Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> --- .../certificate-configuration-scenarios.md | 78 +++++++++++++++---- 1 file changed, 61 insertions(+), 17 deletions(-) diff --git a/docs/user-guide/certificate-configuration-scenarios.md b/docs/user-guide/certificate-configuration-scenarios.md index deed2211ea..08b651164c 100644 --- a/docs/user-guide/certificate-configuration-scenarios.md +++ b/docs/user-guide/certificate-configuration-scenarios.md @@ -15,12 +15,12 @@ Zowe servers require both a keystore to store the certificates and a truststore 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. +This automation can be performed by customizing certificate scenario YAML files found in the `files/examples/setup/certificate` sub-directory within your Zowe installation directory. +Zowe can then use these scenarios and 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`. +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 should directly define the parameter `zowe.certificate`, which specifies the location of each of these certificates and their storage objects. ::: ## * What is a valid certificate in Zowe? @@ -43,6 +43,7 @@ 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. +* [Running a Scenario file](#running-a-scenario-file) * [Scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates](#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-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-3-use-a-zos-keyring-based-keystore-with-zowe-generated-certificates) @@ -50,13 +51,64 @@ Each scenario described in this article provides the configuration details via c * [Scenario 5: Use a z/OS keyring-based keystore and import a certificate stored in a data set](#scenario-5-use-a-zos-keyring-based-keystore-and-import-a-certificate-stored-in-a-data-set) +## Running a Scenario file + +Zowe supplies 5 certificate scenario YAML files in the `files/examples/setup/certificate` sub-directory within your Zowe installation directory. The scenario sections below will describe what each scenario will accomplish, and how to complete customization of the respective scenario YAML files. Once you have selected and finished configuring one of these scenarios, follow one of the two options below to execute them: + +
+Run scenario YAML with configmgr + +1. Identify the fully-qualified path to your selected scenario YAML configuration file. In this example, we will use `/path/to/files/examples/setup/certificate/scenario-1.yaml`. + +2. Identify the fully-qualified path to your main `zowe.yaml` configuration file. In this example, we will use `/path/to/zowe.yaml`. + +3. Create the following configuration parameter, replacing our example paths with your real ones: + ``` + FILE(/path/to/files/examples/setup/certificate/scenario-1.yaml):FILE(/path/to/zowe.yaml) + ``` + +4. Submit `init certificate` using the configuration parameter from Step 3. Note the quotation marks surrounding the configuration path are *required*! + ``` + zwe init certificate -c "FILE(/path/to/files/examples/setup/certificate/scenario-1.yaml):FILE(/path/to/zowe.yaml)" + ``` + +
+ +
+Append scenario YAML contents to main zowe.yaml + +1. Identify the fully-qualified path to your selected scenario YAML configuration file. In this example, we will use `/path/to/files/examples/setup/certificate/scenario-1.yaml`. + +2. Identify the fully-qualified path to your main `zowe.yaml` configuration file. In this example, we will use `/path/to/zowe.yaml`. + +3. Make a manual backup of your `zowe.yaml` file before modification. For example: + ``` + cp /path/to/zowe.yaml /path/to/zowe-backup.yaml + ``` + +4. Append the contents of your selected scenario YAML configuration file to your main `zowe.yaml` configuration. For example: + ``` + cat /path/to/files/examples/setup/certificate/scenario-1.yaml >> /path/to/zowe.yaml + ``` +:::note +If you make further changes to your scenario.yaml configuration file after this step or if you decide to change scenarios, you should either modify the appended values in your `zowe.yaml` file directly, or restore `zowe.yaml` from your backup in Step 3 and re-run Step 4. +::: + +5. Submit `init certificate` using your `zowe.yaml` file. + ``` + zwe init certificate -c /path/to/zowe.yaml + ``` + +
+ + :::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. +Follow this procedure and configure `scenario-1.yaml` within the `files/examples/setup/certificate` directory to enable Zowe to use newly generated PKCS12 certificates stored in a USS directory.
Click here for details. @@ -105,14 +157,6 @@ Use this procedure to configure the `zowe.setup.certificate` section in your yam 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](https://www.ibm.com/support/pages/apar/IJ48749). -::: **Example zowe yaml for scenario 1:** @@ -140,13 +184,13 @@ For more information, see this article in [IBM Support](https://www.ibm.com/supp ``` 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](https://www.youtube.com/playlist?list=PL8REpLGaY9QERUmM--1USMF8yOG-Awzwn) on YouTube. More information about this certificate configuration scenario is also availabe in [this Medium blog post](https://medium.com/zowe/step-by-step-guide-use-a-pkcs12-file-based-keystore-with-zowe-generated-certificate-365dc48eea29). +For more information about using a file-based PKCS12 certificate in Zowe services, see the [video tutorials](https://www.youtube.com/playlist?list=PL8REpLGaY9QERUmM--1USMF8yOG-Awzwn) on YouTube. More information about this certificate configuration scenario is also availabe in [this Medium blog post](https://medium.com/zowe/step-by-step-guide-use-a-pkcs12-file-based-keystore-with-zowe-generated-certificate-365dc48eea29). Both of these resources modify `zowe.yaml` directly, so adapt their contents to your `scenario-1.yaml` configuration file instead.
## 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. +Follow this procedure and configure `scenario-2.yaml` within the `files/examples/setup/certificate` directory to enable Zowe to use previously generated certificates with a PKCS12 keystore stored in a USS directory.
Click here for details. @@ -211,7 +255,7 @@ Your yaml file is now configured to enable Zowe to use a file-based PKCS12 keyst ## 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. +Follow this procedure and configure `scenario-3.yaml` within the `files/examples/setup/certificate` directory to enable Zowe to use newly generated certificates with a z/OS keyring-based keystore.
Click here for details. @@ -299,7 +343,7 @@ Your yaml file is now configured to enable Zowe to use a z/OS keyring-based keys ## 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. +Follow this procedure and configure `scenario-4.yaml` within the `files/examples/setup/certificate` directory to enable Zowe to connect existing certificates with a z/OS keyring-based keystore.
Click here for details. @@ -365,7 +409,7 @@ Your yaml file is now configured to use a z/OS keyring-based keystore and connec ## 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. +Follow this procedure and configure `scenario-5.yaml` within the `files/examples/setup/certificate` directory to enable Zowe to import existing certificates from a dataset into a z/OS keyring-based keystore.
Click here for details. From 720a121ecf4aeb539ac4b58b0d3eb824a0fdca5d Mon Sep 17 00:00:00 2001 From: MarkAckert <35308966+MarkAckert@users.noreply.github.com> Date: Fri, 23 Jan 2026 10:47:44 -0500 Subject: [PATCH 02/26] checkpoint doc changes for certs Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> --- docs/appendix/zowe-security-glossary.md | 21 +-- ...ertificates-configuration-questionnaire.md | 12 +- ...> certificates-configuration-scenarios.md} | 178 +++++++++++------- .../certificates-finalize-configuration.md | 75 ++++++++ ...etup.md => certificates-workflow-setup.md} | 0 docs/user-guide/configure-certificates.md | 80 +++----- docs/user-guide/generate-certificates.md | 133 +------------ docs/user-guide/use-certificates.md | 44 ----- .../zos-components-installation-checklist.md | 2 +- sidebars.js | 32 +++- 10 files changed, 245 insertions(+), 332 deletions(-) rename docs/user-guide/{certificate-configuration-scenarios.md => certificates-configuration-scenarios.md} (68%) create mode 100644 docs/user-guide/certificates-finalize-configuration.md rename docs/user-guide/{certificates-setup.md => certificates-workflow-setup.md} (100%) delete mode 100644 docs/user-guide/use-certificates.md diff --git a/docs/appendix/zowe-security-glossary.md b/docs/appendix/zowe-security-glossary.md index d7335d8ce3..3868058230 100644 --- a/docs/appendix/zowe-security-glossary.md +++ b/docs/appendix/zowe-security-glossary.md @@ -74,6 +74,7 @@ If you do not yet have certificates, Zowe can create self-signed certificates fo - [Extended key usage](#extended-key-usage) - [Hostname validity](#hostname-validity) - [z/OSMF access](#zosmf-access) + ### Extended key usage Zowe server certificates must either not have the `Extended Key Usage` (EKU) attribute, or have both the `TLS Web Server Authentication (1.3.6.1.5.5.7.3.1)` and `TLS Web Client Authentication (1.3.6.1.5.5.7.3.2)` values present within. @@ -88,29 +89,19 @@ The z/OSMF certificate is verified according to Zowe [Certificate verification s ## Certificate setup types -Whether importing or letting Zowe generate certificates, the setup for Zowe certificate automation and the configuration to use an existing keystore and truststore depends upon the content format: file-based (`PKCS12`) or z/OS key ring-based. +Whether importing or letting Zowe generate certificates, the setup for Zowe certificate automation and the configuration to use an existing keystore and truststore depends upon the content format: file-based (`PKCS12`) or z/OS key ring-based. If you are bringing your own previously defined certificates and keyrings to Zowe, you can configure `zowe.certificate` with this information directly and bypass `zwe init certificate` completely. - [File-based (PKCS12) certificate setup](#file-based-pkcs12-certificate-setup) - [z/OS key ring-based certificate setup](#zos-key-ring-based-certificate-setup) + ### File-based (PKCS12) certificate setup Zowe is able to use PKCS12 certificates that are stored in USS. Zowe uses a `keystore` directory to contain its certificates primarily in PKCS12 (`.p12`, `.pfx`) file format, but also in PEM (`.pem`) format. The truststore is in the `truststore` directory that holds the public keys and CA chain of servers which Zowe communicates with (for example z/OSMF). +Configuring PKCS12 certificates is covered under [Certificate Configuration](../user-guide/configure-certificates.md) and [Reviewing Certificate Configuration](../user-guide/certificates-finalize-configuration.md). ### z/OS key ring-based certificate setup -Zowe is able to work with certificates held in a **z/OS Key ring**. - -The JCL member `.SZWESAMP(ZWEKRING)` contains security commands to create a SAF keyring. By default, this key ring is named `ZoweKeyring`. You can use the security commands in this JCL member to generate a Zowe certificate authority (CA) and sign the server certificate with this CA. The JCL contains commands for all three z/OS security managers: RACF, TopSecret, and ACF2. - -There are two ways to configure and submit `ZWEKRING`: - -- Copy the JCL `ZWEKRING` member and customize its values. -- Customize the `zowe.setup.certificate` section in `zowe.yaml` and use the `zwe init certificate` command. - - You can also use the `zwe init certificate` command to prepare a customized JCL member using `ZWEKRING` as a template. +Zowe is able to work with certificates held in a **z/OS key ring**. -A number of key ring scenarios are supported: -- Creation of a local certificate authority (CA) which is used to sign a locally generated certificate. Both the CA and the certificate are placed in the `ZoweKeyring`. -- Import of an existing certificate already held in z/OS to the `ZoweKeyring` for use by Zowe. -- Creation of a locally generated certificate and signed by an existing certificate authority. The certificate is placed in the key ring. +If you are not bringing your own certificate and keyring, and instead would like Zowe to create these for you, then you should follow the instructions under [Zowe Assisted Certificate Setup](../user-guide/certificates-configuration-questionnaire.md). \ No newline at end of file diff --git a/docs/user-guide/certificates-configuration-questionnaire.md b/docs/user-guide/certificates-configuration-questionnaire.md index b9ed04cb4e..2b38275805 100644 --- a/docs/user-guide/certificates-configuration-questionnaire.md +++ b/docs/user-guide/certificates-configuration-questionnaire.md @@ -1,6 +1,6 @@ # Zowe certificates configuration questionnaire -To properly configure Zowe to use certificates for server-side component installation, review the certificate setup options presented in this article. +To properly configure Zowe with certificates for server-side component installation, review the certificate setup options presented in this article. Understanding these options makes it possible to select the best certificate configuration scenario that fits your Zowe deployment use case. :::info Required roles: system programmer, security administrator @@ -42,19 +42,19 @@ If you plan to use Zowe generated self-signed certificates and your target envir Decide if you want to store the certificate in a z/OS keyring or to a file based keystore/truststore. :::tip -While using a keystore/truststore pair is possible to store your certificates, we recommend that you use z/OS keyrings for production deployments. +While using a keystore/truststore pair is possible to store your certificates, we recommend that you use z/OS key rings for production deployments. ::: **Question 4:** Do you plan to use an existing certificate from another keyring or from a dataset? If you have an existing certificate, you can import or connect this certificate to the planned z/OS keyring based storage. -Before you import your certificates, check to make sure that the certificate format, type, and properties correspond to the required protection and acceptability depending on the planned deployment environment (DEV, TEST, PROD). -For example, use Zowe generated self-signed certificates only with development or testing environments and not with production environments. +Before you import your certificates, check to make sure that the certificate format, type, and properties meet your security requirements depending on the planned deployment environment (DEV, TEST, PROD). For example, Zowe generated self-signed certificates may be acceptable with development or testing environments, but not with production environments. + +Required certificate properties are covered in [the Zowe Security Glossary](../appendix/zowe-security-glossary.md#zowe-certificate-requirements). -For more information, see [Import and configure an existing certificate](./import-certificates.md). ## Next steps -After you select your applicable certificate configuration scenario and review the certificate configurate sample in the article [Certificate configuration scenarios](./certificate-configuration-scenarios.md), you can continue to [Configure Zowe Certificates](./configure-certificates.md). +After you select your applicable certificate configuration scenario, you can proceed to [Certificate configuration scenarios](./certificates-configuration-scenarios.md). :::tip If you encounter issues when configuring your certificate, see [Troubleshooting the certificate configuration](../troubleshoot/troubleshoot-zos-certificate.md), to find resolution of errors. diff --git a/docs/user-guide/certificate-configuration-scenarios.md b/docs/user-guide/certificates-configuration-scenarios.md similarity index 68% rename from docs/user-guide/certificate-configuration-scenarios.md rename to docs/user-guide/certificates-configuration-scenarios.md index 08b651164c..22d0777d55 100644 --- a/docs/user-guide/certificate-configuration-scenarios.md +++ b/docs/user-guide/certificates-configuration-scenarios.md @@ -1,26 +1,16 @@ # 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. + After you complete the [Zowe certificates configuration questionnaire](./certificates-configuration-questionnaire.md) to determine your specific configuration use case, choose from the five scenarios presented in this article to complete Zowe assisted certificate setup. Examples sections from `zowe.yaml` files are provided for each scenario. :::info 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](./certificates-configuration-questionnaire.md). This questionnaire guides you through questions 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 customizing certificate scenario YAML files found in the `files/examples/setup/certificate` sub-directory within your Zowe installation directory. -Zowe can then use these scenarios and automate the certificate setup via the `zwe init certificate` command. - +Zowe's assisted certificate setup begins with customizing certificate scenario YAML files found in the `files/examples/setup/certificate` sub-directory within your Zowe installation directory. Zowe will then use these scenarios and complete 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 should directly define the parameter `zowe.certificate`, which specifies the location of each of these certificates and their storage objects. +Reminder: Automated generation of certificates is an option, but is not required. If you already have certificates and a key ring or keystore / truststore combination you've created on your own, you can go right to [Reviewing Certificate Configuration](./certificates-finalize-configuration.md). ::: ## * What is a valid certificate in Zowe? @@ -53,7 +43,7 @@ Each scenario described in this article provides the configuration details via c ## Running a Scenario file -Zowe supplies 5 certificate scenario YAML files in the `files/examples/setup/certificate` sub-directory within your Zowe installation directory. The scenario sections below will describe what each scenario will accomplish, and how to complete customization of the respective scenario YAML files. Once you have selected and finished configuring one of these scenarios, follow one of the two options below to execute them: +Zowe supplies 5 certificate scenario YAML files in the `files/examples/setup/certificate` sub-directory within your Zowe installation directory. The scenario sections below will describe what each scenario will accomplish, and how to complete customization of the respective scenario YAML files. Once you have selected and finished configuring one of these scenarios, follow one of the two options below to execute them.
Run scenario YAML with configmgr @@ -67,9 +57,9 @@ Zowe supplies 5 certificate scenario YAML files in the `files/examples/setup/cer FILE(/path/to/files/examples/setup/certificate/scenario-1.yaml):FILE(/path/to/zowe.yaml) ``` -4. Submit `init certificate` using the configuration parameter from Step 3. Note the quotation marks surrounding the configuration path are *required*! +4. Submit `init certificate` using the configuration parameter from Step 3. Note the quotation marks surrounding the configuration parameter! ``` - zwe init certificate -c "FILE(/path/to/files/examples/setup/certificate/scenario-1.yaml):FILE(/path/to/zowe.yaml)" + zwe init certificate -c "FILE(/path/to/files/examples/setup/certificate/scenario-1.yaml):FILE(/path/to/zowe.yaml)" --update-config ```
@@ -81,22 +71,19 @@ Zowe supplies 5 certificate scenario YAML files in the `files/examples/setup/cer 2. Identify the fully-qualified path to your main `zowe.yaml` configuration file. In this example, we will use `/path/to/zowe.yaml`. -3. Make a manual backup of your `zowe.yaml` file before modification. For example: - ``` - cp /path/to/zowe.yaml /path/to/zowe-backup.yaml - ``` +3. Make a manual backup of your `zowe.yaml` file before modification. 4. Append the contents of your selected scenario YAML configuration file to your main `zowe.yaml` configuration. For example: ``` cat /path/to/files/examples/setup/certificate/scenario-1.yaml >> /path/to/zowe.yaml ``` :::note -If you make further changes to your scenario.yaml configuration file after this step or if you decide to change scenarios, you should either modify the appended values in your `zowe.yaml` file directly, or restore `zowe.yaml` from your backup in Step 3 and re-run Step 4. +If you make changes to your scenario.yaml configuration file after this step or if you decide on a different certificate scenario, you should either modify the appended values in your `zowe.yaml` file directly, or restore `zowe.yaml` from your backup in Step 3 and re-run Step 4. ::: 5. Submit `init certificate` using your `zowe.yaml` file. ``` - zwe init certificate -c /path/to/zowe.yaml + zwe init certificate -c /path/to/zowe.yaml --update-config ```
@@ -108,34 +95,37 @@ Ensure that all alias values for all scenarios use only lower-case. ## Scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates -Follow this procedure and configure `scenario-1.yaml` within the `files/examples/setup/certificate` directory to enable Zowe to use newly generated PKCS12 certificates stored in a USS directory. +Follow this procedure and configure `scenario-1.yaml` within the `files/examples/setup/certificate` directory to enable Zowe to use newly generated PKCS12 certificates stored in a USS directory. These certificates will be signed by a newly created, self-signed Certificate Authority. As such, this is not recommended for production environments.
Click here for details. -1. Set the `type` of the certificate storage to `PKCS12`. +In your `scenario-1.yaml` configuration file: -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: +1. Customize the keystore directory in the following format: + ```yaml + directory: /var/zowe/keystore ``` +2. Customize the certificate alias name. The default value is `localhost`. +3. Set the keystore password. The default value is `password`. +4. (Optional) Uncomment the lock field, which locks the keystore directory so it is accessible only to the Zowe runtime user and group: + ```yaml 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`. - ``` +5. (Optional) Set the alias name of certificate authority. The default value is `local_ca`. + ```yaml caAlias: local_ca ``` -7. Set the password of the keystore stored self-signed certificate authority. The default value is `local_ca_password`. - ``` +6. (Optional) Set the password of the keystore stored certificate authority. The default value is `local_ca_password`. + ```yaml caPassword: local_ca_password ``` -8. (Optional) Specify the distinguished name for Zowe generated certificates. - +7. Set the validity in days for the Zowe generated certificates + ```yaml + validity: 3650 ``` +8. (Optional) Specify the distinguished name for Zowe generated certificates. If you do not want to customize this, you can leave it commented out. + ```yaml dname: caCommonName: "" commonName: "" @@ -145,46 +135,92 @@ Follow this procedure and configure `scenario-1.yaml` within the `files/examples 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`. - ``` +9. (Optional) 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`, which are found in your main `zowe.yaml` file. + ```yaml san: - sample domain name + # sample domain name - dvipa.my-company.com - sample IP address + # sample IP address - 12.34.56.78 ``` +:::tip +To get the san IP address, run `ping dvipa.my-company.com` in your terminal. +::: + + **Example scenario-1 yaml file:** + +```yaml +zowe: + setup: + certificate: + type: PKCS12 + pkcs12: + directory: /global/zowe/keystore + lock: true + name: localhost # Optional, default value is localhost. + password: password # Optional, default value is password. + caAlias: local_ca # Optional, default value is local_ca. + caPassword: local_ca_password # Optional, default value is local_ca_password. + dname: # Distinguished name for Zowe generated certificates. All optional. + caCommonName: "" + commonName: "" + orgUnit: "" + org: "" + locality: "" + state: "" + country: "" + validity: 3650 + san: + - dvipa.my-company.com + - 12.34.56.78 +``` +Your yaml file is now configured to enable Zowe to use generated PKCS12 certificates, and you are ready to [run the scenario](#running-a-scenario-file). - **Example zowe yaml for scenario 1:** +The following command output shows the generation of a PKCS12 keystore using the default values, and has the following associated artifacts. (Note that some detailed output messages have been omitted.) +- The CA is created. +- The keystore is created and the CA is added to the keystore. +- The certificate is created and is added to the keystore. +- The truststore is created. +- Directory permissions are changed to restrict access to the private key. + +**Command output:** ``` - 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 +#>zwe init certificate -c --update-config +------------------------------------------------------------------------------- +>> Creating certificate authority "local_ca" +>> Certificate authority local_ca is created successfully. +------------------------------------------------------------------------------- +>> Export keystore /global/zowe/keystore/local_ca/local_ca.keystore.p12 +>> Keystore /global/zowe/keystore/local_ca/local_ca.keystore.p12 is exported successfully. +------------------------------------------------------------------------------- +>> Creating certificate "localhost" +>> Certificate localhost is created successfully. +------------------------------------------------------------------------------- +>> Export keystore /global/zowe/keystore/localhost/localhost.keystore.p12 +>> Keystore /global/zowe/keystore/localhost/localhost.keystore.p12 is exported successfully.------------------------------------------------------------------------------- +>> Export keystore /global/zowe/keystore/localhost/localhost.truststore.p12 +>> Keystore /global/zowe/keystore/localhost/localhost.truststore.p12 is exported successfully. +------------------------------------------------------------------------------- +>> Lock keystore directory /global/zowe/keystore +>> Keystore directory /global/zowe/keystore is locked. +------------------------------------------------------------------------------- +>> Update certificate configuration to + +- update "zowe.certificate.keystore.type" with value: PKCS12 +... +- update "zowe.certificate.pem.certificateAuthorities" with value: /global/zowe/keystore/local_ca/local_ca.cer + +>> Zowe configuration is updated successfully. + +#> ``` -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](https://www.youtube.com/playlist?list=PL8REpLGaY9QERUmM--1USMF8yOG-Awzwn) on YouTube. More information about this certificate configuration scenario is also availabe in [this Medium blog post](https://medium.com/zowe/step-by-step-guide-use-a-pkcs12-file-based-keystore-with-zowe-generated-certificate-365dc48eea29). Both of these resources modify `zowe.yaml` directly, so adapt their contents to your `scenario-1.yaml` configuration file instead. +You are ready to [Finalize your Zowe Certificate Configuration](./certificates-finalize-configuration.md). + +::note +For more information about using a file-based PKCS12 certificate in Zowe services, see the [video tutorials](https://www.youtube.com/playlist?list=PL8REpLGaY9QERUmM--1USMF8yOG-Awzwn) on YouTube. More information about this certificate configuration scenario is also availabe in [this Medium blog post](https://medium.com/zowe/step-by-step-guide-use-a-pkcs12-file-based-keystore-with-zowe-generated-certificate-365dc48eea29). Both of these resources target an older release of Zowe and modify `zowe.yaml` directly, so you'll need to adapt some of their configuration to your `scenario-1.yaml` configuration file instead. +::
@@ -396,6 +432,12 @@ The following example uses an existing JCERACFKS certificate for Zowe's z/OS com - "zOSMFCA" ``` +**Example:** +![Alt text](../images/certificates/connect-JCERACFKS.png) + +**Note:** +In this example, the command `zwe init certificate -c ./zowe.yaml --security-dry-run` allows the JCL to be inspected before submission, as well as handed off to a security administrator who has privileges to submit the JCL under their user ID. By default, the JCL id submitted immediately. + 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. diff --git a/docs/user-guide/certificates-finalize-configuration.md b/docs/user-guide/certificates-finalize-configuration.md new file mode 100644 index 0000000000..eb49ac38a7 --- /dev/null +++ b/docs/user-guide/certificates-finalize-configuration.md @@ -0,0 +1,75 @@ +# Finalize Certificate Configuration + +Once you have your certificates and either key ring or USS keystore and truststore ready, you can finish configuring certificates with Zowe. Follow the procedure described in this article according to your requirements to finalize and review your Zowe certificate configuration. + +:::info Required roles: system programmer, security administrator +::: +Choose from the following procedures: + +- [Review PKCS12 Certificate Configuration](#review-pkcs12-certificate-configuration) +- [Review JCERACFKS Certificate Configuration](#review-jceracfks-certificate-configuration) + +## Review PKCS12 Certificate Configuration + +Details about the PKCS12 certificates used when Zowe is launched are specified in the `zowe.yaml` section `zowe.certificate`. This configuration block contains information about the certificate name and the location of the certificate, together with the keystore and truststore location. + +If you've used Zowe Assisted Certificate Setup with `--update-config`, the `zowe.certificate` section should be filled out correctly for you. If you did not use `--update-config`, or are bringing your own PKCS12 certificates, then customize your `zowe.yaml` file's `zowe.certificate` section using this guide: + +```yaml +zowe: + # ... you have other fields before certificate + certificate: + keystore: + type: PKCS12 + file: /path/to/your/keystore.p12 + # the password to your keystore + password: password + # alias is the name of your key/cert + alias: my_cert_in_keystore_label + truststore: + # truststore can have the same values as keystore (minus alias), but can be a separate truststore if desired. + # This example shows a separate truststore definition. + type: PKCS12 + file: /path/to/your/truststore.p12 + # the password to your truststore + password: password + pem: + key: /path/to/your/cert.key + certificate: /path/to/your/cert.cer + certificateAuthorities: /path/to/your/cert_authority.cer +``` + +Ensure all the values in this section are correct: they exist in their stated locations, the passwords to the keystore and truststore are accurate, and all file locations are accessible by your Zowe runtime user. + +You can verify the certificate configuration is accurate by starting Zowe. + +## Review JCERACFKS Certificate Configuration + +Details about the JCERACFKS certificates used when Zowe is launched are specified in the `zowe.yaml` section `zowe.certificate`. This section contains information about the certificate name, certificate keystore, and certificate truststore. Both the keystore and truststore will be z/OSMF key rings in this case. + +If you've used Zowe Assisted Certificate Setup with `--update-config`, the `zowe.certificate` section should be filled out correctly for you. If you did not use `--update-config`, or are bringing your own JCERACFKS certificates, then customize your `zowe.yaml` file's `zowe.certificate` section using this guide: + +::note If there is a `zowe.certificate.pem` section, remove it from your `zowe.yaml` file. +:: + +```yaml +zowe: + # ... you have other fields before certificate + certificate: + keystore: + # Type of certificate storage. Value by default should be JCERACFKS. APIML additionally supports: JCEKS, JCECCAKS, JCECCARACFKS, or JCEHYBRIDRACFKS + type: JCERACFKS + file: safkeyring://YOURID/YOURKEYRING + # "password" should literally "password" for key rings + password: password + # alias is the name of your key/cert. Use the Case Sensitive, Space Sensitive value in your ESM's list ring capability + alias: your_cert_label_in_keyring + truststore: + # Truststore usually has same values as keystore (minus alias), but can be different if desired. + # In this example, we link the truststore values to match the keystore values. You can copy this verbatim in most cases. + type: "${{ zowe.certificate.keystore.type }}" + file: "${{ zowe.certificate.keystore.file }}" + password: "${{ zowe.certificate.keystore.password }}" +``` + + diff --git a/docs/user-guide/certificates-setup.md b/docs/user-guide/certificates-workflow-setup.md similarity index 100% rename from docs/user-guide/certificates-setup.md rename to docs/user-guide/certificates-workflow-setup.md diff --git a/docs/user-guide/configure-certificates.md b/docs/user-guide/configure-certificates.md index 25bb90b2b2..34e87f542e 100644 --- a/docs/user-guide/configure-certificates.md +++ b/docs/user-guide/configure-certificates.md @@ -9,7 +9,7 @@ Zowe uses digital certificates for secure, encrypted network communication over Zowe's certificates are stored in its **keystore**. Verification of these certificates and any incoming certificates from other servers or clients is done by using certificates of certificate authorities (CAs) within Zowe's **truststore**. -Zowe supports using either file-based (`PKCS12`) or z/OS key ring-based (when on z/OS) keystores and truststores, and can reuse compatible stores if they exist. Zowe can assist in creating the stores by either generating certificates or by allowing users to import their own compatible certificates via the `zwe init certificate` command. +Zowe supports using either file-based (`PKCS12`) or z/OS key ring-based (when on z/OS) keystores and truststores, and can reuse compatible stores if they exist. * [Certificate concepts](#certificate-concepts) * [Certificate verification](#certificate-verification) @@ -18,7 +18,7 @@ Zowe supports using either file-based (`PKCS12`) or z/OS key ring-based (when on * [Next steps: Creating or importing certificates to Zowe](#next-steps-creating-or-importing-certificates-to-zowe) :::note -If you are already familiar with certificate concepts and how Zowe uses certificates and are ready to get started, see the options under the section _Next steps: Creating or importing certificates to Zowe_ at the end of this article. +If you are already familiar with certificate concepts and how Zowe uses certificates and are ready to get started, see the options under the section [_Next steps: Creating or importing certificates to Zowe_](#next-steps-creating-or-importing-certificates-to-zowe) at the end of this article. ::: ## Certificate concepts @@ -34,44 +34,41 @@ Before you get started with configuring certificates, it is useful to familiariz * [Self-signed certificates](#self-signed-certificates) ### 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. -When you are using a key ring, a single key ring can serve both as a keystore and as a truststore if desired. +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 certificate represented by a public/private key pair, which can then be used by each Zowe server. ### Truststore -The truststore is used by Zowe to verify the authenticity of the certificates that Zowe encounters. The authenticity is required when Zowe is communicating with another server, with one of Zowe's own servers, or with a client that presents a certificate. A truststore is composed of Certificate Authority (CA) certificates that are compared against the CAs that an incoming certificate claims to be signed by. To ensure a certificate is authentic, Zowe must verify that the certificate's claims are correct. Certificate claims include that the certificate was sent by the host that the certificate was issued to, and that the cryptographic signature of the authorities the certificate claims to have been signed by match those found within the truststore. This process helps to ensure that Zowe only communicates with hosts that you trust and have verified as authentic. -When using a key ring, a single key ring can be both a keystore and a truststore if desired. +The truststore is used by Zowe to verify the authenticity of the certificates that Zowe encounters. The authenticity is required when Zowe is communicating with another server, with one of Zowe's own servers, or with a client that presents a certificate. A truststore is composed of Certificate Authority (CA) certificates that are compared against the CAs that an incoming certificate claims to be signed by. To ensure a certificate is authentic, Zowe must verify that the certificate's claims are correct. This process helps to ensure that Zowe only communicates with hosts that you trust and have verified as authentic. ### PKCS12 -PKCS12 is a file format that allows a Zowe user to hold many cryptographic 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. +PKCS12 is a file format that allows a Zowe user to hold many cryptographic objects in one encrypted, password-protected file which is well supported across platforms. PKCS12 setups typically have distinct keystores and truststores, though you can use one store as both keystore and truststore. Throughout Zowe's documentation, we will by default treat the keystore and truststore as separate and distinct. -### z/OS key ring -z/OS provides an interface to manage cryptographic objects in "key rings". As opposed to PKCS12 files, using z/OS key rings allows the crypto objects of many different products to be managed in a uniform manner. z/OS key rings are still encrypted, but do not use passwords for access. Instead, SAF privileges are used to manage access. Java's key ring API requires that the password field for key ring access to be set to "password", so despite not needing a password, you can see this keyword. +* Use of PKCS12 keystores and truststores is recommended for non-production environments. -Use of a z/OS keystore is the recommended option for storing certificates if system programmers are already familiar with the certificate operation and usage. -Creating a key ring and connecting the certificate key pair requires elevated permissions. When the TSO user ID does not have the authority to manipulate key rings and users want to create a Zowe sandbox environment or for testing purposes, the USS keystore is a good alternative. +### z/OS key ring +z/OS provides an interface to manage cryptographic objects in "key rings". Compared with PKCS12, using z/OS key rings grants a deeper integration of certificates into z/OS systems and security management, which benefits systems management and operations across multiple products. z/OS key rings are still encrypted, but do not use passwords for access. Instead, SAF privileges are used to manage access. -One option for certificate setup for key rings is to copy the JCL `ZWEKRING` member of Zowe's SAMPLIB and customize its values. +* Use of z/OS key rings is recommended for production environments. ### Server certificate Servers need a certificate to identify themselves to clients. Every time that you go to an HTTPS website, for example, your browser checks the server certificate and its CA chain to verify that the server you reached is authentic. ### Client certificate -Clients do not always need certificates when they are communicating with servers, but sometimes client certificates can be used wherein the server verifies authenticity of the client similar to how the client verifies authenticity for the server. When client certificates are unique to a client, the certificate can be used as a form of authentication to provide convenient yet secure login. +Clients do not always need certificates when they are communicating with servers, but sometimes client certificates can be used to establish the server's trust of a client's identity, similar to how the client verifies authenticity for the server. When client certificates are unique to a client, the certificate can be used as a form of authentication and login. ### Self-signed certificates -A self-signed certificate is one that is not signed by a CA at all – neither private nor public. In this case, the certificate is signed with its own private key, instead of requesting verification from a public or a private CA. It means that there is no chain of trust to guarantee that the host with this certificate is the one you wanted to communicate with. Note that these certificates are not secure against other hosts masquerading as the one you want to access. As such, it is highly recommended that certificates be verified against the truststore for production environments. +A self-signed certificate is one that is not signed by a public or private certificate authority. In this case, the certificate is signed with its own private key, instead of requesting a signature from a public or a private CA. Self-signed certificates means there is no chain of trust to guarantee that the host with such a certificate is definitively the one you wanted to communicate with, and such they are considered **insecure**. Therefore, we highly recommended and by default require all certificates be verified against a certificate authority in the truststore. ## Certificate verification When you configure Zowe, it is necessary to decide whether Zowe verifies certificates against its truststore. In the Zowe configuration YAML, the property `zowe.verifyCertificates` controls the verification behavior. It can be `DISABLED`, `NONSTRICT`, or `STRICT`. -You can set this property either before or after certificate setup, but **it is recommended to set `zowe.verifyCertificates` before certificate setup** because it affects the automation that Zowe can perform during certificate setup. +You can set this property either before or after certificate setup, but **it is recommended to set `zowe.verifyCertificates` before certificate setup**. ### DISABLED verification If you set `zowe.verifyCertificates` to `DISABLED`, certificate verification is not performed. It is not recommended for security reasons, but may be used for proof of concept or when certificates within your environment are self-signed. -If you set `DISABLED` before certificate setup, Zowe does not automate putting z/OSMF trust objects into the Zowe truststore. This action can result in failure to communicate with z/OSMF if later you enable verification. As such. It is recommended to either set verification on by default, or to reinitialize the keystore if you choose to turn on verification at a later point. +If you set `DISABLED` before certificate setup, Zowe does not automate putting z/OSMF trust objects into the Zowe truststore. This action can result in failure to communicate with z/OSMF if later you enable verification. As such, it is recommended to either set verification on by default, or to reinitialize the keystore if you choose to turn on verification at a later point. ### NON-STRICT verification If you set `zowe.verifyCertificates` to `NONSTRICT`, certificate verification is performed except for hostname validation. Using this setting, the certificate Common Name or Subject Alternate Name (SAN) is not checked. Skipping hostname validation facilitates deployment to environments where certificates are valid but do not contain a valid hostname. This configuration is for development purposes only and should not be used for production. @@ -89,60 +86,31 @@ Zowe server certificates must either not have the `Extended Key Usage` (EKU) att Some Zowe components act as a server, some as a client, and some as both - client and server. The component certificate usage for each of these cases is controlled by the Extended Key Usage (EKU) certificate attribute. The Zowe components use a single certificate (or the same certificate) for client and server authentication, so it is required that this certificate is valid for the intended usage/s of the component - client, server, or both. The EKU certificate extension attribute is not required, however, if it is specified, it must be defined with the intended usage/s. Otherwise, connection requests will be rejected by the other party -### Supported algorithm +### JWT Token Signing Algorithm The server certificate could be used to sign JWT tokens when one of the following conditions is valid: - The token provider is set as SAF (see `apiml.security.auth.provider=saf`) -- The token provider is set as z/OSMF (see `apiml.security.auth.provider=zosmf`), but the z/OSMF is not [configured to support JWT tokens](https://www.ibm.com/docs/en/zos/3.1.0?topic=configurations-enabling-json-web-token-support) -- [Personal access token (PAT)](../getting-started/zowe-security-authentication.md/#authentication-with-personal-access-token-pat) are enabled +- The token provider is set as z/OSMF (see `apiml.security.auth.provider=zosmf`) _and_ z/OSMF is not [configured to support JWT tokens](https://www.ibm.com/docs/en/zos/3.1.0?topic=configurations-enabling-json-web-token-support) +- [Personal access tokens (PAT)](../getting-started/zowe-security-authentication.md#authentication-with-personal-access-token-pat) are enabled -The supported algorithm is: RSASSA-PKCS1-v1_5 using SHA-256 signature algorithm as defined by RFC 7518, Section 3.3. This algorithm requires a 2048-bit key. +Given one of those conditions, the supported JWT signing algorithm is `RSASSA-PKCS1-v1_5` using SHA-256 signature algorithm as defined by RFC 7518, Section 3.3. This algorithm requires a 2048-bit key, so ensure your server certificate has a key size of at least 2048 bits. ### Hostname validity -The host communicating with a certificate should have its hostname match one of the values of the certificate's Common Name or Subject Alternate Name (SAN). If this condition is not true for at least one of the certificates that are seen by Zowe, then you may wish to set [NON-STRICT verification](#non-strict-verification) within Zowe's configuration. +The host communicating with a certificate should have its hostname match one of the values of the certificate's Common Name or Subject Alternate Name (SAN). If this condition is not true for at least one of the certificates that are seen by Zowe, then you can set [NON-STRICT verification](#non-strict-verification) within Zowe's configuration as a workaround. It is recommended to update your certificates so their SAN or Common Name match the hostname. ### z/OSMF access -The z/OSMF certificate is verified according to Zowe's [Certificate verification setting](#certificate-verification), as is the case with any certificate that is seen by Zowe. However, Zowe will also set up a trust relationship with z/OSMF within Zowe's truststore during certificate setup automation if the certificate setting is set to any value other than [DISABLED](#disabled-verification). +z/OSMF's certificate is verified according to Zowe's [Certificate verification setting](#certificate-verification), as is the case with any certificate that is seen by Zowe. Therefore, you will need the certificate authority which signed z/OSMF's certificate in Zowe's truststore. ## Certificate setup type -Whether importing or letting Zowe generate certificates, the setup for Zowe certificate automation and the configuration to use an existing keystore and truststore depends upon the content format: file-based (`PKCS12`) or z/OS key ring-based. - -### File-based (PKCS12) certificate setup - -Zowe is able to use PKCS12 certificates that are stored in USS. Zowe uses a `keystore` directory to contain its certificates primarily in PKCS12 (`.p12`, `.pfx`) file format, but also in PEM (`.pem`) format. The truststore is in the `truststore` directory that holds the public keys and CA chain of servers that Zowe communicates with (for example z/OSMF). - -### z/OS key ring-based certificate setup - -Zowe is able to work with certificates held in a **z/OS key ring**. - -The JCL member `.SZWESAMP(ZWEKRING)` contains security commands to create a SAF key ring. By default, this key ring is named `ZoweKeyring`. You can use the security commands in this JCL member to generate a Zowe certificate authority (CA) and sign the server certificate with this CA. The JCL contains commands for all three z/OS security managers: RACF, TopSecret, and ACF2. - -There are two ways to configure and submit `ZWEKRING`: +Zowe offers automated assistance setting up certificates, though this is disabled by default during the installation process, as we expect most users to bring their own certificates to Zowe. Zowe offers automation for five different scenarios covering both PKCS12 and z/OS key ring options, detailed later under [Certificate Configuration Scenarios](./certificate-configuration-scenarios.md). -- Copy the JCL `ZWEKRING` member and customize its values. -- Customize the `zowe.setup.certificate` section in `zowe.yaml` and use the `zwe init certificate` command. - - You can also use the `zwe init certificate` command to prepare a customized JCL member by using `ZWEKRING` as a template. - -A number of key ring scenarios are supported: - -- Creation of a local certificate authority (CA) which is used to sign a locally generated certificate. Both the CA and the certificate are placed in the `ZoweKeyring`. -- Import of an existing certificate that is already held in z/OS to the `ZoweKeyring` for use by Zowe. -- Import of an existing certificate already held in z/OS to the `ZoweKeyring` for use by Zowe. - -## Next steps: Creating or importing certificates to Zowe +## Next steps: Configuring Certificates for Zowe Review the following options and choose which best applies to your use case: -* Take our [Certificates Configuration Questionnaire](./certificates-configuration-questionnaire.md) to assist with determining which configuration scenario and associated zowe.yaml format best suits your use case. - -* To review the various zowe.yaml files to see which certificate configuration applies to your specific use case, see [Certificate configuration scenarios](./certificate-configuration-scenarios.md). - -* If you have an existing certificate, you can import this certificate to the keystore. For more information, see [Import and configure an existing certificate](./import-certificates.md). - -* If you do not have an existing certificate, you can create one. For more information, see [Generate a certificate](./generate-certificates.md). +* If you are bringing your own certificates and key ring, and configuring them without Zowe's automated assistance, see [Finalize Certificate Configuration](./certificates-finalize-configuration.md). -* When your certificate is already in the keystore, it is ready for use. For more information about how to use it, see [Use certificates](./use-certificates.md). +* If you are not bringing your own certificates and key ring and will use Zowe's automated assistance, take our [Certificates Configuration Questionnaire](./certificates-configuration-questionnaire.md) to determine which configuration scenario best suits your use case and proceed from there. -* If you run into any error when configuring certificates, see [Troubleshooting the certificate configuration](../troubleshoot/troubleshoot-zos-certificate.md). +If you run into any error when configuring certificates, see [Troubleshooting the certificate configuration](../troubleshoot/troubleshoot-zos-certificate.md). diff --git a/docs/user-guide/generate-certificates.md b/docs/user-guide/generate-certificates.md index e70079419f..a34040db27 100644 --- a/docs/user-guide/generate-certificates.md +++ b/docs/user-guide/generate-certificates.md @@ -15,144 +15,13 @@ Both certificate types are self-signed certificates. ## Creating a PKCS12 keystore -Use can create PKCS12 certificates that are stored in USS. This certificate is used for encrypting TLS communication between Zowe clients and Zowe z/OS servers, as well as intra z/OS Zowe server to server communcation. Zowe uses a keystore directory to contain its external certificate, and a truststore directory to hold the public keys of servers it communicate with (for example z/OSMF). +Use can create PKCS12 certificates that are stored in USS. This certificate is used for encrypting TLS communication between Zowe clients and Zowe z/OS servers, as well as z/OS Zowe server to server communication. Zowe uses a keystore directory to contain its external certificate, and a truststore directory to hold the public keys of servers it communicate with (for example z/OSMF). Follow these steps to generate a PKCS12 keystore: 1. [Configure the PKCS12 setup section in zowe.yaml](#configure-the-pkcs12-setup-section-in-zoweyaml) 2. [Run the command to generate a PKCS12 keystore](#run-the-command-to-generate-a-pkcs12-keystore) -### Configure the PKCS12 setup section in zowe.yaml - -To assist with updating `zowe.yaml`, see the example yaml for [scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates](certificate-configuration-scenarios.md/#scenario-1-use-a-file-based-pkcs12-keystore-with-zowe-generated-certificates) in the article Certificate configuration scenarios. - -For PKCS12 certificate users, customize the following parameters in the `zowe.yaml` file: - -| Parameter | Description | -| --------- | ----------- | -| `zowe.setup.certificate.pkcs12.directory` | Specifies the directory where you plan to store the PKCS12 keystore and truststore. This is required if `zowe.setup.certificate.type` is PKCS12. | -| `zowe.setup.certificate.pkcs12.lock` | Is a boolean configuration to tell if we should lock the PKCS12 keystore directory only for Zowe runtime user and group. Default value is true. | -| `zowe.setup.certificate.pkcs12` (*Optional*) | Defines name, password, caAlias and caPassword to customize the keystore and truststore. It is recommended to update these values from the default values. **Note:** Alias names should be all in lower case.| -| `dname` (*Optional*) | Specifies the distinguished name. Domain names and IPs should be added into certificate SAN. If the field `san` is not defined, the `zwe init` command uses `zowe.externalDomains`.| - -**Configuring the `zowe.yaml` file for a PKCS12 certificate** -The following `zowe.yaml` example generates the following artifacts: - - - A `PKCS12` certificate, specified in `zowe.setup.certificate.type`. - - A keystore directory `/var/zowe/keystore`, specified in `zowe.setup.certificate.pkcs12.directory`. - - A certificate name (or alias) `localhost`, specified in `zowe.setup.certificate.pkcs12.name`. - - A certificate authority name `local_ca`, specified in `zowe.setup.certificate.certificate.pkcs12.caAlias`. - -**Example `zowe.yaml` using PKCS12:** -``` -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. - caAlias: local_ca # Optional, default value is local_ca. - caPassword: local_ca_password # Optional, default value is local_ca_password. - dname: # Distinguished name for Zowe generated certificates. All optional. - caCommonName: "" - commonName: "" - orgUnit: "" - org: "" - locality: "" - state: "" - country: "" - validity: 3650 - san: - - dvipa.my-company.com - - 12.34.56.78 -``` - -:::tip -To get the san IP address, run `ping dvipa.my-company.com` in your terminal. -::: - -### Run the command to generate a PKCS12 keystore - -After you configure the `zowe.yaml`, use the following procedure to generate the PKCS12 certificate. - -1. Log in to your system. In this example, run `ssh dvipa.my-company.com` with your password. - -2. Run the following command in the directory with this `zowe.yaml` in the terminal to generate the certificate and update the configuration values in the `zowe.yaml` file. - - `zwe init certificate -c --update-config` - -The following command output shows the generation of a PKCS12 keystore using the default values, and has the following associated artifacts. (Note that some detailed output messages have been omitted.) - -- The CA is created. -- The keystore is created and the CA is added to the keystore. -- The certificate is created and is added to the keystore. -- The truststore is created. -- Directory permissions are changed to restrict access to the private key. - -**Command output:** -``` -#>zwe init certificate -c --update-config -------------------------------------------------------------------------------- ->> Creating certificate authority "local_ca" ->> Certificate authority local_ca is created successfully. -------------------------------------------------------------------------------- ->> Export keystore /global/zowe/keystore/local_ca/local_ca.keystore.p12 ->> Keystore /global/zowe/keystore/local_ca/local_ca.keystore.p12 is exported successfully. -------------------------------------------------------------------------------- ->> Creating certificate "localhost" ->> Certificate localhost is created successfully. -------------------------------------------------------------------------------- ->> Export keystore /global/zowe/keystore/localhost/localhost.keystore.p12 ->> Keystore /global/zowe/keystore/localhost/localhost.keystore.p12 is exported successfully.------------------------------------------------------------------------------- ->> Export keystore /global/zowe/keystore/localhost/localhost.truststore.p12 ->> Keystore /global/zowe/keystore/localhost/localhost.truststore.p12 is exported successfully. -------------------------------------------------------------------------------- ->> Lock keystore directory /global/zowe/keystore ->> Keystore directory /global/zowe/keystore is locked. -------------------------------------------------------------------------------- ->> Update certificate configuration to - -- update "zowe.certificate.keystore.type" with value: PKCS12 -... -- update "zowe.certificate.pem.certificateAuthorities" with value: /global/zowe/keystore/local_ca/local_ca.cer - ->> Zowe configuration is updated successfully. - -#> -``` - -The `zwe init certificate` command generates a certificate based on `zowe.yaml` values in the `zowe.setup.certificate` section. The certificate values used at runtime are referenced in the `zowe.certificate` section in the `zowe.yaml` file. The command `zwe init certificate -c --update-config` updates the runtime `zowe.certificate` section to reference the generated certificate generated from the `zowe.setup.certificate`. - -3. Open the `zowe.yaml` file to check the references to the newly generated certificate values as shown in the following code snippet: - -**Updated `zowe.certificate` section in `zowe.yaml`:** - -``` - certificate: - keystore: - type: PKCS12 - file: /var/zowe/keystore/localhost/localhost.keystore.p12 - password: password - alias: localhost - truststore: - type: PKCS12 - file: /var/zowe/keystore/localhost/localhost.truststore.p12 - password: password - pem: - key: /var/zowe/keystore/localhost/localhost.key - certificate: /var/zowe/keystore/localhost/localhost.cer - certificateAuthorities: /var/zowe/keystore/local_ca/local_ca.cer -``` - -4. (Optional) For details about the certificate you generated, run the following command: -`keytool -v -list -keystore localhost.keystore.p12 -storetype PKCS12` - -You completed the procedure to generate a PKCS12 keystore. - - For more information about additional commands to manage a keystore, see the [keytool documentation](https://docs.oracle.com/en/java/javase/11/tools/keytool.html). ### Next steps after PKCS12 setup diff --git a/docs/user-guide/use-certificates.md b/docs/user-guide/use-certificates.md deleted file mode 100644 index c32ae73243..0000000000 --- a/docs/user-guide/use-certificates.md +++ /dev/null @@ -1,44 +0,0 @@ -# Using certificates - -Once you have generated or imported your certificates, you can now use the certificates with Zowe. Use the procedure descibed in this article that corresponds to the type of certificates you generated or imported. - -:::info Required roles: system programmer, security administrator -::: -Choose from the following procedures: - -- [Use PKCS12 certificates](#use-pkcs12-certificates) -- [Use JCERACFKS certificates](#use-jceracfks-certificates) - -## Use PKCS12 certificates - -To use PKCS12 certificates, run the command `zwe start -c ./zowe.yaml` in the directory with the `zowe.yaml` file to start Zowe. - -Details about the PKCS12 certificate used when Zowe is launched are specified in the `zowe.yaml` section `certificates`. This section contains information about the certificate name and the location of the certificate, together with the truststore location. - -The two most common scenarios for using a PKCS12 certificate are: - -* You have an existing certificate and wish to configure Zowe to use the certificate. -* You do not have a certificate and wish to [generate a new certificate](./generate-certificates.md). - - The `zwe init certificate` command supports both scenarios. The input parameters that control certificate configuration are specified in the section `zowe.setup.certificates`. - -To troubleshoot issues during Zowe startup, see [Troubleshooting startup of Zowe z/OS components](https://docs.zowe.org/stable/troubleshoot/troubleshoot-zos-startup). - -## Use JCERACFKS certificates - -Details about the JCERACFKS certificate used when Zowe is launched are specified in the `zowe.yaml` section `certificates`. This section contains information about the certificate name and location, together with the truststore location. - -The two most common scenarios for using a JCERACFKS certificate are: - -* You have been given an existing certificate and wish to configure Zowe to use it. -* You do not have a certificate and wish to generate a new one. - - The `zwe init certificate` command supports both scenarios. The input parameters that control certificate configuration are specified in the section `zowe.setup.certificates`. See the example of connecting a JCERACFKS certificate below. - -**Example:** -![Alt text](../images/certificates/connect-JCERACFKS.png) - -**Note:** -In this example, the command `zwe init certificate -c ./zowe.yaml --security-dry-run` allows the JCL to be inspected before submission, as well as handed off to a security administrator who has privileges to submit the JCL under their user ID. By default, the JCL id submitted immediately. For details about this example, see this [playlist](https://youtube.com/playlist?list=PL8REpLGaY9QEHLNA81DRgGqWcgOYC0PDX). - - diff --git a/docs/user-guide/zos-components-installation-checklist.md b/docs/user-guide/zos-components-installation-checklist.md index d92584369f..4b81500ef3 100644 --- a/docs/user-guide/zos-components-installation-checklist.md +++ b/docs/user-guide/zos-components-installation-checklist.md @@ -45,7 +45,7 @@ Zowe is able to use PKCS12 certificates or certificates held in a z/OS Keyring. | Task | Results | Time Estimate | |--------------------|----|------| -| Read the article [Zowe certificate configuration overview](../user-guide/configure-certificates.md). Then use one of the following options:

**Option 1: Choose the [certificate configuration scenario](../user-guide/certificate-configuration-scenarios.md)** that best applies to your use case, and follow the configuration procedure and scenario template.

**Option 2: [Set up Zowe certificates using workflows](../user-guide/certificates-setup.md)** | Your certificates are configured and stored securely. |2 hours +| Read the article [Zowe certificate configuration overview](../user-guide/configure-certificates.md). Then use one of the following options:

**Option 1: Choose the [certificate configuration scenario](../user-guide/certificate-configuration-scenarios.md)** that best applies to your use case, and follow the configuration procedure and scenario template.

**Option 2: [Set up Zowe certificates using workflows](../user-guide/certificates-workflow-setup.md)** | Your certificates are configured and stored securely. |2 hours ## Configuring the Zowe cross memory server (ZIS) diff --git a/sidebars.js b/sidebars.js index c77fe6a95c..c81b3fb2e0 100644 --- a/sidebars.js +++ b/sidebars.js @@ -228,16 +228,28 @@ module.exports = { label: "Configuring certificates", link: { type: "doc", id: "user-guide/configure-certificates" }, items: [ - "user-guide/certificates-configuration-questionnaire", - "user-guide/certificate-configuration-scenarios", - "user-guide/import-certificates", - "user-guide/generate-certificates", - "user-guide/use-certificates", - "user-guide/certificates-setup", - "user-guide/tls-configuration", - "user-guide/configuring-at-tls-for-zowe-server-single-service", - "user-guide/configuring-at-tls-for-zowe-server", - "user-guide/using-icsf-hardware-private-keys", + { + type: "category", + label: "Zowe Assisted Certificate Setup", + items: [ + "user-guide/certificates-configuration-questionnaire", + "user-guide/certificates-configuration-scenarios", + "user-guide/import-certificates", + "user-guide/generate-certificates", + "user-guide/certificates-workflow-setup" + ] + }, + { + type: "category", + label: "Advanced Certificate Topics", + items: [ + "user-guide/tls-configuration", + "user-guide/configuring-at-tls-for-zowe-server-single-service", + "user-guide/configuring-at-tls-for-zowe-server", + "user-guide/using-icsf-hardware-private-keys", + ] + }, + "user-guide/certificates-finalize-configuration" ], }, { From fd0f267985590d884b367a1eefadcef7ceb9713d Mon Sep 17 00:00:00 2001 From: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com> Date: Mon, 26 Jan 2026 10:05:13 +0100 Subject: [PATCH 03/26] Fix typos in certificates configuration documentation Signed-off-by: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com> --- docs/user-guide/certificates-configuration-scenarios.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/certificates-configuration-scenarios.md b/docs/user-guide/certificates-configuration-scenarios.md index 22d0777d55..09a0e0d308 100644 --- a/docs/user-guide/certificates-configuration-scenarios.md +++ b/docs/user-guide/certificates-configuration-scenarios.md @@ -219,7 +219,7 @@ The following command output shows the generation of a PKCS12 keystore using the You are ready to [Finalize your Zowe Certificate Configuration](./certificates-finalize-configuration.md). ::note -For more information about using a file-based PKCS12 certificate in Zowe services, see the [video tutorials](https://www.youtube.com/playlist?list=PL8REpLGaY9QERUmM--1USMF8yOG-Awzwn) on YouTube. More information about this certificate configuration scenario is also availabe in [this Medium blog post](https://medium.com/zowe/step-by-step-guide-use-a-pkcs12-file-based-keystore-with-zowe-generated-certificate-365dc48eea29). Both of these resources target an older release of Zowe and modify `zowe.yaml` directly, so you'll need to adapt some of their configuration to your `scenario-1.yaml` configuration file instead. +For more information about using a file-based PKCS12 certificate in Zowe services, see the [video tutorials](https://www.youtube.com/playlist?list=PL8REpLGaY9QERUmM--1USMF8yOG-Awzwn) on YouTube. More information about this certificate configuration scenario is also available in [this Medium blog post](https://medium.com/zowe/step-by-step-guide-use-a-pkcs12-file-based-keystore-with-zowe-generated-certificate-365dc48eea29). Both of these resources target an older release of Zowe and modify `zowe.yaml` directly, so you'll need to adapt some of their configuration to your `scenario-1.yaml` configuration file instead. ::
@@ -285,7 +285,7 @@ PEM format certificate authorities can be imported and trusted. - /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. +Your yaml file is now configured to enable Zowe to use a file-based PKCS12 keystore to import a certificate generated by another CA.
@@ -498,4 +498,4 @@ Follow this procedure and configure `scenario-5.yaml` within the `files/examples ``` Your yaml file is now configured to use a z/OS keyring-based keystore and import a certificate stored in a data set. -
\ No newline at end of file + From d3280b6b0f5fba755465737744d15de9d2fbf684 Mon Sep 17 00:00:00 2001 From: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com> Date: Mon, 26 Jan 2026 13:59:48 +0100 Subject: [PATCH 04/26] Fix typos in generate-certificates.md Corrected typos in the documentation regarding certificate labels and names. Signed-off-by: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com> --- docs/user-guide/generate-certificates.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/generate-certificates.md b/docs/user-guide/generate-certificates.md index a34040db27..0c6f974d77 100644 --- a/docs/user-guide/generate-certificates.md +++ b/docs/user-guide/generate-certificates.md @@ -54,7 +54,7 @@ The following `zowe.yaml` example generates the following artifacts: - A certificate authority with the label `localca` specified in `zowe.setup.certificate.keyring.caLabel` with a common name `Zowe Service CA`. **Example `zowe.yaml` file using a JCERACFKS certificate:** -``` +```yaml zowe: setup: certificate: @@ -80,7 +80,7 @@ zowe: :::note Notes: - Alias names should be all lower cases. -- The name and lables shown above are the default value in `zowe.yaml`. +- The name and labels shown above are the default value in `zowe.yaml`. - `dname` for distinguished name is all optional. - Domain names and IPs should be added to the certificate SAN. If the field `san` is not defined, the `zwe init` command will use `zowe.externalDomains`. The value for the `san` parameter presented in the example is for demonstration purposes. ::: @@ -125,7 +125,7 @@ As shown in the example, the job ends with code `0`. There may, however, be fail 3. Open the `zowe.yaml` file to check the references to the newly generated certificate values. Because the `--update-config` parameter was specified, the runtime configuration section of zowe.yaml is updated to match the values to the generated keystore, certificate, and certificate authority. The updated section is shown in the following code snippet: **Updated `zowe.certificate` section in `zowe.yaml`:** -``` +```yaml zowe: certificate: keystore: From d776cbcdf01010d90673cca251b75de0a753eede Mon Sep 17 00:00:00 2001 From: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com> Date: Mon, 26 Jan 2026 14:12:13 +0100 Subject: [PATCH 05/26] Correct formatting in certificates configuration guide Fixed formatting issues in YAML examples and export messages. Signed-off-by: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com> --- .../certificates-configuration-scenarios.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/user-guide/certificates-configuration-scenarios.md b/docs/user-guide/certificates-configuration-scenarios.md index 09a0e0d308..2d063b41eb 100644 --- a/docs/user-guide/certificates-configuration-scenarios.md +++ b/docs/user-guide/certificates-configuration-scenarios.md @@ -198,7 +198,8 @@ The following command output shows the generation of a PKCS12 keystore using the >> Certificate localhost is created successfully. ------------------------------------------------------------------------------- >> Export keystore /global/zowe/keystore/localhost/localhost.keystore.p12 ->> Keystore /global/zowe/keystore/localhost/localhost.keystore.p12 is exported successfully.------------------------------------------------------------------------------- +>> Keystore /global/zowe/keystore/localhost/localhost.keystore.p12 is exported successfully. +------------------------------------------------------------------------------- >> Export keystore /global/zowe/keystore/localhost/localhost.truststore.p12 >> Keystore /global/zowe/keystore/localhost/localhost.truststore.p12 is exported successfully. ------------------------------------------------------------------------------- @@ -269,7 +270,7 @@ PEM format certificate authorities can be imported and trusted. **Example zowe yaml for scenario 2 (PKCS12):** - ``` + ```yaml certificate: type: PKCS12 pkcs12: @@ -350,7 +351,7 @@ Due to the limitation of the `RACDCERT` command, this field should contain exact **Example zowe yaml for scenario 3:** - ``` + ```yaml certificate: #Type of certificate storage. Valid values are: PKCS12 or JCERACFKS type: JCERACFKS @@ -418,7 +419,7 @@ The following example uses an existing JCERACFKS certificate for Zowe's z/OS com **Example zowe yaml for scenario 4:** -``` +```yaml # >>>> Certificate setup scenario 4 # z/OS Keyring and connect to existing certificate certificate: @@ -485,7 +486,7 @@ Follow this procedure and configure `scenario-5.yaml` within the `files/examples ``` **Example zowe yaml for scenario 5:** -``` +```yaml # >>>> Certificate setup scenario 5 # z/OS Keyring and connect to existing certificate certificate: From 24a1a50fb56ddbf2f4792278178061192a671647 Mon Sep 17 00:00:00 2001 From: MarkAckert <35308966+MarkAckert@users.noreply.github.com> Date: Wed, 28 Jan 2026 13:36:10 -0500 Subject: [PATCH 06/26] code review updates Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> --- ...ertificates-configuration-questionnaire.md | 31 +++++++------------ .../certificates-configuration-scenarios.md | 18 +++++------ .../certificates-finalize-configuration.md | 20 ++++++------ 3 files changed, 31 insertions(+), 38 deletions(-) diff --git a/docs/user-guide/certificates-configuration-questionnaire.md b/docs/user-guide/certificates-configuration-questionnaire.md index 2b38275805..5edfe1c9c5 100644 --- a/docs/user-guide/certificates-configuration-questionnaire.md +++ b/docs/user-guide/certificates-configuration-questionnaire.md @@ -1,17 +1,22 @@ # Zowe certificates configuration questionnaire -To properly configure Zowe with certificates for server-side component installation, review the certificate setup options presented in this article. -Understanding these options makes it possible to select the best certificate configuration scenario that fits your Zowe deployment use case. - :::info Required roles: system programmer, security administrator If you know that you will be using certificates in a production deployment environment, and that you will be using an external certificate authority (CA), we recommend you consult with your organization's security administrator before you start certificate configuration. ::: -Review the Configure Zowe Certificates diagram and answer the questions presented in the questionnaire at the end of this article. +Zowe's assisted certificate setup provides scripts and automation for five different common certificate configurations, with each configuration separated into distinct scenarios. To identify which scenario best meets your site requirements, review the Configure Zowe Certificates diagram and answer the questions presented in the questionnaire at the end of this article. The five different scenarios we provide are: + +* 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 + +After completing the questionnaire, if you find that none of the certificate setup scenarios here satisfy to your site requirements, you should instead proceed by contacting your security administrator and [bringing your own certificates to Zowe](./certificates-finalize-configuration.md). :::tip -Before determining which scenario best suits your use case, it is practical to have a general understanding of the certificate configuration basics and Zowe certificates configuration overview. For more information, see the following articles: +Before answering the questionnaire, it is useful to have a general understanding of the certificate configuration basics and Zowe certificates configuration overview. For more information, see the following articles: - [Certificates concepts](../appendix/zowe-security-glossary.md#certificate-concepts) in the [Zowe Security Glossary](../appendix/zowe-security-glossary.md) - [Zowe certificates overview](../getting-started/zowe-certificates-overview.md) ::: @@ -20,14 +25,6 @@ The numerated decision blocks (yellow diamonds) in the following diagram corresp Follow this sequence of questions to determine which certificate configuration scenario best suits your certificate use case. ![Certificates configuration decision tree](../images/install/certificates-config-scenarios.png) - -Each of the following certificate configuration scenarios are available in the article [Certificate configuration scenarios](./certificate-configuration-scenarios.md). - -* [Scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates](./certificate-configuration-scenarios.md#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](./certificate-configuration-scenarios.md#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](./certificate-configuration-scenarios.md#scenario-3-use-a-zos-keyring-based-keystore-with-zowe-generated-certificates) -* [Scenario 4: Use a z/OS keyring-based keystore and connect an existing certificate](./certificate-configuration-scenarios.md#scenario-4-use-a-zos-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](./certificate-configuration-scenarios.md#scenario-5-use-a-zos-keyring-based-keystore-and-import-a-certificate-stored-in-a-data-set) ## Certificate configuration questionnaire Answer each question and find which scenarios are relevant for the selected option: @@ -48,14 +45,10 @@ While using a keystore/truststore pair is possible to store your certificates, w **Question 4:** Do you plan to use an existing certificate from another keyring or from a dataset? If you have an existing certificate, you can import or connect this certificate to the planned z/OS keyring based storage. -Before you import your certificates, check to make sure that the certificate format, type, and properties meet your security requirements depending on the planned deployment environment (DEV, TEST, PROD). For example, Zowe generated self-signed certificates may be acceptable with development or testing environments, but not with production environments. +Before you import your certificates, check to make sure that the certificate format, type, and properties meet your security requirements depending on the planned deployment environment (DEV, TEST, PROD). For example, Zowe generated self-signed certificates might be acceptable with development or testing environments, but not with production environments. Required certificate properties are covered in [the Zowe Security Glossary](../appendix/zowe-security-glossary.md#zowe-certificate-requirements). ## Next steps -After you select your applicable certificate configuration scenario, you can proceed to [Certificate configuration scenarios](./certificates-configuration-scenarios.md). - -:::tip -If you encounter issues when configuring your certificate, see [Troubleshooting the certificate configuration](../troubleshoot/troubleshoot-zos-certificate.md), to find resolution of errors. -::: +After you have completed the questionnaire and selected a certificate configuration scenario, proceed to [Certificate configuration scenarios](./certificates-configuration-scenarios.md). \ No newline at end of file diff --git a/docs/user-guide/certificates-configuration-scenarios.md b/docs/user-guide/certificates-configuration-scenarios.md index 2d063b41eb..43bb8ab99f 100644 --- a/docs/user-guide/certificates-configuration-scenarios.md +++ b/docs/user-guide/certificates-configuration-scenarios.md @@ -13,6 +13,11 @@ Zowe's assisted certificate setup begins with customizing certificate scenario Y Reminder: Automated generation of certificates is an option, but is not required. If you already have certificates and a key ring or keystore / truststore combination you've created on your own, you can go right to [Reviewing Certificate Configuration](./certificates-finalize-configuration.md). ::: +:::tip +If you encounter issues when configuring your certificate, see [Troubleshooting the certificate configuration](../troubleshoot/troubleshoot-zos-certificate.md), to find resolution of errors. +::: + + ## * What is a valid certificate in Zowe? A valid certificate for use in Zowe conforms to one of the following two options: @@ -298,18 +303,13 @@ Follow this procedure and configure `scenario-3.yaml` within the `files/examples Click here for details. 1. Set the `type` of the certificate storage to one of the following keyring types: - + * JCERACFKS (default) * 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: +2. Under the nested subsection `keyring:`, specify the following keyring values: * keyring name ``` @@ -334,11 +334,11 @@ Follow this procedure and configure `scenario-3.yaml` within the `files/examples state: "" country: "" ``` -4. Set the validity in days for the Zowe generated certificates +3. 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 +4. 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: diff --git a/docs/user-guide/certificates-finalize-configuration.md b/docs/user-guide/certificates-finalize-configuration.md index eb49ac38a7..c66484feb3 100644 --- a/docs/user-guide/certificates-finalize-configuration.md +++ b/docs/user-guide/certificates-finalize-configuration.md @@ -1,4 +1,4 @@ -# Finalize Certificate Configuration +# Finalize certificate configuration Once you have your certificates and either key ring or USS keystore and truststore ready, you can finish configuring certificates with Zowe. Follow the procedure described in this article according to your requirements to finalize and review your Zowe certificate configuration. @@ -9,11 +9,11 @@ Choose from the following procedures: - [Review PKCS12 Certificate Configuration](#review-pkcs12-certificate-configuration) - [Review JCERACFKS Certificate Configuration](#review-jceracfks-certificate-configuration) -## Review PKCS12 Certificate Configuration +## Review PKCS12 certificate configuration -Details about the PKCS12 certificates used when Zowe is launched are specified in the `zowe.yaml` section `zowe.certificate`. This configuration block contains information about the certificate name and the location of the certificate, together with the keystore and truststore location. +When Zowe is launched, details about the PKCS12 certificates are found in the `zowe.yaml` file's `zowe.certificate` section. This configuration block contains information about the certificate name and the location of the certificate, together with the keystore and truststore location. -If you've used Zowe Assisted Certificate Setup with `--update-config`, the `zowe.certificate` section should be filled out correctly for you. If you did not use `--update-config`, or are bringing your own PKCS12 certificates, then customize your `zowe.yaml` file's `zowe.certificate` section using this guide: +If you have used [Zowe Assisted Certificate Setup](./certificates-configuration-scenarios.md) with `--update-config`, the `zowe.certificate` section should be filled out correctly for you. If you did not use `--update-config`, or are bringing your own PKCS12 certificates, then customize your `zowe.yaml` file's `zowe.certificate` section using this guide: ```yaml zowe: @@ -43,14 +43,14 @@ Ensure all the values in this section are correct: they exist in their stated lo You can verify the certificate configuration is accurate by starting Zowe. -## Review JCERACFKS Certificate Configuration +## Review JCERACFKS certificate configuration -Details about the JCERACFKS certificates used when Zowe is launched are specified in the `zowe.yaml` section `zowe.certificate`. This section contains information about the certificate name, certificate keystore, and certificate truststore. Both the keystore and truststore will be z/OSMF key rings in this case. +When Zowe is launched, details about the JCERACFKS certificates are found in the `zowe.yaml` file's `zowe.certificate` section. This section contains information about the certificate name, certificate keystore, and certificate truststore. Both the keystore and truststore are z/OSMF key rings in this case. -If you've used Zowe Assisted Certificate Setup with `--update-config`, the `zowe.certificate` section should be filled out correctly for you. If you did not use `--update-config`, or are bringing your own JCERACFKS certificates, then customize your `zowe.yaml` file's `zowe.certificate` section using this guide: +If you have used Zowe Assisted Certificate Setup with `--update-config`, the `zowe.certificate` section should be filled out correctly for you. If you did not use `--update-config`, or are bringing your own JCERACFKS certificates, then customize your `zowe.yaml` file's `zowe.certificate` section using this guide: -::note If there is a `zowe.certificate.pem` section, remove it from your `zowe.yaml` file. -:: +:::note If there is a `zowe.certificate.pem` section, remove it from your `zowe.yaml` file. +::: ```yaml zowe: @@ -60,7 +60,7 @@ zowe: # Type of certificate storage. Value by default should be JCERACFKS. APIML additionally supports: JCEKS, JCECCAKS, JCECCARACFKS, or JCEHYBRIDRACFKS type: JCERACFKS file: safkeyring://YOURID/YOURKEYRING - # "password" should literally "password" for key rings + # "password" should literally be "password" for key rings password: password # alias is the name of your key/cert. Use the Case Sensitive, Space Sensitive value in your ESM's list ring capability alias: your_cert_label_in_keyring From 2c2c66da3ec8584ad6aece9fcf17f353fa69ed6a Mon Sep 17 00:00:00 2001 From: MarkAckert <35308966+MarkAckert@users.noreply.github.com> Date: Wed, 28 Jan 2026 13:45:12 -0500 Subject: [PATCH 07/26] better glossary info, code review feedback Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> --- docs/appendix/zowe-security-glossary.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/appendix/zowe-security-glossary.md b/docs/appendix/zowe-security-glossary.md index 3868058230..5a33e543e7 100644 --- a/docs/appendix/zowe-security-glossary.md +++ b/docs/appendix/zowe-security-glossary.md @@ -89,7 +89,7 @@ The z/OSMF certificate is verified according to Zowe [Certificate verification s ## Certificate setup types -Whether importing or letting Zowe generate certificates, the setup for Zowe certificate automation and the configuration to use an existing keystore and truststore depends upon the content format: file-based (`PKCS12`) or z/OS key ring-based. If you are bringing your own previously defined certificates and keyrings to Zowe, you can configure `zowe.certificate` with this information directly and bypass `zwe init certificate` completely. +Zowe requires certificates in one of two formats: file-based (`PKCS12`) or z/OS key ring-based. If you are bringing your own previously defined certificates to Zowe, you can configure `zowe.certificate` with this information directly. If you are not bringing your own certificates, [Zowe can assist](../user-guide/certificates-configuration-scenarios.md) with certificate generation. - [File-based (PKCS12) certificate setup](#file-based-pkcs12-certificate-setup) - [z/OS key ring-based certificate setup](#zos-key-ring-based-certificate-setup) @@ -97,11 +97,13 @@ Whether importing or letting Zowe generate certificates, the setup for Zowe cert ### File-based (PKCS12) certificate setup Zowe is able to use PKCS12 certificates that are stored in USS. Zowe uses a `keystore` directory to contain its certificates primarily in PKCS12 (`.p12`, `.pfx`) file format, but also in PEM (`.pem`) format. The truststore is in the `truststore` directory that holds the public keys and CA chain of servers which Zowe communicates with (for example z/OSMF). -Configuring PKCS12 certificates is covered under [Certificate Configuration](../user-guide/configure-certificates.md) and [Reviewing Certificate Configuration](../user-guide/certificates-finalize-configuration.md). + +Generating PKCS12 certificate is covered in [Certificate configuration scenarios](../user-guide/certificates-configuration-scenarios.md), Scenarios 1 and 2. +Configuring PKCS12 certificates is covered in [Finalize certificate configuration](../user-guide/certificates-finalize-configuration.md). ### z/OS key ring-based certificate setup Zowe is able to work with certificates held in a **z/OS key ring**. - -If you are not bringing your own certificate and keyring, and instead would like Zowe to create these for you, then you should follow the instructions under [Zowe Assisted Certificate Setup](../user-guide/certificates-configuration-questionnaire.md). \ No newline at end of file +Generating keyrings with certificates is covered in [Certificate configuration scenarios](../user-guide/certificates-configuration-scenarios.md), Scenarios 3 through 5. +Configuring keyrings with certificates is covered in [Finalize certificate configuration](../user-guide/certificates-finalize-configuration.md). \ No newline at end of file From c9a53551b1c3e100bb5786e2e01622d1c6de38e9 Mon Sep 17 00:00:00 2001 From: MarkAckert <35308966+MarkAckert@users.noreply.github.com> Date: Wed, 28 Jan 2026 13:56:16 -0500 Subject: [PATCH 08/26] fix review steps after configuring certs Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> --- .../certificates-finalize-configuration.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/certificates-finalize-configuration.md b/docs/user-guide/certificates-finalize-configuration.md index c66484feb3..adf5a5a29e 100644 --- a/docs/user-guide/certificates-finalize-configuration.md +++ b/docs/user-guide/certificates-finalize-configuration.md @@ -39,9 +39,13 @@ zowe: certificateAuthorities: /path/to/your/cert_authority.cer ``` -Ensure all the values in this section are correct: they exist in their stated locations, the passwords to the keystore and truststore are accurate, and all file locations are accessible by your Zowe runtime user. +Manually review that all the values you provided are correct: +* The keystore, truststore, and certificates exist in their stated locations. +* The passwords to the keystore and truststore are accurate. +* The certificate alias is correct and exists in the provided keystore. +* All file locations are accessible by your Zowe runtime user. -You can verify the certificate configuration is accurate by starting Zowe. +After manual review, you are ready to start Zowe with your certificate configuration. When Zowe starts, it will perform another series of verifications against your configuration and alert you in the job output if there are any problems. ## Review JCERACFKS certificate configuration @@ -72,4 +76,9 @@ zowe: password: "${{ zowe.certificate.keystore.password }}" ``` +Manually review that all the values you provided are correct: +* The keyring exists. +* The certificate alias is correct and exists in the provided keyring. +* The keyring is accessible by your Zowe runtime user. +After manual review, you are ready to start Zowe with your certificate configuration. When Zowe starts, it will perform another series of verifications against your configuration and alert you in the job output if there are any problems. \ No newline at end of file From fc12b3e51e837e01f993949e2af9da90a470104c Mon Sep 17 00:00:00 2001 From: MarkAckert <35308966+MarkAckert@users.noreply.github.com> Date: Thu, 29 Jan 2026 11:58:17 -0500 Subject: [PATCH 09/26] remove generate certificates article, and rewire markdown links Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> --- .../getting-started/zowe-security-overview.md | 4 +- docs/troubleshoot/known-issues-with-apiml.md | 2 +- ...ertificates-configuration-questionnaire.md | 2 +- .../certificates-configuration-scenarios.md | 250 ++++++++++-------- ....md => certificates-trust-off-platform.md} | 105 +------- docs/user-guide/generate-certificates.md | 154 ----------- sidebars.js | 3 +- 7 files changed, 145 insertions(+), 375 deletions(-) rename docs/user-guide/{import-certificates.md => certificates-trust-off-platform.md} (50%) delete mode 100644 docs/user-guide/generate-certificates.md diff --git a/docs/getting-started/zowe-security-overview.md b/docs/getting-started/zowe-security-overview.md index 4818cbb7c1..be7e53e2e6 100644 --- a/docs/getting-started/zowe-security-overview.md +++ b/docs/getting-started/zowe-security-overview.md @@ -82,8 +82,6 @@ For more information about the SAF resource check, see [Configuring SAF resource ## Additional resources For more information about getting started with certificates including determining your certificate configuration use case, importing certificates, generating certificates and using certificates, see the following resources: -- [Certificate configuration scenarios](../user-guide/certificate-configuration-scenarios.md) -- [Generating a certificate](../user-guide/generate-certificates.md) -- [Importing and configuring a certificate](../user-guide/import-certificates.md) +- [Certificate configuration scenarios](../user-guide/certificates-configuration-scenarios.md) - [Configuring certificates](../user-guide/configure-certificates.md) diff --git a/docs/troubleshoot/known-issues-with-apiml.md b/docs/troubleshoot/known-issues-with-apiml.md index 42b52525dd..c137d42a8a 100644 --- a/docs/troubleshoot/known-issues-with-apiml.md +++ b/docs/troubleshoot/known-issues-with-apiml.md @@ -201,6 +201,6 @@ Request a new certificate that contains a valid z/OSMF host name in the subject ### Re-create the Zowe keystore -Re-create the Zowe keystore by deleting it and re-creating it. For more information, see [Importing a file-based PKCS12 certificate](../user-guide/import-certificates.md#importing-an-existing-pkcs12-certificate). The Zowe keystore directory is the value of the `KEYSTORE_DIRECTORY` variable in the `zowe.yaml` file that is used to launch Zowe. +Re-create the Zowe keystore by deleting it and re-creating it. For more information, see [Scenario 2: Importing a file-based PKCS12 certificate](../user-guide/certificates-configuration-scenarios.md#scenario-2-use-a-file-based-pkcs12-keystore-and-import-a-certificate-generated-by-another-ca). The Zowe keystore directory is the value of the `KEYSTORE_DIRECTORY` variable in the `zowe.yaml` file that is used to launch Zowe. diff --git a/docs/user-guide/certificates-configuration-questionnaire.md b/docs/user-guide/certificates-configuration-questionnaire.md index 5edfe1c9c5..11498857ab 100644 --- a/docs/user-guide/certificates-configuration-questionnaire.md +++ b/docs/user-guide/certificates-configuration-questionnaire.md @@ -5,7 +5,7 @@ If you know that you will be using certificates in a production deployment environment, and that you will be using an external certificate authority (CA), we recommend you consult with your organization's security administrator before you start certificate configuration. ::: -Zowe's assisted certificate setup provides scripts and automation for five different common certificate configurations, with each configuration separated into distinct scenarios. To identify which scenario best meets your site requirements, review the Configure Zowe Certificates diagram and answer the questions presented in the questionnaire at the end of this article. The five different scenarios we provide are: +Zowe's assisted certificate setup provides scripts and automation for five different common certificate configurations, with each configuration separated into distinct scenarios. To identify which scenario best meets your site requirements, review the Configure Zowe Certificates diagram and answer the questions presented in the questionnaire at the end of this article. The five different certificate setup scenarios we support are: * 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 diff --git a/docs/user-guide/certificates-configuration-scenarios.md b/docs/user-guide/certificates-configuration-scenarios.md index 43bb8ab99f..200a43c2ee 100644 --- a/docs/user-guide/certificates-configuration-scenarios.md +++ b/docs/user-guide/certificates-configuration-scenarios.md @@ -1,40 +1,26 @@ # Certificate configuration scenarios - After you complete the [Zowe certificates configuration questionnaire](./certificates-configuration-questionnaire.md) to determine your specific configuration use case, choose from the five scenarios presented in this article to complete Zowe assisted certificate setup. Examples sections from `zowe.yaml` files are provided for each scenario. +After you have completed the [Zowe certificates configuration questionnaire](./certificates-configuration-questionnaire.md) and chosen a certificate configuration scenario, follow the scenario-specific documentation and `zowe.yaml` examples in this article. :::info Required roles: system programmer, security administrator ::: Zowe servers require both a keystore to store the certificates and a truststore to validate certificates. -Zowe's assisted certificate setup begins with customizing certificate scenario YAML files found in the `files/examples/setup/certificate` sub-directory within your Zowe installation directory. Zowe will then use these scenarios and complete certificate setup via the `zwe init certificate` command. +Zowe's assisted certificate setup begins with customizing certificate scenario YAML files found in the `files/examples/setup/certificate` sub-directory within your Zowe installation directory. Zowe will then use these scenario configurations and complete certificate setup via the `zwe init certificate` command. :::note -Reminder: Automated generation of certificates is an option, but is not required. If you already have certificates and a key ring or keystore / truststore combination you've created on your own, you can go right to [Reviewing Certificate Configuration](./certificates-finalize-configuration.md). -::: - -:::tip -If you encounter issues when configuring your certificate, see [Troubleshooting the certificate configuration](../troubleshoot/troubleshoot-zos-certificate.md), to find resolution of errors. +Reminder: Zowe assisted generation of certificates is an option, but is not required. If you already have certificates and a key ring or keystore / truststore combination you created on your own, you can instead go to [Finalize certificate configuration](./certificates-finalize-configuration.md). ::: - -## * What is a valid certificate in Zowe? +## 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. +## Scenario overview 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. @@ -45,10 +31,13 @@ Each scenario described in this article provides the configuration details via c * [Scenario 4: Use a z/OS keyring-based keystore and connect an existing certificate](#scenario-4-use-a-zos-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](#scenario-5-use-a-zos-keyring-based-keystore-and-import-a-certificate-stored-in-a-data-set) +:::note +Ensure that all certificate alias values for all scenarios use only lower-case. +::: -## Running a Scenario file +## Running a scenario file -Zowe supplies 5 certificate scenario YAML files in the `files/examples/setup/certificate` sub-directory within your Zowe installation directory. The scenario sections below will describe what each scenario will accomplish, and how to complete customization of the respective scenario YAML files. Once you have selected and finished configuring one of these scenarios, follow one of the two options below to execute them. +Zowe supplies 5 certificate scenario YAML files in the `files/examples/setup/certificate` sub-directory within your Zowe installation directory. The scenario section below describes what each scenario will accomplish, and how to complete customization of the respective scenario YAML files. Once you have selected and finished configuring one of these scenarios, follow the below instructions to execute the scenario.
Run scenario YAML with configmgr @@ -62,14 +51,30 @@ Zowe supplies 5 certificate scenario YAML files in the `files/examples/setup/cer FILE(/path/to/files/examples/setup/certificate/scenario-1.yaml):FILE(/path/to/zowe.yaml) ``` -4. Submit `init certificate` using the configuration parameter from Step 3. Note the quotation marks surrounding the configuration parameter! - ``` - zwe init certificate -c "FILE(/path/to/files/examples/setup/certificate/scenario-1.yaml):FILE(/path/to/zowe.yaml)" --update-config +4. Navigate to your Zowe installation root directory. + +4. Submit `./bin/zwe init certificate` using the configuration parameter from Step 3. Note the quotation marks surrounding the configuration parameter! If you are running Scenario 3, 4, or 5, you can add `--dry-run` to the command and review the JCL used to create the keyring before submission. + ```shell + ./bin/zwe init certificate --update-config -c "FILE(/path/to/files/examples/setup/certificate/scenario-1.yaml):FILE(/path/to/zowe.yaml)" + + # If you are using scenarios 3, 4, or 5, this will print JCL to the console for review + ./bin/zwe init certificate --dry-run --update-config -c "FILE(/path/to/files/examples/setup/certificate/scenario-1.yaml):FILE(/path/to/zowe.yaml)" ```
-
+ - -:::note -Ensure that all alias values for all scenarios use only lower-case. +:::tip +If you encounter issues when configuring your certificate, see [Troubleshooting the certificate configuration](../troubleshoot/troubleshoot-zos-certificate.md), to find resolution of errors. ::: ## Scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates @@ -179,7 +183,7 @@ zowe: - dvipa.my-company.com - 12.34.56.78 ``` -Your yaml file is now configured to enable Zowe to use generated PKCS12 certificates, and you are ready to [run the scenario](#running-a-scenario-file). +Your yaml file is now configured to enable Zowe to use generated PKCS12 certificates. You can now go to [Running a scenario file](#running-a-scenario-file). The following command output shows the generation of a PKCS12 keystore using the default values, and has the following associated artifacts. (Note that some detailed output messages have been omitted.) @@ -222,7 +226,8 @@ The following command output shows the generation of a PKCS12 keystore using the #> ``` -You are ready to [Finalize your Zowe Certificate Configuration](./certificates-finalize-configuration.md). +You are ready to [Finalize your Zowe Certificate Configuration](./certificates-finalize-configuration.md). + ::note For more information about using a file-based PKCS12 certificate in Zowe services, see the [video tutorials](https://www.youtube.com/playlist?list=PL8REpLGaY9QERUmM--1USMF8yOG-Awzwn) on YouTube. More information about this certificate configuration scenario is also available in [this Medium blog post](https://medium.com/zowe/step-by-step-guide-use-a-pkcs12-file-based-keystore-with-zowe-generated-certificate-365dc48eea29). Both of these resources target an older release of Zowe and modify `zowe.yaml` directly, so you'll need to adapt some of their configuration to your `scenario-1.yaml` configuration file instead. @@ -238,35 +243,34 @@ Follow this procedure and configure `scenario-2.yaml` within the `files/examples 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 +2. Customize the keystore `directory` in the following format: + ```yaml + directory: /var/zowe/keystore ``` 3. Lock the keystore directory so it is accessible only to the Zowe runtime user and group: - ``` + ```yaml 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. - ``` +4. Set keystore password. The default value is `password`. +5. Set the existing PKCS12 keystore which holds the certificate issued by an external CA. + ```yaml keystore: "" ``` -7. Set the password of the keystore set in step 6. - ``` +6. Set the password of the keystore set in step 5. + ```yaml password: "" ``` -8. Specify the alias of the certificate to be imported. - ``` +7. Specify the alias of the certificate to be imported. + ```yaml alias: "" ``` -9. Set the path to the certificate authority that signed the certificate to be imported. - ``` +8. Set the path to the certificate authority that signed the certificate to be imported. PEM-formatted certificate authorities can be imported. + ```yaml importCertificateAuthorities: + - "" ``` :::note @@ -291,7 +295,12 @@ PEM format certificate authorities can be imported and trusted. - /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 generated by another CA. +:::note +Due to the limitation of the RACDCERT command, the `importCertificateAuthorities` field can contain a maximum of two entries. +::: + + +Your yaml file is now configured to enable Zowe to use a file-based PKCS12 keystore to import a certificate generated by another CA. You can now go to [Running a scenario file](#running-a-scenario-file).
@@ -308,23 +317,22 @@ Follow this procedure and configure `scenario-3.yaml` within the `files/examples * JCECCAKS * JCECCARACFKS * JCEHYBRIDRACFKS - + 2. Under the nested subsection `keyring:`, specify the following keyring values: - * keyring name - ``` + ```yaml name: ZoweKeyring ``` * Label of Zowe certificate. The default value is `localhost`. - ``` + ```yaml label: localhost ``` * Label of Zowe CA certificate. The default value is `localca`. - ``` + ```yaml caLabel: localca ``` - * The distinguished name for Zowe generated certificates. - ``` + * (Optional) The distinguished name for Zowe generated certificates. + ```yaml dname: caCommonName: "" commonName: "" @@ -334,13 +342,13 @@ Follow this procedure and configure `scenario-3.yaml` within the `files/examples state: "" country: "" ``` -3. Set the validity in days for the Zowe generated certificates - ``` +3. (Optional) Set the validity in days for the Zowe generated certificates. Defaults to 3650 days. + ```yaml validity: 3650 ``` -4. Set the domain names and IPs specified in the certificate SAN. If +4. (Optional, Recommended) 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`. - ``` + ```yaml san: - dvipa.my-company.com - 12.34.56.78 @@ -353,12 +361,8 @@ Due to the limitation of the `RACDCERT` command, this field should contain exact ```yaml certificate: - #Type of certificate storage. Valid values are: PKCS12 or JCERACFKS type: JCERACFKS - createZosmfTrust: true keyring: - #**COMMONLY_CUSTOMIZED** - #Keystore directory name: ZoweKeyring label: localhost caLabel: localca @@ -374,65 +378,91 @@ Due to the limitation of the `RACDCERT` command, this field should contain exact - 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. +Your yaml file is now configured to enable Zowe to use a z/OS keyring-based keystore with Zowe generated certificates. You can now go to [Running a scenario file](#running-a-scenario-file). + +The following command output shows the generation of a JCERACFKS certificate using the default values. Note that some detailed output messages have been omitted. + +**Command output:** +``` +#>zwe init certificate -c --update-config +------------------------------------------------------------------------------- +>> Generate Zowe certificate in keyring + +>>>> Modify ZWEKRING + - IBMUSER.ZWEV3.CUST.JCLLIB(ZW101431) is prepared +>>>> Submit IBMUSER.ZWEV3.CUST.JCLLIB(ZW101431) + - Job ZWEKRING(JOB03054) ends with code 0 (COMPLETED). +>> Certificate is generated in keyring successfully. + +------------------------------------------------------------------------------- +>> Update certificate configuration to +>> Zowe configuration is updated successfully. + +#> +``` + +:::tip +As shown in the example, the job ends with code `0`. There may, however, be failures in the individual steps. It is advised to check the job output. The security manager commands in the job are generated based on the value of `zowe.security.product`. Job steps for each product can be determined by the security manager. +::: ## Scenario 4: Use a z/OS keyring-based keystore and connect to an existing certificate -Follow this procedure and configure `scenario-4.yaml` within the `files/examples/setup/certificate` directory to enable Zowe to connect existing certificates with a z/OS keyring-based keystore. +Follow this procedure and configure `scenario-4.yaml` within the `files/examples/setup/certificate` directory to enable Zowe to connect existing certificates with a z/OS keyring-based keystore.
Click here for details. 1. Set the `type` of the certificate storage to one of the following keyring types: - + * JCERACFKS (default) * JCEKS * JCECCAKS - * JCERACFKS * JCECCARACFKS * JCEHYBRIDRACFKS -2. Under `keyring:`, specify the keyring name: - ``` +2. Under keyring, specify the keyring `name`: + ```yaml 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. - ``` +3. Under the nested subsection `connect`, specify the following parameters: + * The current owner of the existing certificate. Possible values can be `SITE` or a user ID. + ```yaml user: IBMUSER ``` * The label of the existing certificate to be connected to the Zowe keyring. - ``` + ```yaml label: "" ``` * All certificate authorities you want to be trusted in the Zowe keyring. - ``` + ```yaml 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](https://medium.com/zowe/master-zowe-certificates-use-an-existing-jceracfks-certificate-for-zowes-z-os-components-975ffa0d9f2f), or the video tutorials in [this YouTube playlist](https://www.youtube.com/playlist?list=PL8REpLGaY9QEHLNA81DRgGqWcgOYC0PDX). **Example zowe yaml for scenario 4:** ```yaml - # >>>> 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" +zowe: + setup: + certificate: + type: JCERACFKS + keyring: + name: ZoweKeyring + connect: + user: IBMUSER + label: "" + importCertificateAuthorities: + - "zOSMFCA" ``` +Your yaml file is now configured to enable Zowe to use a z/OS keyring-based keystore with Zowe generated certificates. You can now go to [Running a scenario file](#running-a-scenario-file). + +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](https://medium.com/zowe/master-zowe-certificates-use-an-existing-jceracfks-certificate-for-zowes-z-os-components-975ffa0d9f2f), or the video tutorials in [this YouTube playlist](https://www.youtube.com/playlist?list=PL8REpLGaY9QEHLNA81DRgGqWcgOYC0PDX). + **Example:** ![Alt text](../images/certificates/connect-JCERACFKS.png) @@ -446,8 +476,6 @@ If you would like to use this example in your Zowe configuration YAML file, repl * 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 @@ -458,45 +486,47 @@ Follow this procedure and configure `scenario-5.yaml` within the `files/examples Click here for details. 1. Set the `type` of the certificate storage to one of the following keyring types: - + * JCERACFKS (default) * JCEKS * JCECCAKS - * JCERACFKS * JCECCARACFKS * JCEHYBRIDRACFKS -2. Under `keyring:`, specify the following keyring values: +2. Under `keyring`, specify the following keyring values: - * keyring name - ``` + * keyring `name` + ```yaml name: ZoweKeyring ``` * Label of Zowe certificate. The default value is `localhost`. - ``` + ```yaml 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: "" +3. Under the nested subsection `import`, specify the following parameters: + * The name of the data set that holds the certificate issued by another CA. This data set should be in PKCS12 format and contain private key. + ```yaml + dsName: "" ``` * The password for the PKCS12 data set. - ``` - password: "" + ```yaml + password: "" ``` **Example zowe yaml for scenario 5:** ```yaml - # >>>> 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 +zowe: + setup: + certificate: + type: JCERACFKS + keyring: + name: ZoweKeyring + label: localhost # Optional, default value is localhost. + import: + dsName: "" + password: "" ``` -Your yaml file is now configured to use a z/OS keyring-based keystore and import a certificate stored in a data set. + +Your yaml file is now configured to use a z/OS keyring-based keystore and import a certificate stored in a data set. You can now go to [Running a scenario file](#running-a-scenario-file). + diff --git a/docs/user-guide/import-certificates.md b/docs/user-guide/certificates-trust-off-platform.md similarity index 50% rename from docs/user-guide/import-certificates.md rename to docs/user-guide/certificates-trust-off-platform.md index b21beaa205..248710241d 100644 --- a/docs/user-guide/import-certificates.md +++ b/docs/user-guide/certificates-trust-off-platform.md @@ -1,15 +1,7 @@ -# Importing and configuring a certificate +# Trusting certificates in client environments -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. -:::info Required roles: system programmer, security administrator -::: - -Choose from the following certificate importing options: -* [Importing a file-based PKCS12 certificate](#importing-an-existing-pkcs12-certificate) -* [Importing a JCERACFKS certificate](#importing-an-existing-jceracfks-certificate) -* [Importing a certificate stored in an MVS data set into a Zowe key ring](#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: @@ -17,41 +9,6 @@ To import a PKCS12 certificate, it is first necessary to import a certificate au * [Manually importing a certificate authority into a web browser](#manually-importing-a-certificate-authority-into-a-web-browser) * [Importing a local CA certificate on Linux](#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](../user-guide/certificate-configuration-scenarios.md#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](#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. @@ -159,66 +116,6 @@ Steps are verified with Ubuntu 20.04.6 LTS. After successfully importing your local CA certificate on Linux, you can now [import an existing PKCS12 certificate](#importing-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](certificate-configuration-scenarios.md#scenario-4-use-a-zos-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](#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](certificate-configuration-scenarios.md#scenario-5-use-a-zos-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](./use-certificates.md) in a Zowe production environment. diff --git a/docs/user-guide/generate-certificates.md b/docs/user-guide/generate-certificates.md deleted file mode 100644 index 0c6f974d77..0000000000 --- a/docs/user-guide/generate-certificates.md +++ /dev/null @@ -1,154 +0,0 @@ - -# Generating a certificate - -If you do not have a certificate, follow the procedure in this article that corresponds to the certificate type you choose to generate. - -:::info Required roles: system programmer, security administrator -::: - -Choose from the following certificate types: - -* [Creating a PKCS12 certificate](#creating-a-pkcs12-keystore) -* [Creating a JCERACFKS certificate](#creating-a-jceracfks-certificate) - -Both certificate types are self-signed certificates. - -## Creating a PKCS12 keystore - -Use can create PKCS12 certificates that are stored in USS. This certificate is used for encrypting TLS communication between Zowe clients and Zowe z/OS servers, as well as z/OS Zowe server to server communication. Zowe uses a keystore directory to contain its external certificate, and a truststore directory to hold the public keys of servers it communicate with (for example z/OSMF). - -Follow these steps to generate a PKCS12 keystore: - -1. [Configure the PKCS12 setup section in zowe.yaml](#configure-the-pkcs12-setup-section-in-zoweyaml) -2. [Run the command to generate a PKCS12 keystore](#run-the-command-to-generate-a-pkcs12-keystore) - - -### Next steps after PKCS12 setup - -When using a Zowe-generated certificate, you will be challenged by your browser when logging in to Zowe to accept Zowe's untrusted certificate authority. Depending on the browser you are using, there are different ways to proceed. See next steps about how to [import the PKCS12 certificate to your browser](./import-certificates.md). - -## Creating a JCERACFKS certificate - -You can create a JCERACFKS certificate for use in a z/OS keystore. JCERACFKS uses SAF and RACF services to protect key material and certificates. - -Use the following procedure to configure the `zowe.yaml` file for JCERACFKS certificates: - -1. [Configure the JCERACFKS setup section in zowe.yaml](#configure-the-jceracfks-setup-section-in-zoweyaml) -2. [Run the command to generate a JCERACFKS certificate](#run-the-command-to-generate-a-jceracfks-certificate) - -To assist with updating `zowe.yaml`, see the example yaml in [Scenario 3: Use a z/OS keyring-based keystore with Zowe generated certificates](certificate-configuration-scenarios.md#scenario-3-use-a-zos-keyring-based-keystore-with-zowe-generated-certificates) in the article Certificate configuration scenarios. -### Configure the JCERACFKS setup section in zowe.yaml - -For JCERACFKS certificate (z/OS key ring) users, customize the following parameters in the `zowe.yaml` file: - -| Parameter | Description | -| ---------- | ----------- | -| `zowe.setup.certificate.keyring.owner` | The key ring owner. This parameter is optional and the default value is `zowe.setup.security.users.zowe`. If this parameter is not defined, the default value is ZWESVUSR.| -| `zowe.setup.certificate.keyring.name` | Specifies the key ring name to be created on z/OS. This parameter is required if `zowe.setup.certificate.type` is `JCERACFKS`.| - -The following `zowe.yaml` example generates the following artifacts: - - - A `JCERACFKS` certificate, specified in `zowe.setup.certificate.type`. - - A key ring named `ZoweKeyring` specified in `zowe.setup.certificate.keyring.name`. - - A certificate with the label `localhost` specified in `zowe.setup.certificate.keyring.label`. - - A certificate authority with the label `localca` specified in `zowe.setup.certificate.keyring.caLabel` with a common name `Zowe Service CA`. - -**Example `zowe.yaml` file using a JCERACFKS certificate:** -```yaml -zowe: - setup: - certificate: - type: JCERACFKS - createZosmfTrust: true - keyring: - name: ZoweKeyring - label: localhost # Optional, default value is localhost. - caLabel: localca # Optional, default value is localca. - dname: # Distinguished name for Zowe generated certificates. All optional. - caCommonName: "" - commonName: "" - orgUnit: "" - org: "" - locality: "" - state: "" - country: "" - validity: 3650 - san: - - dvipa.my-company.com - - 12.34.56.78 -``` - -:::note Notes: -- Alias names should be all lower cases. -- The name and labels shown above are the default value in `zowe.yaml`. -- `dname` for distinguished name is all optional. -- Domain names and IPs should be added to the certificate SAN. If the field `san` is not defined, the `zwe init` command will use `zowe.externalDomains`. The value for the `san` parameter presented in the example is for demonstration purposes. -::: - -### Run the command to generate a JCERACFKS certificate - -After you configure the `zowe.yaml`, use the following procedure to generate a JCERACFKS certificate. - -1. Log in to your system. In this example, run `ssh dvipa.my-company.com` with your password. - -2. Run the following command in the directory with this `zowe.yaml` in terminal to generate the certificate and update the configuration values in `zowe.yaml`. - - `zwe init certificate -c --update-config` - - When the command is run, a customized JCL member name is created in the `CUST.JCLLIB` data set. The PDS name is defined in the `zowe.setup.dataset.jcllib` property. In the following example output, the PDS member `USER.ZWE3.CUST.JCLLIB(ZW101431)` is created that contains the security manager commands, and then submitted as a job ID: `ZWEKRING(JOB03054)`. - -The following command output shows the generation of a JCERACFKS certificate using the default values. Note that some detailed output messages have been omitted. - -**Command output:** -``` -#>zwe init certificate -c --update-config -------------------------------------------------------------------------------- ->> Generate Zowe certificate in keyring - ->>>> Modify ZWEKRING - - IBMUSER.ZWEV3.CUST.JCLLIB(ZW101431) is prepared ->>>> Submit IBMUSER.ZWEV3.CUST.JCLLIB(ZW101431) - - Job ZWEKRING(JOB03054) ends with code 0 (COMPLETED). ->> Certificate is generated in keyring successfully. - -------------------------------------------------------------------------------- ->> Update certificate configuration to ->> Zowe configuration is updated successfully. - -#> -``` - -:::tip -As shown in the example, the job ends with code `0`. There may, however, be failures in the individual steps. It is advised to check the job output. The security manager commands in the job are generated based on the value of `zowe.security.product`. Job steps for each product can be determined by the security manager. -::: - -3. Open the `zowe.yaml` file to check the references to the newly generated certificate values. Because the `--update-config` parameter was specified, the runtime configuration section of zowe.yaml is updated to match the values to the generated keystore, certificate, and certificate authority. The updated section is shown in the following code snippet: - -**Updated `zowe.certificate` section in `zowe.yaml`:** -```yaml -zowe: - certificate: - keystore: - alias: localhost - password: 'password' - file: safkeyring://ZWESVUSR/ZoweKeyring - type: JCERACFKS - truststore: - type: JCERACFKS - file: safkeyring://ZWESVUSR/ZoweKeyring - password: "password" - pem: - key: - certificate: - certificateAuthorities: safkeyring://ZWESVUSR/ZoweKeyring&localca -``` - -:::note -`zowe.certificate.keystore.password` has a hardcoded password value. If you are using `type: PKCS12`, the password field must be the real password. -::: - -You completed the procedure to generate a JCERACFKS certificate. - -### Next steps after JCERACFKS setup - -For more information about how to use your JCERACFKS certificate, see [Use JCERACFKS certificates](./use-certificates.md). diff --git a/sidebars.js b/sidebars.js index c81b3fb2e0..83a61d24ef 100644 --- a/sidebars.js +++ b/sidebars.js @@ -234,8 +234,6 @@ module.exports = { items: [ "user-guide/certificates-configuration-questionnaire", "user-guide/certificates-configuration-scenarios", - "user-guide/import-certificates", - "user-guide/generate-certificates", "user-guide/certificates-workflow-setup" ] }, @@ -243,6 +241,7 @@ module.exports = { type: "category", label: "Advanced Certificate Topics", items: [ + "user-guide/certificates-trust-off-platform", "user-guide/tls-configuration", "user-guide/configuring-at-tls-for-zowe-server-single-service", "user-guide/configuring-at-tls-for-zowe-server", From 6831adb46c90459da50db7417e1af2692349b092 Mon Sep 17 00:00:00 2001 From: MarkAckert <35308966+MarkAckert@users.noreply.github.com> Date: Thu, 29 Jan 2026 17:24:34 -0500 Subject: [PATCH 10/26] re-structure off-platform article a little bit Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> --- .../certificates-trust-off-platform.md | 20 +++++-------------- 1 file changed, 5 insertions(+), 15 deletions(-) diff --git a/docs/user-guide/certificates-trust-off-platform.md b/docs/user-guide/certificates-trust-off-platform.md index 248710241d..026e05615c 100644 --- a/docs/user-guide/certificates-trust-off-platform.md +++ b/docs/user-guide/certificates-trust-off-platform.md @@ -1,20 +1,13 @@ -# Trusting certificates in client environments +# Trusting certificates off platform - - -## 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](#manually-importing-a-certificate-authority-into-a-web-browser) -* [Importing a local CA certificate on Linux](#importing-a-local-ca-certificate-on-linux) +Zowe services are protected by the certificates you set in your `zowe.yaml` configuration file, and these certificates are presented to all clients connecting to Zowe, including off-platform clients. If you are using your browser to view Zowe's API Mediation Layer or Web Desktop, or if you are using Zowe Explorer with an API Mediation Layer connection profile, the certificate Zowe presents may be challenged by your browser or operating system. This article covers a common method for trusting certificates: importing them in your off-platform client environment. ## 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](#manually-importing-a-certificate-authority-into-a-web-browser) -* [Importing a local CA certificate on Linux](#importing-a-local-ca-certificate-on-linux) +* [Importing commands according to your operating system](#importing-commands-according-to-your-operating-system) ### Manually importing a certificate authority into a web browser @@ -23,7 +16,7 @@ To avoid the browser untrusted CA challenge, import Zowe certificates into the b 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. + If a SAF keyring is used and the certificate was generated on z/OS, 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](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) 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. @@ -43,7 +36,7 @@ For Windows, click here for command details. ``` -certutil -enterprise -f -v -AddStore Root" localca.cer +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. @@ -82,7 +75,6 @@ pref("security.enterprise_roots.enabled", true); 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-an-existing-pkcs12-certificate). ### Importing a local CA certificate on Linux @@ -114,8 +106,6 @@ Steps are verified with Ubuntu 20.04.6 LTS. --header 'Authorization: Basic ************' ``` -After successfully importing your local CA certificate on Linux, you can now [import an existing PKCS12 certificate](#importing-an-existing-pkcs12-certificate). - ## Next steps Once your certificate is successfully imported, review the documentation about how to [use certificates](./use-certificates.md) in a Zowe production environment. From 4e44d4e61aa0830fa0d927f03e6364a3580b4514 Mon Sep 17 00:00:00 2001 From: MarkAckert <35308966+MarkAckert@users.noreply.github.com> Date: Thu, 29 Jan 2026 17:36:56 -0500 Subject: [PATCH 11/26] few more touches for clarity Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> --- docs/user-guide/certificates-finalize-configuration.md | 10 +++++++--- docs/user-guide/configure-certificates.md | 2 +- ...onfiguring-at-tls-for-zowe-server-single-service.md | 2 +- docs/user-guide/tls-configuration.md | 2 +- 4 files changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/user-guide/certificates-finalize-configuration.md b/docs/user-guide/certificates-finalize-configuration.md index adf5a5a29e..fde01c6641 100644 --- a/docs/user-guide/certificates-finalize-configuration.md +++ b/docs/user-guide/certificates-finalize-configuration.md @@ -47,11 +47,15 @@ Manually review that all the values you provided are correct: After manual review, you are ready to start Zowe with your certificate configuration. When Zowe starts, it will perform another series of verifications against your configuration and alert you in the job output if there are any problems. -## Review JCERACFKS certificate configuration +## Review key ring certificate configuration -When Zowe is launched, details about the JCERACFKS certificates are found in the `zowe.yaml` file's `zowe.certificate` section. This section contains information about the certificate name, certificate keystore, and certificate truststore. Both the keystore and truststore are z/OSMF key rings in this case. +When Zowe is launched, details about the key ring certificates are found in the `zowe.yaml` file's `zowe.certificate` section. This section contains information about the certificate name, certificate keystore, and certificate truststore. Both the keystore and truststore are z/OSMF key rings in this case. -If you have used Zowe Assisted Certificate Setup with `--update-config`, the `zowe.certificate` section should be filled out correctly for you. If you did not use `--update-config`, or are bringing your own JCERACFKS certificates, then customize your `zowe.yaml` file's `zowe.certificate` section using this guide: +If you have used Zowe Assisted Certificate Setup with `--update-config`, the `zowe.certificate` section should be filled out correctly for you. If you did not use `--update-config`, or are bringing your own key ring and certificates, then customize your `zowe.yaml` file's `zowe.certificate` section using the below guide. + +If you are using AT-TLS with Zowe, consult the [Enabling AT-TLS for single-service deployment mode](./configuring-at-tls-for-zowe-server-single-service.md) article before proceeding. The key ring you define in your AT-TLS configuration should be the key ring you supply in the below guide. + +If you want to use ICSF-backed private keys, consult the [Using ICSF Hardware Private Keys](./using-icsf-hardware-private-keys.md) article before proceeding. As mentioned in that article, ensure you are using `JCEHYBRIDRACFKS` as you follow the below example. :::note If there is a `zowe.certificate.pem` section, remove it from your `zowe.yaml` file. ::: diff --git a/docs/user-guide/configure-certificates.md b/docs/user-guide/configure-certificates.md index 34e87f542e..0ddfcb74b5 100644 --- a/docs/user-guide/configure-certificates.md +++ b/docs/user-guide/configure-certificates.md @@ -109,7 +109,7 @@ Zowe offers automated assistance setting up certificates, though this is disable Review the following options and choose which best applies to your use case: -* If you are bringing your own certificates and key ring, and configuring them without Zowe's automated assistance, see [Finalize Certificate Configuration](./certificates-finalize-configuration.md). +* If you are bringing your own certificates and key ring, and configuring them without Zowe's automated assistance, see [Finalize Certificate Configuration](./certificates-finalize-configuration.md). You should also choose this option if you are setting up Zowe with an [AT-TLS configuration](./configuring-at-tls-for-zowe-server-single-service.md). * If you are not bringing your own certificates and key ring and will use Zowe's automated assistance, take our [Certificates Configuration Questionnaire](./certificates-configuration-questionnaire.md) to determine which configuration scenario best suits your use case and proceed from there. diff --git a/docs/user-guide/configuring-at-tls-for-zowe-server-single-service.md b/docs/user-guide/configuring-at-tls-for-zowe-server-single-service.md index 1d61c005c2..70dca49465 100644 --- a/docs/user-guide/configuring-at-tls-for-zowe-server-single-service.md +++ b/docs/user-guide/configuring-at-tls-for-zowe-server-single-service.md @@ -8,7 +8,7 @@ Configuring AT-TLS allows Zowe to offload all TLS responsibilities to the z/OS C This article explains how to enable AT-TLS for single-service deployment mode so your Zowe environment can benefit from this streamlined, system-driven approach to secure communications. :::tip -Beginning with Zowe v3.4.0 and for later versions, we recommend the use of single-service deployment mode. For the benefits of running Zowe in this mode, see [Enabling Single-Service deployment of API Mediation Layer](api-mediation/api-mediation-modulith.md). +Beginning with Zowe v3.4.0 and for later versions, we recommend the use of single-service deployment mode. For the benefits of running Zowe in this mode, see [Enabling Single-Service deployment of API Mediation Layer](api-mediation/api-mediation-modulith.md). ::: :::note diff --git a/docs/user-guide/tls-configuration.md b/docs/user-guide/tls-configuration.md index 62f453a488..6f4d192b5c 100644 --- a/docs/user-guide/tls-configuration.md +++ b/docs/user-guide/tls-configuration.md @@ -2,7 +2,7 @@ Zowe's servers have built-in TLS support to enable HTTPS connections. -TLS support is the default setting, and an alternative to using AT-TLS. For information about using AT-TLS, see [Enabling AT-TLS](./configuring-at-tls-for-zowe-server.md). +TLS support is the default setting, and an alternative to using AT-TLS. For information about using AT-TLS, see [Enabling AT-TLS](./configuring-at-tls-for-zowe-server-single-service.md). :::info Required role: security administrator ::: From 30d8bde480bee0d881a9fe0be341dad81672eabf Mon Sep 17 00:00:00 2001 From: MarkAckert <35308966+MarkAckert@users.noreply.github.com> Date: Fri, 30 Jan 2026 13:16:32 -0500 Subject: [PATCH 12/26] fix some broken links Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> --- .../certificates-finalize-configuration.md | 2 +- docs/user-guide/certificates-trust-off-platform.md | 3 +-- docs/user-guide/configure-certificates.md | 12 ++++++------ 3 files changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/user-guide/certificates-finalize-configuration.md b/docs/user-guide/certificates-finalize-configuration.md index fde01c6641..26d314542c 100644 --- a/docs/user-guide/certificates-finalize-configuration.md +++ b/docs/user-guide/certificates-finalize-configuration.md @@ -7,7 +7,7 @@ Once you have your certificates and either key ring or USS keystore and truststo Choose from the following procedures: - [Review PKCS12 Certificate Configuration](#review-pkcs12-certificate-configuration) -- [Review JCERACFKS Certificate Configuration](#review-jceracfks-certificate-configuration) +- [Review JCERACFKS Certificate Configuration](#review-key-ring-certificate-configuration) ## Review PKCS12 certificate configuration diff --git a/docs/user-guide/certificates-trust-off-platform.md b/docs/user-guide/certificates-trust-off-platform.md index 026e05615c..0cc37dfe61 100644 --- a/docs/user-guide/certificates-trust-off-platform.md +++ b/docs/user-guide/certificates-trust-off-platform.md @@ -105,8 +105,7 @@ Steps are verified with Ubuntu 20.04.6 LTS. --url 'https://tvt6092.svl.ibm.com:7554/jobs/api/v1?owner=ibmuser&prefix=*' --header 'Authorization: Basic ************' ``` - ## Next steps -Once your certificate is successfully imported, review the documentation about how to [use certificates](./use-certificates.md) in a Zowe production environment. +Once your certificate is successfully imported, your browser and operating system should no longer challenge every connection as untrusted. diff --git a/docs/user-guide/configure-certificates.md b/docs/user-guide/configure-certificates.md index 0ddfcb74b5..654e3d9011 100644 --- a/docs/user-guide/configure-certificates.md +++ b/docs/user-guide/configure-certificates.md @@ -15,10 +15,10 @@ Zowe supports using either file-based (`PKCS12`) or z/OS key ring-based (when on * [Certificate verification](#certificate-verification) * [Zowe certificate requirements](#zowe-certificate-requirements) * [Certificate setup type](#certificate-setup-type) -* [Next steps: Creating or importing certificates to Zowe](#next-steps-creating-or-importing-certificates-to-zowe) +* [Next steps: Creating or importing certificates to Zowe](#next-steps-configuring-certificates-for-zowe) :::note -If you are already familiar with certificate concepts and how Zowe uses certificates and are ready to get started, see the options under the section [_Next steps: Creating or importing certificates to Zowe_](#next-steps-creating-or-importing-certificates-to-zowe) at the end of this article. +If you are already familiar with certificate concepts and how Zowe uses certificates and are ready to get started, see the options under the section [_Next steps: Creating or importing certificates to Zowe_](#next-steps-configuring-certificates-for-zowe) at the end of this article. ::: ## Certificate concepts @@ -56,10 +56,10 @@ Servers need a certificate to identify themselves to clients. Every time that yo Clients do not always need certificates when they are communicating with servers, but sometimes client certificates can be used to establish the server's trust of a client's identity, similar to how the client verifies authenticity for the server. When client certificates are unique to a client, the certificate can be used as a form of authentication and login. ### Self-signed certificates -A self-signed certificate is one that is not signed by a public or private certificate authority. In this case, the certificate is signed with its own private key, instead of requesting a signature from a public or a private CA. Self-signed certificates means there is no chain of trust to guarantee that the host with such a certificate is definitively the one you wanted to communicate with, and such they are considered **insecure**. Therefore, we highly recommended and by default require all certificates be verified against a certificate authority in the truststore. +A self-signed certificate is one that is not signed by a public or private certificate authority. Instead, the certificate is signed with its own private key, hence self-signed. Self-signed certificates means there is no chain of trust to guarantee that the host with such a certificate is definitively the one you wanted to communicate with, and such they are considered **insecure**. Therefore, we highly recommended and by default require that all certificates are verified against a certificate authority in the truststore. ## Certificate verification -When you configure Zowe, it is necessary to decide whether Zowe verifies certificates against its truststore. +When you configure Zowe, you can change whether Zowe verifies certificates against its truststore or not. In the Zowe configuration YAML, the property `zowe.verifyCertificates` controls the verification behavior. It can be `DISABLED`, `NONSTRICT`, or `STRICT`. @@ -103,9 +103,9 @@ The host communicating with a certificate should have its hostname match one of z/OSMF's certificate is verified according to Zowe's [Certificate verification setting](#certificate-verification), as is the case with any certificate that is seen by Zowe. Therefore, you will need the certificate authority which signed z/OSMF's certificate in Zowe's truststore. ## Certificate setup type -Zowe offers automated assistance setting up certificates, though this is disabled by default during the installation process, as we expect most users to bring their own certificates to Zowe. Zowe offers automation for five different scenarios covering both PKCS12 and z/OS key ring options, detailed later under [Certificate Configuration Scenarios](./certificate-configuration-scenarios.md). +Zowe offers automated assistance setting up certificates, though this is disabled by default during the installation process, as we expect most users to bring their own certificates to Zowe. Zowe offers automation for five different scenarios covering both PKCS12 and z/OS key ring options, detailed later under [Certificate Configuration Scenarios](./certificates-configuration-scenarios.md). -## Next steps: Configuring Certificates for Zowe +## Next steps: configuring certificates for Zowe Review the following options and choose which best applies to your use case: From ab6aee307f56862c3b2f1148a6b4fe4005dc16dd Mon Sep 17 00:00:00 2001 From: MarkAckert <35308966+MarkAckert@users.noreply.github.com> Date: Fri, 30 Jan 2026 15:09:41 -0500 Subject: [PATCH 13/26] Make a quick note that keyrings and AT-TLS go together in the glossary Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> --- docs/appendix/zowe-security-glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/appendix/zowe-security-glossary.md b/docs/appendix/zowe-security-glossary.md index 5a33e543e7..1f302c7e2a 100644 --- a/docs/appendix/zowe-security-glossary.md +++ b/docs/appendix/zowe-security-glossary.md @@ -89,7 +89,7 @@ The z/OSMF certificate is verified according to Zowe [Certificate verification s ## Certificate setup types -Zowe requires certificates in one of two formats: file-based (`PKCS12`) or z/OS key ring-based. If you are bringing your own previously defined certificates to Zowe, you can configure `zowe.certificate` with this information directly. If you are not bringing your own certificates, [Zowe can assist](../user-guide/certificates-configuration-scenarios.md) with certificate generation. +Zowe requires certificates in one of two formats: file-based (`PKCS12`) or z/OS key ring-based. If you are bringing your own previously defined certificates to Zowe, you can configure `zowe.certificate` with this information directly. Key rings are required for Zowe AT-TLS configurations. If you are not bringing your own certificates, [Zowe can assist](../user-guide/certificates-configuration-scenarios.md) with certificate generation. - [File-based (PKCS12) certificate setup](#file-based-pkcs12-certificate-setup) - [z/OS key ring-based certificate setup](#zos-key-ring-based-certificate-setup) From 1c8fed6cfd87a81ed2f6cd41a471220fb6a650ac Mon Sep 17 00:00:00 2001 From: Mark Ackert <35308966+MarkAckert@users.noreply.github.com> Date: Mon, 2 Feb 2026 10:51:43 -0500 Subject: [PATCH 14/26] Update docs/appendix/zowe-security-glossary.md Co-authored-by: anaxceron Signed-off-by: Mark Ackert <35308966+MarkAckert@users.noreply.github.com> --- docs/appendix/zowe-security-glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/appendix/zowe-security-glossary.md b/docs/appendix/zowe-security-glossary.md index 1f302c7e2a..bc137695fa 100644 --- a/docs/appendix/zowe-security-glossary.md +++ b/docs/appendix/zowe-security-glossary.md @@ -98,7 +98,7 @@ Zowe requires certificates in one of two formats: file-based (`PKCS12`) or z/OS Zowe is able to use PKCS12 certificates that are stored in USS. Zowe uses a `keystore` directory to contain its certificates primarily in PKCS12 (`.p12`, `.pfx`) file format, but also in PEM (`.pem`) format. The truststore is in the `truststore` directory that holds the public keys and CA chain of servers which Zowe communicates with (for example z/OSMF). -Generating PKCS12 certificate is covered in [Certificate configuration scenarios](../user-guide/certificates-configuration-scenarios.md), Scenarios 1 and 2. +Generating PKCS12 certificates is covered in [Certificate configuration scenarios](../user-guide/certificates-configuration-scenarios.md) Scenario 1 and Scenario 2. Configuring PKCS12 certificates is covered in [Finalize certificate configuration](../user-guide/certificates-finalize-configuration.md). ### z/OS key ring-based certificate setup From 9ccf429edab82a093dc0789a8254de4724dc35ac Mon Sep 17 00:00:00 2001 From: Mark Ackert <35308966+MarkAckert@users.noreply.github.com> Date: Mon, 2 Feb 2026 10:54:05 -0500 Subject: [PATCH 15/26] Apply suggestions from code review Co-authored-by: anaxceron Signed-off-by: Mark Ackert <35308966+MarkAckert@users.noreply.github.com> --- docs/appendix/zowe-security-glossary.md | 2 +- docs/troubleshoot/known-issues-with-apiml.md | 2 +- docs/user-guide/certificates-configuration-questionnaire.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/appendix/zowe-security-glossary.md b/docs/appendix/zowe-security-glossary.md index bc137695fa..070abd59b2 100644 --- a/docs/appendix/zowe-security-glossary.md +++ b/docs/appendix/zowe-security-glossary.md @@ -105,5 +105,5 @@ Configuring PKCS12 certificates is covered in [Finalize certificate configuratio Zowe is able to work with certificates held in a **z/OS key ring**. -Generating keyrings with certificates is covered in [Certificate configuration scenarios](../user-guide/certificates-configuration-scenarios.md), Scenarios 3 through 5. +Generating keyrings with certificates is covered in [Certificate configuration scenarios](../user-guide/certificates-configuration-scenarios.md), Scenarios 3-5. Configuring keyrings with certificates is covered in [Finalize certificate configuration](../user-guide/certificates-finalize-configuration.md). \ No newline at end of file diff --git a/docs/troubleshoot/known-issues-with-apiml.md b/docs/troubleshoot/known-issues-with-apiml.md index c137d42a8a..96409d87bc 100644 --- a/docs/troubleshoot/known-issues-with-apiml.md +++ b/docs/troubleshoot/known-issues-with-apiml.md @@ -201,6 +201,6 @@ Request a new certificate that contains a valid z/OSMF host name in the subject ### Re-create the Zowe keystore -Re-create the Zowe keystore by deleting it and re-creating it. For more information, see [Scenario 2: Importing a file-based PKCS12 certificate](../user-guide/certificates-configuration-scenarios.md#scenario-2-use-a-file-based-pkcs12-keystore-and-import-a-certificate-generated-by-another-ca). The Zowe keystore directory is the value of the `KEYSTORE_DIRECTORY` variable in the `zowe.yaml` file that is used to launch Zowe. +Recreate the Zowe keystore by deleting it and recreating it. For more information, see [Scenario 2: Importing a file-based PKCS12 certificate](../user-guide/certificates-configuration-scenarios.md#scenario-2-use-a-file-based-pkcs12-keystore-and-import-a-certificate-generated-by-another-ca). The Zowe keystore directory is the value of the `KEYSTORE_DIRECTORY` variable in the `zowe.yaml` file that is used to launch Zowe. diff --git a/docs/user-guide/certificates-configuration-questionnaire.md b/docs/user-guide/certificates-configuration-questionnaire.md index 11498857ab..c412e200cf 100644 --- a/docs/user-guide/certificates-configuration-questionnaire.md +++ b/docs/user-guide/certificates-configuration-questionnaire.md @@ -5,7 +5,7 @@ If you know that you will be using certificates in a production deployment environment, and that you will be using an external certificate authority (CA), we recommend you consult with your organization's security administrator before you start certificate configuration. ::: -Zowe's assisted certificate setup provides scripts and automation for five different common certificate configurations, with each configuration separated into distinct scenarios. To identify which scenario best meets your site requirements, review the Configure Zowe Certificates diagram and answer the questions presented in the questionnaire at the end of this article. The five different certificate setup scenarios we support are: +Zowe's assisted certificate setup provides scripts and automation for five different common certificate configurations, with each configuration separated into distinct scenarios. To identify which scenario best meets your site requirements, review the Configure Zowe Certificates diagram and answer the questions presented in the questionnaire at the end of this article. The five different certificate setup scenarios Zowe supports are: * 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 From a37317a6d4c711e13e3c1ae54446d3afed6e1c15 Mon Sep 17 00:00:00 2001 From: MarkAckert <35308966+MarkAckert@users.noreply.github.com> Date: Mon, 2 Feb 2026 11:01:34 -0500 Subject: [PATCH 16/26] key ring format Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> --- docs/appendix/zowe-security-glossary.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/appendix/zowe-security-glossary.md b/docs/appendix/zowe-security-glossary.md index 070abd59b2..3cdc7aeb13 100644 --- a/docs/appendix/zowe-security-glossary.md +++ b/docs/appendix/zowe-security-glossary.md @@ -105,5 +105,5 @@ Configuring PKCS12 certificates is covered in [Finalize certificate configuratio Zowe is able to work with certificates held in a **z/OS key ring**. -Generating keyrings with certificates is covered in [Certificate configuration scenarios](../user-guide/certificates-configuration-scenarios.md), Scenarios 3-5. -Configuring keyrings with certificates is covered in [Finalize certificate configuration](../user-guide/certificates-finalize-configuration.md). \ No newline at end of file +Generating key rings with certificates is covered in [Certificate configuration scenarios](../user-guide/certificates-configuration-scenarios.md), Scenarios 3-5. +Configuring key rings with certificates is covered in [Finalize certificate configuration](../user-guide/certificates-finalize-configuration.md). \ No newline at end of file From dcc55689d2a255d561a6f813ee7e59c02682e2c3 Mon Sep 17 00:00:00 2001 From: MarkAckert <35308966+MarkAckert@users.noreply.github.com> Date: Mon, 2 Feb 2026 13:10:43 -0500 Subject: [PATCH 17/26] code review comments, fix broken links Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> --- .../extend-apiml/certificate-management-in-zowe-apiml.md | 4 ++-- docs/getting-started/zowe-certificates-overview.md | 2 -- docs/getting-started/zowe-security-overview.md | 3 +-- docs/user-guide/zos-components-installation-checklist-dev.md | 2 +- 4 files changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/extend/extend-apiml/certificate-management-in-zowe-apiml.md b/docs/extend/extend-apiml/certificate-management-in-zowe-apiml.md index dd49398eca..c992d90c23 100644 --- a/docs/extend/extend-apiml/certificate-management-in-zowe-apiml.md +++ b/docs/extend/extend-apiml/certificate-management-in-zowe-apiml.md @@ -63,8 +63,8 @@ There are two ways to set up certificates on a z/OS machine: - [Certificates in SAF keyring](#api-ml-saf-keyring) For detailed instructions about how to set up certificates during installation, see the following articles: -* [Use PKCS12 certificates](../../user-guide/use-certificates.md#use-pkcs12-certificates) -* [Use JCERACFS certificates](../../user-guide/use-certificates.md#use-jceracfks-certificates) in a keyring +* [Use PKCS12 certificates](../../user-guide/certificates-configuration-scenarios.md#scenario-overview) +* [Use JCERACFS certificates](../../user-guide/certificates-configuration-scenarios.md#scenario-overview) in a keyring Follow the procedure in the applicable section in this article during installation. diff --git a/docs/getting-started/zowe-certificates-overview.md b/docs/getting-started/zowe-certificates-overview.md index 3fd408941f..7788da1abe 100644 --- a/docs/getting-started/zowe-certificates-overview.md +++ b/docs/getting-started/zowe-certificates-overview.md @@ -39,8 +39,6 @@ X.509 Digital certificates are primarly used to implement the following function Zowe uses digital certificates as a foundational element for both communication and for identity security. Additionally, Zowe provides a client identity validation functionality based on the ownership of the provided x.509 client certificate and the mainframe security authentication mechanism. -For more information about how Zowe leverages certificates, see [Zowe certificate usage](../user-guide/use-certificates.md). - To review the various Zowe certificate configuration options, see the [Zowe certificate configuration overview](../user-guide/configure-certificates.md). ## Public key infrastructure diff --git a/docs/getting-started/zowe-security-overview.md b/docs/getting-started/zowe-security-overview.md index be7e53e2e6..38cd71d825 100644 --- a/docs/getting-started/zowe-security-overview.md +++ b/docs/getting-started/zowe-security-overview.md @@ -49,8 +49,7 @@ Review digital certificates terminology in the [Zowe security glossary](../appen Zowe uses digital certificates to secure the communication channel between Zowe components as well as between Zowe clients and Zowe services. Digital client certificates can also be used to validate that the identity of a client-user (the service user) is known to the mainframe security facility. **Next Steps:** -- For more information about the mechanics of digital certificate, see [Using certificates](../user-guide/use-certificates.md). -- To learn more about the various options for Zowe certificate configuration, see [Zowe certificate configuration overview](../user-guide/configure-certificates.md) under the _Use_ tab. +- To learn more about the various options for Zowe certificate configuration, see [Zowe certificate configuration overview](../user-guide/configure-certificates.md). ## User Authentication Zowe always authenticates the users accessing its interfaces and services. diff --git a/docs/user-guide/zos-components-installation-checklist-dev.md b/docs/user-guide/zos-components-installation-checklist-dev.md index be2e16bc48..ba883e9005 100644 --- a/docs/user-guide/zos-components-installation-checklist-dev.md +++ b/docs/user-guide/zos-components-installation-checklist-dev.md @@ -28,7 +28,7 @@ Use one of the following installation options to install Zowe z/OS components. | Task | Results | Time Estimate | |--------------------|----|------| -| Zowe is able to use PKCS12 certificates or certificates held in a z/OS Keyring.

Read the article [Zowe certificate configuration overview](../user-guide/configure-certificates.md). Then use one of the following options:

**Option 1:** Review [Zowe certificates configuration questionnaire](../user-guide/certificates-configuration-questionnaire.md) and [certificate configuration scenarios](../user-guide/certificate-configuration-scenarios.md) to determine which scenario best applies to your use case.
Once you have imported or generated a certificate, see [Use certificates](../user-guide/use-certificates.md).
**Option 2:** [Set up Zowe certificates using workflows](../user-guide/certificates-setup.md) | Your certificates are configured and stored securely|2 hours +| Zowe is able to use PKCS12 certificates or certificates held in a z/OS Keyring.

Read the article [Zowe certificate configuration overview](../user-guide/configure-certificates.md). Then use one of the following options:

**Option 1:** Review [Zowe certificates configuration questionnaire](../user-guide/certificates-configuration-questionnaire.md) and [certificate configuration scenarios](../user-guide/certificate-configuration-scenarios.md) to determine which scenario best applies to your use case.
Once you have imported or generated a certificate, see [Finalize Certificate Configuration](../user-guide/certificates-finalize-configuration.md).
**Option 2:** [Set up Zowe certificates using workflows](../user-guide/certificates-workflow-setup.md) | Your certificates are configured and stored securely|2 hours ## Starting and Stopping Zowe From 143ce6b1214d11e4abf1e9a64b87cc7fc9c9e1a8 Mon Sep 17 00:00:00 2001 From: Mark Ackert <35308966+MarkAckert@users.noreply.github.com> Date: Mon, 2 Feb 2026 13:22:30 -0500 Subject: [PATCH 18/26] Update docs/user-guide/configuring-at-tls-for-zowe-server-single-service.md Co-authored-by: anaxceron Signed-off-by: Mark Ackert <35308966+MarkAckert@users.noreply.github.com> --- .../configuring-at-tls-for-zowe-server-single-service.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/configuring-at-tls-for-zowe-server-single-service.md b/docs/user-guide/configuring-at-tls-for-zowe-server-single-service.md index 70dca49465..594d226daa 100644 --- a/docs/user-guide/configuring-at-tls-for-zowe-server-single-service.md +++ b/docs/user-guide/configuring-at-tls-for-zowe-server-single-service.md @@ -8,7 +8,7 @@ Configuring AT-TLS allows Zowe to offload all TLS responsibilities to the z/OS C This article explains how to enable AT-TLS for single-service deployment mode so your Zowe environment can benefit from this streamlined, system-driven approach to secure communications. :::tip -Beginning with Zowe v3.4.0 and for later versions, we recommend the use of single-service deployment mode. For the benefits of running Zowe in this mode, see [Enabling Single-Service deployment of API Mediation Layer](api-mediation/api-mediation-modulith.md). +Beginning with Zowe v3.4.0 and for later versions, it is recommend to use single-service deployment mode. For the benefits of running Zowe in this mode, see [Enabling Single-Service deployment of API Mediation Layer](api-mediation/api-mediation-modulith.md). ::: :::note From 871324a6f1817c7d4309fcb0e74079ab108b89e2 Mon Sep 17 00:00:00 2001 From: Mark Ackert <35308966+MarkAckert@users.noreply.github.com> Date: Mon, 2 Feb 2026 13:22:39 -0500 Subject: [PATCH 19/26] Update docs/user-guide/certificates-trust-off-platform.md Co-authored-by: anaxceron Signed-off-by: Mark Ackert <35308966+MarkAckert@users.noreply.github.com> --- docs/user-guide/certificates-trust-off-platform.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/certificates-trust-off-platform.md b/docs/user-guide/certificates-trust-off-platform.md index 0cc37dfe61..322912f13d 100644 --- a/docs/user-guide/certificates-trust-off-platform.md +++ b/docs/user-guide/certificates-trust-off-platform.md @@ -72,7 +72,7 @@ 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. +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 might incur a cost payable to the publicly trusted CA. ::: From cbb433796a03d8275183e2bd5ff6ce9c7e304f3b Mon Sep 17 00:00:00 2001 From: Mark Ackert <35308966+MarkAckert@users.noreply.github.com> Date: Mon, 2 Feb 2026 13:23:34 -0500 Subject: [PATCH 20/26] Update docs/user-guide/certificates-trust-off-platform.md Co-authored-by: anaxceron Signed-off-by: Mark Ackert <35308966+MarkAckert@users.noreply.github.com> --- docs/user-guide/certificates-trust-off-platform.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/certificates-trust-off-platform.md b/docs/user-guide/certificates-trust-off-platform.md index 322912f13d..b6fb1210d9 100644 --- a/docs/user-guide/certificates-trust-off-platform.md +++ b/docs/user-guide/certificates-trust-off-platform.md @@ -94,7 +94,7 @@ Steps are verified with Ubuntu 20.04.6 LTS. `$ 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). +3. Verify that the new expected certificate was added (the newest certificate is at the bottom of the list which contains an extended list of concatenated CAs). `$ cat /etc/ssl/certs/ca-certificates.crt` From 31b9289d4684519c15b530cbe17b3bfd4f84541c Mon Sep 17 00:00:00 2001 From: Mark Ackert <35308966+MarkAckert@users.noreply.github.com> Date: Mon, 2 Feb 2026 13:23:45 -0500 Subject: [PATCH 21/26] Update docs/user-guide/certificates-trust-off-platform.md Co-authored-by: anaxceron Signed-off-by: Mark Ackert <35308966+MarkAckert@users.noreply.github.com> --- docs/user-guide/certificates-trust-off-platform.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/certificates-trust-off-platform.md b/docs/user-guide/certificates-trust-off-platform.md index b6fb1210d9..3351401345 100644 --- a/docs/user-guide/certificates-trust-off-platform.md +++ b/docs/user-guide/certificates-trust-off-platform.md @@ -62,7 +62,7 @@ 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: +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 */ From e1c4ec0a438f896c2be79d744230a91a42afa926 Mon Sep 17 00:00:00 2001 From: MarkAckert <35308966+MarkAckert@users.noreply.github.com> Date: Mon, 2 Feb 2026 13:27:05 -0500 Subject: [PATCH 22/26] add admonition Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> --- docs/user-guide/certificates-trust-off-platform.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/user-guide/certificates-trust-off-platform.md b/docs/user-guide/certificates-trust-off-platform.md index 3351401345..09c96090cb 100644 --- a/docs/user-guide/certificates-trust-off-platform.md +++ b/docs/user-guide/certificates-trust-off-platform.md @@ -39,7 +39,9 @@ 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. +:::note +Ensure that you open the terminal as **administrator**. This operation installs the certificate to the Trusted Root Certification Authorities. +::: From 2a0f1c4c46ffe336f0cc54f6b7816bcfa6fbd859 Mon Sep 17 00:00:00 2001 From: MarkAckert <35308966+MarkAckert@users.noreply.github.com> Date: Mon, 2 Feb 2026 14:00:02 -0500 Subject: [PATCH 23/26] changes from code review comments Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> --- .../configuration-client-certificates.md | 2 +- .../certificates-configuration-scenarios.md | 69 ++++++++++--------- .../certificates-finalize-configuration.md | 8 +-- .../certificates-trust-off-platform.md | 10 +-- 4 files changed, 45 insertions(+), 44 deletions(-) diff --git a/docs/user-guide/api-mediation/configuration-client-certificates.md b/docs/user-guide/api-mediation/configuration-client-certificates.md index 98db77b030..1fa6a3a6b6 100644 --- a/docs/user-guide/api-mediation/configuration-client-certificates.md +++ b/docs/user-guide/api-mediation/configuration-client-certificates.md @@ -105,7 +105,7 @@ The following steps are only required if the ZSS hostname or default Zowe user n ::: * **components.gateway.apiml.security.x509.externalMapperUser** - To authenticate to the mapping API, a JWT is sent with the request. The token represents the user that is configured with this property. The user authorization is required to use the `IRR.RUSERMAP` resource within the `FACILITY` class. The default value is `ZWESVUSR`. Permissions are set up during installation with the `ZWESECUR` JCL or workflow. + To authenticate to the mapping API, a JWT is sent with the request. The token represents the user that is configured with this property. The user authorization is required to use the `IRR.RUSERMAP` resource within the `FACILITY` class. The default value is: `ZWESVUSR`. Permissions are set up during installation with the `ZWESECUR` JCL or workflow. If you customized the `ZWESECUR` JCL or workflow (the customization of zowe runtime user: `// SET ZOWEUSER=ZWESVUSR * userid for Zowe started task`) and changed the default USERID, create the `components.gateway.apiml.security.x509.externalMapperUser` property and set the value by adding a new line as in the following example: diff --git a/docs/user-guide/certificates-configuration-scenarios.md b/docs/user-guide/certificates-configuration-scenarios.md index 200a43c2ee..5bf8006f76 100644 --- a/docs/user-guide/certificates-configuration-scenarios.md +++ b/docs/user-guide/certificates-configuration-scenarios.md @@ -7,10 +7,10 @@ After you have completed the [Zowe certificates configuration questionnaire](./c Zowe servers require both a keystore to store the certificates and a truststore to validate certificates. -Zowe's assisted certificate setup begins with customizing certificate scenario YAML files found in the `files/examples/setup/certificate` sub-directory within your Zowe installation directory. Zowe will then use these scenario configurations and complete certificate setup via the `zwe init certificate` command. +Zowe's assisted certificate setup begins with customizing certificate scenario YAML files found in the `files/examples/setup/certificate` sub-directory within your Zowe installation directory. Zowe then uses these scenario configurations and complete certificate setup via the `zwe init certificate` command. :::note -Reminder: Zowe assisted generation of certificates is an option, but is not required. If you already have certificates and a key ring or keystore / truststore combination you created on your own, you can instead go to [Finalize certificate configuration](./certificates-finalize-configuration.md). +Reminder: Zowe assisted generation of certificates is an option, but is not required. If you already have certificates and a key ring or keystore/truststore combination you created on your own, you can instead go to [Finalize certificate configuration](./certificates-finalize-configuration.md). ::: ## What is a valid certificate in Zowe? @@ -32,19 +32,19 @@ Each scenario described in this article provides the configuration details via c * [Scenario 5: Use a z/OS keyring-based keystore and import a certificate stored in a data set](#scenario-5-use-a-zos-keyring-based-keystore-and-import-a-certificate-stored-in-a-data-set) :::note -Ensure that all certificate alias values for all scenarios use only lower-case. +Ensure that all certificate alias values for all scenarios use only lowercase. ::: ## Running a scenario file -Zowe supplies 5 certificate scenario YAML files in the `files/examples/setup/certificate` sub-directory within your Zowe installation directory. The scenario section below describes what each scenario will accomplish, and how to complete customization of the respective scenario YAML files. Once you have selected and finished configuring one of these scenarios, follow the below instructions to execute the scenario. +Zowe supplies five certificate scenario YAML files in the `files/examples/setup/certificate` sub-directory within your Zowe installation directory. The scenario section below describes what each scenario accomplishes, and how to complete customization of the respective scenario YAML files. Once you have selected and finished configuring one of these scenarios, follow the below instructions to execute the scenario.
Run scenario YAML with configmgr -1. Identify the fully-qualified path to your selected scenario YAML configuration file. In this example, we will use `/path/to/files/examples/setup/certificate/scenario-1.yaml`. +1. Identify the fully-qualified path to your selected scenario YAML configuration file. In this example, we use `/path/to/files/examples/setup/certificate/scenario-1.yaml`. -2. Identify the fully-qualified path to your main `zowe.yaml` configuration file. In this example, we will use `/path/to/zowe.yaml`. +2. Identify the fully-qualified path to your main `zowe.yaml` configuration file. In this example, we use `/path/to/zowe.yaml`. 3. Create the following configuration parameter, replacing our example paths with your real ones: ``` @@ -53,7 +53,7 @@ Zowe supplies 5 certificate scenario YAML files in the `files/examples/setup/cer 4. Navigate to your Zowe installation root directory. -4. Submit `./bin/zwe init certificate` using the configuration parameter from Step 3. Note the quotation marks surrounding the configuration parameter! If you are running Scenario 3, 4, or 5, you can add `--dry-run` to the command and review the JCL used to create the keyring before submission. +5. Issue `./bin/zwe init certificate` using the configuration parameter from Step 3. Note the quotation marks surrounding the configuration parameter! If you are running Scenario 3, 4, or 5, you can add `--dry-run` to the command and review the JCL used to create the keyring before submission. ```shell ./bin/zwe init certificate --update-config -c "FILE(/path/to/files/examples/setup/certificate/scenario-1.yaml):FILE(/path/to/zowe.yaml)" @@ -77,9 +77,9 @@ zowe: details> Append scenario YAML contents to main zowe.yaml -1. Identify the fully-qualified path to your selected scenario YAML configuration file. In this example, we will use `/path/to/files/examples/setup/certificate/scenario-1.yaml`. +1. Identify the fully-qualified path to your selected scenario YAML configuration file. In this example, we use `/path/to/files/examples/setup/certificate/scenario-1.yaml`. -2. Identify the fully-qualified path to your main `zowe.yaml` configuration file. In this example, we will use `/path/to/zowe.yaml`. +2. Identify the fully-qualified path to your main `zowe.yaml` configuration file. In this example, we use `/path/to/zowe.yaml`. 3. Make a manual backup of your `zowe.yaml` file before modification. @@ -91,7 +91,7 @@ details> If you make changes to your scenario.yaml configuration file after this step or if you decide on a different certificate scenario, you should either modify the appended values in your `zowe.yaml` file directly, or restore `zowe.yaml` from your backup in Step 3 and re-run Step 4. ::: -5. Submit `init certificate` using your `zowe.yaml` file. +5. Issue `init certificate` using your `zowe.yaml` file. ``` zwe init certificate -c /path/to/zowe.yaml --update-config ``` @@ -99,12 +99,12 @@ If you make changes to your scenario.yaml configuration file after this step or
--> :::tip -If you encounter issues when configuring your certificate, see [Troubleshooting the certificate configuration](../troubleshoot/troubleshoot-zos-certificate.md), to find resolution of errors. +If you encounter issues when configuring your certificate, see [Troubleshooting the certificate configuration](../troubleshoot/troubleshoot-zos-certificate.md) to find resolution of errors. ::: ## Scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates -Follow this procedure and configure `scenario-1.yaml` within the `files/examples/setup/certificate` directory to enable Zowe to use newly generated PKCS12 certificates stored in a USS directory. These certificates will be signed by a newly created, self-signed Certificate Authority. As such, this is not recommended for production environments. +Follow this procedure and configure `scenario-1.yaml` within the `files/examples/setup/certificate` directory to enable Zowe to use newly generated PKCS12 certificates stored in a USS directory. These certificates are signed by a newly created, self-signed Certificate Authority. As such, this is not recommended for production environments.
Click here for details. @@ -115,17 +115,17 @@ In your `scenario-1.yaml` configuration file: ```yaml directory: /var/zowe/keystore ``` -2. Customize the certificate alias name. The default value is `localhost`. -3. Set the keystore password. The default value is `password`. +2. Customize the certificate alias name. The default value is: `localhost`. +3. Set the keystore password. The default value is: `password`. 4. (Optional) Uncomment the lock field, which locks the keystore directory so it is accessible only to the Zowe runtime user and group: ```yaml lock: true ``` -5. (Optional) Set the alias name of certificate authority. The default value is `local_ca`. +5. (Optional) Set the alias name of certificate authority. The default value is: `local_ca`. ```yaml caAlias: local_ca ``` -6. (Optional) Set the password of the keystore stored certificate authority. The default value is `local_ca_password`. +6. (Optional) Set the password of the keystore stored certificate authority. The default value is: `local_ca_password`. ```yaml caPassword: local_ca_password ``` @@ -156,7 +156,7 @@ In your `scenario-1.yaml` configuration file: To get the san IP address, run `ping dvipa.my-company.com` in your terminal. ::: - **Example scenario-1 yaml file:** + **Example scenario-1 YAML file:** ```yaml zowe: @@ -183,7 +183,7 @@ zowe: - dvipa.my-company.com - 12.34.56.78 ``` -Your yaml file is now configured to enable Zowe to use generated PKCS12 certificates. You can now go to [Running a scenario file](#running-a-scenario-file). +Your YAML file is now configured to enable Zowe to use generated PKCS12 certificates. You can now go to [Running a scenario file](#running-a-scenario-file). The following command output shows the generation of a PKCS12 keystore using the default values, and has the following associated artifacts. (Note that some detailed output messages have been omitted.) @@ -226,11 +226,11 @@ The following command output shows the generation of a PKCS12 keystore using the #> ``` -You are ready to [Finalize your Zowe Certificate Configuration](./certificates-finalize-configuration.md). +You are ready to [Finalize your Zowe certificate configuration](./certificates-finalize-configuration.md). ::note -For more information about using a file-based PKCS12 certificate in Zowe services, see the [video tutorials](https://www.youtube.com/playlist?list=PL8REpLGaY9QERUmM--1USMF8yOG-Awzwn) on YouTube. More information about this certificate configuration scenario is also available in [this Medium blog post](https://medium.com/zowe/step-by-step-guide-use-a-pkcs12-file-based-keystore-with-zowe-generated-certificate-365dc48eea29). Both of these resources target an older release of Zowe and modify `zowe.yaml` directly, so you'll need to adapt some of their configuration to your `scenario-1.yaml` configuration file instead. +For more information about using a file-based PKCS12 certificate in Zowe services, see the [video tutorials](https://www.youtube.com/playlist?list=PL8REpLGaY9QERUmM--1USMF8yOG-Awzwn) on YouTube. More information about this certificate configuration scenario is also available in [this Medium blog post](https://medium.com/zowe/step-by-step-guide-use-a-pkcs12-file-based-keystore-with-zowe-generated-certificate-365dc48eea29). Both of these resources target an older release of Zowe and modify `zowe.yaml` directly, so you will need to adapt some of their configuration to your `scenario-1.yaml` configuration file instead. ::
@@ -251,7 +251,7 @@ Follow this procedure and configure `scenario-2.yaml` within the `files/examples ```yaml lock: true ``` -4. Set keystore password. The default value is `password`. +4. Set keystore password. The default value is: `password`. 5. Set the existing PKCS12 keystore which holds the certificate issued by an external CA. ```yaml keystore: "" @@ -300,7 +300,7 @@ Due to the limitation of the RACDCERT command, the `importCertificateAuthorities ::: -Your yaml file is now configured to enable Zowe to use a file-based PKCS12 keystore to import a certificate generated by another CA. You can now go to [Running a scenario file](#running-a-scenario-file). +Your YAML file is now configured to enable Zowe to use a file-based PKCS12 keystore to import a certificate generated by another CA. You can now go to [Running a scenario file](#running-a-scenario-file). @@ -323,11 +323,11 @@ Follow this procedure and configure `scenario-3.yaml` within the `files/examples ```yaml name: ZoweKeyring ``` - * Label of Zowe certificate. The default value is `localhost`. + * Label of Zowe certificate. The default value is: `localhost`. ```yaml label: localhost ``` - * Label of Zowe CA certificate. The default value is `localca`. + * Label of Zowe CA certificate. The default value is: `localca`. ```yaml caLabel: localca ``` @@ -378,7 +378,7 @@ Due to the limitation of the `RACDCERT` command, this field should contain exact - 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. You can now go to [Running a scenario file](#running-a-scenario-file). +Your YAML file is now configured to enable Zowe to use a z/OS keyring-based keystore with Zowe generated certificates. You can now go to [Running a scenario file](#running-a-scenario-file). The following command output shows the generation of a JCERACFKS certificate using the default values. Note that some detailed output messages have been omitted. @@ -440,7 +440,7 @@ Follow this procedure and configure `scenario-4.yaml` within the `files/examples - "" ``` :::note -Due to the limitation of `RACDCERT` command, this field should contain a maximum of 2 entries. +Due to the limitation of `RACDCERT` command, this field should contain a maximum of two entries. ::: **Example zowe yaml for scenario 4:** @@ -459,20 +459,21 @@ zowe: - "zOSMFCA" ``` -Your yaml file is now configured to enable Zowe to use a z/OS keyring-based keystore with Zowe generated certificates. You can now go to [Running a scenario file](#running-a-scenario-file). +Your YAML file is now configured to enable Zowe to use a z/OS keyring-based keystore with Zowe generated certificates. You can now go to [Running a scenario file](#running-a-scenario-file). 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](https://medium.com/zowe/master-zowe-certificates-use-an-existing-jceracfks-certificate-for-zowes-z-os-components-975ffa0d9f2f), or the video tutorials in [this YouTube playlist](https://www.youtube.com/playlist?list=PL8REpLGaY9QEHLNA81DRgGqWcgOYC0PDX). **Example:** ![Alt text](../images/certificates/connect-JCERACFKS.png) -**Note:** -In this example, the command `zwe init certificate -c ./zowe.yaml --security-dry-run` allows the JCL to be inspected before submission, as well as handed off to a security administrator who has privileges to submit the JCL under their user ID. By default, the JCL id submitted immediately. +:::note +In this example, the command `zwe init certificate -c ./zowe.yaml --security-dry-run` allows the JCL to be inspected before submission, as well as handed off to a security administrator who has privileges to submit the JCL under their user ID. By default, the JCL is submitted immediately. +::: 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 `ZoweKeyringZOSMF` with your own key ring name. +* Replace `IZUSVR` with the user name that 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. @@ -480,7 +481,7 @@ If you would like to use this example in your Zowe configuration YAML file, repl ## Scenario 5: Use a z/OS keyring-based keystore and import a certificate stored in a data set -Follow this procedure and configure `scenario-5.yaml` within the `files/examples/setup/certificate` directory to enable Zowe to import existing certificates from a dataset into a z/OS keyring-based keystore. +Follow this procedure and configure `scenario-5.yaml` within the `files/examples/setup/certificate` directory to enable Zowe to import existing certificates from a data set into a z/OS keyring-based keystore.
Click here for details. @@ -498,7 +499,7 @@ Follow this procedure and configure `scenario-5.yaml` within the `files/examples ```yaml name: ZoweKeyring ``` - * Label of Zowe certificate. The default value is `localhost`. + * Label of Zowe certificate. The default value is: `localhost`. ```yaml label: localhost ``` @@ -526,7 +527,7 @@ zowe: password: "" ``` -Your yaml file is now configured to use a z/OS keyring-based keystore and import a certificate stored in a data set. You can now go to [Running a scenario file](#running-a-scenario-file). +Your YAML file is now configured to use a z/OS keyring-based keystore and import a certificate stored in a data set. You can now go to [Running a scenario file](#running-a-scenario-file).
diff --git a/docs/user-guide/certificates-finalize-configuration.md b/docs/user-guide/certificates-finalize-configuration.md index 26d314542c..74c0669350 100644 --- a/docs/user-guide/certificates-finalize-configuration.md +++ b/docs/user-guide/certificates-finalize-configuration.md @@ -13,7 +13,7 @@ Choose from the following procedures: When Zowe is launched, details about the PKCS12 certificates are found in the `zowe.yaml` file's `zowe.certificate` section. This configuration block contains information about the certificate name and the location of the certificate, together with the keystore and truststore location. -If you have used [Zowe Assisted Certificate Setup](./certificates-configuration-scenarios.md) with `--update-config`, the `zowe.certificate` section should be filled out correctly for you. If you did not use `--update-config`, or are bringing your own PKCS12 certificates, then customize your `zowe.yaml` file's `zowe.certificate` section using this guide: +If you have used [Zowe assisted certificate setup](./certificates-configuration-scenarios.md) with `--update-config`, the `zowe.certificate` section should be filled out correctly for you. If you did not use `--update-config`, or are bringing your own PKCS12 certificates, then customize your `zowe.yaml` file's `zowe.certificate` section using this guide: ```yaml zowe: @@ -45,7 +45,7 @@ Manually review that all the values you provided are correct: * The certificate alias is correct and exists in the provided keystore. * All file locations are accessible by your Zowe runtime user. -After manual review, you are ready to start Zowe with your certificate configuration. When Zowe starts, it will perform another series of verifications against your configuration and alert you in the job output if there are any problems. +After manual review, you are ready to start Zowe with your certificate configuration. When Zowe starts, it performs another series of verifications against your configuration and alerts you in the job output if there are any problems. ## Review key ring certificate configuration @@ -55,7 +55,7 @@ If you have used Zowe Assisted Certificate Setup with `--update-config`, the `zo If you are using AT-TLS with Zowe, consult the [Enabling AT-TLS for single-service deployment mode](./configuring-at-tls-for-zowe-server-single-service.md) article before proceeding. The key ring you define in your AT-TLS configuration should be the key ring you supply in the below guide. -If you want to use ICSF-backed private keys, consult the [Using ICSF Hardware Private Keys](./using-icsf-hardware-private-keys.md) article before proceeding. As mentioned in that article, ensure you are using `JCEHYBRIDRACFKS` as you follow the below example. +If you want to use ICSF-backed private keys, consult the [Using ICSF hardware private keys](./using-icsf-hardware-private-keys.md) article before proceeding. As mentioned in that article, ensure you are using `JCEHYBRIDRACFKS` as you follow the below example. :::note If there is a `zowe.certificate.pem` section, remove it from your `zowe.yaml` file. ::: @@ -85,4 +85,4 @@ Manually review that all the values you provided are correct: * The certificate alias is correct and exists in the provided keyring. * The keyring is accessible by your Zowe runtime user. -After manual review, you are ready to start Zowe with your certificate configuration. When Zowe starts, it will perform another series of verifications against your configuration and alert you in the job output if there are any problems. \ No newline at end of file +After manual review, you are ready to start Zowe with your certificate configuration. When Zowe starts, it performs another series of verifications against your configuration and alerts you in the job output if there are any problems. \ No newline at end of file diff --git a/docs/user-guide/certificates-trust-off-platform.md b/docs/user-guide/certificates-trust-off-platform.md index 09c96090cb..bc63e247b1 100644 --- a/docs/user-guide/certificates-trust-off-platform.md +++ b/docs/user-guide/certificates-trust-off-platform.md @@ -1,8 +1,8 @@ # Trusting certificates off platform -Zowe services are protected by the certificates you set in your `zowe.yaml` configuration file, and these certificates are presented to all clients connecting to Zowe, including off-platform clients. If you are using your browser to view Zowe's API Mediation Layer or Web Desktop, or if you are using Zowe Explorer with an API Mediation Layer connection profile, the certificate Zowe presents may be challenged by your browser or operating system. This article covers a common method for trusting certificates: importing them in your off-platform client environment. +Zowe services are protected by the certificates you set in your `zowe.yaml` configuration file, and these certificates are presented to all clients connecting to Zowe, including off-platform clients. If you are using your browser to view Zowe's API Mediation Layer or Web Desktop, or if you are using Zowe Explorer with an API Mediation Layer connection profile, the certificate Zowe presents might be challenged by your browser or operating system. This article covers a common method for trusting certificates: importing them in your off-platform client environment. -## Importing a certificate Authority (CA) +## 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. @@ -13,13 +13,13 @@ Importing a certificate authority (CA) is a prerequisite to importing a PKCS12 c 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. +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 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 the certificate was generated on z/OS, 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. + If a SAF keyring is used and the certificate was generated on z/OS, the procedure to obtain the certificate does not apply. In this case, it is recommended that you work with your security system administrator to obtain the certificate. ::: -The public certificate in [PEM format](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) 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. +The public certificate in [PEM format](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) is stored in a USS directory and 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`. From cd1f5fec16d48792e4f08623074f7b07c4abee0c Mon Sep 17 00:00:00 2001 From: MarkAckert <35308966+MarkAckert@users.noreply.github.com> Date: Mon, 2 Feb 2026 14:01:24 -0500 Subject: [PATCH 24/26] one more suggested change Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> --- docs/user-guide/certificates-configuration-scenarios.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/certificates-configuration-scenarios.md b/docs/user-guide/certificates-configuration-scenarios.md index 5bf8006f76..96eca2d49e 100644 --- a/docs/user-guide/certificates-configuration-scenarios.md +++ b/docs/user-guide/certificates-configuration-scenarios.md @@ -57,7 +57,7 @@ Zowe supplies five certificate scenario YAML files in the `files/examples/setup/ ```shell ./bin/zwe init certificate --update-config -c "FILE(/path/to/files/examples/setup/certificate/scenario-1.yaml):FILE(/path/to/zowe.yaml)" - # If you are using scenarios 3, 4, or 5, this will print JCL to the console for review + # If you are using scenarios 3, 4, or 5, this prints JCL to the console for review ./bin/zwe init certificate --dry-run --update-config -c "FILE(/path/to/files/examples/setup/certificate/scenario-1.yaml):FILE(/path/to/zowe.yaml)" ``` From db102ac6a8aaad98ab6222faacf2c759fb6ef105 Mon Sep 17 00:00:00 2001 From: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com> Date: Tue, 3 Feb 2026 17:16:18 +0100 Subject: [PATCH 25/26] Keyring to key ring Corrected formatting of bullet points for clarity. Signed-off-by: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com> --- docs/user-guide/certificates-finalize-configuration.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/certificates-finalize-configuration.md b/docs/user-guide/certificates-finalize-configuration.md index 74c0669350..3353456483 100644 --- a/docs/user-guide/certificates-finalize-configuration.md +++ b/docs/user-guide/certificates-finalize-configuration.md @@ -81,8 +81,8 @@ zowe: ``` Manually review that all the values you provided are correct: -* The keyring exists. -* The certificate alias is correct and exists in the provided keyring. -* The keyring is accessible by your Zowe runtime user. +* The key ring exists. +* The certificate alias is correct and exists in the provided key ring. +* The key ring is accessible by your Zowe runtime user. -After manual review, you are ready to start Zowe with your certificate configuration. When Zowe starts, it performs another series of verifications against your configuration and alerts you in the job output if there are any problems. \ No newline at end of file +After manual review, you are ready to start Zowe with your certificate configuration. When Zowe starts, it performs another series of verifications against your configuration and alerts you in the job output if there are any problems. From 0800dcffdfa2f4631a064607b295415dabf3d558 Mon Sep 17 00:00:00 2001 From: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com> Date: Tue, 3 Feb 2026 17:19:53 +0100 Subject: [PATCH 26/26] Typos Signed-off-by: Martin Zeithaml <66114686+Martin-Zeithaml@users.noreply.github.com> --- docs/user-guide/certificates-trust-off-platform.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/certificates-trust-off-platform.md b/docs/user-guide/certificates-trust-off-platform.md index bc63e247b1..80e89b2824 100644 --- a/docs/user-guide/certificates-trust-off-platform.md +++ b/docs/user-guide/certificates-trust-off-platform.md @@ -16,7 +16,7 @@ To avoid the browser untrusted CA challenge, import Zowe certificates into the b 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 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 the certificate was generated on z/OS, the procedure to obtain the certificate does not apply. In this case, it is recommended that you work with your security system administrator to obtain the certificate. + If a SAF key ring is used and the certificate was generated on z/OS, the procedure to obtain the certificate does not apply. In this case, it is recommended that you work with your security system administrator to obtain the certificate. ::: The public certificate in [PEM format](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) is stored in a USS directory and 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. @@ -58,7 +58,7 @@ $ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.ke
-For Firefox, click here for command deails. +For Firefox, click here for command details. Manually import your root certificate via the Firefox settings, or force Firefox to use the Windows truststore.