Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Removed v1 details from the docs and updated to v2 zowe.yaml descript… #3817

Merged
merged 8 commits into from
Aug 22, 2024
4 changes: 2 additions & 2 deletions docs/troubleshoot/troubleshoot-apiml.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
54 changes: 36 additions & 18 deletions docs/user-guide/import-certificates.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<KEYSTORE_DIRECTORY>/local_ca/localca.cer` where `<KEYSTORE_DIRECTORY>` is defined in a customized `<RUNTIME_DIR>/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:
<details>

```
certutil -enterprise -f -v -AddStore "Root" localca.cer
```
<summary>
For Windows, click here for command details.
</summary>

**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:
</details>

<details>
<summary>
For macOS, click here for command details.
</summary>

```
$ 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.
</details>

Create a new Javascript file firefox-windows-truststore.js at `C:\Program Files (x86)\Mozilla Firefox\defaults\pref` with the following content:
<details>
<summary>
For Firefox, click here for command deails.
</summary>

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);
```
</details>

:::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.
Expand Down
Loading