1 \input texinfo @c -*-texinfo-*-
4 @settitle PGG @value{VERSION}
9 This file describes PGG @value{VERSION}, an Emacs interface to various
12 Copyright @copyright{} 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
13 2010 Free Software Foundation, Inc.
16 Permission is granted to copy, distribute and/or modify this document
17 under the terms of the GNU Free Documentation License, Version 1.3 or
18 any later version published by the Free Software Foundation; with no
19 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
20 and with the Back-Cover Texts as in (a) below. A copy of the license
21 is included in the section entitled ``GNU Free Documentation License.''
23 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
24 modify this GNU manual. Buying copies from the FSF supports it in
25 developing GNU and promoting software freedom.''
31 * PGG: (pgg). Emacs interface to various PGP implementations.
40 @vskip 0pt plus 1filll
49 PGG is an interface library between Emacs
50 and various tools for secure communication. PGG also provides a simple
51 user interface to encrypt, decrypt, sign, and verify MIME messages.
58 * Overview:: What PGG is.
59 * Prerequisites:: Complicated stuff you may have to do.
60 * How to use:: Getting started quickly.
62 * Parsing OpenPGP packets::
63 * GNU Free Documentation License:: The license for this documentation.
71 PGG is an interface library between Emacs and various tools for secure
72 communication. Even though Mailcrypt has similar feature, it does not
73 deal with detached PGP messages, normally used in PGP/MIME
74 infrastructure. This was the main reason why I wrote the new library.
76 PGP/MIME is an application of MIME Object Security Services (RFC1848).
77 The standard is documented in RFC2015.
80 @chapter Prerequisites
82 PGG requires at least one implementation of privacy guard system.
83 This document assumes that you have already obtained and installed them
84 and that you are familiar with its basic functions.
86 By default, PGG uses GnuPG. If you are new to such a system, I
87 recommend that you should look over the GNU Privacy Handbook (GPH)
88 which is available at @uref{http://www.gnupg.org/documentation/}.
90 When using GnuPG, we recommend the use of the @code{gpg-agent}
91 program, which is distributed with versions 2.0 and later of GnuPG.
92 This is a daemon to manage private keys independently from any
93 protocol, and provides the most secure way to input and cache your
94 passphrases (@pxref{Caching passphrase}). By default, PGG will
95 attempt to use @code{gpg-agent} if it is running. @xref{Invoking
96 GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}.
98 PGG also supports Pretty Good Privacy version 2 or version 5.
103 The toplevel interface of this library is quite simple, and only
104 intended to use with public-key cryptographic operation.
106 To use PGG, evaluate following expression at the beginning of your
113 If you want to check existence of pgg.el at runtime, instead you can
114 list autoload setting for desired functions as follows.
117 (autoload 'pgg-encrypt-region "pgg"
118 "Encrypt the current region." t)
119 (autoload 'pgg-encrypt-symmetric-region "pgg"
120 "Encrypt the current region with symmetric algorithm." t)
121 (autoload 'pgg-decrypt-region "pgg"
122 "Decrypt the current region." t)
123 (autoload 'pgg-sign-region "pgg"
124 "Sign the current region." t)
125 (autoload 'pgg-verify-region "pgg"
126 "Verify the current region." t)
127 (autoload 'pgg-insert-key "pgg"
128 "Insert the ASCII armored public key." t)
129 (autoload 'pgg-snarf-keys-region "pgg"
130 "Import public keys in the current region." t)
135 * Selecting an implementation::
136 * Caching passphrase::
137 * Default user identity::
141 @section User Commands
143 At this time you can use some cryptographic commands. The behavior of
144 these commands relies on a fashion of invocation because they are also
145 intended to be used as library functions. In case you don't have the
146 signer's public key, for example, the function @code{pgg-verify-region}
147 fails immediately, but if the function had been called interactively, it
148 would ask you to retrieve the signer's public key from the server.
150 @deffn Command pgg-encrypt-region start end recipients &optional sign passphrase
151 Encrypt the current region between @var{start} and @var{end} for
152 @var{recipients}. When the function were called interactively, you
153 would be asked about the recipients.
155 If encryption is successful, it replaces the current region contents (in
156 the accessible portion) with the resulting data.
158 If optional argument @var{sign} is non-@code{nil}, the function is
159 request to do a combined sign and encrypt. This currently is
160 confirmed to work with GnuPG, but might not work with PGP or PGP5.
162 If optional @var{passphrase} is @code{nil}, the passphrase will be
163 obtained from the passphrase cache or user.
166 @deffn Command pgg-encrypt-symmetric-region &optional start end passphrase
167 Encrypt the current region between @var{start} and @var{end} using a
168 symmetric cipher. After invocation you are asked for a passphrase.
170 If optional @var{passphrase} is @code{nil}, the passphrase will be
171 obtained from the passphrase cache or user.
173 symmetric-cipher encryption is currently only implemented for GnuPG.
176 @deffn Command pgg-decrypt-region start end &optional passphrase
177 Decrypt the current region between @var{start} and @var{end}. If
178 decryption is successful, it replaces the current region contents (in
179 the accessible portion) with the resulting data.
181 If optional @var{passphrase} is @code{nil}, the passphrase will be
182 obtained from the passphrase cache or user.
185 @deffn Command pgg-sign-region start end &optional cleartext passphrase
186 Make the signature from text between @var{start} and @var{end}. If the
187 optional third argument @var{cleartext} is non-@code{nil}, or the
188 function is called interactively, it does not create a detached
189 signature. In such a case, it replaces the current region contents (in
190 the accessible portion) with the resulting data.
192 If optional @var{passphrase} is @code{nil}, the passphrase will be
193 obtained from the passphrase cache or user.
196 @deffn Command pgg-verify-region start end &optional signature fetch
197 Verify the current region between @var{start} and @var{end}. If the
198 optional third argument @var{signature} is non-@code{nil}, it is treated
199 as the detached signature file of the current region.
201 If the optional 4th argument @var{fetch} is non-@code{nil}, or the
202 function is called interactively, we attempt to fetch the signer's
203 public key from the key server.
206 @deffn Command pgg-insert-key
207 Retrieve the user's public key and insert it as ASCII-armored format.
210 @deffn Command pgg-snarf-keys-region start end
211 Collect public keys in the current region between @var{start} and
212 @var{end}, and add them into the user's keyring.
215 @node Selecting an implementation
216 @section Selecting an implementation
218 Since PGP has a long history and there are a number of PGP
219 implementations available today, the function which each one has differs
220 considerably. For example, if you are using GnuPG, you know you can
221 select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on
222 the other hand the version 2 of PGP only supports IDEA.
224 Which implementation is used is controlled by the @code{pgg-scheme}
225 variable. If it is @code{nil} (the default), the value of the
226 @code{pgg-default-scheme} variable will be used instead.
229 Force specify the scheme of PGP implementation. The value can be set to
230 @code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{nil}.
233 @defvar pgg-default-scheme
234 The default scheme of PGP implementation. The value should be one of
235 @code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{gpg}.
238 @node Caching passphrase
239 @section Caching passphrase
241 When using GnuPG (gpg) as the PGP scheme, we recommend using a program
242 called @code{gpg-agent} for entering and caching
243 passphrases@footnote{Actually, @code{gpg-agent} does not cache
244 passphrases but private keys. On the other hand, from a user's point
245 of view, this technical difference isn't visible.}.
247 @defvar pgg-gpg-use-agent
248 If non-@code{nil}, attempt to use @code{gpg-agent} whenever possible.
249 The default is @code{t}. If @code{gpg-agent} is not running, or GnuPG
250 is not the current PGP scheme, PGG's own passphrase-caching mechanism
254 To use @code{gpg-agent} with PGG, you must first ensure that
255 @code{gpg-agent} is running. For example, if you are running in the X
256 Window System, you can do this by putting the following line in your
257 @file{.xsession} file:
260 eval "$(gpg-agent --daemon)"
263 For more details on invoking @code{gpg-agent}, @xref{Invoking
264 GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}.
266 Whenever you perform a PGG operation that requires a GnuPG passphrase,
267 GnuPG will contact @code{gpg-agent}, which prompts you for the
268 passphrase. Furthermore, @code{gpg-agent} ``caches'' the result, so
269 that subsequent uses will not require you to enter the passphrase
270 again. (This cache usually expires after a certain time has passed;
271 you can change this using the @code{--default-cache-ttl} option when
272 invoking @code{gpg-agent}.)
274 If you are running in a X Window System environment, @code{gpg-agent}
275 prompts for a passphrase by opening a graphical window. However, if
276 you are running Emacs on a text terminal, @code{gpg-agent} has trouble
277 receiving input from the terminal, since it is being sent to Emacs.
278 One workaround for this problem is to run @code{gpg-agent} on a
279 different terminal from Emacs, with the @code{--keep-tty} option; this
280 tells @code{gpg-agent} use its own terminal to prompt for passphrases.
282 When @code{gpg-agent} is not being used, PGG prompts for a passphrase
283 through Emacs. It also has its own passphrase caching mechanism,
284 which is controlled by the variable @code{pgg-cache-passphrase} (see
287 There is a security risk in handling passphrases through PGG rather
288 than @code{gpg-agent}. When you enter your passphrase into an Emacs
289 prompt, it is temporarily stored as a cleartext string in the memory
290 of the Emacs executable. If the executable memory is swapped to disk,
291 the root user can, in theory, extract the passphrase from the
292 swapfile. Furthermore, the swapfile containing the cleartext
293 passphrase might remain on the disk after the system is discarded or
294 stolen. @code{gpg-agent} avoids this problem by using certain tricks,
295 such as memory locking, which have not been implemented in Emacs.
297 @defvar pgg-cache-passphrase
298 If non-@code{nil}, store passphrases. The default value of this
299 variable is @code{t}. If you are worried about security issues,
300 however, you could stop the caching of passphrases by setting this
301 variable to @code{nil}.
304 @defvar pgg-passphrase-cache-expiry
305 Elapsed time for expiration in seconds.
308 If your passphrase contains non-ASCII characters, you might need to
309 specify the coding system to be used to encode your passphrases, since
310 GnuPG treats them as a byte sequence, not as a character sequence.
312 @defvar pgg-passphrase-coding-system
313 Coding system used to encode passphrase.
316 @node Default user identity
317 @section Default user identity
319 The PGP implementation is usually able to select the proper key to use
320 for signing and decryption, but if you have more than one key, you may
321 need to specify the key id to use.
323 @defvar pgg-default-user-id
324 User ID of your default identity. It defaults to the value returned
325 by @samp{(user-login-name)}. You can customize this variable.
328 @defvar pgg-gpg-user-id
329 User ID of the GnuPG default identity. It defaults to @samp{nil}.
330 This overrides @samp{pgg-default-user-id}. You can customize this
334 @defvar pgg-pgp-user-id
335 User ID of the PGP 2.x/6.x default identity. It defaults to
336 @samp{nil}. This overrides @samp{pgg-default-user-id}. You can
337 customize this variable.
340 @defvar pgg-pgp5-user-id
341 User ID of the PGP 5.x default identity. It defaults to @samp{nil}.
342 This overrides @samp{pgg-default-user-id}. You can customize this
347 @chapter Architecture
349 PGG introduces the notion of a "scheme of PGP implementation" (used
350 interchangeably with "scheme" in this document). This term refers to a
351 singleton object wrapped with the luna object system.
353 Since PGG was designed for accessing and developing PGP functionality,
354 the architecture had to be designed not just for interoperability but
355 also for extensiblity. In this chapter we explore the architecture
356 while finding out how to write the PGG back end.
365 @section Initializing
367 A scheme must be initialized before it is used.
368 It had better guarantee to keep only one instance of a scheme.
370 The following code is snipped out of @file{pgg-gpg.el}. Once an
371 instance of @code{pgg-gpg} scheme is initialized, it's stored to the
372 variable @code{pgg-scheme-gpg-instance} and will be reused from now on.
375 (defvar pgg-scheme-gpg-instance nil)
377 (defun pgg-make-scheme-gpg ()
378 (or pgg-scheme-gpg-instance
379 (setq pgg-scheme-gpg-instance
380 (luna-make-entity 'pgg-scheme-gpg))))
383 The name of the function must follow the
384 regulation---@code{pgg-make-scheme-} follows the back end name.
386 @node Back end methods
387 @section Back end methods
389 In each back end, these methods must be present. The output of these
390 methods is stored in special buffers (@ref{Getting output}), so that
391 these methods must tell the status of the execution.
393 @deffn Method pgg-scheme-lookup-key scheme string &optional type
394 Return keys associated with @var{string}. If the optional third
395 argument @var{type} is non-@code{nil}, it searches from the secret
399 @deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign passphrase
400 Encrypt the current region between @var{start} and @var{end} for
401 @var{recipients}. If @var{sign} is non-@code{nil}, do a combined sign
402 and encrypt. If encryption is successful, it returns @code{t},
403 otherwise @code{nil}.
406 @deffn Method pgg-scheme-encrypt-symmetric-region scheme start end &optional passphrase
407 Encrypt the current region between @var{start} and @var{end} using a
408 symmetric cipher and a passphrases. If encryption is successful, it
409 returns @code{t}, otherwise @code{nil}. This function is currently only
410 implemented for GnuPG.
413 @deffn Method pgg-scheme-decrypt-region scheme start end &optional passphrase
414 Decrypt the current region between @var{start} and @var{end}. If
415 decryption is successful, it returns @code{t}, otherwise @code{nil}.
418 @deffn Method pgg-scheme-sign-region scheme start end &optional cleartext passphrase
419 Make the signature from text between @var{start} and @var{end}. If the
420 optional third argument @var{cleartext} is non-@code{nil}, it does not
421 create a detached signature. If signing is successful, it returns
422 @code{t}, otherwise @code{nil}.
425 @deffn Method pgg-scheme-verify-region scheme start end &optional signature
426 Verify the current region between @var{start} and @var{end}. If the
427 optional third argument @var{signature} is non-@code{nil}, it is treated
428 as the detached signature of the current region. If the signature is
429 successfully verified, it returns @code{t}, otherwise @code{nil}.
432 @deffn Method pgg-scheme-insert-key scheme
433 Retrieve the user's public key and insert it as ASCII-armored format.
434 On success, it returns @code{t}, otherwise @code{nil}.
437 @deffn Method pgg-scheme-snarf-keys-region scheme start end
438 Collect public keys in the current region between @var{start} and
439 @var{end}, and add them into the user's keyring.
440 On success, it returns @code{t}, otherwise @code{nil}.
444 @section Getting output
446 The output of the back end methods (@ref{Back end methods}) is stored in
447 special buffers, so that these methods must tell the status of the
450 @defvar pgg-errors-buffer
451 The standard error output of the execution of the PGP command is stored
455 @defvar pgg-output-buffer
456 The standard output of the execution of the PGP command is stored here.
459 @defvar pgg-status-buffer
460 The rest of status information of the execution of the PGP command is
464 @node Parsing OpenPGP packets
465 @chapter Parsing OpenPGP packets
467 The format of OpenPGP messages is maintained in order to publish all
468 necessary information needed to develop interoperable applications.
469 The standard is documented in RFC 2440.
471 PGG has its own parser for the OpenPGP packets.
473 @defun pgg-parse-armor string
474 List the sequence of packets in @var{string}.
477 @defun pgg-parse-armor-region start end
478 List the sequence of packets in the current region between @var{start}
482 @defvar pgg-ignore-packet-checksum
483 If non-@code{nil}, don't check the checksum of the packets.
486 @node GNU Free Documentation License
487 @appendix GNU Free Documentation License
488 @include doclicense.texi
491 @unnumbered Function Index
495 @unnumbered Variable Index