1 Python module and tools for constructing and sending PGP/MIME email.
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.
16 I've packaged ``pgp-mime`` for Gentoo_. You need layman_ and
17 my `wtk overlay`_. Install with::
19 # emerge -av app-portage/layman
21 # emerge -av dev-python/pgp-mime
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
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.
44 ``pgp-mime`` is available as a Git_ repository::
46 $ git clone git://tremily.us/pgp-mime.git
48 See the homepage_ for details. To install the checkout, run the
51 $ python setup.py install
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.
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::
67 $ FROM="From: Rincewind <rincewind@uu.edu>"
69 Twoflower <tf@isa.ae.cw>|9
70 Eric Thursley <et@pseudopolis.net>|10
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
79 If you can convince your students to get PGP keys, you could also
80 encrypt their grades by changing ``--mode sign`` to ``--mode
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.
87 Configuring the SMTP connection
88 -------------------------------
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``::
97 host: smtp.mail.uu.edu
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.
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.
115 Run the internal unit tests using nose_::
117 $ nosetests --with-doctest --doctest-tests pgp_mime
119 If a Python-3-version of ``nosetests`` is not the default on your
120 system, you may need to try something like::
122 $ nosetests-3.2 --with-doctest --doctest-tests pgp_mime
127 This project is distributed under the `GNU General Public License
128 Version 3`_ or greater.
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/
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