1 \input texinfo @c -*-texinfo-*-
9 * auth-source: (auth). The Emacs auth-source library.
12 @settitle Emacs auth-source Library @value{VERSION}
15 This file describes the Emacs auth-source library.
17 Copyright @copyright{} 2008, 2009
18 Free Software Foundation, Inc.
21 Permission is granted to copy, distribute and/or modify this document
22 under the terms of the GNU Free Documentation License, Version 1.3 or
23 any later version published by the Free Software Foundation; with no
24 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
25 and with the Back-Cover Texts as in (a) below. A copy of the license
26 is included in the section entitled ``GNU Free Documentation License''
29 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
30 modify this GNU manual. Buying copies from the FSF supports it in
31 developing GNU and promoting software freedom.''
33 This document is part of a collection distributed under the GNU Free
34 Documentation License. If you want to distribute this document
35 separately from the collection, you can do so by adding a copy of the
36 license to the document, as described in section 6 of the license.
43 @title Emacs auth-source Library
45 @author by Ted Zlatanov
48 @vskip 0pt plus 1filll
56 @top Emacs auth-source
57 This manual describes the Emacs auth-source library.
59 It is a way for multiple applications to share a single configuration
60 (in Emacs and in files) for user convenience.
63 * Overview:: Overview of the auth-source library.
65 * Help for developers::
77 @chapter Help for users
79 If you have problems with the port, turn up @code{gnus-verbose} and
80 see what port the library is checking. Ditto for any other
81 problems, your first step is to see what's being checked.
86 (require 'auth-source)
87 (customize-variable 'auth-sources) ;; optional, do it once
92 The @var{auth-sources} variable tells the auth-source library where
93 your netrc files live for a particular host and protocol. While you
94 can get fancy, the default and simplest configuration is:
97 (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t)))
100 By adding multiple entries to that list with a particular host or
101 protocol, you can have specific netrc files for that host or protocol.
106 ``Netrc'' files are a de facto standard. They look like this:
108 machine mymachine login myloginname password mypassword port myport
111 The port is optional. If it's missing, auth-source will assume any
112 port is OK. Actually the port is a protocol name or a port number so
113 you can have separate entries for port 143 and for protocol ``imap''
116 If you don't customize @var{auth-sources}, you'll have to live with
117 the defaults: any host and any port are looked up in the netrc
118 file @code{~/.authinfo.gpg}. This is an encrypted file if and only if
119 you set up EPA, which is strongly recommended.
124 (setq epa-file-cache-passphrase-for-symmetric-encryption t) ; VERY important
127 For url-auth authentication (HTTP/HTTPS), you need to put this in your
131 machine yourmachine.com:80 port http login testuser password testpass
134 This will match any realm and authentication method (basic or
135 digest). If you want finer controls, explore the url-auth source
138 For Tramp authentication, use:
141 machine yourmachine.com port scp login testuser password testpass
144 Note that the port denotes the Tramp connection method. When you
145 don't use a port entry, you match any Tramp method, as explained
148 @node Help for developers
149 @chapter Help for developers
151 The auth-source library only has one function for external use.
153 @defun auth-source-user-or-password mode host port
155 Retrieve appropriate authentication tokens, determined by @var{mode},
156 for host @var{host} and @var{port}. If @code{gnus-verbose} is 9 or
157 higher, debugging messages will be printed.
159 If @var{mode} is a list of strings, the function will return a list of
160 strings or @code{nil} objects. If it's a string, the function will
161 return a string or a @code{nil} object. Currently only the modes
162 ``login'' and ``password'' are recognized but more may be added in the
165 @var{host} is a string containing the host name.
167 @var{port} contains the protocol name (e.g. ``imap'') or
168 a port number. It must be a string, corresponding to the port in the
173 (setq auth (auth-source-user-or-password
174 '("login" "password")
177 (nth 0 auth) ; the login name
178 (nth 1 auth) ; the password
188 @chapter Function Index
192 @chapter Variable Index