doc/misc/pgg.texi

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