debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-11-21 18:38:08 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
notmuch/doc/man7/notmuch-properties.rst

149 lines
5.6 KiB
ReStructuredText
Raw Permalink Normal View History

doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
.. _notmuch-properties(7):
doc: add notmuch-properties(7) We will want a user-facing place to record details about the use of notmuch properties shortly. This establishes a new manual page for that purpose.
2017-10-21 04:25:39 +02:00
==================
notmuch-properties
==================
SYNOPSIS
========
**notmuch** **count** **property:**\ <*key*>=<*value*>
**notmuch** **search** **property:**\ <*key*>=<*value*>
**notmuch** **show** **property:**\ <*key*>=<*value*>
**notmuch** **reindex** **property:**\ <*key*>=<*value*>
**notmuch** **tag** +<*tag*> **property:**\ <*key*>=<*value*>
**notmuch** **dump** **--include=properties**
**notmuch** **restore** **--include=properties**
DESCRIPTION
===========
Several notmuch commands can search for, modify, add or remove
properties associated with specific messages. Properties are
key/value pairs, and a message can have more than one key/value pair
for the same key.
While users can select based on a specific property in their search
terms with the prefix **property:**, the notmuch command-line
interface does not provide mechanisms for modifying properties
directly to the user.
Instead, message properties are expected to be set and used
programmatically, according to logic in notmuch itself, or in
extensions to it.
Extensions to notmuch which make use of properties are encouraged to
report the specific properties used to the upstream notmuch project,
as a way of avoiding collisions in the property namespace.
reindex: drop all properties named with prefix "index." This allows us to create new properties that will be automatically set during indexing, and cleared during re-indexing, just by choice of property name.
2017-10-21 04:25:40 +02:00
CONVENTIONS
===========
Any property with a key that starts with "index." will be removed (and
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
possibly re-set) upon reindexing (see :any:`notmuch-reindex(1)`).
reindex: drop all properties named with prefix "index." This allows us to create new properties that will be automatically set during indexing, and cleared during re-indexing, just by choice of property name.
2017-10-21 04:25:40 +02:00
crypto: index encrypted parts when indexopts try_decrypt is set. If we see index options that ask us to decrypt when indexing a message, and we encounter an encrypted part, we'll try to descend into it. If we can decrypt, we add the property index.decryption=success. If we can't decrypt (or recognize the encrypted type of mail), we add the property index.decryption=failure. Note that a single message may have both values of the "index.decryption" property: "success" and "failure". For example, consider a message that includes multiple layers of encryption. If we manage to decrypt the outer layer ("index.decryption=success"), but fail on the inner layer ("index.decryption=failure"). Because of the property name, this will be automatically cleared (and possibly re-set) during re-indexing. This means it will subsequently correspond to the actual semantics of the stored index.
2017-10-21 04:25:41 +02:00
MESSAGE PROPERTIES
==================
The following properties are set by notmuch internally in the course
of its normal activity.
doc: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
index.decryption
crypto: index encrypted parts when indexopts try_decrypt is set. If we see index options that ask us to decrypt when indexing a message, and we encounter an encrypted part, we'll try to descend into it. If we can decrypt, we add the property index.decryption=success. If we can't decrypt (or recognize the encrypted type of mail), we add the property index.decryption=failure. Note that a single message may have both values of the "index.decryption" property: "success" and "failure". For example, consider a message that includes multiple layers of encryption. If we manage to decrypt the outer layer ("index.decryption=success"), but fail on the inner layer ("index.decryption=failure"). Because of the property name, this will be automatically cleared (and possibly re-set) during re-indexing. This means it will subsequently correspond to the actual semantics of the stored index.
2017-10-21 04:25:41 +02:00
If a message contains encrypted content, and notmuch tries to
decrypt that content during indexing, it will add the property
``index.decryption=success`` when the cleartext was successfully
indexed. If notmuch attempts to decrypt any part of a message
during indexing and that decryption attempt fails, it will add the
property ``index.decryption=failure`` to the message.
Note that it's possible for a single message to have both
``index.decryption=success`` and ``index.decryption=failure``.
Consider an encrypted e-mail message that contains another
encrypted e-mail message as an attachment -- if the outer message
can be decrypted, but the attached part cannot, then both
properties will be set on the message as a whole.
If notmuch never tried to decrypt an encrypted message during
indexing: Change from try_decrypt to decrypt the command-line interface for indexing (reindex, new, insert) used --try-decrypt; and the configuration records used index.try_decrypt. But by comparison with "show" and "reply", there doesn't seem to be any reason for the "try" prefix. This changeset adjusts the command-line interface and the configuration interface. For the moment, i've left indexopts_{set,get}_try_decrypt alone. The subsequent changeset will address those.
2017-12-08 07:23:50 +01:00
indexing (which is the default, see ``index.decrypt`` in
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
:any:`notmuch-config(1)`), then this property will not be set on that
config: define new option index.try_decrypt By default, notmuch won't try to decrypt on indexing. With this patch, we make it possible to indicate a per-database preference using the config variable "index.try_decrypt", which by default will be false. At indexing time, the database needs some way to know its internal defaults for how to index encrypted parts. It shouldn't be contingent on an external config file (since that can't be retrieved from the database object itself), so we store it in the database. This behaves similarly to the query.* configurations, which are also stored in the database itself, so we're not introducing any new dependencies by requiring that it be stored in the database.
2017-10-21 04:25:43 +02:00
message.
crypto: index encrypted parts when indexopts try_decrypt is set. If we see index options that ask us to decrypt when indexing a message, and we encounter an encrypted part, we'll try to descend into it. If we can decrypt, we add the property index.decryption=success. If we can't decrypt (or recognize the encrypted type of mail), we add the property index.decryption=failure. Note that a single message may have both values of the "index.decryption" property: "success" and "failure". For example, consider a message that includes multiple layers of encryption. If we manage to decrypt the outer layer ("index.decryption=success"), but fail on the inner layer ("index.decryption=failure"). Because of the property name, this will be automatically cleared (and possibly re-set) during re-indexing. This means it will subsequently correspond to the actual semantics of the stored index.
2017-10-21 04:25:41 +02:00
doc: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
session-key
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
When :any:`notmuch-show(1)` or :any:`notmuch-reply(1)` encounters
a message with an encrypted part, if notmuch finds a
``session-key`` property associated with the message, it will try
that stashed session key for decryption.
cli/show, reply: document use of stashed session keys in notmuch-properties The stashed session keys are stored internally as notmuch properties. So a user or developer who is reading about those properties might want to understand how they fit into the bigger picture. Note here that decrypting with a stored session key no longer needs -decrypt for "notmuch show" and "notmuch reply".
2017-12-08 07:23:56 +01:00
If you do not want to use any stashed session keys that might be
present, you should pass those programs ``--decrypt=false``.
crypto: use stashed session-key properties for decryption, if available When doing any decryption, if the notmuch database knows of any session keys associated with the message in question, try them before defaulting to using default symmetric crypto. This changeset does the primary work in _notmuch_crypto_decrypt, which grows some new parameters to handle it. The primary advantage this patch offers is a significant speedup when rendering large encrypted threads ("notmuch show") if session keys happen to be cached. Additionally, it permits message composition without access to asymmetric secret keys ("notmuch reply"); and it permits recovering a cleartext index when reindexing after a "notmuch restore" for those messages that already have a session key stored. Note that we may try multiple decryptions here (e.g. if there are multiple session keys in the database), but we will ignore and throw away all the GMime errors except for those that come from last decryption attempt. Since we don't necessarily know at the time of the decryption that this *is* the last decryption attempt, we'll ask for the errors each time anyway. This does nothing if no session keys are stashed in the database, which is fine. Actually stashing session keys in the database will come as a subsequent patch.
2017-11-30 09:59:29 +01:00
Using a stashed session key with "notmuch show" will speed up
rendering of long encrypted threads. It also allows the user to
destroy the secret part of any expired encryption-capable subkey
while still being able to read any retained messages for which
they have stashed the session key. This enables truly deletable
e-mail, since (once the session key and asymmetric subkey are both
destroyed) there are no keys left that can be used to decrypt any
copy of the original message previously stored by an adversary.
However, access to the stashed session key for an encrypted message
permits full byte-for-byte reconstruction of the cleartext
message. This includes attachments, cryptographic signatures, and
other material that cannot be reconstructed from the index alone.
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
See ``index.decrypt`` in :any:`notmuch-config(1)` for more
crypto: actually stash session keys when decrypt=true If you're going to store the cleartext index of an encrypted message, in most situations you might just as well store the session key. Doing this storage has efficiency and recoverability advantages. Combined with a schedule of regular OpenPGP subkey rotation and destruction, this can also offer security benefits, like "deletable e-mail", which is the store-and-forward analog to "forward secrecy". But wait, i hear you saying, i have a special need to store cleartext indexes but it's really bad for me to store session keys! Maybe (let's imagine) i get lots of e-mails with incriminating photos attached, and i want to be able to search for them by the text in the e-mail, but i don't want someone with access to the index to be actually able to see the photos themselves. Fret not, the next patch in this series will support your wacky uncommon use case.
2017-12-08 07:24:01 +01:00
details about how to set notmuch's policy on when to store session
keys.
crypto: use stashed session-key properties for decryption, if available When doing any decryption, if the notmuch database knows of any session keys associated with the message in question, try them before defaulting to using default symmetric crypto. This changeset does the primary work in _notmuch_crypto_decrypt, which grows some new parameters to handle it. The primary advantage this patch offers is a significant speedup when rendering large encrypted threads ("notmuch show") if session keys happen to be cached. Additionally, it permits message composition without access to asymmetric secret keys ("notmuch reply"); and it permits recovering a cleartext index when reindexing after a "notmuch restore" for those messages that already have a session key stored. Note that we may try multiple decryptions here (e.g. if there are multiple session keys in the database), but we will ignore and throw away all the GMime errors except for those that come from last decryption attempt. Since we don't necessarily know at the time of the decryption that this *is* the last decryption attempt, we'll ask for the errors each time anyway. This does nothing if no session keys are stashed in the database, which is fine. Actually stashing session keys in the database will come as a subsequent patch.
2017-11-30 09:59:29 +01:00
The session key should be in the ASCII text form produced by
GnuPG. For OpenPGP, that consists of a decimal representation of
the hash algorithm used (identified by number from RFC 4880,
e.g. 9 means AES-256) followed by a colon, followed by a
hexadecimal representation of the algorithm-specific key. For
example, an AES-128 key might be stashed in a notmuch property as:
``session-key=7:14B16AF65536C28AF209828DFE34C9E0``.
doc: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
index.repaired
repair: set up codebase for repair functionality This adds no functionality directly, but is a useful starting point for adding new repair functionality. Signed-off-by: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
2019-08-29 17:38:47 +02:00
Some messages arrive in forms that are confusing to view; they can
be mangled by mail transport agents, or the sending mail user
agent may structure them in a way that is confusing. If notmuch
knows how to both detect and repair such a problematic message, it
will do so during indexing.
If it applies a message repair during indexing, it will use the
``index.repaired`` property to note the type of repair(s) it
performed.
index: avoid indexing legacy-display parts When we notice a legacy-display part during indexing, it makes more sense to avoid indexing it as part of the message body. Given that the protected subject will already be indexed, there is no need to index this part at all, so we skip over it. If this happens during indexing, we set a property on the message: index.repaired=skip-protected-headers-legacy-display Signed-off-by: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
2019-08-29 17:38:53 +02:00
``index.repaired=skip-protected-headers-legacy-display`` indicates
that when indexing the cleartext of an encrypted message, notmuch
skipped over a "legacy-display" text/rfc822-headers part that it
found in that message, since it was able to index the built-in
protected headers directly.
index: repair "Mixed Up" messages before indexing. When encountering a message that has been mangled in the "mixed up" way by an intermediate MTA, notmuch should instead repair it and index the repaired form. When it does this, it also associates the index.repaired=mixedup property with the message. If a problem is found with this repair process, or an improved repair process is proposed later, this should make it easy for people to reindex the relevant message. The property will also hopefully make it easier to diagnose this particular problem in the future. Signed-off-by: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
2019-05-28 20:42:26 +02:00
``index.repaired=mixedup`` indicates the repair of a "Mixed Up"
encrypted PGP/MIME message, a mangling typically produced by
Microsoft's Exchange MTA. See
https://tools.ietf.org/html/draft-dkg-openpgp-pgpmime-message-mangling
for more information.
doc: add notmuch-properties(7) We will want a user-facing place to record details about the use of notmuch properties shortly. This establishes a new manual page for that purpose.
2017-10-21 04:25:39 +02:00
SEE ALSO
========
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
:any:`notmuch(1)`,
:any:`notmuch-config(1)`,
:any:`notmuch-dump(1)`,
:any:`notmuch-insert(1)`,
:any:`notmuch-new(1)`,
:any:`notmuch-reindex(1)`,
:any:`notmuch-reply(1)`,
:any:`notmuch-restore(1)`,
:any:`notmuch-search-terms(7)`,
:any:`notmuch-show(1)`
Reference in a new issue Copy permalink