From 24ed3461fd8e401d7b573b595a8e1afd026f3ff3 Mon Sep 17 00:00:00 2001 From: 1000TurquoisePogs Date: Wed, 23 Oct 2024 12:18:09 -0700 Subject: [PATCH] V3 guide for TLS configuration Signed-off-by: 1000TurquoisePogs --- docs/user-guide/at-tls-configuration.md | 4 +- docs/user-guide/mvd-configuration.md | 5 ++ docs/user-guide/tls-configuration.md | 84 +++++++++++++++++++++++++ sidebars.js | 1 + 4 files changed, 92 insertions(+), 2 deletions(-) create mode 100644 docs/user-guide/tls-configuration.md diff --git a/docs/user-guide/at-tls-configuration.md b/docs/user-guide/at-tls-configuration.md index ab36c09d92..ebbe5d523a 100644 --- a/docs/user-guide/at-tls-configuration.md +++ b/docs/user-guide/at-tls-configuration.md @@ -1,4 +1,4 @@ -# Enabling AT-TLS across your Zowe environment +# Enabling AT-TLS The communication server on z/OS provides functionality to encrypt HTTP communication for on-platform jobs. This functionality is referred to as Application Transparent Transport Layer Security (AT-TLS). @@ -20,4 +20,4 @@ zowe: For detailed configuration instructions specific to each component, refer to the following guides: - [Configuring AT-TLS for API Mediation Layer](../user-guide/api-mediation/configuration-at-tls.md) -- [Using AT-TLS in the App Framework](../user-guide/mvd-configuration#using-at-tls-in-the-app-framework) \ No newline at end of file +- [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 85712c2b1d..b404694122 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..18be801602 --- /dev/null +++ b/docs/user-guide/tls-configuration.md @@ -0,0 +1,84 @@ +# 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](./at-tls-configuration). + +:::info Required roles: 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, this will match this reference: 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 fbd4f1dfdb..187a4f4259 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/at-tls-configuration", ], },