mirror of
https://github.com/mailscope/kumomta.git
synced 2026-08-18 18:38:18 +00:00
Wez Furlong
68 lines
2.4 KiB
Markdown
68 lines
2.4 KiB
Markdown
# Authentication Result Object
|
|
|
|
{{since('2023.11.28-b5252a41')}}
|
|
|
|
This object represents parsed individual *Authentication Result* as specified by [RFC
|
|
8601](https://datatracker.ietf.org/doc/html/rfc8601). Technically speaking, each
|
|
instance of the object corresponds to the parsed form of the `resinfo` term specified
|
|
by the RFC. It doesn't represent an entire header value, just an individual result
|
|
for an individual authentication method.
|
|
|
|
Certain verification methods return arrays of authentication results for you to
|
|
act upon in your policy and/or add to incoming message as headers.
|
|
|
|
The object has the following fields:
|
|
|
|
* `method` - required string; the authentication method
|
|
* `method_version` - optional integer; the version of the authentication method
|
|
* `result` - required string; the result of the authentication method.
|
|
* `reason` - optional string; an explanation of why the method produced that result
|
|
* `props` - a table with string keys and values containing various
|
|
method-specific properties that describe additional information about this
|
|
result. For example, for DKIM results, this will often contain copies of
|
|
some of the DKIM signature fields in order to correlate a given result with
|
|
the appropriate DKIM signature header when multiple signatures are present.
|
|
|
|
## Example: obtaining DKIM authentication results
|
|
|
|
This will verify the DKIM signatures that are present in the message
|
|
and return an array of authentication results:
|
|
|
|
```lua
|
|
kumo.on('smtp_server_message_received', function(msg)
|
|
-- Verify the dkim signature and return the results.
|
|
-- Note that this example isn't making any policy decisions;
|
|
-- it is only annotating the message with the results and
|
|
-- allowing it to be relayed
|
|
local verify = msg:dkim_verify()
|
|
print('dkim', kumo.json_encode_pretty(verify))
|
|
-- Add the results to the message
|
|
msg:add_authentication_results(msg:get_meta 'hostname', verify)
|
|
end)
|
|
```
|
|
|
|
might print something like this to the diagnostic log:
|
|
|
|
```
|
|
dkim [
|
|
{
|
|
"props": {
|
|
"header.d": "github.com",
|
|
"header.i": "@github.com",
|
|
"header.s": "pf2023",
|
|
"header.a": "rsa-sha256",
|
|
"header.b": "jo0EO4dX"
|
|
},
|
|
"result": "pass",
|
|
"method": "dkim",
|
|
"reason": null,
|
|
"method_version": null
|
|
}
|
|
]
|
|
```
|
|
|
|
## See Also:
|
|
|
|
* [msg:add_authentication_results()](message/add_authentication_results.md)
|
|
* [msg:dkim_verify()](message/dkim_verify.md)
|