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 * Key management::
 120 * Cryptographic operations on regions::
 121 * Cryptographic operations on files::
 122 * Dired integration::
 123 * Mail-mode integration::
 124 * Encrypting/decrypting *.gpg files::
 125 @end menu
 126
 127 @node Key management
 128 @section Key management
 129 Probably the first step of using EasyPG Assistant is to browse your
 130 keyring.  @kbd{M-x epa-list-keys} is corresponding to @samp{gpg
 131 --list-keys} from the command line.
 132
 133 @deffn Command epa-list-keys name mode
 134 Show all keys matched with @var{name} from the public keyring.
 135 @end deffn
 136
 137 The output looks as follows.
 138
 139 @example
 140   u A5B6B2D4B15813FE Daiki Ueno <ueno@@unixuser.org>
 141 @end example
 142
 143 A character on the leftmost column indicates the trust level of the
 144 key.  If it is @samp{u}, the key is marked as ultimately trusted.  The
 145 second column is the key ID, and the rest is the user ID.
 146
 147 You can move over entries by @kbd{TAB}.  If you type @kbd{RET} or
 148 clicked button1 on an entry, you will see more detailed information
 149 about the key you selected.
 150
 151 @example
 152  u Daiki Ueno <ueno@@unixuser.org>
 153  u A5B6B2D4B15813FE 1024bits DSA
 154         Created: 2001-10-09
 155         Expires: 2007-09-04
 156         Capabilities: sign certify
 157         Fingerprint: 8003 7CD0 0F1A 9400 03CA  50AA A5B6 B2D4 B158 13FE
 158  u 4447461B2A9BEA2D 2048bits ELGAMAL_E
 159         Created: 2001-10-09
 160         Expires: 2007-09-04
 161         Capabilities: encrypt
 162         Fingerprint: 9003 D76B 73B7 4A8A E588  10AF 4447 461B 2A9B EA2D
 163 @end example
 164
 165 To browse your private keyring, use @kbd{M-x epa-list-secret-keys}.
 166
 167 @deffn Command epa-list-secret-keys name
 168 Show all keys matched with @var{name} from the private keyring.
 169 @end deffn
 170
 171 In @samp{*Keys*} buffer, several commands are available.  The common
 172 use case is to export some keys to a file.  To do that, type @kbd{m}
 173 to select keys, type @kbd{o}, and then supply the filename.
 174
 175 Below are other commands related to key management.  Some of them take
 176 a file as input/output, and others take the current region.
 177
 178 @deffn Command epa-insert-keys keys
 179 Insert selected @var{keys} after the point.  It will let you select
 180 keys before insertion.  By default, it will encode keys in the OpenPGP
 181 armor format.
 182 @end deffn
 183
 184 @deffn Command epa-import-keys file
 185 Import keys from @var{file} to your keyring.
 186 @end deffn
 187
 188 @deffn Command epa-import-keys-region start end
 189 Import keys from the current region between @var{start} and @var{end}
 190 to your keyring.
 191 @end deffn
 192
 193 @deffn Command epa-import-armor-in-region start end
 194 Import keys in the OpenPGP armor format in the current region between
 195 @var{start} and @var{end}.  The difference from
 196 @code{epa-import-keys-region} is that
 197 @code{epa-import-armor-in-region} searches armors in the region and
 198 applies @code{epa-import-keys-region} to each of them.
 199 @end deffn
 200
 201 @deffn Command epa-delete-keys allow-secret
 202 Delete selected keys.  If @var{allow-secret} is non-@code{nil}, it
 203 also delete the secret keys.
 204 @end deffn
 205
 206 @node Cryptographic operations on regions
 207 @section Cryptographic operations on regions
 208
 209 @deffn Command epa-decrypt-region start end
 210 Decrypt the current region between @var{start} and @var{end}.  It
 211 replaces the region with the decrypted plaintext.
 212 @end deffn
 213
 214 @deffn Command epa-decrypt-armor-in-region start end
 215 Decrypt OpenPGP armors in the current region between @var{start} and
 216 @var{end}.  The difference from @code{epa-decrypt-region} is that
 217 @code{epa-decrypt-armor-in-region} searches armors in the region
 218 and applies @code{epa-decrypt-region} to each of them.  That is, this
 219 command does not alter the original text around armors.
 220 @end deffn
 221
 222 @deffn Command epa-verify-region start end
 223 Verify the current region between @var{start} and @var{end}.  It sends
 224 the verification result to the minibuffer or a popup window.  It
 225 replaces the region with the signed text.
 226 @end deffn
 227
 228 @deffn Command epa-verify-cleartext-in-region
 229 Verify OpenPGP cleartext blocks in the current region between
 230 @var{start} and @var{end}.  The difference from
 231 @code{epa-verify-region} is that @code{epa-verify-cleartext-in-region}
 232 searches OpenPGP cleartext blocks in the region and applies
 233 @code{epa-verify-region} to each of them.  That is, this command does
 234 not alter the original text around OpenPGP cleartext blocks.
 235 @end deffn
 236
 237 @deffn Command epa-sign-region start end signers type
 238 Sign the current region between @var{start} and @var{end}.  By
 239 default, it creates a cleartext signature.  If a prefix argument is
 240 given, it will let you select signing keys, and then a signature
 241 type.
 242 @end deffn
 243
 244 @deffn Command epa-encrypt-region start end recipients sign signers
 245 Encrypt the current region between @var{start} and @var{end}.  It will
 246 let you select recipients.  If a prefix argument is given, it will
 247 also ask you whether or not to sign the plaintext before encryption
 248 and if you answered yes, it will let you select the signing keys.
 249 @end deffn
 250
 251 @node Cryptographic operations on files
 252 @section Cryptographic operations on files
 253
 254 @deffn Command epa-decrypt-file file
 255 Decrypt @var{file}.
 256 @end deffn
 257
 258 @deffn Command epa-verify-file file
 259 Verify @var{file}.
 260 @end deffn
 261
 262 @deffn Command epa-sign-file file signers type
 263 Sign @var{file}.  If a prefix argument is given, it will let you
 264 select signing keys, and then a signature type.
 265 @end deffn
 266
 267 @deffn Command epa-encrypt-file file recipients
 268 Encrypt @var{file}.  It will let you select recipients.
 269 @end deffn
 270
 271 @node Dired integration
 272 @section Dired integration
 273
 274 EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to
 275 easily do cryptographic operations on files.  The following keys are
 276 assigned.
 277
 278 @table @kbd
 279 @item C-c
 280 @kindex @kbd{: d}
 281 @findex epa-dired-do-decrypt
 282 Decrypt marked files.
 283
 284 @item : v
 285 @kindex @kbd{: v}
 286 @findex epa-dired-do-verify
 287 Verify marked files.
 288
 289 @item : s
 290 @kindex @kbd{: s}
 291 @findex epa-dired-do-sign
 292 Sign marked files.
 293
 294 @item : e
 295 @kindex @kbd{: e}
 296 @findex epa-dired-do-encrypt
 297 Encrypt marked files.
 298
 299 @end table
 300
 301 @node Mail-mode integration
 302 @section Mail-mode integration
 303
 304 EasyPG Assistant provides a minor mode to help composing clearsigned
 305 or OpenPGP armored encrypted mails.  The following keys are assigned.
 306
 307 (not yet written.)
 308
 309 @node Encrypting/decrypting *.gpg files
 310 @section Encrypting/decrypting *.gpg files
 311 Once @code{epa-setup} is loaded, every file whose extension is
 312 @samp{.gpg} will be treated as encrypted.  That is, when you attempt
 313 to open such a file which already exists, the decrypted text is
 314 inserted in the buffer rather than encrypted one.  On the other hand,
 315 when you attempt to save the buffer to a file whose extension is
 316 @samp{.gpg}, encrypted data is written.
 317
 318 If you want to temporarily disable this behavior, use @kbd{M-x
 319 epa-file-disable}, and then to enable this behavior use @kbd{M-x
 320 epa-file-enable}.
 321
 322 @deffn Command epa-file-disable
 323 Disable automatic encryption/decryption of *.gpg files.
 324 @end deffn
 325
 326 @deffn Command epa-file-enable
 327 Enable automatic encryption/decryption of *.gpg files.
 328 @end deffn
 329
 330 @code{epa-file} will let you select recipients.  If you want to
 331 suppress this question, it might be a good idea to put the following
 332 line on the first line of the plaintext.
 333 @vindex epa-file-encrypt-to
 334
 335 @lisp
 336 ;; -*- epa-file-encrypt-to: ("ueno@@unixuser.org") -*-
 337 @end lisp
 338
 339 Other variables which control the automatic encryption/decryption
 340 behavior are below.
 341
 342 @defvar epa-file-cache-passphrase-for-symmetric-encryption
 343 If non-@code{nil}, cache passphrase for symmetric encryption.  The
 344 default value is @code{nil}.
 345 @end defvar
 346
 347 @defvar epa-file-inhibit-auto-save
 348 If non-@code{nil}, disable auto-saving when opening an encrypted file.
 349 The default value is @code{t}.
 350 @end defvar
 351
 352 @summarycontents
 353 @contents
 354 @bye
 355
 356 @c End: