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 EasyPG Assistant is an Emacs user interface for GNU Privacy Guard
  53 (GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}).
  54
  55 EasyPG Assistant is a part of the package called EasyPG which is an
  56 all-in-one GnuPG interface for Emacs.  EasyPG also contains the
  57 library interface called EasyPG Library.
  58
  59 This manual covers EasyPG version @value{VERSION}.
  60
  61 @menu
  62 * Overview::
  63 * Quick start::
  64 * Commands::
  65 @end menu
  66
  67 @node  Overview
  68 @chapter Overview
  69
  70 EasyPG Assistant provides the following features.
  71
  72 @itemize @bullet
  73 @item Keyring browser.
  74 @item Cryptographic operations on regions.
  75 @item Cryptographic operations on files.
  76 @item Dired integration.
  77 @item Encryption/decryption of *.gpg files.
  78 @end itemize
  79
  80 @node  Quick start
  81 @chapter Quick start
  82
  83 To install, just follow the standard CMMI installation instructions.
  84
  85 @example
  86 $ ./configure
  87 $ sudo make install
  88 @end example
  89
  90 Then, add the following line to your @file{~/.emacs}
  91
  92 @lisp
  93 (require 'epa-setup)
  94 @end lisp
  95
  96 That's all.  Restart emacs and type @kbd{M-x epa- TAB}, and you will see a
  97 lot of commands available.  For example,
  98
  99 @itemize @bullet
 100 @item To browse your keyring, type @kbd{M-x epa-list-keys}
 101
 102 @item To create a cleartext signature of the region, type @kbd{M-x epa-sign-region}
 103 @end itemize
 104
 105 You can also do some cryptographic operations from dired.
 106
 107 @example
 108 M-x dired
 109 (mark some files)
 110 : e (or M-x epa-dired-do-encrypt)
 111 (select recipients by 'm' and click [OK])
 112 @end example
 113
 114 @node Commands
 115 @chapter Commands
 116
 117 This chapter introduces various commands for typical use cases.
 118
 119 @menu
 120 * Key management::
 121 * Cryptographic operations on regions::
 122 * Cryptographic operations on files::
 123 * Dired integration::
 124 * Mail-mode integration::
 125 * Encrypting/decrypting *.gpg files::
 126 @end menu
 127
 128 @node Key management
 129 @section Key management
 130 Probably the first step of using EasyPG Assistant is to browse your
 131 keyring.  @kbd{M-x epa-list-keys} is corresponding to @samp{gpg
 132 --list-keys} from the command line.
 133
 134 @deffn Command epa-list-keys name mode
 135 Show all keys matched with @var{name} from 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 To browse your private keyring, use @kbd{M-x epa-list-secret-keys}.
 167
 168 @deffn Command epa-list-secret-keys name
 169 Show all keys matched with @var{name} from the private keyring.
 170 @end deffn
 171
 172 In @samp{*Keys*} buffer, several commands are available.  The common
 173 use case is to export some keys to a file.  To do that, type @kbd{m}
 174 to select keys, type @kbd{o}, and then supply the filename.
 175
 176 Below are other commands related to key management.  Some of them take
 177 a file as input/output, and others take the current region.
 178
 179 @deffn Command epa-insert-keys keys
 180 Insert selected @var{keys} after the point.  It will let you select
 181 keys before insertion.  By default, it will encode keys in the OpenPGP
 182 armor format.
 183 @end deffn
 184
 185 @deffn Command epa-import-keys file
 186 Import keys from @var{file} to your keyring.
 187 @end deffn
 188
 189 @deffn Command epa-import-keys-region start end
 190 Import keys from the current region between @var{start} and @var{end}
 191 to your keyring.
 192 @end deffn
 193
 194 @deffn Command epa-import-armor-in-region start end
 195 Import keys in the OpenPGP armor format in the current region between
 196 @var{start} and @var{end}.  The difference from
 197 @code{epa-import-keys-region} is that
 198 @code{epa-import-armor-in-region} searches armors in the region and
 199 applies @code{epa-import-keys-region} to each of them.
 200 @end deffn
 201
 202 @deffn Command epa-delete-keys allow-secret
 203 Delete selected keys.  If @var{allow-secret} is non-@code{nil}, it
 204 also delete the secret keys.
 205 @end deffn
 206
 207 @node Cryptographic operations on regions
 208 @section Cryptographic operations on regions
 209
 210 @deffn Command epa-decrypt-region start end
 211 Decrypt the current region between @var{start} and @var{end}.  It
 212 replaces the region with the decrypted text.
 213 @end deffn
 214
 215 @deffn Command epa-decrypt-armor-in-region start end
 216 Decrypt OpenPGP armors in the current region between @var{start} and
 217 @var{end}.  The difference from @code{epa-decrypt-region} is that
 218 @code{epa-decrypt-armor-in-region} searches armors in the region
 219 and applies @code{epa-decrypt-region} to each of them.  That is, this
 220 command does not alter the original text around armors.
 221 @end deffn
 222
 223 @deffn Command epa-verify-region start end
 224 Verify the current region between @var{start} and @var{end}.  It sends
 225 the verification result to the minibuffer or a popup window.  It
 226 replaces the region with the signed text.
 227 @end deffn
 228
 229 @deffn Command epa-verify-cleartext-in-region
 230 Verify OpenPGP cleartext blocks in the current region between
 231 @var{start} and @var{end}.  The difference from
 232 @code{epa-verify-region} is that @code{epa-verify-cleartext-in-region}
 233 searches OpenPGP cleartext blocks in the region and applies
 234 @code{epa-verify-region} to each of them.  That is, this command does
 235 not alter the original text around OpenPGP cleartext blocks.
 236 @end deffn
 237
 238 @deffn Command epa-sign-region start end signers type
 239 Sign the current region between @var{start} and @var{end}.  By
 240 default, it creates a cleartext signature.  If a prefix argument is
 241 given, it will let you select signing keys, and then a signature
 242 type.
 243 @end deffn
 244
 245 @deffn Command epa-encrypt-region start end recipients sign signers
 246 Encrypt the current region between @var{start} and @var{end}.  It will
 247 let you select recipients.  If a prefix argument is given, it will
 248 also ask you whether or not to sign the text before encryption and if
 249 you answered yes, it will let you select the signing keys.
 250 @end deffn
 251
 252 @node Cryptographic operations on files
 253 @section Cryptographic operations on files
 254
 255 @deffn Command epa-decrypt-file file
 256 Decrypt @var{file}.
 257 @end deffn
 258
 259 @deffn Command epa-verify-file file
 260 Verify @var{file}.
 261 @end deffn
 262
 263 @deffn Command epa-sign-file file signers type
 264 Sign @var{file}.  If a prefix argument is given, it will let you
 265 select signing keys, and then a signature type.
 266 @end deffn
 267
 268 @deffn Command epa-encrypt-file file recipients
 269 Encrypt @var{file}.  It will let you select recipients.
 270 @end deffn
 271
 272 @node Dired integration
 273 @section Dired integration
 274
 275 EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to
 276 easily do cryptographic operations on files.  The following keys are
 277 assigned.
 278
 279 @table @kbd
 280 @item : d
 281 @kindex @kbd{: d}
 282 @findex epa-dired-do-decrypt
 283 Decrypt marked files.
 284
 285 @item : v
 286 @kindex @kbd{: v}
 287 @findex epa-dired-do-verify
 288 Verify marked files.
 289
 290 @item : s
 291 @kindex @kbd{: s}
 292 @findex epa-dired-do-sign
 293 Sign marked files.
 294
 295 @item : e
 296 @kindex @kbd{: e}
 297 @findex epa-dired-do-encrypt
 298 Encrypt marked files.
 299
 300 @end table
 301
 302 @node Mail-mode integration
 303 @section Mail-mode integration
 304
 305 EasyPG Assistant provides a minor mode to help composing clearsigned
 306 or OpenPGP armored encrypted mails.  The following keys are assigned.
 307
 308 (not yet written.)
 309
 310 @node Encrypting/decrypting *.gpg files
 311 @section Encrypting/decrypting *.gpg files
 312 Once @code{epa-setup} is loaded, every file whose extension is
 313 @samp{.gpg} will be treated as encrypted.  That is, when you attempt
 314 to open such a file which already exists, the decrypted text is
 315 inserted in the buffer rather than encrypted one.  On the other hand,
 316 when you attempt to save the buffer to a file whose extension is
 317 @samp{.gpg}, encrypted data is written.
 318
 319 If you want to temporarily disable this behavior, use @kbd{M-x
 320 epa-file-disable}, and then to enable this behavior use @kbd{M-x
 321 epa-file-enable}.
 322
 323 @deffn Command epa-file-disable
 324 Disable automatic encryption/decryption of *.gpg files.
 325 @end deffn
 326
 327 @deffn Command epa-file-enable
 328 Enable automatic encryption/decryption of *.gpg files.
 329 @end deffn
 330
 331 @code{epa-file} will let you select recipients.  If you want to
 332 suppress this question, it might be a good idea to put the following
 333 line on the first line of the text being encrypted.
 334 @vindex epa-file-encrypt-to
 335
 336 @lisp
 337 ;; -*- epa-file-encrypt-to: ("ueno@@unixuser.org") -*-
 338 @end lisp
 339
 340 Other variables which control the automatic encryption/decryption
 341 behavior are below.
 342
 343 @defvar epa-file-cache-passphrase-for-symmetric-encryption
 344 If non-@code{nil}, cache passphrase for symmetric encryption.  The
 345 default value is @code{nil}.
 346 @end defvar
 347
 348 @defvar epa-file-inhibit-auto-save
 349 If non-@code{nil}, disable auto-saving when opening an encrypted file.
 350 The default value is @code{t}.
 351 @end defvar
 352
 353 @summarycontents
 354 @contents
 355 @bye
 356
 357 @c End: