From 9827faf76c5776b18707458210997f7ca343c3d0 Mon Sep 17 00:00:00 2001 From: Julie Zhao Date: Mon, 8 Jul 2024 12:51:46 -0400 Subject: [PATCH] EOP-209: DANE doc (#767) --- content/momentum/4/config/enable-dane.md | 29 +++++ content/momentum/4/config/index.md | 3 + content/momentum/4/config/ref-debug-flags.md | 1 + .../momentum/4/config/tlsa-expire-interval.md | 26 +++++ content/momentum/4/config/use-dane.md | 30 ++++++ content/momentum/4/modules/dane.md | 100 ++++++++++++++++++ content/momentum/4/modules/index.md | 1 + .../momentum/4/modules/summary-all-modules.md | 3 +- content/momentum/navigation.yml | 2 + 9 files changed, 194 insertions(+), 1 deletion(-) create mode 100644 content/momentum/4/config/enable-dane.md create mode 100644 content/momentum/4/config/tlsa-expire-interval.md create mode 100644 content/momentum/4/config/use-dane.md create mode 100644 content/momentum/4/modules/dane.md diff --git a/content/momentum/4/config/enable-dane.md b/content/momentum/4/config/enable-dane.md new file mode 100644 index 000000000..0765917f7 --- /dev/null +++ b/content/momentum/4/config/enable-dane.md @@ -0,0 +1,29 @@ +--- +lastUpdated: "06/01/2024" +title: "enable_dane" +description: "config option to enable application of DANE TLS verification for outbound mails" +--- + + +## Name + +enable_dane — specify whether Momentum should apply DANE TLS verification for outbound emails + +## Synopsis + +`enable_dane = "true|false"` + +## Description + +This option is only effective when [dane module](/momentum/4/modules/dane) is configured and + [use_dane](/momentum/4/config/use-dane) is `true` for a recipient domain. + +This option specifies whether Momentum should try to apply the DANE TLS verification rules defined + in TLSA record when sending emails to a remote site. + +The default value is `true` when `use_dane` is `true` for a domain. + + +## Scope + +`enable_dane` is valid in the binding, binding_group, domain and global scopes. diff --git a/content/momentum/4/config/index.md b/content/momentum/4/config/index.md index b2d056c29..e9527aa35 100644 --- a/content/momentum/4/config/index.md +++ b/content/momentum/4/config/index.md @@ -75,6 +75,7 @@ description: "This chapter provides the definitions of the configuration options | [ecstream_timeout](/momentum/4/config/ref-ecstream-timeout) | the amount of time to wait for an ecstream connection to be established | | [ehlo_hostname](/momentum/4/config/ref-ehlo-hostname) | set the hostname used for EHLO in outbound mail | | [ehlo_timeout](/momentum/4/config/ref-ehlo-timeout) | network timeout for EHLO | +| [enable_dane](/momentum/4/config/enable-dane) | enable application of DANE TLS verification on email delivery to a remote domain | | [enable_fbl_header_insertion](/momentum/4/config/ref-enable-fbl-header-insertion) | enable or disable fbl header insertion | | [enable_mta_sts](/momentum/4/config/mta-sts/enable-mta-sts) | enable application of MTA-STS policy on email delivery to a remote domain | | [event_loop](/momentum/4/config/ref-event-loop) | associate a pool of event loops within a listener scope to use multiple threads | @@ -220,6 +221,7 @@ description: "This chapter provides the definitions of the configuration options | [tls_verified_peer_is_authorized](/momentum/4/config/tls-verified-peer-is-authorized) | Marks requests that use a verified SSL Client certificate as being authorized | | [tls_verify](/momentum/4/config/tls-verify) | specify how to handle the remote presented certificate | | [tls_verify_mode](/momentum/4/config/tls-verify-mode) | determine whether a TLS certificate is required | +| [tlsa_expire_interval](/momentum/4/config/tlsa-expire-interval) | how often to check for expired TLSA records | | [trace_smtp_mode](/momentum/4/config/ref-trace-smtp-mode) | set the default permissions of trace files | | [tracking_domain](/momentum/4/config/tracking-domain) | set the tracking domain to use for engagement tracking in SMTP injections | | [tracking_link_expiry](/momentum/4/config/tracking-link-expiry) | set the expiration time for engagement tracking for SMTP injections | @@ -227,6 +229,7 @@ description: "This chapter provides the definitions of the configuration options | [transform_8bitmime_content](/momentum/4/config/ref-transform-8-bitmime-content) | Enable 8BITMIME downconversion when sending mail | | [unlink_on_spool_in_failure](/momentum/4/config/ref-unlink-on-spool-in-failure) | Whether or not to remove malformed messages | | [_unsafe_spool](/momentum/4/config/ref-unsafe-spool) | allow dangerous spool semantics to be used | +| [use_dane](/momentum/4/config/use-dane) | enable DNSSEC validation on MX/A records, if both secure, TLSA record is fetched and DNSSEC validation is done for a domain | | [use_iflist_cache](/momentum/4/config/ref-use-iflist-cache) | Whether or not to cache the list of network interfaces configured by the system | | [use_ipv6](/momentum/4/config/ref-use-ipv-6) | Affects the selection of IPv6 hosts in the SMTP client | | [use_mmap](/momentum/4/config/ref-use-mmap) | use mmap when spooling messages from disk | diff --git a/content/momentum/4/config/ref-debug-flags.md b/content/momentum/4/config/ref-debug-flags.md index 3bcd78525..cacdd02f6 100644 --- a/content/momentum/4/config/ref-debug-flags.md +++ b/content/momentum/4/config/ref-debug-flags.md @@ -65,6 +65,7 @@ Debug_Flags { | File Descriptors | FD | | SMTP | SMTP | | LOG1 | LOG1 | +| DANE | DANE | | DNS | DNS | | DNS data structures | DNSDS | | MTA-STS | MTA_STS | diff --git a/content/momentum/4/config/tlsa-expire-interval.md b/content/momentum/4/config/tlsa-expire-interval.md new file mode 100644 index 000000000..903e14912 --- /dev/null +++ b/content/momentum/4/config/tlsa-expire-interval.md @@ -0,0 +1,26 @@ +--- +lastUpdated: "06/01/2024" +title: "tlsa_expire_interval" +description: "tlsa expire interval how often to check for expired TLSA DNS records" +--- + +## Name + +tlsa_expire_interval — how often to check for expired TLSA records + +## Synopsis + +`tlsa_expire_interval = 3600` + +## Description + +How often the garbage collector should check for expired TLSA records. During email delivery, + a related TLSA record will be checked for expiration and removed from memory if expired. + The purpose of garbage collection controlled by this configuration option is to retire + the stale TLSA records which are not actively in use. + +The default is `3600` seconds. + +## Scope + +`tlsa_expire_interval` is valid in the global scope. diff --git a/content/momentum/4/config/use-dane.md b/content/momentum/4/config/use-dane.md new file mode 100644 index 000000000..de88605ac --- /dev/null +++ b/content/momentum/4/config/use-dane.md @@ -0,0 +1,30 @@ +--- +lastUpdated: "06/01/2024" +title: "use_dane" +description: "config option to enable DANE TLSA DNS lookup for a domain" +--- + + +## Name + +use_dane — specify whether Momentum should check DNS record DNSSEC status and look up TLSA + records if applicable. + +## Synopsis + +`use_dane = "true|false"` + +## Description + +This option is only effective when [dane module](/momentum/4/modules/dane) is configured. + +This option specifies whether Momentum shall check the DNSSEC status of a domain's MX and A record, + and if both pass DNSSEC validation, corresponding TLSA record will be fetched and DNSSEC status + checked. + +The default value is `false`. + + +## Scope + +`use_dane` is valid in the domain and global scopes. diff --git a/content/momentum/4/modules/dane.md b/content/momentum/4/modules/dane.md new file mode 100644 index 000000000..21092cdbd --- /dev/null +++ b/content/momentum/4/modules/dane.md @@ -0,0 +1,100 @@ +--- +lastUpdated: "06/01/2024" +title: "DANE support" +description: "DANE support TLSA DNSSEC" +--- + +The dane module handles DANE related DNS lookups and outbound STARTTLS enforcement and + verifications. + +DANE (DNS-Based Authentication of Named Entities) is a standard for improving transport security. + [RFC 7672](https://datatracker.ietf.org/doc/html/rfc7672) describes the use of DANE for improving + SMTP security between MTAs. + +Momentum has supported STARTTLS for a long time. The use of STARTTLS for establishing channel + security (encrypting the channel) can be achieved via the use of [tls](/momentum/4/config/ref-tls), + [tls_verify](/momentum/4/config/tls-verify) configuration options. + +DANE for SMTP security allows the remote side to enforce the use of STARTTLS whenever clients like + Momentum connect to the site to transfer email. RFC 7672 describes various methods through which + remote sites could advertise the availability of STARTTLS with them, and whether they require + the connecting clients to always use STARTTLS when communicating with them. + DANE requires that the DNS resolver support DNSSEC, a secure way of looking up DNS records. + Google DNS (8.8.8.8) is an example of a DNS lookup service that supports DNSSEC. + +Momentum 4.8 and above supports the use of DANE for enforcing SMTP security. + When DANE is enabled, Momentum must be configured with a DNS resolver that supports DNSSEC in order + for DANE to work properly. + If the new [dane module](/momentum/4/modules/dane) is enabled and the new directive + [use_dane](/momentum/4/config/use-dane) for a domain is set to `true`, + Momentum will lookup the remote site's STARTTLS preferences (through DNS resolution) and use that + information to influence whether STARTTLS is established or not with the remote site prior to + transferring email to it. If the remote site requires the use of STARTTLS, Momentum will only + transfer email to the remote site if STARTTLS was successful in establishing an encrypted channel + to the remote site. And, in accordance with the DANE standard, Momentum will attempt to verify + the certificate presented by the remote host during STARTTLS based on the fingerprints it obtained + through DNS TLSA records. If the remote site is strict about the use of STARTTLS, + and Momentum could not perform STARTTLS successfully (e.g, Momentum failed to verify that the + fingerprint of the certificate presented by the remote site matches the fingerprint of the + certificate specified in the TLSA DNS records), Momentum will not transfer email to the remote + server. Email is held in the queue until Momentum can establish STARTTLS successfully in accordance + with DANE protocol with the remote site. + +See RFC 7672 for more descriptions on how certificate matching is specified via the use of + TLSA DNS records. Please contact support if you have any further questions about DANE protocol. + +DANE works independently from and takes preference over the configuration controlled STARTTLS + behavior. + +When [MTA-STS](/momentum/4/mta-sts) is also enabled on a binding domain, + MTA-STS policy will apply to MX selection for + email delivery, but if secure TLSA record is available, only the DANE TLS validation will be + applied to establish the STARTTLS connection. If DANE TLS failed, no fallback to other + verification means (e.g. MTA-STS, or administrator configured STARTTLS behaviors defined by + [tls](/momentum/4/config/ref-tls) or [tls_verify](/momentum/4/config/tls-verify)). + +### Configuration + +You need to enable the dane module in the ecelerity configuration file to use the feature: + +``` +dane {} +``` + +### Note +With dane module enabled, you still need to have the following global/binding/domain scope + configuration options to fully enable the feature application on email sending. + +- [use_dane](/momentum/4/config/use-dane) +- [enable_dane](/momentum/4/config/enable-dane) + +The following configuration is the minimum needed to enable DANE TLSA lookup and TLS verification +for all domains: + +``` +dane {} +use_dane = true +``` + +[domain](/momentum/4/console-commands/domain) command is updated to show the TLSA record if available, + and a flag of `+dnssec` is added to each DNS record to indicate that they are DNSSEC + validated. An example is shown here: + +``` +Domain 'comcast.net' has 8 MXs and a TTL of 58 seconds +dnssec + [50 mx2c1.comcast.net. TTL:7198] +dnssec +TLSA '_25._tcp.mx2c1.comcast.net' has a TTL of 120 seconds +dnssec + 3 1 1 29b116c43593748345aa7f4c43717e792f94137a88b93d674de2ce1162f98625 + [96.102.18.146]:0 IPv4 (0.00ms con 0.00ms dlv)\ +... +``` + + +## Other DANE Related Configuration Options + +- [tlsa_expire_interval](/momentum/4/config/tlsa-expire-interval) + + +## Related [Debug_Flags](/momentum/4/config/ref-debug-flags) +- DANE + diff --git a/content/momentum/4/modules/index.md b/content/momentum/4/modules/index.md index 4fc70ceb1..164907132 100644 --- a/content/momentum/4/modules/index.md +++ b/content/momentum/4/modules/index.md @@ -34,6 +34,7 @@ description: "Table of Contents 71 1 Introduction 71 2 ac auth Authentication Ha | [csapi](/momentum/4/modules/csapi) | Symantec CSAPI Antivirus Support | | [custom_bounce_logger](/momentum/4/modules/custom-bounce-logger) | Custom Bounce Logging | | [custom_logger](/momentum/4/modules/custom-logger) | User-defined Logging | +| [dane](/momentum/4/modules/dane) | DANE related DNS Lookups and TLS Verifications | | [delay_dsn](/momentum/4/modules/delay-dsn) | Delay DSN Generation | | [dnsbuf](/momentum/4/modules/dnsbuf) | Dynamically Set the DNS UDP Buffer Size | | [domainkeys](/momentum/4/modules/domainkeys) | Yahoo! DomainKeys | diff --git a/content/momentum/4/modules/summary-all-modules.md b/content/momentum/4/modules/summary-all-modules.md index 5fd08877c..22031ab1b 100644 --- a/content/momentum/4/modules/summary-all-modules.md +++ b/content/momentum/4/modules/summary-all-modules.md @@ -38,6 +38,7 @@ All modules are listed alphabetically with a brief description. Singleton module | [“csapi – Symantec CSAPI Antivirus Support”](/momentum/4/modules/csapi) | 4.0 | Integration for Symantec content scanners |   |   |  ✓ |   | | [“custom_bounce_logger – Custom Bounce Logging”](/momentum/4/modules/custom-bounce-logger) | 4.2 | Append a "User_String" to the end of each bounce record |  ✓ |   |   | [“bounce_logger – Momentum-Style Bounce Logging”](/momentum/4/modules/bounce-logger) | | [“custom_logger – User-defined Logging”](/momentum/4/modules/custom-logger) | 4.0 | Create custom logs |   |   |   |   | +| ["dane - DNS-based Authentication of Named Entities"](/momentum/4/modules/dane) | 4.8 | Support for DANE |   |   |   |   | | [“delay_dsn – Delay DSN Generation”](/momentum/4/modules/delay-dsn) | 4.0 | Configure and send delay DSNs |   |   |   |   | | [dk_sign](/momentum/4/modules/domainkeys) | 4.0 | Attach domain keys signatures to outbound mail |   |   |  ✓ |   | | [dk_validate](/momentum/4/modules/domainkeys) | 4.0 | Validate inbound mail checking domain keys signatures |   |   |  ✓ |   | @@ -97,4 +98,4 @@ All modules are listed alphabetically with a brief description. Singleton module | [“suppress_spool – Deferred Message Spooling”](/momentum/4/modules/suppress-spool) | 4.0 | Defer spool attempts |   |   |   |   | | [“syslog_io – The syslog_io Module”](/momentum/4/modules/syslog-io) (*singleton*) | 4.0 | Use the syslog wrapper to write entries to the log |  ✓ |   |   |   | | [“tls_macros – TLS-related Logging”](/momentum/4/4-tls-macros) | 4.0 | Provide several macros supporting custom logging of TLS-related data |   |   |   |   | -| [“url_ripper – URL Extraction”](/momentum/4/modules/url-ripper) | 4.0 | A toolkit for DNS-based content correlation |   |   |  ✓ |   | \ No newline at end of file +| [“url_ripper – URL Extraction”](/momentum/4/modules/url-ripper) | 4.0 | A toolkit for DNS-based content correlation |   |   |  ✓ |   | diff --git a/content/momentum/navigation.yml b/content/momentum/navigation.yml index 4340432dc..0ca1eae86 100644 --- a/content/momentum/navigation.yml +++ b/content/momentum/navigation.yml @@ -513,6 +513,8 @@ title: Using Complex Templates - link: /momentum/4/mta-sts title: MTA-STS support + - link: /momentum/4/modules/dane + title: DANE support - link: /momentum/4/http-api-stats title: Stats HTTP API items: