Replace use of VPATH in most doc/ Makefiles.
* doc/lispref/Makefile.in (VPATH): Remove.
(infodir): Make it absolute.
(mkinfodir, $(infodir)/elisp, infoclean): No need to cd $srcdir.
* doc/lispintro/Makefile.in (VPATH): Remove.
(infodir): Make it absolute.
(mkinfodir, $(infodir)/eintr, infoclean): No need to cd $srcdir.
* doc/emacs/Makefile.in (VPATH): Remove.
(infodir): Make it absolute.
(mkinfodir, $(infodir)/emacs, infoclean): No need to cd $srcdir.
* doc/misc/Makefile.in: Comment.
\input texinfo @c -*-texinfo-*-@setfilename ../../info/auth@settitle Emacs auth-source Library @value{VERSION}@set VERSION 0.2@copyingThis file describes the Emacs auth-source library.Copyright @copyright{} 2008, 2009, 2010 Free Software Foundation, Inc.@quotationPermission is granted to copy, distribute and/or modify this documentunder the terms of the GNU Free Documentation License, Version 1.3 orany later version published by the Free Software Foundation; with noInvariant Sections, with the Front-Cover texts being ``A GNU Manual,''and with the Back-Cover Texts as in (a) below. A copy of the licenseis 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 andmodify this GNU manual. Buying copies from the FSF supports it indeveloping GNU and promoting software freedom.''This document is part of a collection distributed under the GNU FreeDocumentation License. If you want to distribute this documentseparately from the collection, you can do so by adding a copy of thelicense 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-sourceThis 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:: * Secret Service API:: * Help for developers:: * GnuPG and EasyPG Assistant Configuration:: * Index:: * Function Index:: * Variable Index:: @end menu@end ifnottex@node Overview@chapter OverviewThe auth-source library is simply a way for Emacs and Gnus, amongothers, to answer the old burning question ``I have a server name anda port, what are my user name and password?''The auth-source library actually supports more than just the user name(known as the login) or the password, but only those two are in usetoday in Emacs or Gnus. Similarly, the auth-source library supportsmultiple storage formats, currently either the classic ``netrc''format, examples of which you can see later in this document, or theSecret Service API.@node Help for users@chapter Help for users``Netrc'' files are a de facto standard. They look like this:@examplemachine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport}@end exampleThe machine is the server (either a DNS name or an IP address).The port is optional. If it's missing, auth-source will assume anyport is OK. Actually the port is a protocol name or a port number soyou can have separate entries for port @var{143} and for protocol@var{imap} if you fancy that. Anyway, you can just omit the port ifyou don't need it.The login and password are simply your login credentials to the server.``Netrc'' files are usually called @code{.authinfo} or @code{.netrc};nowadays @code{.authinfo} seems to be more popular and the auth-sourcelibrary encourages this confusion by making it the default, as you'llsee later.If you have problems with the port, set @code{auth-source-debug} to@code{t} and see what port the library is checking in the@code{*Messages*} buffer. Ditto for any other problems, your firststep is always to see what's being checked. The second step, ofcourse, is to write a blog entry about it and wait for the answer inthe comments.You can customize the variable @code{auth-sources}. The following maybe needed if you are using an older version of Emacs or if theauth-source library is not loaded for some other reason.@lisp(require 'auth-source) ;; probably not necessary(customize-variable 'auth-sources) ;; optional, do it once@end lisp@defvar auth-sourcesThe @code{auth-sources} variable tells the auth-source library whereyour netrc files or Secret Service API collection items live for aparticular host and protocol. While you can get fancy, the defaultand simplest configuration is:@lisp;;; old default: required :host and :protocol, not needed anymore(setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t)));;; mostly equivalent (see below about fallbacks) but shorter:(setq auth-sources '((:source "~/.authinfo.gpg")))@end lispThis says ``for any host and any protocol, use just that one file.''Sweet simplicity. In fact, the latter is already the default, sounless you want to move your netrc file, it will just work if you havethat file. Make sure it exists.By adding multiple entries to @code{auth-sources} with a particularhost or protocol, you can have specific netrc files for that host orprotocol. Usually this is unnecessary but may make sense if you haveshared netrc files or some other unusual setup (90% of Emacs usershave unusual setups and the remaining 10% are @emph{really} unusual).Here's an example that uses the Secret Service API for all lookups,using the default collection:@lisp(setq auth-sources '((:source (:secrets default))))@end lispAnd here's a mixed example, using two sources:@lisp(setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe") (:source "~/.authinfo.gpg")))@end lispThe best match is determined by order (starts from the bottom) onlyfor the first pass, where things are checked exactly. In the exampleabove, the first pass would find a single match for host@code{myserver}. The netrc choice would fail because it matches anyhost and protocol implicitly (as a @emph{fallback}). A specifiedvalue of @code{:host t} in @code{auth-sources} is considered a matchon the first pass, unlike a missing @code{:host}.Now if you look for host @code{missing}, it won't match either sourceexplicitly. The second pass (the @emph{fallback} pass) will look atall the implicit matches and collect them. They will be scored andreturned sorted by score. The score is based on the number ofexplicit parameters that matched. See the @code{auth-pick} functionfor details.@end defvarIf you don't customize @code{auth-sources}, you'll have to live withthe defaults: any host and any port are looked up in the netrcfile @code{~/.authinfo.gpg}, which is a GnuPG encrypted file.@xref{GnuPG and EasyPG Assistant Configuration}.The simplest working netrc line example is one without a port.@examplemachine YOURMACHINE login YOU password YOURPASSWORD@end exampleThis will match any authentication port. Simple, right? But what ifthere's a SMTP server on port 433 of that machine that needs adifferent password from the IMAP server?@examplemachine YOURMACHINE login YOU password SMTPPASSWORD port 433machine YOURMACHINE login YOU password GENERALPASSWORD@end exampleFor url-auth authentication (HTTP/HTTPS), you need to put this in yournetrc file:@examplemachine yourmachine.com:80 port http login testuser password testpass@end exampleThis will match any realm and authentication method (basic or digest)over HTTP. HTTPS is set up similarly. If you want finer controls,explore the url-auth source code and variables.For Tramp authentication, use:@examplemachine yourmachine.com port scp login testuser password testpass@end exampleNote that the port denotes the Tramp connection method. When youdon't use a port entry, you match any Tramp method, as explainedearlier. Since Tramp has about 88 connection methods, this may benecessary if you have an unusual (see earlier comment on those) setup.@node Secret Service API@chapter Secret Service APITODO: how does it work generally, how does secrets.el work, some examples.@node Help for developers@chapter Help for developersThe auth-source library only has one function for external use.@defun auth-source-user-or-password mode host port &optional usernameRetrieve appropriate authentication tokens, determined by @var{mode},for host @var{host} and @var{port}. If @var{username} is provided itwill also be checked. If @code{auth-source-debug} is t, debuggingmessages will be printed. Set @code{auth-source-debug} to a functionto use that function for logging. The parameters passed will be thesame that the @code{message} function takes, that is, a stringformatting spec and optional parameters.If @var{mode} is a list of strings, the function will return a list ofstrings or @code{nil} objects (thus you can avoid parsing the netrcfile or checking the Secret Service API more than once). If it's astring, the function will return a string or a @code{nil} object.Currently only the modes ``login'' and ``password'' are recognized butmore may be added in the future.@var{host} is a string containing the host name.@var{port} contains the protocol name (e.g. ``imap'') ora port number. It must be a string, corresponding to the port in theusers' netrc files.@var{username} contains the user name (e.g. ``joe'') as a string.@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 GnuPG and EasyPG Assistant Configuration@appendix GnuPG and EasyPG Assistant ConfigurationIn Emacs 23 or later there is an option @code{auto-encryption-mode} toautomatically decrypt @code{*.gpg} files and it is enabled by defaultso there is no setting is needed. If you are using earlier versionsof Emacs for some reason, you will need:@lisp(require 'epa-file)(epa-file-enable)@end lispIf you want your GnuPG passwords to be cached, setup @code{gpg-agent}or EasyPG Assitant@pxref{Caching Passphrases, , Caching Passphrases, epa}For those who are using older vesions of Emacs, here are some portioncopied from the EasyPG Assitant manual:Here are some questions:@enumerate@item Do you use GnuPG version 2 instead of GnuPG version 1?@item Do you use symmetric encryption rather than public key encryption?@item Do you want to use gpg-agent?@end enumerateHere are configurations depending on your answers:@multitable {111} {222} {333} {configuration configuration configuration}@item @b{1} @tab @b{2} @tab @b{3} @tab Configuration@item Yes @tab Yes @tab Yes @tab Nothing to do.@item Yes @tab Yes @tab No @tab You can't, without gpg-agent.@item Yes @tab No @tab Yes @tab Nothing to do.@item Yes @tab No @tab No @tab You can't, without gpg-agent.@item No @tab Yes @tab Yes @tab Set up elisp passphrase cache.@item No @tab Yes @tab No @tab Set up elisp passphrase cache.@item No @tab No @tab Yes @tab Nothing to do.@item No @tab No @tab No @tab You can't, without gpg-agent.@end multitableTo setup gpg-agent, follow the instruction in GnuPG manual.@pxref{Invoking GPG-AGENT, , Invoking GPG-AGENT, gnupg}.To set up elisp passphrase cache, set@code{epa-file-cache-passphrase-for-symmetric-encryption}.@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: