document exceptions used in encryption handler

Prepare clear and rigorous communication of errors and other
unexpected conditions to the user. Eventually these will make
the foundation for messages propagating up the stack until they
reach the UI.

diff --git a/deltatar/crypto.py b/deltatar/crypto.py
index f40270a..0a65741 100755 (executable)
--- a/deltatar/crypto.py
+++ b/deltatar/crypto.py
@@ -27,6 +27,34 @@ References:
 Trouble with python-cryptography packages: authentication tags can only be
 passed in advance: https://github.com/pyca/cryptography/pull/3421
 
+Errors
+-------------------------------------------------------------------------------
+
+Errors fall into roughly three categories:
+
+    - Cryptographical errors or data validity.
+
+        - ``InvalidGCMTag`` (decryption failed on account of an invalid GCM
+          tag),
+        - ``InvalidIVFixedPart`` (IV fixed part of object not found in list),
+        - ``DecryptionError`` (used in CLI decryption).
+
+    - Incorrect usage of the library.
+
+        - ``InvalidParameter`` (non-conforming user supplied parameter),
+        - ``InvalidHeader`` (data passed for reading not parsable into header),
+        - ``FormatError`` (cannot handle header or parameter version),
+        - ``RuntimeError``.
+
+    - Bad internal state. If one of these is encountered it means that a state
+      was reached that shouldn’t occur during normal processing.
+
+        - ``InternalError``,
+        - ``Unreachable``.
+
+Also, ``EndOfFile`` is used as a sentinel to communicate that a stream supplied
+for reading is exhausted.
+
 """
 
 import binascii