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