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