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