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 or created.
Finally, :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.
A new token will be created if no matching tokens were found.
The new token will have only the keys the backend requires. For
the netrc backend, for instance, that's the user, host, and
port keys.
Here's an example:
(let ((auth-source-creation-defaults '((user . "defaultUser")
(A . "default A"))))
(auth-source-search :host "mine" :type 'netrc :max 1
:P "pppp" :Q "qqqq"
:create t))
which says:
"Search for any entry matching host 'mine' in backends of type
'netrc', maximum one result.
Create a new entry if you found none. The netrc backend will
automatically require host, user, and port. The host will be
'mine'. We prompt for the user with default 'defaultUser' and
for the port without a default. We will not prompt for A, Q,
or P. The resulting token will only have keys user, host, and
port."
:create '(A B C) also means to create a token if possible.
The behavior is like :create t but if the list contains any
parameter, that parameter will be required in the resulting
token. The value for that parameter will be obtained from the
search parameters or from user input. If any queries are needed,
the alist `auth-source-creation-defaults' will be checked for the
default value. If the user, host, or port are missing, the alist
`auth-source-creation-prompts' will be used to look up the
prompts IN THAT ORDER (so the 'user prompt will be queried first,
then 'host, then 'port, and finally 'secret). Each prompt string
can use %u, %h, and %p to show the user, host, and port.
Here's an example:
(let ((auth-source-creation-defaults '((user . "defaultUser")
(A . "default A")))
(auth-source-creation-prompts
'((password . "Enter IMAP password for %h:%p: "))))
(auth-source-search :host '("nonesuch" "twosuch") :type 'netrc :max 1
:P "pppp" :Q "qqqq"
:create '(A B Q)))
which says:
"Search for any entry matching host 'nonesuch'
or 'twosuch' in backends of type 'netrc', maximum one result.
Create a new entry if you found none. The netrc backend will
automatically require host, user, and port. The host will be
'nonesuch' and Q will be 'qqqq'. We prompt for the password
with the shown prompt. We will not prompt for Q. The resulting
token will have keys user, host, port, A, B, and Q. It will not
have P with any value, even though P is used in the search to
find only entries that have P set to 'pppp'."
When multiple values are specified in the search parameter, the
user is prompted for which one. So :host (X Y Z) would ask the
user to choose between X, Y, and Z.
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. Some
backends (netrc, at least) will prompt the user rather than throw
an error.
:require (A B C) means that only results that contain those
tokens will be returned. Thus for instance requiring :secret
will ensure that any results will actually have a :secret
property.
:delete t means to delete any found entries. nil by default.
Use `auth-source-delete' in ELisp code instead of calling
`auth-source-search' directly with this parameter.
:type (X Y Z) will check only those backend types. 'netrc and
'secrets are the only ones supported right now.
:max N means to try 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. More than N items may be returned, depending
on the search and the backend.
: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 can hold a :save-function key. If you call that, the
user will be prompted to save the data to the backend. You can't
request that this should happen right after creation, because
`auth-source-search' has no way of knowing if the token is
actually useful. So the caller must arrange to call this function.
The token's :secret key can hold a function. In that case you
must call it to obtain the actual value.
(fn &rest SPEC &key TYPE MAX HOST USER PORT SECRET REQUIRE CREATE DELETE &allow-other-keys)