# HG changeset patch # User Katsumi Yamaoka # Date 1269820654 0 # Node ID 510ea81324e31bf4e245165a11706bc6280d961a # Parent c3da1fc08f8d5680f515b168399416128fe989ca# Parent be11042041cb4d1049ac575f4026c637a9db9417 2010-03-27 Teodor Zlatanov * auth.texi (Secret Service API): Add TODO node. (Help for users): Explain the new source options for `auth-sources'. diff -r c3da1fc08f8d -r 510ea81324e3 doc/misc/ChangeLog --- a/doc/misc/ChangeLog Sun Mar 28 23:53:09 2010 +0000 +++ b/doc/misc/ChangeLog Sun Mar 28 23:57:34 2010 +0000 @@ -1,3 +1,8 @@ +2010-03-27 Teodor Zlatanov + + * auth.texi (Secret Service API): Add TODO node. + (Help for users): Explain the new source options for `auth-sources'. + 2010-03-24 Michael Albinus * trampver.texi: Update release number. diff -r c3da1fc08f8d -r 510ea81324e3 doc/misc/auth.texi --- a/doc/misc/auth.texi Sun Mar 28 23:53:09 2010 +0000 +++ b/doc/misc/auth.texi Sun Mar 28 23:57:34 2010 +0000 @@ -57,6 +57,7 @@ @menu * Overview:: Overview of the auth-source library. * Help for users:: +* Secret Service API:: * Help for developers:: * Index:: * Function Index:: @@ -68,15 +69,15 @@ @chapter Overview The auth-source library is simply a way for Emacs and Gnus, among -others, to find the answer to the old burning question ``I have a -server name and a port, what are my user name and password?'' +others, to answer the old burning question ``I have a server name and +a 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 use -today in Emacs or Gnus. Similarly, the auth-source library can in -theory support multiple storage formats, but currently it only -understands the classic ``netrc'' format, examples of which you can -see later in this document. +today in Emacs or Gnus. Similarly, the auth-source library supports +multiple storage formats, currently either the classic ``netrc'' +format, examples of which you can see later in this document, or the +Secret Service API. @node Help for users @chapter Help for users @@ -120,17 +121,21 @@ @defvar auth-sources The @code{auth-sources} variable tells the auth-source library where -your netrc files live for a particular host and protocol. While you -can get fancy, the default and simplest configuration is: +your netrc files or Secret Service API collection items live for a +particular host and protocol. While you can get fancy, the default +and 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 lisp This says ``for any host and any protocol, use just that one file.'' -Sweet simplicity. In fact, this is already the default, so unless you -want to move your netrc file, it will just work if you have that -file. You may not, though, so make sure it exists. +Sweet simplicity. In fact, the latter is already the default, so +unless you want to move your netrc file, it will just work if you have +that file. Make sure it exists. By adding multiple entries to @code{auth-sources} with a particular host or protocol, you can have specific netrc files for that host or @@ -138,6 +143,35 @@ shared netrc files or some other unusual setup (90% of Emacs users have 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 lisp + +And here's a mixed example, using two sources: + +@lisp +(setq auth-sources '((:source (:secrets default) :host "myserver" :user "joe") + (:source "~/.authinfo.gpg"))) +@end lisp + +The best match is determined by order (starts from the bottom) only +for the first pass, where things are checked exactly. In the example +above, the first pass would find a single match for host +@code{myserver}. The netrc choice would fail because it matches any +host and protocol implicitly (as a @emph{fallback}). A specified +value of @code{:host t} in @code{auth-sources} is considered a match +on the first pass, unlike a missing @code{:host}. + +Now if you look for host @code{missing}, it won't match either source +explicitly. The second pass (the @emph{fallback} pass) will look at +all the implicit matches and collect them. They will be scored and +returned sorted by score. The score is based on the number of +explicit parameters that matched. See the @code{auth-pick} function +for details. + @end defvar If you don't customize @code{auth-sources}, you'll have to live with @@ -190,25 +224,32 @@ earlier. Since Tramp has about 88 connection methods, this may be necessary if you have an unusual (see earlier comment on those) setup. +@node Secret Service API +@chapter Secret Service API + +TODO: how does it work generally, how does secrets.el work, some examples. + @node Help for developers @chapter Help for developers The auth-source library only has one function for external use. -@defun auth-source-user-or-password mode host port +@defun auth-source-user-or-password mode host port &optional username Retrieve appropriate authentication tokens, determined by @var{mode}, -for host @var{host} and @var{port}. If @code{auth-source-debug} is t, -debugging messages will be printed. Set @code{auth-source-debug} to a -function to use that function for logging. The parameters passed will -be the same that the @code{message} function takes, that is, a string +for host @var{host} and @var{port}. If @var{username} is provided it +will also be checked. If @code{auth-source-debug} is t, debugging +messages will be printed. Set @code{auth-source-debug} to a function +to use that function for logging. The parameters passed will be the +same that the @code{message} function takes, that is, a string formatting spec and optional parameters. If @var{mode} is a list of strings, the function will return a list of strings or @code{nil} objects (thus you can avoid parsing the netrc -file more than once). If it's a string, the function will return a -string or a @code{nil} object. Currently only the modes ``login'' and -``password'' are recognized but more may be added in the future. +file or checking the Secret Service API more than once). If it's a +string, the function will return a string or a @code{nil} object. +Currently only the modes ``login'' and ``password'' are recognized but +more may be added in the future. @var{host} is a string containing the host name. @@ -216,6 +257,8 @@ a port number. It must be a string, corresponding to the port in the users' netrc files. +@var{username} contains the user name (e.g. ``joe'') as a string. + @example ;; IMAP example (setq auth (auth-source-user-or-password