mailauth 0.3.0

data/lib/mailauth/arc/set.rb

@@ -0,0 +1,74 @@
+module MailAuth
+  module Arc
+    # The three header fields sharing one instance value (RFC 8617 §4.2). Each
+    # is held as the list of fields claiming this instance, so a set that
+    # carries two of anything can say so rather than quietly keeping one.
+    class Set
+      attr_reader :instance
+
+      def initialize(instance)
+        @instance = instance
+        @fields = { authentication_results: [], message_signature: [], seal: [] }
+      end
+
+      def add(kind, field)
+        @fields.fetch(kind) << field
+      end
+
+      def complete?
+        @fields.each_value.all?(&:one?)
+      end
+
+      # A tag list that doesn't parse leaves nothing to verify against, and no
+      # reading of the rest can rescue it (RFC 6376 §3.2).
+      def readable?
+        !seal_tags.nil? && !message_signature_tags.nil?
+      end
+
+      def authentication_results
+        @fields[:authentication_results].first
+      end
+
+      def message_signature
+        @fields[:message_signature].first
+      end
+
+      def seal
+        @fields[:seal].first
+      end
+
+      # The status this hop stamped, which §5.2 step 3.3 holds to "none" at
+      # instance 1 and "pass" above it.
+      def chain_status
+        seal_tags.to_h["cv"].to_s.downcase
+      end
+
+      def seal_tags
+        return @seal_tags if defined?(@seal_tags)
+
+        @seal_tags = Arc.tags_in(seal)
+      end
+
+      def message_signature_tags
+        return @message_signature_tags if defined?(@message_signature_tags)
+
+        @message_signature_tags = Arc.tags_in(message_signature)
+      end
+
+      # The payload an Authentication-Results header would carry, with the
+      # instance tag that prefixes it here (§4.1.1) taken off.
+      def authentication_results_payload
+        Arc.value_of(authentication_results).to_s.sub(INSTANCE_PREFIX, "").strip
+      end
+
+      # Best effort, and never load-bearing: the chain's validity is a question
+      # about signatures, so an unreadable assertion must not fail it. A name
+      # carrying a dot is one of RFC 8601's properties (`smtp.mailfrom`), not a
+      # method, and says nothing about a verdict.
+      def claimed
+        authentication_results_payload.scan(/(?<![\w.-])([a-z][a-z0-9-]*)[ \t]*=[ \t]*([a-z]+)/i).
+          each_with_object({}) { |(method, result), claims| claims[method.downcase] ||= result.downcase }
+      end
+    end
+  end
+end

data/lib/mailauth/arc.rb

@@ -0,0 +1,143 @@
+require "mailauth/dkim"
+require "mailauth/arc/chain"
+require "mailauth/arc/message_signature"
+require "mailauth/arc/seal"
+
+module MailAuth
+  # RFC 8617. An Authenticated Received Chain records what each intermediary
+  # concluded about a message as it passed through, sealed so a later reader can
+  # tell the record has not been touched since. Forwarding routinely breaks SPF
+  # and DKIM; a chain says what they said before it did.
+  #
+  # What a valid chain proves is only that each hop sealed what it sealed.
+  # Sealing a chain over one's own message costs nothing, so whether any sealer
+  # is to be believed is a decision for the caller and has no answer here.
+  module Arc
+    CRLF = "\r\n".b
+
+    # §4.2.1. The ceiling is enforced before any key is fetched: each set
+    # otherwise costs a lookup, and a long chain is cheap to write.
+    MAXIMUM_SETS = 50
+
+    CHAIN_STATUSES = %w[ none fail pass ].freeze
+    CANONICALIZATIONS = Dkim::CANONICALIZATIONS
+
+    HASHES = %w[ sha256 ].freeze
+    SIGNING_ALGORITHMS = Dkim::SIGNING_ALGORITHMS
+
+    # §4.1.1 puts the instance ahead of the payload an AAR carries, where the
+    # other two hold it among their tags.
+    INSTANCE_PREFIX = /\A[ \t\r\n]*i[ \t\r\n]*=[ \t\r\n]*(\d+)[ \t\r\n]*;/n
+
+    # `now` is taken for symmetry with the other checks and not consulted: ARC
+    # gives a chain no lifetime, and a message can sit in a queue for days
+    # without that saying anything about the hops it already crossed.
+    def self.verify(message, resolver: Resolver.new, now: Time.now)
+      Validation.new(message, resolver: resolver).result
+    end
+
+    def self.value_of(field)
+      field&.split(":", 2)&.last
+    end
+
+    def self.tags_in(field)
+      Dkim.parse_tags(value_of(field).to_s)
+    end
+
+    # sha1 is still legal for a DKIM signature and never was for ARC.
+    def self.signing_algorithm?(algorithm)
+      SIGNING_ALGORITHMS.include?(signing_algorithm(algorithm)) && HASHES.include?(hash_algorithm(algorithm))
+    end
+
+    def self.signing_algorithm(algorithm)
+      algorithm.to_s.split("-").first.to_s.downcase
+    end
+
+    def self.hash_algorithm(algorithm)
+      algorithm.to_s.split("-").last.to_s.downcase
+    end
+
+    # The validator of §5.2, in its order. Every failure is permanent, DNS
+    # included (§5.2.1), so a chain is only ever pass, fail, or none — the
+    # reason a hop failed survives on that set rather than in the status.
+    class Validation
+      def initialize(message, resolver:)
+        @message, @resolver = message, resolver
+        @chain = Chain.new(message)
+        @seals = {}
+        @signatures = {}
+      end
+
+      def result
+        if @chain.empty?
+          result_of Status::NONE, comment: "no ARC sets"
+        elsif @chain.oversized?
+          result_of Status::FAIL, comment: "more than #{MAXIMUM_SETS} ARC sets"
+        elsif sealed_as_failed?
+          result_of Status::FAIL, comment: "sealed cv=fail at i=#{@chain.newest.instance}"
+        elsif error = @chain.structural_error
+          result_of Status::FAIL, comment: error
+        elsif !newest_signature_verifies?
+          result_of Status::FAIL, comment: "ARC-Message-Signature i=#{@chain.newest.instance} did not verify"
+        elsif broken = broken_seal
+          result_of Status::FAIL, comment: "ARC-Seal i=#{broken.instance} did not verify"
+        else
+          result_of Status::PASS
+        end
+      end
+
+      private
+        # Step 2, ahead of the structural checks: a chain the newest hop has
+        # already declared broken is broken whatever else it looks like.
+        def sealed_as_failed?
+          @chain.newest&.complete? && @chain.newest.chain_status == "fail"
+        end
+
+        # Step 4. Only the newest, and deliberately: an intermediary that
+        # rewrites a subject line invalidates the hop before it, which is the
+        # very situation ARC exists to carry a message through.
+        def newest_signature_verifies?
+          signature_for(@chain.newest).status == Status::PASS
+        end
+
+        def signature_for(set)
+          @signatures[set.instance] ||=
+            MessageSignature.new(@message, set.message_signature, set.message_signature_tags, resolver: @resolver).result
+        end
+
+        # Step 6, newest first, each seal over the chain as it stood when that
+        # hop sealed it.
+        def broken_seal
+          @chain.ordered.reverse.find { |set| seal_for(set).status != Status::PASS }
+        end
+
+        def seal_for(set)
+          @seals[set.instance] ||= Seal.new(@chain.through(set.instance), resolver: @resolver).result
+        end
+
+        def result_of(status, comment: nil)
+          ArcResult.new(status: status, sets: reported_sets, comment: comment,
+            oldest_pass: (oldest_pass if status == Status::PASS))
+        end
+
+        # A chain that never got as far as verifying anything still reports the
+        # hops it found, so a reader can see who sealed what.
+        def reported_sets
+          @chain.ordered.map do |set|
+            ArcSet.new(instance: set.instance, chain_status: set.chain_status,
+              seal: @seals[set.instance], message_signature: @signatures[set.instance],
+              authentication_results: set.authentication_results_payload, claimed: set.claimed)
+          end
+        end
+
+        # Step 5, optional: the oldest hop whose signature still verifies, which
+        # says how far back the message is unmodified without bearing on whether
+        # the chain is valid.
+        def oldest_pass
+          broken = @chain.ordered[0..-2].reverse.find { |set| signature_for(set).status != Status::PASS }
+
+          broken ? broken.instance + 1 : 0
+        end
+    end
+  end
+end

data/lib/mailauth/authentication_results.rb

@@ -0,0 +1,164 @@
+module MailAuth
+  # RFC 8601. States the verdicts in an Authentication-Results header for a
+  # downstream MTA to read.
+  class AuthenticationResults
+    LINE_WIDTH = 78                                       # RFC 5322 §2.1.1
+    INDENT = " ".freeze
+    FOLD = "\r\n#{INDENT}".freeze
+
+    # RFC 8601 §2.2 requires an authserv-id. Without one we say so out loud
+    # rather than emitting a header that appears to be signed by nobody.
+    UNKNOWN_AUTHSERV_ID = "unknown".freeze
+    NO_RESULTS = "none".freeze
+
+    # A pvalue may be an RFC 2045 token or a bare addr-spec, so "@" and "." ride
+    # along unquoted; everything else has to become a quoted-string.
+    TOKEN = /\A[!#-'*+\-.0-9@-Z^-~]+\z/
+
+    # `header_from` is optional: a DmarcResult carries a verdict, not an
+    # identity; pass the From: domain to have it reported as `header.from`.
+    def initialize(spf:, dkim:, dmarc:, arc: nil, mta: nil, header_from: nil)
+      @spf, @dkim, @dmarc, @arc, @mta, @header_from = spf, dkim, dmarc, arc, mta, header_from
+    end
+
+    # The value alone — everything after "Authentication-Results:" — so the
+    # caller writes the field name itself.
+    def to_s
+      fold segments
+    end
+
+    private
+      def segments
+        clauses = [ [ authserv_id ], *method_clauses ]
+
+        clauses.each_with_index.map do |tokens, index|
+          index == clauses.length - 1 ? tokens : terminated(tokens)
+        end
+      end
+
+      def authserv_id
+        escape(@mta.to_s.strip.empty? ? UNKNOWN_AUTHSERV_ID : @mta)
+      end
+
+      def method_clauses
+        clauses = [ spf_clause, *dkim_clauses, dmarc_clause, arc_clause ].compact
+
+        # A header with nothing to report still has to report that.
+        clauses.any? ? clauses : [ [ NO_RESULTS ] ]
+      end
+
+      def spf_clause
+        if @spf
+          [ "spf=#{@spf.status}", comment(@spf.comment), property("smtp.mailfrom", @spf.domain) ].compact
+        end
+      end
+
+      # Three signatures make three dkim= results: collapsing them would lose
+      # which domain the passing one belonged to.
+      def dkim_clauses
+        @dkim&.signatures&.map do |signature|
+          [ "dkim=#{signature.status}",
+            comment(signature.comment),
+            comment(undersized(signature)),
+            property("header.d", signature.domain),
+            property("header.s", signature.selector),
+            property("header.a", signature.algorithm) ].compact
+        end
+      end
+
+      # Tells the header's reader when l= left part of the body unsigned.
+      def undersized(signature)
+        "undersized signature: #{signature.under_sized} bytes unsigned" if signature.under_sized
+      end
+
+      def dmarc_clause
+        if @dmarc
+          [ "dmarc=#{@dmarc.status}", comment(policy_comment), property("header.from", @header_from) ].compact
+        end
+      end
+
+      # The result says whether the message aligned; the comment says what
+      # the domain asked us to do about it.
+      def policy_comment
+        "p=#{@dmarc.policy.upcase}" if @dmarc.policy
+      end
+
+      # RFC 8617 §5.2 registers pass, fail, and none and nothing else, so the
+      # sealer rides along as a comment rather than as a property, and a chain
+      # that passed never touches the dmarc= clause above it.
+      def arc_clause
+        if @arc
+          [ "arc=#{@arc.status}", comment(newest_sealer) ].compact
+        end
+      end
+
+      def newest_sealer
+        if @arc.newest&.seal&.domain
+          "i=#{@arc.newest.instance} d=#{@arc.newest.seal.domain}"
+        end
+      end
+
+      def property(name, value)
+        value = sanitize(value)
+
+        if value.empty?
+          nil
+        else
+          "#{name}=#{escape(value)}"
+        end
+      end
+
+      def comment(text)
+        text = sanitize(text)
+
+        if text.empty?
+          nil
+        else
+          "(#{escape_comment(text)})"
+        end
+      end
+
+      def escape(value)
+        value = sanitize(value)
+
+        if value.match?(TOKEN)
+          value
+        else
+          %("#{value.gsub(/["\\]/) { |char| "\\#{char}" }}")
+        end
+      end
+
+      # Parentheses have to balance and a backslash quotes whatever follows it,
+      # so both — and the "(" that would open a comment we never meant to start —
+      # are escaped.
+      def escape_comment(text)
+        text.gsub(/[()\\]/) { |char| "\\#{char}" }
+      end
+
+      # Everything here can come from a remote party — a surviving CR or LF
+      # would let them forge headers of their own.
+      def sanitize(value)
+        value.to_s.gsub(/[\x00-\x1f\x7f]+/, " ").squeeze(" ").strip
+      end
+
+      def terminated(tokens)
+        tokens[..-2] + [ "#{tokens.last};" ]
+      end
+
+      # Folds at token boundaries only: a quoted string or comment can carry a
+      # space, and breaking one across lines would change what it says.
+      def fold(segments)
+        segments.flat_map { |tokens| lines(tokens) }.join(FOLD)
+      end
+
+      def lines(tokens)
+        tokens.each_with_object([]) do |token, lines|
+          if lines.any? && lines.last.length + INDENT.length + token.length < LINE_WIDTH
+            lines.last << " " << token
+          else
+            lines << token.dup
+          end
+        end
+      end
+  end
+end

data/lib/mailauth/dkim/algorithm.rb

@@ -0,0 +1,28 @@
+require "openssl"
+
+module MailAuth
+  module Dkim
+    # Both directions of the same maths, in one place: RFC 8463 §3 has EdDSA
+    # sign the hash of the canonicalized headers where RSA signs the headers
+    # themselves, and a signer and a verifier that disagree about that produce
+    # signatures nobody can check.
+    module Algorithm
+      def self.sign(data, key:, digest: OpenSSL::Digest::SHA256)
+        case KEY_TYPES.fetch(key.oid)
+        when "rsa"     then key.sign(digest.new, data)
+        when "ed25519" then key.sign(nil, digest.digest(data))
+        end
+      end
+
+      def self.verified?(data, key:, signature:, digest: OpenSSL::Digest::SHA256)
+        case KEY_TYPES.fetch(key.oid)
+        when "rsa"     then key.verify(digest.new, signature, data)
+        when "ed25519" then key.verify(nil, signature, digest.digest(data))
+        end
+      rescue OpenSSL::PKey::PKeyError
+        # A signature of the wrong length for the key never reaches the maths.
+        false
+      end
+    end
+  end
+end

data/lib/mailauth/dkim/canonicalization.rb

@@ -0,0 +1,40 @@
+module MailAuth
+  module Dkim
+    # RFC 6376 §3.4: the bytes a signature covers. One implementation, so
+    # signing and verifying can't reduce a message differently.
+    module Canonicalization
+      class << self
+        def body(bytes, form)
+          case form
+          when "relaxed" then relaxed_body(bytes)
+          when "simple"  then simple_body(bytes)
+          end
+        end
+
+        def field(field, form)
+          case form
+          when "relaxed" then relaxed_field(field)
+          when "simple"  then field.chomp(CRLF)
+          end
+        end
+
+        private
+          # An unterminated final line is still a line (§3.4.4 a.1): its trailing
+          # whitespace goes too, and the CRLF it lacks is put back.
+          def relaxed_body(bytes)
+            body = bytes.gsub(/[ \t]+/n, " ").gsub(/ (?=\r\n|\z)/n, "").sub(/(?:\r\n)*\z/n, "")
+            body.empty? ? body : body + CRLF
+          end
+
+          def simple_body(bytes)
+            bytes.sub(/(?:\r\n)*\z/n, CRLF)
+          end
+
+          def relaxed_field(field)
+            name, value = field.split(":", 2)
+            "#{name.strip.downcase}:#{value.to_s.gsub(/\r\n/n, "").gsub(/[ \t]+/n, " ").strip}"
+          end
+      end
+    end
+  end
+end

data/lib/mailauth/dkim/public_key.rb

@@ -0,0 +1,54 @@
+require "openssl"
+
+module MailAuth
+  module Dkim
+    # The key a signing domain publishes, per RFC 6376 §3.6.1. ARC keys live in
+    # the same records under the same names, so both protocols read them here.
+    module PublicKey
+      class << self
+        def retrieve(selector:, domain:, algorithm:, resolver:)
+          read record_for(name_for(selector: selector, domain: domain), resolver), algorithm
+        end
+
+        def name_for(selector:, domain:)
+          "#{selector}._domainkey.#{domain}"
+        end
+
+        private
+          def record_for(name, resolver)
+            tags = Dkim.parse_tags(resolver.txt(name).first.to_s)
+
+            if tags.nil?
+              raise Malformed, "invalid key record for #{name}"
+            elsif tags["v"] && tags["v"].downcase != "dkim1"
+              raise Malformed, "unknown key version #{tags["v"]}"
+            elsif tags["p"].to_s.empty?
+              raise Malformed, "key revoked"
+            else
+              tags["p"].gsub(/[ \t\r\n]+/n, "").unpack1("m")
+            end
+          end
+
+          def read(material, algorithm)
+            key = OpenSSL::PKey.read(wrapped(material))
+
+            if KEY_TYPES[key.oid] != algorithm
+              raise Malformed, "key is not #{algorithm}"
+            elsif algorithm == "rsa" && key.n.num_bits < MINIMUM_RSA_BITS
+              raise Malformed, "rsa key shorter than #{MINIMUM_RSA_BITS} bits"
+            else
+              key
+            end
+          rescue OpenSSL::PKey::PKeyError
+            raise Malformed, "unreadable public key"
+          end
+
+          # ed25519 keys travel as 32 raw bytes (RFC 8463 §3), so we put back
+          # the SubjectPublicKeyInfo wrapper OpenSSL insists on before reading.
+          def wrapped(material)
+            material.bytesize == 32 ? ED25519_SPKI_PREFIX + material : material
+          end
+      end
+    end
+  end
+end

data/lib/mailauth/dkim/signer.rb

@@ -0,0 +1,122 @@
+require "openssl"
+
+require "mailauth/message"
+require "mailauth/domain"
+
+module MailAuth
+  module Dkim
+    # Signs a message per RFC 6376 §5, relaxed/relaxed.
+    class Signer
+      # The RFC 6376 §5.4.1 example set: what a reader's client renders or threads on.
+      DEFAULT_SIGNED_HEADERS = %w[
+        from sender reply-to subject date message-id to cc
+        mime-version content-type content-transfer-encoding
+        in-reply-to references list-id list-help list-owner
+        list-unsubscribe list-unsubscribe-post list-subscribe list-post
+      ].freeze
+
+      # Named in h= once more than they occur — a name past its count matches
+      # nothing (§5.4.2), so an instance added after signing breaks the signature.
+      OVERSIGNED_HEADERS = %w[ from to cc subject date reply-to message-id ].freeze
+
+      def initialize(raw, domain:, selector:, key:, headers: nil, oversign: OVERSIGNED_HEADERS, expires_in: nil, now: Time.now)
+        @message = Message.new(raw)
+        @domain = Domain.normalize(domain)
+        @selector = Domain.normalize(selector)
+        @key = key
+        @requested = (headers || DEFAULT_SIGNED_HEADERS).map(&:downcase)
+        @oversign = oversign.map(&:downcase)
+        @expires_in = expires_in
+        @now = now
+      end
+
+      def signed_message
+        field + @message.raw
+      end
+
+      def field
+        @field ||= begin
+          validate
+          unsigned_field + [ signature ].pack("m0").scan(/.{1,72}/).join("\r\n\t") + CRLF
+        end
+      end
+
+      private
+        def validate
+          raise ArgumentError, "unsupported key type #{@key.oid}" unless KEY_TYPES.key?(@key.oid)
+          raise ArgumentError, "rsa key shorter than #{MINIMUM_RSA_BITS} bits" if undersized_rsa?
+          raise ArgumentError, "From is not signed" unless signed_names.include?("from")
+        end
+
+        # Held to the same floor the verifier enforces, so no signature leaves
+        # here that the other side is required to reject.
+        def undersized_rsa?
+          KEY_TYPES.fetch(@key.oid) == "rsa" && @key.n.num_bits < MINIMUM_RSA_BITS
+        end
+
+        # Ends with b=, where the signature lands — in the signed bytes and the
+        # emitted field alike.
+        def unsigned_field
+          "DKIM-Signature: v=1; " + properties.join("\r\n\t")
+        end
+
+        def properties
+          [
+            "a=#{algorithm}; c=relaxed/relaxed;",
+            "d=#{@domain};",
+            "s=#{@selector}; t=#{@now.to_i};",
+            expiration,
+            "bh=#{body_hash};",
+            "h=#{signed_names.join(":")};",
+            "b="
+          ].compact
+        end
+
+        def algorithm
+          "#{KEY_TYPES.fetch(@key.oid)}-sha256"
+        end
+
+        def expiration
+          "x=#{@now.to_i + @expires_in.to_i};" if @expires_in
+        end
+
+        def body_hash
+          [ OpenSSL::Digest::SHA256.digest(Canonicalization.body(@message.body, "relaxed")) ].pack("m0")
+        end
+
+        def signed_names
+          @signed_names ||= present_names + @oversign
+        end
+
+        def present_names
+          @message.fields.map { |field| @message.field_name(field) }.select { |name| @requested.include?(name) }
+        end
+
+        def signature
+          sign(signable)
+        end
+
+        # The emitted field itself is canonicalized and signed, unterminated —
+        # no room to sign one thing and send another.
+        def signable
+          signed_fields.map { |field| Canonicalization.field(field, "relaxed") + CRLF }.join +
+            Canonicalization.field(unsigned_field, "relaxed")
+        end
+
+        # Duplicates are taken bottom-up, the order a verifier takes them (§5.4.2).
+        def signed_fields
+          remaining = @message.fields.dup
+
+          signed_names.filter_map do |name|
+            if index = remaining.rindex { |field| @message.field_name(field) == name }
+              remaining.delete_at(index)
+            end
+          end
+        end
+
+        def sign(data)
+          Algorithm.sign(data, key: @key)
+        end
+    end
+  end
+end