bridgedb/distributors/email/dkim.py

   1 # -*- coding: utf-8 ; test-case-name: bridgedb.test.test_email_dkim -*-
   2 #_____________________________________________________________________________
   3 #
   4 # This file is part of BridgeDB, a Tor bridge distribution system.
   5 #
   6 # :authors: Nick Mathewson <nickm@torproject.org>
   7 #           Isis Lovecruft <isis@torproject.org> 0xA3ADB67A2CDB8B35
   8 #           Matthew Finkel <sysrqb@torproject.org>
   9 #           please also see AUTHORS file
  10 # :copyright: (c) 2007-2017, The Tor Project, Inc.
  11 #             (c) 2013-2017, Isis Lovecruft
  12 # :license: see LICENSE for licensing information
  13 #_____________________________________________________________________________
  14
  15 """
  16 .. py:module:: bridgedb.distributors.email.dkim
  17     :synopsis: Functions for checking DKIM verification results in email
  18                headers.
  19
  20 bridgedb.distributors.email.dkim
  21 ===================
  22
  23 Functions for checking DKIM verification results in email headers.
  24
  25 ::
  26
  27  bridgedb.distributors.email.dkim
  28   |_ checkDKIM - Check the DKIM verification results header.
  29
  30 ..
  31 """
  32
  33 from __future__ import unicode_literals
  34
  35 import logging
  36
  37
  38 def checkDKIM(message, rules):
  39     """Check the DKIM verification results header.
  40
  41     This check is only run if the incoming email, **message**, originated from
  42     a domain for which we're configured (in the ``EMAIL_DOMAIN_RULES``
  43     dictionary in the config file) to check DKIM verification results for.
  44
  45     Returns ``False`` if:
  46
  47     1. We're supposed to expect and check the DKIM headers for the
  48        client's email provider domain.
  49     2. Those headers were *not* okay.
  50
  51     Otherwise, returns ``True``.
  52
  53     :type message: :api:`twisted.mail.smtp.rfc822.Message`
  54     :param message: The incoming client request email, including headers.
  55     :param dict rules: The list of configured ``EMAIL_DOMAIN_RULES`` for the
  56         canonical domain which the client's email request originated from.
  57     :rtype: bool
  58     :returns: ``False`` if the checks failed, ``True`` otherwise.
  59     """
  60     logging.info("Checking DKIM verification results...")
  61     logging.debug("Domain has rules: %s" % ', '.join(rules))
  62
  63     if 'dkim' in rules:
  64         # getheader() returns the last of a given kind of header; we want
  65         # to get the first, so we use getheaders() instead.
  66         dkimHeaders = message.get("X-DKIM-Authentication-Results")
  67         dkimHeader = dkimHeaders if dkimHeaders else "<no header>"
  68         if not dkimHeader.startswith("pass"):
  69             logging.info("Rejecting bad DKIM header on incoming email: %r "
  70                          % dkimHeader)
  71             return False
  72     return True