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