epa.texi

   1 \input texinfo                  @c -*- mode: texinfo -*-
   2 @c %**start of header
   3 @setfilename epa.info
   4 @settitle EasyPG Assistant
   5 @c %**end of header
   6 @include version.texi
   7 @c @documentlanguage en
   8
   9 @dircategory GNU Emacs Lisp
  10 @direntry
  11 * epa: (epa).   EasyPG Assistant
  12 @end direntry
  13
  14 @ifinfo
  15 This file describes EasyPG Assistant.
  16
  17 Copyright (C) 2007 Daiki Ueno.
  18
  19 Permission is granted to copy, distribute and/or modify this document
  20 under the terms of the GNU Free Documentation License, Version 1.1 or
  21 any later version published by the Free Software Foundation; with no
  22 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
  23 Texts.  A copy of the license is included in the section entitled "GNU
  24 Free Documentation License".
  25 @end ifinfo
  26
  27 @tex
  28
  29 @titlepage
  30 @title EasyPG Assistant
  31
  32 @author by Daiki Ueno
  33 @page
  34
  35 @vskip 0pt plus 1filll
  36 Copyright @copyright{} 2007 Daiki Ueno.
  37
  38 Permission is granted to copy, distribute and/or modify this document
  39 under the terms of the GNU Free Documentation License, Version 1.1 or
  40 any later version published by the Free Software Foundation; with no
  41 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
  42 Texts.  A copy of the license is included in the section entitled "GNU
  43 Free Documentation License".
  44 @end titlepage
  45 @page
  46
  47 @end tex
  48
  49 @node Top
  50 @top EasyPG Assistant user's manual
  51
  52 This manual covers EasyPG version @value{VERSION}.
  53
  54 @menu
  55 * Overview::
  56 * Quick start::
  57 * Commands::
  58 @end menu
  59
  60 @node  Overview
  61 @chapter Overview
  62
  63 EasyPG is an all-in-one GnuPG (@pxref{Top, , Top, gnupg, Using the GNU
  64 Privacy Guard}) interface for Emacs.  It has two aspects: convenient
  65 tools which allow to use GnuPG from Emacs (EasyPG Assistant), and a
  66 fully functional interface library to GnuPG (EasyPG Library).  This
  67 manual describes EasyPG Assistant specifically.
  68
  69 The EasyPG Assistant provides the following features.
  70
  71 @itemize @bullet
  72 @item Keyring browser.
  73 @item Cryptographic operations on regions.
  74 @item Cryptographic operations on files.
  75 @item Dired integration.
  76 @item Encryption/decryption of *.gpg files.
  77 @end itemize
  78
  79 @node  Quick start
  80 @chapter Quick start
  81
  82 To install, just follow the standard CMMI installation instructions.
  83
  84 @example
  85 $ ./configure
  86 $ sudo make install
  87 @end example
  88
  89 Then, add the following line to your @file{~/.emacs}
  90
  91 @lisp
  92 (require 'epa-setup)
  93 @end lisp
  94
  95 That's all.  Restart emacs and type @kbd{M-x epa- TAB}, and you will see a
  96 lot of commands available.  For example,
  97
  98 @itemize @bullet
  99 @item To browse your keyring, type @kbd{M-x epa-list-keys}
 100
 101 @item To create a cleartext signature of the region, type @kbd{M-x epa-sign-region}
 102 @end itemize
 103
 104 You can also do some cryptographic operations from dired.
 105
 106 @example
 107 M-x dired
 108 (mark some files)
 109 : e (or M-x epa-dired-do-encrypt)
 110 (select recipients by 'm' and click [OK])
 111 @end example
 112
 113 @node Commands
 114 @chapter Commands
 115
 116 This chapter introduces various commands for typical use cases.
 117
 118 @menu
 119 * Keyring browser::
 120 * Cryptographic operations on regions::
 121 * Cryptographic operations on files::
 122 * Dired integration::
 123 * Encrypting/decrypting *.gpg files::
 124 @end menu
 125
 126 @node Keyring browser
 127 @section Keyring browser
 128 Probably the first step of using EasyPG Assistant is to browse your
 129 keyring.  @kbd{M-x epa-list-keys} is corresponding to @samp{gpg
 130 --list-keys} from the command line.
 131
 132 @deffn Command epa-list-keys name mode
 133 Show all keys matched with @var{name} from the keyring.
 134 If @var{mode} is non-nil, it reads the private keyring.  Otherwise, it
 135 reads the public keyring.
 136 @end deffn
 137
 138 The output looks as follows.
 139
 140 @example
 141   u A5B6B2D4B15813FE Daiki Ueno <ueno@@unixuser.org>
 142 @end example
 143
 144 A character on the leftmost column indicates the trust level of the
 145 key.  If it is @samp{u}, the key is marked as ultimately trusted.  The
 146 second column is the key ID, and the rest is the user ID.
 147
 148 You can move over entries by @kbd{TAB}.  If you type @kbd{RET} or
 149 clicked button1 on an entry, you will see more detailed information
 150 about the key you selected.
 151
 152 @example
 153  u Daiki Ueno <ueno@@unixuser.org>
 154  u A5B6B2D4B15813FE 1024bits DSA
 155         Created: 2001-10-09
 156         Expires: 2007-09-04
 157         Capabilities: sign certify
 158         Fingerprint: 8003 7CD0 0F1A 9400 03CA  50AA A5B6 B2D4 B158 13FE
 159  u 4447461B2A9BEA2D 2048bits ELGAMAL_E
 160         Created: 2001-10-09
 161         Expires: 2007-09-04
 162         Capabilities: encrypt
 163         Fingerprint: 9003 D76B 73B7 4A8A E588  10AF 4447 461B 2A9B EA2D
 164 @end example
 165
 166 In @samp{*Keys*} buffer, several commands are available.  The common
 167 use case is to export some keys to a file.  To do that, type @kbd{m}
 168 to select keys, type @kbd{o}, and then supply the filename.
 169
 170 @node Cryptographic operations on regions
 171 @section Cryptographic operations on regions
 172
 173 @deffn Command epa-decrypt-region start end
 174 Decrypt the current region between @var{start} and @var{end}.  It
 175 replaces the region with the decrypted plaintext.
 176 @end deffn
 177
 178 @deffn Command epa-decrypt-armor-in-region start end
 179 Decrypt OpenPGP armors in the current region between @var{start} and
 180 @var{end}.  The difference from @code{epa-decrypt-region} is that
 181 @code{epa-decrypt-armor-in-region} searches ASCII armors in the region
 182 and applies @code{epa-decrypt-region} to each of them.  That is, this
 183 command does not alter the original text around ASCII armors.
 184 @end deffn
 185
 186 @deffn Command epa-verify-region start end
 187 Verify the current region between @var{start} and @var{end}.  It sends
 188 the verification result to the minibuffer or a popup window.  It
 189 replaces the region with the signed text.
 190 @end deffn
 191
 192 @deffn Command epa-verify-cleartext-in-region
 193 Verify OpenPGP cleartext blocks in the current region between
 194 @var{start} and @var{end}.  The difference from
 195 @code{epa-verify-region} is that @code{epa-verify-cleartext-in-region}
 196 searches OpenPGP cleartext blocks in the region and applies
 197 @code{epa-verify-region} to each of them.  That is, this command does
 198 not alter the original text around OpenPGP cleartext blocks.
 199 @end deffn
 200
 201 @deffn Command epa-sign-region start end signers type
 202 Sign the current region between @var{start} and @var{end}.  By
 203 default, it creates a cleartext signature.  If a prefix argument is
 204 given, it will let you to select signing keys, and then a signature
 205 type.
 206 @end deffn
 207
 208 @deffn Command epa-encrypt-region start end recipients sign signers
 209 Encrypt the current region between @var{start} and @var{end}.  It will
 210 let you to select recipients.  If a prefix argument is given, it will
 211 also ask you whether or not to sign the plaintext before encryption
 212 and if you answered yes, it will let you to select the signing keys.
 213 @end deffn
 214
 215 @node Cryptographic operations on files
 216 @section Cryptographic operations on files
 217
 218 @deffn Command epa-decrypt-file file
 219 Decrypt @var{file}.
 220 @end deffn
 221
 222 @deffn Command epa-verify-file file
 223 Verify @var{file}.
 224 @end deffn
 225
 226 @deffn Command epa-sign-file file signers type
 227 Sign @var{file}.  If a prefix argument is given, it will let you to
 228 select signing keys, and then a signature type.
 229 @end deffn
 230
 231 @deffn Command epa-encrypt-file file recipients
 232 Encrypt @var{file}.  It will let you to select recipients.
 233 @end deffn
 234
 235 @node Dired integration
 236 @section Dired integration
 237 (not yet written.)
 238
 239 @node Encrypting/decrypting *.gpg files
 240 @section Encrypting/decrypting *.gpg files
 241 Once @code{epa-setup} is loaded, every file whose extension is
 242 @samp{.gpg} will be treated as encrypted.  That is, when you attempt
 243 to open such a file which already exists, the decrypted text is
 244 inserted in the buffer rather than encrypted one.  On the other hand,
 245 when you attempt to save the buffer to a file whose extension is
 246 @samp{.gpg}, encrypted data is written.
 247
 248 If you want to temporarily disable this behavior, use @kbd{M-x
 249 epa-file-disable}, and then to enable this behavior use @kbd{M-x
 250 epa-file-enable}.
 251
 252 @deffn Command epa-file-disable
 253 Disable automatic encryption/decryption of *.gpg files.
 254 @end deffn
 255
 256 @deffn Command epa-file-enable
 257 Enable automatic encryption/decryption of *.gpg files.
 258 @end deffn
 259
 260 @code{epa-file} will let you to select recipients.  If you want to
 261 suppress this question, it might be good idea to put the following
 262 line on the first line of the plaintext.
 263
 264 @lisp
 265 ;; -*- epa-file-encrypt-to: ("ueno@@unixuser.org") -*-
 266 @end lisp
 267
 268 @summarycontents
 269 @contents
 270 @bye
 271
 272 @c End: