more cleanup

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** (` | <var class="pdparam">closure</var>, |   |
-|   | <var class="pdparam">msg</var>, |   |
-|   | <var class="pdparam">ac</var>, |   |
-|   | <var class="pdparam">ctx</var>`)`; |   |
-
-`void * <var class="pdparam">closure</var>`;
-`ec_message * <var class="pdparam">msg</var>`;<a name="idp19138336"></a>
-`accept_construct * <var class="pdparam">ac</var>`;
-`validate_context * <var class="pdparam">ctx</var>`;<a name="idp45851968"></a>
+`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**

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

@@ -18,16 +18,16 @@ 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.
 
 ```
 
 ## 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-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,15 +93,17 @@ 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.
+
 
 <a name="lua.ref.msys.validate.opendarc.sign.example"></a>
 ### Example
 
 
 ```
 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);

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)