Merge async work into master for 1.0

ChangeLog

@@ -1,5 +1,7 @@
 Version 1.0.0
     - Add support for RFC 8460 tlsrpt DKIM signature processing (LP: #1847020)
+    - Add async support with aiodns for DKIM verification (ARC not supported)
+      (LP: #1847002)
     - Add new timeout parameter to enable DNS lookup timeouts to be adjusted
     - Add new DKIM.present function to allow applications to test if a DKIM
       signature is present without doing validation (LP: #1851141)

README

@@ -19,6 +19,8 @@ Dependencies will be automatically included for normal DKIM usage.  The
 extras_requires feature 'ed25519' will add the dependencies needed for signing
 and verifying using the new DCRUP ed25519-sha256 algorithm.  The
 extras_requires feature 'ARC' will add the extra dependencies needed for ARC.
+Similarly, extras_requires feature 'asyncio' will add the extra dependencies
+needed for asyncio.
 
  - Python 2.x >= 2.7, or Python 3.x >= 3.5.  Recent versions have not been
    tested on python < 2.7 or python3 < 3.5, but may still work on python2.6
@@ -28,6 +30,7 @@ extras_requires feature 'ARC' will add the extra dependencies needed for ARC.
  - argparse.  Standard library in python2.7 and later.
  - authres.  Needed for ARC.
  - PyNaCl.  Needed for use of ed25519 capability.
+ - aiodns.  Needed for asycnio (Required python3.5 or later)
 
 INSTALLATION
 

dkim/__init__.py

@@ -36,6 +36,7 @@ import base64
 import hashlib
 import logging
 import re
+import sys
 import time
 import binascii
 
@@ -71,8 +72,13 @@ from dkim.crypto import (
 try:
     from dkim.dnsplug import get_txt
 except ImportError:
-    def get_txt(s,timeout=5):
-        raise RuntimeError("DKIM.verify requires DNS or dnspython module")
+    try:
+        import aiodns
+        from dkim.asyncsupport import get_txt_async as get_txt
+    except:
+        # Only true if not using async
+        def get_txt(s,timeout=5):
+            raise RuntimeError("DKIM.verify requires DNS or dnspython module")
 from dkim.util import (
     get_default_logger,
     InvalidTagValueList,
@@ -420,8 +426,7 @@ def fold(header, namelen=0, linesep=b'\r\n'):
             return pre + header
 
 
-def load_pk_from_dns(name, dnsfunc=get_txt, timeout=5):
-  s = dnsfunc(name, timeout=timeout)
+def evaluate_pk(name, s):
   if not s:
       raise KeyFormatError("missing public key: %s"%name)
   try:
@@ -470,6 +475,12 @@ def load_pk_from_dns(name, dnsfunc=get_txt, timeout=5):
   return pk, keysize, ktag, seqtlsrpt
 
 
+def load_pk_from_dns(name, dnsfunc=get_txt, timeout=5):
+  s = dnsfunc(name, timeout=timeout)
+  pk, keysize, ktag, seqtlsrpt = evaluate_pk(name, s)
+  return pk, keysize, ktag, seqtlsrpt
+
+
 #: Abstract base class for holding messages and options during DKIM/ARC signing and verification.
 class DomainSigner(object):
   # NOTE - the first 2 indentation levels are 2 instead of 4
@@ -676,27 +687,12 @@ class DomainSigner(object):
 
     return header_value
 
-  # Abstract helper method to verify a signed header
-  #: @param sig: List of (key, value) tuples containing tag=values of the header
-  #: @param include_headers: headers to validate b= signature against
-  #: @param sig_header: (header_name, header_value)
-  #: @param dnsfunc: interface to dns
-  def verify_sig(self, sig, include_headers, sig_header, dnsfunc):
-    name = sig[b's'] + b"._domainkey." + sig[b'd'] + b"."
-    try:
-      pk, self.keysize, ktag, self.seqtlsrpt = load_pk_from_dns(name, dnsfunc,
-              timeout=self.timeout)
-    except KeyFormatError as e:
-      self.logger.error("%s" % e)
-      return False
-    except binascii.Error as e:
-      self.logger.error('KeyFormatError: {0}'.format(e))
-      return False
-
+  def verify_sig_process(self, sig, include_headers, sig_header, dnsfunc):
+    """Non-async sensitive verify_sig elements.  Separated to avoid async code
+    duplication."""
     # RFC 8460 MAY ignore signatures without tlsrpt Service Type
     if self.tlsrpt == 'strict' and not self.seqtlsrpt:
         raise ValidationError("Message is tlsrpt and Service Type is not tlsrpt")
-
     # Inferred requirement from both RFC 8460 and RFC 6376
     if not self.tlsrpt and self.seqtlsrpt:
         raise ValidationError("Message is not tlsrpt and Service Type is tlsrpt")
@@ -744,24 +740,43 @@ class DomainSigner(object):
     if self.debug_content:
         self.logger.debug("signed for %s: %r" % (sig_header[0], h.hashed()))
     signature = base64.b64decode(re.sub(br"\s+", b"", sig[b'b']))
-    if ktag == b'rsa':
+    if self.ktag == b'rsa':
         try:
-            res = RSASSA_PKCS1_v1_5_verify(h, signature, pk)
+            res = RSASSA_PKCS1_v1_5_verify(h, signature, self.pk)
             self.logger.debug("%s valid: %s" % (sig_header[0], res))
             if res and self.keysize < self.minkey:
                 raise KeyFormatError("public key too small: %d" % self.keysize)
             return res
         except (TypeError,DigestTooLargeError) as e:
             raise KeyFormatError("digest too large for modulus: %s"%e)
-    elif ktag == b'ed25519':
+    elif self.ktag == b'ed25519':
         try:
-            pk.verify(h.digest(), signature)
+            self.pk.verify(h.digest(), signature)
             self.logger.debug("%s valid" % (sig_header[0]))
             return True
         except (nacl.exceptions.BadSignatureError) as e:
             return False
     else:
-        raise UnknownKeyTypeError(ktag)
+        raise UnknownKeyTypeError(self.ktag)
+
+
+  # Abstract helper method to verify a signed header
+  #: @param sig: List of (key, value) tuples containing tag=values of the header
+  #: @param include_headers: headers to validate b= signature against
+  #: @param sig_header: (header_name, header_value)
+  #: @param dnsfunc: interface to dns
+  def verify_sig(self, sig, include_headers, sig_header, dnsfunc):
+    name = sig[b's'] + b"._domainkey." + sig[b'd'] + b"."
+    try:
+      self.pk, self.keysize, self.ktag, self.seqtlsrpt = load_pk_from_dns(name,
+              dnsfunc, timeout=self.timeout)
+    except KeyFormatError as e:
+      self.logger.error("%s" % e)
+      return False
+    except binascii.Error as e:
+      self.logger.error('KeyFormatError: {0}'.format(e))
+      return False
+    return self.verify_sig_process(sig, include_headers, sig_header, dnsfunc)
 
 
 #: Hold messages and options during DKIM signing and verification.
@@ -881,15 +896,9 @@ class DKIM(DomainSigner):
   def present(self):
     return (len([(x,y) for x,y in self.headers if x.lower() == b"dkim-signature"]) > 0)
 
-  #: Verify a DKIM signature.
-  #: @type idx: int
-  #: @param idx: which signature to verify.  The first (topmost) signature is 0.
-  #: @type dnsfunc: callable
-  #: @param dnsfunc: an option function to lookup TXT resource records
-  #: for a DNS domain.  The default uses dnspython or pydns.
-  #: @return: True if signature verifies or False otherwise
-  #: @raise DKIMException: when the message, signature, or key are badly formed
-  def verify(self,idx=0,dnsfunc=get_txt):
+  def verify_headerprep(self, idx=0):
+    """Non-DNS verify parts to minimize asyncio code duplication."""
+
     sigheaders = [(x,y) for x,y in self.headers if x.lower() == b"dkim-signature"]
     if len(sigheaders) <= idx:
         return False
@@ -909,7 +918,18 @@ class DKIM(DomainSigner):
 
     include_headers = [x.lower() for x in re.split(br"\s*:\s*", sig[b'h'])]
     self.include_headers = tuple(include_headers)
+    return sig, include_headers, sigheaders
 
+  #: Verify a DKIM signature.
+  #: @type idx: int
+  #: @param idx: which signature to verify.  The first (topmost) signature is 0.
+  #: @type dnsfunc: callable
+  #: @param dnsfunc: an option function to lookup TXT resource records
+  #: for a DNS domain.  The default uses dnspython or pydns.
+  #: @return: True if signature verifies or False otherwise
+  #: @raise DKIMException: when the message, signature, or key are badly formed
+  def verify(self,idx=0,dnsfunc=get_txt):
+    sig, include_headers, sigheaders = self.verify_headerprep(idx=0)
     return self.verify_sig(sig, include_headers, sigheaders[idx], dnsfunc)
 
 
@@ -1307,7 +1327,8 @@ def sign(message, selector, domain, privkey, identity=None,
     return d.sign(selector, domain, privkey, identity=identity, canonicalize=canonicalize, include_headers=include_headers, length=length)
 
 
-def verify(message, logger=None, dnsfunc=get_txt, minkey=1024, timeout=5, tlsrpt=False):
+def verify(message, logger=None, dnsfunc=get_txt, minkey=1024,
+        timeout=5, tlsrpt=False):
     """Verify the first (topmost) DKIM signature on an RFC822 formatted message.
     @param message: an RFC822 formatted message (with either \\n or \\r\\n line endings)
     @param logger: a logger to which debug info will be written (default None)
@@ -1326,6 +1347,18 @@ def verify(message, logger=None, dnsfunc=get_txt, minkey=1024, timeout=5, tlsrpt
             logger.error("%s" % x)
         return False
 
+
+# aiodns requires Python 3.5+, so no async before that
+if sys.version_info >= (3, 5):
+    try:
+        import aiodns
+        from dkim.asyncsupport import verify_async
+        dkim_verify_async = verify_async
+    except ImportError:
+        # If aiodns is not installed, then async verification is not available
+        pass
+
+
 # For consistency with ARC
 dkim_sign = sign
 dkim_verify = verify

dkim/asyncsupport.py

@@ -0,0 +1,123 @@
+# This software is provided 'as-is', without any express or implied
+# warranty.  In no event will the author be held liable for any damages
+# arising from the use of this software.
+#
+# Permission is granted to anyone to use this software for any purpose,
+# including commercial applications, and to alter it and redistribute it
+# freely, subject to the following restrictions:
+#
+# 1. The origin of this software must not be misrepresented; you must not
+#    claim that you wrote the original software. If you use this software
+#    in a product, an acknowledgment in the product documentation would be
+#    appreciated but is not required.
+# 2. Altered source versions must be plainly marked as such, and must not be
+#    misrepresented as being the original software.
+# 3. This notice may not be removed or altered from any source distribution.
+#
+# Copyright (c) 2008 Greg Hewgill http://hewgill.com
+#
+# This has been modified from the original software.
+# Copyright (c) 2011 William Grant <me@williamgrant.id.au>
+#
+# This has been modified from the original software.
+# Copyright (c) 2016 Google, Inc.
+# Contact: Brandon Long <blong@google.com>
+#
+# This has been modified from the original software.
+# Copyright (c) 2016, 2017, 2018, 2019 Scott Kitterman <scott@kitterman.com>
+#
+# This has been modified from the original software.
+# Copyright (c) 2017 Valimail Inc
+# Contact: Gene Shuman <gene@valimail.com>
+
+import asyncio
+import aiodns
+import base64
+import dkim
+import re
+
+__all__ = [
+    'get_txt_async',
+    'load_pk_from_dns_async',
+    'verify_async'
+    ]
+
+
+async def get_txt_async(name, timeout=5):
+    """Return a TXT record associated with a DNS name in an asnyc loop. For
+    DKIM we can assume there is only one."""
+
+    # Note: This will use the existing loop or create one if needed
+    loop = asyncio.get_event_loop()
+    resolver = aiodns.DNSResolver(loop=loop, timeout=timeout)
+
+    async def query(name, qtype):
+        return await resolver.query(name, qtype)
+
+    #q = query(name, 'TXT')
+    try:
+        result = await query(name, 'TXT')
+    except aiodns.error.DNSError:
+        result = None
+
+    if result:
+        return result[0].text
+    else:
+        return None
+
+
+async def load_pk_from_dns_async(name, dnsfunc, timeout=5):
+  s = await dnsfunc(name, timeout=timeout)
+  pk, keysize, ktag, seqtlsrpt = dkim.evaluate_pk(name, s)
+  return pk, keysize, ktag, seqtlsrpt
+
+class DKIM(dkim.DKIM):
+  #: Sign an RFC822 message and return the DKIM-Signature header line.
+  #:
+  #: Identical to dkim.DKIM, except uses aiodns and can be awaited in an
+  #: ascyncio context.  See dkim.DKIM for details.
+
+  # Abstract helper method to verify a signed header
+  #: @param sig: List of (key, value) tuples containing tag=values of the header
+  #: @param include_headers: headers to validate b= signature against
+  #: @param sig_header: (header_name, header_value)
+  #: @param dnsfunc: interface to dns
+  async def verify_sig(self, sig, include_headers, sig_header, dnsfunc):
+    name = sig[b's'] + b"._domainkey." + sig[b'd'] + b"."
+    try:
+      self.pk, self.keysize, self.ktag, self.seqtlsrpt = await load_pk_from_dns_async(name,
+              dnsfunc, timeout=self.timeout)
+    except dkim.KeyFormatError as e:
+      self.logger.error("%s" % e)
+      return False
+    return self.verify_sig_process(sig, include_headers, sig_header, dnsfunc)
+
+
+  async def verify(self,idx=0,dnsfunc=get_txt_async):
+    sig, include_headers, sigheaders = self.verify_headerprep(idx=0)
+    return await self.verify_sig(sig, include_headers, sigheaders[idx], dnsfunc)
+
+
+async def verify_async(message, logger=None, dnsfunc=None, minkey=1024,
+        timeout=5, tlsrpt=False):
+    """Verify the first (topmost) DKIM signature on an RFC822 formatted message in an asyncio contxt.
+    @param message: an RFC822 formatted message (with either \\n or \\r\\n line endings)
+    @param logger: a logger to which debug info will be written (default None)
+    @param timeout: number of seconds for DNS lookup timeout (default = 5)
+    @param tlsrpt: message is an RFC 8460 TLS report (default False)
+    False: Not a tlsrpt, True: Is a tlsrpt, 'strict': tlsrpt, invalid if
+    service type is missing. For signing, if True, length is never used.
+    @return: True if signature verifies or False otherwise
+    """
+    # type: (bytes, any, function, int) -> bool
+    # Note: This will use the existing loop or create one if needed
+    loop = asyncio.get_event_loop()
+    if not dnsfunc:
+        dnsfunc=get_txt_async
+    d = DKIM(message,logger=logger,minkey=minkey,timeout=timeout,tlsrpt=tlsrpt)
+    try:
+        return await d.verify(dnsfunc=dnsfunc)
+    except dkim.DKIMException as x:
+        if logger is not None:
+            logger.error("%s" % x)
+        return False

dkimverify_async.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python
+
+# This software is provided 'as-is', without any express or implied
+# warranty.  In no event will the author be held liable for any damages
+# arising from the use of this software.
+#
+# Permission is granted to anyone to use this software for any purpose,
+# including commercial applications, and to alter it and redistribute it
+# freely, subject to the following restrictions:
+#
+# 1. The origin of this software must not be misrepresented; you must not
+#    claim that you wrote the original software. If you use this software
+#    in a product, an acknowledgment in the product documentation would be
+#    appreciated but is not required.
+# 2. Altered source versions must be plainly marked as such, and must not be
+#    misrepresented as being the original software.
+# 3. This notice may not be removed or altered from any source distribution.
+#
+# Copyright (c) 2008 Greg Hewgill http://hewgill.com
+#
+# This has been modified from the original software.
+# Copyright (c) 2011 William Grant <me@williamgrant.id.au>
+
+from __future__ import print_function
+
+import sys
+import asyncio
+import dkim
+
+
+if sys.version_info[0] >= 3:
+    # Make sys.stdin a binary stream.
+    sys.stdin = sys.stdin.detach()
+
+message = sys.stdin.read()
+
+async def main():
+    res = await dkim.verify_async(message)
+    return res
+
+
+if __name__ == "__main__":
+    res = asyncio.run(main())
+    if not res:
+        print("signature verification failed")
+        sys.exit(1)
+    print("signature ok")
+

setup.py

@@ -86,7 +86,8 @@ verification.""",
             'pynacl',
         ],
         'ed25519':  ['pynacl'],
-        'ARC': ['authres']
+        'ARC': ['authres'],
+        'asyncio': ['aiodns']
     },
     **kw
 )