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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
|
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>GnuPG support in SqWebMail</title>
<meta name="MSSmartTagsPreventParsing" content="TRUE" />
<!-- $Id: README.html,v 1.10 2003/07/24 23:04:54 mrsam Exp $ -->
</head>
<body text="#000000" bgcolor="#FFFFFF" link="#0000EE" vlink="#551A8B"
alink="#FF0000" xml:lang="en" lang="en">
<!-- Copyright 1998 - 2001 Double Precision, Inc. See COPYING for -->
<!-- distribution information. -->
<h1>GnuPG support in <code>SqWebMail</code></h1>
<p>Table of contents:</p>
<ul>
<li><a href="#intro">Introduction</a><br />
<br />
</li>
<li><a href="#require">Requirements</a><br />
<br />
</li>
<li><a href="#implementation">Implementation</a><br />
<br />
</li>
<li><a href="#interop">Interoperability</a><br />
<br />
</li>
<li><a href="#passphrase">Using passphrase-protected private keys</a><br />
<br />
</li>
<li><a href="#bugs">Bugs</a><br />
<br />
</li>
<li><a href="#random">Important note for Linux and other systems that use
the <code>/dev/random</code> device.</a><br />
<br />
</li>
</ul>
<h2><a name="intro" id="intro">Introduction</a></h2>
<p>This is experimental beta of GnuPG support in <code>SqWebMail</code>. The
following functionality is available:</p>
<ul>
<li>Create new keypairs<br />
<br />
</li>
<li>List public/private keys<br />
<br />
</li>
<li>Delete keys<br />
<br />
</li>
<li>Sign keys<br />
<br />
</li>
<li>Export keys (attach them to the current message)<br />
<br />
</li>
<li>Import keys from messages<br />
<br />
</li>
<li>Sign outgoing messages<br />
<br />
</li>
<li>Encrypt outgoing messages<br />
<br />
</li>
<li>Display and verify signed messages<br />
<br />
</li>
<li>Decrypt encrypted messages<br />
<br />
</li>
<li>Reply and forward encrypted messages. Correctly handle
multipart/alternative and multipart/related.<br />
<br />
</li>
</ul>
<p><code>SqWebMail</code> creates and manages its own keyrings.
<code>$HOME/.gnupg</code> is not used. This allows GnuPG functions to work
for virtual accounts that have no home directory.</p>
<h2><a name="require" id="require">Requirements</a></h2>
<p>This implementation requires GnuPG, which is used for all of the heavy
lifting. No encryption code exists in <code>SqWebMail</code> itself. The
configuration script searches the current PATH for the <code>gpg</code>
binary. The final <code>SqWebMail</code> binary gets the hardcoded absolute
path to the <code>gpg</code> binary. If <code>gpg</code> is not found in the
current PATH, <code>/usr/bin/gpg</code> will be used. Therefore, if GnuPG is
locally installed in a non-default location, make sure that <code>gpg</code>
can be found in the current PATH.</p>
<p>As of now, only GnuPG versions 1.0.4 through 1.0.6 are supported.
<code>SqWebMail</code> uses some command line gpg options that GnuPG's
documentation notes as subject to change. Therefore, all bets are off for any
other version of GnuPG. Support for newer versions of GnuPG will be added in
due time.</p>
<h2><a name="implementation" id="implementation">Implementation</a></h2>
<p><code><code>SqWebMail</code></code> runs <code>gpg</code> automatically to
handle all the actual tasks involved in encrypting and decrypting messages.
<code>make install</code> also installs two more binaries:
<code>reformime</code> and <code>mimegpg</code>. Those binaries do some other
things, and nothing really needs to be done about them, or to them, except to
know that they're there.</p>
<h3>The <code>webgpg</code> script</h3>
<code>make install</code> automatically installs a shell script,
<code>webgpg</code>. Encryption/decryption capabilities for all mail accounts
are disabled by default. The <code>webgpg</code> script takes one argument -
the complete pathname to a Maildir. <code>webgpg</code> creates a new
subdirectory, <code>Maildir/gpg</code>, and initializes it. Once that
subdirectory is created, encryption/decryption in <code>SqWebMail</code> will
become available for that account. Not every mail account has to have
encryption/decryption enabled. This functionality can be selectively enabled
and disabled for individual accounts.
<p>NOTE: <code>webgpg</code> script MUST be executed by the same userid and
groupid that owns the <code>Maildir</code> directory.</p>
<p>NOTE: The current implementation consists of the bare minimum required to
get the overall functionality. As a result, a number of shortcuts are taken
with respect to avoiding some hoops that GnuPG occasionally requires to be
jumped through. For example, by default GnuPG requires that a public key
must be signed before it can be used for encryption. <code>SqWebMail</code>
will automatically provide the "always-trust" option to bypass the check.
Basically, if you have the public key in your keyring, you can use it.</p>
<h3>Issues with adding or activating encryption for existing accounts</h3>
<p>Obviously, encryption/decryption takes additional server CPU cycles. There
is no hard and fast rule for how much additional load is needed. Fortunately,
this is not an "all or none" deal. Encryption support can be activated in a
controlled manner and phased in gradually, in steps, allowing the impact on
the web/mail server to be closely monitored, and controlled.</p>
<h3>Issues with adding or activating encryption for new accounts</h3>
<p>The <code>webgpg</code> script needs to be used to initialize encryption
support for newly-created accounts. Many systems use the
<code>/etc/skel</code> directory as a template for setting up the initial
contents of new accounts. In that case, use run "<code>webgpg
/etc/skel/Maildir</code>", and all new accounts will have encryption
automatically activated.</p>
<h2><a name="interop" id="interop">Interoperability</a></h2>
<p>As of now, <code>SqWebMail</code>'s encryption/decryption is experimental.
There's not been much interoperability testing with other encryption-capable
mail software. It is very much possible that there are some interoperability
issues that will have to be worked out.</p>
<p>The directory <code>Maildir/gpg</code> does pretty much what
<code>$HOME/.gnupg</code> does for the command-line <code>gpg</code> tool.
<code>SqWebMail</code> does not use <code>$HOME/.gnupg</code>, it keeps its
keyrings and other GnuPG-related stuff in the <code>Maildir/gpg</code>
directory. That's because <code>SqWebMail</code> can be configured to use
both physical system accounts and virtual mail accounts, and after
authenticating, there is no difference whatsoever between the two. Therefore,
<code>SqWebMail</code> has no concept of the $HOME directory. Its entire
universe consists of the <code>Maildir</code> directory, and its contents.
<code>SqWebMail</code> is completely unaware of the existence of
<code>$HOME/.gnupg</code>, and will never be aware of it. Any keypairs in
<code>$HOME/.gnupg</code> will have to be imported into
<code>Maildir/gpg</code>.</p>
<h3>Importing keys</h3>
<p>Since <code>$HOME/.gnupg</code> is not used, any existing keys will have
to be imported. If shell access is available, the <code>pubring</code> and
<code>secring</code> files can simply be copied to <code>Maildir/gpg</code>.
The following procedure can be used to import keys in all other
circumstances. The following example imports keys from mail account M to
<code>SqWebMail</code> mail account W.</p>
<ul>
<li>Create a temporary keypair in W.<br />
<br />
</li>
<li>Create a new message, addressed to M, attach the new public key, and
send it.<br />
<br />
</li>
<li>In M, take the new public key and import it.<br />
<br />
</li>
<li>Export M's secret key. With GnuPG, use the following command:
<pre>gpg --export-secret-key --armor [fingerprint]</pre>
<p>The output from this command looks something like this:</p>
<pre>-----BEGIN PGP PRIVATE KEY BLOCK-----
Version: GnuPG v1.0.4 (GNU/Linux)
Comment: For info see http://www.gnupg.org
+M3OSONvootZCzKXP6VT29Vf+lZLQkjSyuY28PpfflaFKi8YpeCEKo4dDhynxCbV
NAYk2I6wXguwl4MOT0ebkEWM1WS9lTsto7cCzz0ovSg3xe82PozA/4s6E5UUgl1B
...
RQj/UASJxoPEEDHAhfZ0FYPsDFbo/P///4nDiTQk6Pz///+J2I1l+FteXcOJ9lWJ
RSBQ/3Uc/3UY/3UU/3UQ/3UM/3UI6GsAAACDxBz/dSxqBf91KGoAicP/dST8McCJ
-----END PGP PRIVATE KEY BLOCK-----</pre>
<br />
<br />
</li>
<li>Wrap this inside a MIME-formatted mail message. The end result should
look something like this:
<pre>Mime-Version: 1.0
Content-Type: multipart/mixed; boundary="xxx"
--xxx
Content-Type: text/plain
Here's the key
--xxx
Content-Type: application/pgp-keys
-----BEGIN PGP PRIVATE KEY BLOCK-----
Version: GnuPG v1.0.4 (GNU/Linux)
Comment: For info see http://www.gnupg.org
+M3OSONvootZCzKXP6VT29Vf+lZLQkjSyuY28PpfflaFKi8YpeCEKo4dDhynxCbV
NAYk2I6wXguwl4MOT0ebkEWM1WS9lTsto7cCzz0ovSg3xe82PozA/4s6E5UUgl1B
...
RQj/UASJxoPEEDHAhfZ0FYPsDFbo/P///4nDiTQk6Pz///+J2I1l+FteXcOJ9lWJ
RSBQ/3Uc/3UY/3UU/3UQ/3UM/3UI6GsAAACDxBz/dSxqBf91KGoAicP/dST8McCJ
-----END PGP PRIVATE KEY BLOCK-----
--xxx</pre>
<br />
<br />
</li>
<li>Encrypt the whole message using W's public key. The end result should
look something like this:
<pre>Mime-version: 1.0
Content-Type: multipart/encrypted;
boundary="yyy";
protocol="application/pgp-encrypted"
--yyy
Content-Type: application/pgp-encrypted
Content-Transfer-Encoding: 7bit
Version: 1
--yyy
Content-Type: application/octet-stream
Content-Transfer-Encoding: 7bit
-----BEGIN PGP MESSAGE-----
Version: GnuPG v1.0.4 (GNU/Linux)
Comment: For info see http://www.gnupg.org
hQIOA8nMaZ+WFjCiEAf+IzymijY0K0ELubJnDuTo0OZg6n8EApLTdwXVZ7sjoWvU
YbEjfvwBXp+wc7X4lvw3S/AGYe4/mmshgTnRjuDPKsN3zHViYGdGF0UaB40sjUp3
...
U9Qi2kvxRvV0b8nBN1qeFUSSRF8Ncwug1sr/rFVNNWA0yavb5WDFrqRE6WFJU3z3
p0vPPRbdWCOTP7WGOygpHdRMLQSCxG4m+L9uG3roG5Uu7A==
=GutI
-----END PGP MESSAGE-----
--yyy--</pre>
<br />
</li>
<li>Mail this message to W. Repeat the procedure with M's public key
(<code>gpg --export-key --armor). If you're handy with composing MIME
messages, both keys can be sent in a single encrypted message. <br />
<br />
</code></li>
<li>In <code>SqWebMail</code>, you should be able to decrypt the message
containing the keys, and import them.</li>
</ul>
<h2><a name="passphrase" id="passphrase">Using passphrase-protected private
keys</a></h2>
<p>SqWebMail can handle passphrase-protected keys only when SSL is being
used. This is an artificial restriction that prevents passphrases from going
over the network, in the clear. When SSL is used, SqWebMail will
automatically prompt for a passphrase. Leave the passphrase field empty if
the secret key is not protected by a passphrase.</p>
<h2><a name="bugs" id="bugs">Bugs</a></h2>
<ol>
<li>Although <code>SqWebMail</code> contains mappings for many charsets,
GnuPG versions prior to 1.0.6 know only about <code>iso-8859-1</code> and
<code>iso-8859-2</code>. All messages displayed by <code>SqWebMail</code>
from GnuPG 1.0.5 or earlier will come out in <code>iso-8859-1</code>. <br
/>
<br />
</li>
<li>Currently, there are no command line options in GnuPG for removing key
signatures (is that even possible?). You can sign keys, but can't
"unsign" them.<br />
<br />
</li>
<li>There has not been any/much interoperability testing with other
GnuPG/PGP mail software. It is entirely possible that
<code>SqWebMail</code>'s implementation is currently not interoperable,
and may require some tinkering as time goes by.<br />
<br />
</li>
<li>GnuPG will always blather "Warning: secret key NOT protected" when
using keys not protected by a passphrase. This whinge is harmless, and
can be ignored.<br />
<br />
</li>
<li>The error message from GnuPG for a missing passphrase is not very
helpful: "Unable to get tty input". This is because SqWebMail runs GnuPG
with the --no-tty flag, and provides a passphrase separately, when it's
entered. When SqWebMail does not provide a passphrase, GnuPG complains
that tty input is disabled.<br />
<br />
</li>
</ol>
<h2><a name="random" id="random">Important note for Linux and other systems
that use the <code>/dev/random</code> device.</a></h2>
<p>If GnuPG is compiled on a system that has a <code>/dev/random</code>
device, GnuPG will use the <code>/dev/random</code> device as a source for
random entropy. The <code>/dev/random</code> device driver in Linux, and in
many other implementations, creates the entropy pool from system device
driver background activity. Unfortunately, it's is not a bottomless pit of
random entropy. When the random device driver entropy pool is empty,
<code>/dev/random</code> halts until device drivers create more noise.</p>
<p>That means that when GnuPG is used on Linux, GnuPG may pause for an
excessive period of time, and issue its famous "please do something" prompt.
Since GnuPG is invoked in automatic mode, there is no other alternative,
except to wait until more device driver noise becomes available.</p>
<p>This is more likely to happen when GnuPG is used to create new keypairs,
especially ones that are 1024 bits, or longer. Before deploying, extensive
testing is recommended to make sure that even an idle system generates
sufficient background noise so that the additional wait is not excessive.
There are several possible solutions that can also be used:</p>
<ol>
<li>GnuPG can be optionally configured to use a pseudo-random generator
that does not use <code>/dev/random</code>, but instead uses several
alternative sources of random junk. Consult GnuPG's documentation for
more information.<br />
<br />
</li>
<li>Many systems also have a <code>/dev/urandom</code> device, which
automatically generates pseudo-random noise if <code>/dev/random</code>
runs out of entropy. This makes it possible to simply remove the
<code>/dev/random</code> device and create a link from
<code>/dev/random</code> to <code>/dev/urandom</code>.</li>
</ol>
<p>Although - technically - both approaches can theoretically result in
slightly less secure keypairs, practically the difference is probably
academic in nature.</p>
</body>
</html>
|
