mailauth 0.3.0

data/lib/mailauth/dkim.rb

@@ -0,0 +1,270 @@
+require "openssl"
+
+require "mailauth/dmarc/alignment"
+require "mailauth/dkim/canonicalization"
+require "mailauth/dkim/algorithm"
+require "mailauth/dkim/public_key"
+require "mailauth/dkim/signer"
+
+module MailAuth
+  # RFC 6376. Verifies the DKIM-Signature headers on a message against the
+  # public keys their domains publish, and signs outgoing messages with the
+  # private ones.
+  module Dkim
+    CRLF = "\r\n".b
+
+    # Always maps to permerror: retrying changes nothing when a tag is missing,
+    # the algorithm is unsupported, or the key is unreadable.
+    class Malformed < StandardError; end
+
+    HASHES = { "sha1" => OpenSSL::Digest::SHA1, "sha256" => OpenSSL::Digest::SHA256 }.freeze
+    SIGNING_ALGORITHMS = %w[ rsa ed25519 ].freeze
+
+    # What OpenSSL calls a key, mapped to what a= calls it.
+    KEY_TYPES = { "rsaEncryption" => "rsa", "ED25519" => "ed25519" }.freeze
+
+    CANONICALIZATIONS = %w[ simple relaxed ].freeze
+    REQUIRED_TAGS = %w[ v a b bh d h s ].freeze
+
+    # RFC 6376 §3.2: ALPHA *ALNUMPUNC.
+    TAG_NAME = /\A[a-zA-Z][a-zA-Z0-9_]*\z/n
+
+    # Shorter RSA keys are factorable cheaply enough to prove nothing.
+    MINIMUM_RSA_BITS = 1024
+
+    # ed25519 keys travel as 32 raw bytes (RFC 8463 §3), so we put back the
+    # SubjectPublicKeyInfo wrapper OpenSSL insists on before reading one.
+    ED25519_SPKI_PREFIX = [ "302a300506032b6570032100" ].pack("H*")
+
+    def self.verify(message, resolver: Resolver.new, now: Time.now)
+      signatures = message.fields_named("dkim-signature").map do |field|
+        Verification.new(message, field, resolver:, now:).result
+      end
+      signatures << Signature.new(status: Status::NONE, comment: "message not signed") if signatures.empty?
+
+      DkimResult.new(signatures:)
+    end
+
+    def self.sign(raw, domain:, selector:, key:, headers: nil, oversign: Signer::OVERSIGNED_HEADERS, expires_in: nil, now: Time.now)
+      Signer.new(raw, domain:, selector:, key:, headers:, oversign:, expires_in:, now:).signed_message
+    end
+
+    # RFC 6376 §3.2. A malformed tag name, a repeated one, or an empty entry
+    # invalidates the whole list rather than the one tag: reading the rest
+    # would take a forged tag as read beside the one silently dropped. Values
+    # fold across lines, so callers strip whitespace themselves on the tags
+    # where it matters.
+    def self.parse_tags(text)
+      specs = text.split(";", -1)
+      specs.pop if specs.last&.strip&.empty?   # the tag-list's optional trailing ";"
+
+      specs.each_with_object({}) do |spec, tags|
+        name, value = spec.split("=", 2)
+        name = name.to_s.strip
+
+        return nil unless value && name.match?(TAG_NAME) && !tags.key?(name)
+
+        tags[name] = value.strip
+      end
+    end
+
+    # One DKIM-Signature header, taken from its tags to a verdict.
+    class Verification
+      def initialize(message, field, resolver:, now:)
+        @message, @field, @resolver, @now = message, field, resolver, now
+        tags = Dkim.parse_tags(field.split(":", 2).last.to_s)
+        @well_formed = !tags.nil?
+        @tags = tags || {}
+      end
+
+      def result
+        validate
+
+        if expired?
+          failed("signature expired")
+        elsif postdated?
+          failed("signature timestamp in the future")
+        elsif body_hash_matches?
+          verified? ? signature(Status::PASS) : failed("bad signature")
+        else
+          # Some verifiers call this neutral. We call it failure: the signer
+          # said what the body would hash to, and it hashes to something else.
+          failed("body hash did not verify")
+        end
+      rescue Malformed => error
+        signature(Status::PERMERROR, comment: error.message)
+      rescue Resolver::NotFound
+        signature(Status::PERMERROR, comment: "no key for #{key_name}")
+      rescue Resolver::Timeout, Resolver::ServerFailure
+        signature(Status::TEMPERROR, comment: "DNS failure resolving #{key_name}")
+      end
+
+      private
+        def validate
+          raise Malformed, "invalid tag list" unless @well_formed
+          raise Malformed, "unsupported signature version" unless @tags["v"] == "1"
+
+          if missing = REQUIRED_TAGS.find { |tag| @tags[tag].to_s.empty? }
+            raise Malformed, "missing #{missing}= tag"
+          end
+
+          unless SIGNING_ALGORITHMS.include?(signing_algorithm) && HASHES.key?(hash_algorithm)
+            raise Malformed, "unsupported algorithm #{@tags["a"]}"
+          end
+
+          unless CANONICALIZATIONS.include?(header_canonicalization) && CANONICALIZATIONS.include?(body_canonicalization)
+            raise Malformed, "unsupported canonicalization #{canonicalization}"
+          end
+
+          # A signature that leaves From unsigned says nothing about who the
+          # message claims to be from, which is the only question here.
+          raise Malformed, "From is not signed" unless signed_header_names.include?("from")
+
+          raise Malformed, "invalid l= tag" if @tags["l"] && !@tags["l"].match?(/\A\d+\z/n)
+        end
+
+        def expired?
+          expires_at && expires_at < @now
+        end
+
+        def expires_at
+          Time.at(@tags["x"].to_i) if @tags["x"]&.match?(/\A\d+\z/n)
+        end
+
+        def postdated?
+          signed_at && signed_at > @now
+        end
+
+        def signed_at
+          Time.at(@tags["t"].to_i) if @tags["t"]&.match?(/\A\d+\z/n)
+        end
+
+        def body_hash_matches?
+          digest.digest(signed_body) == unfolded("bh").unpack1("m")
+        end
+
+        # l= counts canonicalized bytes, not the bytes that arrived — the tag
+        # signs a prefix of the canonical body, not of the message on the wire.
+        def signed_body
+          if body_limit
+            canonical_body.byteslice(0, body_limit)
+          else
+            canonical_body
+          end
+        end
+
+        def body_limit
+          @tags["l"].to_i if @tags["l"]&.match?(/\A\d+\z/n)
+        end
+
+        def canonical_body
+          @canonical_body ||= Canonicalization.body(@message.body, body_canonicalization)
+        end
+
+        def verified?
+          Algorithm.verified?(canonical_headers, key: public_key, digest: digest,
+            signature: unfolded("b").unpack1("m"))
+        end
+
+        def public_key
+          PublicKey.retrieve(selector: @tags["s"], domain: @tags["d"],
+            algorithm: signing_algorithm, resolver: @resolver)
+        end
+
+        def key_name
+          PublicKey.name_for(selector: @tags["s"], domain: @tags["d"])
+        end
+
+        # No trailing CRLF after the signature field: the bytes after b= are
+        # what the signature covers.
+        def canonical_headers
+          signed_fields.map { |field| canonicalize_field(field) + CRLF }.join + canonical_signature_field
+        end
+
+        # Takes the last unused instance of each named header, walking upward
+        # through duplicates. Naming a header that isn't present (oversigning)
+        # contributes nothing but forbids one being added later.
+        def signed_fields
+          remaining = @message.fields.dup
+
+          signed_header_names.filter_map do |name|
+            if index = remaining.rindex { |field| @message.field_name(field) == name }
+              remaining.delete_at(index)
+            end
+          end
+        end
+
+        def signed_header_names
+          unfolded("h").to_s.downcase.split(":").reject(&:empty?)
+        end
+
+        def canonical_signature_field
+          canonicalize_field(@field).sub(/([;:\s]+b=)[^;]*/n, '\1')
+        end
+
+        def canonicalize_field(field)
+          Canonicalization.field(field, header_canonicalization)
+        end
+
+        def digest
+          HASHES.fetch(hash_algorithm)
+        end
+
+        def signing_algorithm
+          @tags["a"].to_s.split("-").first.to_s.downcase
+        end
+
+        def hash_algorithm
+          @tags["a"].to_s.split("-").last.to_s.downcase
+        end
+
+        def header_canonicalization
+          canonicalization.split("/").first
+        end
+
+        def body_canonicalization
+          canonicalization.split("/")[1] || "simple"
+        end
+
+        def canonicalization
+          @tags["c"].to_s.downcase.strip.empty? ? "simple/simple" : @tags["c"].downcase.strip
+        end
+
+        # Tags whose value is base64 or a colon-separated list carry folding
+        # whitespace that was never part of the value.
+        def unfolded(tag)
+          @tags[tag]&.gsub(/[ \t\r\n]+/n, "")
+        end
+
+        def failed(comment)
+          signature(Status::FAIL, comment:)
+        end
+
+        def signature(status, comment: nil)
+          Signature.new(status:, domain: @tags["d"]&.downcase, selector: @tags["s"], algorithm: @tags["a"],
+            canonicalization: canonicalization, comment:, aligned: aligned?, under_sized: under_sized)
+        end
+
+        # Relaxed DMARC alignment: the From: domain and the signing domain need
+        # only share an organizational domain, not match exactly.
+        def aligned?
+          from, signing_domain = @message.header_from_domain, @tags["d"]&.downcase
+
+          if from && signing_domain
+            Dmarc::Alignment.aligned?(from, signing_domain, strict: false)
+          else
+            false
+          end
+        end
+
+        # In canonicalized bytes — the tail a signature says nothing about,
+        # and where content gets smuggled.
+        def under_sized
+          if body_limit && CANONICALIZATIONS.include?(body_canonicalization)
+            uncovered = canonical_body.bytesize - body_limit
+            uncovered if uncovered.positive?
+          end
+        end
+    end
+  end
+end

data/lib/mailauth/dmarc/alignment.rb

@@ -0,0 +1,32 @@
+require "mailauth/domain"
+require "mailauth/dmarc/organizational_domain"
+
+module MailAuth
+  # RFC 7489 §3.1. Does a domain that SPF or DKIM authenticated stand for the
+  # same organization as the From: domain a reader sees?
+  module Dmarc
+    module Alignment
+      class << self
+        # Strict and relaxed are separate rules, not a fallback pair — falling
+        # back to relaxed after a strict miss would make `adkim=s`/`aspf=s`
+        # decorative.
+        def aligned?(from, candidate, strict:)
+          from, candidate = normalize(from), normalize(candidate)
+
+          if from.empty? || candidate.empty?
+            false
+          elsif strict
+            from == candidate
+          else
+            OrganizationalDomain.of(from) == OrganizationalDomain.of(candidate)
+          end
+        end
+
+        private
+          def normalize(domain)
+            Domain.normalize(domain)
+          end
+      end
+    end
+  end
+end

data/lib/mailauth/dmarc/organizational_domain.rb

@@ -0,0 +1,22 @@
+require "public_suffix"
+
+require "mailauth/domain"
+
+module MailAuth
+  module Dmarc
+    # The registrable domain — "bar.co.uk" for "foo.bar.co.uk", never "co.uk".
+    # Only the Public Suffix List can answer this; counting labels would put
+    # bank.co.uk and attacker.co.uk in the same organization.
+    module OrganizationalDomain
+      def self.of(name)
+        domain = Domain.normalize(name)
+
+        # Private suffixes are boundaries too: two tenants of one host
+        # (user1.blogspot.com, user2.blogspot.com) are separate organizations.
+        PublicSuffix.domain(domain, ignore_private: false) || domain
+      rescue PublicSuffix::Error
+        domain # under no known suffix, a name can only align with itself
+      end
+    end
+  end
+end

data/lib/mailauth/dmarc/record.rb

@@ -0,0 +1,120 @@
+require "mailauth/dmarc/organizational_domain"
+
+module MailAuth
+  module Dmarc
+    # The policy a domain publishes at _dmarc.<domain>, plus the one thing the
+    # text itself doesn't say: whether we had to walk up to the organizational
+    # domain to find it, which is what decides between `p` and `sp`.
+    class Record
+      DMARC1 = /\Av=DMARC1\b/i
+      TAGS = %w[ v p sp adkim aspf pct rua ruf fo rf ri ].freeze
+      POLICIES = %w[ none quarantine reject ].freeze
+      STRICT = "s".freeze
+      DEFAULT_PCT = 100
+
+      class << self
+        # DNS failures are raised rather than swallowed: "we couldn't ask" is
+        # a different answer from "there is nothing there".
+        def find(domain, resolver:)
+          at(domain, resolver: resolver) || at_organizational_domain(domain, resolver: resolver)
+        end
+
+        private
+          def at(domain, resolver:, organizational: false)
+            texts = resolver.txt("_dmarc.#{domain}").map(&:strip).grep(DMARC1)
+
+            # Two policies are as good as none: RFC 7489 §6.6.3 would rather
+            # apply nothing than guess which one the domain meant.
+            if texts.one? && (record = new(texts.first, organizational: organizational)).usable?
+              record
+            end
+          rescue Resolver::NotFound
+            nil
+          end
+
+          # A subdomain with no record of its own — or one too broken to apply —
+          # falls back to its parent, which is how a single record at the
+          # organizational domain covers a whole tree of hostnames.
+          def at_organizational_domain(domain, resolver:)
+            organizational = OrganizationalDomain.of(domain)
+
+            at(organizational, resolver: resolver, organizational: true) unless organizational == domain
+          end
+      end
+
+      attr_reader :tags
+
+      def initialize(text, organizational: false)
+        @text, @organizational = text, organizational
+        @tags = parse(text)
+      end
+
+      # `p` is the one required tag beyond the version; without it the record
+      # may as well not exist.
+      def usable?
+        !requested_policy.nil?
+      end
+
+      # RFC 7489 §6.6.3: mail from a subdomain answers to the parent's `sp`,
+      # deliberately not the parent's own `p` — an organization can reject
+      # forgeries of unused hostnames while still easing its own mail through
+      # under p=none.
+      def policy
+        if organizational? && subdomain_policy
+          subdomain_policy
+        else
+          requested_policy
+        end
+      end
+
+      # Surfaced, never applied: rolling the `pct` dice here would make the
+      # same message pass and fail at random, which an authentication result
+      # must never do.
+      def pct
+        Integer(tags["pct"], exception: false)&.clamp(0, 100) || DEFAULT_PCT
+      end
+
+      # Both alignment tags default to relaxed, so only an explicit "s" is strict.
+      def strict_dkim?
+        tags["adkim"]&.downcase == STRICT
+      end
+
+      def strict_spf?
+        tags["aspf"]&.downcase == STRICT
+      end
+
+      def organizational?
+        @organizational
+      end
+
+      def to_s
+        @text
+      end
+
+      private
+        # Unknown tags are dropped rather than treated as an error, so a
+        # record using a tag from a later extension still governs the mail it
+        # was published for.
+        def parse(text)
+          text.to_s.split(";").filter_map { |tag|
+            name, value = tag.split("=", 2)
+            name = name.to_s.strip.downcase
+
+            [ name, value.strip ] if value && TAGS.include?(name)
+          }.to_h
+        end
+
+        def requested_policy
+          validated(tags["p"])
+        end
+
+        def subdomain_policy
+          validated(tags["sp"])
+        end
+
+        def validated(policy)
+          policy&.downcase&.then { |value| value if POLICIES.include?(value) }
+        end
+    end
+  end
+end

data/lib/mailauth/dmarc.rb

@@ -0,0 +1,64 @@
+require "mailauth/dmarc/alignment"
+require "mailauth/dmarc/record"
+
+module MailAuth
+  # RFC 7489. Do the SPF or DKIM results line up with the From: domain a reader
+  # sees, and what does that domain ask us to do when they don't?
+  module Dmarc
+    class << self
+      # Takes the already-computed SPF and DKIM results — alignment is a
+      # comparison, not a check of its own. None or several From: domains is
+      # `permerror`, not `none`: the message is malformed, not simply
+      # unpolicied.
+      def check(header_from:, spf:, dkim:, resolver: Resolver.new)
+        if domain = sole_domain(header_from)
+          evaluate(domain, spf: spf, dkim: dkim, resolver: resolver)
+        else
+          DmarcResult.new(status: Status::PERMERROR)
+        end
+      end
+
+      private
+        def sole_domain(header_from)
+          domains = Array(header_from).map { |domain| domain.to_s.strip.downcase.chomp(".") }.reject(&:empty?)
+
+          domains.first if domains.one?
+        end
+
+        def evaluate(domain, spf:, dkim:, resolver:)
+          if record = Record.find(domain, resolver: resolver)
+            verdict(domain, record, spf: spf, dkim: dkim)
+          else
+            DmarcResult.new(status: Status::NONE)
+          end
+        rescue Resolver::Timeout, Resolver::ServerFailure
+          # Calling this `none` would hand a spoofer a free pass every time a
+          # nameserver hiccups.
+          DmarcResult.new(status: Status::TEMPERROR)
+        end
+
+        def verdict(domain, record, spf:, dkim:)
+          alignment = { dkim: dkim_aligned?(domain, dkim, record), spf: spf_aligned?(domain, spf, record) }
+
+          DmarcResult.new \
+            status: alignment.values.any? ? Status::PASS : Status::FAIL,
+            policy: record.policy,
+            pct: record.pct,
+            alignment: alignment,
+            record: record.to_s
+        end
+
+        # .any? because a forwarder's own valid signature can sit happily
+        # beside the author's — one aligned pass is enough.
+        def dkim_aligned?(domain, dkim, record)
+          Array(dkim&.passing_domains).any? do |signing_domain|
+            Alignment.aligned?(domain, signing_domain, strict: record.strict_dkim?)
+          end
+        end
+
+        def spf_aligned?(domain, spf, record)
+          spf&.status == Status::PASS && Alignment.aligned?(domain, spf.domain, strict: record.strict_spf?)
+        end
+    end
+  end
+end

data/lib/mailauth/domain.rb

@@ -0,0 +1,34 @@
+require "simpleidn"
+
+module MailAuth
+  # One spelling for a domain name, so two of them can be compared. An
+  # internationalized domain travels both as the U-label a person reads
+  # (münchen.example) and the A-label DNS and DKIM's d= carry
+  # (xn--mnchen-3ya.example); comparing those byte-wise fails DMARC alignment
+  # on perfectly good mail.
+  module Domain
+    class << self
+      def normalize(name)
+        name = printable(name).strip.chomp(".")
+
+        ascii(name).downcase
+      end
+
+      private
+        # These names come from headers and DNS records, so they can hold any
+        # bytes at all — and invalid UTF-8 raises on the first thing done to it.
+        def printable(name)
+          name = name.to_s
+          name.valid_encoding? ? name : name.scrub("")
+        end
+
+        def ascii(name)
+          name.ascii_only? ? name : SimpleIDN.to_ascii(name)
+        rescue StandardError
+          # A name punycode can't encode can't be looked up either, so let it
+          # fail to match rather than raising here.
+          name
+        end
+    end
+  end
+end

data/lib/mailauth/message.rb

@@ -0,0 +1,76 @@
+module MailAuth
+  # A received message, split once into the parts every check needs. Binary
+  # throughout: DKIM hashes bytes, so transcoding changes the answer.
+  class Message
+    HEADER_SEPARATOR = "\r\n\r\n".b
+
+    attr_reader :raw, :headers, :body
+
+    def initialize(raw)
+      @raw = normalize(raw)
+      @headers, @body = @raw.split(HEADER_SEPARATOR, 2)
+      @headers = @headers.to_s
+      @body = @body.to_s
+    end
+
+    # Order is load-bearing: DKIM walks duplicate headers from the bottom up.
+    def fields
+      @fields ||= headers.lines.each_with_object([]) do |line, fields|
+        if fields.any? && line.start_with?(" ", "\t")
+          fields.last << line
+        else
+          fields << line
+        end
+      end
+    end
+
+    def fields_named(name)
+      fields.select { |field| field_name(field) == name.downcase }
+    end
+
+    def field_name(field)
+      field.split(":", 2).first.to_s.strip.downcase
+    end
+
+    # What DMARC alignment is measured against. Quoted display names are
+    # stripped first: `From: "Foo <evil@attacker.example>" <real@bank.example>`
+    # renders as bank.example, and taking the first address found would align
+    # against the attacker's domain instead. Several From addresses (RFC 5322
+    # permits it; DMARC doesn't) is no domain rather than a guess.
+    def header_from_domain
+      addresses = from_addresses
+
+      if addresses.one?
+        addresses.first.downcase.chomp(".")
+      end
+    end
+
+    private
+      # Bare LF becomes CRLF so a message that took a lossy path still
+      # canonicalizes as its signer intended; a lone CR is left alone.
+      def normalize(raw)
+        raw.to_s.b.gsub(/\r?\n/n, "\r\n")
+      end
+
+      # RFC 5322 §3.6 permits exactly one From field, and a second one is how a
+      # message says two different things at once: DKIM signs the last From
+      # (§5.4.2) while a reader is shown the first, so a signature over an
+      # attacker's own domain would align against a name nobody sees. Anything
+      # but one field carrying one address is no domain at all.
+      def from_addresses
+        fields = fields_named("from")
+
+        if fields.one?
+          unquoted(fields.first.split(":", 2).last.to_s).scan(/@([^\s>,;()]+)/).flatten
+        else
+          []
+        end
+      end
+
+      # Quoted strings and comments can hold anything, including something that
+      # reads as an address; neither is one.
+      def unquoted(value)
+        value.gsub(/"(?:\\.|[^"\\])*"/n, " ").gsub(/\((?:\\.|[^()\\])*\)/n, " ")
+      end
+  end
+end