Draft of TLS documentation

Signed-off-by: 1000TurquoisePogs <[email protected]>

docs/user-guide/mvd-configuration.md

@@ -86,24 +86,12 @@ The file `_defaultVT.json` within the `vt-ng2` app folder `/config/storageDefaul
 
 **Note:** The following attributes are to be defined in the Zowe configuration file.
 
-The App Server can be accessed over HTTP and/or HTTPS, provided it has been configured for either. HTTPS should be used, as HTTP is not secure unless AT-TLS is used.
-When AT-TLS is used by ZSS, `components.zss.agent.http.attls` must be set to true.
+The App Server and ZSS are HTTPS servers by default. However, AT-TLS can be used instead, as seen in the guide [for configuring AT-TLS](./at-tls-configuration)
 
 ### HTTPS
 
-Both `app-server` and `zss` server components use HTTPS by default, and the `port` parameters `components.app-server.port` and `components.zss.port` control which port they are accessible from. However, each have advanced configuration options to control their HTTPS behavior.
-
-The `app-server` component configuration can be used to customize its HTTPS connection such as which certificate and ciphers to use, and these parameters are to be set within `components.app-server.node.https` as defined within the [json-schema file](https://github.com/zowe/zlux-app-server/blob/v2.x/staging/schemas/app-server-config.json#L15)
-
-The `zss` component configuration can be used to customize its HTTPS connection such as which certificate and ciphers to use, and these parameters are to be set within `components.zss.agent.https` as defined within the [json-schema file](https://github.com/zowe/zss/blob/v2.x/staging/schemas/zss-config.json#L81)
-
-
-### HTTP
-
-The `app-server` can be configured for HTTP via the `components.app-server.node.http` section of the Zowe configuration file, as specified within the `app-server` [json-schema file](https://github.com/zowe/zlux-app-server/blob/v2.x/staging/schemas/app-server-config.json#L73).
-
-The `zss` server can be configured for HTTP via the `components.zss.agent.http` section of the Zowe configuration file, as specified within the `zss` [json-schema file](https://github.com/zowe/zss/blob/v2.x/staging/schemas/zss-config.json#L99). Note that `components.zss.tls` must be set to false for HTTP to take effect, and that `components.zss.agent.http.attls` must be set to true for AT-TLS to be recognized correctly.
-
+Both `app-server` and `zss` server components use HTTPS by default, and the `port` parameters `components.app-server.port` and `components.zss.port` control which port they are accessible from.
+Parameters 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, which may also be placed within each component to control a particular component, such as `components.zss.zowe.network.server.tls`. For more information, see [TLS configuration](./tls-configuration);
 
 
 ## Configuration Directories

docs/user-guide/tls-configuration.md

@@ -0,0 +1,49 @@
+# Customizing HTTPS connections for Zowe servers
+
+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
+:::
+
+## Configuration Parameters
+
+By default, Zowe servers will listen on IP address "0.0.0.0" and use TLSv1.3 with industry standard ciphers.
+You may wish to change this behavior, and can do so globally by editing the `zowe.network` configuration of the Zowe YAML file, or locally by editing `zowe.network` within a component, such as `components.zss.zowe.network` for ZSS.
+
+**Note: The parameters are recommended for servers to use, but some servers may support some parameters, and not others, or none at all. It is good to verify that the settings are taking effect by for example checking the connection in your browser, as well as checking the documentation of extensions of Zowe.**
+
+Below is a list of parameters you can set.
+
+`zowe.network.server.listenAddresses`: This is an array of strings of IPv4 or IPv6 addresses that servers will be instructed to listen on.
+Default: `- "0.0.0.0"`
+
+`zowe.network.server.tls.maxTls`: This is a string stating which TLS version to use as a maximum. The value can be one of "TLSv1.2", "TLSv1.3".
+Default: `TLSv1.3"
+
+`zowe.network.server.tls.minTls`: This is a string stating which TLS version to use as a minimum. The value can be one of "TLSv1.2", "TLSv1.3".
+Default: `TLSv1.2"
+
+`zowe.network.server.tls.ciphers`: This is an array of strings in the format of IANA cipher names. There are many possible values as seen here: https://testssl.sh/openssl-iana.mapping.html
+Default: Changes regularly as needed for industry standards. A reference for likely ciphers is here: https://wiki.mozilla.org/Security/Server_Side_TLS
+
+### 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"

sidebars.js

@@ -200,6 +200,7 @@ module.exports = {
                 "user-guide/generate-certificates",
                 "user-guide/use-certificates",
                 "user-guide/certificates-setup",
+                "user-guide/tls-configuration",
                 "user-guide/at-tls-configuration",
               ],
             },