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