django-secure-mail 1.2.0

Introduction

django-secure-mail is a Django reusable app providing a mail backend to send opportunistically signed and encrypted emails using PGP. Also provided are models and an admin page to manage uploaded PGP keys.

Note that the provided backend only signs outgoing mail if the recipient has uploaded a valid public key. Users without valid public keys will not have their outgoing mail signed or encrypted.

Dependencies

• python-gnupg is required for sending PGP encrypted email.

Installation

The easiest way to install django-secure-mail is directly from PyPi using pip by running the command below:

$ pip install django-secure-mail

Otherwise you can download django-secure-mail and install it directly from source:

$ python setup.py install

Configuration

1. Add secure_mail to your INSTALLED_APPS setting and run database migrations:

   $ python manage.py migrate secure_mail

2. Set EMAIL_BACKEND in your settings module to secure_mail.backends.EncryptingSmtpEmailBackend or one of the development/testing backends listed in Development and Testing.

3. Set the SECURE_MAIL_GNUPG_HOME setting to a directory that contains the GPG keyring. If you are running multiple Django nodes, each node will need read and write access to this directory.

4. Set the SECURE_MAIL_GNUPG_ENCODING variable to the encoding your GPG executable requires. This is generally latin-1 for GPG 1.x and utf-8 for GPG 2.x.

5. Whle it is not required to send encrypted email, it is highly recommended that you generate a signing key for outgoing mail. Please follow the instructions in the Generate Signing Key section. All nodes that will be sending outgoing mail will need to have read access to the directory specified by SECURE_MAIL_GNUPG_HOME.

There are additional configuration options available. Please see the Options section for a complete list.

SECURE_MAIL_SIGNING_KEY_DATA = {
    'key_type': "RSA",
    'key_length': 4096,
    'name_real': settings.SITE_NAME,
    'name_comment': "Outgoing email server",
    'name_email': settings.DEFAULT_FROM_EMAIL,
    'expire_date': '2y',
}

$ python manage.py email_signing_key --generate

$ python manage.py email_signing_key 7AB59FE794A7AC12EBA87507EF33F601153CFE28

$ python manage.py email_signing_key 7AB59FE794A7AC12EBA87507EF33F601153CFE28 --print-private-key

$ python manage.py email_signing_key 7AB59FE794A7AC12EBA87507EF33F601153CFE28 -k keys.ubuntu.com keys.redhat.com -k pgp.mit.edu

$ python manage.py email_signing_key --generate --keyserver pgp.mit.edu --print-private-key

Sending PGP Encrypted Email

Once the backend is configured and specified by the EMAIL_BACKEND setting, all outgoing mail will be opportunistically signed and encrypted. This means that if a message is being sent to a recipient who has a valid public key in the database and the GPG/PGP keyring, the backend will attempt to sign and encrypt outgoing mail to them.

Error Handling

This backend allows users to specify custom error handlers when encryption fails for the following objects:

• The plain text message itself

• Any message attachments

• Any message alternatives (for instance: HTML mail delivered with a plain text fallback)

Error handlers are called when an exception is raised and are passed the raised exception.

def handle_failed_encryption(exception):
    # Handle errors

def handle_failed_alternative_encryption(exception):
    # Handle errors

def handle_failed_attachment_encryption(exception):
    # Handle errors

The default error handlers simply re-raise the exception, but this may be undesirable for all cases.

To assist with handling errors, the package provides a few helper functions that can be used in custom error handlers:

• force_send_message - Accepts the unencrypted message as an argument, and sends the message without attempting to encrypt or sign it.

• force_delete_key - Accepts the recipient’s address as an argument and forcibly removes all keys from the database and the GPG/PGP keyring.

• force_mail_admins - Accepts the unencrypted message and the failing address as arguments. If the address is in the ADMINS setting, it sends the message unencrypted, otherwise, it mails the admins a message containing the subject of the original message and the original intended recipient.

• get_variable_from_exception - Accepts the exception and a variable name as arguments, then digs back through the stacktrace to find the first variable with the specified name.

To specify a custom error handlers, set keys in the SECURE_MAIL_FAILURE_HANDLERS setting dictionary in your project’s settings.py to the dotted-path of your error handler/s:

SECURE_MAIL_FAILURE_HANDLERS = {
    'message': 'myapp.handlers.handle_failed_encryption',
    'alternative': 'myapp.handlers.handle_failed_alternative_encryption',
    'attachment': 'myapp.handlers.handle_failed_attachment_encryption',
}

You do not have to override all of the handlers, you can override as many or as few as you wish.

Development and Testing

This package provides a backend mixin (EncryptingEmailBackendMixin) if you wish to extend the backend or create a custom backend of your own:

class EncryptingLocmemEmailBackend(EncryptingEmailBackend, LocmemBackend):
    pass

For a working, real-world example of using the EncryptingEmailBackendMixin in another Django app, check out the emailhub.backends.secure_mail.EncryptingEmailBackendMixin from the django-emailhub project:

In addition to the provided EncryptingSmtpEmailBackend, this package ships with a few more backends that mirror the built-in Django backends:

• EncryptingConsoleEmailBackend

• EncryptingLocmemEmailBackend

• EncryptingFilebasedEmailBackend

Alternative Django Apps

Other Django apps with similar functionality are:

• django-email-extras - Provides two functions for sending PGP encrypted, multipart emails using Django’s template system. Also provides a mail backend that displays HTML mail in the browser during development.

• django-gnupg-mails - Provides a GnuPGMessage (subclass of Django’s EmailMessage) to send PGP/MIME signed email.

Both of those apps require third party app developers to “opt-in” to sending encrypted mail. This project automatically encrypts and signs all outgoing mail for all apps.