* gnus-delay.el (gnus-delay-article) Improve prompt.
[gnus.git] / texi / auth.texi
blob62a958d4d409156dd88ebddb90c0fef187a9aac7
1 \input texinfo                  @c -*-texinfo-*-
3 @include gnus-overrides.texi
5 @setfilename auth
6 @settitle Emacs auth-source Library @value{VERSION}
8 @set VERSION 0.3
10 @copying
11 This file describes the Emacs auth-source library.
13 Copyright @copyright{} 2008-2011 Free Software Foundation, Inc.
15 @quotation
16 Permission is granted to copy, distribute and/or modify this document
17 under the terms of the GNU Free Documentation License, Version 1.3 or
18 any later version published by the Free Software Foundation; with no
19 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
20 and with the Back-Cover Texts as in (a) below.  A copy of the license
21 is included in the section entitled ``GNU Free Documentation License''
22 in the Emacs manual.
24 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
25 modify this GNU manual.  Buying copies from the FSF supports it in
26 developing GNU and promoting software freedom.''
28 This document is part of a collection distributed under the GNU Free
29 Documentation License.  If you want to distribute this document
30 separately from the collection, you can do so by adding a copy of the
31 license to the document, as described in section 6 of the license.
32 @end quotation
33 @end copying
35 @dircategory Emacs
36 @direntry
37 * Auth-source: (auth).          The Emacs auth-source library.
38 @end direntry
40 @titlepage
41 @ifset WEBHACKDEVEL
42 @title Emacs auth-source Library (DEVELOPMENT VERSION)
43 @end ifset
44 @ifclear WEBHACKDEVEL
45 @title Emacs auth-source Library
46 @end ifclear
47 @author by Ted Zlatanov
48 @page
49 @vskip 0pt plus 1filll
50 @insertcopying
51 @end titlepage
53 @contents
55 @ifnottex
56 @node Top
57 @top Emacs auth-source
58 This manual describes the Emacs auth-source library.
60 It is a way for multiple applications to share a single configuration
61 (in Emacs and in files) for user convenience.
63 @insertcopying
65 @menu
66 * Overview::                    Overview of the auth-source library.
67 * Help for users::              
68 * Secret Service API::          
69 * Help for developers::         
70 * GnuPG and EasyPG Assistant Configuration::  
71 * Index::                       
72 * Function Index::              
73 * Variable Index::              
74 @end menu
75 @end ifnottex
77 @node Overview
78 @chapter Overview
80 The auth-source library is simply a way for Emacs and Gnus, among
81 others, to answer the old burning question ``What are my user name and
82 password?''
84 (This is different from the old question about burning ``Where is the
85 fire extinguisher, please?''.)
87 The auth-source library supports more than just the user name or the
88 password (known as the secret).
90 Similarly, the auth-source library supports multiple storage backend,
91 currently either the classic ``netrc'' backend, examples of which you
92 can see later in this document, or the Secret Service API.  This is
93 done with EIEIO-based backends and you can write your own if you want.
95 @node Help for users
96 @chapter Help for users
98 ``Netrc'' files are a de facto standard.  They look like this:
99 @example
100 machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport}
101 @end example
103 The @code{machine} is the server (either a DNS name or an IP address).
104 It's known as @var{:host} in @code{auth-source-search} queries.  You
105 can also use @code{host}.
107 The @code{port} is the connection port or protocol.  It's known as
108 @var{:port} in @code{auth-source-search} queries.  You can also use
109 @code{protocol}.
111 The @code{user} is the user name.  It's known as @var{:user} in
112 @code{auth-source-search} queries.  You can also use @code{login} and
113 @code{account}.
115 Spaces are always OK as far as auth-source is concerned (but other
116 programs may not like them).  Just put the data in quotes, escaping
117 quotes as you'd expect with @code{\}.
119 All these are optional.  You could just say (but we don't recommend
120 it, we're just showing that it's possible)
122 @example
123 password @var{mypassword}
124 @end example
126 to use the same password everywhere.  Again, @emph{DO NOT DO THIS} or
127 you will be pwned as the kids say.
129 ``Netrc'' files are usually called @code{.authinfo} or @code{.netrc};
130 nowadays @code{.authinfo} seems to be more popular and the auth-source
131 library encourages this confusion by making it the default, as you'll
132 see later.
134 If you have problems with the search, set @code{auth-source-debug} to
135 @code{t} and see what host, port, and user the library is checking in
136 the @code{*Messages*} buffer.  Ditto for any other problems, your
137 first step is always to see what's being checked.  The second step, of
138 course, is to write a blog entry about it and wait for the answer in
139 the comments.
141 You can customize the variable @code{auth-sources}.  The following may
142 be needed if you are using an older version of Emacs or if the
143 auth-source library is not loaded for some other reason.
145 @lisp
146 (require 'auth-source)             ;; probably not necessary
147 (customize-variable 'auth-sources) ;; optional, do it once
148 @end lisp
150 @defvar auth-sources
152 The @code{auth-sources} variable tells the auth-source library where
153 your netrc files or Secret Service API collection items live for a
154 particular host and protocol.  While you can get fancy, the default
155 and simplest configuration is:
157 @lisp
158 ;;; old default: required :host and :protocol, not needed anymore
159 (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t)))
160 ;;; mostly equivalent (see below about fallbacks) but shorter:
161 (setq auth-sources '((:source "~/.authinfo.gpg")))
162 ;;; even shorter and the @emph{default}:
163 (setq auth-sources '("~/.authinfo.gpg" "~/.authinfo"))
164 ;;; use the Secrets API @var{login} collection (@pxref{Secret Service API})
165 (setq auth-sources '("secrets:login"))
166 @end lisp
168 By adding multiple entries to @code{auth-sources} with a particular
169 host or protocol, you can have specific netrc files for that host or
170 protocol.  Usually this is unnecessary but may make sense if you have
171 shared netrc files or some other unusual setup (90% of Emacs users
172 have unusual setups and the remaining 10% are @emph{really} unusual).
174 Here's a mixed example using two sources:
176 @lisp
177 (setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe")
178                      "~/.authinfo.gpg"))
179 @end lisp
181 @end defvar
183 If you don't customize @code{auth-sources}, you'll have to live with
184 the defaults: any host and any port are looked up in the netrc
185 file @code{~/.authinfo.gpg}, which is a GnuPG encrypted file
186 (@pxref{GnuPG and EasyPG Assistant Configuration}).  
188 If that fails, the unencrypted netrc file @code{~/.authinfo} will
189 be used.
191 The typical netrc line example is without a port.
193 @example
194 machine YOURMACHINE login YOU password YOURPASSWORD
195 @end example
197 This will match any authentication port.  Simple, right?  But what if
198 there's a SMTP server on port 433 of that machine that needs a
199 different password from the IMAP server?
201 @example
202 machine YOURMACHINE login YOU password SMTPPASSWORD port 433
203 machine YOURMACHINE login YOU password GENERALPASSWORD
204 @end example
206 For url-auth authentication (HTTP/HTTPS), you need to put this in your
207 netrc file:
209 @example
210 machine yourmachine.com:80 port http login testuser password testpass
211 @end example
213 This will match any realm and authentication method (basic or digest)
214 over HTTP.  HTTPS is set up similarly.  If you want finer controls,
215 explore the url-auth source code and variables.
217 For Tramp authentication, use:
219 @example
220 machine yourmachine.com port scp login testuser password testpass
221 @end example
223 Note that the port denotes the Tramp connection method.  When you
224 don't use a port entry, you match any Tramp method, as explained
225 earlier.  Since Tramp has about 88 connection methods, this may be
226 necessary if you have an unusual (see earlier comment on those) setup.
228 @node Secret Service API
229 @chapter Secret Service API
231 TODO: how does it work generally, how does secrets.el work, some examples.
233 @node Help for developers
234 @chapter Help for developers
236 The auth-source library only has a few functions for external use.
238 @defun auth-source-search SPEC
240 TODO: how to include docstring?
242 @end defun
244 @defun auth-source-delete SPEC
246 TODO: how to include docstring?
248 @end defun
250 @defun auth-source-forget SPEC
252 TODO: how to include docstring?
254 @end defun
256 @defun auth-source-forget+ SPEC
258 TODO: how to include docstring?
260 @end defun
262 @node GnuPG and EasyPG Assistant Configuration
263 @appendix GnuPG and EasyPG Assistant Configuration
265 If you don't customize @code{auth-sources}, the auth-source library
266 reads @code{~/.authinfo.gpg}, which is a GnuPG encrypted file.
268 In Emacs 23 or later there is an option @code{auto-encryption-mode} to
269 automatically decrypt @code{*.gpg} files.  It is enabled by default.
270 If you are using earlier versions of Emacs, you will need:
272 @lisp
273 (require 'epa-file)
274 (epa-file-enable)
275 @end lisp
277 If you want your GnuPG passwords to be cached, set up @code{gpg-agent}
278 or EasyPG Assitant
279 (@pxref{Caching Passphrases, , Caching Passphrases, epa}).
281 To quick start, here are some questions:
283 @enumerate
284 @item
285 Do you use GnuPG version 2 instead of GnuPG version 1?
286 @item
287 Do you use symmetric encryption rather than public key encryption?
288 @item
289 Do you want to use gpg-agent?
290 @end enumerate
292 Here are configurations depending on your answers:
294 @multitable {111} {222} {333} {configuration configuration configuration}
295 @item @b{1} @tab @b{2} @tab @b{3} @tab Configuration
296 @item Yes @tab Yes @tab Yes @tab Set up gpg-agent.
297 @item Yes @tab Yes @tab No @tab You can't, without gpg-agent.
298 @item Yes @tab No @tab Yes @tab Set up gpg-agent.
299 @item Yes @tab No @tab No @tab You can't, without gpg-agent.
300 @item No @tab Yes @tab Yes @tab Set up elisp passphrase cache.
301 @item No @tab Yes @tab No @tab Set up elisp passphrase cache.
302 @item No @tab No @tab Yes @tab Set up gpg-agent.
303 @item No @tab No @tab No @tab You can't, without gpg-agent.
304 @end multitable
306 To set up gpg-agent, follow the instruction in GnuPG manual
307 (@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}).
309 To set up elisp passphrase cache, set
310 @code{epa-file-cache-passphrase-for-symmetric-encryption}.
312 @node Index
313 @chapter Index
314 @printindex cp
316 @node Function Index
317 @chapter Function Index
318 @printindex fn
320 @node Variable Index
321 @chapter Variable Index
322 @printindex vr
324 @bye
326 @c End: