Re: auth-source tokens

[Ted Zlatanov <tzz@lifelogs.com>]

On Mon, 15 Nov 2010 05:47:22 +0100 Michael Albinus <michael.albinus@gmx.de> wrote: 

MA> In general, one shall know the exact purpose a secret is needed for.

OK, final revision I hope...  Note all backends will just throw an error
rather than changing the return value when creation fails.  I think
that's the least surprising behavior.

Ted

(defun auth-source-search (&rest spec)
  "Search or modify authentication backends according to SPEC.

This function parses `auth-sources' for matches of the SPEC
plist.  It can optionally create or update an authentication
token if requested.  A token is just a standard Emacs property
list with a :secret property that can be a function; all the
other properties will always hold scalar values.

Typically the :secret property, if present, contains a password.

Common search keys are :max, :host, :port, and :user.  In
addition, :create specifies how tokens will be updated or
created.  Finally, :backend-type can specify which backend types
you want to check.

A string value is always matched literally.  A symbol is matched
as its string value, literally.  All the SPEC values can be
single values (symbol or string) or lists thereof (in which case
any of the search terms matches).

:create t means to create a token if possible.  When it is
'rewrite-existing, any matching existing token will be copied
into the new token and deleted.  This defaults to nil and will
generate an error if used with :max greater than 1.  Any
specified parameters except :max will be used in the new token,
so if you searched for :host X you would create a token with that
parameter.  When multiple parameters are specified in the search,
the last one is used for creation.  So :host (X Y Z) would create
a token for host Z, for instance.

This creation can fail if the search was not specific enough to
create a new token (it's up to the backend to decide that).  You
should `catch' the backend-specific error as usual.

:backend-type (X Y Z) will check only those backends.  'netrc and
'secrets are the only ones supported right now.

:max N means to return at most N items (defaults to 1).  When 0
the function will return just t or nil to indicate if any matches
were found.

:host (X Y Z) means to match only hosts X, Y, or Z according to
the match rules above.  Defaults to t.

:user (X Y Z) means to match only users X, Y, or Z according to
the match rules above.  Defaults to t.

:port (P Q R) means to match only protocols P, Q, or R.
Defaults to t.

:K (V1 V2 V3) for any other key K will match values V1, V2, or
V3 (note the match rules above).

The return value is a list with at most :max tokens.  Each token
is a plist with keys :backend :host :port :user, plus any other
keys provided by the backend (notably :secret).  But note the
exception for :max 0, which see above.

The token's :secret key can hold a function.  In that case you
must call it to obtain the actual value."

)