   This file describes EasyPG Assistant.

   Copyright (C) 2007 Daiki Ueno.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 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".

EasyPG Assistant user's manual
******************************

EasyPG Assistant is an Emacs user interface to GNU Privacy Guard
(GnuPG, see gnupg).

   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.

This manual covers EasyPG version 0.0.16.

1 Overview
**********

EasyPG Assistant provides the following features.

   * Key manegement.

   * Cryptographic operations on regions.

   * Cryptographic operations on files.

   * Dired integration.

   * Mail-mode integration.

   * Automatic encryption/decryption of *.gpg files.

2 Quick start
*************

To install, just follow the standard CMMI installation instructions.

     $ ./configure
     $ sudo make install

Then, add the following line to your `~/.emacs'

     (require 'epa-setup)

That's all.  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'

3 Commands
**********

This chapter introduces various commands for typical use cases.

3.1 Key management
==================

Probably the first step of using EasyPG Assistant is to browse your
keyring.  `M-x epa-list-keys' is corresponding to `gpg --list-keys'
from the command line.

 -- Command: epa-list-keys name mode
     Show all keys matched with NAME from the public keyring.

The output looks as follows.

       u A5B6B2D4B15813FE Daiki Ueno <ueno@unixuser.org>

A character on the leftmost column indicates the trust level of the
key.  If it is `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 <TAB>.  If you type <RET> or click
button1 on an entry, you will see more detailed information about the
key you selected.

      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

To browse your private keyring, use `M-x epa-list-secret-keys'.

 -- Command: epa-list-secret-keys name
     Show all keys matched with NAME from the private keyring.

In `*Keys*' buffer, several commands are available.  The common use
case is to export some keys to a file.  To do that, type `m' to select
keys, type `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.

 -- Command: epa-insert-keys keys
     Insert selected KEYS after the point.  It will let you select keys
     before insertion.  By default, it will encode keys in the OpenPGP
     armor format.

 -- Command: epa-import-keys file
     Import keys from FILE to your keyring.

 -- Command: epa-import-keys-region start end
     Import keys from the current region between START and END to your
     keyring.

 -- Command: epa-import-armor-in-region start end
     Import keys in the OpenPGP armor format in the current region
     between START and END.  The difference from
     `epa-import-keys-region' is that `epa-import-armor-in-region'
     searches armors in the region and applies `epa-import-keys-region'
     to each of them.

 -- Command: epa-delete-keys allow-secret
     Delete selected keys.  If ALLOW-SECRET is non-`nil', it also
     delete the secret keys.

3.2 Cryptographic operations on regions
=======================================

 -- Command: epa-decrypt-region start end
     Decrypt the current region between START and END.  It replaces the
     region with the decrypted text.

 -- Command: epa-decrypt-armor-in-region start end
     Decrypt OpenPGP armors in the current region between START and
     END.  The difference from `epa-decrypt-region' is that
     `epa-decrypt-armor-in-region' searches armors in the region and
     applies `epa-decrypt-region' to each of them.  That is, this
     command does not alter the original text around armors.

 -- Command: epa-verify-region start end
     Verify the current region between START and END.  It sends the
     verification result to the minibuffer or a popup window.  It
     replaces the region with the signed text.

 -- Command: epa-verify-cleartext-in-region
     Verify OpenPGP cleartext blocks in the current region between
     START and END.  The difference from `epa-verify-region' is that
     `epa-verify-cleartext-in-region' searches OpenPGP cleartext blocks
     in the region and applies `epa-verify-region' to each of them.
     That is, this command does not alter the original text around
     OpenPGP cleartext blocks.

 -- Command: epa-sign-region start end signers type
     Sign the current region between START and 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.

 -- Command: epa-encrypt-region start end recipients sign signers
     Encrypt the current region between START and 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.

3.3 Cryptographic operations on files
=====================================

 -- Command: epa-decrypt-file file
     Decrypt FILE.

 -- Command: epa-verify-file file
     Verify FILE.

 -- Command: epa-sign-file file signers type
     Sign FILE.  If a prefix argument is given, it will let you select
     signing keys, and then a signature type.

 -- Command: epa-encrypt-file file recipients
     Encrypt FILE.  It will let you select recipients.

3.4 Dired integration
=====================

EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to
easily do cryptographic operations on files.  For example,

     M-x dired
     (mark some files)
     : e (or M-x epa-dired-do-encrypt)
     (select recipients by 'm' and click [OK])

The following keys are assigned.

`: d'
     Decrypt marked files.

`: v'
     Verify marked files.

`: s'
     Sign marked files.

`: e'
     Encrypt marked files.

3.5 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 Mm'kay?.

The following keys are assigned.

`C-c C-e d'
     Decrypt OpenPGP armors in the current buffer.

`C-c C-e v'
     Verify OpenPGP cleartext signed messages in the current buffer.

`C-c C-e s'
     Compose a signed message from the current buffer.

`C-c C-e e'
     Compose an encrypted message from the current buffer.

3.6 Encrypting/decrypting *.gpg files
=====================================

Once `epa-setup' is loaded, every file whose extension is `.gpg' 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 `.gpg', encrypted data is
written.

   If you want to temporarily disable this behavior, use `M-x
epa-file-disable', and then to enable this behavior use `M-x
epa-file-enable'.

 -- Command: epa-file-disable
     Disable automatic encryption/decryption of *.gpg files.

 -- Command: epa-file-enable
     Enable automatic encryption/decryption of *.gpg files.

`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.

     ;; -*- epa-file-encrypt-to: ("ueno@unixuser.org") -*-

   Other variables which control the automatic encryption/decryption
behavior are below.

 -- Variable: epa-file-cache-passphrase-for-symmetric-encryption
     If non-`nil', cache passphrase for symmetric encryption.  The
     default value is `nil'.

 -- Variable: epa-file-inhibit-auto-save
     If non-`nil', disable auto-saving when opening an encrypted file.
     The default value is `t'.