X-Git-Url: https://cgit.sxemacs.org/?a=blobdiff_plain;f=texi%2Fpgg.texi;h=9d91de7699a19b451e8a708a7a32686dcce96ba8;hb=b817682d77692cbd253539f14557228a4337215c;hp=a578e49b55b5875b4bf826adcb318652755fbec5;hpb=a49ce981e8312669d91d9dfbca370138124eb5e1;p=gnus diff --git a/texi/pgg.texi b/texi/pgg.texi index a578e49b5..9d91de769 100644 --- a/texi/pgg.texi +++ b/texi/pgg.texi @@ -1,34 +1,36 @@ \input texinfo @c -*-texinfo-*- @setfilename pgg +@settitle PGG @value{VERSION} @set VERSION 0.1 - @copying -This file describes PGG, an Emacs interface to various PGP implementations. +This file describes PGG @value{VERSION}, an Emacs interface to various +PGP implementations. -Copyright @copyright{} 2001, 2003, 2004, 2005, 2006, 2007 Free Software -Foundation, Inc. +Copyright @copyright{} 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009, +2010, 2011 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 or +under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no -Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -Texts. A copy of the license is included in the section entitled ``GNU -Free Documentation License.'' +Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License.'' + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual. Buying copies from the FSF supports it in +developing GNU and promoting software freedom.'' @end quotation @end copying @dircategory Emacs @direntry -* PGG: (pgg). Emacs interface to various PGP implementations. +* PGG: (pgg). Emacs interface to various PGP implementations. @end direntry -@settitle PGG @value{VERSION} - - @titlepage @title PGG @@ -38,20 +40,27 @@ Free Documentation License.'' @vskip 0pt plus 1filll @insertcopying @end titlepage -@page + +@contents @node Top @top PGG -This manual describes PGG. PGG is an interface library between Emacs + +PGG is an interface library between Emacs and various tools for secure communication. PGG also provides a simple user interface to encrypt, decrypt, sign, and verify MIME messages. +@ifnottex +@insertcopying +@end ifnottex + @menu * Overview:: What PGG is. * Prerequisites:: Complicated stuff you may have to do. * How to use:: Getting started quickly. * Architecture:: * Parsing OpenPGP packets:: +* GNU Free Documentation License:: The license for this documentation. * Function Index:: * Variable Index:: @end menu @@ -125,7 +134,7 @@ list autoload setting for desired functions as follows. * User Commands:: * Selecting an implementation:: * Caching passphrase:: -* Default user identity:: +* Default user identity:: @end menu @node User Commands @@ -229,8 +238,61 @@ The default scheme of PGP implementation. The value should be one of @node Caching passphrase @section Caching passphrase -PGG uses a simple passphrase caching mechanism, which is enabled by -default. +When using GnuPG (gpg) as the PGP scheme, we recommend using a program +called @code{gpg-agent} for entering and caching +passphrases@footnote{Actually, @code{gpg-agent} does not cache +passphrases but private keys. On the other hand, from a user's point +of view, this technical difference isn't visible.}. + +@defvar pgg-gpg-use-agent +If non-@code{nil}, attempt to use @code{gpg-agent} whenever possible. +The default is @code{t}. If @code{gpg-agent} is not running, or GnuPG +is not the current PGP scheme, PGG's own passphrase-caching mechanism +is used (see below). +@end defvar + +To use @code{gpg-agent} with PGG, you must first ensure that +@code{gpg-agent} is running. For example, if you are running in the X +Window System, you can do this by putting the following line in your +@file{.xsession} file: + +@smallexample +eval "$(gpg-agent --daemon)" +@end smallexample + +For more details on invoking @code{gpg-agent}, @xref{Invoking +GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}. + +Whenever you perform a PGG operation that requires a GnuPG passphrase, +GnuPG will contact @code{gpg-agent}, which prompts you for the +passphrase. Furthermore, @code{gpg-agent} ``caches'' the result, so +that subsequent uses will not require you to enter the passphrase +again. (This cache usually expires after a certain time has passed; +you can change this using the @code{--default-cache-ttl} option when +invoking @code{gpg-agent}.) + +If you are running in a X Window System environment, @code{gpg-agent} +prompts for a passphrase by opening a graphical window. However, if +you are running Emacs on a text terminal, @code{gpg-agent} has trouble +receiving input from the terminal, since it is being sent to Emacs. +One workaround for this problem is to run @code{gpg-agent} on a +different terminal from Emacs, with the @code{--keep-tty} option; this +tells @code{gpg-agent} use its own terminal to prompt for passphrases. + +When @code{gpg-agent} is not being used, PGG prompts for a passphrase +through Emacs. It also has its own passphrase caching mechanism, +which is controlled by the variable @code{pgg-cache-passphrase} (see +below). + +There is a security risk in handling passphrases through PGG rather +than @code{gpg-agent}. When you enter your passphrase into an Emacs +prompt, it is temporarily stored as a cleartext string in the memory +of the Emacs executable. If the executable memory is swapped to disk, +the root user can, in theory, extract the passphrase from the +swapfile. Furthermore, the swapfile containing the cleartext +passphrase might remain on the disk after the system is discarded or +stolen. @code{gpg-agent} avoids this problem by using certain tricks, +such as memory locking, which have not been implemented in Emacs. @defvar pgg-cache-passphrase If non-@code{nil}, store passphrases. The default value of this @@ -243,12 +305,12 @@ variable to @code{nil}. Elapsed time for expiration in seconds. @end defvar -@defvar pgg-gpg-use-agent -When using GnuPG (gpg) as PGP scheme you can use @code{gpg-agent} for -caching@footnote{Actually @code{gpg-agent} does not cache passphrases -but private keys. On the other hand, from a users point of view this -technical difference isn't visible.}. It defaults to @code{t}. -Setting this to @code{nil} is not recommended. +If your passphrase contains non-ASCII characters, you might need to +specify the coding system to be used to encode your passphrases, since +GnuPG treats them as a byte sequence, not as a character sequence. + +@defvar pgg-passphrase-coding-system +Coding system used to encode passphrase. @end defvar @node Default user identity @@ -315,7 +377,7 @@ variable @code{pgg-scheme-gpg-instance} and will be reused from now on. (defun pgg-make-scheme-gpg () (or pgg-scheme-gpg-instance (setq pgg-scheme-gpg-instance - (luna-make-entity 'pgg-scheme-gpg)))) + (luna-make-entity 'pgg-scheme-gpg)))) @end lisp The name of the function must follow the @@ -421,20 +483,18 @@ and @var{end}. If non-@code{nil}, don't check the checksum of the packets. @end defvar +@node GNU Free Documentation License +@appendix GNU Free Documentation License +@include doclicense.texi + @node Function Index -@chapter Function Index +@unnumbered Function Index @printindex fn @node Variable Index -@chapter Variable Index +@unnumbered Variable Index @printindex vr -@summarycontents -@contents @bye @c End: - -@ignore - arch-tag: 0c205838-34b9-41a5-b9d7-49ae57ccac85 -@end ignore