EOP-209: DANE doc (#767)

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"
+---
+
+<a name="config.enable-dane"></a>
+## 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.

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,13 +221,15 @@ 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 |
 | [transfail_drain_rate](/momentum/4/config/ref-transfail-drain-rate) | the maximum number of messages to pop off the transient failure queue in a single scheduler iteration |
 | [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 |

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 |

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.

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"
+---
+
+<a name="config.use-dane"></a>
+## 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.

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)).
+
+### <a name="modules.dane.configuration.example"></a> 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
+

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 |

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 |   |   |  ✓ |   |
+| [“url_ripper – URL Extraction”](/momentum/4/modules/url-ripper) | 4.0 | A toolkit for DNS-based content correlation |   |   |  ✓ |   |

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: