Mercurial > emacs
annotate doc/misc/pgg.texi @ 85940:3885b7dccf03
*** empty log message ***
author | Juanma Barranquero <lekktu@gmail.com> |
---|---|
date | Tue, 06 Nov 2007 11:23:36 +0000 |
parents | a3c27999decb |
children | 5d58981e6690 |
rev | line source |
---|---|
84310 | 1 \input texinfo @c -*-texinfo-*- |
2 | |
84329
3d431f1997d8
(setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents:
84310
diff
changeset
|
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 | |
11 Copyright @copyright{} 2001, 2003, 2004, 2005, 2006, 2007 Free Software | |
12 Foundation, Inc. | |
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
a3c27999decb
Update Gnus to No Gnus 0.7 from the Gnus CVS trunk
Miles Bader <miles@gnu.org>
parents:
84329
diff
changeset
|
348 while finding out how to write the PGG back end. |
84310 | 349 |
350 @menu | |
351 * Initializing:: | |
85712
a3c27999decb
Update Gnus to No Gnus 0.7 from the Gnus CVS trunk
Miles Bader <miles@gnu.org>
parents:
84329
diff
changeset
|
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
a3c27999decb
Update Gnus to No Gnus 0.7 from the Gnus CVS trunk
Miles Bader <miles@gnu.org>
parents:
84329
diff
changeset
|
376 regulation---@code{pgg-make-scheme-} follows the back end name. |
84310 | 377 |
85712
a3c27999decb
Update Gnus to No Gnus 0.7 from the Gnus CVS trunk
Miles Bader <miles@gnu.org>
parents:
84329
diff
changeset
|
378 @node Back end methods |
a3c27999decb
Update Gnus to No Gnus 0.7 from the Gnus CVS trunk
Miles Bader <miles@gnu.org>
parents:
84329
diff
changeset
|
379 @section Back end methods |
84310 | 380 |
85712
a3c27999decb
Update Gnus to No Gnus 0.7 from the Gnus CVS trunk
Miles Bader <miles@gnu.org>
parents:
84329
diff
changeset
|
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
a3c27999decb
Update Gnus to No Gnus 0.7 from the Gnus CVS trunk
Miles Bader <miles@gnu.org>
parents:
84329
diff
changeset
|
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 |