\input texinfo @c -*-texinfo-*-
@setfilename pgg
+@settitle PGG @value{VERSION}
@set VERSION 0.1
-
@copying
-This file describes the PGG.
+This file describes PGG @value{VERSION}, an Emacs interface to various
+PGP implementations.
-Copyright (C) 2003, 2004, 2005 Free Software Foundation, Inc.
-Copyright (C) 2001 Daiki Ueno.
+Copyright @copyright{} 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
+2010 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
@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
This document assumes that you have already obtained and installed them
and that you are familiar with its basic functions.
-By default, PGG uses GnuPG, but Pretty Good Privacy version 2 or version
-5 are also supported. If you are new to such a system, I recommend that
-you should look over the GNU Privacy Handbook (GPH) which is available
-at @uref{http://www.gnupg.org/gph/}.
+By default, PGG uses GnuPG. If you are new to such a system, I
+recommend that you should look over the GNU Privacy Handbook (GPH)
+which is available at @uref{http://www.gnupg.org/documentation/}.
+
+When using GnuPG, we recommend the use of the @code{gpg-agent}
+program, which is distributed with versions 2.0 and later of GnuPG.
+This is a daemon to manage private keys independently from any
+protocol, and provides the most secure way to input and cache your
+passphrases (@pxref{Caching passphrase}). By default, PGG will
+attempt to use @code{gpg-agent} if it is running. @xref{Invoking
+GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}.
+
+PGG also supports Pretty Good Privacy version 2 or version 5.
@node How to use
@chapter How to use
@lisp
(autoload 'pgg-encrypt-region "pgg"
"Encrypt the current region." t)
+(autoload 'pgg-encrypt-symmetric-region "pgg"
+ "Encrypt the current region with symmetric algorithm." t)
(autoload 'pgg-decrypt-region "pgg"
"Decrypt the current region." t)
(autoload 'pgg-sign-region "pgg"
* User Commands::
* Selecting an implementation::
* Caching passphrase::
-* Default user identity::
+* Default user identity::
@end menu
@node User Commands
fails immediately, but if the function had been called interactively, it
would ask you to retrieve the signer's public key from the server.
-@deffn Command pgg-encrypt-region start end recipients &optional sign
+@deffn Command pgg-encrypt-region start end recipients &optional sign passphrase
Encrypt the current region between @var{start} and @var{end} for
@var{recipients}. When the function were called interactively, you
would be asked about the recipients.
the accessible portion) with the resulting data.
If optional argument @var{sign} is non-@code{nil}, the function is
-request to do a combined sign and encrypt. This currently only work
-with GnuPG.
+request to do a combined sign and encrypt. This currently is
+confirmed to work with GnuPG, but might not work with PGP or PGP5.
+
+If optional @var{passphrase} is @code{nil}, the passphrase will be
+obtained from the passphrase cache or user.
+@end deffn
+
+@deffn Command pgg-encrypt-symmetric-region &optional start end passphrase
+Encrypt the current region between @var{start} and @var{end} using a
+symmetric cipher. After invocation you are asked for a passphrase.
+
+If optional @var{passphrase} is @code{nil}, the passphrase will be
+obtained from the passphrase cache or user.
+
+symmetric-cipher encryption is currently only implemented for GnuPG.
@end deffn
-@deffn Command pgg-decrypt-region start end
+@deffn Command pgg-decrypt-region start end &optional passphrase
Decrypt the current region between @var{start} and @var{end}. If
decryption is successful, it replaces the current region contents (in
the accessible portion) with the resulting data.
+
+If optional @var{passphrase} is @code{nil}, the passphrase will be
+obtained from the passphrase cache or user.
@end deffn
-@deffn Command pgg-sign-region start end &optional cleartext
+@deffn Command pgg-sign-region start end &optional cleartext passphrase
Make the signature from text between @var{start} and @var{end}. If the
optional third argument @var{cleartext} is non-@code{nil}, or the
function is called interactively, it does not create a detached
signature. In such a case, it replaces the current region contents (in
the accessible portion) with the resulting data.
+
+If optional @var{passphrase} is @code{nil}, the passphrase will be
+obtained from the passphrase cache or user.
@end deffn
@deffn Command pgg-verify-region start end &optional signature fetch
Verify the current region between @var{start} and @var{end}. If the
-optional third argument @var{signature} is non-@code{nil}, or the function
-is called interactively, it is treated as the detached signature of the
-current region.
+optional third argument @var{signature} is non-@code{nil}, it is treated
+as the detached signature file of the current region.
If the optional 4th argument @var{fetch} is non-@code{nil}, or the
function is called interactively, we attempt to fetch the signer's
select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on
the other hand the version 2 of PGP only supports IDEA.
-By default, if the variable @code{pgg-scheme} is not set, PGG searches the
-registered scheme for an implementation of the requested service
-associated with the named algorithm. If there are no match, PGG uses
-@code{pgg-default-scheme}. In other words, there are two options to
-control which command is used to process the incoming PGP armors. One
-is for encrypting and signing, the other is for decrypting and
-verifying.
+Which implementation is used is controlled by the @code{pgg-scheme}
+variable. If it is @code{nil} (the default), the value of the
+@code{pgg-default-scheme} variable will be used instead.
@defvar pgg-scheme
-Force specify the scheme of PGP implementation for decrypting and verifying.
-The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
+Force specify the scheme of PGP implementation. The value can be set to
+@code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{nil}.
@end defvar
@defvar pgg-default-scheme
-Force specify the scheme of PGP implementation for encrypting and signing.
-The value can be @code{gpg}, @code{pgp}, and @code{pgp5}.
+The default scheme of PGP implementation. The value should be one of
+@code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{gpg}.
@end defvar
@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
-variable is @code{t}. If you were worry about security issue, however,
-you could stop caching with setting it @code{nil}.
+variable is @code{t}. If you are worried about security issues,
+however, you could stop the caching of passphrases by setting this
+variable to @code{nil}.
@end defvar
@defvar pgg-passphrase-cache-expiry
Elapsed time for expiration in seconds.
@end defvar
+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
@section Default user identity
(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
keyrings.
@end deffn
-@deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign
+@deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign passphrase
Encrypt the current region between @var{start} and @var{end} for
@var{recipients}. If @var{sign} is non-@code{nil}, do a combined sign
and encrypt. If encryption is successful, it returns @code{t},
otherwise @code{nil}.
@end deffn
-@deffn Method pgg-scheme-decrypt-region scheme start end
+@deffn Method pgg-scheme-encrypt-symmetric-region scheme start end &optional passphrase
+Encrypt the current region between @var{start} and @var{end} using a
+symmetric cipher and a passphrases. If encryption is successful, it
+returns @code{t}, otherwise @code{nil}. This function is currently only
+implemented for GnuPG.
+@end deffn
+
+@deffn Method pgg-scheme-decrypt-region scheme start end &optional passphrase
Decrypt the current region between @var{start} and @var{end}. If
decryption is successful, it returns @code{t}, otherwise @code{nil}.
@end deffn
-@deffn Method pgg-scheme-sign-region scheme start end &optional cleartext
+@deffn Method pgg-scheme-sign-region scheme start end &optional cleartext passphrase
Make the signature from text between @var{start} and @var{end}. If the
optional third argument @var{cleartext} is non-@code{nil}, it does not
create a detached signature. If signing is successful, it returns
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:
projects / gnus / blobdiff