From 41896bb841d91d7f005fc317183f2cff2a5179f0 Mon Sep 17 00:00:00 2001 From: Philipp Gesang Date: Mon, 10 Apr 2017 10:36:12 +0200 Subject: [PATCH] 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. --- deltatar/crypto.py | 28 ++++++++++++++++++++++++++++ 1 files changed, 28 insertions(+), 0 deletions(-) diff --git a/deltatar/crypto.py b/deltatar/crypto.py index f40270a..0a65741 100755 --- 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 -- 1.7.1