diff --git a/content/momentum/4/lua/ref-msys-validate-openarc-sign.md b/content/momentum/4/lua/ref-msys-validate-openarc-sign.md new file mode 100644 index 000000000..22fbbd379 --- /dev/null +++ b/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" +--- + + +## 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. + + + +### 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) diff --git a/content/momentum/4/lua/ref-msys-validate-openarc-verify.md b/content/momentum/4/lua/ref-msys-validate-openarc-verify.md new file mode 100644 index 000000000..3b6ed25a1 --- /dev/null +++ b/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" +--- + + +## 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` +## 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. + + +### 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) diff --git a/content/momentum/4/modules/index.md b/content/momentum/4/modules/index.md index 164907132..e21809faa 100644 --- a/content/momentum/4/modules/index.md +++ b/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) | diff --git a/content/momentum/4/modules/openarc.md b/content/momentum/4/modules/openarc.md new file mode 100644 index 000000000..6f3f17813 --- /dev/null +++ b/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. + + +### 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.