diff --git a/content/momentum/4/4-console-commands.md b/content/momentum/4/4-console-commands.md index 3570e8fd9..4136666f6 100644 --- a/content/momentum/4/4-console-commands.md +++ b/content/momentum/4/4-console-commands.md @@ -118,6 +118,9 @@ This table lists all console commands alphabetically giving a brief description. | [message retry](/momentum/4/console-commands/message-retry) – Perform an immediate delivery attempt on a message | 4.0 |   | message | | [module hooks](/momentum/4/console-commands/4-module) – Manage loaded module hooks | 4.0 |   | module | | [module list](/momentum/4/console-commands/4-module) – Show loaded modules | 4.0 |   | module | +| [mta_sts list all](/momentum/4/console-commands/mta-sts) – list active domains which have MTA-STS policy | 4.8 |   | mta-sts | +| [mta_sts show domain](/momentum/4/console-commands/mta-sts) – show MTA-STS policy details for a domain | 4.8 |   | mta-sts | +| [mta_sts refresh policy](/momentum/4/console-commands/mta-sts) – refresh MTA-STS policy for a domain | 4.8 |   | mta-sts | | [outbound_audit:instance_name clear all](/momentum/4/modules/outbound-audit#modules.outbound_audit.console) – Zero-out all statistics | 4.0 | outbound_audit | module | | [outbound_audit:instance_name clear domain](/momentum/4/modules/outbound-audit#modules.outbound_audit.console) – Zero-out a domain's statistics | 4.0 | outbound_audit | module | | [outbound_audit:instance_name domain_list](/momentum/4/modules/outbound-audit#modules.outbound_audit.console) – Runtime addition/deletion of a domain in the monitoring list | 4.0 | outbound_audit | module | @@ -160,4 +163,4 @@ This table lists all console commands alphabetically giving a brief description. | [trace smtp remove](/momentum/4/console-commands/trace-smtp) – Remove an SMTP trace | 4.0 |   | misc | | [unlink stats](/momentum/4/console-commands/unlink-stats) – Show statistics of removing messages from the disk | 4.0 |   | stats | | [version](/momentum/4/console-commands/version) – Show version information of Momentum | 4.0 |   | misc | -| [write config](/momentum/4/console-commands/write-config) – Display current running configuration | 4.0 |   | config | \ No newline at end of file +| [write config](/momentum/4/console-commands/write-config) – Display current running configuration | 4.0 |   | config | diff --git a/content/momentum/4/config-options-summary.md b/content/momentum/4/config-options-summary.md index cca6110c6..33915dcbc 100644 --- a/content/momentum/4/config-options-summary.md +++ b/content/momentum/4/config-options-summary.md @@ -149,6 +149,7 @@ The `Version` column indicated the version(s) of Momentum that support the optio | [enable_authorization](/momentum/4/control-authz) – Whether or not to enable authorization for console commands | receiving |   | 4.0 and later | control_listener, listen, peer | | [enable_duravip](/momentum/4/4-cluster-config-duravip) – Whether to enable Durable MultiVIP© bindings (cluster-specific) | both |   | 4.0 and later | binding, listen | | [enable_fbl_header_insertion](/momentum/4/config/ref-enable-fbl-header-insertion) – Enable or disable fbl header insertion | sending |   | 4.0 and later | binding, binding_group, domain, global | +| [enable_mta_sts](/momentum/4/config/mta-sts/enable-mta-sts) – Enable or disable MTA-STS policy application | sending |   | 4.8 and later | binding, binding_group, domain, global | | **enabled** – Whether or not the module is enabled (cluster-specific) | na | true | 4.0 and later | cluster | | [error](/momentum/4/config/ref-debug-flags) – Set the debug level | na | ALL | 4.0 and later | debug_flags | | [esmtp_listener](/momentum/4/esmtp-listener) *(scope)* – Listener for incoming SMTP connections | receiving |   | 4.0 and later | global | @@ -237,6 +238,8 @@ The `Version` column indicated the version(s) of Momentum that support the optio | [max_resident_active_queue](/momentum/4/config/ref-max-resident-active-queue) – Threshold above which messages are not held in memory | sending | 250 | 4.0 and later | binding, binding_group, domain, global | | [max_resident_messages](/momentum/4/config/ref-max-resident-messages) – Threshold above which messages are not held in memory | sending | 32768 | 4.0 and later | binding, binding_group, global | | [max_resident_transfails](/momentum/4/config/ref-max-resident-transfails) – If the transient failure queue grows beyond this size, messages are swapped out of memory | sending | 100 | 4.0 and later | global | +| [mta_sts_dns_cname_max_depth](/momentum/4/config/mta-sts/mta-sts-dns-cname-max-depth) – Maximum number of continous CNAME lookups allowed while doing MTA-STS DNS lookup | sending | 5 | 4.8 and later | global | +| [mta_sts_policy_store](/momentum/4/config/mta-sts/mta-sts-policy-store) – Directory to store MTA-STS policy files | sending | /var/spool/ecelerity/mtasts (*non-dynamic*) | 4.8 and later | global | | [swap_out_meta_after_each_tempfail](/momentum/4/config/ref-swap-out-meta-after-each-tempfail) – If this is set to false, Momentum will only update metadata on disk after each tempfail if the message context is dirty, and the num_retires, next_attempt and message context may not be accurate if Momentum crashes | sending | true | 4.3.1 and later | global | | [max_retries](/momentum/4/config/ref-max-retries) – Override the system configured max_retries | sending |   | 4.0 and later | binding, binding_group, domain, global | | [max_retry_interval](/momentum/4/config/ref-max-retry-interval) – Maximum retry interval | sending | 43200 | 4.0 and later | binding, binding_group, domain, global | @@ -365,6 +368,7 @@ The `Version` column indicated the version(s) of Momentum that support the optio | [use_iflist_cache](/momentum/4/config/ref-use-iflist-cache) – Whether or not to cache the list of interfaces configured by the system | sending | 0 (*non-dynamic*) | 4.0 and later | global | | [use_ipv6](/momentum/4/config/ref-use-ipv-6) – Affects the selection of IPv6 hosts in the SMTP client | sending | false | 4.0 and later | global | | [use_mmap](/momentum/4/config/ref-use-mmap) – Use mmap when spooling messages from disk | na | false | 4.0 and later | global | +| [use_mta_sts](/momentum/4/config/mta-sts/use-mta-sts) – Enable MTA-STS policy fetching on a domain | sending | false | 4.8 and later | global, domain | | [use_sendfile](/momentum/4/config/ref-use-sendfile) – Use sendfile() when sending mail | sending | false | 4.0 and later | global | | **use_ssl** – Whether or not to use SSL verification | receiving | false | 4.0 and later | ecstream_listener, esmtp_listener, http_listener, listen, pathway, pathway_group, peer | | [user](/momentum/4/config/ref-user) – User identity to assume after startup | na | ecuser (*non-dynamic*) | 4.0 and later | security | 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 5f820d160..e9527aa35 100644 --- a/content/momentum/4/config/index.md +++ b/content/momentum/4/config/index.md @@ -75,7 +75,9 @@ 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 | | [eventloop](/momentum/4/config/ref-eventloop) | define a pool of event loops to enable multiple event loop configuration | | [events_per_iter](/momentum/4/config/ref-events-per-iter) | employ when using a concurrency greater than 1. | @@ -136,6 +138,8 @@ description: "This chapter provides the definitions of the configuration options | [migrate_connections_between_sibling_domains](/momentum/4/config/ref-migrate-connections-between-sibling-domains) | optimize connections for sibling domains | | [mime_parse_large_messages_during_reception](/momentum/4/config/ref-mime-parse-large-messages-during-reception) | configure whether large messages are parsed upon reception or just in time. | | [min_dns_ttl](/momentum/4/config/ref-min-dns-ttl) | override DNS TTLs smaller than this value | +| [mta_sts_dns_cname_max_depth](/momentum/4/config/mta-sts/mta-sts-dns-cname-max-depth) | the maximum number of continuous CNAME lookups while doing MTA-STS DNS TXT lookup | +| [mta_sts_policy_store](/momentum/4/config/mta-sts/mta-sts-policy-store) | the directory to store MTA-STS policy files | | [mx_failures_fallback_to_a](/momentum/4/config/ref-mx-failures-fallback-to-a) | configure the maximum number of times an MX lookup will be attempted | | [mx_failures_to_delay](/momentum/4/config/ref-mx-failures-to-delay) | number of consecutive failures before a domain is auto-delayed | | [never_attempt_expired_messages](/momentum/4/config/ref-never-attempt-expired-messages) | Never attempt delivery of expired messages | @@ -217,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 | @@ -224,9 +229,11 @@ 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 | +| [use_mta_sts](/momentum/4/config/mta-sts/use-mta-sts) | fetch MTA-STS policy for a domain | | [use_sendfile](/momentum/4/config/ref-use-sendfile) | use sendfile() when sending mail | | [user](/momentum/4/config/ref-user) | security: user identity to assume after startup | | [xclient](/momentum/4/config/ref-xclient) | use the xclient extension to SMTP for outbound mail | diff --git a/content/momentum/4/config/mta-sts/enable-mta-sts.md b/content/momentum/4/config/mta-sts/enable-mta-sts.md new file mode 100644 index 000000000..8f4197d97 --- /dev/null +++ b/content/momentum/4/config/mta-sts/enable-mta-sts.md @@ -0,0 +1,42 @@ +--- +lastUpdated: "06/01/2024" +title: "enable_mta_sts" +description: "config option to enable MTA-STS policy application for outbound mails" +--- + + +## Name + +enable_mta_sts — specify whether Momentum should apply MTA-STS policies for outbound emails. + +## Synopsis + +`enable_mta_sts = "true|false"` + +## Description + +This option is only effective when [use_mta_sts](/momentum/4/config/mta-sts/use-mta-sts) is `true` +for a recipient domain. +This option specifies whether Momentum should try to apply the retrieved MTA-STS policy when sending +emails to a remote site. See [MTA-STS support in Momentum](/momentum/4/mta-sts) for more details. + + +When this option is `true`, the MTA-STS policy mode will be considered along with the configuration + values for [TLS](/momentum/4/config/ref-tls) and [TLS_Verify](/momentum/4/config/tls-verify). + The more strict policy will apply: + +- When the MTA-STS policy mode is `enforce`, regardless of the + values for `TLS` and `TLS_Verify`, Momentum will enforce TLS (equivalent to `TLS = required`) and + will fail the delivery upon a failed certificate validation (equivalent to `TLS_Verify = host`). +- When the MTA-STS policy mode is `testing`, Momentum will apply `TLS = ifavailable` (unless + `TLS = required` is specified) and `TLS_Verify = optional` (unless `TLS_Verify = host` is + specified). +- When the MTA-STS policy mode is `none`, the policy will be ignored and the configuration values for + `TLS` and `TLS_Verify` will be respected. + +The default value is `true` when `use_mta_sts` is `true` for a domain. + + +## Scope + +`enable_mta_sts` is valid in the domain, binding, binding_group, and global scopes. diff --git a/content/momentum/4/config/mta-sts/index.md b/content/momentum/4/config/mta-sts/index.md new file mode 100644 index 000000000..391faeb2b --- /dev/null +++ b/content/momentum/4/config/mta-sts/index.md @@ -0,0 +1,14 @@ +--- +lastUpdated: "06/01/2024" +title: "Category File" +type: "custom" +name: "MTA-STS Configuration Options Reference" +description: "MTA-STS configuration Options index" +--- + +- [use_mta_sts](/momentum/4/config/mta-sts/use-mta-sts) +- [enable_mta_sts](/momentum/4/config/mta-sts/enable-mta-sts) +- [mta_sts_dns_cname_max_depth](/momentum/4/config/mta-sts/mta-sts-dns-cname-max-depth) +- [mta_sts_policy_store](/momentum/4/config/mta-sts/mta-sts-policy-store) + + diff --git a/content/momentum/4/config/mta-sts/mta-sts-dns-cname-max-depth.md b/content/momentum/4/config/mta-sts/mta-sts-dns-cname-max-depth.md new file mode 100644 index 000000000..29e4c8630 --- /dev/null +++ b/content/momentum/4/config/mta-sts/mta-sts-dns-cname-max-depth.md @@ -0,0 +1,31 @@ +--- +lastUpdated: "06/01/2024" +title: "mta_sts_dns_cname_max_depth" +description: "config option on how many continuous CNAME lookups are allowed when doing MTA-STS TXT +record lookup for a domain" +--- + + +## Name + +mta_sts_dns_cname_max_depth — specifies how many continuous `CNAME` lookups are allowed when doing DNS + lookups for MTA-STS TXT record for a domain. Exceeding the configured value will be treated as a DNS + lookup failure, which will be further treated as no MTA-STS policy available. + +## Synopsis + +`mta_sts_dns_cname_max_depth = 5` + +## Description + +Momentum supports MTA-STS policy delegation, which points the `_mta-sts` TXT record for the policy + domain via `CNAME` (to the `_mta-sts` record maintained by the provider). Momentum's DNS lookup + will follow the `CNAME`s. To avoid a DNS lookup loop, Momentum uses this config option to limit how + many continuous `CNAME` lookups can happen before claiming a lookup failure. + +The default value is `5`. + + +## Scope + +`mta_sts_dns_cname_max_depth` is valid in the domain and global scopes. diff --git a/content/momentum/4/config/mta-sts/mta-sts-policy-store.md b/content/momentum/4/config/mta-sts/mta-sts-policy-store.md new file mode 100644 index 000000000..188409941 --- /dev/null +++ b/content/momentum/4/config/mta-sts/mta-sts-policy-store.md @@ -0,0 +1,27 @@ +--- +lastUpdated: "06/01/2024" +title: "mta_sts_policy_store" +description: "the location to store the MTA-STS policy" +--- + + +## Name + +mta_sts_policy_store — specifies the location to keep the MTA-STS policy details for the domains. + +## Synopsis + +`mta_sts_policy_store = "/var/spool/ecelerity/mtasts"` + +## Description + +Momentum stores MTA-STS policy for a domain in a file on disk, and accesses the HTTPS endpoint to refresh the + policy once every 24 hours. This config option specifies the directory where the policies are stored + on the disk. + +The default value is `/var/spool/ecelerity/mtasts`. + + +## Scope + +`mta_sts_policy_store` is valid in the global scope. diff --git a/content/momentum/4/config/mta-sts/use-mta-sts.md b/content/momentum/4/config/mta-sts/use-mta-sts.md new file mode 100644 index 000000000..ed6f1ab08 --- /dev/null +++ b/content/momentum/4/config/mta-sts/use-mta-sts.md @@ -0,0 +1,27 @@ +--- +lastUpdated: "06/01/2024" +title: "use_mta_sts" +description: "config option to enable MTA-STS policy fetching for a domain" +--- + + +## Name + +use_mta_sts — specify whether Momentum should do MTA-STS policy fetching for a domain. + +## Synopsis + +`use_mta_sts = "true|false"` + +## Description + +This option specifies whether Momentum shall attempt to discover the recipient domain's MTA-STS + policy (via a DNS TXT lookup to retrieve the MTA-STS policy ID and a HTTPS lookup to retrieve the + MTA-STS policy). + +The default value is `false`. + + +## Scope + +`use_mta_sts` is valid in the domain and global scopes. diff --git a/content/momentum/4/config/ref-debug-flags.md b/content/momentum/4/config/ref-debug-flags.md index 666d5c739..cacdd02f6 100644 --- a/content/momentum/4/config/ref-debug-flags.md +++ b/content/momentum/4/config/ref-debug-flags.md @@ -28,11 +28,21 @@ Debug_Flags { CRITICAL = (TIME FD SMTP LOG1 DNS DNSDS NET SIG MEM DB LIC SSL MOD START ALL) } ``` - ### Note - Use ‘`ALL`’ instead of listing each service debug flag. + +The example below enables more (at `WARNING` level) MTA-STS and SSL related logging, along with default +`ERROR` and `CRITICAL` loggings: +``` +Debug_Flags { + WARNING = (MTA_STS SSL) + ERROR = (ALL) + CRITICAL = (ALL) +} +``` + + @@ -55,8 +65,10 @@ Use ‘`ALL`’ instead of listing each service debug flag. | File Descriptors | FD | | SMTP | SMTP | | LOG1 | LOG1 | +| DANE | DANE | | DNS | DNS | | DNS data structures | DNSDS | +| MTA-STS | MTA_STS | | Network | NET | | Signals | SIG | | Memory Management | MEM | @@ -69,4 +81,4 @@ Use ‘`ALL`’ instead of listing each service debug flag. ## Scope -debug_flags is valid in the global scope. \ No newline at end of file +debug_flags is valid in the global scope. 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/console-commands/index.md b/content/momentum/4/console-commands/index.md index d9219f1ce..1eb37278b 100644 --- a/content/momentum/4/console-commands/index.md +++ b/content/momentum/4/console-commands/index.md @@ -1,5 +1,5 @@ --- -lastUpdated: "02/09/2021" +lastUpdated: "06/01/2024" title: "Category File" type: "custom" name: "Non-Module-Specific Console Commands" @@ -44,6 +44,7 @@ description: "This section documents all the non module specific console command | [message fail quiet](/momentum/4/console-commands/message-fail-quiet) | fail a message and do not create a non-delivery receipt (NDR) | | [message retry](/momentum/4/console-commands/message-retry) | perform an immediate delivery attempt on a message | | [module](/momentum/4/console-commands/4-module) | manage loaded modules online | +| [mta_sts](/momentum/4/console-commands/mta_sts) | commands to display and manage MTA-STS policy for a domain | | [\pager](/momentum/4/console-commands/pager) | Page output of long console commands in the console. | | [paniclog](/momentum/4/console-commands/paniclog) | show last several entries written to paniclog | | [pid](/momentum/4/console-commands/pid) | show process id of Momentum | diff --git a/content/momentum/4/console-commands/mta-sts.md b/content/momentum/4/console-commands/mta-sts.md new file mode 100644 index 000000000..ea7bd0516 --- /dev/null +++ b/content/momentum/4/console-commands/mta-sts.md @@ -0,0 +1,53 @@ +--- +lastUpdated: "06/01/2024" +title: "mta_sts" +description: "mta_sts ec_console commands" +--- + + +## Name + +mta_sts - commands for MTA-STS related data. + +## Synopsis + +`mta_sts list all` + +`mta_sts show domain {domain name}` + +`mta_sts refresh policy {domain name}` + +## Description + +**mta_sts list all** - lists all the active domains which have MTA-STS policies + +``` +15:42:38 /tmp/2025> mta_sts list all +gmail.com +Total domains: 1 +``` + +**mta_sts show domain { domain name }** - shows MTA-STS TXT record and policy details of a given domain. + The same content will be shown in [domain](/momentum/4/console-commands/domain) command output also, if + available. + + +``` +18:13:43 /tmp/2025> mta_sts show domain gmail.com +Domain 'gmail.com' has MTA-STS TXT and a TTL of 185 seconds + id: 20190429T010101 + max_age: 86400 seconds; refresh in 86375 seconds + mode: enforce + mxlist: + gmail-smtp-in.l.google.com + *.gmail-smtp-in.l.google.com +``` + +**mta_sts refresh policy {domain name}** - forces MTA-STS policy refresh by fetching the policy + from the HTTPS endpoint for a given domain. + + +``` +18:14:41 /tmp/2025> mta_sts refresh policy gmail.com +MTA-STS policy for gmail.com refreshed. +``` 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/4/mta-sts.md b/content/momentum/4/mta-sts.md new file mode 100644 index 000000000..2f3fe210b --- /dev/null +++ b/content/momentum/4/mta-sts.md @@ -0,0 +1,100 @@ +--- +lastUpdated: "06/01/2024" +title: "MTA-STS support" +description: "MTA-STS support" +--- + +MTA-STS (MTA Strict Transport Security) improves email security by requiring authentication +checks and encryption for delivering email. RFC 8461 describes the use of MTA-STS for improving +SMTP security between MTAs. Momentum starts to support MTA-STS in 4.8. + +If the config option [use_mta_sts](/momentum/4/config/mta-sts/use-mta-sts) for a domain is set to `true`, + Momentum will attempt to discover the recipient domain's MTA-STS policy + (via a DNS lookup to retrieve the MTA-STS policy ID and a HTTPS lookup to retrieve the + MTA-STS policy), and if the [enable_mta_sts](/momentum/4/config/mta-sts/enable-mta-sts) + for the binding/domain is `true`, Momentum will apply the MTA-STS policy for validating + the connection to the remote site. + If the recipient domain enforces MTA-STS, Momentum delivers email to the remote + domain's MX if and only if the following conditions are satisfied: + - remote site matches at least one of the MX patterns defined in the recipient domain's MTA-STS + policy + - connection to remote site can be encrypted (via the use of STARTTLS) + - Momentum can authenticate both: the certificate chain presented by the server on the connection, + and the server name in the certificate + +For verifying certificates, Momentum uses the configured CA for outbound email defined by + [TLS_CA](/momentum/4/config/tls-ca). + Momentum does *not* currently check for certificate revocation via the Online Certificate Status +Protocol (RFC 6960). + +Momentum caches the MTA-STS policy for up to `max-age` specified in the policy, and attempts to +refresh the cached policy once every 24 hours. + +Momentum does *not* currently implement SMTP TLS Reporting (RFC 8460). + +The examples below illustrate a few cases describing how Momentum implements MTA-STS. +For all examples the recipient domain would be `domain.com`. + +### Example 1: Recipient domain enforces MTA-STS and MX is allowed as per the MTA-STS policy + +> **MTA-STS policy retrieved from `https://mta-sts.domain.com/.well-known/mta-sts.txt`** +``` +version: STSv1 +mode: enforce +mx: *.domain.com +max_age: 86400 +``` +> **DNS results for domain's MX lookup** +``` +mx1.domain.com +``` +> **Explanation** +> Momentum attempts to deliver email to `mx1.domain.com` as it matches at least one of the +MX patterns defined in the MTA-STS policy. + +### Example 2: Recipient domain enforces MTA-STS and MX is not allowed as per the MTA-STS policy + +> **MTA-STS policy retrieved from `https://mta-sts.domain.com/.well-known/mta-sts.txt`** +``` +version: STSv1 +mode: enforce +mx: *.domain.com +max_age: 86400 +``` +> **DNS results for domain's MX lookup** +``` +mx1.other.com +``` +> **Explanation** +> Momentum does not attempt to deliver email to `mx1.other.com` as it does not match any of the +MX patterns defined in the MTA-STS policy. + +### Example 3: Recipient domain does not enforce MTA-STS and MX is not allowed as per the MTA-STS +policy + +> **MTA-STS policy retrieved from `https://mta-sts.domain.com/.well-known/mta-sts.txt`** +``` +version: STSv1 +mode: testing +mx: *.domain.com +max_age: 86400 +``` +> **DNS results for domain's MX lookup** +``` +mx1.other.com +``` +> **Explanation** +> Momentum attempts to deliver email to `mx1.other.com` even though it does not match any of the +MX patterns defined in the MTA-STS policy since the policy mode is not `enforce`. + + +## Related Configuration Options +- [MTA-STS configuration options](/momentum/4/config/mta-sts) + + +## Related [Debug_Flags](/momentum/4/config/ref-debug-flags) +- MTA_STS + + +## ec_console commands +- [mta_sts](/momentum/4/console-commands/mta-sts) diff --git a/content/momentum/navigation.yml b/content/momentum/navigation.yml index ad8832b87..0ca1eae86 100644 --- a/content/momentum/navigation.yml +++ b/content/momentum/navigation.yml @@ -511,6 +511,10 @@ title: Sending Emails as CC and BCC - link: /momentum/4/complex-template 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: @@ -2007,4 +2011,4 @@ - link: /momentum/changelog/legacy/message-central title: Message Central Legacy Changelog - link: /momentum/changelog/legacy/message-scope - title: Message Scope Legacy Changelog \ No newline at end of file + title: Message Scope Legacy Changelog