doc/misc/pgg.texi

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