X-Git-Url: http://cgit.sxemacs.org/?a=blobdiff_plain;f=texi%2Fpgg.texi;h=4d5c7731594dfc70542630039e4ed5c1e265d8f5;hb=5df93a963e4bdf16117d251fc00c033201a9133a;hp=2af115d94c10b99a7c52fce232dec520674ab050;hpb=300b081b5d4089cf9830cc987a323623adb36e12;p=gnus diff --git a/texi/pgg.texi b/texi/pgg.texi index 2af115d94..4d5c77315 100644 --- a/texi/pgg.texi +++ b/texi/pgg.texi @@ -1,65 +1,74 @@ \input texinfo @c -*-texinfo-*- +@include gnus-overrides.texi + @setfilename pgg +@settitle PGG @value{VERSION} @set VERSION 0.1 -@direntry -* PGG: (pgg). Emacs interface to various PGP implementations. -@end direntry +@copying +This file describes PGG @value{VERSION}, an Emacs interface to various +PGP implementations. -@settitle PGG @value{VERSION} - -@ifinfo -This file describes the PGG. - -Copyright (C) 2003, 2004 Free Software Foundation, Inc. -Copyright (C) 2001 Daiki Ueno. +Copyright @copyright{} 2001, 2003-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.1 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". -@end ifinfo +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.'' -@tex +(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 network features +@direntry +* PGG: (pgg). Emacs interface to various PGP implementations. +@end direntry @titlepage +@ifset WEBHACKDEVEL +@title PGG (DEVELOPMENT VERSION) +@end ifset +@ifclear WEBHACKDEVEL @title PGG +@end ifclear @author by Daiki Ueno @page @vskip 0pt plus 1filll -Copyright @copyright{} 2001 Daiki Ueno. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 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". +@insertcopying @end titlepage -@page -@end tex +@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:: -* Function Index:: -* Variable Index:: +* Architecture:: +* Parsing OpenPGP packets:: +* GNU Free Documentation License:: The license for this documentation. +* Function Index:: +* Variable Index:: @end menu @node Overview @@ -80,10 +89,19 @@ PGG requires at least one implementation of privacy guard system. 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 @@ -104,6 +122,8 @@ list autoload setting for desired functions as follows. @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" @@ -117,10 +137,10 @@ list autoload setting for desired functions as follows. @end lisp @menu -* User Commands:: -* Selecting an implementation:: -* Caching passphrase:: -* Default user identity:: +* User Commands:: +* Selecting an implementation:: +* Caching passphrase:: +* Default user identity:: @end menu @node User Commands @@ -133,7 +153,7 @@ signer's public key, for example, the function @code{pgg-verify-region} 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. @@ -141,29 +161,48 @@ would be asked about the recipients. If encryption is successful, it replaces the current region contents (in the accessible portion) with the resulting data. -If optional argument @var{sign} is non-nil, the function is request to -do a combined sign and encrypt. This currently only work with GnuPG. +If optional argument @var{sign} is non-@code{nil}, the function is +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-decrypt-region start end +@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 &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 @@ -188,40 +227,98 @@ considerably. For example, if you are using GnuPG, you know you can 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 @@ -261,13 +358,13 @@ singleton object wrapped with the luna object system. Since PGG was designed for accessing and developing PGP functionality, the architecture had to be designed not just for interoperability but -also for extensiblity. In this chapter we explore the architecture -while finding out how to write the PGG backend. +also for extensibility. In this chapter we explore the architecture +while finding out how to write the PGG back end. @menu -* Initializing:: -* Backend methods:: -* Getting output:: +* Initializing:: +* Back end methods:: +* Getting output:: @end menu @node Initializing @@ -286,16 +383,16 @@ 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 -regulation---@code{pgg-make-scheme-} follows the backend name. +regulation---@code{pgg-make-scheme-} follows the back end name. -@node Backend methods -@section Backend methods +@node Back end methods +@section Back end methods -In each backend, these methods must be present. The output of these +In each back end, these methods must be present. The output of these methods is stored in special buffers (@ref{Getting output}), so that these methods must tell the status of the execution. @@ -305,19 +402,26 @@ argument @var{type} is non-@code{nil}, it searches from the secret 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-nil, do a combined sign and -encrypt. If encryption is successful, it returns @code{t}, otherwise -@code{nil}. +@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 @@ -345,7 +449,7 @@ On success, it returns @code{t}, otherwise @code{nil}. @node Getting output @section Getting output -The output of the backend methods (@ref{Backend methods}) is stored in +The output of the back end methods (@ref{Back end methods}) is stored in special buffers, so that these methods must tell the status of the execution. @@ -385,16 +489,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: