TASK-10736: Documentation of new features and changelog of Momentum 5.1 #800
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,123 @@ | ||
| --- | ||
| lastUpdated: "05/10/2025" | ||
| title: "smtp_tls_reporting" | ||
| description: "hook invoked after every TLS events for reporting purpose rfc8460 TLSRPT" | ||
| --- | ||
|
|
||
| <a name="hooks.core.smtp_tls_reporting"></a> | ||
| ## Name | ||
|
|
||
| smtp_tls_reporting - This hook is added in 5.1 and allows you inspect a SMTP TLS reporting data | ||
| point in JSON format. | ||
|
|
||
| ## Synopsis | ||
|
|
||
| `#include "hooks/core/smtp_tls_reporting.h"` | ||
|
|
||
| `int core_smtp_tls_reporting(void closure, struct json_object *json)` | ||
|
|
||
|
|
||
| ## Description | ||
|
|
||
| This hook is called upon: | ||
| - any TLSRPT (rfc8460) defined failures, before a TLS connection is attempted, | ||
| normally during TLS policy (including MTA-STS, TLSA/DANE) fetching stage. | ||
| - TLS negotiation failures or successes during outbound delivery when MTA-STS or TLSA/DANE is enabled. | ||
| **Currently, only enabled on domains with successfully fetched MTA-STS policies or DANE TLSA records **. | ||
|
|
||
| The JSON fields and values are defined in `tlsrpt.h`, with most of the field names the same as | ||
| defined in the RFC: https://datatracker.ietf.org/doc/html/rfc8460. | ||
|
|
||
| The following JSON fields are not defined in the RFC: | ||
| * `epoch` - epoch time of when the hook is invoked | ||
| * `type` - whether the data is for a successful TLS connection or a failure. | ||
| `0` - failure; `1` - success | ||
|
|
||
| **An example JSON for a success**: | ||
|
|
||
| ``` | ||
| { | ||
| "epoch": 1746712864, | ||
| "type": 1, | ||
| "policy": { | ||
| "policy-type": "sts", | ||
| "policy-domain": "test.bird.com", | ||
| "policy-string": [ | ||
| "version: STSv1", | ||
| "mode: enforce", | ||
| "mx: mx.bird.com", | ||
| "mx: server.ectest.OMNITI.com", | ||
| "max_age: 604800" | ||
| ] | ||
| }, | ||
| "sending-mta-ip": "127.0.0.1", | ||
| "receiving-mx-hostname": "server.ectest.OMNITI.com", | ||
| "receiving-ip": "127.0.0.1" | ||
| } | ||
| ``` | ||
|
|
||
| **An example JSON for a failure**: | ||
|
|
||
| ``` | ||
| { | ||
| "epoch": 1746629177, | ||
| "type": 0, | ||
| "policy": { | ||
| "policy-type": "sts", | ||
| "policy-domain": "mismatch.cert.com", | ||
| "policy-string": [ | ||
| "version: STSv1", | ||
| "mode: enforce", | ||
| "mx: test.bird.com", | ||
| "max_age: 86400" | ||
| ] | ||
| }, | ||
| "result-type": "certificate-host-mismatch", | ||
| "failure-reason-code": "4.7.5 [internal] SSL certificate subject does not match host", | ||
| "sending-mta-ip": "127.0.0.1", | ||
| "receiving-mx-hostname": "test.BIRD.com", | ||
| "receiving-ip": "127.0.0.1" | ||
| } | ||
| ``` | ||
|
|
||
|
|
||
| **Return Values** | ||
|
|
||
| This hook returns `int`, but for now the return value has no significance. | ||
|
|
||
|
|
||
| **Threading** | ||
|
|
||
| This hook could be called in any thread. Please avoid doing time consuming tasks in the hook's | ||
| implementation. | ||
|
|
||
|
|
||
| ### Example: a Lua implementation of the hook to log the JSON into the `paniclog` | ||
|
|
||
| ``` | ||
| require("msys.core"); | ||
| require("json") | ||
|
|
||
| local mod = {} | ||
|
|
||
| function mod:core_smtp_tls_reporting(js) | ||
| print("tls report: ", js) -- log the whole JSON | ||
| if js.type == 0 then -- failure | ||
| print(string.format("TLSRPT: %s@%s@%s", js.policy["policy-domain"], | ||
| js.policy["policy-type"], js["result-type"])) | ||
| else -- success | ||
| print(string.format("TLSRPT: %s@%s@%s", js.policy["policy-domain"], | ||
| js.policy["policy-type"], "OK")) | ||
| end | ||
| end | ||
|
|
||
| msys.registerModule("tlsrpt", mod); | ||
| ``` | ||
|
|
||
| **Example of the paniclog output from the above Lua hook**: | ||
| ``` | ||
| 1746712864:scriptlet: tls report: { "epoch": 1746712864, "type": 1, "policy": { "policy-type": "sts", "policy-domain": "test.bird.com", "policy-string": [ "version: STSv1", "mode: enforce", "mx: mx.bird.com", "mx: server.ectest.OMNITI.com", "max_age: 604800" ] }, "sending-mta-ip": "127.0.0.1", "receiving-mx-hostname": "server.ectest.OMNITI.com", "receiving-ip": "127.0.0.1" } | ||
| 1746712864:scriptlet: TLSRPT: test.bird.com@sts@OK | ||
| 1746719856:scriptlet: tls report: { "epoch": 1746719856, "type": 0, "policy": { "policy-type": "sts", "policy-domain": "mismatch.cert.com", "policy-string": [ "version: STSv1", "mode: enforce", "mx: test.bird.com", "max_age: 86400" ] }, "result-type": "certificate-host-mismatch", "failure-reason-code": "4.7.5 [internal] SSL certificate subject does not match host", "sending-mta-ip": "127.0.0.1", "receiving-mx-hostname": "test.BIRD.com", "receiving-ip": "127.0.0.1" } | ||
| 1746719856:scriptlet: TLSRPT: mismatch.cert.com@sts@certificate-host-mismatch | ||
| ``` |
|
There was a problem hiding this comment. You can ignore this file; it was reviewed before. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
There was a problem hiding this comment. You can ignore this file; it was reviewed before. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
There was a problem hiding this comment. You can ignore this file; it was reviewed before. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
There was a problem hiding this comment. You can ignore this file; it was reviewed before. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
There was a problem hiding this comment. You can ignore this file; it was reviewed before. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
There was a problem hiding this comment. You can ignore this file; it was reviewed before. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
There was a problem hiding this comment. You can ignore this file; it was reviewed before. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
There was a problem hiding this comment. You can ignore this file; it was reviewed before. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,84 +1,94 @@ | ||
| --- | ||
| lastUpdated: "05/30/2025" | ||
| title: "outbound_smtp_auth" | ||
| description: "This module enables users to specify authentication parameters for a given set of messages so that Momentum will authenticate against the peer server when it sends outbound mail It currently supports the AUTH LOGIN, AUTH PLAIN and AUTH XOAUTH2 methods of authentication You can specify the parameters in configuration or in lua..." | ||
| --- | ||
|
|
||
| <a name="modules.outbound_smtp_auth"></a> | ||
|
|
||
| This module enables users to specify authentication parameters for a given set of messages so that | ||
| Momentum will authenticate against the peer server when it sends outbound mail. It currently | ||
| supports the `AUTH LOGIN`, `AUTH PLAIN` and `AUTH XOAUTH2` methods of authentication. | ||
| You can specify the parameters in configuration or in lua, or use a combination of both. | ||
|
|
||
| ### Note | ||
|
|
||
| This module makes heavy use of message contexts to facilitate authentication. If it is enabled, you risk having extra I/O unless `keep_message_dicts_in_memory` is on. | ||
|
|
||
| ### <a name="modules.outbound_smtp_auth.configuration"></a> Configuration | ||
|
|
||
| > This module is refactored in Momentum 5.1, but this feature is available in | ||
| Momentum 4.2 and later. `AUTH XOAUTH2` support is added in 5.1. | ||
|
|
||
| Configuration variables are listed below. These values can all be changed and overridden by setting | ||
| message context variables with the same name as the options in lua. | ||
| All variables are valid in the binding group, binding, domain, and global scopes. | ||
|
|
||
| <dl class="variablelist"> | ||
|
|
||
| <dt>outbound_smtp_auth_pass</dt> | ||
|
|
||
| <dd> | ||
|
|
||
| The password or auth token (e.g. for `AUTH XOAUTH2`) that will be passed to the remote server. | ||
| It has no default value. | ||
|
|
||
| ### Note | ||
|
|
||
| Setting the password in configuration will leave it as plaintext. | ||
| To set the password more securely, it's recommended to dynamically retrieve it from a data store | ||
| in lua and set it in the context variable that corresponds to this option. | ||
|
|
||
| </dd> | ||
|
|
||
| <dt>outbound_smtp_auth_type</dt> | ||
|
|
||
| <dd> | ||
|
|
||
| Determines what authentication protocol should be used. The only supported values are `PLAIN`, | ||
| `LOGIN` and `XOAUTH2`. It has no default value. | ||
|
|
||
| </dd> | ||
|
|
||
| <dt>outbound_smtp_auth_user</dt> | ||
|
|
||
| <dd> | ||
|
|
||
| The username that will be passed to the remote server. It has no default value. | ||
|
|
||
| </dd> | ||
|
|
||
| </dl> | ||
|
|
||
| ### <a name="modules.outbound_smtp_auth.usage"></a> Usage | ||
|
|
||
| A hook `outbound_smtp_auth_config(msg)` is added by this module to allow per message auth settings. | ||
| The settings in `ec_message` context will override the configuration values. | ||
| This hook is called in delivery/scheduler thread before sending SMTP `AUTH` command. | ||
| Please avoid blocking or lengthy operations when implementing this hook. | ||
|
|
||
| Basic examples of usage are provided below. | ||
|
|
||
| The following example shows how you can extend the new hook and set the username and password in lua | ||
| for each message. | ||
|
|
||
| <a name="modules.outbound_smtp_auth.example.set_username_pw"></a> | ||
|
|
||
|
|
||
| ``` | ||
| function mod:outbound_smtp_auth_config(msg) | ||
| --print('NOTICE: outbound_smtp_auth_config Lua hook called'); | ||
| msg:context_set(VCTX_MESS, 'outbound_smtp_auth_type', 'XOAUTH2') | ||
| -- credential taken from example here: | ||
| -- https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth | ||
| msg:context_set(VCTX_MESS, 'outbound_smtp_auth_user', '[email protected]') | ||
| msg:context_set(VCTX_MESS, 'outbound_smtp_auth_pass', 'EwBAAl3BAAUFFpUAo7J3Ve0bjLBWZWCclRC3EoAA') | ||
| end | ||
| ``` | ||
|
|
||
| The following example shows how to use the new configuration variables to set distinct authorization parameters for two different domains. | ||
|
|
||
| <a name="modules.outbound_smtp_auth.example.set_auth_parms"></a> | ||
|
|
||
|
|
||
| ``` | ||
|
|
@@ -90,13 +100,17 @@ Domain "messagesystems.com" { | |
| Outbound_SMTP_AUTH_Type = "LOGIN" | ||
| Outbound_SMTP_AUTH_User = "msys" | ||
| Outbound_SMTP_AUTH_Pass = "msys" | ||
| } | ||
|
|
||
| Domain "sparkpost.com" { | ||
| Outbound_SMTP_AUTH_Type = "PLAIN" | ||
| Outbound_SMTP_AUTH_user = "sparkpost" | ||
| Outbound_SMTP_AUTH_pass = "sparkpost" | ||
| } | ||
|
|
||
| Domain "bird.com" { | ||
| Outbound_SMTP_AUTH_Type = "XOAUTH2" | ||
| Outbound_SMTP_AUTH_user = "[email protected]" | ||
| Outbound_SMTP_AUTH_pass = "EwBAAl3BAAUFFpUAo7J3Ve0bjLBWZWCclRC3EoAA" | ||
| } | ||
| ``` | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You can ignore this file; it was reviewed before.