From 8701e996d3ab2ba5a92c9bb0f09386d18336ca81 Mon Sep 17 00:00:00 2001 From: Scott Kitterman Date: Mon, 9 Dec 2019 17:36:01 -0500 Subject: [PATCH] Make README Mardown (README.md) and use for long_description --- MANIFEST.in | 2 +- README => README.md | 62 ++++++++++++++++++++++++++++++--------------- setup.py | 11 ++++---- 3 files changed, 49 insertions(+), 26 deletions(-) rename README => README.md (88%) diff --git a/MANIFEST.in b/MANIFEST.in index 58d5846..f2d0b51 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -2,7 +2,7 @@ include dkim/* include dkim/tests/* include dkim/tests/data/* include LICENSE -include README +include README.md include ChangeLog include MANIFEST.in include man/* diff --git a/README b/README.md similarity index 88% rename from README rename to README.md index 69b4dd1..7ee36a8 100644 --- a/README +++ b/README.md @@ -4,18 +4,18 @@ https://launchpad.net/dkimpy/ Friendly fork of: http://hewgill.com/pydkim/ -INTRODUCTION +# INTRODUCTION dkimpy is a library that implements DKIM (DomainKeys Identified Mail) email signing and verification. Basic DKIM requirements are defined in RFC 6376: https://tools.ietf.org/html/rfc6376 -VERSION +# VERSION This is dkimpy 1.0.0. -REQUIREMENTS +# REQUIREMENTS Dependencies will be automatically included for normal DKIM usage. The extras_requires feature 'ed25519' will add the dependencies needed for signing @@ -34,40 +34,46 @@ needed for asyncio. - PyNaCl. Needed for use of ed25519 capability. - aiodns. Needed for asycnio (Requires python3.5 or later) -INSTALLATION +# INSTALLATION This package includes a scripts and man pages. For those to be installed when installing using setup.py, the following incantation is required because setuptools developers decided not being able to do this by default is a feature: -python3 setup.py install --single-version-externally-managed --record=/dev/null +```python3 setup.py install --single-version-externally-managed --record=/dev/null``` -DOCUMENTATION +# DOCUMENTATION An online version of the package documentation can be found at: https://gathman.org/pydkim/ -TESTING +# TESTING To run dkimpy's test suite: - PYTHONPATH=. python3 dkim +```PYTHONPATH=. python3 dkim``` + or - python3 test.py + +```python3 test.py``` + or - PYTHONPATH=. python3 -m unittest dkim.tests.test_suite + +```PYTHONPATH=. python3 -m unittest dkim.tests.test_suite``` + Alternatively, if you have testrepository installed: - testr init - testr run +```testr init``` -You should install all optional dependencies, e.g. by creating a virtualenv -and using: +```testr run``` - pip install -e '.[testing]' +You should install all optional dependencies required for the test suite, e.g. +by creating a virtualenv and using: + +```pip install -e '.[testing]'``` The included ARC tests are very limited. The primary testing method for ARC is using the ARC test suite: https://github.com/ValiMail/arc_test_suite @@ -76,10 +82,10 @@ As of 0.6.0, all tests pass for both python2.7 and python3. The test suite ships with test runners for dkimpy. After downloading the test suite, you can run the signing and validation tests like this: -python2.7 ./testarc.py sign runners/arcsigntest.py -python2.7 ./testarc.py validate runners/arcverifytest.py +```python2.7 ./testarc.py sign runners/arcsigntest.py``` +```python2.7 ./testarc.py validate runners/arcverifytest.py``` -USAGE +# USAGE The dkimpy library offers one module called dkim. The sign() function takes an RFC822 formatted message, along with some signing options, and returns a @@ -94,10 +100,14 @@ signatures. To restore the previous behavior, you can add them back after instantiating your DKIM class using the add_frozen function as shown in the following example: +```python >>> dkim = DKIM() >>> dkim.add_frozen((b'date',b'subject')) >>> [text(x) for x in sorted(dkim.frozen_sign)] ['date', 'from', 'subject'] +``` + +## DKIM RSA MODERNIZATION (RFC 8301) RFC8301 updated DKIM requirements in two ways: @@ -116,6 +126,8 @@ verifying rsa-sha1 signatures. There are still some significant users of rsa-sha1 signatures, so operationally it's premature to disable verification of rsa-sha1. +## ED25519 (RFC 8463) SUPPORT + As of version 0.7, experimental signing and verifying of DKIM Ed25519 signatures is supported as described in draft-ietf-dcrup-dkim-crypto: @@ -127,6 +139,8 @@ need not be considered experimental. The dkimpy implementation has successfully interoperated with three other implementations and the technical parameters for ed25519-sha256 are defined and stable. +## DKIM SCRIPTS + Three helper programs are also supplied: dknewkey, dkimsign and dkimverify @@ -146,6 +160,8 @@ dkimverify reads an RFC822 message on standard input, and returns with exit code 0 if the signature verifies successfully. Otherwise, it returns with exit code 1. +## ARC (Authenticated Receive Chain) + As of version 0.6.0, dkimpy provides experimental support for ARC (Authenticated Received Chain). See RFC 8617 for the current version of ARC: @@ -156,12 +172,13 @@ arc_sign and arc_verify functions as well as an ARC class. Both DKIM ed25519 and ARC are now considered stable (no longer experimantal). -ASYNC SUPPORT +## ASYNC SUPPORT As of version 1.0, an alternative to dkim.verify for use in an async environment is provied. It requires aiodns, https://pypi.org/project/aiodns/. Here is a simple example of dkim.verify_async usage: +```python >>> sys.stdin = sys.stdin.detach() >>> >>> async def main(): @@ -170,9 +187,12 @@ Here is a simple example of dkim.verify_async usage: >>> >>> if __name__ == "__main__": >>> res = asyncio.run(main()) +``` This feature requires python3.5 or newer. +## TLSRPT (TLS Report) + As of version 1.0, the RFC 8460 tlsrpt service type is supported: https://tools.ietf.org/html/rfc8460 @@ -182,13 +202,15 @@ service type (s=) is optional in the DKIM public key record, it is not required by RFC 8460. When checking for a tlsrpt signature, set the tlsrpt= flag when verifying the signature: +```python >>> res = dkim.verify(smessage, tlsrpt='strict') +``` If tlsrpt='strict', only public key records with s=tlsrpt will be considered valid. If set to tlsrpt=True, the service type is not required, but other RFC 8460 requirements are applied. -FEEDBACK +# FEEDBACK Bug reports may be submitted to the bug tracker for the dkimpy project on launchpad. diff --git a/setup.py b/setup.py index 29595f2..6e0ead8 100644 --- a/setup.py +++ b/setup.py @@ -37,14 +37,15 @@ try: except ImportError: # If PyDNS is not installed, prefer dnspython kw['install_requires'] = ['dnspython'] +with open("README.md", "r") as fh: + long_description = fh.read() + setup( name = "dkimpy", version = version, - description = "DKIM (DomainKeys Identified Mail)", - long_description = - """dkimpy is a Python library that implements DKIM (DomainKeys -Identified Mail) and ARC (Authenticated Received Chain) email signing and -verification.""", + description = "DKIM (DomainKeys Identified Mail), ARC (Authenticated Receive Chain), and TLSRPT (TLS Report) email signing and verification", + long_description=long_description, + long_description_content_type='text/markdown', author = "Scott Kitterman", author_email = "scott@kitterman.com", url = "https://launchpad.net/dkimpy",