Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

SD-3987: add config option TLSv13_Ciphersuites #749

Merged
merged 5 commits into from
Oct 26, 2023
Merged

SD-3987: add config option TLSv13_Ciphersuites #749

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
abb6cc3
add config option TLSv13_Ciphersuites
juliebin Sep 20, 2023
35d6072
minor update
juliebin Sep 20, 2023
7cea18e
minor update
juliebin Sep 20, 2023
b62fe31
lastUpdated
juliebin Sep 20, 2023
4f1d513
minor change from review comment
juliebin Oct 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion content/momentum/4/config-options-summary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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..."
---
Expand Down Expand Up @@ -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 |
Expand Down
3 changes: 2 additions & 1 deletion content/momentum/4/config/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
lastUpdated: "09/14/2021"
lastUpdated: "09/20/2023"
title: "Category File"
type: "custom"
name: "Configuration Options Reference"
Expand Down Expand Up @@ -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 |
deepakpn marked this conversation as resolved.
Show resolved Hide resolved
| [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 |
Expand Down
10 changes: 6 additions & 4 deletions content/momentum/4/config/tls-protocols.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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..."
---
Expand All @@ -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"`

Expand All @@ -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.
62 changes: 62 additions & 0 deletions content/momentum/4/config/tlsv13-ciphersuites.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "(if not explicitly specified through this configuration option)" seems redundant, especially since you state the default again below.

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.
kkelley1 marked this conversation as resolved.
Show resolved Hide resolved
6 changes: 4 additions & 2 deletions content/momentum/4/inbound-tls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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..."
---
Expand Down Expand Up @@ -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)
Expand All @@ -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).
6 changes: 4 additions & 2 deletions content/momentum/4/tls-option.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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..."
---
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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).
Loading