doc/misc/pgg.texi

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