doc/misc/pgg.texi

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