1 \input texinfo @c -*-texinfo-*-
3 @setfilename ../info/pgg
9 This file describes PGG, an Emacs interface to various PGP implementations.
11 Copyright @copyright{} 2001, 2003, 2004, 2005, 2006, 2007 Free Software
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.''
26 * PGG: (pgg). Emacs interface to various PGP implementations.
29 @settitle PGG @value{VERSION}
38 @vskip 0pt plus 1filll
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.
50 * Overview:: What PGG is.
51 * Prerequisites:: Complicated stuff you may have to do.
52 * How to use:: Getting started quickly.
54 * Parsing OpenPGP packets::
62 PGG is an interface library between Emacs and various tools for secure
63 communication. Even though Mailcrypt has similar feature, it does not
64 deal with detached PGP messages, normally used in PGP/MIME
65 infrastructure. This was the main reason why I wrote the new library.
67 PGP/MIME is an application of MIME Object Security Services (RFC1848).
68 The standard is documented in RFC2015.
71 @chapter Prerequisites
73 PGG requires at least one implementation of privacy guard system.
74 This document assumes that you have already obtained and installed them
75 and that you are familiar with its basic functions.
77 By default, PGG uses GnuPG. If you are new to such a system, I
78 recommend that you should look over the GNU Privacy Handbook (GPH)
79 which is available at @uref{http://www.gnupg.org/documentation/}.
81 When using GnuPG, we recommend the use of the @code{gpg-agent}
82 program, which is distributed with versions 2.0 and later of GnuPG.
83 This is a daemon to manage private keys independently from any
84 protocol, and provides the most secure way to input and cache your
85 passphrases (@pxref{Caching passphrase}). By default, PGG will
86 attempt to use @code{gpg-agent} if it is running. @xref{Invoking
87 GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}.
89 PGG also supports Pretty Good Privacy version 2 or version 5.
94 The toplevel interface of this library is quite simple, and only
95 intended to use with public-key cryptographic operation.
97 To use PGG, evaluate following expression at the beginning of your
104 If you want to check existence of pgg.el at runtime, instead you can
105 list autoload setting for desired functions as follows.
108 (autoload 'pgg-encrypt-region "pgg"
109 "Encrypt the current region." t)
110 (autoload 'pgg-encrypt-symmetric-region "pgg"
111 "Encrypt the current region with symmetric algorithm." t)
112 (autoload 'pgg-decrypt-region "pgg"
113 "Decrypt the current region." t)
114 (autoload 'pgg-sign-region "pgg"
115 "Sign the current region." t)
116 (autoload 'pgg-verify-region "pgg"
117 "Verify the current region." t)
118 (autoload 'pgg-insert-key "pgg"
119 "Insert the ASCII armored public key." t)
120 (autoload 'pgg-snarf-keys-region "pgg"
121 "Import public keys in the current region." t)
126 * Selecting an implementation::
127 * Caching passphrase::
128 * Default user identity::
132 @section User Commands
134 At this time you can use some cryptographic commands. The behavior of
135 these commands relies on a fashion of invocation because they are also
136 intended to be used as library functions. In case you don't have the
137 signer's public key, for example, the function @code{pgg-verify-region}
138 fails immediately, but if the function had been called interactively, it
139 would ask you to retrieve the signer's public key from the server.
141 @deffn Command pgg-encrypt-region start end recipients &optional sign passphrase
142 Encrypt the current region between @var{start} and @var{end} for
143 @var{recipients}. When the function were called interactively, you
144 would be asked about the recipients.
146 If encryption is successful, it replaces the current region contents (in
147 the accessible portion) with the resulting data.
149 If optional argument @var{sign} is non-@code{nil}, the function is
150 request to do a combined sign and encrypt. This currently is
151 confirmed to work with GnuPG, but might not work with PGP or PGP5.
153 If optional @var{passphrase} is @code{nil}, the passphrase will be
154 obtained from the passphrase cache or user.
157 @deffn Command pgg-encrypt-symmetric-region &optional start end passphrase
158 Encrypt the current region between @var{start} and @var{end} using a
159 symmetric cipher. After invocation you are asked for a passphrase.
161 If optional @var{passphrase} is @code{nil}, the passphrase will be
162 obtained from the passphrase cache or user.
164 symmetric-cipher encryption is currently only implemented for GnuPG.
167 @deffn Command pgg-decrypt-region start end &optional passphrase
168 Decrypt the current region between @var{start} and @var{end}. If
169 decryption is successful, it replaces the current region contents (in
170 the accessible portion) with the resulting data.
172 If optional @var{passphrase} is @code{nil}, the passphrase will be
173 obtained from the passphrase cache or user.
176 @deffn Command pgg-sign-region start end &optional cleartext passphrase
177 Make the signature from text between @var{start} and @var{end}. If the
178 optional third argument @var{cleartext} is non-@code{nil}, or the
179 function is called interactively, it does not create a detached
180 signature. In such a case, it replaces the current region contents (in
181 the accessible portion) with the resulting data.
183 If optional @var{passphrase} is @code{nil}, the passphrase will be
184 obtained from the passphrase cache or user.
187 @deffn Command pgg-verify-region start end &optional signature fetch
188 Verify the current region between @var{start} and @var{end}. If the
189 optional third argument @var{signature} is non-@code{nil}, it is treated
190 as the detached signature file of the current region.
192 If the optional 4th argument @var{fetch} is non-@code{nil}, or the
193 function is called interactively, we attempt to fetch the signer's
194 public key from the key server.
197 @deffn Command pgg-insert-key
198 Retrieve the user's public key and insert it as ASCII-armored format.
201 @deffn Command pgg-snarf-keys-region start end
202 Collect public keys in the current region between @var{start} and
203 @var{end}, and add them into the user's keyring.
206 @node Selecting an implementation
207 @section Selecting an implementation
209 Since PGP has a long history and there are a number of PGP
210 implementations available today, the function which each one has differs
211 considerably. For example, if you are using GnuPG, you know you can
212 select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on
213 the other hand the version 2 of PGP only supports IDEA.
215 Which implementation is used is controlled by the @code{pgg-scheme}
216 variable. If it is @code{nil} (the default), the value of the
217 @code{pgg-default-scheme} variable will be used instead.
220 Force specify the scheme of PGP implementation. The value can be set to
221 @code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{nil}.
224 @defvar pgg-default-scheme
225 The default scheme of PGP implementation. The value should be one of
226 @code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{gpg}.
229 @node Caching passphrase
230 @section Caching passphrase
232 When using GnuPG (gpg) as the PGP scheme, we recommend using a program
233 called @code{gpg-agent} for entering and caching
234 passphrases@footnote{Actually, @code{gpg-agent} does not cache
235 passphrases but private keys. On the other hand, from a user's point
236 of view, this technical difference isn't visible.}.
238 @defvar pgg-gpg-use-agent
239 If non-@code{nil}, attempt to use @code{gpg-agent} whenever possible.
240 The default is @code{t}. If @code{gpg-agent} is not running, or GnuPG
241 is not the current PGP scheme, PGG's own passphrase-caching mechanism
245 To use @code{gpg-agent} with PGG, you must first ensure that
246 @code{gpg-agent} is running. For example, if you are running in the X
247 Window System, you can do this by putting the following line in your
248 @file{.xsession} file:
251 eval "$(gpg-agent --daemon)"
254 For more details on invoking @code{gpg-agent}, @xref{Invoking
255 GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}.
257 Whenever you perform a PGG operation that requires a GnuPG passphrase,
258 GnuPG will contact @code{gpg-agent}, which prompts you for the
259 passphrase. Furthermore, @code{gpg-agent} ``caches'' the result, so
260 that subsequent uses will not require you to enter the passphrase
261 again. (This cache usually expires after a certain time has passed;
262 you can change this using the @code{--default-cache-ttl} option when
263 invoking @code{gpg-agent}.)
265 If you are running in a X Window System environment, @code{gpg-agent}
266 prompts for a passphrase by opening a graphical window. However, if
267 you are running Emacs on a text terminal, @code{gpg-agent} has trouble
268 receiving input from the terminal, since it is being sent to Emacs.
269 One workaround for this problem is to run @code{gpg-agent} on a
270 different terminal from Emacs, with the @code{--keep-tty} option; this
271 tells @code{gpg-agent} use its own terminal to prompt for passphrases.
273 When @code{gpg-agent} is not being used, PGG prompts for a passphrase
274 through Emacs. It also has its own passphrase caching mechanism,
275 which is controlled by the variable @code{pgg-cache-passphrase} (see
278 There is a security risk in handling passphrases through PGG rather
279 than @code{gpg-agent}. When you enter your passphrase into an Emacs
280 prompt, it is temporarily stored as a cleartext string in the memory
281 of the Emacs executable. If the executable memory is swapped to disk,
282 the root user can, in theory, extract the passphrase from the
283 swapfile. Furthermore, the swapfile containing the cleartext
284 passphrase might remain on the disk after the system is discarded or
285 stolen. @code{gpg-agent} avoids this problem by using certain tricks,
286 such as memory locking, which have not been implemented in Emacs.
288 @defvar pgg-cache-passphrase
289 If non-@code{nil}, store passphrases. The default value of this
290 variable is @code{t}. If you are worried about security issues,
291 however, you could stop the caching of passphrases by setting this
292 variable to @code{nil}.
295 @defvar pgg-passphrase-cache-expiry
296 Elapsed time for expiration in seconds.
299 If your passphrase contains non-ASCII characters, you might need to
300 specify the coding-system to be used to encode your passphrases since
301 GnuPG treats them as a byte sequence not a character sequence.
303 @defvar pgg-passphrase-coding-system
304 Coding-system used to encode passphrase.
307 @node Default user identity
308 @section Default user identity
310 The PGP implementation is usually able to select the proper key to use
311 for signing and decryption, but if you have more than one key, you may
312 need to specify the key id to use.
314 @defvar pgg-default-user-id
315 User ID of your default identity. It defaults to the value returned
316 by @samp{(user-login-name)}. You can customize this variable.
319 @defvar pgg-gpg-user-id
320 User ID of the GnuPG default identity. It defaults to @samp{nil}.
321 This overrides @samp{pgg-default-user-id}. You can customize this
325 @defvar pgg-pgp-user-id
326 User ID of the PGP 2.x/6.x default identity. It defaults to
327 @samp{nil}. This overrides @samp{pgg-default-user-id}. You can
328 customize this variable.
331 @defvar pgg-pgp5-user-id
332 User ID of the PGP 5.x default identity. It defaults to @samp{nil}.
333 This overrides @samp{pgg-default-user-id}. You can customize this
338 @chapter Architecture
340 PGG introduces the notion of a "scheme of PGP implementation" (used
341 interchangeably with "scheme" in this document). This term refers to a
342 singleton object wrapped with the luna object system.
344 Since PGG was designed for accessing and developing PGP functionality,
345 the architecture had to be designed not just for interoperability but
346 also for extensiblity. In this chapter we explore the architecture
347 while finding out how to write the PGG backend.
356 @section Initializing
358 A scheme must be initialized before it is used.
359 It had better guarantee to keep only one instance of a scheme.
361 The following code is snipped out of @file{pgg-gpg.el}. Once an
362 instance of @code{pgg-gpg} scheme is initialized, it's stored to the
363 variable @code{pgg-scheme-gpg-instance} and will be reused from now on.
366 (defvar pgg-scheme-gpg-instance nil)
368 (defun pgg-make-scheme-gpg ()
369 (or pgg-scheme-gpg-instance
370 (setq pgg-scheme-gpg-instance
371 (luna-make-entity 'pgg-scheme-gpg))))
374 The name of the function must follow the
375 regulation---@code{pgg-make-scheme-} follows the backend name.
377 @node Backend methods
378 @section Backend methods
380 In each backend, these methods must be present. The output of these
381 methods is stored in special buffers (@ref{Getting output}), so that
382 these methods must tell the status of the execution.
384 @deffn Method pgg-scheme-lookup-key scheme string &optional type
385 Return keys associated with @var{string}. If the optional third
386 argument @var{type} is non-@code{nil}, it searches from the secret
390 @deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign passphrase
391 Encrypt the current region between @var{start} and @var{end} for
392 @var{recipients}. If @var{sign} is non-@code{nil}, do a combined sign
393 and encrypt. If encryption is successful, it returns @code{t},
394 otherwise @code{nil}.
397 @deffn Method pgg-scheme-encrypt-symmetric-region scheme start end &optional passphrase
398 Encrypt the current region between @var{start} and @var{end} using a
399 symmetric cipher and a passphrases. If encryption is successful, it
400 returns @code{t}, otherwise @code{nil}. This function is currently only
401 implemented for GnuPG.
404 @deffn Method pgg-scheme-decrypt-region scheme start end &optional passphrase
405 Decrypt the current region between @var{start} and @var{end}. If
406 decryption is successful, it returns @code{t}, otherwise @code{nil}.
409 @deffn Method pgg-scheme-sign-region scheme start end &optional cleartext passphrase
410 Make the signature from text between @var{start} and @var{end}. If the
411 optional third argument @var{cleartext} is non-@code{nil}, it does not
412 create a detached signature. If signing is successful, it returns
413 @code{t}, otherwise @code{nil}.
416 @deffn Method pgg-scheme-verify-region scheme start end &optional signature
417 Verify the current region between @var{start} and @var{end}. If the
418 optional third argument @var{signature} is non-@code{nil}, it is treated
419 as the detached signature of the current region. If the signature is
420 successfully verified, it returns @code{t}, otherwise @code{nil}.
423 @deffn Method pgg-scheme-insert-key scheme
424 Retrieve the user's public key and insert it as ASCII-armored format.
425 On success, it returns @code{t}, otherwise @code{nil}.
428 @deffn Method pgg-scheme-snarf-keys-region scheme start end
429 Collect public keys in the current region between @var{start} and
430 @var{end}, and add them into the user's keyring.
431 On success, it returns @code{t}, otherwise @code{nil}.
435 @section Getting output
437 The output of the backend methods (@ref{Backend methods}) is stored in
438 special buffers, so that these methods must tell the status of the
441 @defvar pgg-errors-buffer
442 The standard error output of the execution of the PGP command is stored
446 @defvar pgg-output-buffer
447 The standard output of the execution of the PGP command is stored here.
450 @defvar pgg-status-buffer
451 The rest of status information of the execution of the PGP command is
455 @node Parsing OpenPGP packets
456 @chapter Parsing OpenPGP packets
458 The format of OpenPGP messages is maintained in order to publish all
459 necessary information needed to develop interoperable applications.
460 The standard is documented in RFC 2440.
462 PGG has its own parser for the OpenPGP packets.
464 @defun pgg-parse-armor string
465 List the sequence of packets in @var{string}.
468 @defun pgg-parse-armor-region start end
469 List the sequence of packets in the current region between @var{start}
473 @defvar pgg-ignore-packet-checksum
474 If non-@code{nil}, don't check the checksum of the packets.
478 @chapter Function Index
482 @chapter Variable Index
492 arch-tag: 0c205838-34b9-41a5-b9d7-49ae57ccac85