code.delx.au - gnu-emacs/blob - doc/misc/pgg.texi

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