84310
|
1 \input texinfo @c -*-texinfo-*-
|
|
2
|
84329
|
3 @setfilename ../../info/pgg
|
84310
|
4
|
|
5 @set VERSION 0.1
|
|
6
|
|
7
|
|
8 @copying
|
|
9 This file describes PGG, an Emacs interface to various PGP implementations.
|
|
10
|
87903
|
11 Copyright @copyright{} 2001, 2003, 2004, 2005, 2006, 2007, 2008
|
|
12 Free Software Foundation, Inc.
|
84310
|
13
|
|
14 @quotation
|
|
15 Permission is granted to copy, distribute and/or modify this document
|
|
16 under the terms of the GNU Free Documentation License, Version 1.2 or
|
|
17 any later version published by the Free Software Foundation; with no
|
|
18 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
|
|
19 Texts. A copy of the license is included in the section entitled ``GNU
|
|
20 Free Documentation License.''
|
|
21 @end quotation
|
|
22 @end copying
|
|
23
|
|
24 @dircategory Emacs
|
|
25 @direntry
|
|
26 * PGG: (pgg). Emacs interface to various PGP implementations.
|
|
27 @end direntry
|
|
28
|
|
29 @settitle PGG @value{VERSION}
|
|
30
|
|
31
|
|
32 @titlepage
|
|
33 @title PGG
|
|
34
|
|
35 @author by Daiki Ueno
|
|
36 @page
|
|
37
|
|
38 @vskip 0pt plus 1filll
|
|
39 @insertcopying
|
|
40 @end titlepage
|
|
41 @page
|
|
42
|
|
43 @node Top
|
|
44 @top PGG
|
|
45 This manual describes PGG. PGG is an interface library between Emacs
|
|
46 and various tools for secure communication. PGG also provides a simple
|
|
47 user interface to encrypt, decrypt, sign, and verify MIME messages.
|
|
48
|
|
49 @menu
|
|
50 * Overview:: What PGG is.
|
|
51 * Prerequisites:: Complicated stuff you may have to do.
|
|
52 * How to use:: Getting started quickly.
|
|
53 * Architecture::
|
|
54 * Parsing OpenPGP packets::
|
|
55 * GNU Free Documentation License:: The license for this documentation.
|
|
56 * Function Index::
|
|
57 * Variable Index::
|
|
58 @end menu
|
|
59
|
|
60 @node Overview
|
|
61 @chapter Overview
|
|
62
|
|
63 PGG is an interface library between Emacs and various tools for secure
|
|
64 communication. Even though Mailcrypt has similar feature, it does not
|
|
65 deal with detached PGP messages, normally used in PGP/MIME
|
|
66 infrastructure. This was the main reason why I wrote the new library.
|
|
67
|
|
68 PGP/MIME is an application of MIME Object Security Services (RFC1848).
|
|
69 The standard is documented in RFC2015.
|
|
70
|
|
71 @node Prerequisites
|
|
72 @chapter Prerequisites
|
|
73
|
|
74 PGG requires at least one implementation of privacy guard system.
|
|
75 This document assumes that you have already obtained and installed them
|
|
76 and that you are familiar with its basic functions.
|
|
77
|
|
78 By default, PGG uses GnuPG. If you are new to such a system, I
|
|
79 recommend that you should look over the GNU Privacy Handbook (GPH)
|
|
80 which is available at @uref{http://www.gnupg.org/documentation/}.
|
|
81
|
|
82 When using GnuPG, we recommend the use of the @code{gpg-agent}
|
|
83 program, which is distributed with versions 2.0 and later of GnuPG.
|
|
84 This is a daemon to manage private keys independently from any
|
|
85 protocol, and provides the most secure way to input and cache your
|
|
86 passphrases (@pxref{Caching passphrase}). By default, PGG will
|
|
87 attempt to use @code{gpg-agent} if it is running. @xref{Invoking
|
|
88 GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}.
|
|
89
|
|
90 PGG also supports Pretty Good Privacy version 2 or version 5.
|
|
91
|
|
92 @node How to use
|
|
93 @chapter How to use
|
|
94
|
|
95 The toplevel interface of this library is quite simple, and only
|
|
96 intended to use with public-key cryptographic operation.
|
|
97
|
|
98 To use PGG, evaluate following expression at the beginning of your
|
|
99 application program.
|
|
100
|
|
101 @lisp
|
|
102 (require 'pgg)
|
|
103 @end lisp
|
|
104
|
|
105 If you want to check existence of pgg.el at runtime, instead you can
|
|
106 list autoload setting for desired functions as follows.
|
|
107
|
|
108 @lisp
|
|
109 (autoload 'pgg-encrypt-region "pgg"
|
|
110 "Encrypt the current region." t)
|
|
111 (autoload 'pgg-encrypt-symmetric-region "pgg"
|
|
112 "Encrypt the current region with symmetric algorithm." t)
|
|
113 (autoload 'pgg-decrypt-region "pgg"
|
|
114 "Decrypt the current region." t)
|
|
115 (autoload 'pgg-sign-region "pgg"
|
|
116 "Sign the current region." t)
|
|
117 (autoload 'pgg-verify-region "pgg"
|
|
118 "Verify the current region." t)
|
|
119 (autoload 'pgg-insert-key "pgg"
|
|
120 "Insert the ASCII armored public key." t)
|
|
121 (autoload 'pgg-snarf-keys-region "pgg"
|
|
122 "Import public keys in the current region." t)
|
|
123 @end lisp
|
|
124
|
|
125 @menu
|
|
126 * User Commands::
|
|
127 * Selecting an implementation::
|
|
128 * Caching passphrase::
|
|
129 * Default user identity::
|
|
130 @end menu
|
|
131
|
|
132 @node User Commands
|
|
133 @section User Commands
|
|
134
|
|
135 At this time you can use some cryptographic commands. The behavior of
|
|
136 these commands relies on a fashion of invocation because they are also
|
|
137 intended to be used as library functions. In case you don't have the
|
|
138 signer's public key, for example, the function @code{pgg-verify-region}
|
|
139 fails immediately, but if the function had been called interactively, it
|
|
140 would ask you to retrieve the signer's public key from the server.
|
|
141
|
|
142 @deffn Command pgg-encrypt-region start end recipients &optional sign passphrase
|
|
143 Encrypt the current region between @var{start} and @var{end} for
|
|
144 @var{recipients}. When the function were called interactively, you
|
|
145 would be asked about the recipients.
|
|
146
|
|
147 If encryption is successful, it replaces the current region contents (in
|
|
148 the accessible portion) with the resulting data.
|
|
149
|
|
150 If optional argument @var{sign} is non-@code{nil}, the function is
|
|
151 request to do a combined sign and encrypt. This currently is
|
|
152 confirmed to work with GnuPG, but might not work with PGP or PGP5.
|
|
153
|
|
154 If optional @var{passphrase} is @code{nil}, the passphrase will be
|
|
155 obtained from the passphrase cache or user.
|
|
156 @end deffn
|
|
157
|
|
158 @deffn Command pgg-encrypt-symmetric-region &optional start end passphrase
|
|
159 Encrypt the current region between @var{start} and @var{end} using a
|
|
160 symmetric cipher. After invocation you are asked for a passphrase.
|
|
161
|
|
162 If optional @var{passphrase} is @code{nil}, the passphrase will be
|
|
163 obtained from the passphrase cache or user.
|
|
164
|
|
165 symmetric-cipher encryption is currently only implemented for GnuPG.
|
|
166 @end deffn
|
|
167
|
|
168 @deffn Command pgg-decrypt-region start end &optional passphrase
|
|
169 Decrypt the current region between @var{start} and @var{end}. If
|
|
170 decryption is successful, it replaces the current region contents (in
|
|
171 the accessible portion) with the resulting data.
|
|
172
|
|
173 If optional @var{passphrase} is @code{nil}, the passphrase will be
|
|
174 obtained from the passphrase cache or user.
|
|
175 @end deffn
|
|
176
|
|
177 @deffn Command pgg-sign-region start end &optional cleartext passphrase
|
|
178 Make the signature from text between @var{start} and @var{end}. If the
|
|
179 optional third argument @var{cleartext} is non-@code{nil}, or the
|
|
180 function is called interactively, it does not create a detached
|
|
181 signature. In such a case, it replaces the current region contents (in
|
|
182 the accessible portion) with the resulting data.
|
|
183
|
|
184 If optional @var{passphrase} is @code{nil}, the passphrase will be
|
|
185 obtained from the passphrase cache or user.
|
|
186 @end deffn
|
|
187
|
|
188 @deffn Command pgg-verify-region start end &optional signature fetch
|
|
189 Verify the current region between @var{start} and @var{end}. If the
|
|
190 optional third argument @var{signature} is non-@code{nil}, it is treated
|
|
191 as the detached signature file of the current region.
|
|
192
|
|
193 If the optional 4th argument @var{fetch} is non-@code{nil}, or the
|
|
194 function is called interactively, we attempt to fetch the signer's
|
|
195 public key from the key server.
|
|
196 @end deffn
|
|
197
|
|
198 @deffn Command pgg-insert-key
|
|
199 Retrieve the user's public key and insert it as ASCII-armored format.
|
|
200 @end deffn
|
|
201
|
|
202 @deffn Command pgg-snarf-keys-region start end
|
|
203 Collect public keys in the current region between @var{start} and
|
|
204 @var{end}, and add them into the user's keyring.
|
|
205 @end deffn
|
|
206
|
|
207 @node Selecting an implementation
|
|
208 @section Selecting an implementation
|
|
209
|
|
210 Since PGP has a long history and there are a number of PGP
|
|
211 implementations available today, the function which each one has differs
|
|
212 considerably. For example, if you are using GnuPG, you know you can
|
|
213 select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on
|
|
214 the other hand the version 2 of PGP only supports IDEA.
|
|
215
|
|
216 Which implementation is used is controlled by the @code{pgg-scheme}
|
|
217 variable. If it is @code{nil} (the default), the value of the
|
|
218 @code{pgg-default-scheme} variable will be used instead.
|
|
219
|
|
220 @defvar pgg-scheme
|
|
221 Force specify the scheme of PGP implementation. The value can be set to
|
|
222 @code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{nil}.
|
|
223 @end defvar
|
|
224
|
|
225 @defvar pgg-default-scheme
|
|
226 The default scheme of PGP implementation. The value should be one of
|
|
227 @code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{gpg}.
|
|
228 @end defvar
|
|
229
|
|
230 @node Caching passphrase
|
|
231 @section Caching passphrase
|
|
232
|
|
233 When using GnuPG (gpg) as the PGP scheme, we recommend using a program
|
|
234 called @code{gpg-agent} for entering and caching
|
|
235 passphrases@footnote{Actually, @code{gpg-agent} does not cache
|
|
236 passphrases but private keys. On the other hand, from a user's point
|
|
237 of view, this technical difference isn't visible.}.
|
|
238
|
|
239 @defvar pgg-gpg-use-agent
|
|
240 If non-@code{nil}, attempt to use @code{gpg-agent} whenever possible.
|
|
241 The default is @code{t}. If @code{gpg-agent} is not running, or GnuPG
|
|
242 is not the current PGP scheme, PGG's own passphrase-caching mechanism
|
|
243 is used (see below).
|
|
244 @end defvar
|
|
245
|
|
246 To use @code{gpg-agent} with PGG, you must first ensure that
|
|
247 @code{gpg-agent} is running. For example, if you are running in the X
|
|
248 Window System, you can do this by putting the following line in your
|
|
249 @file{.xsession} file:
|
|
250
|
|
251 @smallexample
|
|
252 eval "$(gpg-agent --daemon)"
|
|
253 @end smallexample
|
|
254
|
|
255 For more details on invoking @code{gpg-agent}, @xref{Invoking
|
|
256 GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}.
|
|
257
|
|
258 Whenever you perform a PGG operation that requires a GnuPG passphrase,
|
|
259 GnuPG will contact @code{gpg-agent}, which prompts you for the
|
|
260 passphrase. Furthermore, @code{gpg-agent} ``caches'' the result, so
|
|
261 that subsequent uses will not require you to enter the passphrase
|
|
262 again. (This cache usually expires after a certain time has passed;
|
|
263 you can change this using the @code{--default-cache-ttl} option when
|
|
264 invoking @code{gpg-agent}.)
|
|
265
|
|
266 If you are running in a X Window System environment, @code{gpg-agent}
|
|
267 prompts for a passphrase by opening a graphical window. However, if
|
|
268 you are running Emacs on a text terminal, @code{gpg-agent} has trouble
|
|
269 receiving input from the terminal, since it is being sent to Emacs.
|
|
270 One workaround for this problem is to run @code{gpg-agent} on a
|
|
271 different terminal from Emacs, with the @code{--keep-tty} option; this
|
|
272 tells @code{gpg-agent} use its own terminal to prompt for passphrases.
|
|
273
|
|
274 When @code{gpg-agent} is not being used, PGG prompts for a passphrase
|
|
275 through Emacs. It also has its own passphrase caching mechanism,
|
|
276 which is controlled by the variable @code{pgg-cache-passphrase} (see
|
|
277 below).
|
|
278
|
|
279 There is a security risk in handling passphrases through PGG rather
|
|
280 than @code{gpg-agent}. When you enter your passphrase into an Emacs
|
|
281 prompt, it is temporarily stored as a cleartext string in the memory
|
|
282 of the Emacs executable. If the executable memory is swapped to disk,
|
|
283 the root user can, in theory, extract the passphrase from the
|
|
284 swapfile. Furthermore, the swapfile containing the cleartext
|
|
285 passphrase might remain on the disk after the system is discarded or
|
|
286 stolen. @code{gpg-agent} avoids this problem by using certain tricks,
|
|
287 such as memory locking, which have not been implemented in Emacs.
|
|
288
|
|
289 @defvar pgg-cache-passphrase
|
|
290 If non-@code{nil}, store passphrases. The default value of this
|
|
291 variable is @code{t}. If you are worried about security issues,
|
|
292 however, you could stop the caching of passphrases by setting this
|
|
293 variable to @code{nil}.
|
|
294 @end defvar
|
|
295
|
|
296 @defvar pgg-passphrase-cache-expiry
|
|
297 Elapsed time for expiration in seconds.
|
|
298 @end defvar
|
|
299
|
|
300 If your passphrase contains non-ASCII characters, you might need to
|
|
301 specify the coding system to be used to encode your passphrases, since
|
|
302 GnuPG treats them as a byte sequence, not as a character sequence.
|
|
303
|
|
304 @defvar pgg-passphrase-coding-system
|
|
305 Coding system used to encode passphrase.
|
|
306 @end defvar
|
|
307
|
|
308 @node Default user identity
|
|
309 @section Default user identity
|
|
310
|
|
311 The PGP implementation is usually able to select the proper key to use
|
|
312 for signing and decryption, but if you have more than one key, you may
|
|
313 need to specify the key id to use.
|
|
314
|
|
315 @defvar pgg-default-user-id
|
|
316 User ID of your default identity. It defaults to the value returned
|
|
317 by @samp{(user-login-name)}. You can customize this variable.
|
|
318 @end defvar
|
|
319
|
|
320 @defvar pgg-gpg-user-id
|
|
321 User ID of the GnuPG default identity. It defaults to @samp{nil}.
|
|
322 This overrides @samp{pgg-default-user-id}. You can customize this
|
|
323 variable.
|
|
324 @end defvar
|
|
325
|
|
326 @defvar pgg-pgp-user-id
|
|
327 User ID of the PGP 2.x/6.x default identity. It defaults to
|
|
328 @samp{nil}. This overrides @samp{pgg-default-user-id}. You can
|
|
329 customize this variable.
|
|
330 @end defvar
|
|
331
|
|
332 @defvar pgg-pgp5-user-id
|
|
333 User ID of the PGP 5.x default identity. It defaults to @samp{nil}.
|
|
334 This overrides @samp{pgg-default-user-id}. You can customize this
|
|
335 variable.
|
|
336 @end defvar
|
|
337
|
|
338 @node Architecture
|
|
339 @chapter Architecture
|
|
340
|
|
341 PGG introduces the notion of a "scheme of PGP implementation" (used
|
|
342 interchangeably with "scheme" in this document). This term refers to a
|
|
343 singleton object wrapped with the luna object system.
|
|
344
|
|
345 Since PGG was designed for accessing and developing PGP functionality,
|
|
346 the architecture had to be designed not just for interoperability but
|
|
347 also for extensiblity. In this chapter we explore the architecture
|
85712
|
348 while finding out how to write the PGG back end.
|
84310
|
349
|
|
350 @menu
|
|
351 * Initializing::
|
85712
|
352 * Back end methods::
|
84310
|
353 * Getting output::
|
|
354 @end menu
|
|
355
|
|
356 @node Initializing
|
|
357 @section Initializing
|
|
358
|
|
359 A scheme must be initialized before it is used.
|
|
360 It had better guarantee to keep only one instance of a scheme.
|
|
361
|
|
362 The following code is snipped out of @file{pgg-gpg.el}. Once an
|
|
363 instance of @code{pgg-gpg} scheme is initialized, it's stored to the
|
|
364 variable @code{pgg-scheme-gpg-instance} and will be reused from now on.
|
|
365
|
|
366 @lisp
|
|
367 (defvar pgg-scheme-gpg-instance nil)
|
|
368
|
|
369 (defun pgg-make-scheme-gpg ()
|
|
370 (or pgg-scheme-gpg-instance
|
|
371 (setq pgg-scheme-gpg-instance
|
|
372 (luna-make-entity 'pgg-scheme-gpg))))
|
|
373 @end lisp
|
|
374
|
|
375 The name of the function must follow the
|
85712
|
376 regulation---@code{pgg-make-scheme-} follows the back end name.
|
84310
|
377
|
85712
|
378 @node Back end methods
|
|
379 @section Back end methods
|
84310
|
380
|
85712
|
381 In each back end, these methods must be present. The output of these
|
84310
|
382 methods is stored in special buffers (@ref{Getting output}), so that
|
|
383 these methods must tell the status of the execution.
|
|
384
|
|
385 @deffn Method pgg-scheme-lookup-key scheme string &optional type
|
|
386 Return keys associated with @var{string}. If the optional third
|
|
387 argument @var{type} is non-@code{nil}, it searches from the secret
|
|
388 keyrings.
|
|
389 @end deffn
|
|
390
|
|
391 @deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign passphrase
|
|
392 Encrypt the current region between @var{start} and @var{end} for
|
|
393 @var{recipients}. If @var{sign} is non-@code{nil}, do a combined sign
|
|
394 and encrypt. If encryption is successful, it returns @code{t},
|
|
395 otherwise @code{nil}.
|
|
396 @end deffn
|
|
397
|
|
398 @deffn Method pgg-scheme-encrypt-symmetric-region scheme start end &optional passphrase
|
|
399 Encrypt the current region between @var{start} and @var{end} using a
|
|
400 symmetric cipher and a passphrases. If encryption is successful, it
|
|
401 returns @code{t}, otherwise @code{nil}. This function is currently only
|
|
402 implemented for GnuPG.
|
|
403 @end deffn
|
|
404
|
|
405 @deffn Method pgg-scheme-decrypt-region scheme start end &optional passphrase
|
|
406 Decrypt the current region between @var{start} and @var{end}. If
|
|
407 decryption is successful, it returns @code{t}, otherwise @code{nil}.
|
|
408 @end deffn
|
|
409
|
|
410 @deffn Method pgg-scheme-sign-region scheme start end &optional cleartext passphrase
|
|
411 Make the signature from text between @var{start} and @var{end}. If the
|
|
412 optional third argument @var{cleartext} is non-@code{nil}, it does not
|
|
413 create a detached signature. If signing is successful, it returns
|
|
414 @code{t}, otherwise @code{nil}.
|
|
415 @end deffn
|
|
416
|
|
417 @deffn Method pgg-scheme-verify-region scheme start end &optional signature
|
|
418 Verify the current region between @var{start} and @var{end}. If the
|
|
419 optional third argument @var{signature} is non-@code{nil}, it is treated
|
|
420 as the detached signature of the current region. If the signature is
|
|
421 successfully verified, it returns @code{t}, otherwise @code{nil}.
|
|
422 @end deffn
|
|
423
|
|
424 @deffn Method pgg-scheme-insert-key scheme
|
|
425 Retrieve the user's public key and insert it as ASCII-armored format.
|
|
426 On success, it returns @code{t}, otherwise @code{nil}.
|
|
427 @end deffn
|
|
428
|
|
429 @deffn Method pgg-scheme-snarf-keys-region scheme start end
|
|
430 Collect public keys in the current region between @var{start} and
|
|
431 @var{end}, and add them into the user's keyring.
|
|
432 On success, it returns @code{t}, otherwise @code{nil}.
|
|
433 @end deffn
|
|
434
|
|
435 @node Getting output
|
|
436 @section Getting output
|
|
437
|
85712
|
438 The output of the back end methods (@ref{Back end methods}) is stored in
|
84310
|
439 special buffers, so that these methods must tell the status of the
|
|
440 execution.
|
|
441
|
|
442 @defvar pgg-errors-buffer
|
|
443 The standard error output of the execution of the PGP command is stored
|
|
444 here.
|
|
445 @end defvar
|
|
446
|
|
447 @defvar pgg-output-buffer
|
|
448 The standard output of the execution of the PGP command is stored here.
|
|
449 @end defvar
|
|
450
|
|
451 @defvar pgg-status-buffer
|
|
452 The rest of status information of the execution of the PGP command is
|
|
453 stored here.
|
|
454 @end defvar
|
|
455
|
|
456 @node Parsing OpenPGP packets
|
|
457 @chapter Parsing OpenPGP packets
|
|
458
|
|
459 The format of OpenPGP messages is maintained in order to publish all
|
|
460 necessary information needed to develop interoperable applications.
|
|
461 The standard is documented in RFC 2440.
|
|
462
|
|
463 PGG has its own parser for the OpenPGP packets.
|
|
464
|
|
465 @defun pgg-parse-armor string
|
|
466 List the sequence of packets in @var{string}.
|
|
467 @end defun
|
|
468
|
|
469 @defun pgg-parse-armor-region start end
|
|
470 List the sequence of packets in the current region between @var{start}
|
|
471 and @var{end}.
|
|
472 @end defun
|
|
473
|
|
474 @defvar pgg-ignore-packet-checksum
|
|
475 If non-@code{nil}, don't check the checksum of the packets.
|
|
476 @end defvar
|
|
477
|
|
478 @node GNU Free Documentation License
|
|
479 @appendix GNU Free Documentation License
|
|
480 @include doclicense.texi
|
|
481
|
|
482 @node Function Index
|
|
483 @unnumbered Function Index
|
|
484 @printindex fn
|
|
485
|
|
486 @node Variable Index
|
|
487 @unnumbered Variable Index
|
|
488 @printindex vr
|
|
489
|
|
490 @summarycontents
|
|
491 @contents
|
|
492 @bye
|
|
493
|
|
494 @c End:
|
|
495
|
|
496 @ignore
|
|
497 arch-tag: 0c205838-34b9-41a5-b9d7-49ae57ccac85
|
|
498 @end ignore
|