README

   1 Python module and tools 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_
   5 (via `gpgme-tool`_) to 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 `pyassuan`_ module to
  30 talk to `gpgme-tool`_ over pipes or sockets.  If this isn't working
  31 for you, you need only replace the ``pgp_mime.crypt`` module to handle
  32 the cryptography.
  33
  34 __ wrappers_
  35
  36 It would be awkward to backport ``pgp-mime`` to Python 2.7, because we
  37 take advantage of the ``pass_fds`` argument to Popen_ to pass file
  38 descriptors to the child `gpgme-tool` processes.  Once we get to
  39 Python 3.3, we'll use sendmsg_ and recvmsg_ instead.
  40
  41 Installing by hand
  42 ------------------
  43
  44 ``pgp-mime`` is available as a Git_ repository::
  45
  46   $ git clone git://tremily.us/pgp-mime.git
  47
  48 See the homepage_ for details.  To install the checkout, run the
  49 standard::
  50
  51   $ python setup.py install
  52
  53 Usage
  54 =====
  55
  56 Pgp-mime has grown up as I've become more experienced with Python.
  57 The current interface is much simpler, and there are lots of
  58 docstrings showing you how to use each function.
  59
  60 If you're looking for a higher level example, pgp-mime includes a
  61 command line script ``send-pgp-mime.py`` that allows you to send
  62 signed and/or encrypted email from the command line.  I recommend you
  63 use ``gpg2`` with my `wrappers and pinentry program`_ to allow easy
  64 pinentry from the command line.  Here's how you could mail signed
  65 grades to your class::
  66
  67   $ FROM="From: Rincewind <rincewind@uu.edu>"
  68   $ head -n2 grades
  69   Twoflower <tf@isa.ae.cw>|9
  70   Eric Thursley <et@pseudopolis.net>|10
  71   $ while read LINE; do
  72       STUDENT=$(echo "$LINE" | cut -d '|' -f 1)
  73       GRADE=$(echo "$LINE" | cut -d '|' -f 2)
  74       HEAD=$(echo -e "$FROM\nTo: $STUDENT\nSubject: Grades")
  75       BODY=$(echo -e "$STUDENT,\n\nYou got a $GRADE.\n\nGood job.")
  76       send-pgp-mime.py -H <(echo "$HEAD") -B <(echo "$BODY") --mode sign
  77     done < grades
  78
  79 If you can convince your students to get PGP keys, you could also
  80 encrypt their grades by changing ``--mode sign`` to ``--mode
  81 sign-encrypt``.
  82
  83 Of course, if you're interested in working with students and grades,
  84 you might also be interested in my `pygrader`_ package, which uses
  85 pgp-mime under the hood.
  86
  87 Configuring the SMTP connection
  88 -------------------------------
  89
  90 Pgp-mime supports two methods for sending messages (via
  91 ``pgp_mime.mail``).  It can either call your system's ``sendmail``
  92 equivalent, or connect directly to an SMTP_ server using ``smtplib``.
  93 Since I imagine SMTP will be more common, you can easily configure
  94 your SMTP connection via ``~/.config/smtplib.conf``::
  95
  96   [smtp]
  97   host: smtp.mail.uu.edu
  98   port: 587
  99   starttls: yes
 100   username: rincewind
 101   password: 7ugg@g3
 102
 103 All of these fields are optional.  ``host`` defaults to ``localhost``
 104 and ``port`` defaults to 25.  If ``username`` is not given, we do not
 105 attempt to login to the SMTP server after connecting.
 106
 107 If ``starttls`` is ``no`` or not given, the SMTP transaction occurs in
 108 plain text (although the underlying emails will still be encrypted).
 109 However, if you set a ``username`` (to login), pgp-mime will require a
 110 STARTTLS_ to protect your password from sniffing.
 111
 112 Testing
 113 =======
 114
 115 Run the internal unit tests using nose_::
 116
 117   $ nosetests --with-doctest --doctest-tests pgp_mime
 118
 119 If a Python-3-version of ``nosetests`` is not the default on your
 120 system, you may need to try something like::
 121
 122   $ nosetests-3.2 --with-doctest --doctest-tests pgp_mime
 123
 124 Licence
 125 =======
 126
 127 This project is distributed under the `GNU General Public License
 128 Version 3`_ or greater.
 129
 130 Author
 131 ======
 132
 133 W. Trevor King
 134 wking@tremily.us
 135
 136 .. _PGP: http://en.wikipedia.org/wiki/Pretty_Good_Privacy
 137 .. _Gentoo: http://www.gentoo.org/
 138 .. _layman: http://layman.sourceforge.net/
 139 .. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
 140 .. _wrappers: http://wiki.python.org/moin/GnuPrivacyGuard
 141 .. _pyassuan: http://blog.tremily.us/posts/pyassuan/
 142 .. _gpgme-tool:
 143   http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gpgme.git;a=blob;f=src/gpgme-tool.c;hb=HEAD
 144 .. _Popen: http://docs.python.org/py3k/library/subprocess.html#subprocess.Popen
 145 .. _sendmsg: http://docs.python.org/dev/library/socket.html#socket.socket.sendmsg
 146 .. _recvmsg: http://docs.python.org/dev/library/socket.html#socket.socket.recvmsg
 147 .. _Git: http://git-scm.com/
 148 .. _homepage: http://blog.tremily.us/posts/pgp-mime/
 149 .. _wrappers and pinentry program: http://blog.tremily.us/posts/gpg-agent/
 150 .. _pygrader: http://blog.tremily.us/posts/pygrader/
 151 .. _SMTP: http://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol
 152 .. _STARTTLS: http://en.wikipedia.org/wiki/STARTTLS
 153 .. _GnuPG: http://www.gnupg.org/
 154 .. _nose: http://readthedocs.org/docs/nose/en/latest/
 155 .. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.html