Merge pull request #464 from newsboat/feature/better-passwordeval-docs

Improve docs on passwords for remote APIs

2 files changed, 57 insertions, 37 deletions

diff --git a/doc/chapter-password.txt b/doc/chapter-password.txt
index c1a8d435..b8402046 100644
--- a/doc/chapter-password.txt
+++ b/doc/chapter-password.txt
@@ -1,31 +1,51 @@
-When using external APIs for newsfeeds, the user has different options for how
-to provide the password to authenticate against the API.
-Instead of directly writing the password into the configuration file,
-the user can choose to provide a file containing the password or an external
-command that evaluates to the user's password.
-This is useful if the user wants to share the configuration file online or
-store the password in a password manager or the systems keyring.
-
-For example when using the <<_the_old_reader,API for "The Old Reader">>,
-newsboat will first check the <<oldreader-password,`oldreader-password`>> configuration variable,
-if this variable is set (meaning it's present and not empty),
-then its value will be used for authentication.
-If <<oldreader-password,`oldreader-password`>> is not set (meaning it's not present or it's empty)
-but the <<oldreader-passwordfile,`oldreader-passwordfile`>> configuration variable is set,
-then the first line of this file will be used as the password.
-This is, unless the file doesn't exist, is unreadable or its first line is empty,
-in those cases Newsboat will exit with an error.
-If <<oldreader-passwordfile,`oldreader-passwordfile`>> is not set but <<oldreader-passwordeval,`oldreader-passwordeval`>> is set,
-then the command will be evaluated and the first line of the result will be
-used as the password.
-This is, unless the first line of the result's string is empty,
-in those cases Newsboat will exit with an error.
-Newsboat will ignore the exit status of the command,
-however it will wait for the command to exit.
-The command's output to stderr will be ignored by Newsboat and forwarded to
-the user, the output to stdout on the other hand will never be printed.
-If neither <<oldreader-password,`oldreader-password`>>, <<oldreader-passwordfile,`oldreader-passwordfile`>> nor
-<<oldreader-passwordeval,`oldreader-passwordeval`>> are set, then Newsboat will ask for the user's
-password with an interactive prompt.
-The entered password will be used unless it is empty,
-in which case Newsboat will exit with an error.
+There are a number of ways to specify a password, each represented by
+a separate setting. Newsboat looks for settings in certain order, and uses the
+first one that it finds. The exact order is described below.
+
+Settings are prefixed by API names; e.g. `newsblur-password`,
+`feedhq-passwordeval`. All APIs support all the settings, so examples below use
+`REMOTEAPI` for prefix. Replace it with the name of the remote API you use.
+
+The first setting Newsboat checks is `REMOTEAPI-password`. It should contain the
+password in plain text.
+
+The second setting Newsboat checks is `REMOTEAPI-passwordfile`. It should
+contain a path to a file; the first line of that file should contain the
+password in plain text. If the file doesn't exit, is unreadable, or its first
+line is empty, Newsboat will exit with an error.
+
+The third setting Newsboat checks is `REMOTEAPI-passwordeval`. It should
+contain a command that, when executed, will print out the password to stdout.
+stderr will be passed through to the terminal.
+
+If the first line of command's output is empty, or the command fails to
+execute, Newsboat will exit with an error. This is the most versatile of all
+the options, because it lets you emulate every other and more; let's look at it
+in more detail.
+
+For example, a user might want to store their password in a file encrypted by
+GPG. They create the file like that:
+
+    $ gpg --encrypt --default-recipient-self --output ~/.newsboat/password.gpg
+
+They enter their password, press Enter, and finish the command by pressing ^D
+(Control and d simultaneously). Then, they specify in their Newsboat config:
+
+    REMOTEAPI-passwordeval "gpg --decrypt ~/.newsboat/password.gpg"
+
+Now every time they start Newsboat, GPG will be ran. It'll probably ask for
+keyring password, then decrypt the file, and pass its contents to Newsboat,
+which will use it to authenticate with the remote API.
+
+Note that Newsboat will keep the password in memory the entire time Newsboat is
+running. Other programs might be able to dump the memory and obtain the
+password. We don't currently have any protection from that; patches are
+welcome.
+
+The user might use any other command here; for example, they could fetch the
+password from GNOME keyring, KeePass, or somewhere else entirely. The
+possibilities are truly endless.
+
+If no of the aforementioned settings were found, Newsboat will ask the user for
+the password using an interactive prompt. If the password that the user enters
+is empty, Newsboat will give up and exit with an error.
diff --git a/doc/configcommands.dsv b/doc/configcommands.dsv
index e3369fee..b2e07cae 100644
--- a/doc/configcommands.dsv
+++ b/doc/configcommands.dsv
@@ -31,7 +31,7 @@ feedhq-login||<login>||""||This variable sets your FeedHQ login for FeedHQ suppo
 feedhq-min-items||<number>||20||This variable sets the number of articles that are loaded from FeedHQ per feed.||feedhq-min-items 100
 feedhq-password||<password>||""||This variable sets your FeedHQ password for FeedHQ support. Double quotes should be escaped, i.e. you should write +{backslash}"+ instead of `"`.||feedhq-password "here_goesAquote:\""
 feedhq-passwordfile||<path>||""||A more secure alternative to the above, by storing your password elsewhere in your system.||feedhq-passwordfile "~/.newsboat/feedhq-pw.txt"
-feedhq-passwordeval||<command>||""||Another secure alternative, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring.||feedhq-passwordeval "command some-parameter"
+feedhq-passwordeval||<command>||""||Another secure alternative, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring.||feedhq-passwordeval "gpg --decrypt ~/.newsboat/feedhq-password.gpg"
 feedhq-show-special-feeds||[yes/no]||yes||If set and FeedHQ support is used, then "special feeds" like "People you follow" (articles shared by people you follow), "Starred items" (your starred articles) and "Shared items" (your shared articles) appear in your subscription list.||feedhq-show-special-feeds "no"
 feedhq-url||<url>||"https://feedhq.org/"||Configures the URL where your FeedHQ instance resides.||feedhq-url "https://feedhq.example.com/"
 feedlist-format||<format>||"%4i %n %11u %t"||This variable defines the format of entries in the feed list. See the respective section in the documentation for more information on format strings.||feedlist-format " %n %4i - %11u -%> %t"
@@ -55,7 +55,7 @@ inoreader-login||<login>||""||This variable sets your Inoreader login for Inorea
 inoreader-min-items||<number>||20||This variable sets the number of articles that are loaded from Inoreader per feed.||inoreader-min-items 100
 inoreader-password||<password>||""||This variable sets your Inoreader password for Inoreader support. Double quotes should be escaped, i.e. you should write +{backslash}"+ instead of `"`.||inoreader-password "here_goesAquote:\""
 inoreader-passwordfile||<path>||""||A more secure alternative to the above, by storing your password elsewhere in your system.||inoreader-passwordfile "~/.newsboat/inoreader-pw.txt"
-inoreader-passwordeval||<command>||""||Another secure alternative, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring.||inoreader-passwordeval "command some-parameter"
+inoreader-passwordeval||<command>||""||Another secure alternative, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring.||inoreader-passwordeval "gpg --decrypt ~/.newsboat/inoreader-password.gpg"
 inoreader-show-special-feeds||[yes/no]||yes||If set and Inoreader support is used, then "special feeds" like "Starred items" (your starred articles) and "Shared items" (your shared articles) appear in your subscription list.||inoreader-show-special-feeds "no"
 keep-articles-days||<number>||0||If set to a number greater than 0, only articles that are were published within the last <number> days are kept, and older articles are deleted. If set to 0, this option is not active. Note that changing this setting won't bring back the articles that were deleted earlier; currently, there's no non-hacky way to bring back deleted articles.||keep-articles-days 30
 macro||<macro key> <command list>||n/a||With this command, you can define a macro key and specify a list of commands that shall be executed when the macro prefix and the macro key are pressed.||macro k open ; reload ; quit
@@ -67,7 +67,7 @@ newsblur-login||<login>||""||This variable sets your NewsBlur login for NewsBlur
 newsblur-min-items||<number>||20||This variable sets the number of articles that are loaded from NewsBlur per feed.||newsblur-min-items 100
 newsblur-password||<password>||""||This variable sets your NewsBlur password for NewsBlur support. Double quotes should be escaped, i.e. you should write +{backslash}"+ instead of `"`.||newsblur-password "here_goesAquote:\""
 newsblur-passwordfile||<path>||""||A more secure alternative to the above, by storing your password elsewhere in your system.||newsblur-passwordfile "~/.newsboat/newsblur-pw.txt"
-newsblur-passwordeval||<command>||""||Another secure alternative, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring.||newsblur-passwordeval "command some-parameter"
+newsblur-passwordeval||<command>||""||Another secure alternative, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring.||newsblur-passwordeval "gpg --decrypt ~/.newsboat/newsblur-password.gpg"
 newsblur-url||<url>||"https://newsblur.com"||Configures the URL where the NewsBlur instance resides.||newsblur-url "https://localhost"
 notify-always||[yes/no]||no||If set to `no`, notifications will only be made when there are new feeds or articles. If set to `yes`, notifications will be made regardless.||notify-always yes
 notify-beep||[yes/no]||no||If set to `yes`, then the speaker beep on new articles.||notify-beep yes
@@ -79,7 +79,7 @@ ocnews-flag-star||<character>||""||If set and ownCloud News support is used, the
 ocnews-login||<username>||""||Sets the username to use with the ownCloud instance.||ocnews-login "user"
 ocnews-password||<password>||""||Configures the password to use with the ownCloud instance. Double quotes should be escaped, i.e. you should write +{backslash}"+ instead of `"`.||ocnews-password "here_goesAquote:\""
 ocnews-passwordfile||<path>||""||A more secure alternative to the above, by storing your password elsewhere in your system.||ocnews-passwordfile "~/.newsboat/ocnews-pw.txt"
-ocnews-passwordeval||<command>||""||Another secure alternative, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring.||ocnews-passwordeval "command some-parameter"
+ocnews-passwordeval||<command>||""||Another secure alternative, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring.||ocnews-passwordeval "gpg --decrypt ~/.newsboat/ocnews-password.gpg"
 ocnews-url||<url>||""||Configures the URL where the ownCloud instance resides.||ocnews-url "https://localhost/owncloud"
 oldreader-flag-share||<flag>||""||If set and The Old Reader support is used, then all articles that are flagged with the specified flag are being "shared" in The Old Reader so that people that follow you can see it.||oldreader-flag-share "a"
 oldreader-flag-star||<flag>||""||If set and The Old Reader support is used, then all articles that are flagged with the specified flag are being "starred" in The Old Reader and appear in the list of "Starred items".||oldreader-flag-star "b"
@@ -87,7 +87,7 @@ oldreader-login||<login>||""||This variable sets your The Old Reader login for T
 oldreader-min-items||<number>||20||This variable sets the number of articles that are loaded from The Old Reader per feed.||oldreader-min-items 100
 oldreader-password||<password>||""||This variable sets your The Old Reader password for The Old Reader support. Double quotes should be escaped, i.e. you should write +{backslash}"+ instead of `"`.||oldreader-password "here_goesAquote:\""
 oldreader-passwordfile||<path>||""||A more secure alternative to the above, by storing your password elsewhere in your system.||oldreader-passwordfile "~/.newsboat/oldreader-pw.txt"
-oldreader-passwordeval||<command>||""||Another secure alternative, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring.||oldreader-passwordeval "command some-parameter"
+oldreader-passwordeval||<command>||""||Another secure alternative, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring.||oldreader-passwordeval "gpg --decrypt ~/.newsboat/oldreader-password.gpg"
 oldreader-show-special-feeds||[yes/no]||yes||If set and The Old reader support is used, then "special feeds" like "People you follow" (articles shared by people you follow), "Starred items" (your starred articles) and "Shared items" (your shared articles) appear in your subscription list.||oldreader-show-special-feeds "no"
 openbrowser-and-mark-jumps-to-next-unread||[yes/no]||no||If set to `yes`, jump to the next unread item when an item is opened in the browser and marked as read.||openbrowser-and-mark-jumps-to-next-unread yes
 opml-url||<url> ...||""||If the OPML online subscription mode is enabled, then the list of feeds will be taken from the OPML file found on this location. Optionally, you can specify more than one URL. All the listed OPML URLs will then be taken into account when loading the feed list.||opml-url "http://host.domain.tld/blogroll.opml" "http://example.com/anotheropmlfile.opml"
@@ -123,7 +123,7 @@ ttrss-login||<username>||""||Sets the username for use with Tiny Tiny RSS.||ttrs
 ttrss-mode||[multi/single]||multi||Configures the mode in which Tiny Tiny RSS is used. In single-user mode, login and password are used for HTTP authentication, while in multi-user mode, they are used for authenticating with Tiny Tiny RSS.||ttrss-mode "single"
 ttrss-password||<password>||""||Configures the password for use with Tiny Tiny RSS. Double quotes should be escaped, i.e. you should write +{backslash}"+ instead of `"`.||ttrss-password "here_goesAquote:\""
 ttrss-passwordfile||<path>||""||A more secure alternative to the above, by storing your password elsewhere in your system.||ttrss-passwordfile "~/.newsboat/ttrss-pw.txt"
-ttrss-passwordeval||<command>||""||Another secure alternative, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring.||ttrss-passwordeval "command some-parameter"
+ttrss-passwordeval||<command>||""||Another secure alternative, is providing your password from an external command that is evaluated during login. This can be used to read your password from a gpg encrypted file or your system keyring.||ttrss-passwordeval "gpg --decrypt ~/.newsboat/ttrss-password.gpg"
 ttrss-url||<url>||""||Configures the URL where the Tiny Tiny RSS installation you want to use resides.||ttrss-url "http://example.com/ttrss/"
 unbind-key||<key> [<dialog>]||n/a||Unbind key <key>. This means that no operation is called when <key> is pressed. If you provide "-a" as <key>, all currently bound keys will become unbound. Optionally, you can specify a dialog (for a list of available dialogs, see `bind-key` above). If you specify one, the key binding will only be unbound for the specified dialog.||unbind-key R
 urls-source||<source>||"local"||This configuration command sets the source where URLs shall be retrieved from. By default, this is ~/.newsboat/urls. Alternatively, you can set it to `opml`, which enables newsboat's OPML online subscription mode, to `ttrss` which enables newsboat's Tiny Tiny RSS support, to `oldreader`, which enables newsboat's The Old Reader support, to `newsblur`, which enables NewsBlur support, or `feedhq` for FeedHQ support, or `ocnews` for ownCloud News support, or `inoreader` for Inoreader support. Query feed specifications will be read from the local urls file regardless of this setting.||urls-source "oldreader"