Improve user education on keystores & certificates, and how Zowe uses them

[1000TurquoisePogs]

I've assisted many users, each taking significant time to get zowe server keystores set up correctly. The problems and time consumed is rarely ever due to a code bug, it's overwhelmingly user education. There are many tickets that describe problems, waiting to be done: https://github.com/zowe/docs-site/issues/2643
https://github.com/zowe/docs-site/issues/2563
https://github.com/zowe/docs-site/issues/2304 https://github.com/zowe/docs-site/issues/2303 https://github.com/zowe/docs-site/issues/2302 https://github.com/zowe/docs-site/issues/1227 https://github.com/zowe/docs-site/issues/1281 https://github.com/zowe/zowe-install-packaging/issues/1653

Education falls into a few categories where improvements must be made:

1. Users need to know the concepts of keystores, keyrings, certificates, certificate authorities

• Users ask, What's a CA? Do I put the CA alias in the keystore section of my config? (no, but users may not know this!)

2. Users need to know how to find attributes of these objects.

• Users ask, Where do I find the alias name to put in my config?

3. Users need to know how to relate these attributes to zowe configuration.

• Users ask, is a label an alias?
• Users do not know that keystore items are "Case, Space, and Symbol Sensitive"
• Users do not know YAML syntax, so the above sensitivity can break their config.

4. Users may not know what Zowe needs at minimum

• Users ask, should the keystore and truststore be 2 different things?
• What goes into the keystore? What goes into the truststore? What are the items within a minimal keyring?

5. Users need to know what's special, if anything, about the way Zowe uses certificates Some people try to import certs from a different webserver, and then complain that it doesn't work with Zowe, implying there's something wrong with Zowe's support for certs. This is often because they don't know how Zowe uses the certs differently from another webserver. Users need to know:

• Zowe uses the certificate(s) not just to present to the browser, but for server-to-server
  • This leads to needing extended key usage flags, which their existing certs probably did not have https://github.com/zowe/docs-site/issues/1901 https://github.com/zowe/docs-site/issues/2210
  • This leads to problems with the certs valid domain name(s) because internal networking, including with VIPA, will make it challenging to get a valid set of domain names, and is certainly not what they'd have from a purely browser-facing certificate. https://github.com/zowe/zowe-install-packaging/issues/2529

6. Users need to know how to avoid ending up with a self-signed cert if they can.

• Instruct users how to use a CA for their certs which is already known by their browsers.
  • Such as exporting a CA from their computer's truststore to zOS for setup?
• Instruct users how to export the CA used during setup to their browser

[samanthasusu]

Hi there, here is a start of the enhancement process, please feel free to leave your comments in the pull request #2822 in doc site repo.

[1000TurquoisePogs]

Can we declare this to be a victory in v2.10? Seems like we did good stuff there.

[balhar-jakub]

We (as Broadcom) are presenting the improvements to some of our customers this Thursday, I believe that we improved a lot, but before closing I would like to get their feedback.