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