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