1Metadata-Version: 2.1 2Name: dkimpy 3Version: 1.0.5 4Summary: DKIM (DomainKeys Identified Mail), ARC (Authenticated Receive Chain), and TLSRPT (TLS Report) email signing and verification 5Home-page: https://launchpad.net/dkimpy 6Author: Scott Kitterman 7Author-email: scott@kitterman.com 8License: BSD-like 9Description: dkimpy - DKIM (DomainKeys Identified Mail) 10 https://launchpad.net/dkimpy/ 11 12 Friendly fork of: 13 http://hewgill.com/pydkim/ 14 15 # INTRODUCTION 16 17 dkimpy is a library that implements DKIM (DomainKeys Identified Mail) email 18 signing and verification. Basic DKIM requirements are defined in RFC 6376: 19 20 https://tools.ietf.org/html/rfc6376 21 22 # VERSION 23 24 This is dkimpy 1.0.5. 25 26 # REQUIREMENTS 27 28 Dependencies will be automatically included for normal DKIM usage. The 29 extras_requires feature 'ed25519' will add the dependencies needed for signing 30 and verifying using the new DCRUP ed25519-sha256 algorithm. The 31 extras_requires feature 'ARC' will add the extra dependencies needed for ARC. 32 Similarly, extras_requires feature 'asyncio' will add the extra dependencies 33 needed for asyncio. 34 35 - Python 2.x >= 2.7, or Python 3.x >= 3.5. Recent versions have not been 36 tested on python < 2.7 or python3 < 3.4, but may still work on python2.6 37 and python 3.1 - 3.3. 38 - dnspython or pydns. dnspython is preferred if both are present and 39 installed to satisfy the DNS module requirement if neither are installed. 40 - argparse. Standard library in python2.7 and later. 41 - authres. Needed for ARC. 42 - PyNaCl. Needed for use of ed25519 capability. 43 - aiodns. Needed for asycnio (Requires python3.5 or later) 44 45 # INSTALLATION 46 47 This package includes a scripts and man pages. For those to be installed when 48 installing using setup.py, the following incantation is required because 49 setuptools developers decided not being able to do this by default is a 50 feature: 51 52 ```python3 setup.py install --single-version-externally-managed --record=/dev/null``` 53 54 # DOCUMENTATION 55 56 An online version of the package documentation for the most recent release can 57 be found at: 58 59 https://pymilter.org/pydkim/ 60 61 # TESTING 62 63 To run dkimpy's test suite: 64 65 ```PYTHONPATH=. python3 dkim``` 66 67 or 68 69 ```python3 test.py``` 70 71 or 72 73 ```PYTHONPATH=. python3 -m unittest dkim.tests.test_suite``` 74 75 76 Alternatively, if you have testrepository installed: 77 78 ```testr init``` 79 80 ```testr run``` 81 82 You should install all optional dependencies required for the test suite, e.g. 83 by creating a virtualenv and using: 84 85 ```pip install -e '.[testing]'``` 86 87 The included ARC tests are very limited. The primary testing method for ARC 88 is using the ARC test suite: https://github.com/ValiMail/arc_test_suite 89 90 As of 0.6.0, all tests pass for both python2.7 and python3. The test suite 91 ships with test runners for dkimpy. After downloading the test suite, you 92 can run the signing and validation tests like this: 93 94 ```python2.7 ./testarc.py sign runners/arcsigntest.py``` 95 ```python2.7 ./testarc.py validate runners/arcverifytest.py``` 96 97 # USAGE 98 99 The dkimpy library offers one module called dkim. The sign() function takes an 100 RFC822 formatted message, along with some signing options, and returns a 101 DKIM-Signature header line that can be prepended to the message. The verify() 102 function takes an RFC822 formatted message, and returns True or False depending 103 on whether the signature verifies correctly. There is also a DKIM class which 104 can be used to perform these functions in a more modern way. 105 106 In version 0.9.0, the default set of header fields that are oversigned was 107 changed from 'from', 'subject', 'date' to 'from' to reduce fragility of 108 signatures. To restore the previous behavior, you can add them back after 109 instantiating your DKIM class using the add_frozen function as shown in the 110 following example: 111 112 ```python 113 >>> dkim = DKIM() 114 >>> dkim.add_frozen((b'date',b'subject')) 115 >>> [text(x) for x in sorted(dkim.frozen_sign)] 116 ['date', 'from', 'subject'] 117 ``` 118 119 ## DKIM RSA MODERNIZATION (RFC 8301) 120 121 RFC8301 updated DKIM requirements in two ways: 122 123 1. It set the minimum valid RSA key size to 1024 bits. 124 2. It removed use of rsa-sha1. 125 126 As of version 0.7, the dkimpy defaults largely support these requirements. 127 128 It is possible to override the minimum key size to a lower value, but this is 129 strongly discouraged. As of 2018, keys much smaller than the minimum are not 130 difficult to factor. 131 132 The code for rsa-sha1 signing and verification is retained, but not used for 133 signing by default. Future releases will raise warnings and then errors when 134 verifying rsa-sha1 signatures. There are still some significant users of 135 rsa-sha1 signatures, so operationally it's premature to disable verification 136 of rsa-sha1. 137 138 ## ED25519 (RFC 8463) SUPPORT 139 140 As of version 0.7, experimental signing and verifying of DKIM Ed25519 141 signatures is supported as described in draft-ietf-dcrup-dkim-crypto: 142 143 https://datatracker.ietf.org/doc/draft-ietf-dcrup-dkim-crypto/ 144 145 The RFC that documents ed25519 DKIM signatures, RFC 8463, has been released 146 and dkimpy 0.7 and later are aligned to its requirements. As of 0.8, ed25519 147 need not be considered experimental. The dkimpy implementation has 148 successfully interoperated with three other implementations and the technical 149 parameters for ed25519-sha256 are defined and stable. 150 151 To install from pypi with the required optional depenencies, use the ed25519 152 option: 153 154 ```pip install -e '.[ed25519]'``` 155 156 ## DKIM SCRIPTS 157 158 Three helper programs are also supplied: dknewkey, dkimsign and 159 dkimverify 160 161 dknewkey is s script that produces private and public key pairs suitable 162 for use with DKIM. Note that the private key file format used for ed25519 is 163 not standardized (there is no standard) and is unique to dkimpy. 164 165 dkimsign is a filter that reads an RFC822 message on standard input, and 166 writes the same message on standard output with a DKIM-Signature line 167 prepended. The signing options are specified on the command line: 168 169 dkimsign selector domain privatekeyfile [identity] 170 171 The identity is optional and defaults to "@domain". 172 173 dkimverify reads an RFC822 message on standard input, and returns with exit 174 code 0 if the signature verifies successfully. Otherwise, it returns with exit 175 code 1. 176 177 ## ARC (Authenticated Receive Chain) 178 179 As of version 0.6.0, dkimpy provides experimental support for ARC (Authenticated 180 Received Chain). See RFC 8617 for the current version of ARC: 181 182 https://tools.ietf.org/html/rfc8617 183 184 In addition to arcsign and arcverify, the dkim module now provides 185 arc_sign and arc_verify functions as well as an ARC class. 186 187 Both DKIM ed25519 and ARC are now considered stable (no longer experimantal). 188 189 ## ASYNC SUPPORT 190 191 As of version 1.0, an alternative to dkim.verify for use in an async 192 environment is provied. It requires aiodns, https://pypi.org/project/aiodns/. 193 Here is a simple example of dkim.verify_async usage: 194 195 ```python 196 >>> sys.stdin = sys.stdin.detach() 197 >>> 198 >>> async def main(): 199 >>> res = await dkim.verify_async(message) 200 >>> return res 201 >>> 202 >>> if __name__ == "__main__": 203 >>> res = asyncio.run(main()) 204 ``` 205 206 This feature requires python3.5 or newer. 207 208 ## TLSRPT (TLS Report) 209 210 As of version 1.0, the RFC 8460 tlsrpt service type is supported: 211 212 https://tools.ietf.org/html/rfc8460 213 214 A non-tlsrpt signed with a key record with s=tlsrpt won't verify. Since the 215 service type (s=) is optional in the DKIM public key record, it is not 216 required by RFC 8460. When checking for a tlsrpt signature, set the tlsrpt= 217 flag when verifying the signature: 218 219 ```python 220 >>> res = dkim.verify(smessage, tlsrpt='strict') 221 ``` 222 223 If tlsrpt='strict', only public key records with s=tlsrpt will be considered 224 valid. If set to tlsrpt=True, the service type is not required, but other 225 RFC 8460 requirements are applied. 226 227 # FEEDBACK 228 229 Bug reports may be submitted to the bug tracker for the dkimpy project on 230 launchpad. 231 232Platform: UNKNOWN 233Classifier: Development Status :: 5 - Production/Stable 234Classifier: Environment :: No Input/Output (Daemon) 235Classifier: Intended Audience :: Developers 236Classifier: License :: DFSG approved 237Classifier: Natural Language :: English 238Classifier: Operating System :: OS Independent 239Classifier: Programming Language :: Python 240Classifier: Programming Language :: Python :: 3 241Classifier: Topic :: Communications :: Email :: Mail Transport Agents 242Classifier: Topic :: Communications :: Email :: Filters 243Classifier: Topic :: Internet :: Name Service (DNS) 244Classifier: Topic :: Software Development :: Libraries :: Python Modules 245Description-Content-Type: text/markdown 246Provides-Extra: ARC 247Provides-Extra: asyncio 248Provides-Extra: ed25519 249Provides-Extra: testing 250