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