README

   1 Python module and for constructing and sending PGP/MIME email.
   2
   3 The ``pgp_mime`` module makes it easy to construct and dispatch signed
   4 and/or encrypted email using PGP_ and :RFC:`3156`.  It uses GnuPG_ to
   5 perform the cryptography.
   6
   7 Installation
   8 ============
   9
  10 Packages
  11 --------
  12
  13 Gentoo
  14 ~~~~~~
  15
  16 I've packaged ``pgp-mime`` for Gentoo_.  You need layman_ and
  17 my `wtk overlay`_.  Install with::
  18
  19   # emerge -av app-portage/layman
  20   # layman --add wtk
  21   # emerge -av dev-python/pgp-mime
  22
  23 Dependencies
  24 ------------
  25
  26 ``pgp-mime`` is a simple package with no external dependencies outside
  27 the Python 3 standard library.  There are a number of GnuPG_ wrappers
  28 for python `out there`__, but none of them seem mature/stable enough
  29 to be worth installing.  Instead, we use the ``subprocess`` module to
  30 call ``gpg`` directly.  If this isn't working for you, you need only
  31 replace the ``*_bytes`` commands which handle the cryptography.
  32
  33 __ wrappers_
  34
  35 Installing by hand
  36 ------------------
  37
  38 ``pgp-mime`` is available as a Git_ repository::
  39
  40   $ git clone git://tremily.us/pgp-mime.git
  41
  42 See the homepage_ for details.  To install the checkout, run the
  43 standard::
  44
  45   $ python setup.py install
  46
  47 Usage
  48 =====
  49
  50 Pgp-mime has grown up as I've become more experienced with Python.
  51 The current interface is much simpler, and there are lots of
  52 docstrings showing you how to use each function.
  53
  54 If you're looking for a higher level example, pgp-mime includes a
  55 command line script ``send-pgp-mime.py`` that allows you to send
  56 signed and/or encrypted email from the command line.  I recommend you
  57 use ``gpg2`` with my `wrappers and pinentry program`_ to allow easy
  58 pinentry from the command line.  Here's how you could mail signed
  59 grades to your class::
  60
  61   $ FROM="From: Rincewind <rincewind@uu.edu>"
  62   $ head -n2 grades
  63   Twoflower <tf@isa.ae.cw>|9
  64   Eric Thursley <et@pseudopolis.net>|10
  65   $ while read LINE; do
  66       STUDENT=$(echo "$LINE" | cut -d '|' -f 1)
  67       GRADE=$(echo "$LINE" | cut -d '|' -f 2)
  68       HEAD=$(echo -e "$FROM\nTo: $STUDENT\nSubject: Grades")
  69       BODY=$(echo -e "$STUDENT,\n\nYou got a $GRADE.\n\nGood job.")
  70       send-pgp-mime.py -H <(echo "$HEAD") -B <(echo "$BODY") --mode sign
  71     done < grades
  72
  73 If you can convince your students to get PGP keys, you could also
  74 encrypt their grades by changing ``--mode sign`` to ``--mode
  75 sign-encrypt``.
  76
  77 Configuring the SMTP connection
  78 -------------------------------
  79
  80 Pgp-mime supports two methods for sending messages (via
  81 ``pgp_mime.mail``).  It can either call your system's ``sendmail``
  82 equivalent, or connect directly to an SMTP_ server using ``smtplib``.
  83 Since I imagine SMTP will be more common, you can easily configure
  84 your SMTP connection via ``~/.config/pgp-mime.conf``::
  85
  86   [smtp]
  87   host: smtp.mail.uu.edu
  88   port: 587
  89   starttls: yes
  90   username: rincewind
  91   password: 7ugg@g3
  92
  93 All of these fields are optional.  ``host`` defaults to ``localhost``
  94 and ``port`` defaults to 25.  If ``username`` is not given, we do not
  95 attempt to login to the SMTP server after connecting.
  96
  97 If ``starttls`` is ``no`` or not given, the SMTP transaction occurs in
  98 plain text (although the underlying emails will still be encrypted).
  99 However, if you set a ``username`` (to login), pgp-mime will require a
 100 STARTTLS_ to protect your password from sniffing.
 101
 102 Testing
 103 =======
 104
 105 Run the internal unit tests using nose_::
 106
 107   $ nosetests --with-doctest --doctest-tests pgp-mime
 108
 109 If a Python-3-version of ``nosetests`` is not the default on your
 110 system, you may need to try something like::
 111
 112   $ nosetests-3.2 --with-doctest --doctest-tests pgp-mime
 113
 114 Licence
 115 =======
 116
 117 This project is distributed under the `GNU General Public License
 118 Version 3`_ or greater.
 119
 120 Author
 121 ======
 122
 123 W. Trevor King
 124 wking@drexel.edu
 125
 126 .. _PGP: http://en.wikipedia.org/wiki/Pretty_Good_Privacy
 127 .. _Gentoo: http://www.gentoo.org/
 128 .. _layman: http://layman.sourceforge.net/
 129 .. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay
 130 .. _wrappers: http://wiki.python.org/moin/GnuPrivacyGuard
 131 .. _Git: http://git-scm.com/
 132 .. _homepage: http://blog.tremily.us/posts/pgp-mime/
 133 .. _wrappers and pinentry program: http://blog.tremily.us/posts/gpg-agent/
 134 .. _SMTP: http://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol
 135 .. _STARTTLS: http://en.wikipedia.org/wiki/STARTTLS
 136 .. _GnuPG: http://www.gnupg.org/
 137 .. _nose: http://readthedocs.org/docs/nose/en/latest/
 138 .. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.html