Metadata-Version: 2.1
Name: django-secure-mail
Version: 1.3.0
Summary: A Django reusable app providing the ability to send PGP encrypted and multipart emails using the Django templating system.
Home-page: https://github.com/blag/django-secure-mail
Author: blag
Author-email: blag@users.noreply.github.com
License: UNKNOWN
Description: .. image:: https://travis-ci.org/blag/django-secure-mail.svg?branch=master
            :target: https://travis-ci.org/blag/django-secure-mail
        
        .. image:: https://coveralls.io/repos/github/blag/django-secure-mail/badge.svg
            :target: https://coveralls.io/github/blag/django-secure-mail
        
        
        Created by `blag <http://github.com/blag>`_. Forked from PR
        `#39 <https://github.com/stephenmcd/django-email-extras/pull/39>`_ and
        `#40 <https://github.com/stephenmcd/django-email-extras/pull/40>`_ of
        `django-email-extras <https://github.com/stephenmcd/django-email-extras>`_ by
        `Stephen McDonald <http://twitter.com/stephen_mcd>`_.
        
        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 <https://bitbucket.org/vinay.sajip/python-gnupg>`_ is
          required for sending PGP encrypted email.
        
        
        Installation
        ============
        
        The easiest way to install django-secure-mail is directly from PyPi
        using `pip <https://pip.pypa.io/en/stable/>`_ by running the command
        below:
        
        .. code-block:: bash
        
            $ pip install django-secure-mail
        
        Otherwise you can download django-secure-mail and install it directly
        from source:
        
        .. code-block:: bash
        
            $ python setup.py install
        
        
        Configuration
        =============
        
        1. Add ``secure_mail`` to your ``INSTALLED_APPS`` setting and run database
           migrations:
        
            .. code-block:: bash
        
                $ 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.
        
        
        Generate Signing Key
        --------------------
        
        Adding a private/public signing keypair is different than importing a
        public encryption key, since the private key will be stored on the
        server.
        
        This project ships with a Django management command to generate and
        export signing keys: ``email_signing_key``.
        
        You first need to set the ``SECURE_MAIL_SIGNING_KEY_DATA`` option in your
        project's ``settings.py``. This is a dictionary that is passed as keyword arguments directly to ``GPG.gen_key()``, so please read and understand all of
        the available `options in their documentation <https://pythonhosted.org/python-gnupg/#generating-keys>`_. The default settings are:
        
        .. code-block:: python
        
            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',
            }
        
        You may wish to change the ``key_type`` to a signing-only type of key,
        such as DSA, or the expire date.
        
        Once you are content with the signing key settings, generate a new
        signing key with the ``--generate`` option:
        
        .. code-block:: bash
        
            $ python manage.py email_signing_key --generate
        
        To work with specific keys, identify them by their fingerprint
        
        .. code-block:: bash
        
            $ python manage.py email_signing_key 7AB59FE794A7AC12EBA87507EF33F601153CFE28
        
        You can print the private key to your terminal/console with:
        
        .. code-block:: bash
        
            $ python manage.py email_signing_key 7AB59FE794A7AC12EBA87507EF33F601153CFE28 --print-private-key
        
        And you can upload the public signing key to one or more specified
        keyservers by passing the key server hostnames with the ``-k`` or
        ``--keyserver`` options:
        
        .. code-block:: bash
        
            $ python manage.py email_signing_key 7AB59FE794A7AC12EBA87507EF33F601153CFE28 -k keys.ubuntu.com keys.redhat.com -k pgp.mit.edu
        
        You can also perform all tasks with one command:
        
        .. code-block:: bash
        
            $ python manage.py email_signing_key --generate --keyserver pgp.mit.edu --print-private-key
        
        Use the ``--help`` option to see the complete help text for the command.
        
        Once you have generated the signing key, you will need to configure
        ``secure_mail`` to use it. Set the ``SECURE_MAIL_KEY_FINGERPRINT`` setting to
        the fingerprint of the outgoing signing key you wish to use. 
        
        
        Options
        -------
        
        There are a few settings you can configure in your project's
        ``settings.py`` module:
        
        * ``SECURE_MAIL_GNUPG_HOME`` - String representing a custom location
          for the GNUPG keyring. If you are running multiple Django nodes, this should
          be set to a directory shared by all nodes, and the ``gpg`` executable on all
          nodes will need read and write access to it.
        * ``SECURE_MAIL_USE_GNUPG`` - Boolean that controls whether the PGP
          encryption features are used. Defaults to ``True`` if
          ``SECURE_MAIL_GNUPG_HOME`` is specified, otherwise ``False``.
        * ``SECURE_MAIL_GNUPG_ENCODING`` - The encoding the local ``gpg`` executable
          expects. This option is passed through to the ``str.encode`` function. In
          general, it should be set to ``latin-1`` for GPG 1.x and ``utf-8`` for GPG
          2.x. Check out
          `python-gnupg documentation <https://pythonhosted.org/python-gnupg/#getting-started>`_
          for more info.
        * ``SECURE_MAIL_FAILURE_HANDLERS`` - A dictionary that maps failed types to the
          dotted-path notation of error handlers. See the `Error Handling`_ section for
          details and an example.
        * ``SECURE_MAIL_ALWAYS_TRUST_KEYS`` - Skip key validation and assume that used
          keys are always fully trusted. This simply sets ``--always-trust`` (or
          ``--trust-model`` for more modern versions of GPG). See the GPG documentation
          on the ``--trust-model`` option for more detail about this setting.
        * ``SECURE_MAIL_SIGNING_KEY_PASSPHRASE`` - A passphrase that is passed to GPG
          when generating or printing private signing keys. Defaults to ``''``.
        * ``SECURE_MAIL_SIGNING_KEY_DATA`` - A dictionary of key options for generating
          new signing keys. See the
          `python-gnupg documentation`_ for more
          details.
        
          Default:
        
            .. code-block:: python
        
                {
                    'key_type': "RSA",
                    'key_length': 4096,
                    'name_real': getattr(settings, 'SITE_NAME', ''),
                    'name_comment': "Outgoing email server",
                    'name_email': settings.DEFAULT_FROM_EMAIL,
                    'expire_date': '2y',
                    'passphrase': settings.SECURE_MAIL_SIGNING_KEY_PASSPHRASE,
                }
        
        * ``SECURE_MAIL_KEY_FINGERPRINT`` - The fingerprint of the key to use when
          signing outgoing mail, must exist in the configured keyring.
        
        
        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.
        
        .. code-block:: python
        
            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:
        
        .. code-block:: python
        
            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:
        
        .. code-block:: python
        
            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 <https://github.com/FIXME/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``
        
        
        Database Models
        ---------------
        
        `PGP explanation <https://en.wikipedia.org/wiki/Pretty_Good_Privacy>`_
        
        Using `python-gnupg`_, two models are defined in ``secure_mail.models`` -
        ``Key`` and ``Address`` which represent a PGP key and an email address for a
        successfully imported key. These models exist purely for the sake of importing
        keys and removing keys for a particular address via the Django
        Admin.
        
        When adding a key, the key is imported into the key ring on
        the server and the instance of the ``Key`` model is not saved. The
        email address for the key is also extracted and saved as an
        ``Address`` instance.
        
        The ``Address`` model is then used when sending email to check for
        an existing key to determine whether an email should be encrypted.
        When an ``Address`` is deleted via the Django Admin, the key is
        removed from the key ring on the server.
        
        
        Alternative Django Apps
        =======================
        
        Other Django apps with similar functionality are:
        
        * `django-email-extras <https://github.com/stephenmcd/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 <https://github.com/jandd/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.
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Framework :: Django
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Security :: Cryptography
Description-Content-Type: text/x-rst
Provides-Extra: dev
Provides-Extra: test
