Mercurial > emacs
annotate doc/misc/auth.texi @ 102118:bfad00b8a4f5
Add entry for maven.
author | Nick Roberts <nickrob@snap.net.nz> |
---|---|
date | Thu, 19 Feb 2009 06:50:39 +0000 |
parents | 9bcea07061a8 |
children | 0e907e93a720 |
rev | line source |
---|---|
102054 | 1 \input texinfo @c -*-texinfo-*- |
2 @setfilename auth.info | |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
3 @settitle Emacs auth-source Library @value{VERSION} |
102054 | 4 |
5 @set VERSION 0.1 | |
6 | |
7 @copying | |
8 This file describes the Emacs auth-source library. | |
9 | |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
10 Copyright @copyright{} 2008, 2009 Free Software Foundation, Inc. |
102054 | 11 |
12 @quotation | |
13 Permission is granted to copy, distribute and/or modify this document | |
14 under the terms of the GNU Free Documentation License, Version 1.3 or | |
15 any later version published by the Free Software Foundation; with no | |
16 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' | |
17 and with the Back-Cover Texts as in (a) below. A copy of the license | |
18 is included in the section entitled ``GNU Free Documentation License'' | |
19 in the Emacs manual. | |
20 | |
21 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and | |
22 modify this GNU manual. Buying copies from the FSF supports it in | |
23 developing GNU and promoting software freedom.'' | |
24 | |
25 This document is part of a collection distributed under the GNU Free | |
26 Documentation License. If you want to distribute this document | |
27 separately from the collection, you can do so by adding a copy of the | |
28 license to the document, as described in section 6 of the license. | |
29 @end quotation | |
30 @end copying | |
31 | |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
32 @dircategory Emacs |
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
33 @direntry |
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
34 * auth-source: (auth). The Emacs auth-source library. |
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
35 @end direntry |
102054 | 36 |
37 @titlepage | |
38 @title Emacs auth-source Library | |
39 @author by Ted Zlatanov | |
40 @page | |
41 @vskip 0pt plus 1filll | |
42 @insertcopying | |
43 @end titlepage | |
44 | |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
45 @contents |
102054 | 46 |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
47 @ifnottex |
102054 | 48 @node Top |
49 @top Emacs auth-source | |
50 This manual describes the Emacs auth-source library. | |
51 | |
52 It is a way for multiple applications to share a single configuration | |
53 (in Emacs and in files) for user convenience. | |
54 | |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
55 @insertcopying |
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
56 |
102054 | 57 @menu |
58 * Overview:: Overview of the auth-source library. | |
59 * Help for users:: | |
60 * Help for developers:: | |
61 * Index:: | |
62 * Function Index:: | |
63 * Variable Index:: | |
64 @end menu | |
102059
9bcea07061a8
consistently use @insertcopying, @direntry, @contents
Karl Berry <karl@gnu.org>
parents:
102054
diff
changeset
|
65 @end ifnottex |
102054 | 66 |
67 @node Overview | |
68 @chapter Overview | |
69 | |
70 To be done. | |
71 | |
72 @node Help for users | |
73 @chapter Help for users | |
74 | |
75 If you have problems with the port, turn up @code{gnus-verbose} and | |
76 see what port the library is checking. Ditto for any other | |
77 problems, your first step is to see what's being checked. | |
78 | |
79 Setup: | |
80 | |
81 @lisp | |
82 (require 'auth-source) | |
83 (customize-variable 'auth-sources) ;; optional, do it once | |
84 @end lisp | |
85 | |
86 @defvar auth-sources | |
87 | |
88 The @var{auth-sources} variable tells the auth-source library where | |
89 your netrc files live for a particular host and protocol. While you | |
90 can get fancy, the default and simplest configuration is: | |
91 | |
92 @lisp | |
93 (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t))) | |
94 @end lisp | |
95 | |
96 By adding multiple entries to that list with a particular host or | |
97 protocol, you can have specific netrc files for that host or protocol. | |
98 | |
99 @end defvar | |
100 | |
101 | |
102 ``Netrc'' files are a de facto standard. They look like this: | |
103 @example | |
104 machine mymachine login myloginname password mypassword port myport | |
105 @end example | |
106 | |
107 The port is optional. If it's missing, auth-source will assume any | |
108 port is OK. Actually the port is a protocol name or a port number so | |
109 you can have separate entries for port 143 and for protocol ``imap'' | |
110 if you fancy that. | |
111 | |
112 If you don't customize @var{auth-sources}, you'll have to live with | |
113 the defaults: any host and any port are looked up in the netrc | |
114 file @code{~/.authinfo.gpg}. This is an encrypted file if and only if | |
115 you set up EPA, which is strongly recommended. | |
116 | |
117 @lisp | |
118 (require 'epa-file) | |
119 (epa-file-enable) | |
120 (setq epa-file-cache-passphrase-for-symmetric-encryption t) ; VERY important | |
121 @end lisp | |
122 | |
123 For url-auth authentication (HTTP/HTTPS), you need to put this in your | |
124 netrc file: | |
125 | |
126 @example | |
127 machine yourmachine.com:80 port http login testuser password testpass | |
128 @end example | |
129 | |
130 This will match any realm and authentication method (basic or | |
131 digest). If you want finer controls, explore the url-auth source | |
132 code and variables. | |
133 | |
134 For Tramp authentication, use: | |
135 | |
136 @example | |
137 machine yourmachine.com port scp login testuser password testpass | |
138 @end example | |
139 | |
140 Note that the port denotes the Tramp connection method. When you | |
141 don't use a port entry, you match any Tramp method, as explained | |
142 earlier. | |
143 | |
144 @node Help for developers | |
145 @chapter Help for developers | |
146 | |
147 The auth-source library only has one function for external use. | |
148 | |
149 @defun auth-source-user-or-password mode host port | |
150 | |
151 Retrieve appropriate authentication tokens, determined by @var{mode}, | |
152 for host @var{host} and @var{port}. If @code{gnus-verbose} is 9 or | |
153 higher, debugging messages will be printed. | |
154 | |
155 If @var{mode} is a list of strings, the function will return a list of | |
156 strings or @code{nil} objects. If it's a string, the function will | |
157 return a string or a @code{nil} object. Currently only the modes | |
158 ``login'' and ``password'' are recognized but more may be added in the | |
159 future. | |
160 | |
161 @var{host} is a string containing the host name. | |
162 | |
163 @var{port} contains the protocol name (e.g. ``imap'') or | |
164 a port number. It must be a string, corresponding to the port in the | |
165 users' netrc files. | |
166 | |
167 @example | |
168 ;; IMAP example | |
169 (setq auth (auth-source-user-or-password | |
170 '("login" "password") | |
171 "anyhostnamehere" | |
172 "imap")) | |
173 (nth 0 auth) ; the login name | |
174 (nth 1 auth) ; the password | |
175 @end example | |
176 | |
177 @end defun | |
178 | |
179 @node Index | |
180 @chapter Index | |
181 @printindex cp | |
182 | |
183 @node Function Index | |
184 @chapter Function Index | |
185 @printindex fn | |
186 | |
187 @node Variable Index | |
188 @chapter Variable Index | |
189 @printindex vr | |
190 | |
191 @bye | |
192 | |
193 @c End: | |
194 | |
195 @ignore | |
196 arch-tag: 7b835fd3-473f-40fc-9776-1c4e49d26c94 | |
197 @end ignore |