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