X-Git-Url: http://cgit.sxemacs.org/?p=packages;a=blobdiff_plain;f=xemacs-packages%2Fgnus%2Ftexi%2Fepa.texi;fp=xemacs-packages%2Fgnus%2Ftexi%2Fepa.texi;h=07b6af4ac082c2f10a211dc295c661bbf62aa98a;hp=0000000000000000000000000000000000000000;hb=264824bc7542eec5be4349263b36e13c713e61a5;hpb=e10974b04b06bb129bf57b2c9edfc950caabc073 diff --git a/xemacs-packages/gnus/texi/epa.texi b/xemacs-packages/gnus/texi/epa.texi new file mode 100644 index 00000000..07b6af4a --- /dev/null +++ b/xemacs-packages/gnus/texi/epa.texi @@ -0,0 +1,519 @@ +\input texinfo @c -*- mode: texinfo -*- +@c %**start of header +@setfilename epa.info +@settitle EasyPG Assistant User's Manual +@include docstyle.texi +@c %**end of header + +@set VERSION 1.0.0 + +@copying +This file describes EasyPG Assistant @value{VERSION}. + +Copyright @copyright{} 2007--2016 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.3 or +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''. + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual.'' +@end quotation +@end copying + +@dircategory Emacs misc features +@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 manual + +EasyPG 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-one +GnuPG interface for Emacs. EasyPG also contains the library interface +called EasyPG Library. + +@ifnottex +@insertcopying +@end ifnottex + +@menu +* 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 +@chapter Overview + +EasyPG 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 start + +EasyPG 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 itemize + +EasyPG Assistant provides several cryptographic features which can be +integrated into other Emacs functionalities. For example, automatic +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:: +@end menu + +@node Key management +@section Key management +Probably the first step of using EasyPG Assistant is to browse your +keyring. @kbd{M-x epa-list-keys} is corresponding to @samp{gpg +--list-keys} from the command line. + +@deffn Command epa-list-keys name mode +Show all keys matched with @var{name} from the public keyring. +@end deffn + +@noindent +The output looks as follows. + +@example + u A5B6B2D4B15813FE Daiki Ueno +@end example + +@noindent +A character on the leftmost column indicates the trust level of the +key. If it is @samp{u}, the key is marked as ultimately trusted. The +second 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} or +click button1 on an entry, you will see more detailed information +about the key you selected. + +@example + u Daiki Ueno + 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 + +@noindent +To browse your private keyring, use @kbd{M-x epa-list-secret-keys}. + +@deffn Command epa-list-secret-keys name +Show all keys matched with @var{name} from the private keyring. +@end deffn + +@noindent +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. + +Below are other commands related to key management. Some of them take +a file as input/output, and others take the current region. + +@deffn Command epa-insert-keys keys +Insert selected @var{keys} after the point. It will let you select +keys before insertion. By default, it will encode keys in the OpenPGP +armor format. +@end deffn + +@deffn Command epa-import-keys file +Import keys from @var{file} to your keyring. +@end deffn + +@deffn Command epa-import-keys-region start end +Import keys from the current region between @var{start} and @var{end} +to your keyring. +@end deffn + +@deffn Command epa-import-armor-in-region start end +Import 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 and +applies @code{epa-import-keys-region} to each of them. +@end deffn + +@deffn Command epa-delete-keys allow-secret +Delete selected keys. If @var{allow-secret} is non-@code{nil}, it +also delete the secret keys. +@end deffn + +@node Cryptographic operations on regions +@section Cryptographic operations on regions + +@deffn Command epa-decrypt-region start end +Decrypt the current region between @var{start} and @var{end}. It +replaces the region with the decrypted text. +@end deffn + +@deffn Command epa-decrypt-armor-in-region start end +Decrypt 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 region +and applies @code{epa-decrypt-region} to each of them. That is, this +command does not alter the original text around armors. +@end deffn + +@deffn Command epa-verify-region start end +Verify the current region between @var{start} and @var{end}. It sends +the verification result to the minibuffer or a popup window. It +replaces the region with the signed text. +@end deffn + +@deffn Command epa-verify-cleartext-in-region +Verify 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 does +not alter the original text around OpenPGP cleartext blocks. +@end deffn + +@deffn Command epa-sign-region start end signers type +Sign the current region between @var{start} and @var{end}. By +default, it creates a cleartext signature. If a prefix argument is +given, it will let you select signing keys, and then a signature +type. +@end deffn + +@deffn Command epa-encrypt-region start end recipients sign signers +Encrypt the current region between @var{start} and @var{end}. It will +let you select recipients. If a prefix argument is given, it will +also ask you whether or not to sign the text before encryption and if +you 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 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 +Verify @var{file}. +@end deffn + +@deffn Command epa-sign-file file signers type +Sign @var{file}. If a prefix argument is given, it will let you +select signing keys, and then a signature type. +@end deffn + +@deffn Command epa-encrypt-file file recipients +Encrypt @var{file}. It will let you select recipients. +@end deffn + +@node Dired integration +@section Dired integration + +EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to +easily do cryptographic operations on files. For example, + +@example +M-x dired +(mark some files) +: e (or M-x epa-dired-do-encrypt) +(select recipients by 'm' and click [OK]) +@end example + +@noindent +The following keys are assigned. + +@table @kbd +@item : d +@kindex @kbd{: d} +@findex epa-dired-do-decrypt +Decrypt marked files. + +@item : v +@kindex @kbd{: v} +@findex epa-dired-do-verify +Verify marked files. + +@item : s +@kindex @kbd{: s} +@findex epa-dired-do-sign +Sign marked files. + +@item : e +@kindex @kbd{: e} +@findex epa-dired-do-encrypt +Encrypt marked files. + +@end table + +@node Mail-mode integration +@section Mail-mode integration + +EasyPG Assistant provides a minor mode @code{epa-mail-mode} to help +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 OpenPGP is not recommended and you should consider to use +PGP/MIME@. See +@uref{http://josefsson.org/inline-openpgp-considered-harmful.html, +Inline OpenPGP in E-mail is bad@comma{} Mm'kay?}. + +@noindent +Once @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 Customize +interface. 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-decrypt +Decrypt 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-verify +Verify 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-sign +Compose 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-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}. 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 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 + +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 + +@deffn Command epa-file-enable +Enable automatic encryption/decryption of *.gpg files. +@end deffn + +@noindent +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 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 + +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. + +@cartouche +@lisp +;; -*- epa-file-encrypt-to: nil -*- +@end lisp +@end cartouche + +Other variables which control the automatic encryption/decryption +behavior are below. + +@defvar epa-file-cache-passphrase-for-symmetric-encryption +If non-@code{nil}, cache passphrase for symmetric encryption. The +default value is @code{nil}. +@end defvar + +@defvar epa-file-inhibit-auto-save +If non-@code{nil}, disable auto-saving when opening an encrypted file. +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: