From ca774710c5d18adff930ccab085393d584e03435 Mon Sep 17 00:00:00 2001 From: 1000TurquoisePogs Date: Wed, 23 Oct 2024 12:18:09 -0700 Subject: [PATCH 1/4] V3 guide for TLS configuration Signed-off-by: 1000TurquoisePogs --- .../configuring-at-tls-for-zowe-server.md | 24 +++--- docs/user-guide/mvd-configuration.md | 5 ++ docs/user-guide/tls-configuration.md | 84 +++++++++++++++++++ sidebars.js | 1 + 4 files changed, 100 insertions(+), 14 deletions(-) create mode 100644 docs/user-guide/tls-configuration.md 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..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 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", ], }, From 5786037fa73185bbab0cb3098fb9ca66ed2595d3 Mon Sep 17 00:00:00 2001 From: 1000TurquoisePogs Date: Wed, 23 Oct 2024 21:18:54 +0200 Subject: [PATCH 2/4] Update tls-configuration.md for syntax Signed-off-by: 1000TurquoisePogs --- docs/user-guide/tls-configuration.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/user-guide/tls-configuration.md b/docs/user-guide/tls-configuration.md index 18be801602..c9e7d8ad46 100644 --- a/docs/user-guide/tls-configuration.md +++ b/docs/user-guide/tls-configuration.md @@ -82,3 +82,4 @@ zowe: - "TLS_CHACHA20_POLY1305_SHA256" client: # Template below assigns same attributes as seen in server section tls: ${{ zowe.network.server.tls }} +``` From 7e2c4d4422c3280814392a16d83a5780698b4181 Mon Sep 17 00:00:00 2001 From: 1000TurquoisePogs Date: Wed, 30 Oct 2024 10:26:35 +0100 Subject: [PATCH 3/4] Formatting updated to match Ana's review Signed-off-by: 1000TurquoisePogs --- docs/user-guide/tls-configuration.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/tls-configuration.md b/docs/user-guide/tls-configuration.md index c9e7d8ad46..4b1cb9816f 100644 --- a/docs/user-guide/tls-configuration.md +++ b/docs/user-guide/tls-configuration.md @@ -1,14 +1,16 @@ # 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 +:::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 @@ -38,6 +40,7 @@ components: ### 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 @@ -55,8 +58,10 @@ zowe: ### 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 +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). From d88f3a769c02dd1dce9f73f4d6b2b539a7e1332d Mon Sep 17 00:00:00 2001 From: 1000TurquoisePogs Date: Wed, 30 Oct 2024 10:48:34 +0100 Subject: [PATCH 4/4] Fix AT-TLS ref link Signed-off-by: 1000TurquoisePogs --- docs/user-guide/tls-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/tls-configuration.md b/docs/user-guide/tls-configuration.md index 4b1cb9816f..d7e7ec0d82 100644 --- a/docs/user-guide/tls-configuration.md +++ b/docs/user-guide/tls-configuration.md @@ -2,7 +2,7 @@ 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). +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 :::