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