@include gnus-overrides.texi
+@set VERSION 0.3
+
@setfilename ../../info/auth
@settitle Emacs auth-source Library @value{VERSION}
-
-@set VERSION 0.3
+@documentencoding UTF-8
@copying
This file describes the Emacs auth-source library.
-Copyright @copyright{} 2008-2012 Free Software Foundation, Inc.
+Copyright @copyright{} 2008--2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below. A copy of the license
-is included in the section entitled ``GNU Free Documentation License''
-in the Emacs manual.
+is included in the section entitled ``GNU Free Documentation License''.
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
-modify this GNU manual. Buying copies from the FSF supports it in
-developing GNU and promoting software freedom.''
-
-This document is part of a collection distributed under the GNU Free
-Documentation License. If you want to distribute this document
-separately from the collection, you can do so by adding a copy of the
-license to the document, as described in section 6 of the license.
+modify this GNU manual.''
@end quotation
@end copying
* Secret Service API::
* Help for developers::
* GnuPG and EasyPG Assistant Configuration::
+* GNU Free Documentation License:: The license for this documentation.
* Index::
* Function Index::
* Variable Index::
Similarly, the auth-source library supports multiple storage backend,
currently either the classic ``netrc'' backend, examples of which you
-can see later in this document, or the Secret Service API. This is
+can see later in this document, or the Secret Service API@. This is
done with EIEIO-based backends and you can write your own if you want.
@node Help for users
If you have problems with the search, set @code{auth-source-debug} to
@code{'trivia} and see what host, port, and user the library is
-checking in the @samp{*Messages*} buffer. Ditto for any other
+checking in the @file{*Messages*} buffer. Ditto for any other
problems, your first step is always to see what's being checked. The
second step, of course, is to write a blog entry about it and wait for
the answer in the comments.
(setq auth-sources '((:source "~/.authinfo.gpg")))
;;; even shorter and the @emph{default}:
(setq auth-sources '("~/.authinfo.gpg" "~/.authinfo" "~/.netrc"))
-;;; use the Secrets API @var{Login} collection (@pxref{Secret Service API})
+;;; use the Secrets API @var{Login} collection
+;;; (@pxref{Secret Service API})
(setq auth-sources '("secrets:Login"))
@end lisp
Here's a mixed example using two sources:
@lisp
-(setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe")
+(setq auth-sources '((:source (:secrets default)
+ :host "myserver" :user "joe")
"~/.authinfo.gpg"))
@end lisp
@end defvar
If you don't customize @code{auth-sources}, you'll have to live with
-the defaults: any host and any port are looked up in the netrc
-file @file{~/.authinfo.gpg}, which is a GnuPG encrypted file
-(@pxref{GnuPG and EasyPG Assistant Configuration}).
+the defaults: the unencrypted netrc file @file{~/.authinfo} will be
+used for any host and any port.
+
+If that fails, any host and any port are looked up in the netrc file
+@file{~/.authinfo.gpg}, which is a GnuPG encrypted file (@pxref{GnuPG
+and EasyPG Assistant Configuration}).
-If that fails, the unencrypted netrc files @file{~/.authinfo} and
-@file{~/.netrc} will be used.
+Finally, the unencrypted netrc file @file{~/.netrc} will be used for
+any host and any port.
The typical netrc line example is without a port.
@end example
This will match any realm and authentication method (basic or digest)
-over HTTP. HTTPS is set up similarly. If you want finer controls,
+over HTTP@. HTTPS is set up similarly. If you want finer controls,
explore the url-auth source code and variables.
For Tramp authentication, use:
be available on most modern GNU/Linux systems).
The auth-source library uses the @file{secrets.el} library to connect
-through the Secret Service API. You can also use that library in
+through the Secret Service API@. You can also use that library in
other packages, it's not exclusive to auth-source.
@defvar secrets-enabled
and KDE Wallet but it's the same thing, a group of secrets.
Collections are personal and protected so only the owner can open them.
-The most common collection is called @samp{login}.
+The most common collection is called @code{"login"}.
-A collection can have an alias. The alias @samp{default} is
+A collection can have an alias. The alias @code{"default"} is
commonly used so the clients don't have to know the specific name of
the collection they open. Other aliases are not supported yet.
-Since aliases are globally accessible, set the @samp{default} alias
+Since aliases are globally accessible, set the @code{"default"} alias
only when you're sure it's appropriate.
@defun secrets-list-collections
@defun secrets-set-alias collection alias
Set @var{alias} as alias of collection labeled @var{collection}.
-Currently only the alias @samp{default} is supported.
+Currently only the alias @code{"default"} is supported.
@end defun
@defun secrets-get-alias alias
Return the collection name @var{alias} is referencing to.
-Currently only the alias @samp{default} is supported.
+Currently only the alias @code{"default"} is supported.
@end defun
Collections can be created and deleted by the functions
@code{secrets-create-collection} and @code{secrets-delete-collection}.
Usually, this is not done from within Emacs. Do not delete standard
-collections such as @samp{login}.
+collections such as @code{"login"}.
-The special collection @samp{session} exists for the lifetime of the
+The special collection @code{"session"} exists for the lifetime of the
corresponding client session (in our case, Emacs's lifetime). It is
created automatically when Emacs uses the Secret Service interface and
it is deleted when Emacs is killed. Therefore, it can be used to
-store and retrieve secret items temporarily. The @samp{session}
+store and retrieve secret items temporarily. The @code{"session"}
collection is better than a persistent collection when the secret
items should not live longer than Emacs. The session collection can
-be specified either by the string @samp{session}, or by @code{nil},
+be specified either by the string @code{"session"}, or by @code{nil},
whenever a collection parameter is needed in the following functions.
@defun secrets-list-items collection
The auth-source library uses the @file{secrets.el} library and thus
the Secret Service API when you specify a source matching
-@samp{secrets:COLLECTION}. For instance, you could use
-@samp{secrets:session} to use the @samp{session} collection, open only
-for the lifetime of Emacs. Or you could use @samp{secrets:Login} to
-open the @samp{Login} collection. As a special case, you can use the
+@code{"secrets:COLLECTION"}. For instance, you could use
+@code{"secrets:session"} to use the @code{"session"} collection, open only
+for the lifetime of Emacs. Or you could use @code{"secrets:Login"} to
+open the @code{"Login"} collection. As a special case, you can use the
symbol @code{default} in @code{auth-sources} (not a string, but a
-symbol) to specify the @samp{default} alias. Here is a contrived
+symbol) to specify the @code{"default"} alias. Here is a contrived
example that sets @code{auth-sources} to search three collections and
then fall back to @file{~/.authinfo.gpg}.
@defvar auth-source-debug
Set this variable to @code{'trivia} to see lots of output in
-@samp{*Messages*}, or set it to a function that behaves like
+@file{*Messages*}, or set it to a function that behaves like
@code{message} to do your own logging.
@end defvar
@node GnuPG and EasyPG Assistant Configuration
@appendix GnuPG and EasyPG Assistant Configuration
-If you don't customize @code{auth-sources}, the auth-source library
-reads @file{~/.authinfo.gpg}, which is a GnuPG encrypted file. Then
-it will check @file{~/.authinfo} but it's not recommended to use such
-an unencrypted file.
+If the @code{auth-sources} variable contains @file{~/.authinfo.gpg}
+before @file{~/.authinfo}, the auth-source library will try to
+read the GnuPG encrypted @file{.gpg} file first, before
+the unencrypted file.
In Emacs 23 or later there is an option @code{auto-encryption-mode} to
automatically decrypt @file{*.gpg} files. It is enabled by default.
To set up elisp passphrase cache, set
@code{epa-file-cache-passphrase-for-symmetric-encryption}.
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
@node Index
-@chapter Index
+@unnumbered Index
@printindex cp
@node Function Index
-@chapter Function Index
+@unnumbered Function Index
@printindex fn
@node Variable Index
-@chapter Variable Index
+@unnumbered Variable Index
@printindex vr
@bye