| 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-2011 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 extensiblity. 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: |