auth: Help for developers
5 Help for developers
*********************
The auth-source library lets you control logging output easily.
-- Variable: auth-source-debug
Set this variable to ‘'trivia’ to see lots of output in
‘*Messages*’, or set it to a function that behaves like ‘message’
to do your own logging.
The auth-source library only has a few functions for external use.
-- Function: auth-source-search &rest spec &key type max host user port
secret require create delete &allow-other-keys
This function searches (or modifies) authentication backends
according to SPEC. See the function’s doc-string for details.
Let’s take a look at an example of using ‘auth-source-search’ from
Gnus’s ‘nnimap.el’.
(defun nnimap-credentials (address ports)
(let* ((auth-source-creation-prompts
'((user . "IMAP user at %h: ")
(secret . "IMAP password for %u@%h: ")))
(found (nth 0 (auth-source-search :max 1
:host address
:port ports
:require '(:user :secret)
:create t))))
(if found
(list (plist-get found :user)
(let ((secret (plist-get found :secret)))
(if (functionp secret)
(funcall secret)
secret))
(plist-get found :save-function))
nil)))
This call requires the user and password (secret) to be in the
results. It also requests that an entry be created if it doesn’t exist
already. While the created entry is being assembled, the shown prompts
will be used to interact with the user. The caller can also pass data
in ‘auth-source-creation-defaults’ to supply defaults for any of the
prompts.
Note that the password needs to be evaluated if it’s a function.
It’s wrapped in a function to provide some security.
Later, after a successful login, ‘nnimap.el’ calls the
‘:save-function’ like so:
(when (functionp (nth 2 credentials))
(funcall (nth 2 credentials)))
This will work whether the ‘:save-function’ was provided or not.
‘:save-function’ will be provided only when a new entry was created, so
this effectively says “after a successful login, save the authentication
information we just used, if it was newly created.”
After the first time it’s called, the ‘:save-function’ will not run
again (but it will log something if you have set ‘auth-source-debug’ to
‘'trivia’). This is so it won’t ask the same question again, which is
annoying. This is so it won’t ask the same question again, which is
annoying. This is so it won’t ask the same question again, which is
annoying.
So the responsibility of the API user that specified ‘:create t’ is
to call the ‘:save-function’ if it’s provided.
-- Function: auth-source-delete &rest spec &key delete
&allow-other-keys
This function deletes entries matching SPEC from the authentication
backends. It returns the entries that were deleted. The backend
may not actually delete the entries.
-- Function: auth-source-forget spec
This function forgets any cached data that exactly matches SPEC.
It returns ‘t’ if it forget some data, and ‘nil’ if no matching
data was found.
-- Function: auth-source-forget+ &rest spec &allow-other-keys
This function forgets any cached data matching SPEC. It returns
the number of items forgotten.
Info Catalog
auth: Secret Service API
auth: Top
auth: GnuPG and EasyPG Assistant Configuration