mta_sts 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0de9b2cdb6adccb9fb59489860cebd39ea5ccd9b31bafad218d05334bbbd79c5
-  data.tar.gz: 4d4390e9071edf2f2ca6a1decbd32a8a862f24572d042464241cc11abb226594
+  metadata.gz: 9b46a83fc4dd32476a29b8c197095b65617a18a5936e90b6121767376154ee2d
+  data.tar.gz: e20185095d16cccb6f717760f82e49e6a01963268ff34312bcf21e4d48316d99
 SHA512:
-  metadata.gz: 836678183d43c161fdff348dc1b6c466a485f071bfc2e6606b805631c89ddd6848dbe8f1e511219f6861a7e40df83c3197c1cacf70cca0f89062f9e4aa4cd12a
-  data.tar.gz: aeeadc31d4ccf52cbd5b54267050ea1fcb01b891e49a9295f7dbd19beff6ea64f064e6299ae3d11208c68c2ea30552b0e6be1eec05bb1b639fe7e9d49b938c6d
+  metadata.gz: 4d61ee904a79ac3e44dbb052f033cef8288b9417be6fc9fda21991c1591ef3f426284333ca6d44fed8226256c54f32e426890075bd89ead162af514c664583a6
+  data.tar.gz: e4912ee834c01be36fdae2fbada466899192dc3c42e97898c928d4a1c69a006de38bc311fce178c18a049061371c660be8938164c957c903c82cd6ba6c066e9e

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.0
+
+- The fetcher resolves the policy host and judges the address before dialling it
+
+## 0.1.1
+
+Documentation
+
 ## 0.1.0
 
 Initial release.

data/README.md

@@ -1,10 +1,30 @@
 # mta_sts
 
-🔒 SMTP MTA Strict Transport Security for Ruby
-
-Answers one question before a message goes out: **must this connection be encrypted, and to which servers?**
-
-Resolve a recipient domain's MTA-STS policy (RFC 8461) and find out which of its mail servers may be used and whether TLS is optional. Also discovers where the domain wants TLS failure reports sent (RFC 8460 TLSRPT) — discovery only; generating and submitting reports is yours.
+🔒 SMTP MTA Strict Transport Security for Ruby.
+
+Answers one question before delivering a message: must this connection be encrypted, and to which servers?
+
+**mta_sts** resolves a recipient domain's MTA-STS policy (RFC 8461) and finds out which of its mail servers may be used and whether TLS is optional. It also discovers where the domain wants TLS failure reports sent (RFC 8460 TLSRPT).
+
+## Contents
+
+- [Installation](#installation)
+- [How It Works](#how-it-works)
+  - [Looking Up a Policy](#looking-up-a-policy)
+  - [Results](#results)
+  - [Status and Policy Are Separate Axes](#status-and-policy-are-separate-axes)
+  - [Holding On to a Policy](#holding-on-to-a-policy)
+  - [TLSRPT Record Discovery](#tlsrpt-record-discovery)
+  - [Custom Resolver & Fetcher](#custom-resolver--fetcher)
+  - [Publishing a Policy](#publishing-a-policy)
+- [Command Line](#command-line)
+- [What It Is Strict About](#what-it-is-strict-about)
+- [What It Is Not That Strict](#what-it-is-not-that-strict)
+- [What It Does Not Check](#what-it-does-not-check)
+- [Testing](#testing)
+- [History](#history)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Installation
 
@@ -91,7 +111,6 @@ Four statuses, each with a predicate:
 
 `policy` is present whenever there's one to honor: fresh, renewed, or the `known` one you passed in that hasn't expired.
 
-
 | what happened                             | status      | policy  | `enforce?` |
 | ----------------------------------------- | ----------- | ------- | ---------- |
 | fresh fetch, `mode: enforce`              | `found`     | present | true       |
@@ -99,7 +118,6 @@ Four statuses, each with a predicate:
 | TXT record gone, held an enforcing policy | `none`      | held    | **true**   |
 | never had one, no TXT record              | `none`      | nil     | false      |
 
-
 The third row looks wrong and isn't. §5.1 keeps a policy in force for its `max_age` regardless of what DNS says now - deleting the TXT record does not withdraw enforcement, only serving `mode: none` does.
 
 Use `enforce?` and `allows?` for the connection decision, not `status`:
@@ -161,9 +179,21 @@ MtaSts.lookup("example.com", known: nil,
   fetcher:  MyPolicyFetcher.new)    # the HTTPS GET
 ```
 
-- **resolver** - needs one method, `txt`, over `dnsruby` by default. Covers discovery only (`_mta-sts` and `_smtp._tls`). Raise `NotFound` for no such record, `Timeout` or `ServerFailure` for no answer. The policy host itself is resolved by the HTTP stack inside the fetcher.
+- **resolver** - needs one method, `txt`, over `dnsruby` by default. Covers discovery only (`_mta-sts` and `_smtp._tls`). Raise `NotFound` for no such record, `Timeout` or `ServerFailure` for no answer.
 - **fetcher** - one `GET`, over stdlib `Net::HTTP` by default, certificate verification on. Body size and a total wall-clock budget are capped so a hostile host cannot hold the thread forever.
 
+The fetcher resolves the policy host itself, so that the address it dials is one it has judged:
+
+```ruby
+MtaSts::Fetcher.new(
+  resolver:  MyResolver.new,                       # needs `addresses` as well as `txt`
+  permitted: ->(address) { my_own_opinion(address) })
+```
+
+- **permitted** - asked about each resolved address; the first one admitted is dialled. Defaults to `MtaSts::Fetcher.public_address?`, which admits public unicast and refuses private, loopback, link-local, and other special-use addresses, including ones wrapped or reached through NAT64. A deployment serving policies from inside its own network passes something more permissive.
+
+The recipient domain names the policy host, so where it resolves is chosen by whoever is being sent mail — without this, that's a request to an address of a stranger's choosing.
+
 ### Publishing a Policy
 
 ```ruby
@@ -219,7 +249,7 @@ Exit codes answer the MTA-STS question only. TLSRPT is printed for diagnostics a
 ## What It Is Strict About
 
 - HTTP 3xx are never followed
-- HTTP caching (RFC 7234) is never used - freshness comes from the TXT `id` and `max_age` only
+- HTTP caching (RFC 7234) is never used. Freshness comes from the TXT `id` and `max_age` only
 - Only `200` is a policy
 - The certificate is verified against `mta-sts.<domain>`, the policy host name
 - The `_mta-sts` discovery record must match the ABNF (`v=STSv1;` case-sensitive, a single well-formed `id`)
@@ -227,16 +257,21 @@ Exit codes answer the MTA-STS question only. TLSRPT is printed for diagnostics a
 
 ## What It Is Not That Strict
 
-- `Content-Type: text/plain` is checked but not enforced - §3.2 says SHOULD, not MUST, and real policies in the wild omit it
+- `Content-Type: text/plain` is checked but not enforced
 - Line terminators may be bare `LF` as well as `CRLF`
 
 ## What It Does Not Check
 
-- **Certificate revocation.** `Net::HTTP` doesn't check it, and this library doesn't wire up OCSP or CRL. Pass your own `fetcher` if you need it.
-- **The address the policy host resolves to.** Fetched at whatever address DNS returns. The certificate check is what protects you here.
-- **DANE.** A separate mechanism needing DNSSEC validation and the peer certificate mid-handshake, which this library never sees.
-- **TLSRPT report generation or submission.** This library finds the `rua`; building and sending aggregate reports is the application's job.
-- **Anything about the SMTP connection.** This library opens one socket, to fetch a policy over HTTPS. It never speaks SMTP.
+- **Certificate revocation.**  
+`Net::HTTP` doesn't check it, and this library doesn't wire up OCSP or CRL. Pass your own `fetcher` if you need it.
+- **The address the policy host resolves to.**  
+Fetched at whatever address DNS returns. The certificate check is what protects you here.
+- **DANE.**  
+A separate mechanism needing DNSSEC validation and the peer certificate mid-handshake, which this library never sees.
+- **TLSRPT report generation or submission.**  
+This library finds the `rua`; building and sending aggregate reports is the application's job.
+- **Anything about the SMTP connection.**  
+This library opens one socket, to fetch a policy over HTTPS. It never speaks SMTP.
 
 ## Testing
 
@@ -245,30 +280,19 @@ bundle install
 rake
 ```
 
-Nothing leaves the machine. Every lookup takes a `resolver:` and a `fetcher:`, and the test doubles stand a hash in for DNS and a string in for the policy host.
-
 ## History
 
-View the [changelog](https://github.com/mailpiece/mta_sts/blob/main/CHANGELOG.md)
+View the [changelog](CHANGELOG.md).
 
 ## Contributing
 
-Everyone is encouraged to help improve this project. Here are a few ways you can help:
+Everyone is encouraged to help improve this project:
 
 - [Report bugs](https://github.com/mailpiece/mta_sts/issues)
-- Fix bugs and [submit pull requests](https://github.com/mailpiece/mta_sts/pulls)
+- Fix bugs and submit pull requests
 - Write, clarify, or fix documentation
 - Suggest or add new features
 
-To get started with development:
-
-```sh
-git clone https://github.com/mailpiece/mta_sts.git
-cd mta_sts
-bundle install
-bundle exec rakecl
-```
-
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE).

data/lib/mta_sts/fetcher.rb

@@ -1,6 +1,8 @@
+require "ipaddr"
 require "net/http"
 require "openssl"
 require "zlib"
+require "mta_sts/resolver"
 require "mta_sts/version"
 
 module MtaSts
@@ -9,6 +11,8 @@ module MtaSts
     class Error < StandardError; end
     class HttpError < Error; end
     class CertificateError < Error; end
+    # A temperror like any other failed fetch, so a policy already held stands.
+    class BlockedAddress < Error; end
     class Timeout < Error; end
 
     WELL_KNOWN_PATH = "/.well-known/mta-sts.txt"
@@ -34,12 +38,75 @@ module MtaSts
       end
     end
 
+    # Special-use IPv4 no policy is published in. RFC 1918, loopback and
+    # link-local are left to the IPAddr predicates.
+    RESERVED_V4 = %w[
+      0.0.0.0/8 100.64.0.0/10 192.0.0.0/24 192.0.2.0/24 192.88.99.0/24
+      198.18.0.0/15 198.51.100.0/24 203.0.113.0/24 224.0.0.0/4 240.0.0.0/4
+    ].map { |range| IPAddr.new(range) }.freeze
+
+    RESERVED_V6 = %w[
+      ::/128 64:ff9b:1::/48 100::/64 2001::/32 2001:2::/48 2001:db8::/32
+      2002::/16 fec0::/10 ff00::/8
+    ].map { |range| IPAddr.new(range) }.freeze
+
+    # RFC 6052 §2.2 with a /96 prefix
+    NAT64 = IPAddr.new("64:ff9b::/96")
+
+    class << self
+      # The policy host is named by the domain being delivered to, so where it
+      # resolves is a stranger's to choose.
+      def public_address?(address)
+        ip = address.is_a?(IPAddr) ? address : IPAddr.new(address.to_s)
+
+        case
+        # No resolver legitimately answers with an address wrapped in another,
+        # whatever it wraps.
+        when ip.ipv4_mapped? || ipv4_compat?(ip) then false
+        when ip.ipv4?                           then public_v4?(ip)
+        when NAT64.include?(ip)                 then public_v4?(embedded_v4(ip))
+        else                                         public_v6?(ip)
+        end
+      rescue IPAddr::Error
+        false
+      end
+
+      private
+        def public_v4?(ip)
+          !(ip.private? || ip.loopback? || ip.link_local? || covered_by?(RESERVED_V4, ip))
+        end
+
+        def public_v6?(ip)
+          !(ip.private? || ip.loopback? || ip.link_local? || covered_by?(RESERVED_V6, ip))
+        end
+
+        def embedded_v4(ip)
+          IPAddr.new(ip.to_i & 0xffffffff, Socket::AF_INET)
+        end
+
+        def covered_by?(ranges, ip)
+          ranges.any? { |range| range.include?(ip) }
+        end
+
+        # IPAddr#ipv4_compat? is obsolete; reimplemented since the check itself
+        # (the deprecated ::a.b.c.d form) is still one we need to catch.
+        def ipv4_compat?(ip)
+          return false unless ip.ipv6?
+
+          low = ip.to_i & 0xffffffff
+          (ip.to_i >> 32).zero? && low != 0 && low != 1
+        end
+    end
+
     def initialize(open_timeout: OPEN_TIMEOUT, read_timeout: READ_TIMEOUT,
-                   total_timeout: TOTAL_TIMEOUT, max_body_bytes: MAX_BODY_BYTES)
+                   total_timeout: TOTAL_TIMEOUT, max_body_bytes: MAX_BODY_BYTES,
+                   resolver: Resolver.new, permitted: Fetcher.method(:public_address?))
       @open_timeout = open_timeout
       @read_timeout = read_timeout
       @total_timeout = total_timeout
       @max_body_bytes = max_body_bytes
+      @resolver = resolver
+      @permitted = permitted
     end
 
     def fetch(host)
@@ -53,8 +120,9 @@ module MtaSts
 
       def get(host)
         deadline = monotonic_now + @total_timeout
+        address = permitted_address(host)
 
-        with_response(host) do |response|
+        with_response(host, address) do |response|
           if response.is_a?(Net::HTTPOK)
             body_from(response, host, deadline)
           else
@@ -64,10 +132,26 @@ module MtaSts
         end
       end
 
-      def with_response(host)
+      # Resolved once here and carried into the connection: resolving again to
+      # dial would leave the second answer free to differ from the one judged.
+      def permitted_address(host)
+        resolve(host).find { |address| @permitted.call(address) } or
+          raise BlockedAddress, "#{host} resolves to no address a policy may be published at"
+      end
+
+      def resolve(host)
+        addresses = @resolver.addresses(host)
+        raise Error, "couldn't resolve #{host}" if addresses.empty?
+
+        addresses
+      rescue Resolver::Error => error
+        raise Error, "couldn't resolve #{host}: #{error.message}"
+      end
+
+      def with_response(host, address)
         result = nil
 
-        connection(host).start do |http|
+        connection(host, address).start do |http|
           http.request(policy_request) { |response| result = yield response }
         end
 
@@ -82,8 +166,11 @@ module MtaSts
         raise Error, "couldn't reach #{host}: #{error.message}"
       end
 
-      def connection(host)
+      def connection(host, address)
         Net::HTTP.new(host, PORT).tap do |http|
+          # Dial the address already judged; the name stays behind for SNI, the
+          # Host header, and the certificate the whole fetch rests on.
+          http.ipaddr = address
           http.use_ssl = true
           http.verify_mode = OpenSSL::SSL::VERIFY_PEER
           http.verify_hostname = true

data/lib/mta_sts/resolver.rb

@@ -14,25 +14,37 @@ module MtaSts
     end
 
     def txt(name)
-      records(name).map { |record| record.strings.join }
+      records(name, "TXT").map { |record| record.strings.join }
+    end
+
+    def addresses(name)
+      %w[ A AAAA ].flat_map { |type| family(name, type) }
     end
 
     private
-      def records(name)
-        answer = resolver.query(name.to_s, "TXT").answer.grep(Dnsruby::RR::IN::TXT)
+      def family(name, type)
+        records(name, type).map { |record| record.address.to_s.downcase }
+      rescue NotFound
+        []
+      end
+
+      # Filter by type: a CNAME answer carries the alias beside the records it
+      # leads to.
+      def records(name, type)
+        answer = resolver.query(name.to_s, type).answer.select { |record| record.type == type }
 
         if answer.any?
           answer
         else
-          raise NotFound, "no TXT records for #{name}"
+          raise NotFound, "no #{type} records for #{name}"
         end
       rescue Dnsruby::NXDomain
         raise NotFound, "no such name #{name}"
       rescue Dnsruby::ResolvTimeout
-        raise Timeout, "timed out resolving TXT #{name}"
+        raise Timeout, "timed out resolving #{type} #{name}"
       # Fall through to ServerFailure, never NotFound — "couldn't ask" must not become "no policy"
       rescue Dnsruby::ResolvError, IOError, SocketError, SystemCallError => error
-        raise ServerFailure, "couldn't resolve TXT #{name}: #{reason(error)}"
+        raise ServerFailure, "couldn't resolve #{type} #{name}: #{reason(error)}"
       end
 
       def reason(error)

data/lib/mta_sts/version.rb

@@ -1,3 +1,3 @@
 module MtaSts
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/mta_sts.gemspec

@@ -6,11 +6,10 @@ Gem::Specification.new do |spec|
   spec.version = MtaSts::VERSION
   spec.platform = Gem::Platform::RUBY
   spec.required_ruby_version = ">= 3.3.4"
-  spec.authors = [ "PostRider" ]
-  spec.email = [ "support@postrider.dev" ]
+  spec.authors = [ "Simon Lev" ]
 
-  spec.summary = "MTA-STS policy discovery and enforcement for outbound SMTP in Ruby."
-  spec.description = "Answers one question before delivering a message: must this connection be encrypted, and to which servers?"
+  spec.summary = "SMTP MTA Strict Transport Security for Ruby."
+  spec.description = "Answers one question before delivering a message: must this connection be encrypted, and to which servers? Implements MTA-STS policy discovery and TLSRPT record discovery."
 
   spec.homepage = "https://github.com/mailpiece/mta_sts"
   spec.license = "MIT"

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: mta_sts
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
-- PostRider
+- Simon Lev
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
@@ -38,9 +38,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.2'
 description: 'Answers one question before delivering a message: must this connection
-  be encrypted, and to which servers?'
-email:
-- support@postrider.dev
+  be encrypted, and to which servers? Implements MTA-STS policy discovery and TLSRPT
+  record discovery.'
 executables:
 - mta-sts
 extensions: []
@@ -84,5 +83,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: MTA-STS policy discovery and enforcement for outbound SMTP in Ruby.
+summary: SMTP MTA Strict Transport Security for Ruby.
 test_files: []