Scott Kitterman
8032276b57
- Update oversigned (frozen) header field list to reduce signature
fragility (removes 'date' and 'subject' fields from being oversigned by
default - see usage section of README for information on how to restore
the previous behavior)
- Added new add_should_not for DKIM/ARC classes to prevent additional
header fields from being signed
- Added 'from' to should sign list (to prevent it from not being signed at
all in the unusual event that 'from' is locally removed from the frozen
header field set (LP: #1525048)
- Updates for experimental ARC support:
- Specified that for ARC, Authentication-Results should not be signed
172 lines
6.3 KiB
Plaintext
172 lines
6.3 KiB
Plaintext
dkimpy - DKIM (DomainKeys Identified Mail)
|
|
https://launchpad.net/dkimpy/
|
|
|
|
Friendly fork of:
|
|
http://hewgill.com/pydkim/
|
|
|
|
INTRODUCTION
|
|
|
|
dkimpy is a library that implements DKIM (DomainKeys Identified Mail) email
|
|
signing and verification.
|
|
|
|
VERSION
|
|
|
|
This is dkimpy 0.9.0.
|
|
|
|
REQUIREMENTS
|
|
|
|
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.
|
|
|
|
- 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
|
|
and python 3.1 - 3.3.
|
|
- dnspython or pydns. dnspython is preferred if both are present and
|
|
installed to satisfy the DNS module requirement if neither are installed.
|
|
- argparse. Standard library in python2.7 and later.
|
|
- authres. Needed for ARC.
|
|
- PyNaCl. Needed for use of ed25519 capability.
|
|
|
|
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:
|
|
|
|
python setup.py install --single-version-externally-managed --record=/dev/null
|
|
|
|
DOCUMENTATION
|
|
|
|
An online version of the package documentation can be found at:
|
|
|
|
https://gathman.org/pydkim/
|
|
|
|
TESTING
|
|
|
|
To run dkimpy's test suite:
|
|
|
|
PYTHONPATH=. python dkim
|
|
or
|
|
python test.py
|
|
or
|
|
PYTHONPATH=. python -m unittest dkim.tests.test_suite
|
|
|
|
Alternatively, if you have testrepository installed:
|
|
|
|
testr init
|
|
testr run
|
|
|
|
You should install all optional dependencies, 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
|
|
|
|
As of 0.6.0, all tests except as_fields_b_512 pass for both python2.7 and
|
|
python3.5. 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
|
|
|
|
The reason for the test failure is that the ARC specification (as of 20170120)
|
|
sets the minimum key size to 512 bits. This is operationally inappropriate,
|
|
so dkimpy sets the default minkey=1024, the same as is used for DKIM. This
|
|
can be overridden, but that is not recommended. The minimum key size
|
|
requirement for DKIM (and thus ARC) has recently been updated to require at
|
|
least a 1024 bit key. See RFC 8301.
|
|
|
|
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
|
|
DKIM-Signature header line that can be prepended to the message. The verify()
|
|
function takes an RFC822 formatted message, and returns True or False depending
|
|
on whether the signature verifies correctly. There is also a DKIM class which
|
|
can be used to perform these functions in a more modern way.
|
|
|
|
In version 0.9.0, the default set of header fields that are oversigned was
|
|
changed from 'from', 'subject', 'date' to 'from' to reduce fragility of
|
|
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:
|
|
|
|
>>> dkim = DKIM()
|
|
>>> dkim.add_frozen((b'date',b'subject'))
|
|
>>> [text(x) for x in sorted(dkim.frozen_sign)]
|
|
['date', 'from', 'subject']
|
|
|
|
RFC8301 updated DKIM requirements in two ways:
|
|
|
|
1. It set the minimum valid RSA key size to 1024 bits.
|
|
2. It removed use of rsa-sha1.
|
|
|
|
As of version 0.7, the dkimpy defaults largely support these requirements.
|
|
|
|
It is possible to override the minimum key size to a lower value, but this is
|
|
strongly discouraged. As of 2018, keys much smaller than the minimum are not
|
|
difficult to factor.
|
|
|
|
The code for rsa-sha1 signing and verification is retained, but not used for
|
|
signing by default. Future releases will raise warnings and then errors when
|
|
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.
|
|
|
|
As of version 0.7, experimental signing and verifying of DKIM Ed25519
|
|
signatures is supported as described in draft-ietf-dcrup-dkim-crypto:
|
|
|
|
https://datatracker.ietf.org/doc/draft-ietf-dcrup-dkim-crypto/
|
|
|
|
The dkimpy 0.7 implementation matches the -08 revision of the draft, except it
|
|
uses Ed25519 vice Ed25519ph (a change to Ed25519 is planned for -09, but that
|
|
had not been published yet as of the release of dkimpy 0.7).
|
|
|
|
draft-ietf-dcrup-dkim-crypto-09 has been released and dkimpy 0.7 and later are
|
|
aligned to its requirements. As of 0.8, ed25519 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.
|
|
|
|
Three helper programs are also supplied: dknewkey, dkimsign and
|
|
dkimverify
|
|
|
|
dknewkey is s script that produces private and public key pairs suitable
|
|
for use with DKIM. Note that the private key file format used for ed25519 is
|
|
not standardized (there is no standard) and is unique to dkimpy.
|
|
|
|
dkimsign is a filter that reads an RFC822 message on standard input, and
|
|
writes the same message on standard output with a DKIM-Signature line
|
|
prepended. The signing options are specified on the command line:
|
|
|
|
dkimsign selector domain privatekeyfile [identity]
|
|
|
|
The identity is optional and defaults to "@domain".
|
|
|
|
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.
|
|
|
|
As of version 0.6.0, dkimpy provides experimental support for ARC (Authenticated
|
|
Received Chain):
|
|
|
|
https://tools.ietf.org/html/draft-ietf-dmarc-arc-protocol-18
|
|
|
|
This new functionality is marked experimental because the protocol is still
|
|
under development. There are no guarantees about API stability or
|
|
compatibility.
|
|
|
|
In addition to arcsign and arcverify, the dkim module now provides
|
|
arc_sign and arc_verify functions as well as an ARC class.
|
|
|
|
FEEDBACK
|
|
|
|
Bug reports may be submitted to the bug tracker for the dkimpy project on
|
|
launchpad.
|