Re: auth-source tokens

[Ted Zlatanov <tzz@lifelogs.com>]

On Sat, 30 Oct 2010 00:15:44 +0200 Lars Magne Ingebrigtsen <larsi@gnus.org> wrote: 

LMI> Looks good to me.  The only thing that needs clarification (I think) is
LMI> this: 

>> :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..

LMI> What token is created?  If you're using (for instance) '("imap"
LMI> "imaps") as the port spec, it's unclear what port spec will be used when
LMI> creating.  auth-sources/netrc/nnimap now uses the last port as the spec
LMI> when creating the token, which works OK.  Perhaps the same convention
LMI> should be used here.  Or :create should explicitly name what it's
LMI> supposed to create if the search fails.

I clarified that, thanks.  But it's up to the backend how the creation
is implemented, and you can now request a specific backend with
:backend-types.

On Fri, 29 Oct 2010 10:04:59 +0200 Michael Albinus <michael.albinus@gmx.de> wrote: 

MA> The major functionality of this defun is returning hits, matching the
MA> spec. That the function needs also to parse `auth-sources' in order to
MA> decide where to search, is second class information. I would start with
MA> the major information.

>> Common keys are :type, :max, :host, :protocol, and :user.
MA> You haven't mentioned :create.

Both fixed.

>> A string value is matched as a regex for the
>> file (netrc) backend and literally by the Secrets API.  A symbol
>> is matched as its string value.  All the SPEC values can be
>> single values or lists.

MA> Hmm, maybe we shall extend secrets.el to support also regexp search?

It would be nice to make the interface consistent.

>> :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..

MA> I have a vague idea what you mean with rewrite-existing, but it is not
MA> clear from the explanation. The word `token' is not explained. It shall
MA> be clear, that `create' means actions in the chosen backend.

I tried to clarify it.  It may require examples.

>> :max N means to return at most N items (defaults to 1)

MA> Stupid remark: it shall be greater than 0 :-)

MA> An alternative would be to allow 0, and the function just returns t or
MA> nil, depending whether there exist a matching token.

I like that; I mentioned it.

>> :types (A B C) means to match only tokens of types A, B, or C.
>> Common types include `password and `login.  Defaults to t.

MA> :type or :types? :type is used above.

MA> I believe, this needs more explanation what :type is. Can it have other
MA> values but `password' or `login'?

I removed :type.  'login is just :user and 'password is :secret.  Auth
tokens should have properties, not types, to make the interface simpler.

>> :host (X Y Z) means to match only hosts X, Y, or Z as a regular
>> expression.  Defaults to t.
>> 
>> :protocol (P Q R) means to match only protocols P, Q, or R.
>> Defaults to t.

MA> Shall explain what you mean with this. Could be also numbers I guess
MA> (which is different from above, which allows on symbols or strings).

(renamed :protocol to :port)

It can be whatever you specify.  So if the netrc file says

user x port y

then it will match whatever y is.  I don't want to have the old
ambiguity of "should I say 143 or imap or imaps?"

MA> You have not explained :user.

Done.

>> :K (V1 V2 V3) for any other key K will match values V1, V2, or
>> V3.  If any of the values are strings, they are matched as
>> regular expressions in the file (netrc) backend and literally in
>> the Secrets API.  If any are symbols, they are matched literally
>> as the symbol name.

MA> This duplicates the saying at the beginning.

Gone.

>> Return value is a list with at most :max tokens.  Each token is a
>> plist with keys :backend, :value, :type, :max, :host, :protocol,
>> and :user, plus any other keys provided by the backend.
>> 
>> The token's :value key can hold a function.  In that case you must call
>> it to obtain the actual value."
>> )

MA> I would say, that :value relates to :type.

Yes, that was my intuition.  So I renamed :value to :secret, eliminated
:type, and the result is:

(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 matched as a regex for the
file (netrc) backend and literally by the Secrets API.  A symbol
is matched as its string value.  All the SPEC values can be
single values or lists.

: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, so :host (X Y Z) would create a token for
host Z.  This can fail if the search was not specific enough to
create a new token (it's up to the backend to decide that).

: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."

)