fix misleading docstrings for index file hook

lay out skeleton for disaster recovery tests

New series of tests for corrupting backup sets and restoring them
incompletely (“tolerant” or “disaster recovery” mode).

draft disaster recovery mode for deltatar

The first stage recovery assumes the index is intact and all
objects are at their expected position. In this scenario, an
attempt is made to extract each object, keeping track of those
that weren’t readable and why.

return valid decrypted data on decryption failure

force tarfile reopen after bad read in deltatar

Closing the tarfile after an unreadable object was encountered
causes the stream to be reopened for the next read. Otherwise,
the corrupt object is already buffered and tarfile would continue
to seek inside the bad data.

distinguish invalid files from parse errors in restore

Especially with index files, the parse error is misleading.
Indicate the prevalent cause of the problem, i. e. that the
file is compressed but compression was not requested during
restore.

update help usage strings wrt. crypto in backup.py

extend crypto.py exception descriptions

actually default to i2n mode with crypto.py scrypt

And adapt the relevant unit test to explicitly request the full
parameters output.

add crypto.py option to output cnf-compatible scrypt object

support PDT encrypted archives with rescue_tar.py

adapt file_crypt.py for revised crypto

kill off old crypto implementation

The old aescrypto.py was only kept for reference but since
downstream integration is more or less complete wrt. encryption
we don’t need it any longer.

Good riddance.

allow passing salt to crypto.py on the command line

Nifty shortcut for hashing without a corresponding pdtcrypt file.

properly align usage message of crypto.py

improve bad CLI argument handling of crypto.py

include header version info in scrypt handler

accept crypto format version in deltatar ctor

add unit test for CLI scrypt hashing

allow passing keys directly to CLI crypto.py

Keys may now be passed as command line argument or environment
variable.

The only valid format is 16 bytes in hexadecimal.

grab password from envp if not supplied on CLI

In order to avoid the password showing up in full in the process
table, pass it in the environment instead. Uses the environment
variable PDTCRYPT_PASSWORD with both crypto.py and backup.py.

default to index mode of deltatar object when choosing extension

For external use.

handle bad randomness during IV creation

Since IVs must be unique we rely on /dev/urandom to yield a
different sequence of bytes when requesting a new fixed part.
In the unlikely event that a new fixed part has already been
used earlier, repeat it for number of times.

Abort if no unique IV could be generated this way since it
most likely indicates a faulty RNG.

extend crypto.py documentation

distinguish auxiliary file errors

Auxiliary files that grow larger than the maximum defined
encrypted file size cause an irrecoverable error because their
fixed IV is being reused. Add a new exception to distinguish this
specific case. Encrypted auxiliary files thus never consist of
more than one object, no on-the-fly continuation is permitted
like with ordinary files.

adapt unit tests for crypto.py subcommands

export scrypt hashing functionality

add SCRYPT hashing mode to crypto.py

Add a subcommand “scrypt” to crypto.py in CLI mode. Example:

    $ python3 ./deltatar/crypto.py scrypt foo -i - -o pwd   \
        <backup_dir/bfull-2017-05-11-0919-001.tar.pdtcrypt
    {"scrypt_params": {"p": 1, "N": 65536, "dkLen": 16, "r": 8},
     "salt": "b'fbdbaa9890ae243eb16391199c9243f6'", "hash":
     "b'1e7d7a78b9300d461779e9c80e4a15ac'"}

The output “hash” is calculated from the salt in the first
header found in the given archive and the password specified.

graciously handle GCM data length limit

unit test crypto file counter wraparound

After the file counter reaches UINT_MAX, it wraps around and a
new fixed part must be created.

The file counter is 32 bit unsigned integer so it needs to be
lowered to make bounds testing feasible.

extend strict iv tracking to encryption

This is just an extra soundness check to prevent accidental reuse
if IVs when handled incorrectly (same initial counters passed
twice to the same context). In normal usage this case cannot
happen.

expand crypto api to accept precomputed key

reduce noise in test_multivol_compression_sizes.py

improve iv diagnostics when decrypting

test that seeking backwards is disallowed by _Stream

Re-extracting an already decrypted file will fail on account of
IV reuse. Currently, tarfile._Stream is not capable of performing
backward seeks, so we’re good. Should this limitation be removed
in a future version, this unit test will fail.

remove pytest dependency from test_crypto.py

add unit test for IV reuse

adapt crypto unit tests to run in main suite

remove IV validation step from RestoreHelper

Since the same decryption context is carried over between the Tar
volumes of one backup set, the built-in IV uniqueness checks
suffice. Between multiple backup sets, the salt and IV fixed
parts change, so there is no occasion for conflict. The IVs of
auxiliary files are unique anyways.

adjust acceptable size window for compressed unit test data

A low bound of 330 causes the test to fail with version 1.2.3 of
zlib.

Earlier this did not occur because in concat mode, tarfile would
always write an empty zlib compressed chunk right at the
beginning of the archive and then immediately create a new one as
soon as actual input arrived. For this reason, the resulting
archive size remained within the bounds chosen in
test_multivol.py. Due to the removal of the redundancy, this is
no longer the case. The problem is masked on newer versions of
zlib (tested: 1.2.8 of fc25) which create larger compressed files
in general for the same inputs.

For the “test_compress_single” unit test, the input consists of a
an archive 61440 bytes. Compress with level 9, window bits 31,
and a memlevel of 9, the output length is:

    version     size (B)
    1.2.3       308
    1.2.8       324

Add to that the file name in our custom header and the latter
passes 330 B whereas the former doesn’t.

A lower bound of 315 is justified.

reuse existing crypto context for subsequent volumes

validate exceptions being thrown from invalid tarfile.open() params

move final IV checks out of crypto context

Collect IVs while decrypting but postpone the final check for
duplicates. Reused IVs still trigger an exception during
decryption but since multiple different contexts may be active
(e. g. when handling a diff backup), the IVs they retrieved from
the headers must be compared afterwards. This test has its place
in a new function “validate” of the ``RestoreHelper`` and must be
called when decryption has been completed.

write auxiliary files whilst processing the backup

Introduce a fixed value for the index file counter to allow
encryption on the fly.

use independent decryption contexts for backup files

When restoring individual files from a diff backup, Deltatar will
traverse both tarballs simultaneously. This leads to access
patterns where reads are interleaved between the two sources,
possibly corrupting the decryption state. Thus when restoring
from multiple “index files” (in practice only two are relevant),
use a separate decryptor context for each of them.

clean up multi-index handling

WIP

properly handle encryption and compression of empty archives

The old implementation always initialized in the ctor regardless
of whether contents would be written to the archive. For empty
archives this now has to be done in ``.close()`` if no data has
been added yet.

adapt test_multivol_compression_sizes.py to revised crypto

remove redundant test

The first part of the condition always evaluates to True since
it’s the precondition to entering that branch.

encode operation modes

Introduce the “arcmode” to comprehensively switch modes to
supplant the pervasive ad-hoc string parsing and attribute
queries. Encodes the triple encryption, compression, concat.

cleanly perform block transition in non-concat mode

clarify exception-driven control flow

Distinguish the actual EOF when hit at the beginning from other
IO errors in _init_read_gz() and only catch this one where it’s
expected. Well formed archives do not end inside a header.

remove unused state variable

“internal_pos” which is only written to and never read was
introduced with this commit:

    commit 85737f48c38a432f2429e9e3e4b81fed164c4b9a
    Author: Eduardo Robles Elvira <edulix@wadobo.com>
    Date:   Fri Jul 5 11:50:43 2013 +0200

        extracting files in r#gz mode now works too, includes unit tests

and lacks a raison d’être ever since.

use append mode in symlink unit test

These tests currently fail despite using the original Gzipfile
compression path. The archives appear to overwrite instead the
passed archive instead of writing new objects.

fix multivol compression handling

handle uncompressed, encrypted archives with tarfile

Internally, tarfile.py uses “tar” to refer to uncompressed
archives, so just handle this accordingly at the API level.

sync on .close() for unencrypted archives

properly (re-) initialize compressor at archive / volume bounds

For unencrypted streams, the compressor still must be reset in
concat mode. For encrypted streams, the decompressor can be
initialized right at the start of the archive since no further
inputs are needed.

keep separate encryptor and decryptor contexts in deltatar.py

The same Deltatar object appears to function as handle for
reading and writing files simultaneously. To support this,
introduce two different crypto contexts that are created
on demand.

properly restart compression when encrypting

Separate finalization of a zlib block from creation of a new one.
Otherwise, we end up with trailing data from the last object that
lingers in the write buffer and gets flushed to the archive after
the next encrypted object has been initialized.

Also get rid of the “new_compression_block” wrapper which
needlessly complicated things.

Special precautions must be taken for the PAX format. Due to its
requirement of a global archive header, TarFile will write to the
stream prior to initialization that is performed in addfile().
Thus, initialize compression before the PAX header is being
written and properly restart compression for the first object
committed to the archive or volume.

use crypto.py to split test archive in test_encryption.py

This again verifies individual decryptability of objects in the
PDT archive.

implement passthrough mode in crypto.py

When invoked with --no-decrypt, write object headers and
ciphertext to output. Combined with --split this allows
extracting encrypted objects from the archive.

implement split mode for CLI encryption

explicitly disable gz initalization for _Stream’s used in aux files

The process of writing an auxiliary (index, info) file differs
drastically from that of tar archives: Since files are not added
individually, the encryption must be initialized externally and
the compression layer cannot rely on being enable in the ctor
because, obviously, the latter is executed before the manual
encryption setup can be performed.

Extend the API of the _Stream ctor with a parameter to “noinit”
to request that all initialization be postponed until the
encryption has been set up. This seems to do the trick but is
quite ugly.

fix decompression error handling

This seems to be a copy&paste oversight from

    commit be60ffd0598fec172eccb69f3c6a8433af6fb643
    Author: Eduardo Robles Elvira <edulix@wadobo.com>
    Date:   Mon Nov 4 08:50:55 2013 +0100

        initial port to python 3, not finished

which added the per-compression mode exceptions but not the
actual handling code.

fix index file encryption handling

convert test_deltatar to revised crypto

permit setting crypto.py parameter version via deltatar ctor

Introduce an optional argument to request a specific crypto
parameter version when invoking Deltatar. This isn’t of much
use ATM since only the one version is implemented, but it’s
handy for testing nonetheless.

eliminate the last traces of encryption “modes”

Since encryption handling has been moved outside of tarfile.py
these no longer apply. Thus remove all references so they don’t
obscure problems in the unit tests.

initialize compression globally for non-“concat” archives

remove obsolete unittests for 256 bit AES

pass encryption context to deltatar volume handlers

rework encryption unittests

fix compression handling on volume bounds

The old “concat compression” simply relied on the _Stream() ctor
to create a new zip block which is no longer possible since the
prerequisite encryption is only available when the first object
is committed to the archive.

Hence, reintroduce the new block initialization after
transitioning to the new volume.

add strict IV validation to decryption handler

Optionally (on CLI, with the “-s” flag) check for additional IV
properties:

    - Accidental reuse: in GCM, the same IV used more than once
      means that the plaintext is compromised.

    - Unstructured archive: In the headers of a normal PDT
      encrypted archive, the variable parts of the IVs are
      consecutive unless the fixed part changes.

allow selecting individual tests with runtests.py

If arguments are passed on the command line, interpret them as
test names and attempt to compose a suite comprising only the
tests specified.

The behavior remains the same if invoked without argument.

improve error handling in crypto handler

Since invalid tags are some the most important bits of
information to be passed down, make the corresponding error
message human-readable.

remove obsolete block size check

fix fallout from EOF changes in CLI decryptor

throw error on partial header reading stream

Throw the EOF exception only if the stream ends exactly at an
object boundary. Otherwise, when less then sizeof(hdr) bytes
are returned from read(), throw InvalidHeader to indicate a
malformed file. This keeps EOF a “benign” exception.

communicate remainder to caller when hitting EOF from crypto

strip extraneous parameters from decryption handler ctor

Format and parameter version as well as the salt are supplied
from the headers. Decrypting should thus only require the
password and, depending on context, an explicit counter as well
as the list of valid IV fixed parts.

add input checks at API boundaries

Verify conformance of user-supplied inputs on a very basic level,
communicating violations via InvalidParameter exception.

Of course due to the limitations of the type systems these can’t
be made exhaustive. E. g. no effort is being made to inspect a
(passing) list or dict test for well-formed contents.

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.

use exception to communicate tag mismatch

unify error and parameter handling in crypto.py

Three classes of errors:

    - bad encryption (tag mismatch, bad IVs);
    - bad user input (request info counter twice);
    - internal error (state was reached that indicates a problem
      with crypto.py).

remove obsolete tag handling functionality from crypto.py

The GCM tag does no longer occur independent of a PDT header so
these are no longer relevant.

fix search string in tar volume generation

use OSError instead of IOError

IOError is a synonym for OSError, so the latter should be used
everywhere to avoid confusion, especially when throwing the one
but catching the other.

Cf. PEP 3151.

allow test_compression_level.py as module

rework crypto.py unittests for revised encryption

Main changes:

    - Adjust usage to revised encryption handler.

    - Adapt to header format.

    - Adjust to changes in error passing (above all ``hdr_read()``).

    - Remove Scrypt or tag tests, these interfaces are no longer
      available.

specify salt and version in ctor when encrypting

Simplify the signature of Encrypt.next() by removing the salt and
version arguments: This will make the encryptor reuse the values
it already has which was either passed to or randomly generated
by the ctor. Currently there is no case where we’d need to change
the salt or version during encryption. When decrypting, the
values from the headers are used anyways so nothing changes over
there.

increment file counter after handling current object

fix IV fixed part validation on decryption

parse buffer as header if passed as arg to next()

adapt concat_compress unit tests to gzip block sequence

The unit tests assume that compression of three files requires
three distinct Gzip blocks. The first one of these is empty and
serves no purpose, differing from the others by containing the
more or less redundant archive name. This is no longer the case
after the revision of the header code: the first block will still
have the archive name in the metadata but also contain the first
file.

Thus, adapt the unit tests to no longer check for and then ignore
the empty initial gzip block.

prefer symbolic constants over literals referring to gzip header

The mixed use of hex and octal is pretty confusing to say the
least, use named constants instead that are defined only in
tarfile.

fix tarfile crypto parameter passing

Remove obsolete parameters like “password” that are no longer
meaningful after moving the creation of the crypto context
outside of tarfile.py.

Also, check test the presence of encryption attributes before
accessing them to avoid conflicts with zlib streams. (Kludgy, but
not avoidable without a larger changes due to the possibility of
“fileobj” being anything, including things that don’t satisfy all
the interfaces that “_Stream” provides.

accept external counter in crypto.py

Required when encrypting an auxiliary file of type info.

unify constant naming I2N_→PDTCRYPT_