1 \input texinfo @c -*-texinfo-*-
9 This file describes PGG, an Emacs interface to various PGP implementations.
11 Copyright @copyright{} 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
12 Copyright @copyright{} 2001 Daiki Ueno.
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, but Pretty Good Privacy version 2 or version
78 5 are also supported. If you are new to such a system, I recommend that
79 you should look over the GNU Privacy Handbook (GPH) which is available
80 at @uref{http://www.gnupg.org/gph/}.
85 The toplevel interface of this library is quite simple, and only
86 intended to use with public-key cryptographic operation.
88 To use PGG, evaluate following expression at the beginning of your
95 If you want to check existence of pgg.el at runtime, instead you can
96 list autoload setting for desired functions as follows.
99 (autoload 'pgg-encrypt-region "pgg"
100 "Encrypt the current region." t)
101 (autoload 'pgg-encrypt-symmetric-region "pgg"
102 "Encrypt the current region with symmetric algorithm." t)
103 (autoload 'pgg-decrypt-region "pgg"
104 "Decrypt the current region." t)
105 (autoload 'pgg-sign-region "pgg"
106 "Sign the current region." t)
107 (autoload 'pgg-verify-region "pgg"
108 "Verify the current region." t)
109 (autoload 'pgg-insert-key "pgg"
110 "Insert the ASCII armored public key." t)
111 (autoload 'pgg-snarf-keys-region "pgg"
112 "Import public keys in the current region." t)
117 * Selecting an implementation::
118 * Caching passphrase::
119 * Default user identity::
123 @section User Commands
125 At this time you can use some cryptographic commands. The behavior of
126 these commands relies on a fashion of invocation because they are also
127 intended to be used as library functions. In case you don't have the
128 signer's public key, for example, the function @code{pgg-verify-region}
129 fails immediately, but if the function had been called interactively, it
130 would ask you to retrieve the signer's public key from the server.
132 @deffn Command pgg-encrypt-region start end recipients &optional sign passphrase
133 Encrypt the current region between @var{start} and @var{end} for
134 @var{recipients}. When the function were called interactively, you
135 would be asked about the recipients.
137 If encryption is successful, it replaces the current region contents (in
138 the accessible portion) with the resulting data.
140 If optional argument @var{sign} is non-@code{nil}, the function is
141 request to do a combined sign and encrypt. This currently is
142 confirmed to work with GnuPG, but might not work with PGP or PGP5.
144 If optional @var{passphrase} is @code{nil}, the passphrase will be
145 obtained from the passphrase cache or user.
148 @deffn Command pgg-encrypt-symmetric-region &optional start end passphrase
149 Encrypt the current region between @var{start} and @var{end} using a
150 symmetric cipher. After invocation you are asked for a passphrase.
152 If optional @var{passphrase} is @code{nil}, the passphrase will be
153 obtained from the passphrase cache or user.
155 symmetric-cipher encryption is currently only implemented for GnuPG.
158 @deffn Command pgg-decrypt-region start end &optional passphrase
159 Decrypt the current region between @var{start} and @var{end}. If
160 decryption is successful, it replaces the current region contents (in
161 the accessible portion) with the resulting data.
163 If optional @var{passphrase} is @code{nil}, the passphrase will be
164 obtained from the passphrase cache or user.
167 @deffn Command pgg-sign-region start end &optional cleartext passphrase
168 Make the signature from text between @var{start} and @var{end}. If the
169 optional third argument @var{cleartext} is non-@code{nil}, or the
170 function is called interactively, it does not create a detached
171 signature. In such a case, it replaces the current region contents (in
172 the accessible portion) with the resulting data.
174 If optional @var{passphrase} is @code{nil}, the passphrase will be
175 obtained from the passphrase cache or user.
178 @deffn Command pgg-verify-region start end &optional signature fetch
179 Verify the current region between @var{start} and @var{end}. If the
180 optional third argument @var{signature} is non-@code{nil}, it is treated
181 as the detached signature file of the current region.
183 If the optional 4th argument @var{fetch} is non-@code{nil}, or the
184 function is called interactively, we attempt to fetch the signer's
185 public key from the key server.
188 @deffn Command pgg-insert-key
189 Retrieve the user's public key and insert it as ASCII-armored format.
192 @deffn Command pgg-snarf-keys-region start end
193 Collect public keys in the current region between @var{start} and
194 @var{end}, and add them into the user's keyring.
197 @node Selecting an implementation
198 @section Selecting an implementation
200 Since PGP has a long history and there are a number of PGP
201 implementations available today, the function which each one has differs
202 considerably. For example, if you are using GnuPG, you know you can
203 select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on
204 the other hand the version 2 of PGP only supports IDEA.
206 Which implementation is used is controlled by the @code{pgg-scheme}
207 variable. If it is @code{nil} (the default), the value of the
208 @code{pgg-default-scheme} variable will be used instead.
211 Force specify the scheme of PGP implementation. The value can be set to
212 @code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{nil}.
215 @defvar pgg-default-scheme
216 The default scheme of PGP implementation. The value should be one of
217 @code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{gpg}.
220 @node Caching passphrase
221 @section Caching passphrase
223 PGG uses a simple passphrase caching mechanism, which is enabled by
226 @defvar pgg-cache-passphrase
227 If non-@code{nil}, store passphrases. The default value of this
228 variable is @code{t}. If you are worried about security issues,
229 however, you could stop the caching of passphrases by setting this
230 variable to @code{nil}.
233 @defvar pgg-passphrase-cache-expiry
234 Elapsed time for expiration in seconds.
237 @defvar pgg-gpg-use-agent
238 When using GnuPG (gpg) as PGP scheme you can use @code{gpg-agent} for
239 caching@footnote{Actually @code{gpg-agent} does not cache passphrases
240 but private keys. On the other hand, from a users point of view this
241 technical difference isn't visible.}. If non-@code{nil} try to use a
242 running @code{gpg-agent}. It defaults to @code{nil}.
245 @node Default user identity
246 @section Default user identity
248 The PGP implementation is usually able to select the proper key to use
249 for signing and decryption, but if you have more than one key, you may
250 need to specify the key id to use.
252 @defvar pgg-default-user-id
253 User ID of your default identity. It defaults to the value returned
254 by @samp{(user-login-name)}. You can customize this variable.
257 @defvar pgg-gpg-user-id
258 User ID of the GnuPG default identity. It defaults to @samp{nil}.
259 This overrides @samp{pgg-default-user-id}. You can customize this
263 @defvar pgg-pgp-user-id
264 User ID of the PGP 2.x/6.x default identity. It defaults to
265 @samp{nil}. This overrides @samp{pgg-default-user-id}. You can
266 customize this variable.
269 @defvar pgg-pgp5-user-id
270 User ID of the PGP 5.x default identity. It defaults to @samp{nil}.
271 This overrides @samp{pgg-default-user-id}. You can customize this
276 @chapter Architecture
278 PGG introduces the notion of a "scheme of PGP implementation" (used
279 interchangeably with "scheme" in this document). This term refers to a
280 singleton object wrapped with the luna object system.
282 Since PGG was designed for accessing and developing PGP functionality,
283 the architecture had to be designed not just for interoperability but
284 also for extensiblity. In this chapter we explore the architecture
285 while finding out how to write the PGG back end.
294 @section Initializing
296 A scheme must be initialized before it is used.
297 It had better guarantee to keep only one instance of a scheme.
299 The following code is snipped out of @file{pgg-gpg.el}. Once an
300 instance of @code{pgg-gpg} scheme is initialized, it's stored to the
301 variable @code{pgg-scheme-gpg-instance} and will be reused from now on.
304 (defvar pgg-scheme-gpg-instance nil)
306 (defun pgg-make-scheme-gpg ()
307 (or pgg-scheme-gpg-instance
308 (setq pgg-scheme-gpg-instance
309 (luna-make-entity 'pgg-scheme-gpg))))
312 The name of the function must follow the
313 regulation---@code{pgg-make-scheme-} follows the back end name.
315 @node Back end methods
316 @section Back end methods
318 In each back end, these methods must be present. The output of these
319 methods is stored in special buffers (@ref{Getting output}), so that
320 these methods must tell the status of the execution.
322 @deffn Method pgg-scheme-lookup-key scheme string &optional type
323 Return keys associated with @var{string}. If the optional third
324 argument @var{type} is non-@code{nil}, it searches from the secret
328 @deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign passphrase
329 Encrypt the current region between @var{start} and @var{end} for
330 @var{recipients}. If @var{sign} is non-@code{nil}, do a combined sign
331 and encrypt. If encryption is successful, it returns @code{t},
332 otherwise @code{nil}.
335 @deffn Method pgg-scheme-encrypt-symmetric-region scheme start end &optional passphrase
336 Encrypt the current region between @var{start} and @var{end} using a
337 symmetric cipher and a passphrases. If encryption is successful, it
338 returns @code{t}, otherwise @code{nil}. This function is currently only
339 implemented for GnuPG.
342 @deffn Method pgg-scheme-decrypt-region scheme start end &optional passphrase
343 Decrypt the current region between @var{start} and @var{end}. If
344 decryption is successful, it returns @code{t}, otherwise @code{nil}.
347 @deffn Method pgg-scheme-sign-region scheme start end &optional cleartext passphrase
348 Make the signature from text between @var{start} and @var{end}. If the
349 optional third argument @var{cleartext} is non-@code{nil}, it does not
350 create a detached signature. If signing is successful, it returns
351 @code{t}, otherwise @code{nil}.
354 @deffn Method pgg-scheme-verify-region scheme start end &optional signature
355 Verify the current region between @var{start} and @var{end}. If the
356 optional third argument @var{signature} is non-@code{nil}, it is treated
357 as the detached signature of the current region. If the signature is
358 successfully verified, it returns @code{t}, otherwise @code{nil}.
361 @deffn Method pgg-scheme-insert-key scheme
362 Retrieve the user's public key and insert it as ASCII-armored format.
363 On success, it returns @code{t}, otherwise @code{nil}.
366 @deffn Method pgg-scheme-snarf-keys-region scheme start end
367 Collect public keys in the current region between @var{start} and
368 @var{end}, and add them into the user's keyring.
369 On success, it returns @code{t}, otherwise @code{nil}.
373 @section Getting output
375 The output of the back end methods (@ref{Back end methods}) is stored in
376 special buffers, so that these methods must tell the status of the
379 @defvar pgg-errors-buffer
380 The standard error output of the execution of the PGP command is stored
384 @defvar pgg-output-buffer
385 The standard output of the execution of the PGP command is stored here.
388 @defvar pgg-status-buffer
389 The rest of status information of the execution of the PGP command is
393 @node Parsing OpenPGP packets
394 @chapter Parsing OpenPGP packets
396 The format of OpenPGP messages is maintained in order to publish all
397 necessary information needed to develop interoperable applications.
398 The standard is documented in RFC 2440.
400 PGG has its own parser for the OpenPGP packets.
402 @defun pgg-parse-armor string
403 List the sequence of packets in @var{string}.
406 @defun pgg-parse-armor-region start end
407 List the sequence of packets in the current region between @var{start}
411 @defvar pgg-ignore-packet-checksum
412 If non-@code{nil}, don't check the checksum of the packets.
416 @chapter Function Index
420 @chapter Variable Index
430 arch-tag: 0c205838-34b9-41a5-b9d7-49ae57ccac85