Momentum#1494 document msys.validate.opendkim.get_sig_result / get_stat_result

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

@@ -1,5 +1,5 @@
 ---
-lastUpdated: "03/01/2025"
+lastUpdated: "08/11/2026"
 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..."
 ---
@@ -178,6 +178,7 @@ This section contains tables of Lua functions. Click the function name for detai
 | [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_ar_verdict](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-ar-verdict) – Derive the Authentication-Results verdict for a DKIM signature | dkim_sig | msys.validate.opendkim | 5.4 | 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 |
 | [msys.validate.opendkim.get_sig_domain](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-domain) – Fetch the signing domain from a DKIM_SIGINFO object | dkim_sig | msys.validate.opendkim | 4.0 | data, data_spool, data_spool_each_rcpt |
 | [msys.validate.opendkim.get_sig_errorstr](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-errorstr) – Fetch the error associated with a DKIM signature | dkim_sig | msys.validate.opendkim | 4.0 | data, data_spool, data_spool_each_rcpt |
@@ -187,6 +188,7 @@ This section contains tables of Lua functions. Click the function name for detai
 | [msys.validate.opendkim.get_sig_keysize](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-keysize) – Fetch the size of the key used to generate a DKIM signature | dkim_sig | msys.validate.opendkim | 4.0 | data, data_spool, data_spool_each_rcpt |
 | [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.get_stat_ar_verdict](/momentum/4/lua/ref-msys-validate-opendkim-get-stat-ar-verdict) – Map a DKIM verification status with no per-signature verdict to an Authentication-Results result | stat | msys.validate.opendkim | 5.4 | 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 | 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 |

content/momentum/4/lua/index.md

@@ -1,5 +1,5 @@
 ---
-lastUpdated: "03/01/2025"
+lastUpdated: "08/11/2026"
 title: "Category File"
 type: "custom"
 name: "Lua Functions Reference"
@@ -195,6 +195,7 @@ description: "This section details all Lua functions Functions are ordered alpha
 | [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_ar_verdict](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-ar-verdict) | Derive the Authentication-Results verdict for a DKIM signature |
 | [msys.validate.opendkim.get_sig_canons](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-canons) | Fetch the canonicalizers used for a signature |
 | [msys.validate.opendkim.get_sig_domain](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-domain) | Fetch the signing domain from a DKIM_SIGINFO object |
 | [msys.validate.opendkim.get_sig_errorstr](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-errorstr) | Fetch the error associated with a DKIM signature |
@@ -204,6 +205,7 @@ description: "This section details all Lua functions Functions are ordered alpha
 | [msys.validate.opendkim.get_sig_keysize](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-keysize) | Fetch the size of the key used to generate a signature |
 | [msys.validate.opendkim.get_sig_selector](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-selector) | Fetch the selector associated with a DKIM signature |
 | [msys.validate.opendkim.get_sig_signalg](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-signalg) | Return the signing algorithm as a string |
+| [msys.validate.opendkim.get_stat_ar_verdict](/momentum/4/lua/ref-msys-validate-opendkim-get-stat-ar-verdict) | Map a DKIM verification status with no per-signature verdict to an Authentication-Results result |
 | [msys.validate.opendkim.sign](/momentum/4/lua/ref-msys-validate-opendkim-sign) | Sign a message using OpenDKIM |
 | [msys.validate.opendkim.verify](/momentum/4/lua/ref-msys-validate-opendkim-verify) | Verify a DKIM signature |
 | [thread.mutex](/momentum/4/lua/ref-thread-mutex) | create a new mutex |

content/momentum/4/lua/ref-msys-validate-opendkim-get-sig-ar-verdict.md

@@ -0,0 +1,53 @@
+---
+lastUpdated: "08/11/2026"
+title: "msys.validate.opendkim.get_sig_ar_verdict"
+description: "msys validate opendkim get sig ar verdict Derive the Authentication Results verdict for a DKIM signature msys validate opendkim get sig ar verdict dkim sig This function returns pass when the signature verified successfully and fail with the failure reason otherwise Use it instead of testing msys validate opendkim get sig errorstr..."
+---
+
+<a name="lua.ref.msys.validate.opendkim.get_sig_ar_verdict"></a> 
+## Name
+
+msys.validate.opendkim.get_sig_ar_verdict — Derive the Authentication-Results verdict for a DKIM signature
+
+<a name="idp18905744"></a> 
+## Synopsis
+
+`msys.validate.opendkim.get_sig_ar_verdict(dkim_sig)`
+
+`dkim_sig: userdata, DKIM_SIGINFO type`<a name="idp18909200"></a> 
+## Description
+
+This function derives the verdict for one DKIM signature, in the form used by the `dkim` clause of an `Authentication-Results` header. It returns the string `"pass"` when the signature verified successfully — the signature validated cryptographically (`DKIM_SIGFLAG_PASSED`) *and* the computed body hash matched the signature's `bh=` tag — and otherwise a string of the form `"fail (<reason>)"` naming the specific failure, for example `"fail (signature verification failed)"` or `"fail (key not found in DNS)"`. If `dkim_sig` is nil, the function instead returns two values, nil and the DKIM status `DKIM_STAT_INVALID`, like the other DKIM_SIGINFO accessors.
+
+Use `msys.validate.opendkim.get_num_sigs` and `msys.validate.opendkim.get_sig` to get a DKIM_SIGINFO object to pass to this function.
+
+Do not decide pass/fail by testing `msys.validate.opendkim.get_sig_errorstr` for nil: for a valid signature that function returns the literal string `"no signature error"`, never nil. This function applies the verification result the way libopendkim intends.
+
+Use `msys.validate.opendkim.get_stat_ar_verdict` first to handle verification statuses that carry no per-signature verdict:
+
+```lua
+local opendkim = require("msys.validate.opendkim")
+
+local dkim, stat = opendkim.verify(msg)
+local result = opendkim.get_stat_ar_verdict(stat)
+if result == nil then
+  local num = opendkim.get_num_sigs(dkim)
+  for i = 0, num - 1 do
+    local sig = opendkim.get_sig(dkim, i)
+    if sig then
+      local domain = opendkim.get_sig_domain(sig)
+      result = opendkim.get_sig_ar_verdict(sig)
+      -- e.g. build "header.DKIM-Signature=@" .. domain .. "; dkim=" .. result
+    end
+  end
+end
+```
+
+This function requires the [`opendkim`](/momentum/4/modules/opendkim) module.
+
+Enable this function with the statement `require('msys.validate.opendkim');`.
+
+<a name="idp18947456"></a> 
+## See Also
+
+[msys.validate.opendkim.get_stat_ar_verdict](/momentum/4/lua/ref-msys-validate-opendkim-get-stat-ar-verdict), [msys.validate.opendkim.verify](/momentum/4/lua/ref-msys-validate-opendkim-verify), [msys.validate.opendkim.get_num_sigs](/momentum/4/lua/ref-msys-validate-opendkim-get-num-sigs), [msys.validate.opendkim.get_sig](/momentum/4/lua/ref-msys-validate-opendkim-get-sig), [msys.validate.opendkim.get_sig_domain](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-domain), [msys.validate.opendkim.get_sig_errorstr](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-errorstr), [msys.validate.opendkim.get_sig_flags](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-flags)

content/momentum/4/lua/ref-msys-validate-opendkim-get-sig-errorstr.md

@@ -1,5 +1,5 @@
 ---
-lastUpdated: "03/26/2020"
+lastUpdated: "08/11/2026"
 title: "msys.validate.opendkim.get_sig_errorstr"
 description: "msys validate opendkim get sig errorstr Fetch the error associated with a DKIM signature msys validate opendkim get sig errorstr dkim sig This function fetches the error associated with a DKIM signature Use msys validate opendkim get num sigs and msys validate opendkim get sig to get a DKIM SIGINFO..."
 ---
@@ -23,7 +23,9 @@ This function requires the [`opendkim`](/momentum/4/modules/opendkim) module.
 
 Enable this function with the statement `require('msys.validate.opendkim');`.
 
-This function returns the error string associated with the DKIM signature (if it exists) and the DKIM status `DKIM_STAT`.
+This function returns the error string associated with the DKIM signature and the DKIM status `DKIM_STAT`. For a valid DKIM signature, it returns the literal string `"no signature error"`. It returns nil only when `dkim_sig` itself is nil, together with the DKIM status `DKIM_STAT_INVALID`.
+
+Be cautious when using this function to decide whether a signature is verified: it never returns nil for an existing signature, and a failing signature can also report `"no signature error"` when the failure (for example, a body hash mismatch) is not recorded as a signature error. To derive a pass/fail verdict, use [msys.validate.opendkim.get_sig_ar_verdict](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-ar-verdict).
 
 The DKIM status `DKIM_STAT` can be one of the following values:
 
@@ -60,4 +62,4 @@ The DKIM status `DKIM_STAT` can be one of the following values:
 <a name="idp18794160"></a> 
 ## See Also
 
-[msys.validate.opendkim.get_sig_canons](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-canons), [msys.validate.opendkim.sign](/momentum/4/lua/ref-msys-validate-opendkim-sign), [msys.validate.opendkim.verify](/momentum/4/lua/ref-msys-validate-opendkim-verify), [msys.validate.opendkim.get_num_sigs](/momentum/4/lua/ref-msys-validate-opendkim-get-num-sigs), [msys.validate.opendkim.get_sig](/momentum/4/lua/ref-msys-validate-opendkim-get-sig), [msys.validate.opendkim.get_sig_domain](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-domain), [msys.validate.opendkim.get_sig_selector](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-selector), [msys.validate.opendkim.get_sig_flags](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-flags), [msys.validate.opendkim.get_sig_identity](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-identity), [msys.validate.opendkim.get_sig_keysize](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-keysize), [msys.validate.opendkim.get_sig_signalg](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-signalg), [msys.validate.opendkim.get_sig_hdrsigned](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-hdrsigned)
+[msys.validate.opendkim.get_sig_ar_verdict](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-ar-verdict), [msys.validate.opendkim.get_sig_canons](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-canons), [msys.validate.opendkim.sign](/momentum/4/lua/ref-msys-validate-opendkim-sign), [msys.validate.opendkim.verify](/momentum/4/lua/ref-msys-validate-opendkim-verify), [msys.validate.opendkim.get_num_sigs](/momentum/4/lua/ref-msys-validate-opendkim-get-num-sigs), [msys.validate.opendkim.get_sig](/momentum/4/lua/ref-msys-validate-opendkim-get-sig), [msys.validate.opendkim.get_sig_domain](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-domain), [msys.validate.opendkim.get_sig_selector](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-selector), [msys.validate.opendkim.get_sig_flags](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-flags), [msys.validate.opendkim.get_sig_identity](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-identity), [msys.validate.opendkim.get_sig_keysize](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-keysize), [msys.validate.opendkim.get_sig_signalg](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-signalg), [msys.validate.opendkim.get_sig_hdrsigned](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-hdrsigned)

content/momentum/4/lua/ref-msys-validate-opendkim-get-stat-ar-verdict.md

@@ -0,0 +1,39 @@
+---
+lastUpdated: "08/11/2026"
+title: "msys.validate.opendkim.get_stat_ar_verdict"
+description: "msys validate opendkim get stat ar verdict Map a DKIM verification status with no per signature verdict to an Authentication Results result msys validate opendkim get stat ar verdict stat This function maps the DKIM STAT returned by msys validate opendkim verify to a result string or returns nil when the per signature results are authoritative..."
+---
+
+<a name="lua.ref.msys.validate.opendkim.get_stat_ar_verdict"></a> 
+## Name
+
+msys.validate.opendkim.get_stat_ar_verdict — Map a DKIM verification status with no per-signature verdict to an Authentication-Results result
+
+<a name="idp18915744"></a> 
+## Synopsis
+
+`msys.validate.opendkim.get_stat_ar_verdict(stat)`
+
+`stat: number, DKIM_STAT returned by msys.validate.opendkim.verify`<a name="idp18919200"></a> 
+## Description
+
+This function maps the overall verification status returned by `msys.validate.opendkim.verify` to a result string for the `dkim` clause of an `Authentication-Results` header, for the statuses that carry no per-signature verdict. It returns:
+
+*   `"none (message not signed)"` – the message carried no DKIM signature (`DKIM_STAT_NOSIG`).
+
+*   `nil` – the per-signature results are authoritative (`DKIM_STAT_OK`, `DKIM_STAT_BADSIG`, `DKIM_STAT_NOKEY`, `DKIM_STAT_CANTVRFY`, `DKIM_STAT_REVOKED`); iterate the signatures and report `msys.validate.opendkim.get_sig_ar_verdict` for each.
+
+*   `"permerror (signature syntax error)"` – the message could not be evaluated (`DKIM_STAT_SYNTAX`).
+
+*   `"temperror (verification status <n>)"` – any other status, including key-retrieval tempfails (`DKIM_STAT_KEYFAIL`) and internal or resource errors; verification may succeed if retried later.
+
+See the [msys.validate.opendkim.get_sig_ar_verdict](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-ar-verdict) page for a usage example combining both functions.
+
+This function requires the [`opendkim`](/momentum/4/modules/opendkim) module.
+
+Enable this function with the statement `require('msys.validate.opendkim');`.
+
+<a name="idp18957456"></a> 
+## See Also
+
+[msys.validate.opendkim.get_sig_ar_verdict](/momentum/4/lua/ref-msys-validate-opendkim-get-sig-ar-verdict), [msys.validate.opendkim.verify](/momentum/4/lua/ref-msys-validate-opendkim-verify), [msys.validate.opendkim.get_num_sigs](/momentum/4/lua/ref-msys-validate-opendkim-get-num-sigs), [msys.validate.opendkim.get_sig](/momentum/4/lua/ref-msys-validate-opendkim-get-sig)