doc/misc/epa.texi

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