man/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  Free Software
  12 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 * Function Index::
  56 * Variable Index::
  57 @end menu
  58
  59 @node Overview
  60 @chapter Overview
  61
  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.
  66
  67 PGP/MIME is an application of MIME Object Security Services (RFC1848).
  68 The standard is documented in RFC2015.
  69
  70 @node Prerequisites
  71 @chapter Prerequisites
  72
  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.
  76
  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/}.
  80
  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}.
  88
  89 PGG also supports Pretty Good Privacy version 2 or version 5.
  90
  91 @node How to use
  92 @chapter How to use
  93
  94 The toplevel interface of this library is quite simple, and only
  95 intended to use with public-key cryptographic operation.
  96
  97 To use PGG, evaluate following expression at the beginning of your
  98 application program.
  99
 100 @lisp
 101 (require 'pgg)
 102 @end lisp
 103
 104 If you want to check existence of pgg.el at runtime, instead you can
 105 list autoload setting for desired functions as follows.
 106
 107 @lisp
 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)
 122 @end lisp
 123
 124 @menu
 125 * User Commands::
 126 * Selecting an implementation::
 127 * Caching passphrase::
 128 * Default user identity::
 129 @end menu
 130
 131 @node User Commands
 132 @section User Commands
 133
 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.
 140
 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.
 145
 146 If encryption is successful, it replaces the current region contents (in
 147 the accessible portion) with the resulting data.
 148
 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.
 152
 153 If optional @var{passphrase} is @code{nil}, the passphrase will be
 154 obtained from the passphrase cache or user.
 155 @end deffn
 156
 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.
 160
 161 If optional @var{passphrase} is @code{nil}, the passphrase will be
 162 obtained from the passphrase cache or user.
 163
 164 symmetric-cipher encryption is currently only implemented for GnuPG.
 165 @end deffn
 166
 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.
 171
 172 If optional @var{passphrase} is @code{nil}, the passphrase will be
 173 obtained from the passphrase cache or user.
 174 @end deffn
 175
 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.
 182
 183 If optional @var{passphrase} is @code{nil}, the passphrase will be
 184 obtained from the passphrase cache or user.
 185 @end deffn
 186
 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.
 191
 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.
 195 @end deffn
 196
 197 @deffn Command pgg-insert-key
 198 Retrieve the user's public key and insert it as ASCII-armored format.
 199 @end deffn
 200
 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.
 204 @end deffn
 205
 206 @node Selecting an implementation
 207 @section Selecting an implementation
 208
 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.
 214
 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.
 218
 219 @defvar pgg-scheme
 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}.
 222 @end defvar
 223
 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}.
 227 @end defvar
 228
 229 @node Caching passphrase
 230 @section Caching passphrase
 231
 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.}.
 237
 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
 242 is used (see below).
 243 @end defvar
 244
 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:
 249
 250 @smallexample
 251 eval "$(gpg-agent --daemon)"
 252 @end smallexample
 253
 254 For more details on invoking @code{gpg-agent}, @xref{Invoking
 255 GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}.
 256
 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}.)
 264
 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.
 272
 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
 276 below).
 277
 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.
 287
 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}.
 293 @end defvar
 294
 295 @defvar pgg-passphrase-cache-expiry
 296 Elapsed time for expiration in seconds.
 297 @end defvar
 298
 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 as a character sequence.
 302
 303 @defvar pgg-passphrase-coding-system
 304 Coding system used to encode passphrase.
 305 @end defvar
 306
 307 @node Default user identity
 308 @section Default user identity
 309
 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.
 313
 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.
 317 @end defvar
 318
 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
 322 variable.
 323 @end defvar
 324
 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.
 329 @end defvar
 330
 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
 334 variable.
 335 @end defvar
 336
 337 @node Architecture
 338 @chapter Architecture
 339
 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.
 343
 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.
 348
 349 @menu
 350 * Initializing::
 351 * Backend methods::
 352 * Getting output::
 353 @end menu
 354
 355 @node Initializing
 356 @section Initializing
 357
 358 A scheme must be initialized before it is used.
 359 It had better guarantee to keep only one instance of a scheme.
 360
 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.
 364
 365 @lisp
 366 (defvar pgg-scheme-gpg-instance nil)
 367
 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))))
 372 @end lisp
 373
 374 The name of the function must follow the
 375 regulation---@code{pgg-make-scheme-} follows the backend name.
 376
 377 @node Backend methods
 378 @section Backend methods
 379
 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.
 383
 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
 387 keyrings.
 388 @end deffn
 389
 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}.
 395 @end deffn
 396
 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.
 402 @end deffn
 403
 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}.
 407 @end deffn
 408
 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}.
 414 @end deffn
 415
 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}.
 421 @end deffn
 422
 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}.
 426 @end deffn
 427
 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}.
 432 @end deffn
 433
 434 @node Getting output
 435 @section Getting output
 436
 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
 439 execution.
 440
 441 @defvar pgg-errors-buffer
 442 The standard error output of the execution of the PGP command is stored
 443 here.
 444 @end defvar
 445
 446 @defvar pgg-output-buffer
 447 The standard output of the execution of the PGP command is stored here.
 448 @end defvar
 449
 450 @defvar pgg-status-buffer
 451 The rest of status information of the execution of the PGP command is
 452 stored here.
 453 @end defvar
 454
 455 @node Parsing OpenPGP packets
 456 @chapter Parsing OpenPGP packets
 457
 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.
 461
 462 PGG has its own parser for the OpenPGP packets.
 463
 464 @defun pgg-parse-armor string
 465 List the sequence of packets in @var{string}.
 466 @end defun
 467
 468 @defun pgg-parse-armor-region start end
 469 List the sequence of packets in the current region between @var{start}
 470 and @var{end}.
 471 @end defun
 472
 473 @defvar pgg-ignore-packet-checksum
 474 If non-@code{nil}, don't check the checksum of the packets.
 475 @end defvar
 476
 477 @node Function Index
 478 @chapter Function Index
 479 @printindex fn
 480
 481 @node Variable Index
 482 @chapter Variable Index
 483 @printindex vr
 484
 485 @summarycontents
 486 @contents
 487 @bye
 488
 489 @c End:
 490
 491 @ignore
 492    arch-tag: 0c205838-34b9-41a5-b9d7-49ae57ccac85
 493 @end ignore