Merge 'master' into noverlay

1 files changed, 170 insertions, 55 deletions

diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi
index cfc62a9f922..9dc63af6bcc 100644
--- a/doc/misc/auth.texi
+++ b/doc/misc/auth.texi
@@ -1,7 +1,5 @@
 \input texinfo                  @c -*-texinfo-*-
 
-@include gnus-overrides.texi
-
 @set VERSION 0.3
 
 @setfilename ../../info/auth.info
@@ -11,7 +9,7 @@
 @copying
 This file describes the Emacs auth-source library.
 
-Copyright @copyright{} 2008--2017 Free Software Foundation, Inc.
+Copyright @copyright{} 2008--2022 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -86,7 +84,7 @@ password (known as the secret).
 
 Similarly, the auth-source library supports multiple storage backend,
 currently either the classic ``netrc'' backend, examples of which you
-can see later in this document, the Secret Service API, and pass, the
+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.
 
@@ -94,13 +92,13 @@ backends and you can write your own if you want.
 @chapter Help for users
 
 ``Netrc'' files are a de facto standard.  They look like this:
+
 @example
 machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport}
 @end example
 
 The @code{machine} is the server (either a DNS name or an IP address).
-It's known as @var{:host} in @code{auth-source-search} queries.  You
-can also use @code{host}.
+It's known as @var{:host} in @code{auth-source-search} queries.
 
 The @code{port} is the connection port or protocol.  It's known as
 @var{:port} in @code{auth-source-search} queries.
@@ -109,6 +107,31 @@ The @code{user} is the user name.  It's known as @var{:user} in
 @code{auth-source-search} queries.  You can also use @code{login} and
 @code{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:
+
+@example
+machine example.com login foobar password geheimnis port smtp
+machine example.com login foobar password hemmelig
+@end example
+
+Here we're using one password for the @code{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:
+
+@example
+machine @var{mymachine} port @var{myport} key @var{key} cert @var{cert}
+@end example
+
+@var{key} and @var{cert} are filenames containing the key and
+certificate to use respectively.  In order to make network connections
+use them automatically, either pass @code{:client-certificate t} to
+@code{open-network-stream}, or customize
+@code{network-stream-use-client-certificates} to @code{t}.
+
 You can use spaces inside a password or other token by surrounding the
 token with either single or double quotes.
 
@@ -168,7 +191,10 @@ get fancy, the default and simplest configuration is:
 (setq auth-sources '("secrets:Login"))
 ;;; use pass (@file{~/.password-store})
 ;;; (@pxref{The Unix password store})
-(setq auth-sources '(password-store))
+(auth-source-pass-enable)
+;;; JSON data in format [@{ "machine": "SERVER",
+;;; "login": "USER", "password": "PASSWORD" @}...]
+(setq auth-sources '("~/.authinfo.json.gpg"))
 @end lisp
 
 By adding multiple entries to @code{auth-sources} with a particular
@@ -213,6 +239,11 @@ machine YOURMACHINE login YOU password SMTPPASSWORD port 433
 machine YOURMACHINE login YOU password GENERALPASSWORD
 @end example
 
+If you wish to specify a particular SMTP authentication method to use
+with a machine, you can use the @code{smtp-auth} keyword.
+@xref{Authentication,, Authentication, smtpmail, Emacs SMTP Library},
+for available methods.
+
 For url-auth authentication (HTTP/HTTPS), you need to put this in your
 netrc file:
 
@@ -235,6 +266,16 @@ 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:
+
+@example
+[
+ @{ "machine": "yourmachine.com", "port": "http",
+    "login": "testuser", "password": "testpass" @}
+]
+@end example
+
 @node Multiple GMail accounts with Gnus
 @chapter Multiple GMail accounts with Gnus
 
@@ -260,11 +301,12 @@ machine gmail2 login account2@@gmail.com password "account2 password" port imap
 @chapter Secret Service API
 
 The @dfn{Secret Service API} is a standard from
-@uref{http://www.freedesktop.org/wiki/Specifications/secret-storage-spec,,freedesktop.org}
+@uref{https://www.freedesktop.org/wiki/Specifications/secret-storage-spec/,,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).
+be available on most modern GNU/Linux systems).  It has been tested
+also with KeePassXC.
 
 The auth-source library uses the @file{secrets.el} library to connect
 through the Secret Service API@.  You can also use that library in
@@ -319,15 +361,19 @@ Collections can be created and deleted by the functions
 Usually, this is not done from within Emacs.  Do not delete standard
 collections such as @code{"login"}.
 
-The special collection @code{"session"} exists for the lifetime of the
-corresponding client session (in our case, Emacs's lifetime).  It is
-created automatically when Emacs uses the Secret Service interface and
-it is deleted when Emacs is killed.  Therefore, it can be used to
-store and retrieve secret items temporarily.  The @code{"session"}
-collection is better than a persistent collection when the secret
-items should not live longer than Emacs.  The session collection can
-be specified either by the string @code{"session"}, or by @code{nil},
-whenever a collection parameter is needed in the following functions.
+With GNOME Keyring, there exists a special collection called
+@code{"session"}, which has the lifetime of the user being logged in.
+Its data are not stored on disk and go away when the user logs out.
+Therefore, it can be used to store and retrieve secret items
+temporarily.  The @code{"session"} collection is better than a
+persistent collection when the secret items should not live
+permanently.  The @code{"session"} collection can be addressed either
+by the string @code{"session"}, or by @code{nil}, whenever a
+collection parameter is needed.
+
+However, other Secret Service provider don't create this temporary
+@code{"session"} collection.  You shall check first that this
+collection exists, before you use it.
 
 @defun secrets-list-items collection
 Returns all the item labels of @var{collection} as a list.
@@ -335,25 +381,36 @@ Returns all the item labels of @var{collection} as a list.
 
 @defun secrets-create-item collection item password &rest attributes
 This function creates a new item in @var{collection} with label
-@var{item} and password @var{password}.  @var{attributes} are
-key-value pairs set for the created item.  The keys are keyword
-symbols, starting with a colon.  Example:
+@var{item} and password @var{password}.  The label @var{item} does not
+have to be unique in @var{collection}.  @var{attributes} are key-value
+pairs set for the created item.  The keys are keyword symbols,
+starting with a colon; values are strings.  Example:
 
 @example
-;;; The session "session", the label is "my item"
-;;; and the secret (password) is "geheim"
+;;; 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")
 @end example
+
+The key @code{: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 @code{:xdg:schema} is given,
+"org.freedesktop.Secret.Generic" is used by default.
 @end defun
 
 @defun secrets-get-secret collection item
-Return the secret of item labeled @var{item} in @var{collection}.
-If there is no such item, return @code{nil}.
+Return the secret of item labeled @var{item} in @var{collection}.  If
+there are several items labeled @var{item}, it is undefined which one
+is returned.  If there is no such item, return @code{nil}.
 @end defun
 
 @defun secrets-delete-item collection item
-This function deletes item @var{item} in @var{collection}.
+This function deletes item @var{item} in @var{collection}.  If there
+are several items labeled @var{item}, it is undefined which one is
+deleted.
 @end defun
 
 The lookup attributes, which are specified during creation of a
@@ -363,18 +420,20 @@ from a given secret item and they can be used for searching of items.
 
 @defun secrets-get-attribute collection item attribute
 Returns the value of key @var{attribute} of item labeled @var{item} in
-@var{collection}.  If there is no such item, or the item doesn't own
-this key, the function returns @code{nil}.
+@var{collection}.  If there are several items labeled @var{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 @code{nil}.
 @end defun
 
 @defun secrets-get-attributes collection item
 Return the lookup attributes of item labeled @var{item} in
-@var{collection}.  If there is no such item, or the item has no
-attributes, it returns @code{nil}.  Example:
+@var{collection}.  If there are several items labeled @var{item}, it
+is undefined which one is returned.  If there is no such item, or the
+item has no attributes, it returns @code{nil}.  Example:
 
 @example
 (secrets-get-attributes "session" "my item")
-     @result{} ((:user . "joe") (:host ."remote-host"))
+     @result{} ((:user . "joe") (:host . "remote-host"))
 @end example
 @end defun
 
@@ -407,24 +466,69 @@ then fall back to @file{~/.authinfo.gpg}.
                      "~/.authinfo.gpg"))
 @end example
 
+Attribute values in the auth-source spec, which are not strings (like
+port numbers), are stringified prior calling the @file{secrets.el}
+functions.
+
 @node The Unix password store
 @chapter The Unix password store
 
-@uref{http://www.passwordstore.org,,The standard unix password
+@uref{https://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
+@file{~/.password-store}.
+
+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} and port @code{22}, you should use one of the following
+filenames.
+
+@table @file
+@item gnu.org.gpg
+No username or port in the filename means that any username and port
+will match.
 
-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.
+@item 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 rms@@gnu.org.gpg
+The username can also be expressed as a prefix, separated from the
+host with an at-sign (@code{@@}).
+
+@item 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 gnu.org:22/rms.gpg
+
+@item rms@@gnu.org:22.gpg
+
+@item a/b/gnu.org.gpg
+Entries can be stored in arbitrary directories.
+
+@item a/b/gnu.org/rms.gpg
+
+@item a/b/rms@@gnu.org.gpg
+
+@item a/b/gnu.org:22.gpg
+
+@item a/b/gnu.org:22/rms.gpg
+
+@item a/b/rms@@gnu.org:22.gpg
+@end table
+
+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} and port @code{22}, then the entry
+@file{gnu.org:22/rms.gpg} is preferred over @file{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
@@ -435,6 +539,16 @@ by other Emacs packages dealing with pass:
 @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 @file{~/.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 @samp{:}.
+@end defvar
+
 @node Help for developers
 @chapter Help for developers
 
@@ -469,10 +583,7 @@ from Gnus's @code{nnimap.el}.
                                            :create t))))
     (if found
         (list (plist-get found :user)
-              (let ((secret (plist-get found :secret)))
-                (if (functionp secret)
-                    (funcall secret)
-                  secret))
+              (auth-info-password found)
               (plist-get found :save-function))
       nil)))
 @end example
@@ -492,7 +603,7 @@ Later, after a successful login, @code{nnimap.el} calls the
 
 @example
 (when (functionp (nth 2 credentials))
-   (funcall (nth 2 credentials)))
+  (funcall (nth 2 credentials)))
 @end example
 
 This will work whether the @code{:save-function} was provided or not.
@@ -527,6 +638,16 @@ This function forgets any cached data matching @var{spec}.
 It returns the number of items forgotten.
 @end defun
 
+@defun auth-source-pick-first-password &rest spec
+This function returns the password of the first record found by
+applying @code{auth-source-search} to @var{spec}.
+@end defun
+
+@defun auth-info-password auth-info
+This function extracts the password string from the @var{auth-info}
+record.
+@end defun
+
 @node GnuPG and EasyPG Assistant Configuration
 @appendix GnuPG and EasyPG Assistant Configuration
 
@@ -535,14 +656,8 @@ before @file{~/.authinfo}, the auth-source library will try to
 read the GnuPG encrypted @file{.gpg} file first, before
 the unencrypted file.
 
-In Emacs 23 or later there is an option @code{auto-encryption-mode} to
-automatically decrypt @file{*.gpg} files.  It is enabled by default.
-If you are using earlier versions of Emacs, you will need:
-
-@lisp
-(require 'epa-file)
-(epa-file-enable)
-@end lisp
+There is an option @code{auto-encryption-mode} to automatically
+decrypt @file{*.gpg} files.  It is enabled by default.
 
 If you want your GnuPG passwords to be cached, set up @code{gpg-agent}
 or EasyPG Assistant