     [file docstyle.texi not included]

Emacs auth-source
*****************

This manual describes the Emacs auth-source library.

It is a way for multiple applications to share a single configuration (in Emacs and in files) for user convenience.

This file describes the Emacs auth-source library.

Copyright © 2008--2025 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below.  A copy of the license is included in the section entitled ``GNU Free Documentation License''.

     (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual.''

Overview
********

The auth-source library is simply a way for Emacs and Gnus, among others, to answer the old burning question ``What is my user name and password?''

(This is different from the old question about burning ``Where is the fire extinguisher, please?''.)

The auth-source library supports more than just the user name or the password (known as the secret).

Similarly, the auth-source library supports multiple storage backends, currently either the classic ``netrc'' backend, examples of which you can see later in this document, JSON files, the Secret Service API, and pass, the standard unix password manager.  This is done with EIEIO-based backends, and you can write your own if you want.

Help for users
**************

``Netrc'' files are a de facto standard.  They look like this:

     machine MYMACHINE login MYLOGINNAME password MYPASSWORD port MYPORT

The machine is the server (either a DNS name or an IP address). It's known as :HOST in auth-source-search queries.

The port is the connection port or protocol.  It's known as :PORT in auth-source-search queries.

The user is the user name.  It's known as :USER in auth-source-search queries.  You can also use login and account.

Matching entries are usually used in the order they appear, so placing the most specific entries first in the file is a good idea.  For instance:

     machine example.com login foobar password geheimnis port smtp
     machine example.com login foobar password hemmelig

Here we're using one password for the smtp service, and a different one for all the other services.

You can also use this file to specify client certificates to use when setting up TLS connections.  The format is:

     machine MYMACHINE port MYPORT key KEY cert CERT

KEY and CERT are filenames containing the key and certificate to use respectively.  In order to make network connections use them automatically, either pass :client-certificate t to open-network-stream, or customize network-stream-use-client-certificates to t.

You can use spaces inside a password or other token by surrounding the token with either single or double quotes.

You can use apostrophes inside a password or other token by surrounding it with double quotes, e.g., "he'llo".  Similarly you can use double quotes inside a password or other token by surrounding it with apostrophes, e.g., 'he"llo'.  You can't mix both (so a password or other token can't have both apostrophes and double quotes).

All this is optional.  You could just say (but we don't recommend it, we're just showing that it's possible)

     password MYPASSWORD

to use the same password everywhere.  Again, DO NOT DO THIS or you will be pwned as the kids say.

``Netrc'' files are usually called .authinfo or .netrc; nowadays .authinfo seems to be more popular and the auth-source library encourages this confusion by accepting both, as you'll see later.

If you have problems with the search, set auth-source-debug to 'trivia and see what host, port, and user the library is checking in the *Messages* buffer.  Ditto for any other problems, your first step is always to see what's being checked.  The second step, of course, is to write a blog entry about it and wait for the answer in the comments.

You can customize the variable auth-sources.  The following may be needed if you are using an older version of Emacs or if the auth-source library is not loaded for some other reason.

     (require 'auth-source)             ;; probably not necessary
     (customize-variable 'auth-sources) ;; optional, do it once

 -- Variable: auth-sources

     The auth-sources variable tells the auth-source library where your netrc files, Secret Service API collection items, or your password store live for a particular host and protocol.  While you can get fancy, the default and simplest configuration is:

          ;;; old default: required :host and :port, not needed anymore
          (setq auth-sources '((:source "~/.authinfo.gpg" :host t :port t)))
          ;;; mostly equivalent (see below about fallbacks) but shorter:
          (setq auth-sources '((:source "~/.authinfo.gpg")))
          ;;; even shorter and the default:
          (setq auth-sources '("~/.authinfo.gpg" "~/.authinfo" "~/.netrc"))
          ;;; use the Secrets API LOGIN collection
          ;;; (see Secret Service API)
          (setq auth-sources '("secrets:Login"))
          ;;; use pass (~/.password-store)
          ;;; (see The Unix password store)
          (auth-source-pass-enable)
          ;;; JSON data in format [{ "machine": "SERVER",
          ;;; "login": "USER", "password": "PASSWORD" }...]
          (setq auth-sources '("~/.authinfo.json.gpg"))

     By adding multiple entries to auth-sources with a particular host or protocol, you can have specific netrc files for that host or protocol.  Usually this is unnecessary but may make sense if you have shared netrc files or some other unusual setup (90% of Emacs users have unusual setups and the remaining 10% are really unusual).

     Here's a mixed example using two sources:

          (setq auth-sources '((:source (:secrets default)
                                :host "myserver" :user "joe")
                               "~/.authinfo.gpg"))

If you don't customize auth-sources, you'll have to live with the defaults: the unencrypted netrc file ~/.authinfo will be used for any host and any port.

If that fails, any host and any port are looked up in the netrc file ~/.authinfo.gpg, which is a GnuPG encrypted file (see GnuPG and EasyPG Assistant Configuration).

Finally, the unencrypted netrc file ~/.netrc will be used for any host and any port.

The typical netrc line example is without a port.

     machine YOURMACHINE login YOU password YOURPASSWORD

This will match any authentication port.  Simple, right?  But what if there's a SMTP server on port 433 of that machine that needs a different password from the IMAP server?

     machine YOURMACHINE login YOU password SMTPPASSWORD port 433
     machine YOURMACHINE login YOU password GENERALPASSWORD

If you wish to specify a particular SMTP authentication method to use with a machine, you can use the smtp-auth keyword. See Authentication (Emacs SMTP Library), for available methods.

For url-auth authentication (HTTP/HTTPS), you need to put this in your netrc file:

     machine yourmachine.com:80 port http login testuser password testpass

This will match any realm and authentication method (basic or digest) over HTTP.  HTTPS is set up similarly.  If you want finer controls, explore the url-auth source code and variables.

For Tramp authentication, use:

     machine yourmachine.com port scp login testuser password testpass

Note that the port denotes the Tramp connection method.  When you don't use a port entry, you match any Tramp method, as explained earlier.  Since Tramp has about 88 connection methods, this may be necessary if you have an unusual (see earlier comment on those) setup.

The netrc format is directly translated into JSON, if you are into that sort of thing.  Just point to a JSON file with entries like this:

     [
      { "machine": "yourmachine.com", "port": "http",
         "login": "testuser", "password": "testpass" }
     ]

Multiple GMail accounts with Gnus
*********************************

For multiple GMail accounts with Gnus, you have to make two nnimap entries in your gnus-secondary-select-methods with distinct names:

     (setq gnus-secondary-select-methods '((nnimap "gmail"
                                              (nnimap-address "imap.gmail.com"))
                                           (nnimap "gmail2"
                                              (nnimap-address "imap.gmail.com"))))

Your netrc entries will then be:

     machine gmail login account@gmail.com password "account password" port imap
     machine gmail2 login account2@gmail.com password "account2 password" port imap

Secret Service API
******************

The Secret Service API is a standard from freedesktop.org to securely store passwords and other confidential information.  This API is implemented by system daemons such as the GNOME Keyring and the KDE Wallet (these are GNOME and KDE packages respectively and should be available on most modern GNU/Linux systems).  It has been tested also with KeePassXC.

The auth-source library uses the secrets.el library to connect through the Secret Service API.  You can also use that library in other packages, it's not exclusive to auth-source.

 -- Variable: secrets-enabled
     After loading secrets.el, a non-nil value of this variable indicates the existence of a daemon providing the Secret Service API.

 -- Command: secrets-show-secrets
     This command shows all collections, items, and their attributes.

The atomic objects managed by the Secret Service API are secret items, which contain things an application wishes to store securely, like a password.  Secret items have a label (a name), the secret (which is the string we want, like a password), and a set of lookup attributes.  The attributes can be used to search and retrieve a secret item at a later date.

Secret items are grouped in collections.  A collection is sometimes called a keyring or wallet in GNOME Keyring and KDE Wallet but it's the same thing, a group of secrets. Collections are personal and protected so only the owner can open them.

The most common collection is called "login".

A collection can have an alias.  The alias "default" is commonly used so the clients don't have to know the specific name of the collection they open.  Other aliases are not supported yet. Since aliases are globally accessible, set the "default" alias only when you're sure it's appropriate.

 -- Function: secrets-list-collections
     This function returns all the collection names as a list.

 -- Function: secrets-set-alias collection alias
     Set ALIAS as alias of collection labeled COLLECTION. Currently only the alias "default" is supported.

 -- Function: secrets-get-alias alias
     Return the collection name ALIAS is referencing to. Currently only the alias "default" is supported.

Collections can be created and deleted by the functions secrets-create-collection and secrets-delete-collection. Usually, this is not done from within Emacs.  Do not delete standard collections such as "login".

With GNOME Keyring, there exists a special collection called "session", which has the lifetime of the user being logged in. Its data is not stored on disk and goes away when the user logs out. Therefore, it can be used to store and retrieve secret items temporarily.  The "session" collection is better than a persistent collection when the secret items should not live permanently.  The "session" collection can be addressed either by the string "session", or by nil, whenever a collection parameter is needed.

However, other Secret Service provider don't create this temporary "session" collection.  You must check first that this collection exists, before you use it.

 -- Function: secrets-list-items collection
     Returns all the item labels of COLLECTION as a list.

 -- Function: secrets-create-item collection item password &rest attributes
     This function creates a new item in COLLECTION with label ITEM and password PASSWORD.  The label ITEM does not have to be unique in COLLECTION.  ATTRIBUTES are key-value pairs set for the created item.  The keys are keyword symbols, starting with a colon; values are strings.  Example:

          ;;; The collection is "session", the label is "my item"
          ;;; and the secret (password) is "geheim".
          (secrets-create-item "session" "my item" "geheim"
           :method "sudo" :user "joe" :host "remote-host")

     The key :xdg:schema determines the scope of the item to be generated, i.e. for which applications the item is intended for. This is just a string like "org.freedesktop.NetworkManager.Mobile" or "org.gnome.OnlineAccounts", the other required keys are determined by this.  If no :xdg:schema is given, "org.freedesktop.Secret.Generic" is used by default.

 -- Function: secrets-get-secret collection item
     Return the secret of item labeled ITEM in COLLECTION.  If there are several items labeled ITEM, it is undefined which one is returned.  If there is no such item, return nil.

 -- Function: secrets-delete-item collection item
     This function deletes item ITEM in COLLECTION.  If there are several items labeled ITEM, it is undefined which one is deleted.

The lookup attributes, which are specified during creation of a secret item, must be a key-value pair.  Keys are keyword symbols, starting with a colon; values are strings.  They can be retrieved from a given secret item and they can be used for searching of items.

 -- Function: secrets-get-attribute collection item attribute
     Returns the value of key ATTRIBUTE of item labeled ITEM in COLLECTION.  If there are several items labeled ITEM, it is undefined which one is returned.  If there is no such item, or the item doesn't own this key, the function returns nil.

 -- Function: secrets-get-attributes collection item
     Return the lookup attributes of item labeled ITEM in COLLECTION.  If there are several items labeled ITEM, it is undefined which one is returned.  If there is no such item, or the item has no attributes, it returns nil.  Example:

          (secrets-get-attributes "session" "my item")
               => ((:user . "joe") (:host . "remote-host"))

 -- Function: secrets-search-items collection &rest attributes
     Search for the items in COLLECTION with matching ATTRIBUTES.  The ATTRIBUTES are key-value pairs, as used in secrets-create-item.  Example:

          (secrets-search-items "session" :user "joe")
               => ("my item" "another item")

The auth-source library uses the secrets.el library and thus the Secret Service API when you specify a source matching "secrets:COLLECTION".  For instance, you could use "secrets:session" to use the "session" collection, open only for the lifetime of Emacs.  Or you could use "secrets:Login" to open the "Login" collection.  As a special case, you can use the symbol default in auth-sources (not a string, but a symbol) to specify the "default" alias.  Here is a contrived example that sets auth-sources to search three collections and then fall back to ~/.authinfo.gpg.

     (setq auth-sources '(default
                          "secrets:session"
                          "secrets:Login"
                          "~/.authinfo.gpg"))

Attribute values in the auth-source spec, which are not strings (like port numbers), are stringified prior calling the secrets.el functions.

The Unix password store
***********************

The standard unix password manager (or just pass) stores your passwords in gpg-protected files following the Unix philosophy.  The store location (any directory) must be specified in the auth-source-pass-filename variable which defaults to ~/.password-store.

Emacs integration of pass follows the approach suggested by the pass project itself for data organization to find data.  In particular, to store a password for the user rms on the host gnu.org and port 22, you should use one of the following filenames.

gnu.org.gpg
     No username or port in the filename means that any username and port will match.

gnu.org/rms.gpg
     The username to match can be expressed as filename inside a directory whose name matches the host.  This is useful if the store has passwords for several users on the same host.

rms@gnu.org.gpg
     The username can also be expressed as a prefix, separated from the host with an at-sign (@).

gnu.org:22.gpg
     The port (aka. service) to match can only be expressed after the host and separated with a colon (:).  The separator can be changed through the auth-source-pass-port-separator variable.

gnu.org:22/rms.gpg

rms@gnu.org:22.gpg

a/b/gnu.org.gpg
     Entries can be stored in arbitrary directories.

a/b/gnu.org/rms.gpg

a/b/rms@gnu.org.gpg

a/b/gnu.org:22.gpg

a/b/gnu.org:22/rms.gpg

a/b/rms@gnu.org:22.gpg

If several entries match, the one matching the most items (where an ``item'' is one of username, port or host) is preferred.  For example, while searching for an entry matching the rms user on host gnu.org and port 22, then the entry gnu.org:22/rms.gpg is preferred over gnu.org.gpg. However, such processing is not applied when the option auth-source-pass-extra-query-keywords is set to t.

Users of pass may also be interested in functionality provided by other Emacs packages:

  * password-store: library wrapping pass;

  * pass: major mode to manipulate the store and edit entries;

  * helm-pass: helm interface for pass.

 -- Variable: auth-source-pass-filename
     Set this variable to a string locating the password store on the disk. Defaults to ~/.password-store.

 -- Variable: auth-source-pass-port-separator
     Set this variable to a string that should separate an host name from a port in an entry.  Defaults to :.

 -- Variable: auth-source-pass-extra-query-keywords
     This expands the selection of available keywords to include :max and :require and tells more of them to accept a list of query parameters as an argument.  When searching, it also favors the rms@gnu.org.gpg form for usernames over the gnu.org/rms.gpg form, regardless of whether a :user param was provided.

     In general, if you prefer idiosyncrasies traditionally exhibited by this backend, such as prioritizing field count in a filename or matching against subdomain labels, keep this option set to nil (the default).  But, if you experience problems predicting the outcome of searches relative to other auth-source backends or encounter code expecting to query multiple backends uniformly, try flipping it to t.

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 docstring 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)
                   (auth-info-password found)
                   (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.

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.

 -- Function: auth-source-pick-first-password &rest spec
     This function returns the password of the first record found by applying auth-source-search to SPEC.

 -- Function: auth-info-password auth-info
     This function extracts the password string from the AUTH-INFO record.

GnuPG and EasyPG Assistant Configuration
****************************************

If the auth-sources variable contains ~/.authinfo.gpg before ~/.authinfo, the auth-source library will try to read the GnuPG encrypted .gpg file first, before the unencrypted file.

The EasyPG Assistant, which comes bundled with Emacs, handles decryption of encrypted files automatically, see EasyPG Assistant User's Manual.  It is an Emacs user interface to GnuPG (GNU Privacy Guard), see Using the GNU Privacy Guard.  To get started with these quickly, see Quick Start (EasyPG Assistant User's Manual).

GNU Free Documentation License
******************************

     [file doclicense.texi not included]