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