X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;ds=sidebyside;f=README;h=3c13257560799f84c763dd848476ceabd9bc6852;hb=116cf83f4957f12852882e9f5aef8766cbee3711;hp=c370ac87003b607c1d56a6f7ad97f73f012a892d;hpb=afe1a4421ada9e44c87787257aad124648973e11;p=elisp%2Fepg.git diff --git a/README b/README index c370ac8..3c13257 100644 --- a/README +++ b/README @@ -1,46 +1,125 @@ * What's this? -EasyPG is yet another GnuPG interface for Emacs. It consists of two -parts: transparent file encryption utility and easy-to-use elisp -library to interact with GnuPG. +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). -* Requirements +* Features + +The EasyPG Assistant provides the following features: -** GNU Emacs 21.4 or later +- Keyring browser. +- Cryptographic operations on regions. +- Cryptographic operations on files. +- Dired integration. +- Encryption/decryption of *.gpg files. -** XEmacs 21.4 or later +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, XEmacs 21.4, or later ** GnuPG 1.4.3 or later + If you are using earlier versions, you will need to specify + --disable-gpg-test when ./configure. * Quick start -(0) Put (require 'epg-file) in your ~/.emacs.el +** Installation + + $ ./configure + $ sudo make install + +Add the following line to your ~/.emacs + + (require 'epa-setup) + +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 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. + +** PGG based MUA + +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 -(1) Restart emacs +SEMI is the MIME library used by Wanderlust, cmail, T-gnus, etc. -(2) C-x C-f ~/test.gpg +There is an EasyPG capable SEMI library called EMIKO-EasyPG. It can +be downloaded from the same site of the EasyPG distribution point. -* Advantages over other competitors +* Security -** EasyPG avoides potential security flaws of Emacs. +There are security pitfalls around Emacs. EasyPG is written with +avoiding them. -*** `call-process-region' writes data in region to a temporary file. +** Passphrase may leak to a temporary file. -PGG and gpg.el use `call-process-region' to communicate with a gpg -subprocess. Your passphrases may leak to the filesystem. +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. -*** There is no way to clear strings safely. +The EasyPG Library does not use call-process-region to communicate +with a gpg subprocess. -If Emacs crashed and dumps core, passphrase strings in memory are also -dumped with the core file. `read-passwd' function clears passphrase -strings by `(fillarray string 0)'. However, it is not perfect. Emacs -does compaction of small strings in gc_sweep phase. If GC happens -before `fillarray', passphrase strings may be copied elsewhere in -memory. So, it is recommended that if you are done with passphrase -you should clear it manually. However, PGG and gpg.el enables -passphrase caching by default. +** Passphrase may be stolen from a core file. -** Most GnuPG features are accessible from Emacs +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) 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. -As the name indicates, EasyPG is inspired by GPGME (GnuPG Made Easy), -and the library interface is close to GPGME. +The EasyPG Library dares to disable passphrase caching. Fortunately, +there is more secure way to cache passphrases - use gpg-agent.