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