@c %**start of header
@setfilename ../../info/epa
@settitle EasyPG Assistant User's Manual
+@documentencoding UTF-8
@c %**end of header
@set VERSION 1.0.0
@copying
This file describes EasyPG Assistant @value{VERSION}.
-Copyright @copyright{} 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
+Copyright @copyright{} 2007--2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
any later version published by the Free Software Foundation; with no
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''
-in the Emacs manual.
+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.''
-
-This document is part of a collection distributed under the GNU Free
-Documentation License. If you want to distribute this document
-separately from the collection, you can do so by adding a copy of the
-license to the document, as described in section 6 of the license.
+modify this GNU manual.''
@end quotation
@end copying
@end ifnottex
@menu
-* Overview::
-* Quick start::
-* Commands::
+* Overview::
+* Quick start::
+* Commands::
+* Caching Passphrases::
+* Bug Reports::
+* GNU Free Documentation License:: The license for this documentation.
+* Key Index::
+* Function Index::
+* Variable Index::
@end menu
@node Overview
EasyPG Assistant provides several cryptographic features which can be
integrated into other Emacs functionalities. For example, automatic
-encryption/decryption of @samp{*.gpg} files.
+encryption/decryption of @file{*.gpg} files.
@node Commands
@chapter Commands
This chapter introduces various commands for typical use cases.
@menu
-* Key management::
-* Cryptographic operations on regions::
-* Cryptographic operations on files::
-* Dired integration::
-* Mail-mode integration::
-* Encrypting/decrypting *.gpg files::
+* Key management::
+* Cryptographic operations on regions::
+* Cryptographic operations on files::
+* Dired integration::
+* Mail-mode integration::
+* Encrypting/decrypting gpg files::
@end menu
@node Key management
@end deffn
@noindent
-In @samp{*Keys*} buffer, several commands are available. The common
+In @file{*Keys*} buffer, several commands are available. The common
use case is to export some keys to a file. To do that, type @kbd{m}
to select keys, type @kbd{o}, and then supply the filename.
@node Cryptographic operations on files
@section Cryptographic operations on files
-@deffn Command epa-decrypt-file file
-Decrypt @var{file}.
+@deffn Command epa-decrypt-file file &optional output
+Decrypt @var{file}. If you do not specify the name @var{output} to
+use for the decrypted file, this function prompts for the value to use.
@end deffn
@deffn Command epa-verify-file file
@section Mail-mode integration
EasyPG Assistant provides a minor mode @code{epa-mail-mode} to help
-user compose inline PGP messages. Inline PGP is a traditional style
-of sending signed/encrypted emails by embedding raw OpenPGP blobs
-inside a message body, not using modern MIME format.
+user compose inline OpenPGP messages. Inline OpenPGP is a traditional
+style of sending signed/encrypted emails by embedding raw OpenPGP
+blobs inside a message body, not using modern MIME format.
-NOTE: Inline PGP is not recommended and you should consider to use
-PGP/MIME. See
+NOTE: Inline OpenPGP is not recommended and you should consider to use
+PGP/MIME@. See
@uref{http://josefsson.org/inline-openpgp-considered-harmful.html,
-Inline PGP in E-mail is bad, Mm'kay?}.
+Inline OpenPGP in E-mail is bad@comma{} Mm'kay?}.
@noindent
Once @code{epa-mail-mode} is enabled, the following keys are assigned.
interface. Try @kbd{M-x customize-variable epa-global-mail-mode}.
@table @kbd
-@item C-c C-e d
+@item C-c C-e C-d and C-c C-e d
+@kindex @kbd{C-c C-e C-d}
@kindex @kbd{C-c C-e d}
@findex epa-mail-decrypt
Decrypt OpenPGP armors in the current buffer.
-@item C-c C-e v
+@item C-c C-e C-v and C-c C-e v
+@kindex @kbd{C-c C-e C-v}
@kindex @kbd{C-c C-e v}
@findex epa-mail-verify
Verify OpenPGP cleartext signed messages in the current buffer.
-@item C-c C-e s
+@item C-c C-e C-s and C-c C-e s
+@kindex @kbd{C-c C-e C-s}
@kindex @kbd{C-c C-e s}
@findex epa-mail-sign
Compose a signed message from the current buffer.
-@item C-c C-e e
+@item C-c C-e C-e and C-c C-e e
+@kindex @kbd{C-c C-e C-e}
@kindex @kbd{C-c C-e e}
@findex epa-mail-encrypt
+@vindex epa-mail-aliases
Compose an encrypted message from the current buffer.
By default it tries to build the recipient list from @samp{to},
@samp{cc}, and @samp{bcc} fields of the mail header. To include your
key in the recipient list, use @samp{encrypt-to} option in
-@file{~/.gnupg/gpg.conf}.
+@file{~/.gnupg/gpg.conf}. This function translates recipient
+addresses using the @code{epa-mail-aliases} list. You can also
+use that option to ignore specific recipients for encryption purposes.
@end table
-@node Encrypting/decrypting *.gpg files
-@section Encrypting/decrypting *.gpg files
-By default, every file whose extension is @samp{.gpg} will be treated
-as encrypted. That is, when you attempt to open such a file which
-already exists, the decrypted text is inserted in the buffer rather
-than encrypted one. On the other hand, when you attempt to save the
-buffer to a file whose extension is @samp{.gpg}, encrypted data is
-written.
+@node Encrypting/decrypting gpg files
+@section Encrypting/decrypting gpg files
+By default, every file whose name ends with @file{.gpg} will be
+treated as encrypted. That is, when you open such a file, the
+decrypted text is inserted in the buffer rather than encrypted one.
+Similarly, when you save the buffer to a @file{foo.gpg} file,
+encrypted data is written.
+
+The file name pattern for encrypted files can be controlled by
+@var{epa-file-name-regexp}.
+
+@defvar epa-file-name-regexp
+Regexp which matches filenames treated as encrypted.
+@end defvar
-If you want to temporarily disable this behavior, use @kbd{M-x
-epa-file-disable}, and then to enable this behavior use @kbd{M-x
-epa-file-enable}.
+You can disable this behavior with @kbd{M-x epa-file-disable}, and
+then get it back with @kbd{M-x epa-file-enable}.
@deffn Command epa-file-disable
Disable automatic encryption/decryption of *.gpg files.
@end deffn
@noindent
-@code{epa-file} will let you select recipients. If you want to
-suppress this question, it might be a good idea to put the following
-line on the first line of the text being encrypted.
+By default, @code{epa-file} will try to use symmetric encryption, aka
+password-based encryption. If you want to use public key encryption
+instead, do @kbd{M-x epa-file-select-keys}, which will pops up the key
+selection dialog.
+
+@deffn Command epa-file-select-keys
+Select recipient keys to encrypt the currently visiting file with
+public key encryption.
+@end deffn
+
+You can also change the default behavior with the variable
+@var{epa-file-select-keys}.
+
+@defvar epa-file-select-keys
+Control whether or not to pop up the key selection dialog.
+@end defvar
+
+For frequently visited files, it might be a good idea to tell Emacs
+which encryption method should be used through @xref{File Variables, ,
+, emacs, the Emacs Manual}. Use the @code{epa-file-encrypt-to} local
+variable for this.
@vindex epa-file-encrypt-to
+For example, if you want an Elisp file to be encrypted with a
+public key associated with an email address @samp{ueno@@unixuser.org},
+add the following line to the beginning of the file.
+
@cartouche
@lisp
;; -*- epa-file-encrypt-to: ("ueno@@unixuser.org") -*-
@end lisp
@end cartouche
-The file name extension of encrypted files can be controlled by
-@var{epa-file-name-regexp}.
+Instead, if you want the file always (regardless of the value of the
+@code{epa-file-select-keys} variable) encrypted with symmetric
+encryption, change the line as follows.
-@defvar epa-file-name-regexp
-Regexp which matches filenames treated as encrypted.
-@end defvar
+@cartouche
+@lisp
+;; -*- epa-file-encrypt-to: nil -*-
+@end lisp
+@end cartouche
Other variables which control the automatic encryption/decryption
behavior are below.
The default value is @code{t}.
@end defvar
+@node Caching Passphrases
+@chapter Caching Passphrases
+
+Typing passphrases is an irritating task if you frequently open and
+close the same file. GnuPG and EasyPG Assistant provide mechanisms to
+remember your passphrases. However, the configuration is a bit
+confusing since it depends on your GnuPG installation (GnuPG version 1 or
+GnuPG version 2), encryption method (symmetric or public key), and whether or
+not you want to use gpg-agent. Here are some questions:
+
+@enumerate
+@item Do you use GnuPG version 2 instead of GnuPG version 1?
+@item Do you use symmetric encryption rather than public key encryption?
+@item Do you want to use gpg-agent?
+@end enumerate
+
+Here are configurations depending on your answers:
+
+@multitable {111} {222} {333} {configuration configuration configuration}
+@item @b{1} @tab @b{2} @tab @b{3} @tab Configuration
+@item Yes @tab Yes @tab Yes @tab Set up gpg-agent.
+@item Yes @tab Yes @tab No @tab You can't, without gpg-agent.
+@item Yes @tab No @tab Yes @tab Set up gpg-agent.
+@item Yes @tab No @tab No @tab You can't, without gpg-agent.
+@item No @tab Yes @tab Yes @tab Set up elisp passphrase cache.
+@item No @tab Yes @tab No @tab Set up elisp passphrase cache.
+@item No @tab No @tab Yes @tab Set up gpg-agent.
+@item No @tab No @tab No @tab You can't, without gpg-agent.
+@end multitable
+
+To set up gpg-agent, follow the instruction in GnuPG manual.
+@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}.
+
+To set up elisp passphrase cache, set
+@code{epa-file-cache-passphrase-for-symmetric-encryption}.
+@xref{Encrypting/decrypting gpg files}.
+
+@node Bug Reports
+@chapter Bug Reports
+
+Bugs and problems with EasyPG Assistant are actively worked on by the
+Emacs development team. Feature requests and suggestions are also
+more than welcome. Use @kbd{M-x report-emacs-bug}, @pxref{Bugs, ,
+Bugs, emacs, Reporting Bugs}.
+
+When submitting a bug report, please try to describe in excruciating
+detail the steps required to reproduce the problem. Also try to
+collect necessary information to fix the bug, such as:
+
+@itemize @bullet
+@item the GnuPG version. Send the output of @samp{gpg --version}.
+@item the GnuPG configuration. Send the contents of @file{~/.gnupg/gpg.conf}.
+@end itemize
+
+Before reporting the bug, you should set @code{epg-debug} in the
+@file{~/.emacs} file and repeat the bug. Then, include the contents
+of the @file{ *epg-debug*} buffer. Note that the first letter of the
+buffer name is a whitespace.
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Key Index
+@unnumbered Key Index
+@printindex ky
+
+@node Function Index
+@unnumbered Function Index
+@printindex fn
+
+@node Variable Index
+@unnumbered Variable Index
+@printindex vr
+
@bye
@c End:
-
-@ignore
- arch-tag: 7404e246-7d4c-4db4-9332-c1293a455a4f
-@end ignore