>From 1b51160e1e7d9cee8d89b652c9495c6af8bcc215 Mon Sep 17 00:00:00 2001 From: Damien Cassou Date: Thu, 13 Jun 2019 21:54:21 +0200 Subject: [PATCH 13/13] * doc/misc/auth.texi (The Unix password store): Complete rewrite --- doc/misc/auth.texi | 50 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 40 insertions(+), 10 deletions(-) diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi index a46e3d73fc..5b4914e8f5 100644 --- a/doc/misc/auth.texi +++ b/doc/misc/auth.texi @@ -445,19 +445,39 @@ The Unix password store @uref{http://www.passwordstore.org,,The standard unix password manager} (or just @code{pass}) stores your passwords in -@code{gpg}-protected files following the Unix philosophy. +@code{gpg}-protected files following the Unix philosophy. The store +location (any directory) must be specified in the +@code{auth-source-pass-filename} variable which defaults to +@code{"~/.password-store"}. -Emacs integration of @code{pass} follows the first approach suggested -by the pass project itself for data organization to find data. This -means that the filename of the file containing the password for a user -on a particular host must contain the host name. The file itself must -contain the password on the first line, as well as a @code{username} -field containing the username on a subsequent line. A @code{port} -field can be used to differentiate the authentication data for several -services with the same username on the same host. +Emacs integration of @code{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 @code{rms} on the host @code{gnu.org} +on port @code{22}, you should use one of the following filenames. + +@itemize +@item @code{"gnu.org.gpg"} : No username or port in the filename means that any username and port will match. +@item @code{"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. +@item @code{"rms@@gnu.org.gpg"} : The username can also be expressed as a prefix, separated from the host with an at-sign (@code{@@}). +@item @code{"gnu.org:22.gpg"} : The port (aka. service) to match can only be expressed after the host and separated with a colon (@code{:}). The separator can be changed through the @code{auth-source-pass-port-separator} variable. +@item @code{"gnu.org:22/rms.gpg"} +@item @code{"rms@@gnu.org:22.gpg"} +@item @code{"a/b/gnu.org.gpg"} : Entries can be stored in arbitrary directories. +@item @code{"a/b/gnu.org/rms.gpg"} +@item @code{"a/b/rms@@gnu.org.gpg"} +@item @code{"a/b/gnu.org:22.gpg"} +@item @code{"a/b/gnu.org:22/rms.gpg"} +@item @code{"a/b/rms@@gnu.org:22.gpg"} +@end itemize + +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 @code{rms} user on host +@code{gnu.org} for port @code{22}, then the entry +@code{"gnu.org:22/rms.gpg"} is preferred over @code{"gnu.org.gpg"}. Users of @code{pass} may also be interested in functionality provided -by other Emacs packages dealing with pass: +by other Emacs packages: @itemize @item @@ -468,6 +488,16 @@ The Unix password store @uref{https://github.com/jabranham/helm-pass,,helm-pass}: helm interface for pass. @end itemize +@defvar auth-source-pass-filename +Set this variable to a string locating the password store on the disk. +Defaults to @code{"~/.password-store"}. +@end defvar + +@defvar 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 @code{":"}. +@end defvar + @node Help for developers @chapter Help for developers -- 2.21.0