[Emacs-diffs] Changes to doc/misc/epa.texi

[Michael W. Olson]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Michael W. Olson <mwolson>      08/02/08 06:54:28

Index: doc/misc/epa.texi
===================================================================
RCS file: doc/misc/epa.texi
diff -N doc/misc/epa.texi
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ doc/misc/epa.texi   8 Feb 2008 06:54:25 -0000       1.1
@@ -0,0 +1,393 @@
+\input texinfo                  @c -*- mode: texinfo -*-
address@hidden %**start of header
address@hidden ../../info/epa
address@hidden EasyPG Assistant User's Manual
address@hidden %**end of header
+
address@hidden VERSION 1.0.0
+
address@hidden
+This file describes EasyPG Assistant.
+
+Copyright @copyright{} 2007, 2008 Free Software Foundation, Inc.
+
address@hidden
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.  A copy of the license is included in the section entitled "GNU
+Free Documentation License".
address@hidden quotation
address@hidden copying
+
address@hidden Emacs
address@hidden
+* EasyPG Assistant: (epa).   An Emacs user interface to GNU Privacy Guard.
address@hidden direntry
+
+
address@hidden
address@hidden EasyPG Assistant
+
address@hidden by Daiki Ueno
address@hidden
+
address@hidden 0pt plus 1filll
address@hidden
address@hidden titlepage
address@hidden
+
address@hidden @summarycontents
address@hidden @contents
+
address@hidden Top
address@hidden 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.
+
address@hidden
+This manual covers EasyPG version @value{VERSION}.
+
address@hidden
+* Overview::                    
+* Quick start::                 
+* Commands::               
address@hidden menu
+
address@hidden  Overview
address@hidden Overview
+
+EasyPG Assistant provides the following features.
+
address@hidden @bullet
address@hidden Key manegement.
address@hidden Cryptographic operations on regions.
address@hidden Cryptographic operations on files.
address@hidden Dired integration.
address@hidden Mail-mode integration.
address@hidden Automatic encryption/decryption of *.gpg files.
address@hidden itemize
+
address@hidden  Quick start
address@hidden Quick start
+
+To install, just follow the standard CMMI installation instructions.
+
address@hidden
address@hidden
+$ ./configure
+$ sudo make install
address@hidden example
address@hidden cartouche
+
address@hidden
+Then, add the following line to your @file{~/.emacs}
+
address@hidden
address@hidden
+(require 'epa-setup)
address@hidden lisp
address@hidden cartouche
+
address@hidden
+That's all.  Restart emacs and type @kbd{M-x epa- @key{TAB}}, and you will see 
a
+lot of commands available.  For example,
+
address@hidden @bullet
address@hidden To browse your keyring, type @kbd{M-x epa-list-keys}
+
address@hidden To create a cleartext signature of the region, type @kbd{M-x 
epa-sign-region}
address@hidden itemize
+
address@hidden Commands
address@hidden Commands
+
+This chapter introduces various commands for typical use cases.
+
address@hidden
+* Key management::              
+* Cryptographic operations on regions::  
+* Cryptographic operations on files::  
+* Dired integration::           
+* Mail-mode integration::       
+* Encrypting/decrypting *.gpg files::  
address@hidden menu
+
address@hidden Key management
address@hidden 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.
+
address@hidden Command epa-list-keys name mode
+Show all keys matched with @var{name} from the public keyring.
address@hidden deffn
+
address@hidden
+The output looks as follows.
+
address@hidden
+  u A5B6B2D4B15813FE Daiki Ueno <ueno@@unixuser.org>
address@hidden example
+
address@hidden
+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.
+
address@hidden
+ u Daiki Ueno <ueno@@unixuser.org>
+ 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
address@hidden example
+
address@hidden
+To browse your private keyring, use @kbd{M-x epa-list-secret-keys}.
+
address@hidden Command epa-list-secret-keys name
+Show all keys matched with @var{name} from the private keyring.
address@hidden deffn
+
address@hidden
+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.
+
address@hidden 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.
address@hidden deffn
+
address@hidden Command epa-import-keys file
+Import keys from @var{file} to your keyring.
address@hidden deffn
+
address@hidden Command epa-import-keys-region start end
+Import keys from the current region between @var{start} and @var{end}
+to your keyring.
address@hidden deffn
+
address@hidden Command epa-import-armor-in-region start end
+Import keys in the OpenPGP armor format in the current region between
address@hidden and @var{end}.  The difference from
address@hidden is that
address@hidden searches armors in the region and
+applies @code{epa-import-keys-region} to each of them.
address@hidden deffn
+
address@hidden Command epa-delete-keys allow-secret
+Delete selected keys.  If @var{allow-secret} is address@hidden, it
+also delete the secret keys.
address@hidden deffn
+
address@hidden Cryptographic operations on regions
address@hidden Cryptographic operations on regions
+
address@hidden Command epa-decrypt-region start end
+Decrypt the current region between @var{start} and @var{end}.  It
+replaces the region with the decrypted text.
address@hidden deffn
+
address@hidden Command epa-decrypt-armor-in-region start end
+Decrypt OpenPGP armors in the current region between @var{start} and
address@hidden  The difference from @code{epa-decrypt-region} is that
address@hidden 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.
address@hidden deffn
+
address@hidden 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.
address@hidden deffn
+
address@hidden Command epa-verify-cleartext-in-region
+Verify OpenPGP cleartext blocks in the current region between
address@hidden and @var{end}.  The difference from
address@hidden is that @code{epa-verify-cleartext-in-region}
+searches OpenPGP cleartext blocks in the region and applies
address@hidden to each of them.  That is, this command does
+not alter the original text around OpenPGP cleartext blocks.
address@hidden deffn
+
address@hidden 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.
address@hidden deffn
+
address@hidden 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.
address@hidden deffn
+
address@hidden Cryptographic operations on files
address@hidden Cryptographic operations on files
+
address@hidden Command epa-decrypt-file file
+Decrypt @var{file}.
address@hidden deffn
+
address@hidden Command epa-verify-file file
+Verify @var{file}.
address@hidden deffn
+
address@hidden 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.
address@hidden deffn
+
address@hidden Command epa-encrypt-file file recipients
+Encrypt @var{file}.  It will let you select recipients.
address@hidden deffn
+
address@hidden Dired integration
address@hidden Dired integration
+
+EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to
+easily do cryptographic operations on files.  For example,
+
address@hidden
+M-x dired
+(mark some files)
+: e (or M-x epa-dired-do-encrypt)
+(select recipients by 'm' and click [OK])
address@hidden example
+
address@hidden
+The following keys are assigned.
+
address@hidden @kbd
address@hidden : d
address@hidden @kbd{: d}
address@hidden epa-dired-do-decrypt
+Decrypt marked files.
+
address@hidden : v
address@hidden @kbd{: v}
address@hidden epa-dired-do-verify
+Verify marked files.
+
address@hidden : s
address@hidden @kbd{: s}
address@hidden epa-dired-do-sign
+Sign marked files.
+
address@hidden : e
address@hidden @kbd{: e}
address@hidden epa-dired-do-encrypt
+Encrypt marked files.
+
address@hidden table
+
address@hidden Mail-mode integration
address@hidden Mail-mode integration
+
+EasyPG Assistant provides a minor mode to help user compose inline PGP
+messages.  Inline PGP is sending the OpenPGP blobs directly inside a
+mail message and it is not recommended and you should consider to use
+PGP/MIME.  See
address@hidden://josefsson.org/inline-openpgp-considered-harmful.html,
+Inline PGP in E-mail is bad, Mm'kay?}.
+
address@hidden
+The following keys are assigned.
+
address@hidden @kbd
address@hidden C-c C-e d
address@hidden @kbd{C-c C-e d}
address@hidden epa-mail-decrypt
+Decrypt OpenPGP armors in the current buffer.
+
address@hidden C-c C-e v
address@hidden @kbd{C-c C-e v}
address@hidden epa-mail-verify
+Verify OpenPGP cleartext signed messages in the current buffer.
+
address@hidden C-c C-e s
address@hidden @kbd{C-c C-e s}
address@hidden epa-mail-sign
+Compose a signed message from the current buffer.
+
address@hidden C-c C-e e
address@hidden @kbd{C-c C-e e}
address@hidden epa-mail-encrypt
+Compose an encrypted message from the current buffer.
+
address@hidden table
+
address@hidden Encrypting/decrypting *.gpg files
address@hidden Encrypting/decrypting *.gpg files
+Once @code{epa-setup} is loaded, every file whose extension is
address@hidden will be treated as encrypted.  That is, when you attempt
+to open such a file which already exists, the decrypted text is
+inserted in the buffer rather than encrypted one.  On the other hand,
+when you attempt to save the buffer to a file whose extension is
address@hidden, encrypted data is written.
+
+If you want to temporarily disable this behavior, use @kbd{M-x
+epa-file-disable}, and then to enable this behavior use @kbd{M-x
+epa-file-enable}.
+
address@hidden Command epa-file-disable
+Disable automatic encryption/decryption of *.gpg files.
address@hidden deffn
+
address@hidden Command epa-file-enable
+Enable automatic encryption/decryption of *.gpg files.
address@hidden deffn
+
address@hidden
address@hidden 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.
address@hidden epa-file-encrypt-to
+
address@hidden
address@hidden
+;; -*- epa-file-encrypt-to: ("ueno@@unixuser.org") -*-
address@hidden lisp
address@hidden cartouche
+
+Other variables which control the automatic encryption/decryption
+behavior are below.
+
address@hidden epa-file-cache-passphrase-for-symmetric-encryption
+If address@hidden, cache passphrase for symmetric encryption.  The
+default value is @code{nil}.
address@hidden defvar
+
address@hidden epa-file-inhibit-auto-save
+If address@hidden, disable auto-saving when opening an encrypted file.
+The default value is @code{t}.
address@hidden defvar
+
address@hidden
+
address@hidden End: