X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=epa.texi;h=30eb53e4dbba66a552150dbf841222bc7354b7a7;hb=783afd037113f1b69226ea32051307bc1ab4917c;hp=5a00b1260ee6ad9ac983f4576b6513a86865cbe6;hpb=d9088a130d92929bd78fa83dc1f9fb94e7c35ae2;p=elisp%2Fepg.git diff --git a/epa.texi b/epa.texi index 5a00b12..30eb53e 100644 --- a/epa.texi +++ b/epa.texi @@ -46,9 +46,20 @@ Free Documentation License". @end tex +@summarycontents +@contents + @node Top @top EasyPG Assistant user's manual +EasyPG Assistant is an Emacs user interface for 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. + +@noindent This manual covers EasyPG version @value{VERSION}. @menu @@ -60,20 +71,15 @@ This manual covers EasyPG version @value{VERSION}. @node Overview @chapter Overview -EasyPG is an all-in-one GnuPG (@pxref{Top, , Top, gnupg, Using the GNU -Privacy Guard}) interface for Emacs. It has two aspects: convenient -tools which allow to use GnuPG from Emacs (EasyPG Assistant), and a -fully functional interface library to GnuPG (EasyPG Library). This -manual describes EasyPG Assistant specifically. - -The EasyPG Assistant provides the following features. +EasyPG Assistant provides the following features. @itemize @bullet -@item Keyring browser. +@item Key manegement. @item Cryptographic operations on regions. @item Cryptographic operations on files. @item Dired integration. -@item Encryption/decryption of *.gpg files. +@item Mail-mode integration. +@item Automatic encryption/decryption of *.gpg files. @end itemize @node Quick start @@ -81,18 +87,24 @@ The EasyPG Assistant provides the following features. To install, just follow the standard CMMI installation instructions. +@cartouche @example $ ./configure $ sudo make install @end example +@end cartouche +@noindent Then, add the following line to your @file{~/.emacs} +@cartouche @lisp (require 'epa-setup) @end lisp +@end cartouche -That's all. Restart emacs and type @kbd{M-x epa- TAB}, and you will see a +@noindent +That's all. Restart emacs and type @kbd{M-x epa- @key{TAB}}, and you will see a lot of commands available. For example, @itemize @bullet @@ -101,30 +113,22 @@ lot of commands available. For example, @item To create a cleartext signature of the region, type @kbd{M-x epa-sign-region} @end itemize -You can also do some cryptographic operations from dired. - -@example -M-x dired -(mark some files) -: e (or M-x epa-dired-do-encrypt) -(select recipients by 'm' and click [OK]) -@end example - @node Commands @chapter Commands This chapter introduces various commands for typical use cases. @menu -* Keyring browser:: +* Key management:: * Cryptographic operations on regions:: * Cryptographic operations on files:: * Dired integration:: +* Mail-mode integration:: * Encrypting/decrypting *.gpg files:: @end menu -@node Keyring browser -@section Keyring browser +@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. @@ -133,24 +137,20 @@ keyring. @kbd{M-x epa-list-keys} is corresponding to @samp{gpg 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 -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 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 @kbd{TAB}. If you type @kbd{RET} or -clicked button1 on an entry, you will see more detailed information +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 @@ -167,24 +167,63 @@ about the key you selected. 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 @samp{*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 plaintext. +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 ASCII armors in the region +@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 ASCII armors. +command does not alter the original text around armors. @end deffn @deffn Command epa-verify-region start end @@ -205,15 +244,15 @@ not alter the original text around OpenPGP cleartext blocks. @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 to select signing keys, and then a signature +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 to select recipients. If a prefix argument is given, it will -also ask you whether or not to sign the plaintext before encryption -and if you answered yes, it will let you to select the signing keys. +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 @@ -228,16 +267,59 @@ 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 to +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 to select 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 to help composing clearsigned +or OpenPGP armored encrypted mails. The following keys are assigned. + (not yet written.) @node Encrypting/decrypting *.gpg files @@ -261,16 +343,31 @@ Disable automatic encryption/decryption of *.gpg files. Enable automatic encryption/decryption of *.gpg files. @end deffn -@code{epa-file} will let you to select recipients. If you want to -suppress this question, it might be good idea to put the following -line on the first line of the plaintext. +@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. +@vindex epa-file-encrypt-to +@cartouche @lisp ;; -*- epa-file-encrypt-to: ("ueno@@unixuser.org") -*- @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 -@summarycontents -@contents @bye @c End: