TASK-3755: New release Momentum 5.0 (#785)

* EOP-281: OpenARC module and APIs (#782)

* TASK-3755: Changelog for 5.0; updated EOL calendar

Signed-off-by: Doug Koerich <[email protected]>

---------

Signed-off-by: Doug Koerich <[email protected]>
Co-authored-by: Julie Zhao <[email protected]>

Author: dkoerichbird

content/momentum/4/4-lua-summary-table.md

@@ -1,5 +1,5 @@
 ---
-lastUpdated: "10/05/2021"
+lastUpdated: "03/01/2025"
 title: "Lua Functions Summary"
 description: "This section contains tables of Lua functions Click the function name for details Table 64 1 Lua functions all Function Description Params Package Version Phases ac esmtp capability add Add a capability to the EHLO response name msys extended ac 4 0 connect ehlo ac esmtp capability remove Removes a..."
 ---
@@ -174,6 +174,8 @@ This section contains tables of Lua functions. Click the function name for detai
 | [msys.unlock](/momentum/4/lua/ref-msys-unlock) – Releases a lock obtained via msys.lock | mutexname | msys | 4.0 | any |
 | [msys.validate.dk.get_responsible_domain](/momentum/4/lua/ref-msys-validate-dk-get-responsible-domain) – This function requires module "dk_validate". "msg" is a mail message. "ctx" is the validation context. It returns the responsible domain for the current message | msg, ctx | msys.validate.dk | 4.0 | data, data_spool, data_spool_each_rcpt |
 | [msys.validate.dk.sign](/momentum/4/lua/ref-msys-validate-dk-sign) – Sign a message using a Domain Key | msg, ctx, options | msys.validate.dk | 4.0 | core_data_validation |
+| [msys.validate.openarc.sign](/momentum/4/lua/ref-msys-validate-openarc-sign) – Sign a message using OpenARC | msg, options, [ar] | msys.validate.openarc | 5.0 | core_post_final_validation |
+| [msys.validate.openarc.verify](/momentum/4/lua/ref-msys-validate-openarc-verify) – Verify ARC sets | msg | msys.validate.openarc | 5.0 | data_spool, data_spool_each_rcpt |
 | [msys.validate.opendkim.get_num_sigs](/momentum/4/lua/ref-msys-validate-opendkim-get-num-sigs) – Return the number of DKIM signatures | dkim | msys.validate.opendkim | 4.0 | data, data_spool, data_spool_each_rcpt |
 | [msys.validate.opendkim.get_sig](/momentum/4/lua/ref-msys-validate-opendkim-get-sig) – Get a signature from a DKIM object | dkim, [num] | msys.validate.opendkim | 4.0 | data, data_spool, data_spool_each_rcpt |
 | [msys.validate.opendkim.get_sig_canons](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-canons) – Fetch the canonicalizers used for a DKIM signature | dkim_sig | msys.validate.opendkim | 4.0 | data, data_spool, data_spool_each_rcpt |
@@ -186,7 +188,7 @@ This section contains tables of Lua functions. Click the function name for detai
 | [msys.validate.opendkim.get_sig_selector](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-selector) – Fetch the selector associated with a DKIM signature | dkim_sig | msys.validate.opendkim | 4.0 | data, data_spool, data_spool_each_rcpt |
 | [msys.validate.opendkim.get_sig_signalg](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-signalg) – Return the signing algorithm as a string | dkim_sig | msys.validate.opendkim | 4.0 | data, data_spool, data_spool_each_rcpt |
 | [msys.validate.opendkim.sign](/momentum/4/lua/ref-msys-validate-opendkim-sign) – Sign a message using OpenDKIM | msg, vctx, [options] | msys.validate.opendkim | 4.0 | core_final_validation |
-| [msys.validate.opendkim.verify](/momentum/4/lua/ref-msys-validate-opendkim-verify) – Verify an DKIM signature | m | msys.validate.opendkim | 4.0 | data, data_spool, data_spool_each_rcpt |
+| [msys.validate.opendkim.verify](/momentum/4/lua/ref-msys-validate-opendkim-verify) – Verify an DKIM signature | msg | msys.validate.opendkim | 4.0 | data, data_spool, data_spool_each_rcpt |
 | [sess:request_add_header](/momentum/4/lua/ref-sess-request-add-header) – Set the header of an HTTP session | header, value, replace | msys.httpclnt | 4.0 | http_request_eval |
 | [sess:request_delete_header](/momentum/4/lua/ref-sess-request-delete-header) – Delete a header from an HTTP session | header | msys.httpclnt | 4.0 | http_request_eval |
 | [sess:request_finalize](/momentum/4/lua/ref-sess-request-finalize) – Finalize changes to an HTTP request | update | msys.httpclnt | 4.0 | http_request_eval |

content/momentum/4/eol-policy.md

@@ -1,5 +1,5 @@
 ---
-lastUpdated: '11/06/2024'
+lastUpdated: '03/01/2025'
 title: 'End of Life Policy'
 description: 'This document provides the latest version of the formal end-of-life policy for releases of software from Message Systems.'
 ---
@@ -43,8 +43,14 @@ Momentum version 4 became GA on April 15, 2014. Therefore:
 - Maintenance for all versions of Momentum 3 ended on December 31, 2018.
 - Support for all versions of Momentum 3 ended on December 31, 2018.
 
-## MOMENTUM 4 GA DATES
+## MOMENTUM 4 END-OF-LIFE DATE
 
+Momentum version 5 became GA on March 1, 2025. Therefore:
+
+- Maintenance for all versions of Momentum 4 will end on March 1, 2026.
+- Support for all versions of Momentum 4 will end on March 1, 2027.
+
+## MOMENTUM 4 AND MOMENTUM 5 GA DATES
 
 | Update and Maintenance Versions | GA         | End of Maintenance | End of Support |
 | ------------------------------- | ---------- | ------------------ | -------------- |
@@ -53,15 +59,16 @@ Momentum version 4 became GA on April 15, 2014. Therefore:
 | Momentum 4.2.x                  | 2015/8/3   | 2020/6/30          | 2021/6/30      |
 | Momentum 4.3.x                  | 2019/3/5   | 2022/9/3           | 2023/9/3       |
 | Momentum 4.4.x                  | 2021/9/3   | 2024/10/20¹        | 2024/12/31³    |
-| Momentum 4.5.0                  | 2023/10/5  | 2024/12/19²        | TBD            |
+| Momentum 4.5.0                  | 2023/10/5  | 2024/12/19²        | 2027/3/1       |
 | Momentum 4.6.0                  | 2023/10/20 | 2024/12/19         | 2024/12/31³    |
-| Momentum 4.7.0                  | 2023/12/19 | 2025/10/17         | TBD            |
-| Momentum 4.8.0                  | 2024/10/17 | TBD                | TBD            |
+| Momentum 4.7.0                  | 2023/12/19 | 2025/10/17         | 2027/3/1       |
+| Momentum 4.8.0                  | 2024/10/17 | 2026/3/1           | 2027/3/1       |
+| **Momentum 5.0.0**              | 2025/3/1   | TBD                | TBD            |
 
 > ¹ Momentum 4.4.x was superseded by 4.6, which was the last version supporting CentOS 7.
 >
 > ² Momentum 4.5 was the first version supporting RHEL 8, and was superseded by 4.7.
 >
-> ³ Given the EOL of CentOS 7 operating system on June 30, 2024, all GA and Maintenance releases of Momentum 4 supporting that platform will be supported until **December 31, 2024**.
+> ³ Given the EOL of CentOS 7 operating system on June 30, 2024, maintenance and support for all GA and Maintenance releases of Momentum 4 supporting that platform ended on **December 31, 2024**.
 
 [Previous version (December 10, 2012)](/momentum/4/eol-policy-2012).

content/momentum/4/hooks/core-post-final-validation.md

@@ -0,0 +1,83 @@
+---
+lastUpdated: "11/26/2024"
+title: "post_final_validation"
+description: "hook invoked after the normal final validation"
+---
+
+<a name="hooks.core.post_final_validation"></a>
+## Name
+
+post_final_validation — This hook is invoked after the normal
+[final_validation](/momentum/3/3-api/hooks-core-final-validation) hook
+
+## Synopsis
+
+`#include "hooks/core/final_validation.h"`
+
+`int core_post_final_validation(void closure, ec_message *msg, accept_construct *ac, valiate_context *ctx)`
+
+
+## Description
+
+This hook is invoked right after the
+[final_validation](/momentum/3/3-api/hooks-core-final-validation) hook. Its return value
+does not have significance for now.
+This hook is added as the absolute last point before writing the message to spool for delivery.
+It guarantees that operations implemented in this hook will happen after the operations done in
+`final_validation`.
+To avoid undefined ordering between multiple implementations of the same hook, you shall have at most
+ one implementation for this hook.
+> It's the recommended hook point for ARC signing/sealing.
+
+
+**Parameters**
+
+The parameters from this hook are the same as the ones for `final_validation` hook.
+
+<dl class="variablelist">
+
+<dt>closure</dt>
+
+<dd>
+
+A pointer to the closure function.
+
+</dd>
+
+<dt>msg</dt>
+
+<dd>
+
+A pointer to an ec_message struct. For documentation of this data structure see [“ec_message”](/momentum/3/3-api/structs-ec-message)
+
+</dd>
+
+<dt>ac</dt>
+
+<dd>
+
+The `accept_construct` struct. For documentation of this data structure see [“accept_construct”](/momentum/3/3-api/structs-accept-construct)
+
+</dd>
+
+<dt>ctx</dt>
+
+<dd>
+
+The `validate_context` struct. For documentation of this data structure see [“validate_context”](/momentum/3/3-api/structs-validate-context)
+
+</dd>
+
+</dl>
+
+**Return Values**
+
+This hook returns `int`, but for now the return value has no significance, i.e. it is not checked in
+the caller.
+
+**Threading**
+
+This hook will be called in any thread.
+
+
+<a name="idp45866720"></a>

content/momentum/4/hooks/index.md

@@ -1,6 +1,6 @@
 ---
-lastUpdated: "10/05/2021"
-title: "Category File"
+lastUpdated: "11/26/2024"
+title: "Hook Points and C Functions Reference"
 type: "custom"
 name: "Hook Points and C Functions Reference"
 description: "This chapter includes hook point and C function reference material that is specific to Momentum 4 Hook points and C functions that are common to Momentum 4 and Momentum 3 are provided in the Momentum 3 x documentation For hook points see the C API For C functions see the..."
@@ -11,6 +11,7 @@ description: "This chapter includes hook point and C function reference material
 |---------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
 | [msg_gen_data_spool](/momentum/4/hooks/msg-gen-data-spool)                            | This hook is invoked after a message has been generated by the msg_gen module |
 | [config_rsrc_setup](/momentum/4/hooks/config-rsrc-setup)                              | Register a resource                                                           |
+| [core_post_final_validation](/momentum/4/hooks/core-post-final-validation)            | Same usage as but invoked right after the `core_final_validation` hook        |
 | [ec_config_rsrc_get](/momentum/4/apis-ec-config-rsrc-get)                             | Return a resource list blobject from the configuration system                 |
 | [ec_httpsrv_register_auth](/momentum/4/apis-ec-httpsrv-register-auth)                 | Register an HTTP handler for authenticating a URI                             |
 | [ec_httpsrv_request_local_address](/momentum/4/apis-ec-httpsrv-request-local-address) | Returns the local IP address from the current session                         |

content/momentum/4/lua/index.md

@@ -1,5 +1,5 @@
 ---
-lastUpdated: "10/05/2021"
+lastUpdated: "03/01/2025"
 title: "Category File"
 type: "custom"
 name: "Lua Functions Reference"
@@ -191,6 +191,8 @@ description: "This section details all Lua functions Functions are ordered alpha
 | [msys.tls_params.set](/momentum/4/lua/ref-msys-tls-params-set) | Set a tls parameter string on a per connection basis |
 | [msys.validate.dk.get_responsible_domain](/momentum/4/lua/ref-msys-validate-dk-get-responsible-domain) | Return the domain responsible for the current message |
 | [msys.validate.dk.sign](/momentum/4/lua/ref-msys-validate-dk-sign) | Sign a message using a Domain Key |
+| [msys.validate.openarc.sign](/momentum/4/lua/ref-msys-validate-openarc-sign) | Sign a message using OpenARC |
+| [msys.validate.openarc.verify](/momentum/4/lua/ref-msys-validate-openarc-verify) | Verify ARC sets |
 | [msys.validate.opendkim.get_num_sigs](/momentum/4/lua/ref-msys-validate-opendkim-get-num-sigs) | Return the number of DKIM signatures |
 | [msys.validate.opendkim.get_sig](/momentum/4/lua/ref-msys-validate-opendkim-get-sig) | Get a signature from a DKIM object |
 | [msys.validate.opendkim.get_sig_canons](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-canons) | Fetch the canonicalizers used for a signature |

content/momentum/4/lua/ref-msys-validate-openarc-sign.md

@@ -0,0 +1,149 @@
+---
+lastUpdated: "11/26/2024"
+title: "msys.validate.openarc.sign"
+description: "msys validate openarc sign seal add ARC set headers"
+---
+
+<a name="lua.ref.msys.validate.openarc.sign"></a>
+## Name
+
+msys.validate.openarc.sign — builds and adds the ARC set headers into an email.
+
+msys.validate.openarc.seal - synonym of `msys.validation.openarc.sign`.
+
+## Synopsis
+
+`msys.validate.openarc.sign(msg, options, ar)`
+
+`msys.validate.openarc.seal(msg, options, ar)`
+
+```
+msg: userdata, ec_message type
+options: table
+ar: string, optional. It's the message's authentication assessment to be copied as-is into the AAR header.
+
+```
+
+## Description
+
+This function acquires ARC chain status (i.e. `cv`) from `ec_message` context variable `arc_cv`. The `cv`
+ will be used in the AS (ARC-Seal) header, and combined with authentication assessments from other
+ methods (e.g. SPF, DKIM, etc) defined by the `ar` and put into the AAR (ARC-Authentication-Results)
+ header. This function signs and seals the message by adding the AMS (ARC-Message-Signature) and AS
+ (ARC-Seal) headers, using the signing mechanism defined in the `options` table.
+
+If `ec_message` context variable `arc_cv` is not set when the function is called, the function will do an
+ internal ARC validation (to set the `arc_cv`), followed by the regular `cv` based signing.
+
+This function requires the [`openarc`](/momentum/4/modules/openarc) module.
+
+Enable this function with the statement `require('msys.validate.openarc')`.
+
+This function takes the following parameters:
+
+*   `msg` - mail message to sign
+
+*   `options`   - table defines the options for signature generation/signing:
+
+    *   `signing_domain` – signing domain
+
+    *   `selector` – signing selector
+
+    *   `authservid` – authentication service identifier, as
+        [authserv-id](https://datatracker.ietf.org/doc/html/rfc8601#section-2.5) defined in RFC.
+
+        If not set, will be defaulted to the hostname.
+
+    *   `header_canon` – header canonicalization setting.
+
+        Supported values are `relaxed`, `simple`. Defaults to `relaxed`.
+
+    *   `body_canon` – body canonicalization setting
+
+        Supported values are `relaxed`, `simple`. Defaults to `relaxed`.
+
+    *   `digest` – signing algorithm digest setting.
+
+        Supported values are `rsa-sha1` and `rsa-sha256`. Defaults to `rsa-sha256`.
+
+    *   `keyfile` – signing key file
+
+    *   `keybuf` – signing key
+
+        Must contain the PEM encoded private key to use for signing the
+        message. This must be a contiguous string, with no line breaks and no white spaces, without the
+        `BEGIN` and `END` tags that are found in the key file itself. The format is similar to the
+        format used for OpenDKIM signing.
+
+        If not defined, will be built from the `keyfile`.
+
+    *   `headerlist` – colon-separated list of headers to sign
+
+    *   `oversign_headerlist` – colon-separated list of headers for over signing
+
+    *   `skip_ar_header_update` – if set, no update to the AR (Authentication-Results) header.
+
+        If not set, Momentum will append the ARC verification result (e.g. `arc=pass`) to
+        the existing AR header or create one if it does not exist.
+
+*   `ar` - authentication assessment to be copied as-is into the AAR (ARC-Authentication-Results) header.
+
+    If not provided, Momentum will take the value from the existing `Authentication-Results` header.
+    Momentum appends this value with the ARC verification result (e.g. `arc=pass`) and uses it to
+    build the AAR header.
+
+
+### Note
+
+Since ARC sealing  must not happen until all potential modification of a message is done, if you
+ already have implementations in some other validation phases/hooks, this function
+ should be invoked in the `post_final_validation` stage to guarantee that it is called
+ after all the other hook implementations.
+
+The function would cause the `ec_message` context variable `arc_seal` to be set:
+
+`ok`: ARC signing/sealing is done, and ARC set headers are added.
+
+`skip`: ARC signing/sealing is skipped, because the ARC chain already fails before reaching the
+ current MTA.
+
+If the context variable `arc_seal` of the `ec_message` is not set, it indicates an unexpected ARC
+ signing/sealing failure, e.g. due to mis-configuration. The error reason is logged in paniclog.
+
+
+<a name="lua.ref.msys.validate.openarc.sign.example"></a>
+### Example
+
+
+```
+require("msys.core");
+require("msys.validate.openarc");
+local mod = {};
+
+function mod:core_post_final_validation(msg, accept, vctx)
+  local sealer = {}
+  sealer.signing_domain = "sparkpost.com"
+  sealer.selector = "dkim-s1024"
+  sealer.keyfile = "path-to-keyfile"
+  sealer.headerlist = "From:Subject:Date:To:MIME-Version:Content-Type"
+  sealer.oversign_headerlist = "From:To:Subject"
+
+  msys.validate.openarc.sign(msg, sealer)
+
+  -- check sign/seal result
+  local ok = msg:context_get(msys.core.ECMESS_CTX_MESS, "arc_seal")
+  if ok == nil or ok == '' then
+    print("ARC seal failed. No ARC set add! Check paniclog for reasons.")
+  elseif ok == "skip" then
+    print("ARC seal skipped. No ARC set add: ARC chain failed before reaching me.")
+  else
+    print("ARC seal ok. ARC set added!")
+  end
+end
+
+msys.registerModule("openarc_sign", mod);
+```
+
+## See Also
+
+[msys.validate.openarc.verify](/momentum/4/lua/ref-msys-validate-openarc-verify)

content/momentum/4/lua/ref-msys-validate-openarc-verify.md

@@ -0,0 +1,63 @@
+---
+lastUpdated: "11/26/2024"
+title: "msys.validate.openarc.verify"
+description: "msys validate openarc verify Verify ARC sets headers"
+---
+
+<a name="lua.ref.msys.validate.openarc.verify"></a>
+## Name
+
+msys.validate.openarc.verify — Verifies ARC set headers in an email, and stores the verification results
+(`none/pass/fail`) into the email's context variable.
+
+## Synopsis
+
+`msys.validate.openarc.verify(msg)`
+
+`msg: userdata, ec_message type`<a name="idp19138336"></a>
+## Description
+
+This function validates the ARC set headers contained in the input message. The validation result
+will be stored as string value (`none` or `pass` or `fail`) in the `ec_message`'s context variable
+of `arc_cv`. A caller can take actions (e.g. disposition of the message) based on the validation
+result.
+
+This function requires the [`openarc`](/momentum/4/modules/openarc) module.
+
+Enable this function with the statement `require('msys.validate.openarc')`.
+
+### Note
+
+After being called, this function always sets the `ec_message` context variable `arc_cv` to one of
+ the values: `none`, `pass`, `fail`. Unexpected `fail` cases are logged into paniclog.
+
+This function invokes dns lookup for signature validation. It's recommended to invoke it from a hook
+which would not block Momentum's main tasks, e.g. from the `validate_data_spool` or the
+ `validate_data_spool_each_rcpt` hook.
+
+<a name="lua.ref.msys.validate.openarc.verify.example"></a>
+### Example
+
+
+```
+require("msys.core");
+require("msys.extended.message");
+require("msys.validate.openarc");
+local mod = {};
+
+function mod:validate_data_spool_each_rcpt(msg, ac, vctx)
+  msys.validate.openarc.verify(msg)
+  local cv = msg:context_get(msys.core.ECMESS_CTX_MESS, "arc_cv")
+  if cv then
+    print("ARC validation result: ", cv)
+  else
+	print("Failed to do ARC validation. Check paniclog for reasons.")
+  end
+end
+
+msys.registerModule("openarc_verify", mod);
+```
+
+## See Also
+
+[msys.validate.openarc.sign](/momentum/4/lua/ref-msys-validate-openarc-sign)