X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=README;h=3c13257560799f84c763dd848476ceabd9bc6852;hb=116cf83f4957f12852882e9f5aef8766cbee3711;hp=155ed1e3194796441a40c32ad0d57b8911cc5754;hpb=3b0d763848664a3d411031de8b2595221a2fe40f;p=elisp%2Fepg.git diff --git a/README b/README index 155ed1e..3c13257 100644 --- a/README +++ b/README @@ -1,19 +1,33 @@ * What's this? -EasyPG is yet another GnuPG interface for Emacs. It consists of two parts: +EasyPG is an all-in-one GnuPG 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). -- "The EasyPG Assistant" - A GUI frontend of GnuPG -- "The EasyPG Library" - A library which makes access to GnuPG easier for applications +* Features -NOTE: EasyPG is neither a fork nor a re-implementation of Gnus/PGG. +The EasyPG Assistant provides the following features: + +- Keyring browser. +- Cryptographic operations on regions. +- Cryptographic operations on files. +- Dired integration. +- Encryption/decryption of *.gpg files. + +The EasyPG Library provides the following features: + +- The API covers most functions of GnuPG like GPGME. +- S/MIME support using gpgsm. +- Designed to avoid potential security pitfalls around Emacs * Requirements -** GNU Emacs 21.4 or XEmacs 21.4 +** GNU Emacs 21.4, XEmacs 21.4, or later -** GnuPG 1.4.3 +** GnuPG 1.4.3 or later + If you are using earlier versions, you will need to specify + --disable-gpg-test when ./configure. * Quick start @@ -26,34 +40,86 @@ Add the following line to your ~/.emacs (require 'epa-setup) -Then you can browse your keyring by `M-x epa-list-keys'. In addition, -you can do some cryptographic operations on dired. +Restart emacs and type `M-x epa- TAB', and you will see a lot of +commands available. For example, + +- To browse your keyring, type `M-x epa-list-keys' +- To create a cleartext signature of the region, type `M-x epa-sign-region' + +You can also do some cryptographic operations from dired. M-x dired (mark some files) - : e (or M-x epg-dired-do-encrypt) - (select recipients and click [OK]) + : e (or M-x epa-dired-do-encrypt) + (select recipients by 'm' and click [OK]) + +* MUA Integration + +The EasyPG Library can be used in combination with various MUA (Mail +User Agents). + +** CVS version of Gnus + +CVS version of Gnus uses EasyPG by default. To make sure of that, +check mml2015-use set to 'epg. Other options which affect on the +EasyPG are + + mml2015-signers + mml2015-encrypt-to-self + mml2015-cache-passphrase + mml2015-passphrase-cache-expiry + mml2015-verbose + +NOTE: You don't need pgg-epg.el in this case. -* Security consideration +** PGG based MUA -There are security pitfalls around Emacs. +PGG is outdated PGP library used by old Gnus (<= v5.11), MH-E, etc. + +There is a PGG backend written using EasyPG called pgg-epg.el. +However, EasyPG API is a superset of PGG and pgg-epg.el provides +nothing but compatibility with PGG. + +*** Limitations of PGG + +As I noted "PGG is outdated PGP library" above, PGG has several +limitations. For example + +- PGG can't handle a message signed with multiple keys. +- PGG can't prompt a user which key is being used. +- PGG can't create a binary PGP messages. +- PGG doesn't provide a way to select keys per cryptographic operation. +- PGG ignores GnuPG's trust metrics. + +** SEMI based MUA + +SEMI is the MIME library used by Wanderlust, cmail, T-gnus, etc. + +There is an EasyPG capable SEMI library called EMIKO-EasyPG. It can +be downloaded from the same site of the EasyPG distribution point. + +* Security + +There are security pitfalls around Emacs. EasyPG is written with +avoiding them. ** Passphrase may leak to a temporary file. -`call-process-region' writes data in region to a temporary file. -The EasyPG Library does not use `call-process-region' to communicate with a gpg -subprocess. +The function call-process-region writes data in region to a temporary +file. If your PGP library used this function, your passphrases would +leak to the filesystem. + +The EasyPG Library does not use call-process-region to communicate +with a gpg subprocess. ** Passphrase may be stolen from a core file. If Emacs crashes and dumps core, Lisp strings in memory are also -dumped within the core file. `read-passwd' function clears passphrase -strings by `(fillarray string 0)'. However, Emacs performs compaction -in gc_sweep phase. If GC happens before `fillarray', passphrase -strings may be moved elsewhere in memory. Therefore, passphrase -caching in elisp is generally a bad idea. - -The EasyPG Library dares to disable passphrase caching. Fortunately, -there is more secure way to cache passphrases - use gpg-agent. Elisp -programs can set `epg-context-passphrase-callback' to cache user's -passphrases, it is not recommended though. +dumped within the core file. read-passwd function clears passphrase +strings by (fillarray string 0) to avoid this risk. However, Emacs +performs compaction in gc_sweep phase. If GC happens before fillarray, +passphrase strings may be moved elsewhere in memory. Therefore, +passphrase caching in elisp is generally a bad idea. + +The EasyPG Library dares to disable passphrase caching. Fortunately, +there is more secure way to cache passphrases - use gpg-agent.