\input texinfo @c -*- mode: texinfo -*-@c %**start of header@setfilename ../../info/epa@settitle EasyPG Assistant User's Manual@c %**end of header@set VERSION 1.0.0@copyingThis file describes EasyPG Assistant @value{VERSION}.Copyright @copyright{} 2007, 2008, 2009, 2010 Free Software Foundation, Inc.@quotationPermission is granted to copy, distribute and/or modify this documentunder the terms of the GNU Free Documentation License, Version 1.3 orany later version published by the Free Software Foundation; with noInvariant Sections, with the Front-Cover texts being ``A GNU Manual,''and with the Back-Cover Texts as in (a) below. A copy of the licenseis included in the section entitled ``GNU Free Documentation License''in the Emacs manual.(a) The FSF's Back-Cover Text is: ``You have the freedom to copy andmodify this GNU manual. Buying copies from the FSF supports it indeveloping GNU and promoting software freedom.''This document is part of a collection distributed under the GNU FreeDocumentation License. If you want to distribute this documentseparately from the collection, you can do so by adding a copy of thelicense to the document, as described in section 6 of the license.@end quotation@end copying@dircategory Emacs@direntry* EasyPG Assistant: (epa). An Emacs user interface to GNU Privacy Guard.@end direntry@titlepage@title EasyPG Assistant@author by Daiki Ueno@page@vskip 0pt plus 1filll@insertcopying@end titlepage@contents@node Top@top EasyPG Assistant user's manualEasyPG Assistant is an Emacs user interface to GNU Privacy Guard(GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}).EasyPG Assistant is a part of the package called EasyPG, an all-in-oneGnuPG interface for Emacs. EasyPG also contains the library interfacecalled EasyPG Library.@ifnottex@insertcopying@end ifnottex@menu* Overview:: * Quick start:: * Commands:: * Caching Passphrases:: * Bug Reports:: @end menu@node Overview@chapter OverviewEasyPG Assistant provides the following features.@itemize @bullet@item Key management.@item Cryptographic operations on regions.@item Cryptographic operations on files.@item Dired integration.@item Mail-mode integration.@item Automatic encryption/decryption of *.gpg files.@end itemize@node Quick start@chapter Quick startEasyPG Assistant commands are prefixed by @samp{epa-}. For example,@itemize @bullet@item To browse your keyring, type @kbd{M-x epa-list-keys}@item To create a cleartext signature of the region, type @kbd{M-x epa-sign-region}@item To encrypt a file, type @kbd{M-x epa-encrypt-file}@end itemizeEasyPG Assistant provides several cryptographic features which can beintegrated into other Emacs functionalities. For example, automaticencryption/decryption of @samp{*.gpg} files.@node Commands@chapter CommandsThis 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:: @end menu@node Key management@section Key managementProbably the first step of using EasyPG Assistant is to browse yourkeyring. @kbd{M-x epa-list-keys} is corresponding to @samp{gpg--list-keys} from the command line.@deffn Command epa-list-keys name modeShow all keys matched with @var{name} from the public keyring.@end deffn@noindentThe output looks as follows.@example u A5B6B2D4B15813FE Daiki Ueno <ueno@@unixuser.org>@end example@noindentA character on the leftmost column indicates the trust level of thekey. If it is @samp{u}, the key is marked as ultimately trusted. Thesecond column is the key ID, and the rest is the user ID.You can move over entries by @key{TAB}. If you type @key{RET} orclick button1 on an entry, you will see more detailed informationabout the key you selected.@example u Daiki Ueno <ueno@@unixuser.org> u A5B6B2D4B15813FE 1024bits DSA Created: 2001-10-09 Expires: 2007-09-04 Capabilities: sign certify Fingerprint: 8003 7CD0 0F1A 9400 03CA 50AA A5B6 B2D4 B158 13FE u 4447461B2A9BEA2D 2048bits ELGAMAL_E Created: 2001-10-09 Expires: 2007-09-04 Capabilities: encrypt Fingerprint: 9003 D76B 73B7 4A8A E588 10AF 4447 461B 2A9B EA2D@end example@noindentTo browse your private keyring, use @kbd{M-x epa-list-secret-keys}.@deffn Command epa-list-secret-keys nameShow all keys matched with @var{name} from the private keyring.@end deffn@noindentIn @samp{*Keys*} buffer, several commands are available. The commonuse 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.Below are other commands related to key management. Some of them takea file as input/output, and others take the current region.@deffn Command epa-insert-keys keysInsert selected @var{keys} after the point. It will let you selectkeys before insertion. By default, it will encode keys in the OpenPGParmor format.@end deffn@deffn Command epa-import-keys fileImport keys from @var{file} to your keyring.@end deffn@deffn Command epa-import-keys-region start endImport keys from the current region between @var{start} and @var{end}to your keyring.@end deffn@deffn Command epa-import-armor-in-region start endImport keys in the OpenPGP armor format in the current region between@var{start} and @var{end}. The difference from@code{epa-import-keys-region} is that@code{epa-import-armor-in-region} searches armors in the region andapplies @code{epa-import-keys-region} to each of them.@end deffn@deffn Command epa-delete-keys allow-secretDelete selected keys. If @var{allow-secret} is non-@code{nil}, italso delete the secret keys.@end deffn@node Cryptographic operations on regions@section Cryptographic operations on regions@deffn Command epa-decrypt-region start endDecrypt the current region between @var{start} and @var{end}. Itreplaces the region with the decrypted text.@end deffn@deffn Command epa-decrypt-armor-in-region start endDecrypt OpenPGP armors in the current region between @var{start} and@var{end}. The difference from @code{epa-decrypt-region} is that@code{epa-decrypt-armor-in-region} searches armors in the regionand applies @code{epa-decrypt-region} to each of them. That is, thiscommand does not alter the original text around armors.@end deffn@deffn Command epa-verify-region start endVerify the current region between @var{start} and @var{end}. It sendsthe verification result to the minibuffer or a popup window. Itreplaces the region with the signed text.@end deffn@deffn Command epa-verify-cleartext-in-regionVerify OpenPGP cleartext blocks in the current region between@var{start} and @var{end}. The difference from@code{epa-verify-region} is that @code{epa-verify-cleartext-in-region}searches OpenPGP cleartext blocks in the region and applies@code{epa-verify-region} to each of them. That is, this command doesnot alter the original text around OpenPGP cleartext blocks.@end deffn@deffn Command epa-sign-region start end signers typeSign the current region between @var{start} and @var{end}. Bydefault, it creates a cleartext signature. If a prefix argument isgiven, it will let you select signing keys, and then a signaturetype.@end deffn@deffn Command epa-encrypt-region start end recipients sign signersEncrypt the current region between @var{start} and @var{end}. It willlet you select recipients. If a prefix argument is given, it willalso ask you whether or not to sign the text before encryption and ifyou answered yes, it will let you select the signing keys.@end deffn@node Cryptographic operations on files@section Cryptographic operations on files@deffn Command epa-decrypt-file fileDecrypt @var{file}.@end deffn@deffn Command epa-verify-file fileVerify @var{file}.@end deffn@deffn Command epa-sign-file file signers typeSign @var{file}. If a prefix argument is given, it will let youselect signing keys, and then a signature type.@end deffn@deffn Command epa-encrypt-file file recipientsEncrypt @var{file}. It will let you select recipients.@end deffn@node Dired integration@section Dired integrationEasyPG Assistant extends Dired Mode for GNU Emacs to allow users toeasily do cryptographic operations on files. For example,@exampleM-x dired(mark some files): e (or M-x epa-dired-do-encrypt)(select recipients by 'm' and click [OK])@end example@noindentThe following keys are assigned.@table @kbd@item : d@kindex @kbd{: d}@findex epa-dired-do-decryptDecrypt marked files.@item : v@kindex @kbd{: v}@findex epa-dired-do-verifyVerify marked files.@item : s@kindex @kbd{: s}@findex epa-dired-do-signSign marked files.@item : e@kindex @kbd{: e}@findex epa-dired-do-encryptEncrypt marked files.@end table@node Mail-mode integration@section Mail-mode integrationEasyPG Assistant provides a minor mode @code{epa-mail-mode} to helpuser compose inline OpenPGP messages. Inline OpenPGP is a traditionalstyle of sending signed/encrypted emails by embedding raw OpenPGPblobs inside a message body, not using modern MIME format.NOTE: Inline OpenPGP is not recommended and you should consider to usePGP/MIME. See@uref{http://josefsson.org/inline-openpgp-considered-harmful.html,Inline OpenPGP in E-mail is bad@comma{} Mm'kay?}.@noindentOnce @code{epa-mail-mode} is enabled, the following keys are assigned.You can do it by @kbd{C-u 1 M-x epa-mail-mode} or through the Customizeinterface. Try @kbd{M-x customize-variable epa-global-mail-mode}.@table @kbd@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-decryptDecrypt OpenPGP armors in the current buffer.@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-verifyVerify OpenPGP cleartext signed messages in the current buffer.@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-signCompose a signed message from the current buffer.@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-encryptCompose 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 yourkey in the recipient list, use @samp{encrypt-to} option in@file{~/.gnupg/gpg.conf}.@end table@node Encrypting/decrypting *.gpg files@section Encrypting/decrypting *.gpg filesBy default, every file whose extension is @samp{.gpg} will be treatedas encrypted. That is, when you attempt to open such a file whichalready exists, the decrypted text is inserted in the buffer ratherthan encrypted one. On the other hand, when you attempt to save thebuffer to a file whose extension is @samp{.gpg}, encrypted data iswritten.If you want to temporarily disable this behavior, use @kbd{M-xepa-file-disable}, and then to enable this behavior use @kbd{M-xepa-file-enable}.@deffn Command epa-file-disableDisable automatic encryption/decryption of *.gpg files.@end deffn@deffn Command epa-file-enableEnable automatic encryption/decryption of *.gpg files.@end deffn@noindent@code{epa-file} will let you select recipients. If you want tosuppress this question, it might be a good idea to put the followingline on the first line of the text being encrypted.@vindex epa-file-encrypt-to@cartouche@lisp;; -*- epa-file-encrypt-to: ("ueno@@unixuser.org") -*-@end lisp@end cartoucheThe file name extension of encrypted files can be controlled by@var{epa-file-name-regexp}.@defvar epa-file-name-regexpRegexp which matches filenames treated as encrypted.@end defvarOther variables which control the automatic encryption/decryptionbehavior are below.@defvar epa-file-cache-passphrase-for-symmetric-encryptionIf non-@code{nil}, cache passphrase for symmetric encryption. Thedefault value is @code{nil}.@end defvar@defvar epa-file-inhibit-auto-saveIf non-@code{nil}, disable auto-saving when opening an encrypted file.The default value is @code{t}.@end defvar@node Caching Passphrases@chapter Caching PassphrasesTyping passphrases is an irritating task if you frequently open andclose the same file. GnuPG and EasyPG Assistant provide mechanisms toremember your passphrases. However, the configuration is a bitconfusing since it depends on your GnuPG installation (GnuPG version 1 orGnuPG version 2), encryption method (symmetric or public key), and whether ornot 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 enumerateHere 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 multitableTo 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 ReportsBugs and problems with EasyPG Assistant are actively worked on by theEmacs development team. Feature requests and suggestions are alsomore 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 excruciatingdetail the steps required to reproduce the problem. Also try tocollect 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 itemizeBefore reporting the bug, you should set @code{epg-debug} in the@file{~/.emacs} file and repeat the bug. Then, include the contentsof the @samp{ *epg-debug*} buffer. Note that the first letter of thebuffer name is a whitespace.@bye@c End:@ignore arch-tag: 7404e246-7d4c-4db4-9332-c1293a455a4f@end ignore