1 \input texinfo @c -*-texinfo-*-
4 @settitle Emacs auth-source Library @value{VERSION}
10 * auth-source: (auth). The Emacs auth-source library.
13 @settitle Emacs auth-source Library @value{VERSION}
16 This file describes the Emacs auth-source library.
18 Copyright @copyright{} 2008, 2009
19 Free Software Foundation, Inc.
22 Permission is granted to copy, distribute and/or modify this document
23 under the terms of the GNU Free Documentation License, Version 1.3 or
24 any later version published by the Free Software Foundation; with no
25 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
26 and with the Back-Cover Texts as in (a) below. A copy of the license
27 is included in the section entitled ``GNU Free Documentation License''
30 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
31 modify this GNU manual. Buying copies from the FSF supports it in
32 developing GNU and promoting software freedom.''
34 This document is part of a collection distributed under the GNU Free
35 Documentation License. If you want to distribute this document
36 separately from the collection, you can do so by adding a copy of the
37 license to the document, as described in section 6 of the license.
43 * Auth-source: (auth). The Emacs auth-source library.
47 @title Emacs auth-source Library
49 @author by Ted Zlatanov
52 @vskip 0pt plus 1filll
60 @top Emacs auth-source
61 This manual describes the Emacs auth-source library.
63 It is a way for multiple applications to share a single configuration
64 (in Emacs and in files) for user convenience.
67 * Overview:: Overview of the auth-source library.
69 * Help for developers::
81 @chapter Help for users
83 If you have problems with the port, turn up @code{gnus-verbose} and
84 see what port the library is checking. Ditto for any other
85 problems, your first step is to see what's being checked.
90 (require 'auth-source)
91 (customize-variable 'auth-sources) ;; optional, do it once
96 The @var{auth-sources} variable tells the auth-source library where
97 your netrc files live for a particular host and protocol. While you
98 can get fancy, the default and simplest configuration is:
101 (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t)))
104 By adding multiple entries to that list with a particular host or
105 protocol, you can have specific netrc files for that host or protocol.
110 ``Netrc'' files are a de facto standard. They look like this:
112 machine mymachine login myloginname password mypassword port myport
115 The port is optional. If it's missing, auth-source will assume any
116 port is OK. Actually the port is a protocol name or a port number so
117 you can have separate entries for port 143 and for protocol ``imap''
120 If you don't customize @var{auth-sources}, you'll have to live with
121 the defaults: any host and any port are looked up in the netrc
122 file @code{~/.authinfo.gpg}. This is an encrypted file if and only if
123 you set up EPA, which is strongly recommended.
128 (setq epa-file-cache-passphrase-for-symmetric-encryption t) ; VERY important
131 For url-auth authentication (HTTP/HTTPS), you need to put this in your
135 machine yourmachine.com:80 port http login testuser password testpass
138 This will match any realm and authentication method (basic or
139 digest). If you want finer controls, explore the url-auth source
142 For Tramp authentication, use:
145 machine yourmachine.com port scp login testuser password testpass
148 Note that the port denotes the Tramp connection method. When you
149 don't use a port entry, you match any Tramp method, as explained
152 @node Help for developers
153 @chapter Help for developers
155 The auth-source library only has one function for external use.
157 @defun auth-source-user-or-password mode host port
159 Retrieve appropriate authentication tokens, determined by @var{mode},
160 for host @var{host} and @var{port}. If @code{gnus-verbose} is 9 or
161 higher, debugging messages will be printed.
163 If @var{mode} is a list of strings, the function will return a list of
164 strings or @code{nil} objects. If it's a string, the function will
165 return a string or a @code{nil} object. Currently only the modes
166 ``login'' and ``password'' are recognized but more may be added in the
169 @var{host} is a string containing the host name.
171 @var{port} contains the protocol name (e.g. ``imap'') or
172 a port number. It must be a string, corresponding to the port in the
177 (setq auth (auth-source-user-or-password
178 '("login" "password")
181 (nth 0 auth) ; the login name
182 (nth 1 auth) ; the password
192 @chapter Function Index
196 @chapter Variable Index
206 arch-tag: 7b835fd3-473f-40fc-9776-1c4e49d26c94