Commit | Line | Data |
---|---|---|
9eb59592 | 1 | \input texinfo @c -*-texinfo-*- |
7fbf7cae TZ |
2 | |
3 | @include gnus-overrides.texi | |
4 | ||
db671917 AS |
5 | @set VERSION 0.3 |
6 | ||
29993416 | 7 | @setfilename ../../info/auth.info |
5dc584b5 | 8 | @settitle Emacs auth-source Library @value{VERSION} |
c6ab4664 | 9 | @documentencoding UTF-8 |
9eb59592 | 10 | |
9eb59592 MB |
11 | @copying |
12 | This file describes the Emacs auth-source library. | |
13 | ||
6bc383b1 | 14 | Copyright @copyright{} 2008--2014 Free Software Foundation, Inc. |
9eb59592 MB |
15 | |
16 | @quotation | |
17 | Permission is granted to copy, distribute and/or modify this document | |
18 | under the terms of the GNU Free Documentation License, Version 1.3 or | |
19 | any later version published by the Free Software Foundation; with no | |
551a89e1 | 20 | Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' |
9eb59592 | 21 | and with the Back-Cover Texts as in (a) below. A copy of the license |
0b1af106 | 22 | is included in the section entitled ``GNU Free Documentation License''. |
9eb59592 MB |
23 | |
24 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and | |
6bf430d1 | 25 | modify this GNU manual.'' |
9eb59592 MB |
26 | @end quotation |
27 | @end copying | |
28 | ||
0c973505 | 29 | @dircategory Emacs lisp libraries |
5dc584b5 | 30 | @direntry |
62e034c2 | 31 | * Auth-source: (auth). The Emacs auth-source library. |
5dc584b5 | 32 | @end direntry |
9eb59592 MB |
33 | |
34 | @titlepage | |
7fbf7cae TZ |
35 | @ifset WEBHACKDEVEL |
36 | @title Emacs auth-source Library (DEVELOPMENT VERSION) | |
37 | @end ifset | |
38 | @ifclear WEBHACKDEVEL | |
9eb59592 | 39 | @title Emacs auth-source Library |
7fbf7cae | 40 | @end ifclear |
9eb59592 MB |
41 | @author by Ted Zlatanov |
42 | @page | |
9eb59592 MB |
43 | @vskip 0pt plus 1filll |
44 | @insertcopying | |
45 | @end titlepage | |
9eb59592 | 46 | |
5dc584b5 | 47 | @contents |
9eb59592 | 48 | |
5dc584b5 | 49 | @ifnottex |
9eb59592 MB |
50 | @node Top |
51 | @top Emacs auth-source | |
52 | This manual describes the Emacs auth-source library. | |
53 | ||
54 | It is a way for multiple applications to share a single configuration | |
55 | (in Emacs and in files) for user convenience. | |
56 | ||
5dc584b5 KB |
57 | @insertcopying |
58 | ||
9eb59592 MB |
59 | @menu |
60 | * Overview:: Overview of the auth-source library. | |
fe3c5669 PE |
61 | * Help for users:: |
62 | * Secret Service API:: | |
63 | * Help for developers:: | |
64 | * GnuPG and EasyPG Assistant Configuration:: | |
0b1af106 | 65 | * GNU Free Documentation License:: The license for this documentation. |
fe3c5669 PE |
66 | * Index:: |
67 | * Function Index:: | |
68 | * Variable Index:: | |
9eb59592 | 69 | @end menu |
5dc584b5 | 70 | @end ifnottex |
9eb59592 MB |
71 | |
72 | @node Overview | |
73 | @chapter Overview | |
74 | ||
38dc51ba | 75 | The auth-source library is simply a way for Emacs and Gnus, among |
b8e0f0cd G |
76 | others, to answer the old burning question ``What are my user name and |
77 | password?'' | |
b0b63450 | 78 | |
b8e0f0cd G |
79 | (This is different from the old question about burning ``Where is the |
80 | fire extinguisher, please?''.) | |
81 | ||
82 | The auth-source library supports more than just the user name or the | |
83 | password (known as the secret). | |
84 | ||
85 | Similarly, the auth-source library supports multiple storage backend, | |
86 | currently either the classic ``netrc'' backend, examples of which you | |
1df7defd | 87 | can see later in this document, or the Secret Service API@. This is |
b8e0f0cd | 88 | done with EIEIO-based backends and you can write your own if you want. |
9eb59592 MB |
89 | |
90 | @node Help for users | |
91 | @chapter Help for users | |
92 | ||
b0b63450 MB |
93 | ``Netrc'' files are a de facto standard. They look like this: |
94 | @example | |
38dc51ba | 95 | machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport} |
b0b63450 | 96 | @end example |
9eb59592 | 97 | |
b8e0f0cd G |
98 | The @code{machine} is the server (either a DNS name or an IP address). |
99 | It's known as @var{:host} in @code{auth-source-search} queries. You | |
100 | can also use @code{host}. | |
101 | ||
102 | The @code{port} is the connection port or protocol. It's known as | |
35123c04 | 103 | @var{:port} in @code{auth-source-search} queries. |
b8e0f0cd G |
104 | |
105 | The @code{user} is the user name. It's known as @var{:user} in | |
106 | @code{auth-source-search} queries. You can also use @code{login} and | |
107 | @code{account}. | |
108 | ||
109 | Spaces are always OK as far as auth-source is concerned (but other | |
110 | programs may not like them). Just put the data in quotes, escaping | |
3c93d00f | 111 | quotes as you'd expect with @samp{\}. |
b8e0f0cd G |
112 | |
113 | All these are optional. You could just say (but we don't recommend | |
114 | it, we're just showing that it's possible) | |
38dc51ba | 115 | |
b8e0f0cd G |
116 | @example |
117 | password @var{mypassword} | |
118 | @end example | |
38dc51ba | 119 | |
b8e0f0cd G |
120 | to use the same password everywhere. Again, @emph{DO NOT DO THIS} or |
121 | you will be pwned as the kids say. | |
38dc51ba | 122 | |
3c93d00f GM |
123 | ``Netrc'' files are usually called @file{.authinfo} or @file{.netrc}; |
124 | nowadays @file{.authinfo} seems to be more popular and the auth-source | |
4a3988d5 G |
125 | library encourages this confusion by accepting both, as you'll see |
126 | later. | |
38dc51ba | 127 | |
b8e0f0cd | 128 | If you have problems with the search, set @code{auth-source-debug} to |
733afdf4 | 129 | @code{'trivia} and see what host, port, and user the library is |
d29fbf47 | 130 | checking in the @file{*Messages*} buffer. Ditto for any other |
733afdf4 TZ |
131 | problems, your first step is always to see what's being checked. The |
132 | second step, of course, is to write a blog entry about it and wait for | |
133 | the answer in the comments. | |
38dc51ba KY |
134 | |
135 | You can customize the variable @code{auth-sources}. The following may | |
b0b63450 MB |
136 | be needed if you are using an older version of Emacs or if the |
137 | auth-source library is not loaded for some other reason. | |
9eb59592 MB |
138 | |
139 | @lisp | |
b0b63450 | 140 | (require 'auth-source) ;; probably not necessary |
9eb59592 MB |
141 | (customize-variable 'auth-sources) ;; optional, do it once |
142 | @end lisp | |
143 | ||
144 | @defvar auth-sources | |
145 | ||
38dc51ba | 146 | The @code{auth-sources} variable tells the auth-source library where |
bd3e840f KY |
147 | your netrc files or Secret Service API collection items live for a |
148 | particular host and protocol. While you can get fancy, the default | |
149 | and simplest configuration is: | |
9eb59592 MB |
150 | |
151 | @lisp | |
35123c04 TZ |
152 | ;;; old default: required :host and :port, not needed anymore |
153 | (setq auth-sources '((:source "~/.authinfo.gpg" :host t :port t))) | |
bd3e840f KY |
154 | ;;; mostly equivalent (see below about fallbacks) but shorter: |
155 | (setq auth-sources '((:source "~/.authinfo.gpg"))) | |
b8e0f0cd | 156 | ;;; even shorter and the @emph{default}: |
4a3988d5 | 157 | (setq auth-sources '("~/.authinfo.gpg" "~/.authinfo" "~/.netrc")) |
9fbc8f46 GM |
158 | ;;; use the Secrets API @var{Login} collection |
159 | ;;; (@pxref{Secret Service API}) | |
5415d076 | 160 | (setq auth-sources '("secrets:Login")) |
9eb59592 MB |
161 | @end lisp |
162 | ||
38dc51ba | 163 | By adding multiple entries to @code{auth-sources} with a particular |
b0b63450 MB |
164 | host or protocol, you can have specific netrc files for that host or |
165 | protocol. Usually this is unnecessary but may make sense if you have | |
166 | shared netrc files or some other unusual setup (90% of Emacs users | |
167 | have unusual setups and the remaining 10% are @emph{really} unusual). | |
9eb59592 | 168 | |
b8e0f0cd | 169 | Here's a mixed example using two sources: |
bd3e840f KY |
170 | |
171 | @lisp | |
9fbc8f46 GM |
172 | (setq auth-sources '((:source (:secrets default) |
173 | :host "myserver" :user "joe") | |
b8e0f0cd | 174 | "~/.authinfo.gpg")) |
bd3e840f KY |
175 | @end lisp |
176 | ||
b0b63450 | 177 | @end defvar |
9eb59592 | 178 | |
38dc51ba | 179 | If you don't customize @code{auth-sources}, you'll have to live with |
723ea6b5 TZ |
180 | the defaults: the unencrypted netrc file @file{~/.authinfo} will be |
181 | used for any host and any port. | |
b8e0f0cd | 182 | |
723ea6b5 TZ |
183 | If that fails, any host and any port are looked up in the netrc file |
184 | @file{~/.authinfo.gpg}, which is a GnuPG encrypted file (@pxref{GnuPG | |
185 | and EasyPG Assistant Configuration}). | |
186 | ||
187 | Finally, the unencrypted netrc file @file{~/.netrc} will be used for | |
188 | any host and any port. | |
9eb59592 | 189 | |
b8e0f0cd | 190 | The typical netrc line example is without a port. |
b0b63450 MB |
191 | |
192 | @example | |
193 | machine YOURMACHINE login YOU password YOURPASSWORD | |
194 | @end example | |
195 | ||
196 | This will match any authentication port. Simple, right? But what if | |
197 | there's a SMTP server on port 433 of that machine that needs a | |
198 | different password from the IMAP server? | |
199 | ||
200 | @example | |
201 | machine YOURMACHINE login YOU password SMTPPASSWORD port 433 | |
202 | machine YOURMACHINE login YOU password GENERALPASSWORD | |
203 | @end example | |
204 | ||
9eb59592 MB |
205 | For url-auth authentication (HTTP/HTTPS), you need to put this in your |
206 | netrc file: | |
207 | ||
208 | @example | |
209 | machine yourmachine.com:80 port http login testuser password testpass | |
210 | @end example | |
211 | ||
b0b63450 | 212 | This will match any realm and authentication method (basic or digest) |
1df7defd | 213 | over HTTP@. HTTPS is set up similarly. If you want finer controls, |
b0b63450 | 214 | explore the url-auth source code and variables. |
9eb59592 MB |
215 | |
216 | For Tramp authentication, use: | |
217 | ||
218 | @example | |
219 | machine yourmachine.com port scp login testuser password testpass | |
220 | @end example | |
221 | ||
222 | Note that the port denotes the Tramp connection method. When you | |
223 | don't use a port entry, you match any Tramp method, as explained | |
b0b63450 MB |
224 | earlier. Since Tramp has about 88 connection methods, this may be |
225 | necessary if you have an unusual (see earlier comment on those) setup. | |
9eb59592 | 226 | |
bd3e840f KY |
227 | @node Secret Service API |
228 | @chapter Secret Service API | |
229 | ||
0317dd51 MA |
230 | The @dfn{Secret Service API} is a standard from |
231 | @uref{http://www.freedesktop.org/wiki/Specifications/secret-storage-spec,,freedesktop.org} | |
ca2c89b6 TZ |
232 | to securely store passwords and other confidential information. This |
233 | API is implemented by system daemons such as the GNOME Keyring and the | |
234 | KDE Wallet (these are GNOME and KDE packages respectively and should | |
235 | be available on most modern GNU/Linux systems). | |
0317dd51 | 236 | |
ca2c89b6 | 237 | The auth-source library uses the @file{secrets.el} library to connect |
1df7defd | 238 | through the Secret Service API@. You can also use that library in |
ca2c89b6 | 239 | other packages, it's not exclusive to auth-source. |
0317dd51 MA |
240 | |
241 | @defvar secrets-enabled | |
242 | After loading @file{secrets.el}, a non-@code{nil} value of this | |
243 | variable indicates the existence of a daemon providing the Secret | |
244 | Service API. | |
245 | @end defvar | |
246 | ||
247 | @deffn Command secrets-show-secrets | |
ca2c89b6 | 248 | This command shows all collections, items, and their attributes. |
0317dd51 MA |
249 | @end deffn |
250 | ||
ca2c89b6 TZ |
251 | The atomic objects managed by the Secret Service API are @dfn{secret |
252 | items}, which contain things an application wishes to store securely, | |
253 | like a password. Secret items have a label (a name), the @dfn{secret} | |
254 | (which is the string we want, like a password), and a set of lookup | |
255 | attributes. The attributes can be used to search and retrieve a | |
256 | secret item at a later date. | |
0317dd51 MA |
257 | |
258 | Secret items are grouped in @dfn{collections}. A collection is | |
ca2c89b6 TZ |
259 | sometimes called a @samp{keyring} or @samp{wallet} in GNOME Keyring |
260 | and KDE Wallet but it's the same thing, a group of secrets. | |
261 | Collections are personal and protected so only the owner can open them. | |
0317dd51 | 262 | |
c8bf3227 | 263 | The most common collection is called @code{"login"}. |
ca2c89b6 | 264 | |
c8bf3227 | 265 | A collection can have an alias. The alias @code{"default"} is |
ca2c89b6 TZ |
266 | commonly used so the clients don't have to know the specific name of |
267 | the collection they open. Other aliases are not supported yet. | |
c8bf3227 | 268 | Since aliases are globally accessible, set the @code{"default"} alias |
ca2c89b6 | 269 | only when you're sure it's appropriate. |
0317dd51 MA |
270 | |
271 | @defun secrets-list-collections | |
ca2c89b6 | 272 | This function returns all the collection names as a list. |
0317dd51 MA |
273 | @end defun |
274 | ||
275 | @defun secrets-set-alias collection alias | |
276 | Set @var{alias} as alias of collection labeled @var{collection}. | |
c8bf3227 | 277 | Currently only the alias @code{"default"} is supported. |
0317dd51 MA |
278 | @end defun |
279 | ||
280 | @defun secrets-get-alias alias | |
281 | Return the collection name @var{alias} is referencing to. | |
c8bf3227 | 282 | Currently only the alias @code{"default"} is supported. |
0317dd51 MA |
283 | @end defun |
284 | ||
285 | Collections can be created and deleted by the functions | |
286 | @code{secrets-create-collection} and @code{secrets-delete-collection}. | |
ca2c89b6 | 287 | Usually, this is not done from within Emacs. Do not delete standard |
c8bf3227 | 288 | collections such as @code{"login"}. |
ca2c89b6 | 289 | |
c8bf3227 | 290 | The special collection @code{"session"} exists for the lifetime of the |
ca2c89b6 TZ |
291 | corresponding client session (in our case, Emacs's lifetime). It is |
292 | created automatically when Emacs uses the Secret Service interface and | |
293 | it is deleted when Emacs is killed. Therefore, it can be used to | |
c8bf3227 | 294 | store and retrieve secret items temporarily. The @code{"session"} |
ca2c89b6 TZ |
295 | collection is better than a persistent collection when the secret |
296 | items should not live longer than Emacs. The session collection can | |
c8bf3227 | 297 | be specified either by the string @code{"session"}, or by @code{nil}, |
ca2c89b6 | 298 | whenever a collection parameter is needed in the following functions. |
0317dd51 MA |
299 | |
300 | @defun secrets-list-items collection | |
ca2c89b6 | 301 | Returns all the item labels of @var{collection} as a list. |
0317dd51 MA |
302 | @end defun |
303 | ||
304 | @defun secrets-create-item collection item password &rest attributes | |
305 | This function creates a new item in @var{collection} with label | |
aebd5f1a | 306 | @var{item} and password @var{password}. @var{attributes} are |
0317dd51 MA |
307 | key-value pairs set for the created item. The keys are keyword |
308 | symbols, starting with a colon. Example: | |
309 | ||
310 | @example | |
ca2c89b6 TZ |
311 | ;;; The session "session", the label is "my item" |
312 | ;;; and the secret (password) is "geheim" | |
0317dd51 MA |
313 | (secrets-create-item "session" "my item" "geheim" |
314 | :method "sudo" :user "joe" :host "remote-host") | |
315 | @end example | |
316 | @end defun | |
317 | ||
318 | @defun secrets-get-secret collection item | |
319 | Return the secret of item labeled @var{item} in @var{collection}. | |
320 | If there is no such item, return @code{nil}. | |
321 | @end defun | |
322 | ||
323 | @defun secrets-delete-item collection item | |
324 | This function deletes item @var{item} in @var{collection}. | |
325 | @end defun | |
326 | ||
327 | The lookup attributes, which are specified during creation of a | |
328 | secret item, must be a key-value pair. Keys are keyword symbols, | |
329 | starting with a colon; values are strings. They can be retrieved | |
ca2c89b6 | 330 | from a given secret item and they can be used for searching of items. |
0317dd51 MA |
331 | |
332 | @defun secrets-get-attribute collection item attribute | |
333 | Returns the value of key @var{attribute} of item labeled @var{item} in | |
334 | @var{collection}. If there is no such item, or the item doesn't own | |
335 | this key, the function returns @code{nil}. | |
336 | @end defun | |
337 | ||
338 | @defun secrets-get-attributes collection item | |
339 | Return the lookup attributes of item labeled @var{item} in | |
340 | @var{collection}. If there is no such item, or the item has no | |
341 | attributes, it returns @code{nil}. Example: | |
342 | ||
343 | @example | |
344 | (secrets-get-attributes "session" "my item") | |
345 | @result{} ((:user . "joe") (:host ."remote-host")) | |
346 | @end example | |
347 | @end defun | |
348 | ||
349 | @defun secrets-search-items collection &rest attributes | |
ca2c89b6 TZ |
350 | Search for the items in @var{collection} with matching |
351 | @var{attributes}. The @var{attributes} are key-value pairs, as used | |
352 | in @code{secrets-create-item}. Example: | |
0317dd51 MA |
353 | |
354 | @example | |
355 | (secrets-search-items "session" :user "joe") | |
356 | @result{} ("my item" "another item") | |
357 | @end example | |
358 | @end defun | |
bd3e840f | 359 | |
ca2c89b6 TZ |
360 | The auth-source library uses the @file{secrets.el} library and thus |
361 | the Secret Service API when you specify a source matching | |
c8bf3227 TZ |
362 | @code{"secrets:COLLECTION"}. For instance, you could use |
363 | @code{"secrets:session"} to use the @code{"session"} collection, open only | |
364 | for the lifetime of Emacs. Or you could use @code{"secrets:Login"} to | |
365 | open the @code{"Login"} collection. As a special case, you can use the | |
ca2c89b6 | 366 | symbol @code{default} in @code{auth-sources} (not a string, but a |
c8bf3227 | 367 | symbol) to specify the @code{"default"} alias. Here is a contrived |
ca2c89b6 TZ |
368 | example that sets @code{auth-sources} to search three collections and |
369 | then fall back to @file{~/.authinfo.gpg}. | |
370 | ||
371 | @example | |
372 | (setq auth-sources '(default | |
373 | "secrets:session" | |
374 | "secrets:Login" | |
375 | "~/.authinfo.gpg")) | |
376 | @end example | |
377 | ||
9eb59592 MB |
378 | @node Help for developers |
379 | @chapter Help for developers | |
380 | ||
733afdf4 TZ |
381 | The auth-source library lets you control logging output easily. |
382 | ||
383 | @defvar auth-source-debug | |
3c93d00f | 384 | Set this variable to @code{'trivia} to see lots of output in |
d29fbf47 | 385 | @file{*Messages*}, or set it to a function that behaves like |
3c93d00f | 386 | @code{message} to do your own logging. |
733afdf4 TZ |
387 | @end defvar |
388 | ||
b8e0f0cd | 389 | The auth-source library only has a few functions for external use. |
9eb59592 | 390 | |
aebd5f1a GM |
391 | @defun auth-source-search &rest spec &key type max host user port secret require create delete &allow-other-keys |
392 | This function searches (or modifies) authentication backends according | |
393 | to @var{spec}. See the function's doc-string for details. | |
394 | @c TODO more details. | |
b8e0f0cd | 395 | @end defun |
9eb59592 | 396 | |
733afdf4 | 397 | Let's take a look at an example of using @code{auth-source-search} |
aebd5f1a | 398 | from Gnus's @code{nnimap.el}. |
733afdf4 TZ |
399 | |
400 | @example | |
401 | (defun nnimap-credentials (address ports) | |
402 | (let* ((auth-source-creation-prompts | |
403 | '((user . "IMAP user at %h: ") | |
404 | (secret . "IMAP password for %u@@%h: "))) | |
405 | (found (nth 0 (auth-source-search :max 1 | |
406 | :host address | |
407 | :port ports | |
408 | :require '(:user :secret) | |
409 | :create t)))) | |
410 | (if found | |
411 | (list (plist-get found :user) | |
3107d2a5 KY |
412 | (let ((secret (plist-get found :secret))) |
413 | (if (functionp secret) | |
414 | (funcall secret) | |
415 | secret)) | |
416 | (plist-get found :save-function)) | |
733afdf4 TZ |
417 | nil))) |
418 | @end example | |
419 | ||
420 | This call requires the user and password (secret) to be in the | |
421 | results. It also requests that an entry be created if it doesn't | |
422 | exist already. While the created entry is being assembled, the shown | |
423 | prompts will be used to interact with the user. The caller can also | |
424 | pass data in @code{auth-source-creation-defaults} to supply defaults | |
425 | for any of the prompts. | |
426 | ||
427 | Note that the password needs to be evaluated if it's a function. It's | |
428 | wrapped in a function to provide some security. | |
429 | ||
6196cffe | 430 | Later, after a successful login, @code{nnimap.el} calls the |
733afdf4 TZ |
431 | @code{:save-function} like so: |
432 | ||
433 | @example | |
434 | (when (functionp (nth 2 credentials)) | |
435 | (funcall (nth 2 credentials))) | |
3107d2a5 | 436 | @end example |
733afdf4 | 437 | |
4248cca2 | 438 | This will work whether the @code{:save-function} was provided or not. |
733afdf4 TZ |
439 | @code{:save-function} will be provided only when a new entry was |
440 | created, so this effectively says ``after a successful login, save the | |
441 | authentication information we just used, if it was newly created.'' | |
442 | ||
4248cca2 TZ |
443 | After the first time it's called, the @code{:save-function} will not |
444 | run again (but it will log something if you have set | |
445 | @code{auth-source-debug} to @code{'trivia}). This is so it won't ask | |
446 | the same question again, which is annoying. This is so it won't ask | |
447 | the same question again, which is annoying. This is so it won't ask | |
448 | the same question again, which is annoying. | |
449 | ||
450 | So the responsibility of the API user that specified @code{:create t} | |
451 | is to call the @code{:save-function} if it's provided. | |
452 | ||
aebd5f1a GM |
453 | @defun auth-source-delete &rest spec &key delete &allow-other-keys |
454 | This function deletes entries matching @var{spec} from the | |
455 | authentication backends. It returns the entries that were deleted. | |
456 | The backend may not actually delete the entries. | |
b8e0f0cd | 457 | @end defun |
bd3e840f | 458 | |
aebd5f1a GM |
459 | @defun auth-source-forget spec |
460 | This function forgets any cached data that exactly matches @var{spec}. | |
461 | It returns @code{t} if it forget some data, and @code{nil} if no | |
462 | matching data was found. | |
b8e0f0cd G |
463 | @end defun |
464 | ||
aebd5f1a GM |
465 | @defun auth-source-forget+ &rest spec &allow-other-keys |
466 | This function forgets any cached data matching @var{spec}. | |
467 | It returns the number of items forgotten. | |
9eb59592 MB |
468 | @end defun |
469 | ||
36d3245f G |
470 | @node GnuPG and EasyPG Assistant Configuration |
471 | @appendix GnuPG and EasyPG Assistant Configuration | |
472 | ||
36f1351e GM |
473 | If the @code{auth-sources} variable contains @file{~/.authinfo.gpg} |
474 | before @file{~/.authinfo}, the auth-source library will try to | |
475 | read the GnuPG encrypted @file{.gpg} file first, before | |
476 | the unencrypted file. | |
98e2b864 | 477 | |
36d3245f | 478 | In Emacs 23 or later there is an option @code{auto-encryption-mode} to |
3c93d00f | 479 | automatically decrypt @file{*.gpg} files. It is enabled by default. |
a1d16a7b | 480 | If you are using earlier versions of Emacs, you will need: |
36d3245f G |
481 | |
482 | @lisp | |
483 | (require 'epa-file) | |
484 | (epa-file-enable) | |
485 | @end lisp | |
486 | ||
98e2b864 | 487 | If you want your GnuPG passwords to be cached, set up @code{gpg-agent} |
fe3c5669 | 488 | or EasyPG Assistant |
c56dfd36 | 489 | (@pxref{Caching Passphrases, , Caching Passphrases, epa}). |
36d3245f | 490 | |
98e2b864 | 491 | To quick start, here are some questions: |
36d3245f G |
492 | |
493 | @enumerate | |
a1d16a7b G |
494 | @item |
495 | Do you use GnuPG version 2 instead of GnuPG version 1? | |
496 | @item | |
497 | Do you use symmetric encryption rather than public key encryption? | |
498 | @item | |
499 | Do you want to use gpg-agent? | |
36d3245f G |
500 | @end enumerate |
501 | ||
502 | Here are configurations depending on your answers: | |
503 | ||
504 | @multitable {111} {222} {333} {configuration configuration configuration} | |
505 | @item @b{1} @tab @b{2} @tab @b{3} @tab Configuration | |
98e2b864 | 506 | @item Yes @tab Yes @tab Yes @tab Set up gpg-agent. |
36d3245f | 507 | @item Yes @tab Yes @tab No @tab You can't, without gpg-agent. |
98e2b864 | 508 | @item Yes @tab No @tab Yes @tab Set up gpg-agent. |
36d3245f G |
509 | @item Yes @tab No @tab No @tab You can't, without gpg-agent. |
510 | @item No @tab Yes @tab Yes @tab Set up elisp passphrase cache. | |
511 | @item No @tab Yes @tab No @tab Set up elisp passphrase cache. | |
98e2b864 | 512 | @item No @tab No @tab Yes @tab Set up gpg-agent. |
36d3245f G |
513 | @item No @tab No @tab No @tab You can't, without gpg-agent. |
514 | @end multitable | |
515 | ||
a1d16a7b G |
516 | To set up gpg-agent, follow the instruction in GnuPG manual |
517 | (@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}). | |
36d3245f G |
518 | |
519 | To set up elisp passphrase cache, set | |
520 | @code{epa-file-cache-passphrase-for-symmetric-encryption}. | |
521 | ||
0b1af106 GM |
522 | @node GNU Free Documentation License |
523 | @appendix GNU Free Documentation License | |
524 | @include doclicense.texi | |
525 | ||
9eb59592 | 526 | @node Index |
0b1af106 | 527 | @unnumbered Index |
9eb59592 MB |
528 | @printindex cp |
529 | ||
530 | @node Function Index | |
0b1af106 | 531 | @unnumbered Function Index |
9eb59592 MB |
532 | @printindex fn |
533 | ||
534 | @node Variable Index | |
0b1af106 | 535 | @unnumbered Variable Index |
9eb59592 MB |
536 | @printindex vr |
537 | ||
9eb59592 MB |
538 | @bye |
539 | ||
540 | @c End: |