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 @value{VERSION}.
  11
  12 Copyright @copyright{} 2007, 2008, 2009, 2010 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.3 or
  17 any later version published by the Free Software Foundation; with no
  18 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
  19 and with the Back-Cover Texts as in (a) below.  A copy of the license
  20 is included in the section entitled ``GNU Free Documentation License''
  21 in the Emacs manual.
  22
  23 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
  24 modify this GNU manual.  Buying copies from the FSF supports it in
  25 developing GNU and promoting software freedom.''
  26
  27 This document is part of a collection distributed under the GNU Free
  28 Documentation License.  If you want to distribute this document
  29 separately from the collection, you can do so by adding a copy of the
  30 license to the document, as described in section 6 of the license.
  31 @end quotation
  32 @end copying
  33
  34 @dircategory Emacs
  35 @direntry
  36 * EasyPG Assistant: (epa).      An Emacs user interface to GNU Privacy Guard.
  37 @end direntry
  38
  39 @titlepage
  40 @title EasyPG Assistant
  41
  42 @author by Daiki Ueno
  43 @page
  44
  45 @vskip 0pt plus 1filll
  46 @insertcopying
  47 @end titlepage
  48
  49 @contents
  50
  51 @node Top
  52 @top EasyPG Assistant user's manual
  53
  54 EasyPG Assistant is an Emacs user interface to GNU Privacy Guard
  55 (GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}).
  56
  57 EasyPG Assistant is a part of the package called EasyPG, an all-in-one
  58 GnuPG interface for Emacs.  EasyPG also contains the library interface
  59 called EasyPG Library.
  60
  61 @ifnottex
  62 @insertcopying
  63 @end ifnottex
  64
  65 @menu
  66 * Overview::
  67 * Quick start::
  68 * Commands::
  69 * Caching Passphrases::
  70 * Bug Reports::
  71 @end menu
  72
  73 @node  Overview
  74 @chapter Overview
  75
  76 EasyPG Assistant provides the following features.
  77
  78 @itemize @bullet
  79 @item Key management.
  80 @item Cryptographic operations on regions.
  81 @item Cryptographic operations on files.
  82 @item Dired integration.
  83 @item Mail-mode integration.
  84 @item Automatic encryption/decryption of *.gpg files.
  85 @end itemize
  86
  87 @node  Quick start
  88 @chapter Quick start
  89
  90 EasyPG Assistant commands are prefixed by @samp{epa-}.  For example,
  91
  92 @itemize @bullet
  93 @item To browse your keyring, type @kbd{M-x epa-list-keys}
  94
  95 @item To create a cleartext signature of the region, type @kbd{M-x epa-sign-region}
  96
  97 @item To encrypt a file, type @kbd{M-x epa-encrypt-file}
  98 @end itemize
  99
 100 EasyPG Assistant provides several cryptographic features which can be
 101 integrated into other Emacs functionalities.  For example, automatic
 102 encryption/decryption of @samp{*.gpg} files.
 103
 104 @node Commands
 105 @chapter Commands
 106
 107 This chapter introduces various commands for typical use cases.
 108
 109 @menu
 110 * Key management::
 111 * Cryptographic operations on regions::
 112 * Cryptographic operations on files::
 113 * Dired integration::
 114 * Mail-mode integration::
 115 * Encrypting/decrypting *.gpg files::
 116 @end menu
 117
 118 @node Key management
 119 @section Key management
 120 Probably the first step of using EasyPG Assistant is to browse your
 121 keyring.  @kbd{M-x epa-list-keys} is corresponding to @samp{gpg
 122 --list-keys} from the command line.
 123
 124 @deffn Command epa-list-keys name mode
 125 Show all keys matched with @var{name} from the public keyring.
 126 @end deffn
 127
 128 @noindent
 129 The output looks as follows.
 130
 131 @example
 132   u A5B6B2D4B15813FE Daiki Ueno <ueno@@unixuser.org>
 133 @end example
 134
 135 @noindent
 136 A character on the leftmost column indicates the trust level of the
 137 key.  If it is @samp{u}, the key is marked as ultimately trusted.  The
 138 second column is the key ID, and the rest is the user ID.
 139
 140 You can move over entries by @key{TAB}.  If you type @key{RET} or
 141 click button1 on an entry, you will see more detailed information
 142 about the key you selected.
 143
 144 @example
 145  u Daiki Ueno <ueno@@unixuser.org>
 146  u A5B6B2D4B15813FE 1024bits DSA
 147         Created: 2001-10-09
 148         Expires: 2007-09-04
 149         Capabilities: sign certify
 150         Fingerprint: 8003 7CD0 0F1A 9400 03CA  50AA A5B6 B2D4 B158 13FE
 151  u 4447461B2A9BEA2D 2048bits ELGAMAL_E
 152         Created: 2001-10-09
 153         Expires: 2007-09-04
 154         Capabilities: encrypt
 155         Fingerprint: 9003 D76B 73B7 4A8A E588  10AF 4447 461B 2A9B EA2D
 156 @end example
 157
 158 @noindent
 159 To browse your private keyring, use @kbd{M-x epa-list-secret-keys}.
 160
 161 @deffn Command epa-list-secret-keys name
 162 Show all keys matched with @var{name} from the private keyring.
 163 @end deffn
 164
 165 @noindent
 166 In @samp{*Keys*} buffer, several commands are available.  The common
 167 use case is to export some keys to a file.  To do that, type @kbd{m}
 168 to select keys, type @kbd{o}, and then supply the filename.
 169
 170 Below are other commands related to key management.  Some of them take
 171 a file as input/output, and others take the current region.
 172
 173 @deffn Command epa-insert-keys keys
 174 Insert selected @var{keys} after the point.  It will let you select
 175 keys before insertion.  By default, it will encode keys in the OpenPGP
 176 armor format.
 177 @end deffn
 178
 179 @deffn Command epa-import-keys file
 180 Import keys from @var{file} to your keyring.
 181 @end deffn
 182
 183 @deffn Command epa-import-keys-region start end
 184 Import keys from the current region between @var{start} and @var{end}
 185 to your keyring.
 186 @end deffn
 187
 188 @deffn Command epa-import-armor-in-region start end
 189 Import keys in the OpenPGP armor format in the current region between
 190 @var{start} and @var{end}.  The difference from
 191 @code{epa-import-keys-region} is that
 192 @code{epa-import-armor-in-region} searches armors in the region and
 193 applies @code{epa-import-keys-region} to each of them.
 194 @end deffn
 195
 196 @deffn Command epa-delete-keys allow-secret
 197 Delete selected keys.  If @var{allow-secret} is non-@code{nil}, it
 198 also delete the secret keys.
 199 @end deffn
 200
 201 @node Cryptographic operations on regions
 202 @section Cryptographic operations on regions
 203
 204 @deffn Command epa-decrypt-region start end
 205 Decrypt the current region between @var{start} and @var{end}.  It
 206 replaces the region with the decrypted text.
 207 @end deffn
 208
 209 @deffn Command epa-decrypt-armor-in-region start end
 210 Decrypt OpenPGP armors in the current region between @var{start} and
 211 @var{end}.  The difference from @code{epa-decrypt-region} is that
 212 @code{epa-decrypt-armor-in-region} searches armors in the region
 213 and applies @code{epa-decrypt-region} to each of them.  That is, this
 214 command does not alter the original text around armors.
 215 @end deffn
 216
 217 @deffn Command epa-verify-region start end
 218 Verify the current region between @var{start} and @var{end}.  It sends
 219 the verification result to the minibuffer or a popup window.  It
 220 replaces the region with the signed text.
 221 @end deffn
 222
 223 @deffn Command epa-verify-cleartext-in-region
 224 Verify OpenPGP cleartext blocks in the current region between
 225 @var{start} and @var{end}.  The difference from
 226 @code{epa-verify-region} is that @code{epa-verify-cleartext-in-region}
 227 searches OpenPGP cleartext blocks in the region and applies
 228 @code{epa-verify-region} to each of them.  That is, this command does
 229 not alter the original text around OpenPGP cleartext blocks.
 230 @end deffn
 231
 232 @deffn Command epa-sign-region start end signers type
 233 Sign the current region between @var{start} and @var{end}.  By
 234 default, it creates a cleartext signature.  If a prefix argument is
 235 given, it will let you select signing keys, and then a signature
 236 type.
 237 @end deffn
 238
 239 @deffn Command epa-encrypt-region start end recipients sign signers
 240 Encrypt the current region between @var{start} and @var{end}.  It will
 241 let you select recipients.  If a prefix argument is given, it will
 242 also ask you whether or not to sign the text before encryption and if
 243 you answered yes, it will let you select the signing keys.
 244 @end deffn
 245
 246 @node Cryptographic operations on files
 247 @section Cryptographic operations on files
 248
 249 @deffn Command epa-decrypt-file file
 250 Decrypt @var{file}.
 251 @end deffn
 252
 253 @deffn Command epa-verify-file file
 254 Verify @var{file}.
 255 @end deffn
 256
 257 @deffn Command epa-sign-file file signers type
 258 Sign @var{file}.  If a prefix argument is given, it will let you
 259 select signing keys, and then a signature type.
 260 @end deffn
 261
 262 @deffn Command epa-encrypt-file file recipients
 263 Encrypt @var{file}.  It will let you select recipients.
 264 @end deffn
 265
 266 @node Dired integration
 267 @section Dired integration
 268
 269 EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to
 270 easily do cryptographic operations on files.  For example,
 271
 272 @example
 273 M-x dired
 274 (mark some files)
 275 : e (or M-x epa-dired-do-encrypt)
 276 (select recipients by 'm' and click [OK])
 277 @end example
 278
 279 @noindent
 280 The following keys are assigned.
 281
 282 @table @kbd
 283 @item : d
 284 @kindex @kbd{: d}
 285 @findex epa-dired-do-decrypt
 286 Decrypt marked files.
 287
 288 @item : v
 289 @kindex @kbd{: v}
 290 @findex epa-dired-do-verify
 291 Verify marked files.
 292
 293 @item : s
 294 @kindex @kbd{: s}
 295 @findex epa-dired-do-sign
 296 Sign marked files.
 297
 298 @item : e
 299 @kindex @kbd{: e}
 300 @findex epa-dired-do-encrypt
 301 Encrypt marked files.
 302
 303 @end table
 304
 305 @node Mail-mode integration
 306 @section Mail-mode integration
 307
 308 EasyPG Assistant provides a minor mode @code{epa-mail-mode} to help
 309 user compose inline PGP messages.  Inline PGP is a traditional style
 310 of sending signed/encrypted emails by embedding raw OpenPGP blobs
 311 inside a message body, not using modern MIME format.
 312
 313 NOTE: Inline PGP is not recommended and you should consider to use
 314 PGP/MIME.  See
 315 @uref{http://josefsson.org/inline-openpgp-considered-harmful.html,
 316 Inline PGP in E-mail is bad, Mm'kay?}.
 317
 318 @noindent
 319 Once @code{epa-mail-mode} is enabled, the following keys are assigned.
 320 You can do it by @kbd{C-u 1 M-x epa-mail-mode} or through the Customize
 321 interface.  Try @kbd{M-x customize-variable epa-global-mail-mode}.
 322
 323 @table @kbd
 324 @item C-c C-e d
 325 @kindex @kbd{C-c C-e d}
 326 @findex epa-mail-decrypt
 327 Decrypt OpenPGP armors in the current buffer.
 328
 329 @item C-c C-e v
 330 @kindex @kbd{C-c C-e v}
 331 @findex epa-mail-verify
 332 Verify OpenPGP cleartext signed messages in the current buffer.
 333
 334 @item C-c C-e s
 335 @kindex @kbd{C-c C-e s}
 336 @findex epa-mail-sign
 337 Compose a signed message from the current buffer.
 338
 339 @item C-c C-e e
 340 @kindex @kbd{C-c C-e e}
 341 @findex epa-mail-encrypt
 342 Compose an encrypted message from the current buffer.
 343 By default it tries to build the recipient list from @samp{to},
 344 @samp{cc}, and @samp{bcc} fields of the mail header.  To include your
 345 key in the recipient list, use @samp{encrypt-to} option in
 346 @file{~/.gnupg/gpg.conf}.
 347
 348 @end table
 349
 350 @node Encrypting/decrypting *.gpg files
 351 @section Encrypting/decrypting *.gpg files
 352 By default, every file whose extension is @samp{.gpg} will be treated
 353 as encrypted.  That is, when you attempt to open such a file which
 354 already exists, the decrypted text is inserted in the buffer rather
 355 than encrypted one.  On the other hand, when you attempt to save the
 356 buffer to a file whose extension is @samp{.gpg}, encrypted data is
 357 written.
 358
 359 If you want to temporarily disable this behavior, use @kbd{M-x
 360 epa-file-disable}, and then to enable this behavior use @kbd{M-x
 361 epa-file-enable}.
 362
 363 @deffn Command epa-file-disable
 364 Disable automatic encryption/decryption of *.gpg files.
 365 @end deffn
 366
 367 @deffn Command epa-file-enable
 368 Enable automatic encryption/decryption of *.gpg files.
 369 @end deffn
 370
 371 @noindent
 372 @code{epa-file} will let you select recipients.  If you want to
 373 suppress this question, it might be a good idea to put the following
 374 line on the first line of the text being encrypted.
 375 @vindex epa-file-encrypt-to
 376
 377 @cartouche
 378 @lisp
 379 ;; -*- epa-file-encrypt-to: ("ueno@@unixuser.org") -*-
 380 @end lisp
 381 @end cartouche
 382
 383 The file name extension of encrypted files can be controlled by
 384 @var{epa-file-name-regexp}.
 385
 386 @defvar epa-file-name-regexp
 387 Regexp which matches filenames treated as encrypted.
 388 @end defvar
 389
 390 Other variables which control the automatic encryption/decryption
 391 behavior are below.
 392
 393 @defvar epa-file-cache-passphrase-for-symmetric-encryption
 394 If non-@code{nil}, cache passphrase for symmetric encryption.  The
 395 default value is @code{nil}.
 396 @end defvar
 397
 398 @defvar epa-file-inhibit-auto-save
 399 If non-@code{nil}, disable auto-saving when opening an encrypted file.
 400 The default value is @code{t}.
 401 @end defvar
 402
 403 @node Caching Passphrases
 404 @chapter Caching Passphrases
 405
 406 Typing passphrases is an irritating task if you frequently open and
 407 close the same file.  GnuPG and EasyPG Assistant provide mechanisms to
 408 remember your passphrases.  However, the configuration is a bit
 409 confusing since it depends on your GnuPG installation (GnuPG version 1 or
 410 GnuPG version 2), encryption method (symmetric or public key), and whether or
 411 not you want to use gpg-agent.  Here are some questions:
 412
 413 @enumerate
 414 @item Do you use GnuPG version 2 instead of GnuPG version 1?
 415 @item Do you use symmetric encryption rather than public key encryption?
 416 @item Do you want to use gpg-agent?
 417 @end enumerate
 418
 419 Here are configurations depending on your answers:
 420
 421 @multitable {111} {222} {333} {configuration configuration configuration}
 422 @item @b{1} @tab @b{2} @tab @b{3} @tab Configuration
 423 @item Yes @tab Yes @tab Yes @tab Set up gpg-agent.
 424 @item Yes @tab Yes @tab No @tab You can't, without gpg-agent.
 425 @item Yes @tab No @tab Yes @tab Set up gpg-agent.
 426 @item Yes @tab No @tab No @tab You can't, without gpg-agent.
 427 @item No @tab Yes @tab Yes @tab Set up elisp passphrase cache.
 428 @item No @tab Yes @tab No @tab Set up elisp passphrase cache.
 429 @item No @tab No @tab Yes @tab Set up gpg-agent.
 430 @item No @tab No @tab No @tab You can't, without gpg-agent.
 431 @end multitable
 432
 433 To set up gpg-agent, follow the instruction in GnuPG manual.
 434 @pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}.
 435
 436 To set up elisp passphrase cache, set
 437 @code{epa-file-cache-passphrase-for-symmetric-encryption}.
 438 @xref{Encrypting/decrypting *.gpg files}.
 439
 440 @node Bug Reports
 441 @chapter Bug Reports
 442
 443 Bugs and problems with EasyPG Assistant are actively worked on by the
 444 Emacs development team.  Feature requests and suggestions are also
 445 more than welcome.  Use @kbd{M-x report-emacs-bug}, @pxref{Bugs, ,
 446 Bugs, emacs, Reporting Bugs}.
 447
 448 When submitting a bug report, please try to describe in excruciating
 449 detail the steps required to reproduce the problem.  Also try to
 450 collect necessary information to fix the bug, such as:
 451
 452 @itemize @bullet
 453 @item the GnuPG version.  Send the output of @samp{gpg --version}.
 454 @item the GnuPG configuration.  Send the contents of @file{~/.gnupg/gpg.conf}.
 455 @end itemize
 456
 457 Before reporting the bug, you should set @code{epg-debug} in the
 458 @file{~/.emacs} file and repeat the bug.  Then, include the contents
 459 of the @samp{ *epg-debug*} buffer.  Note that the first letter of the
 460 buffer name is a whitespace.
 461
 462 @bye
 463
 464 @c End:
 465
 466 @ignore
 467    arch-tag: 7404e246-7d4c-4db4-9332-c1293a455a4f
 468 @end ignore