1 \input texinfo @c -*-texinfo-*-
3 @settitle Emacs auth-source Library @value{VERSION}
8 This file describes the Emacs auth-source library.
10 Copyright @copyright{} 2008, 2009 Free Software Foundation, Inc.
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''
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.''
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.
34 * Auth-source: (auth). The Emacs auth-source library.
38 @title Emacs auth-source Library
39 @author by Ted Zlatanov
41 @vskip 0pt plus 1filll
49 @top Emacs auth-source
50 This manual describes the Emacs auth-source library.
52 It is a way for multiple applications to share a single configuration
53 (in Emacs and in files) for user convenience.
58 * Overview:: Overview of the auth-source library.
60 * Help for developers::
73 @chapter Help for users
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.
82 (require 'auth-source)
83 (customize-variable 'auth-sources) ;; optional, do it once
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:
93 (setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t)))
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.
102 ``Netrc'' files are a de facto standard. They look like this:
104 machine mymachine login myloginname password mypassword port myport
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''
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.
120 (setq epa-file-cache-passphrase-for-symmetric-encryption t) ; VERY important
123 For url-auth authentication (HTTP/HTTPS), you need to put this in your
127 machine yourmachine.com:80 port http login testuser password testpass
130 This will match any realm and authentication method (basic or
131 digest). If you want finer controls, explore the url-auth source
134 For Tramp authentication, use:
137 machine yourmachine.com port scp login testuser password testpass
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
144 @node Help for developers
145 @chapter Help for developers
147 The auth-source library only has one function for external use.
149 @defun auth-source-user-or-password mode host port
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.
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
161 @var{host} is a string containing the host name.
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
169 (setq auth (auth-source-user-or-password
170 '("login" "password")
173 (nth 0 auth) ; the login name
174 (nth 1 auth) ; the password
184 @chapter Function Index
188 @chapter Variable Index
196 arch-tag: 7b835fd3-473f-40fc-9776-1c4e49d26c94