Merge pull request #1214 from zowe/keyring-support

Keyring support documentation
zowe · Jul 28, 2020 · 564b9fc · 564b9fc
2 parents ee6d397 + cf3bad6
commit 564b9fc
Showing 1 changed file with 126 additions and 3 deletions.
diff --git a/docs/user-guide/configure-certificates.md b/docs/user-guide/configure-certificates.md
@@ -1,5 +1,128 @@
 # 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. 
+
+  - Currently only RACF fully supports this option.
+  - 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. 
+
+  For more information, see [zowe-setup-certificate.sh script only](#zowe-setup-certificatesh-script-only).
+
+
+### ZWEKRING JCL and zowe-setup-certificate.sh
+
+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.
+
+<!--[//]: # "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" -->
+
+**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.
+
+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.
@@ -24,7 +147,7 @@ The script reads the default variable values that are provided in the `<ROOT_DIR
 <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
 
@@ -108,11 +231,11 @@ 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.  
+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.  
 
 ## Using web tokens for SSO on ZLUX and ZSS