From a82d27004f73411967ac75fbf483d3354d428e12 Mon Sep 17 00:00:00 2001 From: Dominik Chilla Date: Mon, 5 Jun 2023 21:55:04 +0200 Subject: [PATCH] docs: ENV-options + tests refactoring --- README.md | 31 ++++++++++++++++++++- tests/miltertest.lua | 34 ++++++++++++++--------- tests/miltertest_conn_reuse_fail_pass.lua | 16 +++++------ 3 files changed, 59 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 719f64b..e54486d 100644 --- a/README.md +++ b/README.md @@ -147,4 +147,33 @@ Take a look [here](OCI/README.md) First of all please take a look at how to set up the testing environment, which is described [here](tests/README.md) # How to install on docker/kubernetes/systemd? -The installation procedure is documented [here](INSTALL/README.md) \ No newline at end of file +The installation procedure is documented [here](INSTALL/README.md) + +# How to *configure* the ExOTA-Milter? + +|ENV variable|type|default|description| +|---|---|---|---| +|MILTER_NAME|`string`|`exota-milter`|Name of the milter instance. Base for socket path. Name appears in logs | +|MILTER_SOCKET|`string`|`/socket/`|Defines the filesystem path of milter socket. The milter can be also exposed as a tcp-socket like `inet:4321@127.0.0.1`| +|MILTER_REJECT_MESSAGE|`string`|`Security policy violation!`|Milter reject (SMTP 5xx code) message presented to the calling MTA| +|MILTER_TMPFAIL_MESSAGE|`string`|`Service temporarily not available! Please try again later.`|Milter temporary fail (SMTP 4xx code) message presentetd to the calling MTA.| +|MILTER_TENANT_ID_REQUIRED|`bool`|`false`|Controls the requirement of the presence of the unofficial `X-MS-Exchange-CrossTenant-Id` header. Used as additional authentication factor.| +|MILTER_DKIM_ENABLED|`bool`|`false`|Enables/disables the checking of DKIM authentication results. Used as additional but strong authentication factor.| +|MILTER_DKIM_ALIGNMENT_REQUIRED|`bool`|`false`|Enables/disables the alighment checks of DKIM SDID with RFC-5322.from_domain. Requires ENV[MILTER_DKIM_ENABLED] = `true`| +|MILTER_TRUSTED_AUTHSERVID|`string`|`invalid`|Specifies the trusted DKIM-signature validating entity (DKIM-validator - producer of Authentication-Results header). The DKIM-validator must place exactly the same string as configured here into the Authentication-Results header! Requires ENV[MILTER_DKIM_ENABLED] = `true`| +|MILTER_POLICY_SOURCE|`string`|`file`|Policy source - Possible values `file` (JSON) or `ldap`| +|MILTER_POLICY_FILE|`string`|`/data/policy.json`|Filesystem path to the (JSON) policy file. Requires ENV[MILTER_POLICY_SOURCE] = `file`| +|MILTER_X509_ENABLED|`bool`|`false`|Enables/disables the checking of client x509-certificate. Used as additional authentication factor.| +|MILTER_X509_TRUSTED_CN|`string`|`mail.protection.outlook.com`|FQDN of authenticating client MTA. Requires ENV[MILTER_X509_ENABLED] = `true`| +|MILTER_X509_IP_WHITELIST|Whitespace or comma separated list of `string`|`127.0.0.1,::1`|List of IP-addresses for which the ExOTA-Milter skips x509 checks. Requires ENV[MILTER_X509_ENABLED] = `true`| +|MILTER_ADD_HEADER|`bool`|`false`|Controls if the ExOTA-Milter should write an additional `X-ExOTA-Authentication-Results` header with authentication information| +|MILTER_AUTHSERVID|`string`|empty|Provides ID of authenticating entity within `X-ExOTA-Authentication-Results` header to further validating instances. Required when ENV[MILTER_ADD_HEADER] = `true`| +|MILTER_LDAP_SERVER_URI|`string`|empty|LDAP-URI of LDAP server holding ExOTA policies. Required when ENV[MILTER_POLICY_SOURCE] = `ldap`| +|MILTER_LDAP_RECEIVE_TIMEOUT|`int`|5|Timespan the ExOTA-Milter waits for the LDAP server to respond to a request. This NOT the TCP-connect timeout! Requires ENV[MILTER_POLICY_SOURCE] = `ldap`| +|MILTER_LDAP_BINDDN|`string`|empty|Distinguished name of the binding (authenticating) *user*| +|MILTER_LDAP_BINDPW|`string`|empty|Password of the binding (authenticating) *user*| +|MILTER_LDAP_SEARCH_BASE|`string`|empty|Search base-DN on the LDAP server. Required when ENV[MILTER_POLICY_SOURCE] = `ldap`| +|MILTER_LDAP_QUERY|`string`|empty|LDAP query/filter used to match for a ExOTA-policy. A placeholder must be used to filter for the authenticating domain (`%d`), e.g. `(domain_attribute=%d)`| +|MILTER_LDAP_TENANT_ID_ATTR|`string`|`exotaMilterTenantId`|Custom LDAP attribute name unless using the ExOTA-milter LDAP schema| +|MILTER_LDAP_DKIM_ENABLED_ATTR|`string`|`exotaMilterDkimEnabled`|Custom LDAP attribute name unless using the ExOTA-milter LDAP schema| +|MILTER_LDAP_DKIM_ALIGNMENT_REQIRED_ATTR|`string`|`exotaMilterDkimAlignmentRequired`|Custom LDAP attribute name unless using the ExOTA-milter LDAP schema| diff --git a/tests/miltertest.lua b/tests/miltertest.lua index bc9ad04..83d8acd 100644 --- a/tests/miltertest.lua +++ b/tests/miltertest.lua @@ -37,37 +37,45 @@ if mt.header(conn, "fRoM", '"Blah Blubb" ') ~= nil then - error "mt.header(From) failed" + error "mt.header(Resent-From) failed" end if mt.header(conn, "x-mS-EXCHANGE-crosstenant-id", "1234abcd-18c5-45e8-88de-123456789abc") ~= nil then - error "mt.header(Subject) failed" + error "mt.header(X-MS-Exchange-CrossTenant-Id) failed" +end + +dkim_sig = "v=1; a=rsa-sha256; c=relaxed/simple; d=staging.zwackl.de;\n" +.."\ts=selector-xyz; t=1685872089;\n" +.."\tbh=5/ZUJAdcuyAn6J+J6apWtAaJLbDCKkI5Ie31qVKiY0w=;\n" +.."\th=Date:From:To:Subject:MIME-Version:Content-Type;\n" +.."\tb=Bn/xAbFFjAg1b9bBFPHAYSaupsnL4pzPPDUauetfGB0hu0Qz0Dio+4Z2Vi6PMOesA\n" +.."\t72VbehuxG+b++XVL/hs3+K6p7vTgVAWiWAZLvfs5bHE5HAalsCrNenpKTk6RUcSYtw\n" +.."\tLiiYhvw0TR5LbyNoSPG2J16mXEcS+k2q+K7WfwMg=" +if mt.header(conn, "DKIM-Signature", dkim_sig) ~= nil then + error "mt.header(DKIM-Signature) failed" end ---if mt.header(conn, "X-MS-Exchange-CrossTenant-Id", "4321abcd-18c5-45e8-88de-blahblubb") ~= nil then --- error "mt.header(Subject) failed" ---end if mt.header(conn, "Authentication-Results", "another-wrong-auth-serv-id;\n dkim=fail header.d=yad.onmicrosoft.com header.s=selector1-yad-onmicrosoft-com header.b=mmmjFpv8") ~= nil then - error "mt.header(Subject) failed" + error "mt.header(Authentication-Results) failed" end if mt.header(conn, "Authentication-Results", "wrong-auth-serv-id;\n dkim=pass header.d=yad.onmicrosoft.com header.s=selector1-yad-onmicrosoft-com header.b=mmmjFpv8") ~= nil then - error "mt.header(Subject) failed" + error "mt.header(Authentication-Results) failed" end if mt.header(conn, "Authentication-Results", "my-auth-serv-id;\n exota=pass") ~= nil then - error "mt.header(Subject) failed" + error "mt.header(Authentication-Results) failed" end if mt.header(conn, "Authentication-RESULTS", "my-auth-serv-id;\n dkim=pass header.d=yad.onmicrosoft.comx header.s=selector1-yad-onmicrosoft-com header.b=mmmjFpv8") ~= nil then - error "mt.header(Subject) failed" + error "mt.header(Authentication-Results) failed" end if mt.header(conn, "Authentication-RESULTS", "my-auth-serv-id;\n dkim=pass header.d=staging.zwackl.de header.s=selector1-yad-onmicrosoft-com header.b=mmmjFpv8") ~= nil then - error "mt.header(Subject) failed" + error "mt.header(Authentication-Results) failed" end if mt.header(conn, "Authentication-Results", "my-auth-serv-id;\n dkim=fail header.d=yad.onmicrosoft.com header.s=selector2-asdf header.b=mmmjFpv8") ~= nil then - error "mt.header(Subject) failed" + error "mt.header(Authentication-Results) failed" end if mt.header(conn, "Authentication-Results", "some-validating-host;\n dkim=pass header.d=paypal.de header.s=pp-dkim1 header.b=PmTtUzer;\n dmarc=pass (policy=reject) header.from=paypal.de;\n spf=pass (some-validating-host: domain of service@paypal.de designates 173.0.84.226 as permitted sender) smtp.mailfrom=service@paypal.de") ~= nil then - error "mt.header(Subject) failed" + error "mt.header(Authentication-Results) failed" end if mt.header(conn, "X-ExOTA-Authentication-Results", "my-auth-serv-id;\n exota=pass") ~= nil then - error "mt.header(Subject) failed" + error "mt.header(X-ExOTA-Authentication-Results) failed" end -- EOM diff --git a/tests/miltertest_conn_reuse_fail_pass.lua b/tests/miltertest_conn_reuse_fail_pass.lua index 89cdf00..38e72af 100644 --- a/tests/miltertest_conn_reuse_fail_pass.lua +++ b/tests/miltertest_conn_reuse_fail_pass.lua @@ -35,13 +35,13 @@ if mt.header(conn, "fRoM", '"Blah Blubb"