From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from localhost (localhost [127.0.0.1]) by arlo.cworth.org (Postfix) with ESMTP id C67416DE1203 for ; Tue, 24 Oct 2017 23:52:26 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at cworth.org X-Spam-Flag: NO X-Spam-Score: -0.037 X-Spam-Level: X-Spam-Status: No, score=-0.037 tagged_above=-999 required=5 tests=[AWL=-0.037] autolearn=disabled Received: from arlo.cworth.org ([127.0.0.1]) by localhost (arlo.cworth.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id x3LHRF2gzTg2 for ; Tue, 24 Oct 2017 23:52:26 -0700 (PDT) Received: from che.mayfirst.org (che.mayfirst.org [162.247.75.118]) by arlo.cworth.org (Postfix) with ESMTP id AC9976DE1034 for ; Tue, 24 Oct 2017 23:52:13 -0700 (PDT) Received: from fifthhorseman.net (unknown [38.109.115.130]) by che.mayfirst.org (Postfix) with ESMTPSA id B04E5F9AE for ; Wed, 25 Oct 2017 02:52:12 -0400 (EDT) Received: by fifthhorseman.net (Postfix, from userid 1000) id 183F021976; Wed, 25 Oct 2017 02:52:07 -0400 (EDT) From: Daniel Kahn Gillmor To: Notmuch Mail Subject: [PATCH 17/18] docs: clean up documentation about decryption policies Date: Wed, 25 Oct 2017 02:52:02 -0400 Message-Id: <20171025065203.24403-18-dkg@fifthhorseman.net> X-Mailer: git-send-email 2.14.2 In-Reply-To: <20171025065203.24403-1-dkg@fifthhorseman.net> References: <20171025065203.24403-1-dkg@fifthhorseman.net> X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 25 Oct 2017 06:52:26 -0000 Now that the range of sensible decryption policies has come into full view, we take a bit of space to document the distinctions. Most people will use either "auto" or "true" -- but we provide "false" and "nostash" to handle use cases that might reasonably be requested. Note also that these can be combined in sensible ways. Like, if your mail comes in regularly to a service that doesn't have access to your secret keys, but does have access to your index, and you feel comfortable adding selected encrypted messages to the index after you've read them, you could stay in "auto" normally, and then when you find yourself reading an indexable message (e.g. one you want to be able to search for in the future, and that you don't mind exposing to whatever entities have access to your inde), you can do: notmuch reindex --try-decrypt=true id:whatever@example.biz That leaves your default the same (still "auto") but you get the cleartext index and stashed session key benefits for that particular message. --- doc/man1/notmuch-config.rst | 44 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 38 insertions(+), 6 deletions(-) diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst index d9e22653..6b7d5db2 100644 --- a/doc/man1/notmuch-config.rst +++ b/doc/man1/notmuch-config.rst @@ -142,7 +142,9 @@ The available configuration items are described below. **[STORED IN DATABASE]** - One of ``false``, ``auto``, ``nostash``, or ``true``. + Policy for decrypting encrypted messages during indexing. + Must be one of: ``false``, ``auto``, ``nostash``, or + ``true``. When indexing an encrypted e-mail message, if this variable is set to ``true``, notmuch will try to decrypt the message and @@ -156,11 +158,40 @@ The available configuration items are described below. ``nostash`` is the same as ``true`` except that it will not stash newly-discovered session keys in the database. - Be aware that the notmuch index is likely sufficient to - reconstruct the cleartext of the message itself, so please - ensure that the notmuch message index is adequately protected. - DO NOT USE ``index.try_decrypt=true`` or ``index-only`` - without considering the security of your index. + From the command line (i.e. during **notmuch-new(1)**, + **notmuch-insert(1)**, or **notmuch-reindex**), the user can + override the database's stored decryption policy with the + ``--try-decrypt=`` option. + + Here is a table that summarizes the functionality of each of + these policies: + + +------------------------+-------+------+---------+------+ + | | false | auto | nostash | true | + +========================+=======+======+=========+======+ + | Index cleartext using | | X | X | X | + | stashed session keys | | | | | + +------------------------+-------+------+---------+------+ + | Index cleartext | | | X | X | + | using secret keys | | | | | + +------------------------+-------+------+---------+------+ + | Stash session keys | | | | X | + +------------------------+-------+------+---------+------+ + | Delete stashed session | X | | | | + | keys on reindex | | | | | + +------------------------+-------+------+---------+------+ + + Stashed session keys are kept in the database as properties + associated with the message. See ``session-key`` in + **notmuch-properties(7)** for more details about how they can + be useful. + + Be aware that the notmuch index itself (whether session keys + are stashed or not) is likely sufficient to reconstruct a + close approximation of the cleartext of the message itself, so + please ensure that the notmuch message index is adequately + protected. DO NOT SET ``index.try_decrypt`` to ``true`` or + ``index-only`` without considering the security of your index. Default: ``auto``. @@ -200,5 +231,6 @@ SEE ALSO **notmuch-restore(1)**, **notmuch-search(1)**, **notmuch-search-terms(7)**, +**notmuch-properties(7)**, **notmuch-show(1)**, **notmuch-tag(1)** -- 2.14.2