Keyring support documentation

docs/user-guide/configure-certificates.md

@@ -1,39 +1,158 @@
 # Configuring Zowe certificates 
 
+To configure Zowe certificates, you can use one of the following methods.
+- [Configuring Zowe certificates in a key ring](#configuring-zowe-certificates-in-a-key-ring)
+- [Configuring Zowe certificates in UNIX files](#configuring-zowe-certificates-in-unix-files)
+
+## Configuring Zowe certificates in a key ring
+
+You can configure Zowe certificates in a key ring by using one of the following options. 
+
+- Customize and submit the ZWEKRING JCL and finalize the certificate configuration by executing the `zowe-setup-certificate.sh` script. 
+
+  - This option allows you to easily review all the security commands that generate certificates and manage the key ring. 
+  - You must customize the JCL before submitting it. 
+
+  For more information, see [Use ZWEKRING JCL and zowe-setup-certificate.sh](#zwekring-jcl-and-zowe-setup-certificatesh).
+
+- Use the `zowe-setup-certificate.sh` script only. 
+
+  - This is an identical flow as configuration of certificates in UNIX files keystores except that two new environment variables must be set in the `zowe-setup-certificates.env` file. 
+  - Caller of the `zowe-setup-certificate.sh` script must have appropriate permissions to the `IRR.DIGTCERT.*` resources. 
+  - This `zowe-setup-certificate.sh` script is common to security products RACF, Top Secret, and ACF2.
+  - Maintenance for ACF2 ([SO11887](https://support.broadcom.com/download-center/solution-detail.html?aparNo=SO11887&os=z%2FOS)) 
+    and Top Secret ([SOxxxxx]()) must be applied to ensure that this way works for ACF2 and Top Secret.
+
+  For more information, see [zowe-setup-certificate.sh script only](#zowe-setup-certificatesh-script-only).
+
+
+### ZWEKRING JCL and zowe-setup-certificate.sh
+
+<!--[//]: # "TODO keyring documentation - ZWEKRING JCL - describe what it does, describe how to work with 
+            it(self signed, externally signed certs), describe parts that could be confusing, 
+            connecting CA chain and z/osmf cert. Give an example of the keyring content" -->
+
+The ZWEKRING JCL helps you configure certificates in a key ring in the following scenarios: 
+ 1. The Zowe certificate is already stored in your security manager's database.
+ 2. The Zowe certificate is to be imported to security manager's database from a data set.
+ 3. The Zowe certificate is to be generated by the ZWEKRING JCL and signed by the local Zowe's CA.
+
+Do not submit the ZWEKRING JCL as is. You must customize it depending on the scenario for your environment.
+
+To customize the JCL, edit the JCL variables at the beginning of the JCL and carefully review and edit all the security commands that are valid for your security manager.
+
+**Important!**
+
+ - If you want APIML to verify certificates (for example, `VERIFY_CERTIFICATES=true` is set in the `zowe-setup-certificate.env` file), then the root CA of the z/OSMF certificate must be connected with the Zowe key ring. The ZWEKRING is ready for such a scenario.
+
+   You only need to set the `ROOTZFCA` variable in the ZWEKRING JCL. You can find the root CA by listing a chain of the z/OSMF certificate. For example,
+    - RACF 
+      ```
+      RACDCERT ID(IZUSVR) LISTCHAIN(LABEL('DefaultzOSMFCert.IZUDFLT'))
+      ```
+    - Top Secret
+      ```
+      TSS LIST(IZUSVR) LABLCERT('DefaultzOSMFCert.IZUDFLT') CHAIN
+      ``` 
+    - ACF2
+      ```
+      SET PROFILE(USER) DIVISION(CERTDATA)
+      CHKCERT IZUSVR LABEL(DefaultzOSMFCert.IZUDFLT) CHAIN
+      ``` 
+
+ - The Zowe certificate must be connected to the key ring together with its CA chain (all certificates in the chain). 
+
+   The ZWEKRING has two variables `ITRMZWCA` and `ROOTZWCA` and corresponding "connect to keyring" commands that support the scenario where the Zowe certificate has one intermediate CA and the root CA in its CA chain. If your Zowe certificate has no intermediate CA or has more than one intermediate CA, then you must add or remove the connecting commands accordingly.
+
+   To find out what the certificate's CA chain is, you can use the example commands in the previous note.
+
+   If Zowe certificate is self-signed or signed by the local Zowe CA, then ignore `ITRMZWCA` and `ROOTZWCA` variables. In this case, you might see error messages in the JCL related to the `ITRMZWCA` and `ROOTZWCA` variables.
+
+
+ - You can share a certificate with Zowe if the certificate is already stored in the security manager's database. Such a certificate should be owned by the special SITE ACID (CERTSITE ACID for Top Secret or SITECERT ACID for ACF2).
+
+   In this scenario, you must modify the "connect to keyring" security command so that it connects the SITE owned certificate to the Zowe key ring. Also, you must allow the ZWESVUSR acid to extract private key from the SITE owned certificate. You can do that by uncommenting the security command in the ZWEKRING JCL that gives ZWESVUSR CONTROL access to the `IRR.DIGTCERT.GENCERT` resource.
+
+   If the Zowe certificate is already loaded in the security manager's database, then it might be owned by a different user ACID or by the special SITE ACID (CERTSITE ACID for Top Secret, SITECERT ACID for ACF2) instead of `ZWESVUSR`. <!--In this case, you must--> 
+
+After the ZWEKRING JCL successfully configures the certificates and key ring, you must customize the `zowe-setup-certificate.env` file and run the `zowe-setup-certificate.sh` script so that Zowe knows what the key ring and certificate names are. In the `zowe-setup-certificate.env` file, customize the key ring related variables:
+
+- `GENERATE_CERTS_FOR_KEYRING`
+
+   Must be set to `false` so that the `zowe-setup-certificate.sh` script does not repeat the job already done by the ZWEKRING JCL. Defaults to `false` value.
+
+- `VERIFY_CERTIFICATES` 
+
+   If set to true, the key ring must contain root CA of the z/OSMF certificate (it must be configured by the ZWEKRING JCL).
+
+- `KEYSTORE_ALIAS`
+
+   The certificate alias must match either the `LABEL` variable in the ZWEKRING JCL or the label of the certificate already stored in the security manager's database.
+
+- `ZOWE_USER_ID` 
+
+   The owner of the key ring matches the `ZOWEUSER` variable in the ZWEKRING JCL. Defaults to the `ZWESVUSR` user ID. 
+
+- `ZOWE_KEYRING` 
+
+   The key ring name matches the `ZOWERING` variable in the ZWEKRING JCL. 
+
+    **Warning:** If the variable is empty, then the script generates certificates to UNIX keystore files. 
+
+
+When the `zowe-setup-certificates.sh` script executes successfully, it generates the `zowe-certificates.env` file in the `KEYSTORE_DIRECTORY` directory. This file is used in the Zowe instance configuration step, see [Creating and configuring the Zowe instance directory](../user-guide/configure-instance-directory.md#keystore-configuration).
+
+### zowe-setup-certificate.sh script only
+
+The key ring can be completely configured by the `zowe-setup-certificate.sh` script without running the ZWEKRING JCL. Follow the process described 
+in the [Configuring Zowe certificates in UNIX files](#configuring-zowe-certificates-in-unix-files) section but ensure you set the extra key ring related parameters in the `zowe-setup-certificates.env` file:
+ - `ZOWE_KEYRING=` - set this variable to the key ring name
+ - `GENERATE_CERTS_FOR_KEYRING=true` - set this variable to `true`
+
+The `zowe-setup-certificates.sh` script generates the certificates and populates the key ring with the certificates.
+
+The Zowe user ID specified by the `ZOWE_USER_ID` (`ZWESVUSR` by default) must have READ access to the `IRR.DIGTCERT.LISTRING` security resource.
+
+#### Permissions that are required to configure the key ring using the zowe-setup-certificate.sh script
+
+A required level of permissions for the user ID running the script depends on several conditions such as:
+- A user ID that executes the `zowe-setup-certificate.sh` script is or is not the same as the `ZOWE_USER_ID` value.
+- A Zowe certificate is planned to be signed by external CA or by Zowe's local CA. 
+- The `VERIFY_CERTIFICATES` parameter (in the `zowe-setup-certificate.env` file) is set to `true` or `false`.
+
+The access level for a subset of `IRR.DIGTCERT.*` resources differs depending on a combination of the conditions above. 
+
+For example, `READ` access to the subset of `IRR.DIGTCERT.*` resources is sufficient if the user ID executing the script and `ZOWE_USER_ID` are identical, Zowe's local CA signs the Zowe certificate, and `VERIFY_CERTIFICATES` is set to `false`. The subset of `IRR.DIGTCERT.*` resources means the `ADD`, `ADDRING`, `CONNECT`, `IMPORT`, `DELRING`, `DELETE`, `REMOVE`, and `LISTRING` resources.
+
+## Configuring Zowe certificates in UNIX files
+
 A keystore directory is used by Zowe to hold the certificate used for encrypting communication between Zowe clients and the Zowe z/OS servers.  It also holds the truststore used to hold public keys of any servers that Zowe trusts. When Zowe is launched, the instance directory configuration file `instance.env` specifies the location of the keystore directory. See [Configure instance directory](configure-instance-directory.md#keystore-directory).
 
 If you have already created a keystore directory from a previous release of Version 1.8 or later, then you may reuse the existing keystore directory with newer version of Zowe.
 
 You can use the existing certificate signed by an external certificate authority (CA) for HTTPS ports in the API Mediation Layer and the Zowe Application Framework, or else you can let the Zowe configuration script to generate a self-signed certificate by the local API Mediation CA.
 
-If you let the Zowe configuration to generate a self-signed certificate, the certificates should be imported into your browser to avoid untrusted network traffic challenges. See [Import the local CA certificate to your browser](../extend/extend-apiml/api-mediation-security.md#import-the-local-ca-certificate-to-your-browser).  If you do not import the certificates into your browser when you access a Zowe web page, you may be challenged that the web page cannot be trusted and, depending on the browser you are using, have to add an exception to proceed to the web page.  Some browser versions may not accept the Zowe certificate because it is self-signed and the signing authority is not recognized as a trusted source.  Manually importing the certificate into your browser makes it a trusted source and the challenges will no longer occur.  
+If you let the Zowe configuration to generate a self-signed certificate, the certificates should be imported into your browser to avoid untrusted network traffic challenges. See [Import the local CA certificate to your browser](../extend/extend-apiml/api-mediation-security.md#import-the-local-ca-certificate-to-your-browser).  If you do not import the certificates into your browser when you access a Zowe web page, you may be challenged that the web page cannot be trusted and, depending on the browser you are using, must add an exception to proceed to the web page.  Some browser versions may not accept the Zowe certificate because it is self-signed and the signing authority is not recognized as a trusted source.  Manually importing the certificate into your browser makes it a trusted source and the challenges will no longer occur.  
 
 If you have an existing server certificate that is signed by an external CA, then you use this for the Zowe certificate. This could be a CA managed by the IT department of your company, which has already ensured that any certificates signed by that CA are trusted by browsers in your company because they have included their company's CA in their company's browsers' truststore.  This will avoid the need to manually import the local CA into each client machine's browsers.  
 
 If you want to avoid the need to have each browser trust the CA that has signed the Zowe certificate, you can use a public certificate authority such as Symantec, Comodo, or GoDaddy to create a certificate. These certificates are trusted by all browsers and most REST API clients. However, this option involves a manual process of requesting a certificate and may incur a cost payable to the publicly trusted CA.
 
 It's recommended that you start with the local API Mediation Layer CA for an initial evaluation.
 
-You can configure Zowe certificates via different methods. 
-
-- [Method 1: Configure Zowe certificates using shell script](#method-1-configure-zowe-certificates-using-shell-script)
-- [Method 2: Configure Zowe certificates with z/OSMF Workflows](#method-2-configure-zowe-certificates-with-zosmf-workflows)
-
-## Method 1: Configure Zowe certificates using shell script
-
 You can use the `<ROOT_DIR>/bin/zowe-setup-certificates.sh` script in the Zowe runtime directory to configure the certificates with the set of defined environment variables. The environment variables act as parameters for the certificate configuration are held in the file `<ROOT_DIR>/bin/zowe-setup-certificates.env`. 
 
-### Generate certificate with the default values
+## Generate certificate with the default values
 
 The script reads the default variable values that are provided in the `<ROOT_DIR>/bin/zowe-setup-certificates.env` file and generates the certificate signed by the local API Mediation CA and keystores in the `/global/zowe/keystore` location.   To set up certificates with the default environment variables, ensure that you run the following script in the Zowe runtime directory:
 
 ```shell script
 <ROOT_DIR>/bin/zowe-setup-certificates.sh
 ```
 
-generates the keystore in `/global/zowe/keystore`.  On many z/OS installations access to this location will be restricted to priveledged users so this step should be done by a system programmer with site knowledge for where the certificate should be stored in a way that the public key can be read but private key access is controlled.  
+generates the keystore in `/global/zowe/keystore`.  On many z/OS installations access to this location will be restricted to privileged users so this step should be done by a system programmer with site knowledge for where the certificate should be stored in a way that the public key can be read but private key access is controlled.  
 
-### Generate certificate with the custom values
+## Generate certificate with the custom values
 
 We recommend that you review all the parameters in the `zowe-setup-certificates.env` file and customize the values for variables to meet your requirements. For example, set your preferred location to generate certificates and keystores. 
 
@@ -115,51 +234,8 @@ ZOWE_ZOSMF_HOST=${ZOWE_ZOSMF_HOST}   ZOWE_ZOSMF_PORT=${ZOWE_ZOSMF_PORT}
 You can also specify z/OSMF certificate explicitly in the ZOSMF_CERTIFICATE environmental variable in the zowe-setup-certificates.env file.
 ```
 
-This error has to be resolved before you can proceed with the next installation step.
+This error must be resolved before you can proceed with the next installation step.
 
 **Notes:** 
 
-On many z/OS systems, the certificate for z/OSMF is not signed by a trusted CA and is a self-signed certificate by the z/OS system programmer who configured z/OSMF.  If that is the case, then Zowe itself will not trust the z/OSMF certificate and any function dependent on z/OSMF will not operate correctly.  To ensure that Zowe trusts a z/OSMF self-signed certificate, you must use the value `VERIFY_CERTIFICATES=false` in the `zowe-setup-certificates.env` file.  This is also required if the certificate is from a recognized CA but for a different host name, which can occur when a trusted certificate is copied from one source and reused within a z/OS installation for different servers other than that it was originally created for.  
-
-## Method 2: Configure Zowe certificates with z/OSMF Workflows
-
-z/OSMF Workflow lets you create a keystore directory that is used by Zowe to hold the certificate that is used for encrypting communication between Zowe clients and the Zowe z/OS servers.
-
-Perform the following steps to register and execute the Zowe workflow in the z/OSMF web interface:
-
- 1.	Log in to the z/OSMF web interface.
- 2.	Select **Workflows** from the navigation tree.
- 3.	Select Create Workflow from the **Actions** menu.
- 4.	Enter the complete path to the workflow definition file in the **Workflow Definition filed**.
-    The path to the workflow definition file is *[extracted_pax_folder]/files/workflows/ZWEWRF05.xml file*. 
-5. (Optional) Enter the path to the customized variable input file that you prepared in advance.
-    The path to the variable input file is <extracted_pax_folder>/files/workflows/ ZWEWRF05.properties file. 
-
-    Create a copy of the variable input file. Modify the file as necessary according to the built-in comments. Set the field to the path where the new file is located. When you execute the workflow, the values from the variable input file override the workflow variables default values.
-6. Select the system where you want to execute the workflow.
-7. Select Next.
-8. Specify the unique workflow name.
-9. Select or enter an Owner Use ID and select **Assign all steps to owner user ID**.
-10.Select **Finish**.
-   The workflow is registered in z/OSMF and ready to execute.
-11. Select the workflow that you registered from the workflow list.
-12. Execute the following steps in order:
-    -	**Define Variables**
-
-        Define the custom values for variables that meet your z/OS security and verification configuration requirements.
-    - 	**New Custom zowe-setup-certificates.env**
-
-        Execute the step to create a new `zowe-setup-certificates.env` in the user specified location and substitutes values.
-	-  **Execute zowe-setup-certificates**
-
-        Execute the step to substitute zowe-setup-certificates with the customized zowe-setup-certificates.env file.
-
-13. Perform the following steps to execute each step individually:
-    1.  Double-click the title of the step.
-    2.	Select the **Perform** tab.
-    3.  Review the step contents and update the input values as required.
-    4.	Select **Next**.
-    5.	Repeat the previous two steps to complete all items until the option Finish is available.
-    6.	Select **Finish**.
-
-After you execute each step, the step is marked as Complete. The workflow is executed. For general information about how to execute z/OSMF workflow steps, watch the [z/OSMF Workflows Tutorial](https://www.youtube.com/watch?v=KLKi7bhKBlE&feature=youtu.be).
+On many z/OS systems, the certificate for z/OSMF is not signed by a trusted CA and is a self-signed certificate by the z/OS system programmer who configured z/OSMF.  If that is the case, then Zowe itself will not trust the z/OSMF certificate and any function dependent on z/OSMF will not operate correctly.  To ensure that Zowe trusts a z/OSMF self-signed certificate, you must use the value `VERIFY_CERTIFICATES=false` in the `zowe-setup-certificates.env` file.  This is also required if the certificate is from a recognized CA but for a different host name, which can occur when a trusted certificate is copied from one source and reused within a z/OS installation for different servers other than that it was originally created for.