From 834e91eb0baf7915b811a131daffd46fda3e3012 Mon Sep 17 00:00:00 2001 From: Julie Zhao Date: Tue, 26 Nov 2024 12:52:31 -0500 Subject: [PATCH] more cleanup --- .../4/hooks/core-post-final-validation.md | 14 ++----- .../4/lua/ref-msys-validate-openarc-sign.md | 37 +++++++++++++------ .../4/lua/ref-msys-validate-openarc-verify.md | 6 +-- 3 files changed, 32 insertions(+), 25 deletions(-) diff --git a/content/momentum/4/hooks/core-post-final-validation.md b/content/momentum/4/hooks/core-post-final-validation.md index 341271bd..00820b23 100644 --- a/content/momentum/4/hooks/core-post-final-validation.md +++ b/content/momentum/4/hooks/core-post-final-validation.md @@ -14,21 +14,13 @@ post_final_validation — This hook is invoked after the normal `#include "hooks/core/final_validation.h"` -| `int **core_post_final_validation** (` | closure, |   | -|   | msg, |   | -|   | ac, |   | -|   | ctx`)`; |   | - -`void * closure`; -`ec_message * msg`; -`accept_construct * ac`; -`validate_context * ctx`; +`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 is called. Its return value +[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 into spool. It guarantees that operations implemented in this hook will happen after the operations done in @@ -81,7 +73,7 @@ The `validate_context` struct. For documentation of this data structure see [“ **Return Values** -This hook returns `int`, but for now has no significance, i.e. the return value is not checked in +This hook returns `int`, but for now the return value has no significance, i.e. it is not checked in the caller. **Threading** diff --git a/content/momentum/4/lua/ref-msys-validate-openarc-sign.md b/content/momentum/4/lua/ref-msys-validate-openarc-sign.md index 22fbbd37..9b26b1f8 100644 --- a/content/momentum/4/lua/ref-msys-validate-openarc-sign.md +++ b/content/momentum/4/lua/ref-msys-validate-openarc-sign.md @@ -18,8 +18,7 @@ msys.validate.openarc.seal - synonym of `msys.validation.openarc.sign`. ``` 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. +ar: string, optional. It's the message's authentication assessment to be enshrined into the AAR header. ``` @@ -27,7 +26,8 @@ ar: string, optional. It's the message's authentication assessment to be enshrin 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-Authentication-Results) 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. @@ -47,11 +47,19 @@ This function takes the following parameters: * `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 + If not set, will be default to the hostname. + + * `header_canon` – header canonicalization setting. + + Supported values are `relaxed`, `simple`. Default to `relaxed`. * `body_canon` – body canonicalization setting - * `digest` – signing algorithm digest setting + Supported values are `relaxed`, `simple`. Default to `relaxed`. + + * `digest` – signing algorithm digest setting. + + Supported values are `rsa-sha1` and `rsa-sha256`. Default to `rsa-sha256`. * `keyfile` – signing key file @@ -64,11 +72,16 @@ This function takes the following parameters: If not defined, will be built from the `keyfile`. - * `headerlist` – ";" separated list of headers to sign + * `headerlist` – "`;`" separated list of headers to sign - * `oversign_headerlist` – ";" seperated list of headers for over signing + * `oversign_headerlist` – "`;`" seperated list of headers for over signing -* `ar` - authentication assessment to be enshrined in the AAR (ARC-Authentication-Results) header. + * `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 enshrined 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 use it to @@ -80,6 +93,9 @@ This function takes the following parameters: 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. +If for any reason the ARC signing/sealing failed, the context variable `arc_cv` of the `ec_message` +will not be set, and the error reason is logged into paniclog. + ### Example @@ -87,8 +103,7 @@ shall be invoked in the `post_final_validation` stage after all the other valida ``` require("msys.core"); -require("msys.extended.message"); -local openarc = require("msys.validate.openarc"); +require("msys.validate.openarc"); local mod = {}; function mod:core_post_final_validation(msg, accept, vctx) @@ -99,7 +114,7 @@ function mod:core_post_final_validation(msg, accept, vctx) sealer.headerlist = "From:Subject:Date:To:MIME-Version:Content-Type" sealer.oversign_headerlist = "From:To:Subject" - openarc.sign(msg, sealer) + msys.validate.openarc.sign(msg, sealer) end msys.registerModule("openarc_sign", mod); diff --git a/content/momentum/4/lua/ref-msys-validate-openarc-verify.md b/content/momentum/4/lua/ref-msys-validate-openarc-verify.md index 3b6ed25a..ff855d45 100644 --- a/content/momentum/4/lua/ref-msys-validate-openarc-verify.md +++ b/content/momentum/4/lua/ref-msys-validate-openarc-verify.md @@ -41,11 +41,11 @@ which would not block Momentum's main tasks, e.g. from the `validate_data_spool` ``` require("msys.core"); require("msys.extended.message"); -local openarc = require("msys.validate.openarc"); +require("msys.validate.openarc"); local mod = {}; -function mod:mod:validate_data_spool(msg, ac, vctx) - openarc.verify(msg) +function mod:validate_data_spool(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)