1 \input texinfo @c -*-texinfo-*-
8 * PGG: (pgg). Emacs interface to various PGP implementations.
11 @settitle PGG @value{VERSION}
14 This file describes the PGG.
16 Copyright (C) 2003, 2004 Free Software Foundation, Inc.
17 Copyright (C) 2001 Daiki Ueno.
19 Permission is granted to copy, distribute and/or modify this document
20 under the terms of the GNU Free Documentation License, Version 1.1 or
21 any later version published by the Free Software Foundation; with no
22 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
23 Texts. A copy of the license is included in the section entitled "GNU
24 Free Documentation License".
35 @vskip 0pt plus 1filll
36 Copyright @copyright{} 2001 Daiki Ueno.
38 Permission is granted to copy, distribute and/or modify this document
39 under the terms of the GNU Free Documentation License, Version 1.1 or
40 any later version published by the Free Software Foundation; with no
41 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
42 Texts. A copy of the license is included in the section entitled "GNU
43 Free Documentation License".
51 This manual describes PGG. PGG is an interface library between Emacs
52 and various tools for secure communication. PGG also provides a simple
53 user interface to encrypt, decrypt, sign, and verify MIME messages.
56 * Overview:: What PGG is.
57 * Prerequisites:: Complicated stuff you may have to do.
58 * How to use:: Getting started quickly.
60 * Parsing OpenPGP packets::
68 PGG is an interface library between Emacs and various tools for secure
69 communication. Even though Mailcrypt has similar feature, it does not
70 deal with detached PGP messages, normally used in PGP/MIME
71 infrastructure. This was the main reason why I wrote the new library.
73 PGP/MIME is an application of MIME Object Security Services (RFC1848).
74 The standard is documented in RFC2015.
77 @chapter Prerequisites
79 PGG requires at least one implementation of privacy guard system.
80 This document assumes that you have already obtained and installed them
81 and that you are familiar with its basic functions.
83 By default, PGG uses GnuPG, but Pretty Good Privacy version 2 or version
84 5 are also supported. If you are new to such a system, I recommend that
85 you should look over the GNU Privacy Handbook (GPH) which is available
86 at @uref{http://www.gnupg.org/gph/}.
91 The toplevel interface of this library is quite simple, and only
92 intended to use with public-key cryptographic operation.
94 To use PGG, evaluate following expression at the beginning of your
101 If you want to check existence of pgg.el at runtime, instead you can
102 list autoload setting for desired functions as follows.
105 (autoload 'pgg-encrypt-region "pgg"
106 "Encrypt the current region." t)
107 (autoload 'pgg-decrypt-region "pgg"
108 "Decrypt the current region." t)
109 (autoload 'pgg-sign-region "pgg"
110 "Sign the current region." t)
111 (autoload 'pgg-verify-region "pgg"
112 "Verify the current region." t)
113 (autoload 'pgg-insert-key "pgg"
114 "Insert the ASCII armored public key." t)
115 (autoload 'pgg-snarf-keys-region "pgg"
116 "Import public keys in the current region." t)
121 * Selecting an implementation::
122 * Caching passphrase::
123 * Default user identity::
127 @section User Commands
129 At this time you can use some cryptographic commands. The behavior of
130 these commands relies on a fashion of invocation because they are also
131 intended to be used as library functions. In case you don't have the
132 signer's public key, for example, the function @code{pgg-verify-region}
133 fails immediately, but if the function had been called interactively, it
134 would ask you to retrieve the signer's public key from the server.
136 @deffn Command pgg-encrypt-region start end recipients &optional sign
137 Encrypt the current region between @var{start} and @var{end} for
138 @var{recipients}. When the function were called interactively, you
139 would be asked about the recipients.
141 If encryption is successful, it replaces the current region contents (in
142 the accessible portion) with the resulting data.
144 If optional argument @var{sign} is non-@code{nil}, the function is
145 request to do a combined sign and encrypt. This currently only work
149 @deffn Command pgg-decrypt-region start end
150 Decrypt the current region between @var{start} and @var{end}. If
151 decryption is successful, it replaces the current region contents (in
152 the accessible portion) with the resulting data.
155 @deffn Command pgg-sign-region start end &optional cleartext
156 Make the signature from text between @var{start} and @var{end}. If the
157 optional third argument @var{cleartext} is non-@code{nil}, or the
158 function is called interactively, it does not create a detached
159 signature. In such a case, it replaces the current region contents (in
160 the accessible portion) with the resulting data.
163 @deffn Command pgg-verify-region start end &optional signature fetch
164 Verify the current region between @var{start} and @var{end}. If the
165 optional third argument @var{signature} is non-@code{nil}, or the function
166 is called interactively, it is treated as the detached signature of the
169 If the optional 4th argument @var{fetch} is non-@code{nil}, or the
170 function is called interactively, we attempt to fetch the signer's
171 public key from the key server.
174 @deffn Command pgg-insert-key
175 Retrieve the user's public key and insert it as ASCII-armored format.
178 @deffn Command pgg-snarf-keys-region start end
179 Collect public keys in the current region between @var{start} and
180 @var{end}, and add them into the user's keyring.
183 @node Selecting an implementation
184 @section Selecting an implementation
186 Since PGP has a long history and there are a number of PGP
187 implementations available today, the function which each one has differs
188 considerably. For example, if you are using GnuPG, you know you can
189 select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on
190 the other hand the version 2 of PGP only supports IDEA.
192 By default, if the variable @code{pgg-scheme} is not set, PGG searches the
193 registered scheme for an implementation of the requested service
194 associated with the named algorithm. If there are no match, PGG uses
195 @code{pgg-default-scheme}. In other words, there are two options to
196 control which command is used to process the incoming PGP armors. One
197 is for encrypting and signing, the other is for decrypting and
201 Force specify the scheme of PGP implementation for decrypting and verifying.
202 The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
205 @defvar pgg-default-scheme
206 Force specify the scheme of PGP implementation for encrypting and signing.
207 The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
210 @node Caching passphrase
211 @section Caching passphrase
213 PGG uses a simple passphrase caching mechanism, which is enabled by
216 @defvar pgg-cache-passphrase
217 If non-@code{nil}, store passphrases. The default value of this
218 variable is @code{t}. If you were worry about security issue, however,
219 you could stop caching with setting it @code{nil}.
222 @defvar pgg-passphrase-cache-expiry
223 Elapsed time for expiration in seconds.
226 @node Default user identity
227 @section Default user identity
229 The PGP implementation is usually able to select the proper key to use
230 for signing and decryption, but if you have more than one key, you may
231 need to specify the key id to use.
233 @defvar pgg-default-user-id
234 User ID of your default identity. It defaults to the value returned
235 by @samp{(user-login-name)}. You can customize this variable.
238 @defvar pgg-gpg-user-id
239 User ID of the GnuPG default identity. It defaults to @samp{nil}.
240 This overrides @samp{pgg-default-user-id}. You can customize this
244 @defvar pgg-pgp-user-id
245 User ID of the PGP 2.x/6.x default identity. It defaults to
246 @samp{nil}. This overrides @samp{pgg-default-user-id}. You can
247 customize this variable.
250 @defvar pgg-pgp5-user-id
251 User ID of the PGP 5.x default identity. It defaults to @samp{nil}.
252 This overrides @samp{pgg-default-user-id}. You can customize this
257 @chapter Architecture
259 PGG introduces the notion of a "scheme of PGP implementation" (used
260 interchangeably with "scheme" in this document). This term refers to a
261 singleton object wrapped with the luna object system.
263 Since PGG was designed for accessing and developing PGP functionality,
264 the architecture had to be designed not just for interoperability but
265 also for extensiblity. In this chapter we explore the architecture
266 while finding out how to write the PGG backend.
275 @section Initializing
277 A scheme must be initialized before it is used.
278 It had better guarantee to keep only one instance of a scheme.
280 The following code is snipped out of @file{pgg-gpg.el}. Once an
281 instance of @code{pgg-gpg} scheme is initialized, it's stored to the
282 variable @code{pgg-scheme-gpg-instance} and will be reused from now on.
285 (defvar pgg-scheme-gpg-instance nil)
287 (defun pgg-make-scheme-gpg ()
288 (or pgg-scheme-gpg-instance
289 (setq pgg-scheme-gpg-instance
290 (luna-make-entity 'pgg-scheme-gpg))))
293 The name of the function must follow the
294 regulation---@code{pgg-make-scheme-} follows the backend name.
296 @node Backend methods
297 @section Backend methods
299 In each backend, these methods must be present. The output of these
300 methods is stored in special buffers (@ref{Getting output}), so that
301 these methods must tell the status of the execution.
303 @deffn Method pgg-scheme-lookup-key scheme string &optional type
304 Return keys associated with @var{string}. If the optional third
305 argument @var{type} is non-@code{nil}, it searches from the secret
309 @deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign
310 Encrypt the current region between @var{start} and @var{end} for
311 @var{recipients}. If @var{sign} is non-@code{nil}, do a combined sign
312 and encrypt. If encryption is successful, it returns @code{t},
313 otherwise @code{nil}.
316 @deffn Method pgg-scheme-decrypt-region scheme start end
317 Decrypt the current region between @var{start} and @var{end}. If
318 decryption is successful, it returns @code{t}, otherwise @code{nil}.
321 @deffn Method pgg-scheme-sign-region scheme start end &optional cleartext
322 Make the signature from text between @var{start} and @var{end}. If the
323 optional third argument @var{cleartext} is non-@code{nil}, it does not
324 create a detached signature. If signing is successful, it returns
325 @code{t}, otherwise @code{nil}.
328 @deffn Method pgg-scheme-verify-region scheme start end &optional signature
329 Verify the current region between @var{start} and @var{end}. If the
330 optional third argument @var{signature} is non-@code{nil}, it is treated
331 as the detached signature of the current region. If the signature is
332 successfully verified, it returns @code{t}, otherwise @code{nil}.
335 @deffn Method pgg-scheme-insert-key scheme
336 Retrieve the user's public key and insert it as ASCII-armored format.
337 On success, it returns @code{t}, otherwise @code{nil}.
340 @deffn Method pgg-scheme-snarf-keys-region scheme start end
341 Collect public keys in the current region between @var{start} and
342 @var{end}, and add them into the user's keyring.
343 On success, it returns @code{t}, otherwise @code{nil}.
347 @section Getting output
349 The output of the backend methods (@ref{Backend methods}) is stored in
350 special buffers, so that these methods must tell the status of the
353 @defvar pgg-errors-buffer
354 The standard error output of the execution of the PGP command is stored
358 @defvar pgg-output-buffer
359 The standard output of the execution of the PGP command is stored here.
362 @defvar pgg-status-buffer
363 The rest of status information of the execution of the PGP command is
367 @node Parsing OpenPGP packets
368 @chapter Parsing OpenPGP packets
370 The format of OpenPGP messages is maintained in order to publish all
371 necessary information needed to develop interoperable applications.
372 The standard is documented in RFC 2440.
374 PGG has its own parser for the OpenPGP packets.
376 @defun pgg-parse-armor string
377 List the sequence of packets in @var{string}.
380 @defun pgg-parse-armor-region start end
381 List the sequence of packets in the current region between @var{start}
385 @defvar pgg-ignore-packet-checksum
386 If non-@code{nil}, don't check the checksum of the packets.
390 @chapter Function Index
394 @chapter Variable Index