SD-3987: add config option TLSv13_Ciphersuites (#749)

* add config option TLSv13_Ciphersuites

* minor update

* minor update

* lastUpdated

* minor change from review comment

content/momentum/4/config-options-summary.md

@@ -1,5 +1,5 @@
 ---
-lastUpdated: "09/14/2021"
+lastUpdated: "09/20/2023"
 title: "Configuration Options Summary"
 description: "This chapter lists all configuration options visible in the following scopes global domain host binding binding group security pathway pathway group listener listen peer threadpool debug flags and cluster as well as in the listener specific scope Module specific options are documented in the module documentation and options specific to..."
 ---
@@ -340,6 +340,7 @@ The `Version` column indicated the version(s) of Momentum that support the optio
 | [tls_ca](/momentum/4/config/tls-ca) – Specify certificate authority for outbound mail | sending |   | 4.0 and later | binding, binding_group, domain, global |
 | [tls_certificate](/momentum/4/config/tls-certificate) – Specify certificate to use for inbound and outbound mail | receiving and sending |   | 4.0 and later | binding, binding_group, domain, ecstream_listener, esmtp_listener, global, http_listener, listen, pathway, pathway_group, peer, xmpp_listener |
 | [tls_ciphers](/momentum/4/config/tls-ciphers) – Specify allowable ciphers for TLS inbound and outbound sessions | receiving and sending |   | 4.0 and later | binding, binding_group, domain, ecstream_listener, esmtp_listener, global, http_listener, listen, pathway, pathway_group, peer, xmpp_listener |
+| [tlsv13_ciphersuites](/momentum/4/config/tlsv13-ciphersuites) – Specify allowable TLSv1.3 ciphersuites for TLS inbound and outbound sessions | receiving and sending |   | 4.6 and later | binding, binding_group, domain, esmtp_listener, global, http_listener, listen, pathway, pathway_group, peer |
 | [tls_client_ca](/momentum/4/config/tls-client-ca) – Specify certificate authority for inbound mail | receiving |   | 4.0 and later | ecstream_listener, esmtp_listener, global, http_listener, listen, pathway, pathway_group, peer, xmpp_listener |
 | [tls_dhparams_file](/momentum/4/config/ref-tls-dhparams-file) – Specifies DHE parameters that add per-session randomness to the encryption | both |   | 4.0 and later | global |
 | [tls_enable_dhe_ciphers](/momentum/4/config/ref-tls-enable-dhe-ciphers) – Controls whether or not DHE ciphers are available | both | true | 4.0 and later | global |

content/momentum/4/config/index.md

@@ -1,5 +1,5 @@
 ---
-lastUpdated: "09/14/2021"
+lastUpdated: "09/20/2023"
 title: "Category File"
 type: "custom"
 name: "Configuration Options Reference"
@@ -206,6 +206,7 @@ description: "This chapter provides the definitions of the configuration options
 | [tls_ca](/momentum/4/config/tls-ca) | certificate authority for outbound mail |
 | [tls_certificate](/momentum/4/config/tls-certificate) | certificate to use for inbound and outbound mail |
 | [tls_ciphers](/momentum/4/config/tls-ciphers) | specify allowable ciphers for TLS inbound and outbound sessions |
+| [tlsv13_ciphersuites](/momentum/4/config/tlsv13-ciphersuites) | specify allowable TLSv1.3 ciphersuites for TLS inbound and outbound sessions |
 | [tls_client_ca](/momentum/4/config/tls-client-ca) | certificate authority for inbound mail |
 | [tls_dhparams_file](/momentum/4/config/ref-tls-dhparams-file) | specifies the file of Diffie Hellman (DHE) parameters that add per-session randomness to the encryption. Default parameters are built in the product if none are specified. |
 | [tls_enable_dhe_ciphers](/momentum/4/config/ref-tls-enable-dhe-ciphers) | controls whether or not Diffie Hellman (DHE) ciphers are available |

content/momentum/4/config/tls-protocols.md

@@ -1,5 +1,5 @@
 ---
-lastUpdated: "03/26/2020"
+lastUpdated: "09/20/2023"
 title: "tls_protocols"
 description: "tls protocols allowable ciphers for TLS inbound and outbound sessions tls protocols baseprotocol additional protocols Configuration Change This option is available as of version 4 1 0 2 tls protocols specifies the allowable protocols for an Open SSL TLS session The available protocols are ALL SS Lv 2 SS Lv..."
 ---
@@ -18,7 +18,9 @@ tls_protocols — allowable ciphers for TLS inbound and outbound sessions
 
 **Configuration Change. ** This option is available as of version 4.1.0.2\.
 
-`tls_protocols` specifies the allowable protocols for an OpenSSL TLS session. The available protocols are `ALL`, `SSLv2`, `SSLv3`, `TLSv1.0`, `TLSv1.1`, and `TLSv1.2`. Each set can be enabled or disabled by prefixing its name with a “+” or “-“ respectively. The following example shows the SSLv2 and SSLv3 protocols being disabled:
+`tls_protocols` specifies the allowable protocols for an OpenSSL TLS session. The available
+protocols are `ALL`, `SSLv2`, `SSLv3`, `TLSv1.0`, `TLSv1.1`, `TLSv1.2` and `TLSv1.3` (since Momentum
+4.6). Each set can be enabled or disabled by prefixing its name with a “+” or “-“ respectively. The following example shows the SSLv2 and SSLv3 protocols being disabled:
 
 `TLS_Protocols = "+ALL:-SSLv2:-SSLv3"`
 
@@ -28,9 +30,9 @@ The default value is “+ALL”.
 
 ### Note
 
-In Centos/RHEL 5, which are typically shipped with OpenSSL 0.98, TLSv1.1 and TLSv1.2 are not available.
+In Centos/RHEL 5, which are typically shipped with OpenSSL 0.98, TLSv1.1, TLSv1.2 and TLSv1.3 are not available.
 
 <a name="idp26999712"></a> 
 ## Scope
 
-`tls_ciphers` is valid in the binding, binding_group, domain, ecstream_listener, esmtp_listener, global, http_listener, listen, pathway, pathway_group and peer scopes.
+`tls_protocols` is valid in the binding, binding_group, domain, ecstream_listener, esmtp_listener, global, http_listener, listen, pathway, pathway_group and peer scopes.

content/momentum/4/config/tlsv13-ciphersuites.md

@@ -0,0 +1,62 @@
+---
+lastUpdated: "09/20/2023"
+title: "tlsv13_ciphersuites"
+description: "specify allowable ciphersuites for TLS inbound and outbound sessions when TLSv1.3 protocol is negotiated and used"
+---
+
+<a name="config.tlsv13_ciphersuites"></a>
+## Name
+
+tlsv13_ciphersuites — specify allowable TLSv1.3 ciphersuites for TLS inbound and outbound sessions
+
+## Synopsis
+
+`TLSv13_Ciphersuites = "<ciphersuite>[:<another ciphersuite>]"`
+
+## Description
+
+**Configuration Change. ** This option is available as of version 4.6, for SMTP reception, HTTP reception, and SMTP deliveries only.
+
+This option specifies the allowable ciphersuites for a TLS session using TLSv1.3 protocol. The
+allowable ciphersuites must be a subset of the available TLSv1.3 ciphersuites on the host system.
+
+**OpenSSL**
+
+When TLS_Engine is set to `openssl`, `TLSv13_Ciphersuites` specifies a "ciphersuite list", which is a
+colon (":") separated list of the supported TLSv1.3 ciphersuite names in order of preference.
+There are 5 valid TLSv1.3 ciphersuites that are supported by OpenSSL 1.1.1:
+```
+    TLS_AES_256_GCM_SHA384
+    TLS_CHACHA20_POLY1305_SHA256
+    TLS_AES_128_GCM_SHA256
+    TLS_AES_128_CCM_8_SHA256
+    TLS_AES_128_CCM_SHA256
+```
+By default (if not explicitly specified through this configuration option), only the first three are enabled.
+On the host machine, `openssl11 ciphers -s -tls1_3` can show the default TLSv1.3 ciphersuites;
+`openssl11 ciphers -tls1_3 -v -s -ciphersuites TLS_AES_128_CCM_8_SHA256:TLS_AES_128_CCM_SHA256` can
+check whether the last two ciphersuites are supported if enabled.
+For more information about the TLSv1.3 ciphersuites, see
+[https://wiki.openssl.org/index.php/TLS1.3#Ciphersuites](https://wiki.openssl.org/index.php/TLS1.3#Ciphersuites).
+
+
+* To set the option to all the 5 TLSv1.3 ciphersuites supported by OpenSSL 1.1.1:
+
+```
+TLSv13_Ciphersuites = "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256:TLS_AES_128_CCM_8_SHA256:TLS_AES_128_CCM_SHA256"
+```
+
+The default value (when this option is left unset) is
+`"TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"`.
+
+**GNUTLS**
+
+This option has no meaning for GNUTLS.
+
+
+### Note
+This option is new in Momentum 4.6.
+
+## Scope
+
+`tlsv13_ciphersuites` is valid in the binding, binding_group, domain, esmtp_listener, global, http_listener, listen, pathway, pathway_group and peer scopes.

content/momentum/4/inbound-tls.md

@@ -1,5 +1,5 @@
 ---
-lastUpdated: "03/26/2020"
+lastUpdated: "09/20/2023"
 title: "Inbound TLS"
 description: "Transport Layer Security TLS can be easily configured on an SMTP listener using the following configuration snippet The following are the configuration options related to inbound TLS tls allow renegotiation tls certificate tls ciphers tls client ca tls dhparams file tls enable dhe ciphers tls key tls protocols tls verified..."
 ---
@@ -27,6 +27,8 @@ The following are the configuration options related to inbound TLS:
 
 *   [tls_ciphers](/momentum/4/config/tls-ciphers)
 
+*   [tlsv13_ciphersuites](/momentum/4/config/tlsv13-ciphersuites)
+
 *   [tls_client_ca](/momentum/4/config/tls-client-ca)
 
 *   [tls_dhparams_file](/momentum/4/config/ref-tls-dhparams-file)
@@ -41,4 +43,4 @@ The following are the configuration options related to inbound TLS:
 
 *   [tls_verify_mode](/momentum/4/config/tls-verify-mode)
 
-If client certificate verification fails, the SMTP session does not terminate. The TLS status is stored in predefined context validation variables, so it is possible to drive TLS policy from policy scripts. You can use this to reject messages when client verification failed. For more information regarding the TLS-related context variables, see [“Global Predefined Connection Context Variables”](/momentum/4/4-policy-context-variables#policy.predefined-context-conn-global).
+If client certificate verification fails, the SMTP session does not terminate. The TLS status is stored in predefined context validation variables, so it is possible to drive TLS policy from policy scripts. You can use this to reject messages when client verification failed. For more information regarding the TLS-related context variables, see [“Global Predefined Connection Context Variables”](/momentum/4/4-policy-context-variables#policy.predefined-context-conn-global).

content/momentum/4/tls-option.md

@@ -1,5 +1,5 @@
 ---
-lastUpdated: "03/26/2020"
+lastUpdated: "09/20/2023"
 title: "Outbound TLS"
 description: "A recent initiative among the large IS Ps and receiving domains is to use Transport Layer Security protocol TLS by default for mail traffic TLS is a standard for providing cryptographic protection of communication sessions between two systems It is derived from the earlier standard Secure Sockets Layer SSL and..."
 ---
@@ -32,6 +32,8 @@ By default, TLS is disabled. To use TLS, you must change the `TLS` option in the
 
 *   [tls_ciphers](/momentum/4/config/tls-ciphers)
 
+*   [tlsv13_ciphersuites](/momentum/4/config/tlsv13-ciphersuites)
+
 *   [tls_dhparams_file](/momentum/4/config/ref-tls-dhparams-file)
 
 *   [tls_enable_dhe_ciphers](/momentum/4/config/ref-tls-enable-dhe-ciphers)
@@ -69,4 +71,4 @@ binding "customer-1" {
 
 ### <a name="tls_option.logging"></a> Logging Macros
 
-A number of macros are available to enable logging of details about the TLS session used for a delivery attempt. To use these macros, you must load the tls_macros module. See [“tls_macros – TLS-related Logging”](/momentum/4/4-tls-macros).
+A number of macros are available to enable logging of details about the TLS session used for a delivery attempt. To use these macros, you must load the tls_macros module. See [“tls_macros – TLS-related Logging”](/momentum/4/4-tls-macros).