5 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-parameters is set to t.

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

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.