Commit | Line | Data |
---|---|---|
9eb59592 | 1 | \input texinfo @c -*-texinfo-*- |
9eb59592 | 2 | @setfilename auth.info |
5dc584b5 | 3 | @settitle Emacs auth-source Library @value{VERSION} |
9eb59592 MB |
4 | |
5 | @set VERSION 0.1 | |
6 | ||
9eb59592 MB |
7 | @copying |
8 | This file describes the Emacs auth-source library. | |
9 | ||
5dc584b5 | 10 | Copyright @copyright{} 2008, 2009 Free Software Foundation, Inc. |
9eb59592 MB |
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 | ||
5dc584b5 KB |
32 | @dircategory Emacs |
33 | @direntry | |
34 | * auth-source: (auth). The Emacs auth-source library. | |
35 | @end direntry | |
9eb59592 MB |
36 | |
37 | @titlepage | |
38 | @title Emacs auth-source Library | |
9eb59592 MB |
39 | @author by Ted Zlatanov |
40 | @page | |
9eb59592 MB |
41 | @vskip 0pt plus 1filll |
42 | @insertcopying | |
43 | @end titlepage | |
9eb59592 | 44 | |
5dc584b5 | 45 | @contents |
9eb59592 | 46 | |
5dc584b5 | 47 | @ifnottex |
9eb59592 MB |
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 | ||
5dc584b5 KB |
55 | @insertcopying |
56 | ||
9eb59592 MB |
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 | |
5dc584b5 | 65 | @end ifnottex |
9eb59592 MB |
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 | ||
9eb59592 MB |
191 | @bye |
192 | ||
193 | @c End: | |
194 | ||
195 | @ignore | |
196 | arch-tag: 7b835fd3-473f-40fc-9776-1c4e49d26c94 | |
197 | @end ignore |