EOP-281: OpenARC module and APIs #782
Conversation
✅ Deploy Preview for support-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
| 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. |
| either `verify` or `sign` but not both. | ||
| It's recommended to invoke `msys.validate.opendarc.verify` in `validate_data_spool` or | ||
| [`validate_data_spool_each_rcpt`](/momentum/3/3-api/hooks-core-validate-data-spool-each-rcpt) hook. | ||
| `msys.validate.opendarc.sign` shall be invoked in the last validation phase, in |
| ### Note | ||
|
|
||
| If the `ec_message` context variable `arc_cv` is not set after this function call, errors happened | ||
| and logged into paniclog. |
| <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 |
| 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. |
There was a problem hiding this comment.
I'm guessing "none" means no ARC headers rather than the status of "cv=none" which is normal for just one ARC header set?
There was a problem hiding this comment.
none means cv=none in ARC-Seal, also means no ARC headers.
| * `authservid` – authentication service identifier, as | ||
| [authserv-id](https://datatracker.ietf.org/doc/html/rfc8601#section-2.5) defined in RFC. | ||
|
|
||
| If not set, will be default to the hostname. |
There was a problem hiding this comment.
Curious why we default to the hostname. According to the RFC, Common practice is to use the DNS domain name used by or within that ADMD, sometimes called the "organizational domain"
FWIW, the perl module I use that does signing (Mail::DKIM::ARC::Signer) requires the first token in the (required) AR header to match the srvid input, and this input defaults to the domain input.
There was a problem hiding this comment.
Also, should be "will default to" or "will be defaulted to".
There was a problem hiding this comment.
It's the authservid Momo use for Authentication-Results 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. |
|
|
||
| ### Note | ||
|
|
||
| Since ARC sealing should happen after all potential modification of a message is done, this function |
There was a problem hiding this comment.
Maybe something a little stronger like "must not happen until all"
| This hook is invoked right after the | ||
| [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. |
There was a problem hiding this comment.
I'd suggest "writing the message to spool for delivery".
| 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 | ||
| `final_validtion`. | ||
| No any message modification expected after this stage. |
There was a problem hiding this comment.
No message modification is expected
| It guarantees that operations implemented in this hook will happen after the operations done in | ||
| `final_validtion`. | ||
| No any message modification expected after this stage. | ||
| To avoid undefined race between multiple implementations of the same hook, you shall only have up |
There was a problem hiding this comment.
I'd suggest "ordering" rather than "race" and "you should have at most one"
approved
| This hook is added as the absolute last point before writing the message to spool for delivery. | ||
| It guarantees that operations implemented in this hook will happen after the operations done in | ||
| `final_validation`. | ||
| No message modification is expected after this stage. |
There was a problem hiding this comment.
What's the behavior If it is modified after this stage? Can we clarify the wording.
There was a problem hiding this comment.
I removed this line, since it's not the new behavior introduced by the code.
What Changed
How To Test or Verify
PR Checklist
Below are some checklists to follow for the correct procedure in different circumstance. The first list ("All PRs Checklist") should be followed for ALL PRs. The next 2 are additive to this list depending on what type of PR you are using.
For example: If you are submitting a content change to one of the support documents, your checklist would include the:
If you are submitting a feature addition, enhancement, or bug fix, your checklist would include the:
All PRs Checklist
team-FEorteam-SAZ)Content Changes Checklist
examples/article.mdin the root of the project directory and on the momentum doc's preface articleDevelopment Changes Checklist (some checks are automatic github actions and will not be listed here. ie. "all tests pass")
cypress/directory in the root of the project