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