Fixed indentation.

[elisp/epg.git] / README

diff --git a/README b/README
index c370ac8..64700a6 100644 (file)
--- a/README
+++ b/README
@@ -1,46 +1,63 @@
 * What's this?
 
 * 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 yet another GnuPG interface for Emacs.  It consists of two parts:

 
 

-* Requirements
+epa.el - EasyPG Assistant, a basic GUI of GnuPG
+epg.el - the EasyPG library which interacts with GnuPG
+
+NOTE: EasyPG is not a fork or a re-implementation of Gnus/PGG.

 
 

-** GNU Emacs 21.4 or later
+* Requirements

 
 

-** XEmacs 21.4 or later
+** GNU Emacs 21.4 or later, XEmacs 21.4 or later

 
 ** GnuPG 1.4.3 or later
 
 * Quick start
 
 
 ** GnuPG 1.4.3 or later
 
 * Quick start
 

-(0) Put (require 'epg-file) in your ~/.emacs.el
+** Installation

 
 

-(1) Restart emacs
+$ ./configure
+$ sudo make install

 
 

-(2) C-x C-f ~/test.gpg
+Add the following line to your ~/.emacs
+
+(require 'epa-setup)

 
 * Advantages over other competitors
 
 
 * Advantages over other competitors
 

-** EasyPG avoides potential security flaws of Emacs.
+There are many competitors of EasyPG such as Mailcrypt, Gnus/PGG,
+gpg.el, etc.  EasyPG has some advantages over them.
+
+** EasyPG avoides potential security flaws of Emacs
+
+See "Security consideration" section.
+
+** GnuPG features are directly accessible from Emacs
+
+Other competitors provide only specific features of GnuPG since they
+still support PGP 2.*, 5.*, 6.*.  As the name indicates, EasyPG is
+inspired by GPGME (GnuPG Made Easy), and the library interface is
+close to GPGME.  With EasyPG you can benefit from a lot of features of
+GnuPG.
+
+* Security consideration

 
 

-*** `call-process-region' writes data in region to a temporary file.
+** `call-process-region' writes data in region 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.
+`call-process-region' writes data in region to a temporary file.
+EasyPG does *not* use `call-process-region' to communicate with a gpg
+subprocess.

 
 

-*** There is no way to clear strings safely.
+** `(fillarray string 0)' is not enough to clear passphrases

 
 If Emacs crashed and dumps core, passphrase strings in memory are also
 
 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.
-
-** Most GnuPG features are accessible from Emacs
-
-As the name indicates, EasyPG is inspired by GPGME (GnuPG Made Easy),
-and the library interface is close to GPGME.
+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.
+
+Fortunately, there is gpg-agent to cache passphrases in more secure
+way, so the EasyPG library dares *not* to cache passphrase by itself.
+Elisp programs can set `epg-context-passphrase-callback' to cache
+user's passphrases.