The use of some raw pad bytes as part of the input to the session hash
is a feature of internal format 0, and therefore those bytes must be
taken only after format indicator has been handled.  This follows up
to commit 6774b320 to fix that.

* onetime:
  (Design Overview): Update where the session hash input bytes live.
  (PadSession._digest_source_length): This is just a length, so don't
    try to document where the initialization bytes are located.
  (PadSession._session_hash): Update documentation here too.
  (PadSession.prepare_for_encryption): Don't initialize hash here, and...
  (PadSession.prepare_for_decryption): ...update related comment here.
  (PadSession.convert): Don't initialize hash here either.
  (PadSession._make_inner_header, PadSession._handle_inner_header):
    Initialize session hash right after the fuzz source length bytes.

* check.sh: Update accordingly.

The calculation of the overall message digest now includes some raw
pad bytes (which are not used for encryption), so that the digest
authenticates the pad without reference to the plaintext.

(This really should have happened in commit 121cb054.)

In PadSession._make_inner_header, update the explanation of the
purpose of head fuzz and tail fuzz to match the current code.

Use a new '--test-mode' option to give the test suite a way to request
predictable output, and going back to using random -- or at least
randomer -- numbers in production mode.

* onetime
  (RandomEnough.__init__): Take new test_mode argument, instead of a
    caller-choosable seed argument, and if test_mode is true then
    initialize random number generator with a known magic number.
  (PadSession.__init__): Take new test_mode argument, and pass it
    along to RandomEnough().
  (main): Support new "--test-mode" option, by converting the code for
    the ancient and hitherto unused "--debug" option.

* check.sh: Add --test-mode flag to just the calls that need it.

The bug was a digest miscalculation when encrypting, and its cause was
a confusion about the order in which different things would get hashed
into the digest.

The right order is that the raw head fuzz gets hashed first, followed
by all the message plaintext.  But a subtle problem could either cause
the plaintext hashing to never happen at all, or cause the order of
hashing to be reversed.

The generation of head fuzz was being done in the first call to
convert(), but commit c9095f8b changed PadEncoder.encode() so that
*both* its call to convert() and its call to digest_gulp() were
conditionalized on whether there was some compressed output ready to
encode.  Remember, the compressor doesn't always emit anything on a
given call -- if it can't do enough compression, it buffers stuff up
for a while in the hopes that future input will be compressible based
on past input.

Furthermore, on short input, *no* call to compressor.compress()
returns any output, and we have to wait until compressor.flush(),
which isn't called until PadEncoder.finish().  This means that either
digest_gulp() doesn't get called at all, or, conversely, if we
deconditionalize it in PadEncoder.encode(), it gets called *before*
the first call to convert() -- because convert() would now first be
called in PadEncoder.finish() instead of in PadEncoder.encode() --
thus reversing the order in which head fuzz and plaintext get hashed.

The solution is to do what we should have done a long time ago:
prepare head fuzz in PadSession.prepare_for_encryption(), so that
hashing isn't sensitive to the order of calls to convert().  (A
corollary is that decryption should probably work the same way, but
let's do one change at a time.)

This solution also preserves the fix of the bug that commit c9095f8b
fixed -- the ugly and information-leaking extra newline in the base64
output, between head fuzz section and the message section -- by
ensuring that we never call base64.encodestring() on empty input.

Most of 'make check' still passes after this, except that some tests
still fail as before because of zap expectation issues:

  ERROR: expected 'v', found 'z'
  ERROR: did not see expected DigestMismatch message digest error
  FAIL: tampering with message digest causes authentication error

  ERROR: expected 'a', found 'w'
  ERROR: did not see expected DigestMismatch head fuzz digest error
  FAIL: tampering with head fuzz digest causes authentication error

I will finish updating the test suite in a subsequent commit.

* onetime
  (PadSession.__init__): New internal var self._head_buffer.
  (PadSession.prepare_for_encryption): Fill _head_buffer.
  (PadSession.convert): Don't handle head fuzz here, just prepend any
    head buffer to the result and empty the head buffer if so.  Also,
    add a blank line to indicate conditional flow better, and remove
    an obsolete comment.
  (PadSession._get_id): Remove extra blank line before definition start.
  (PadSession._consume_fuzz_bytes): Fix test for is_head_fuzz.
  (PadSession._make_fuzz): Fix doc string, and remove obsolete comment.
  (SessionEncoder.__init__): Remove _started_encoding flag.
  (SessionEncoder.encode): Deconditionalize call to digest_gulp.

While fixing the tests, I found an unexpected newline in the middle of
the base64-encoded region of an encrypted output file.  That led to
the realization that the deconditionalization of the convert call(),
in commit d7b8d9eb, had changed the boundaries of the base64 output.
This doesn't necessarily affect the correctness of the output, but it
does affect the aesthetics, and it produces an artifact that will
interfere with future debugging.  However, getting rid of that newline
is turning out to be surprisingly complicated; this commit is a start.

* onetime
  (SessionEncoder.__init__): New _started_encoding flag.
  (SessionEncoder.encode): Use the flag.  Emit debugging information.

* check.sh: Adjust a bunch of tests.
  ("tampering with ciphertext causes bzip decoder error"):
  Add exits around current debugging.

* onetime
  (SessionEncoder.encode): Call convert() unconditionally.

* check.sh: Start adjusting.

* onetime
  (PadSession.__init__): Rename _head_fuzz_digest to _msg_hash.
  (PadSession.digest_gulp): New method.
  (PadSession._verify_digests): Rename to...
  (PadSession._verify_digest): ...here, and adjust.
  (PadSession._consume_fuzz_bytes, PadSession._make_fuzz): Just take
    a head fuzz flag instead of a hash object, and conditionally
    update the internal session hash based on the flag.
  (PadSession.finish): Adjust.

Add a lot of debugging prints to discover that we can't count on
convert() getting called (and thus the session has getting initialized
with the head fuzz) on the first call to encode(), because the
compressor might not return anything on a given call and in particular
usually doesn't on the first call.  IOW, this doesn't work yet.

Mostly this is just the expected adjustments to checked lengths, etc.
A couple of changes were more substantive, however:

* check.sh
  ("tampering with head fuzz should have no effect"): Rename to...
  ("tampered head fuzz is detected, but decryption succeeds"): ...here.
    Add comment explaining why the expected behavior is questionable.
  ("tampering with head fuzz digest causes authentication error"): New test.

* onetime (PadSession.FuzzMismatch): Update description.

Since commit e343a860, OneTime hasn't done version control of the
config area, so remove a comment in the test suite referring to that,
and replace it with a comment about a design issue in the test suite.

* check.sh ("tampering with head fuzz should have no effect"):
  Add missing check_result call.

* onetime
  (Design Overview): Update for new hotness, and to be clearer.
  (PadSession._make_fuzz): Update doc string.

* onetime
  (PadSession._verify_digests): Advance tail buffer on each iteration.
  (PadSession.finish): Don't advance tail buffer to adjust for digest
    lengths anymore, because _verify_digests() handles that now.

See the conditional labeled "# KFF: BUG FIX".  The bug was that in
PadSession._verify_digests(), the iteration over the two kinds of
digests, head fuzz digest and message digest, failed to increment the
read position in self._tail_buffer.  The first iteration naturally
succeeded, since self._tail_buffer starts off in the right place, and
that's why we got a successful match for head fuzz.  But the second
iteration produced a totally random received checksum for the message,
because we were XOR'ing the *next* PadSession._digest_length stretch
of pad with the same stretch of self._tail_buffer we'd just done.

This commit leaves some new debugging commits in; I'll remove them
next.  However, there were also some substantive changes:

* onetime
  (PadSession._verify_digests): Shift frame in tail buffer too, as
    discussed above.  The way it is done here is a kluge; after the
    debugging statements are removed, I will do a cleaner fix.
    Improve doc string.
  (PadSession._make_fuzz): Compute digest of the underlying random
    data, not of the pad data nor of the XOR'd result.

This doesn't work yet, and this commit has debugging prints.

* onetime
  (PadSession.__init__): Initialize _head_fuzz_hash.
  (PadSession._make_fuzz, PadSession._consume_fuzz_bytes):
    Take optional new hasher parameter, and update it.
  (PadSession._make_inner_header, PadSession._handle_inner_header):
    Update hash when creating or consuming head fuzz.
  (PadSession._verify_digest): Rename to...
  (PadSession__verify_digests): ...here, and verify both digests.
  (PadSession.finish): When encrypting, emit head fuzz digest too.