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_

unify file extension handling

The required extension no longer depends on the “[index]mode”
parameter since the encryption context is handled independently.
Add a function pick_extension() that reflects this circumstance
and appends the required suffixed depending on three inputs.

catch ESPIPE from ftell () on stream

The result is only used for status output so defaulting to -1 for
stdin doesn’t hurt. All functional uses of the current position
rely on the value of total_read.

improve parameter handling of crypto.py

allow decryption from std{in,out} via crypto.py

Make it possible to invoke the script as

    $ ./crypto.py test1234 - - <bfull-2017-04-04-0856-001.tar.pdtcrypt >out.tar.gz

for extra convenience.

handle zlib correctly

Encryption was split from the “compression mode” and now depends
entirely on the crypto context. Also only finalize a tar stream
being “closed” if the underlying file is being closed.

delay index file write until backup is complete

Due to restrictions of the file counting in the encryption
module, files must be handled in a strictly sequential manner.
Thus, postpone the creation of and all writes to the index file
until after all other files have been processed.

fix file offset calculation

Move the seek-back code down into the “low level file” wrapper so
header writes aren’t counted. This way byte counters match again.

add simple decryption routine to crypto.py

Currently this allows decrypting (and only decrypting) a backup
volume without requiring the deltatar layer in between.

rename open_index to open_auxiliary_file

We need a more neutral name since the functionality is accessed
elsewhere to write the info file too.

prevent the empty string as password

backup.py would default to using the empty string as password
which would cause a crypto context to be created even without
encryption being required.

Use ``None`` instead to indicate absence of a user-supplied
password.

actually output something in toc mode

Until now backup.py wouldn’t print anything when passed the -l
flag. Supply a trivial printer to the “list_func” argument to
output the contents similar to what GNU tar does.

pass encryption context to tarfile

This supersedes the individual parameters.

do not require parameter version with each encrypted object

When encrypting, stick to the parameter version specified in the
ctor. Despite the format allowing for on-the-fly adjustment of
encryption parameters, there is no real world scenario yet in
which this might be desired. Thus, remove this prerequisite as it
only encumbers the signature of ``.next()`` with cruft.

first draft for making the encryption layer independent

WIP.

In Deltatar, we cannot use the ctor itself to set up the
encryption because it is neutral wrt. reading / writing.
Only once one of the entry points:

- ``.list_backup()``,
- ``.create_full_backup()``, ``.create_diff_backup()``, or
- ``.restore_backup()``.

are invoked do we know what the object’s intended use is.
Thus we hook the encryption handler somewhere in there.

change extension for encrypted files

return collected fixed iv parts from .close() when encrypting

Provisional implementation for dumping the IVs in the info file
that will be superseded once the crypto context can be provided
to tarfile by the user.

automate iv fixed-part generation

The crypto context keeps track of the used IV fixed parts
so they can eventually be included in the info file. A new
fixed part is created in the ctor, then for every time the
counter wraps.

“Wrapping” resets the counter to 2 since 1 is globally reserved
for the info file.

properly enter/leave encryption sections

explicitly constuct zlib headers

Get rid of the unnecessary literal byte strings. Commit

    5fdff89f4d9fa28e6b210d40d389680072651eb7

introduced headers for additional blocks, omitting the “original
file name” field that gzip set by default.

unify zlib initialization

apply compression if compressor is present

overhaul pre- and post-crypto sync

In order to handle ``_Stream.close()`` well later, we need to
write the header of the last object before the tar info is
injected. To allow the padding and zlib finalization in .close(),
this cannot be performed when the actual file contents are
written but has to be suspended until we are certain no data will
be written to the current crypto object.

implement encryption passthrough mode

unify common operations between encryption and decryption

adjust versioned encryption parameters

Prepare for revised versioning: Both the encryption mechanism and
the KDF may be specified in the versioning.

extend open_index() API for info file handling

In fact, backup_python’s “info file” is just another “index file”
to deltatar. Conceptually they’re quite different though
especially regarding encryption. To allow requesting an info
flavored index file, add a parameter to communicate with the
crypto layer.

start payload encryption counter at 2

As per the spec, a file counter of 1 is reserved for the info
file.

track encryption state

reinit crypto for objects other than files

Invoke the new-item handler to force a new crypto object for
directories and anything else as well.

track data handled in crypto

first draft of revised encryption layer

WIP. Tested for encryption (no compression) only, and only for
TOC listings (-l).

Decryption is handled entirely by the stream, traversing the
archive entry wise relying only one the header informations.

Encryption requires poking the _Stream thingy to initiate a new
crypto entry.

simplify password save and retrieval

The password must be available for the entire time of the
decryption since it might be necessary to recalculate the key on
account of different salt or parameters of some object.

implement null-kdf to speed up testing

With “parameter version” zero, the KDF consists only of a trivial
string derived from the password so as to reduce runtime. (SCRYPT
takes about 48 seconds here with our parameters.)

adapt tag handling in decryption

fix encrypted read logic for begin/end at entry boundaries

retrieve and save GCM tag from object header

delay kdf until parameters are available from header

When decrypting, initialize the key immediately if parameters and
salt are being passed to the ctor. Otherwise, just save the
passphrase in the object and run the KDF when ``.next()`` is
passed the required bits as part of a PDTCRYPT header.

move ct length bookkeeping into encryptor

This saves us unreliable calculations over the _Stream progress
in tarfile.py.

move tag back into the header

Since we seek back to write the final header it makes little
sense to append the tag to the ciphertext regardless.

initially write dummy header during encryption

create crypto header in .next()

Saves us from exposing the IV to the stream.

redo transition between objects in crypto layer

When encrypting, the ciphertext size isn’t known beforehand.
Likewise, the file name isn’t available when initializing the
decryption of a file.

pass salt between index and archive

Memoization of the scrypt params requires static storage because
both the index file and the archive each have an encryption
context.

revise crypto context interface

Fold key handling and encryption into a common context “class”.
The context takes care of the counter, iv, keys etc. It has one
entry point (ctor) for each direction (read, write → decrypt,
encrypt) and provides hooks for transitioning to the next item.

Header and tag handling remain accessible independent of the
context since tarfile operates on the archive stream and file
objects.

redo stream decryption

When decrypting, the size of the encrypted object is known, as is
the length of the appended authentication tag; there is no
ambiguity regarding the end of an object. Thus the old string
matching logic with its linear search behavior can go.

supersede encryption type by encryption parameters

WIP

polish up backup.py arguments

These are about the only high-level clues regarding its
functionality so it may as well be presented right.

include offending mode string in exception

Be a little more informative about the cause considering this
exception is passed on to the user as-is.

ensure octal format is fed an integer

Fix a “type” error that seems to be enforced by Python 3:

      File "/src/python/python-delta-tar/deltatar/tarfile.py", line 220, in itn
        s = bytes("%0*o" % (digits - 1, n), "ascii") + NUL
    TypeError: %o format: an integer is required, not float

display backup.py usage if no action was specified

Getting no feedback if the invocation had no effect is rather
unseemly. Print the help message instead.

handle reading and formatting of tags

unit test scrypt wrapper

unit test bogus header data

unit test auth tag handling

unit test crypto handling of data spanning multiple chunks

unit test header handling

add basic wrapper for GCM handling with python-cryptography

This currently requires our yet unmerged contribution:
https://github.com/pyca/cryptography/pull/3421

add unit test module for encryption layer

remove key length parameter wherever feasible

Since we’re using fixed AES-128 everywhere, the  revised version
no longer offers adjustable key length.

make tarfile.py error out on invalid crypto modes and combos

The tarfile stream ctor will simply gloss over encryption
requested by the caller unless it happens to exactly match the
string (!) “aes”. Furthermore, with non-gzip compression the
encryption will be ignored altogether.

Instead of deceiving the user about the encryption being applied,
have the ctor fail immediately on invalid combinations.

init crypto support v2

Implements header reading and writing as well as PoC encryption
wrappers.

WIP

ignore all symlinks

Don’t delay the creation of symlinks but suppress it entirely.

The rationale is that extraction with deltatar will only ever
operate on inputs whose symlinks are dereferenced upon archive
creation. Thus valid archives will not contain symlinks at all.

Also, it would appear that deltatar assumes paths of objects
inside a tarball are unique. If the tarball contains ultiple
objects with the same path, it will extract only the first one it
encounters and ignore the rest. This means that it would take at
least two successive backups to perform a symlink attack, the
first one planting the link and the second writing over the
location. This is prevented by the current mitigation strategy
(and by the --unlink option of other tar utilities).

add unit test for overwriting symlinks

Currently, we implement the behavior of GNU Tar: Subsequent files
in an archive override previous ones, which is also true of
symlinks.

rectify delayed symlink restoration

Again, GNU tar serves as the model for safe behavior: We now
check whether the placeholder file exists and if it is indeed the
one we created earlier.

Since deltatar does not allow including symlinks in the backup,
the unit tests invoke tarfile functionality directly to add some
symlinks to an existing backup.

add unit test tracking behavior wrt symlinks

fix calls to deprecated function in deltatar.py

Fixes warning mandating “.warning()” over “.warn()”:

    DeprecationWarning: The 'warn' method is deprecated, use 'warning' instead

delay only absolute symlinks and those pointing to parent dirs

Only apply the symlink hook on those with fishy targets. Internal
symlinks need not be contained so they can be applied as-is.

implement delayed symlink creation

Introduce a hook in ``extract()`` to invoke a callback if a
symlink is encountered in the archive. The implementation is
modeled after GNU Tar.

This is a v2 attempt on the symlink extraction problematic. The
first version simply ``unlink(2)`` all files before extraction
which is a less efficient albeit more robust strategy.

avoid crash in test helper due to fp division

As a matter of fact, ``randomint()`` accepts only int-ishly typed
values, not floats. Consequently, integer division is the way to
go.

simplify control flow in RestoreHelper methods

Make the control flow more obvious. The code in question was
introduced with commit ea6d3c3e… but did not make sense back then
either because cur_index which is the constant $1$ was compared
to the literal constant $0$:

+        cur_index = 1
+        while cur_index < len(self._data):
+            data = self._data[cur_index]
…
+                if cur_index == 0:

This bogus test was since removed but the convoluted ``while``
loop survived. Instead, access index 1 only once using an integer
literal.

Increase version to 1.5

Code review done, comment changes only

Remove dead code

cur_index is always >= 1 in this code path

Remove code duplication

Don't use exception handling for normal control flow

-> Replace buf.index() with buf.find().

Unwinding the stack is expensive and we were
even doing it for the default code path.