From aa605f7e8a4c5e046503d61fdb953721c32f9d3a Mon Sep 17 00:00:00 2001 From: Daniel Kahn Gillmor Date: Fri, 11 May 2018 02:57:59 -0400 Subject: cli/show: enable --decrypt=stash Add fancy new feature, which makes "notmuch show" capable of actually indexing messages that it just decrypted. This enables a workflow where messages can come in in the background and be indexed using "--decrypt=auto". But when showing an encrypted message for the first time, it gets automatically indexed. This is something of a departure for "notmuch show" -- in particular, because it requires read/write access to the database. However, this might be a common use case -- people get mail delivered and indexed in the background, but only want access to their secret key to happen when they're directly interacting with notmuch itself. In such a scenario, they couldn't search newly-delivered, encrypted messages, but they could search for them once they've read them. Documentation of this new feature also uses a table form, similar to that found in the description of index.decrypt in notmuch-config(1). A notmuch UI that wants to facilitate this workflow while also offering an interactive search interface might instead make use of these additional commands while the user is at the console: Count received encrypted messages (if > 0, there are some things we haven't yet tried to index, and therefore can't yet search): notmuch count tag:encrypted and \ not property:index.decryption=success and \ not property:index.decryption=failure Reindex those messages: notmuch reindex --try-decrypt=true tag:encrypted and \ not property:index.decryption=success and \ not property:index.decryption=failure --- doc/man1/notmuch-show.rst | 40 ++++++++++++++++++++++++++++++++++------ 1 file changed, 34 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst index 2b825ccc..b2667537 100644 --- a/doc/man1/notmuch-show.rst +++ b/doc/man1/notmuch-show.rst @@ -110,7 +110,7 @@ Supported options for **show** include supported with --format=json and --format=sexp), and the multipart/signed part will be replaced by the signed data. -``--decrypt=(false|auto|true)`` +``--decrypt=(false|auto|true|stash)`` If ``true``, decrypt any MIME encrypted parts found in the selected content (i.e. "multipart/encrypted" parts). Status of the decryption will be reported (currently only supported @@ -118,17 +118,45 @@ Supported options for **show** include decryption the multipart/encrypted part will be replaced by the decrypted content. + ``stash`` behaves like ``true``, but upon successful decryption it + will also stash the message's session key in the database, and + index the cleartext of the message, enabling automatic decryption + in the future. + If ``auto``, and a session key is already known for the message, then it will be decrypted, but notmuch will not try to access the user's keys. Use ``false`` to avoid even automatic decryption. - Non-automatic decryption expects a functioning - **gpg-agent(1)** to provide any needed credentials. Without - one, the decryption will fail. - - Note: ``true`` implies --verify. + Non-automatic decryption (``stash`` or ``true``, in the absence of + a stashed session key) expects a functioning **gpg-agent(1)** to + provide any needed credentials. Without one, the decryption will + fail. + + Note: setting either ``true`` or ``stash`` here implies + ``--verify``. + + Here is a table that summarizes each of these policies: + + +------------------------+-------+------+------+-------+ + | | false | auto | true | stash | + +========================+=======+======+======+=======+ + | Show cleartext if | | X | X | X | + | session key is | | | | | + | already known | | | | | + +------------------------+-------+------+------+-------+ + | Use secret keys to | | | X | X | + | show cleartext | | | | | + +------------------------+-------+------+------+-------+ + | Stash any newly | | | | X | + | recovered session keys,| | | | | + | reindexing message if | | | | | + | found | | | | | + +------------------------+-------+------+------+-------+ + + Note: ``--decrypt=stash`` requires write access to the database. + Otherwise, ``notmuch show`` operates entirely in read-only mode. Default: ``auto`` -- cgit v1.2.3