OpenARC module and APIs

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

@@ -0,0 +1,110 @@
+---
+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.verify(msg, options, ar)`
+
+```
+msg: userdata, ec_message type
+options: table
+ar: string, optional. It's the message's authentication assessment to be enshrined into the AAR
+(ARC-Authentication-Results) header.
+
+```
+
+## Description
+
+This function does ARC validation first, then combine the validation result with authentication
+assessments from other methods (e.g. SPF, DKIM, etc) defined by the `ar` and put it into the AAR
+header; then sign and seal the message by adding the AMS (ARC-Message-Signature) and AS
+(ARC-Seal) headers, using the signing mechanism defined in the `options` table.
+
+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.
+
+    *   `header_canon` – header canonicalization setting
+
+    *   `body_canon` – body canonicalization setting
+
+    *   `digest` – signing algorithm digest setting
+
+    *   `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` – ";" separated list of headers to sign
+
+    *   `oversign_headerlist` – ";" seperated list of headers for over signing
+
+*   `ar` - authentication assessment to be enshrined in 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 use it to
+    build the AAR header.
+
+
+### Note
+
+Since ARC sealing should happen after all potential modification of a message is done, this function
+shall be invoked in the `post_final_validation` stage after all the other validation phases.
+
+
+<a name="lua.ref.msys.validate.opendarc.sign.example"></a>
+### Example
+
+
+```
+require("msys.core");
+require("msys.extended.message");
+local openarc = 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"
+
+  openarc.sign(msg, sealer)
+end
+
+msys.registerModule("openarc_sign", mod);
+```
+
+## See Also
+
+[msys.validate.opendarc.verify](/momentum/4/lua/ref-msys-validate-openarc-verify)

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

@@ -0,0 +1,62 @@
+---
+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, 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
+
+If the `ec_message` context variable `arc_cv` is not set after this function call, errors happened
+and 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` hook.
+
+<a name="lua.ref.msys.validate.opendarc.verify.example"></a>
+### Example
+
+
+```
+require("msys.core");
+require("msys.extended.message");
+local openarc = require("msys.validate.openarc");
+local mod = {};
+
+function mod:mod:validate_data_spool(msg, ac, vctx)
+  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.opendarc.sign](/momentum/4/lua/ref-msys-validate-openarc-sign)

content/momentum/4/modules/index.md

@@ -60,6 +60,7 @@ description: "Table of Contents 71 1 Introduction 71 2 ac auth Authentication Ha
 | [msgc](/momentum/4/modules/msgc) | Message Systems Group Communication |
 | [msg_gen](/momentum/4/modules/msg-gen) | Message Generation |
 | [mxip](/momentum/4/modules/mxip) | IP Addresses In MX Records |
+| [openarc](/momentum/4/modules/openarc) | Open Source ARC |
 | [opendkim](/momentum/4/modules/opendkim) | Open Source DKIM |
 | [outbound_audit](/momentum/4/modules/outbound-audit) | Outbound traffic analytics |
 | [outbound_smtp_auth(modules.outbound_smtp_auth.php) |

content/momentum/4/modules/openarc.md

@@ -0,0 +1,44 @@
+---
+lastUpdated: "11/26/2024"
+title: "openarc – Open Source ARC"
+description: "The openarc module wraps the open source libopenarc API into Momentum to provide Momentum APIs to do ARC validation verification signature signing and sealing..."
+
+ARC is an acronym for Authenticated Received Chain. It’s a technology protocol defined in
+[RFC8617](https://datatracker.ietf.org/doc/html/rfc8617). It provides an authenticated "chain of
+custody" for a message, allowing each entity that handles the message to see what entities handled
+it before and what the message's authentication assessment was at each step in the handling flow.
+
+The openarc module add ARC capability to Momentum. It provides Lua APIs for
+ARC validation on a received email, and ARC siging and sealing on an outgoing email.
+When the module is enabled, ARC validation and signing/sealing can be achieved through calling these APIs from hook policies.
+
+
+### <a name="modules.openarc.configuration"></a> Configuration
+
+You need to enable the openarc module in the ecelerity configuration file to use the feature:
+
+```
+openarc {}
+```
+
+### Lua APIs and examples
+
+[msys.validate.opendarc.verify](/momentum/4/lua/ref-msys-validate-openarc-verify)
+
+[msys.validate.opendarc.sign](/momentum/4/lua/ref-msys-validate-openarc-sign)
+
+
+### Hook points to invoke the APIs
+
+The `msys.validate.opendarc.sign` does verification first. You should only invoke one of the APIs,
+    either `verify` or `sign` but not both.
+It's recommended to invoke `msys.validate.opendarc.verify` in `validate_data_spool` hook.
+`msys.validate.opendarc.sign` shall be invoked in the last validation phase, in
+`post_final_validation` hook.
+
+The `post_final_validation` hook is added as the absolute last point before writing the message into
+spool. No any message modification expected after this stage. To avoid undefined race between
+multiple implementations of the same hook, you shall only have up to one implementation for this
+hook. And it's the best place to call `msys.validate.opendarc.sign`.
+
+See API examples for hook usages.