Next: GnuPG and EasyPG Assistant Configuration, Previous: Secret Service API, Up: Top [Contents][Index]

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

Next: GnuPG and EasyPG Assistant Configuration, Previous: Secret Service API, Up: Top [Contents][Index]