Skip to content

Commit

Permalink
Merge pull request #3758 from zowe/janan07-add-config-note-to-earlier…
Browse files Browse the repository at this point in the history 
…-versions

update cert config file for previous versions
  • Loading branch information
@janan07
janan07 authored Jul 10, 2024
2 parents ce392a3 + a3b2f30 commit 64518b7
Show file tree
Hide file tree
Showing 5 changed files with 331 additions and 96 deletions.
143 changes: 107 additions & 36 deletions versioned_docs/version-v2.10.x/user-guide/certificate-configuration-scenarios.md
View file
Original file line number Diff line number Diff line change
@@ -1,44 +1,66 @@
# Certificate configuration scenarios
# Certificate configuration scenarios

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

Zowe servers require both a keystore to store the certificates as well as a truststore to validate these certificates and any other certificates that are encountered.
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.

:::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 quetions that lead to a specific configuration scenario presented in this article.
:::

Zowe servers require both a keystore to store the certificates and a truststore to validate certificates.

For use of Zowe on z/OS, the keystore and truststore can either be Unix file-based (PKCS12) or z/OS keyring-based.

For use of Zowe on z/OS, keystore and truststore can either be unix file-based (PKCS12) or z/OS keyring-based.
Both the keystore and truststore can automatically be created by Zowe regardless of which storage type is used. Keystores and truststores can be populated either with certificates that the user chooses, or with self-signed certificates generated by Zowe.
This automation can be performed by defining and customizing the `zowe.setup.certificate` section of your Zowe YAML configuration.
Zowe can then automate the certificate setup via the `zwe init certificate` command. This command is run as a subcommand of `zwe init`.
Zowe can then automate the certificate setup via the `zwe init certificate` command.


**Note:**
Automated generation of certificates is an option, but is not required. If you already have a keystore that contains a valid certificate`*`, and the certificate's corresponding private key, along with a truststore which validates the certificate and any other certificates you expect to encounter, then you also have the option of directly defining the parameter `zowe.certificate` which specifies the location of each of these objects. Note that this parameter should not be confused with the parameter `zowe.setup.certificate`.
:::note
Automated generation of certificates is an option, but is not required. If you already have a keystore that contains a valid certificate <b>*</b>, and the corresponding private key of the certificate, along with a truststore which validates the certificate and any other certificates you expect to encounter, then you also have the option to directly define the parameter `zowe.certificate`, which specifies the location of each of these certificates and their storage objects. Note that this parameter should not be confused with the parameter `zowe.setup.certificate`.
:::

## `*` What is a valid certificate in Zowe?
## <b>*</b> What is a valid certificate in Zowe?

A valid certificate for use in Zowe is required to have one of the following attributes, regardless of the format:
A valid certificate for use in Zowe conforms to one of the following two options:

* A certificate that does not contain the _Extended Key Usage_ section.
* A certificate that contains the _Extended Key Usage_ section and also includes the "Server" and "Client" authentication fields.
* 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

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

* Will you be using file-based (PKCS12) certificates, or z/OS keyrings?
* Will you be letting Zowe create self-signed certificates, or will Zowe be using pre-made certificates which you are providing?
* Do you plan to use a file-based (PKCS12) certificates, or z/OS keyrings?
* Do you plan to enable Zowe to create self-signed certificates, or will Zowe be using pre-made certificates which you are providing?
* If you are providing certificates to Zowe and using a keyring, does the certificate already exist in your security database, or are you importing it via a dataset?

There are five scenarios/use cases for configuring certificates.
Use the applicable certificate configuration scenario according to your needs.

Each scenario described in this article provides the configuration details via code snippets which you can use to edit your Zowe YAML configuration within the `zowe.setup.certificate` section.

* [Scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates](#scenario-1-use-a-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-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-with-zowe-generated-certificates)
* [Scenario 4: Use a z/OS keyring-based keystore and connect an existing certificate](#scenario-4-use-a-zos-keyring-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-and-import-a-certificate-stored-in-a-data-set)
* [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)
* [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 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.

<details>
<summary>Click here for details.</summary>

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

2. Customize the keystore directory in the following format:
Expand All @@ -50,10 +72,8 @@ Each scenario described in this article provides the configuration details via c
lock: true
```
4. Customize the certificate alias name. The default value is `localhost`.
**Note:** Use all lower case as an alias.
5. Set keystore password. Customizing this value is highly recommended. The default value is `password`.
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`.
**Note:** Use all lower case as an alias.
```
caAlias: local_ca
```
Expand Down Expand Up @@ -85,6 +105,14 @@ Each scenario described in this article provides the configuration details via c
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:**

Expand All @@ -110,9 +138,19 @@ Each scenario described in this article provides the configuration details via c
- system.my-company.com
- 12.34.56.78
```
Your yaml file is now configured to enable Zowe to use generated PKCS12 certificates.

For more information about using a file-based PKCS12 certificate in Zowe services, see the [video tutorials](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).

</details>

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

<details>
<summary>Click here for details.</summary>

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

2. Customize the keystore directory in the following format:
Expand All @@ -124,27 +162,30 @@ Each scenario described in this article provides the configuration details via c
lock: true
```
4. Customize the certificate alias name. The default value is `localhost`.
**Note:** Use all lower case as an alias.
5. Set keystore password. The default value is `password`.
6. Set the existing PKCS12 keystore which holds the certificate issued by an external CA.
```
keystore: ""
keystore: "<your-keystore-value>"
```

7. Set the password of the keystore set in step 6.
```
password: ""
password: "<your-password-value>"
```

8. Specify the alias of the certificate to be imported.
```
alias: ""
```
**Note:** Use all lower cases as an alias.
alias: "<your-alias-value>"
```

9. Set the path to the certificate authority that signed the certificate to be imported.
```
importCertificateAuthorities:
```
**Note:** PEM format certificate authorities can be imported and trusted.

:::note
PEM format certificate authorities can be imported and trusted.
:::

**Example zowe yaml for scenario 2 (PKCS12):**

Expand All @@ -164,9 +205,17 @@ Each scenario described in this article provides the configuration details via c
- /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.

</details>

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

<details>
<summary>Click here for details.</summary>

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

* JCEKS
Expand Down Expand Up @@ -215,7 +264,9 @@ this field is not defined, the `zwe init` command uses the value `zowe.externalD
- dvipa.my-company.com
- 12.34.56.78
```
**Note**: Due to the limitation of the `RACDCERT` command, this field should contain exactly 2 entries with the domain name and IP address.
:::note
Due to the limitation of the `RACDCERT` command, this field should contain exactly two entries with the domain name and IP address.
:::

**Example zowe yaml for scenario 3:**

Expand All @@ -238,9 +289,17 @@ this field is not defined, the `zwe init` command uses the value `zowe.externalD
- 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.

</details>

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

<details>
<summary>Click here for details.</summary>

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

* JCEKS
Expand All @@ -267,14 +326,14 @@ this field is not defined, the `zwe init` command uses the value `zowe.externalD
importCertificateAuthorities:
- ""
```
**Note:** Due to the limitation of `RACDCERT` command, this field should contain a maximum of 2 entries.
:::note
Due to the limitation of `RACDCERT` command, this field should contain a maximum of 2 entries.
:::

The following example uses an existing JCERACFKS certificate for Zowe's z/OS components. For more information about configuration in this scenario, see [this blog post](https://medium.com/zowe/master-zowe-certificates-use-an-existing-jceracfks-certificate-for-zowes-z-os-components-975ffa0d9f2f).
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:**



```
# >>>> Certificate setup scenario 4
# z/OS Keyring and connect to existing certificate
Expand All @@ -296,8 +355,17 @@ 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.

</details>

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

<details>
<summary>Click here for details.</summary>

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

* JCEKS
Expand All @@ -321,10 +389,10 @@ If you would like to use this example in your Zowe configuration YAML file, repl
```
dsName: ""
```
* The password for the PKS12 data set.
* The password for the PKCS12 data set.
```
password: ""
```
```
**Example zowe yaml for scenario 5:**

```
Expand All @@ -338,3 +406,6 @@ If you would like to use this example in your Zowe configuration YAML file, repl
dsName: PRODUCT.X.CERT.P12
password: password
```
Your yaml file is now configured to use a z/OS keyring-based keystore and import a certificate stored in a data set.

</details>
Loading

0 comments on commit 64518b7

Please sign in to comment.