doc/misc/pgg.texi

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