diff --git a/docs/troubleshoot/troubleshoot-apiml.md b/docs/troubleshoot/troubleshoot-apiml.md index 4edd5be85e..b1279b8d7f 100644 --- a/docs/troubleshoot/troubleshoot-apiml.md +++ b/docs/troubleshoot/troubleshoot-apiml.md @@ -342,9 +342,9 @@ Fix the missing z/OSMF host name in subject alternative names using the followin **Follow these steps:** 1. Re-create the Zowe keystore by deleting it and re-creating it. -2. In the `zowe-setup-certificates.env` file that is used to generate the keystore, ensure that the property `VERIFY_CERTIFICATES` and `NONSTRICT_VERIFY_CERTIFICATES` are set to `false`. +2. In the `zowe.yaml` file that used to launch Zowe, ensure the property `zowe.verifyCertificates` is set to `DISABLED` or `NONSTRICT`. The default value is `STRICT` which ensures that Zowe validates the certificate authority's signing chain is trusted, and that the IP address for Zowe's servers match the certificate's subject alternative name. -**Important!** Disabling `VERIFY_CERTIFICATES` or `NONSTRICT_VERIFY_CERTIFICATES` may expose your server to security risks. Ensure that you contact your system administrator before disabling these certificates and use these options only for troubleshooting purposes. +**Important!** Disabling `zowe.verifyCertificates` may expose your server to security risks. Ensure that you contact your system administrator before disabling these certificates and use these options only for troubleshooting purposes. #### Invalid z/OSMF host name in subject alternative names diff --git a/docs/user-guide/import-certificates.md b/docs/user-guide/import-certificates.md index be89d4db78..70ed86068f 100644 --- a/docs/user-guide/import-certificates.md +++ b/docs/user-guide/import-certificates.md @@ -69,39 +69,57 @@ Trust in the API ML server is a necessary precondition for secure communication 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. ::: -The public certificate in [PEM format](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) is stored at `/local_ca/localca.cer` where `` is defined in a customized `/bin/zowe-setup-certificates.env` file during the installation step that generates Zowe certificates. The certificate is stored in UTF-8 encoding so you need to transfer it 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 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. :::note Windows currently does not recognize the PEM format. For Windows, use the P12 version of the `local_cer`. ::: -**Importing commands according to your operating system** +#### Importing commands according to your operating system To import the certificate to your root certificate store and trust it, follow the applicable procedure based on your operating system. - - **For Windows**, run the following command: +
- ``` - certutil -enterprise -f -v -AddStore "Root" localca.cer - ``` + +For Windows, click here for command details. + - **Note:** Ensure that you open the terminal as **administrator**. This operation installs the certificate to the Trusted Root Certification Authorities. +``` +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. - - **For macOS**, run the following command: +
+ +
+ +For macOS, click here for command details. + - ``` - $ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain localca.cer - ``` +``` +$ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain localca.cer +``` - - **For Firefox**, 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: +
+ +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: + +``` +/* Enable experimental Windows truststore support */ +pref("security.enterprise_roots.enabled", true); +``` - ``` - /* Enable experimental Windows truststore support */ - 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.