EOP-281: OpenARC module and APIs #782
Open
+322
−3
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
✅ Deploy Preview for support-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
dkoerichbird
requested changes
Nov 26, 2024
| @@ -174,6 +174,8 @@ This section contains tables of Lua functions. Click the function name for detai | |||
| | [msys.unlock](/momentum/4/lua/ref-msys-unlock) – Releases a lock obtained via msys.lock | mutexname | msys | 4.0 | any | | |||
| | [msys.validate.dk.get_responsible_domain](/momentum/4/lua/ref-msys-validate-dk-get-responsible-domain) – This function requires module "dk_validate". "msg" is a mail message. "ctx" is the validation context. It returns the responsible domain for the current message | msg, ctx | msys.validate.dk | 4.0 | data, data_spool, data_spool_each_rcpt | | |||
| | [msys.validate.dk.sign](/momentum/4/lua/ref-msys-validate-dk-sign) – Sign a message using a Domain Key | msg, ctx, options | msys.validate.dk | 4.0 | core_data_validation | | |||
| | [msys.validate.openarc.sign](/momentum/4/lua/ref-msys-validate-openarc-sign) – Sign a message using OpenARC | msg, options, [ar] | msys.validate.openarc | 5.0 | core_post_final_validation | | |||
There was a problem hiding this comment.
Please update the header (lastUpdated) with the new revision date. This applies to other changed files as well.
| @@ -11,6 +11,7 @@ description: "This chapter includes hook point and C function reference material | |||
| |---------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------| | |||
| | [msg_gen_data_spool](/momentum/4/hooks/msg-gen-data-spool) | This hook is invoked after a message has been generated by the msg_gen module | | |||
| | [config_rsrc_setup](/momentum/4/hooks/config-rsrc-setup) | Register a resource | | |||
| | [core_post_final_validation](/momentum/4/hooks/core-post-final-validation) | Same usage as but invoked right after the `core_final_validation` hook | | |||
There was a problem hiding this comment.
Change to post_final_validation for consistency with the target link.
| @@ -174,6 +174,8 @@ This section contains tables of Lua functions. Click the function name for detai | |||
| | [msys.unlock](/momentum/4/lua/ref-msys-unlock) – Releases a lock obtained via msys.lock | mutexname | msys | 4.0 | any | | |||
| | [msys.validate.dk.get_responsible_domain](/momentum/4/lua/ref-msys-validate-dk-get-responsible-domain) – This function requires module "dk_validate". "msg" is a mail message. "ctx" is the validation context. It returns the responsible domain for the current message | msg, ctx | msys.validate.dk | 4.0 | data, data_spool, data_spool_each_rcpt | | |||
| | [msys.validate.dk.sign](/momentum/4/lua/ref-msys-validate-dk-sign) – Sign a message using a Domain Key | msg, ctx, options | msys.validate.dk | 4.0 | core_data_validation | | |||
| | [msys.validate.openarc.sign](/momentum/4/lua/ref-msys-validate-openarc-sign) – Sign a message using OpenARC | msg, options, [ar] | msys.validate.openarc | 5.0 | core_post_final_validation | | |||
There was a problem hiding this comment.
Wouldn't it be necessary to mention the synonym msys.validate.openarc.seal as well?
| 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 | ||
| `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 | ||
| to one implementation for this hook. | ||
| It's the recommended hook point for ARC signing/sealing. |
There was a problem hiding this comment.
Suggestion: use "quote" syntax to highlight it
It's the recommended hook point for ARC sealing.
Refer to content/momentum/4/eol-policy.md for an example (the footnotes below the table)
| 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. |
|
|
||
| ### Lua APIs and examples | ||
|
|
||
| [msys.validate.opendarc.verify](/momentum/4/lua/ref-msys-validate-openarc-verify) |
|
|
||
| [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, |
|
|
||
| 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` or |
kkelley1
reviewed
Dec 4, 2024
| 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?
| * `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".
| ### 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"
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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