diff --git a/docs/user-guide/configuring-at-tls-for-zowe-server.md b/docs/user-guide/configuring-at-tls-for-zowe-server.md index 96ac2bac77..4a74301789 100644 --- a/docs/user-guide/configuring-at-tls-for-zowe-server.md +++ b/docs/user-guide/configuring-at-tls-for-zowe-server.md @@ -1,4 +1,4 @@ -# Configuring AT-TLS for Zowe Server +# Enabling AT-TLS You can configure parameters in the Zowe server to enable Zowe to work with AT-TLS. Review this article for information about AT-TLS inbound and outbound rules, and the required configuration to use AT-TLS in high availability. You can also find troubleshooting tips as well as security recommendations. @@ -32,15 +32,15 @@ Follow these steps to configure Zowe to support AT-TLS: ```yaml zowe: - network: - # For inbound traffic rules: - server: - tls: - attls: true - # If outbound traffic rules will be configured: - client: - tls: - attls: true + network: + # For inbound traffic rules: + server: + tls: + attls: true + # If outbound traffic rules will be configured: + client: + tls: + attls: true ``` While the Zowe Server components do not handle TLS on its own with AT-TLS enabled, the API Mediation Layer (API ML) requires information about the server certificate that is defined in the AT-TLS rule. Ensure that the server certificates provided by the AT-TLS layer are trusted in the configured Zowe keyring. We strongly recommend that AT-TLS be configured with the same Zowe keyring. @@ -684,7 +684,3 @@ TTLSCipherParms CipherParms ``` - -## Additional Zowe feature configuration with AT-TLS - -The Zowe Application Framework also leverages AT-TLS. For more information, see [Using AT-TLS in the App Framework](../user-guide/mvd-configuration#using-at-tls-in-the-app-framework). diff --git a/docs/user-guide/mvd-configuration.md b/docs/user-guide/mvd-configuration.md index ab711706d4..bae48798fb 100644 --- a/docs/user-guide/mvd-configuration.md +++ b/docs/user-guide/mvd-configuration.md @@ -84,6 +84,11 @@ By default, all Zowe servers listen on the IP address `0.0.0.0`. This can be cus The Zowe YAML property `zowe.network.server.tls.listenAddresses` can be used to instruct both `app-server` and `zss` of which IP to listen on. This property can be nested within each component if it is desired to customize them individually. Alternatively, TCPIP port rules can be used to control the assignment of `0.0.0.0` into a particular alternative IP address. [You can read more about this in the network requirements page](./address-network-requirements.md). +### Native TLS + +Both `app-server` and `zss` server components default to using HTTPS without the need for AT-TLS. AT-TLS is also possible. When using the native TLS, attributes such as TLS version and ciphers can be customized within the `zowe.network.server.tls` and `zowe.network.client.tls` objects of the Zowe configuration. These objects can also be placed within the `components.zss` and `components.app-server` objects, such as `components.zss.zowe.network.server.tls` in order to individually customize each server TLS configuration. For more information, read [TLS configuration](./tls-configuration). + + ### AT-TLS You can instruct Zowe servers to expect TLS using the property `zowe.network.server.tls.attls: true`. This is for setting AT-TLS for all the Zowe servers. For more granular control, you can set the following: diff --git a/docs/user-guide/tls-configuration.md b/docs/user-guide/tls-configuration.md new file mode 100644 index 0000000000..d7e7ec0d82 --- /dev/null +++ b/docs/user-guide/tls-configuration.md @@ -0,0 +1,90 @@ +# Customizing Native TLS + +Zowe's servers have built-in TLS support to enable HTTPS connections. + +This is the default, and an alternative to using AT-TLS which is [documented here](./configuring-at-tls-for-zowe-server). + +:::info Required role: security administrator +::: + +## Server Parameters + +Each Zowe server can be customized either by defining attributes within the `zowe.network.server` object of the Zowe YAML configuration file. The same object can be put within an individual component's configuration, such as `components.zss.zowe.network.server` for ZSS, which will allow you to customize each component separate from others. + +Extensions are recommended to adhere to this configuration, but you must check with documentation for extensions to be sure. + +### IP Addresses + +Zowe's servers by default use the TCP IP address `0.0.0.0` which assigns the servers to be available on all network interfaces available to the jobs. + +If this default is not desired, you can either change it either within Zowe or by setting [TCPIP port assignment statements](./address-network-requirements#ip-addresses). + +To customize this within Zowe, define the parameter `zowe.network.server.listenAddresses`. For example, to have all Zowe servers use IP `1.2.3.4`, except for App Server which will use IP `2.3.4.5`, set the following in your Zowe YAML: + +```yaml +zowe: + network: + server: + listenAddresses: + - 1.2.3.4 +components: + app-server: + zowe: + network: + server: + listenAddresses: + - 2.3.4.5 +``` + + +### TLS Versions + +By default, Zowe servers use TLSv1.3. + +To customize this, you can use the parameters `zowe.network.server.tls.minTls` and `zowe.network.server.tls.maxTls`. The following values are allowed: + +* TLSv1.2 +* TLSv1.3 + +Zowe defaults to the following configuration: + +```yaml +zowe: + network: + tls: + minTls: "TLSv1.2" + maxTls: "TLSv1.3" +``` + +### TLS Ciphers + +Zowe is always updating the ciphers used to follow industry best practice. + +Usually, the ciphers used by Zowe will match Mozilla's recommendations: https://wiki.mozilla.org/Security/Server_Side_TLS + +To customize which ciphers Zowe uses, you can define a list of IANA cipher names within the Zowe YAML parameter `zowe.network.server.tls.ciphers`. A list of [IANA ciphers can be found here](https://testssl.sh/openssl-iana.mapping.html). + + +## Client parameters + +The properties within `zowe.network.server.tls` can also be specified within `zowe.network.client.tls`. + +## Default and example +The default TLS configuration changes regularly as needed for industry standards, however below is an example of the defaults: + +```yaml +zowe: + network: + server: + listenAddresses: + - "0.0.0.0" + tls: + maxTls: "TLSv1.3" + minTls: "TLSv1.2" + ciphers: + - "TLS_AES_128_GCM_SHA256" + - "TLS_AES_256_GCM_SHA384" + - "TLS_CHACHA20_POLY1305_SHA256" + client: # Template below assigns same attributes as seen in server section + tls: ${{ zowe.network.server.tls }} +``` diff --git a/sidebars.js b/sidebars.js index a59ee2b523..748aa55f74 100644 --- a/sidebars.js +++ b/sidebars.js @@ -223,6 +223,7 @@ module.exports = { "user-guide/generate-certificates", "user-guide/use-certificates", "user-guide/certificates-setup", + "user-guide/tls-configuration", "user-guide/configuring-at-tls-for-zowe-server", ], },