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