{"id":21814325,"url":"https://github.com/snawoot/postfix-mta-sts-resolver","last_synced_at":"2025-11-12T21:41:50.352Z","repository":{"id":33073278,"uuid":"150882778","full_name":"Snawoot/postfix-mta-sts-resolver","owner":"Snawoot","description":"Daemon which provides TLS client policy for Postfix via socketmap, according to domain MTA-STS policy","archived":false,"fork":false,"pushed_at":"2025-02-04T22:46:43.000Z","size":445,"stargazers_count":123,"open_issues_count":4,"forks_count":24,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-14T05:19:13.566Z","etag":null,"topics":["mta-sts","postfix","postfix-helper","postfix-policy-server","postfix-smtp","smtp-sts","sts"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Snawoot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-09-29T16:29:14.000Z","updated_at":"2025-03-27T16:47:56.000Z","dependencies_parsed_at":"2024-06-18T22:44:59.973Z","dependency_job_id":"436cd810-c992-4374-b3a5-d3a0a6edae97","html_url":"https://github.com/Snawoot/postfix-mta-sts-resolver","commit_stats":{"total_commits":344,"total_committers":22,"mean_commits":"15.636363636363637","dds":"0.26453488372093026","last_synced_commit":"1273febe6887f8288f71a661e1d4c08404f94b71"},"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Snawoot%2Fpostfix-mta-sts-resolver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Snawoot%2Fpostfix-mta-sts-resolver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Snawoot%2Fpostfix-mta-sts-resolver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Snawoot%2Fpostfix-mta-sts-resolver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Snawoot","download_url":"https://codeload.github.com/Snawoot/postfix-mta-sts-resolver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248824733,"owners_count":21167351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mta-sts","postfix","postfix-helper","postfix-policy-server","postfix-smtp","smtp-sts","sts"],"created_at":"2024-11-27T14:37:43.927Z","updated_at":"2025-11-12T21:41:50.316Z","avatar_url":"https://github.com/Snawoot.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"postfix-mta-sts-resolver\n========================\n\n[![Build Status](https://travis-ci.org/Snawoot/postfix-mta-sts-resolver.svg?branch=master)](https://travis-ci.org/Snawoot/postfix-mta-sts-resolver) [![Coverage](https://img.shields.io/badge/coverage-97%25-4dc71f.svg)](https://travis-ci.org/Snawoot/postfix-mta-sts-resolver) [![PyPI - Downloads](https://img.shields.io/pypi/dm/postfix-mta-sts-resolver.svg?color=4dc71f\u0026label=PyPI%20downloads)](https://pypistats.org/packages/postfix-mta-sts-resolver) [![PyPI](https://img.shields.io/pypi/v/postfix-mta-sts-resolver.svg)](https://pypi.org/project/postfix-mta-sts-resolver/) [![PyPI - Status](https://img.shields.io/pypi/status/postfix-mta-sts-resolver.svg)](https://pypi.org/project/postfix-mta-sts-resolver/) [![PyPI - License](https://img.shields.io/pypi/l/postfix-mta-sts-resolver.svg?color=4dc71f)](https://pypi.org/project/postfix-mta-sts-resolver/) [![postfix-mta-sts-resolver](https://snapcraft.io//postfix-mta-sts-resolver/badge.svg)](https://snapcraft.io/postfix-mta-sts-resolver) ![CodeQL](https://github.com/Snawoot/postfix-mta-sts-resolver/workflows/CodeQL/badge.svg)\n\nDaemon which provides TLS client policy for Postfix via socketmap, according to domain MTA-STS policy.\n\nCurrent support of [RFC 8461](https://www.rfc-editor.org/rfc/rfc8461) is limited:\n\n* [MTA-STS policy overrides DANE TLS authentication](#warning-mta-sts-policy-overrides-dane-tls-authentication) against [RFC 8461, 2](https://www.rfc-editor.org/rfc/rfc8461#section-2).\n\n* Daemon lacks some minor features:\n\n  * Fetch error reporting.\n  * Fetch ratelimit (but actual fetch rate partially restricted with `cache_grace` config option).\n\nServer has configurable cache backend which allows to store cached STS policies in memory (`internal`), file (`sqlite`) or in Redis database (`redis`).\n\n## Requirements\n\n* Postfix 3.4+ (or Postfix 2.10+ if missing Postfix SNI feature is tolerable. In that case you have to set zone option `require_sni` to `false` in MTA-STS daemon config)\n* Python 3.5.3+ (see [\"Systems without Python 3.5+\"](#systems-without-python-35) below if you haven't one, or use Docker installation method)\n* aiodns\n* aiohttp\n* aiosqlite\n* redis-py\n* PyYAML\n* (optional) uvloop\n\nAll dependency packages installed automatically if this package is installed via pip.\n\n\n## Installation\n\n### Method 1. System-wide install from PyPI (recommended for humans)\n\nRun:\n\n```bash\nsudo python3 -m pip install postfix-mta-sts-resolver[redis,sqlite,postgres]\n```\n\nIf you don't need `redis` or `sqlite` support, you may omit one of them in square brackets. If you don't need any of them and you plan to use internal cache without persistence, you should also omit square brackets.\n\nPackage scripts shall be available in standard executable locations upon completion.\n\n#### pip user install\n\nAll pip invocations can be run with `--user` option of `pip` installer. In this case superuser privileges are not required and package(s) are getting installed into user home directory. Usually, script executables will appear in `~/.local/bin`.\n\n### Method 2. System-wide install from project source\n\nRun in project directory:\n\n```bash\nsudo python3 -m pip install .[redis,sqlite,postgres]\n```\n\nIf you don't need `redis`, `sqlite` or `postgres` support, you may omit one of them in square brackets. If you don't need any of them and you plan to use internal cache without persistence, you should also omit square brackets.\n\nPackage scripts shall be available in standard executable locations upon completion.\n\n\n### Method 3. Install into virtualenv\n\nSee [\"Building virtualenv\"](#building-virtualenv)\n\n### Method 4. Docker\n\nRun\n\n```bash\ndocker volume create mta-sts-cache\ndocker run -d \\\n    --security-opt no-new-privileges \\\n    -v mta-sts-cache:/var/lib/mta-sts \\\n    -p 127.0.0.1:8461:8461 \\\n    --restart unless-stopped \\\n    --name postfix-mta-sts-resolver \\\n    yarmak/postfix-mta-sts-resolver\n```\n\nDaemon will be up and running, listening on local interface on port 8461. Default configuration baked into docker image uses SQLite for cache stored in persistent docker volume. You may override this configuration with your own config file by mapping it into container with option `-v my_config.yml:/etc/mta-sta-daemon.yml`.\n\n### Method 5. Snap Store\n\n[![Get it from the Snap Store](https://snapcraft.io/static/images/badges/en/snap-store-black.svg)](https://snapcraft.io/postfix-mta-sts-resolver)\n\n```bash\nsudo snap install postfix-mta-sts-resolver\n```\n\nNOTE: in snap layout `mta-sta-daemon` program is named `postfix-mta-sts-resolver.daemon` and `mta-sts-query` is named `postfix-mta-sts-resolver.query`.\n\n### Common installation notes\n\nSee also [contrib/README.md](https://github.com/Snawoot/postfix-mta-sts-resolver/tree/master/contrib/README.md) for RHEL/OEL/Centos and FreeBSD notes.\n\nSee [contrib/](https://github.com/Snawoot/postfix-mta-sts-resolver/tree/master/contrib) for example of systemd unit file suitable to run daemon under systemd control.\n\n## Running\n\nThis package provides two executables available after installation in respective locations.\n\n\n### mta-sts-query\n\n`mta-sts-query` is a command line tool which fetches and outputs domain MTA-STS policies. Intended to be used for debug purposes.\n\nSynopsis:\n\n```\n$ mta-sts-query --help\nusage: mta-sts-query [-h] [-v {debug,info,warn,error,fatal}]\n                     domain [known_version]\n\npositional arguments:\n  domain                domain to fetch MTA-STS policy from\n  known_version         latest known version (default: None)\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -v {debug,info,warn,error,fatal}, --verbosity {debug,info,warn,error,fatal}\n                        logging verbosity (default: warn)\n```\n\n### mta-sts-daemon\n\n`mta-sts-daemon` is a daemon which provides external [TLS policy for Postfix SMTP client](http://www.postfix.org/TLS_README.html#client_tls_policy) via [socketmap interface](http://www.postfix.org/socketmap_table.5.html).\n\nYou may find useful systemd unit file to run daemon in [contrib/](https://github.com/Snawoot/postfix-mta-sts-resolver/tree/master/contrib).\n\nSynopsis:\n\n```\n$ mta-sts-daemon --help\nusage: mta-sts-daemon [-h] [-v {debug,info,warn,error,fatal}] [-c FILE]\n                      [-l FILE] [--disable-uvloop]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -v {debug,info,warn,error,fatal}, --verbosity {debug,info,warn,error,fatal}\n                        logging verbosity (default: info)\n  -c FILE, --config FILE\n                        config file location (default: /etc/mta-sts-\n                        daemon.yml)\n  -l FILE, --logfile FILE\n                        log file location (default: None)\n  --disable-uvloop      do not use uvloop even if it is available (default:\n                        False)\n```\n\n#### Seamless restart/upgrade/reload and load balancing\n\nBy default mta-sts-daemon allows its multiple instances to share same port (on Linux/FreeBSD/Windows). Therefore, restart or upgrade of daemon can be performed seamlessly. Set of unit files for systemd in [contrib/](contrib/) directory implements \"reload\" by mean of running backup instance when main instance is getting restarted.\n\nAlso on Linux and FreeBSD, load distributed across all processes (with SO\\_REUSEPORT and SO\\_REUSEPORT\\_LB respectively).\n\n\n## MTA-STS Daemon configuration\n\nSee [configuration man page](https://github.com/Snawoot/postfix-mta-sts-resolver/blob/master/man/mta-sts-daemon.yml.5.adoc) and [config\\_examples/](https://github.com/Snawoot/postfix-mta-sts-resolver/tree/master/config_examples) directory. Default config location is: `/etc/mta-sts-daemon.yml`, but it can be overridden with command line option `-c FILE`.\n\nAll options is self-explanatory, only exception is `strict_testing` option. If set to `true`, STS policy will be enforced even if domain announces `testing` MTA-STS mode. Useful for premature incorporation of MTA-STS against domains hesitating to go `enforce`. Please use with caution.\n\n\n## Postfix configuration\n\nSMTP client of your Postfix instance must be able to validate peer certificates. In order to achieve that, you have to ensure [`smtp_tls_CAfile`](http://www.postfix.org/postconf.5.html#smtp_tls_CAfile) or [`smtp_tls_CApath`](http://www.postfix.org/postconf.5.html#smtp_tls_CApath) points to system CA bundle. Otherwise you'll get `Unverified TLS connection` even for peers with valid certificate, and delivery failures for MTA-STS-enabled destinations. Also note: even enabled [`tls_append_default_CA`](http://www.postfix.org/postconf.5.html#tls_append_default_CA) will not work alone if both `smtp_tls_CAfile` and `smtp_tls_CApath` are empty.\n\nOnce certificate validation is enabled and your Postfix log shows \"Trusted TLS connection ... \" for destinations with valid certificates signed by public CA, you may enable MTA-STS by adding following line to `main.cf`:\n\n```\nsmtp_tls_policy_maps = socketmap:inet:127.0.0.1:8461:postfix\n```\n\nIf your configuration already has some TLS policy maps, just add MTA-STS socketmap to list of configured maps accordingly to [`smtp_tls_policy_maps`](http://www.postfix.org/postconf.5.html#smtp_tls_policy_maps) syntax. TLS policy tables are searched in the specified order until a match is found, so you may have table with local overrides of TLS policy prior to MTA-STS socketmap. This may be useful for skipping network lookup for well-known destinations or relaxing security for broken destinations, announcing MTA-STS support.\n\nReload Postfix after reconfiguration.\n\n\n### Warning: MTA-STS policy overrides DANE TLS authentication\n\nDue to Postfix's limitations, a resolved MTA-STS policy overrides DANE TLS authentication ([RFC 6698](https://www.rfc-editor.org/rfc/rfc6698)), because DANE is an internal feature of Postfix, and the postfix-mta-sts-resolver always responds with a ([`smtp_tls_policy_maps`](https://www.postfix.org/postconf.5.html#smtp_tls_policy_maps)) lookup result `secure` for [Secure server certificate verification](https://www.postfix.org/TLS_README.html#client_tls_secure).\n\n  * The resulting behaviour is against [RFC 8461, 2](https://www.rfc-editor.org/rfc/rfc8461#section-2):\n    \u003e However, MTA-STS is designed not to interfere with DANE deployments when the two overlap; in particular, senders who implement MTA-STS validation MUST NOT allow MTA-STS Policy validation to override a failing DANE validation.\n    \n    Domains implementing both MTA-STS and DANE probably want DANE to be preferred:\n    \n      * DANE allows strict binding of certificates; the policy can authorize only a certain certificate or certificates from a certain CA. With MTA-STS, a certificate from any trusted CA is automatically trusted; [RFC 8461, 10.1](https://www.rfc-editor.org/rfc/rfc8461#section-10.1):\n\n        \u003e SMTP MTA-STS relies on certificate validation via PKIX-based TLS identity checking [RFC6125].  Attackers who are able to obtain a\n   valid certificate for the targeted recipient mail service (e.g., by compromising a CA) are thus able to circumvent STS authentication.\n      \n      * Based on DNSSEC, DANE not vulnerable to downgrade attack that could prevent policy discovery. MTA-STS security considerations acknowledges this weakness in [RFC 8461, 10.2](https://www.rfc-editor.org/rfc/rfc8461#section-10.2):\n\n        \u003e Since MTA-STS uses DNS TXT records for policy discovery, an attacker who is able to block DNS responses can suppress the discovery of an\n   MTA-STS Policy, making the Policy Domain appear not to have an MTA-STS Policy. \n\n        \u003e Resistance to downgrade attacks of this nature -- due to the ability to authoritatively determine \"lack of a record\" even for non-participating recipients -- is a feature of DANE, due to its use of DNSSEC for policy discovery.\n\n  * The postfix-mta-sts-resolver does not intent to implement policy lookups for DANE, and responses other than `secure` with `match=` would not verify the TLS certificate as required by [RFC 8461, 4,2](https://www.rfc-editor.org/rfc/rfc8461#section-4.2).\n\nIf you wish to meet this requirement:\n\n  * List a DANE policy resolver responding with `dane-only` (for [Mandatory DANE](https://www.postfix.org/TLS_README.html#client_tls_dane)) before postfix-mta-sts-resolver in `smtp_tls_policy_maps` lookup table list.\n  \n  * Alternatively, you could use a static lookup table for domains known to implement both MTA-STS \u0026 DANE, e.g.,\n\n    ```\n    smtp_tls_policy_maps = hash:/etc/postfix/tls_policy,socketmap:inet:127.0.0.1:8461:postfix\n    ```\n\n\n## Operability check\n\nAssuming default MTA-STA daemon configuration. Following command:\n\n```bash\n/usr/sbin/postmap -q dismail.de socketmap:inet:127.0.0.1:8461:postfix\n```\n\nshould return something like:\n\n```\nsecure match=mx1.dismail.de\n```\n\nPostfix log should show `Verified TLS connection established to ...` instead of `Untrusted ...` or `Trusted TLS connection established to ...` when mail is getting sent to MTA-STS-enabled domain.\n\n\n## Special cases of deployment\n\n\n### Systems without Python 3.5+\n\nSome people may find convenient to install latest python from source into `/opt` directory. This way you can have separate python installation not interfering with system packages by any means. Download latest python source from [python.org](https://www.python.org/), unpack and run in unpacked source directory:\n\n```bash\n./configure --prefix=/opt --enable-optimizations \u0026\u0026 make -j $[ $(nproc) + 1 ] \u0026\u0026 make test \u0026\u0026 sudo make install\n```\n\nPython binaries will be available in `/opt/bin`, including `pip3`. You may install `postfix-mta-sts-resolver` using `/opt/bin/pip3` without interference with any system packages:\n\n```bash\nsudo /opt/bin/pip3 install postfix-mta-sts-resolver[sqlite,redis]\n```\n\nExecutable files of `postfix-mta-sts-resolver` will be available in `/opt/bin/mta-sts-query` and `/opt/bin/mta-sts-daemon`\n\n\n### Building virtualenv\n\nRun `make` in project directory in order to build virtualenv. As result of it, new directory `venv` shall appear. `venv` contains interpreter and all required dependencies, i.e. encloses package with dependencies in separate environment. It is possible to specify alternative path where virtualenv directory shall be placed. Specify VENV variable for `make` command. Example:\n\n```bash\nmake VENV=~/postfix-mta-sts-resolver\n```\n\nSuch virtual environment can be moved to another machine of similar type (as far python interpreter is compatible with new environment). If virtualenv is placed into same location on new machine, application can be run this way:\n\n```bash\nvenv/bin/mta-sts-daemon\n```\n\nOtherwise, some hacks required. First option - explicitly call virtualenv interpreter:\n\n```bash\nvenv/bin/python venv/bin/mta-sts-daemon\n```\n\nSecond option - specify new path in shebang of scripts installed in virtualenv. It is recommended to build virtualenv at same location which app shall occupy on target system.\n\n\n## Credits\n\nInspired by [a postfix-user mailing list thread](https://marc.info/?l=postfix-users\u0026m=151889071727364\u0026w=2) (subject: 'MTA-STS when?', first message: 2018-02-17).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnawoot%2Fpostfix-mta-sts-resolver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsnawoot%2Fpostfix-mta-sts-resolver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnawoot%2Fpostfix-mta-sts-resolver/lists"}