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.

From 2.0-beta10 until now (i.e., from commit e9dc370d until now),
we were using raw bytes from the front of the pad as the pad ID, and
for much longer than that, some raw bytes from the pad have been
included as head fuzz and tail fuzz and verified.  But ever since the
introduction of message digests in commit 50e11781, the authentication
provided by verifying head and tail fuzz has been nugatory anyway.  So
this commit reverts commit e9dc370d, so that no raw pad data is
revealed in the pad ID, and randomizes the head and tail fuzz, so that
while their length is still verified their content is not.

* onetime: Update design overview and many comments.  Import `random`.
  (RandomEnough): New class.
  (PadSession._get_id): Go back to using SHA256, undoing commit e9dc370d.
  (PadSession._get_pad_bytes): Rename to...
  (PadSession._make_fuzz): ...here, and mask pad data with random bytes.
  (PadSession._make_fuzz_length_from_pad): Rename to...
  (PadSession._get_fuzz_length_from_pad): ...here, to avoid confusion.
  (PadSession._verify_fuzz_bytes): Rename to...
  (PadSession._consume_fuzz_bytes): ...here, and consume without verifying.
  (PadSession.FuzzMismatch): Adjust description.
  (PadSession.DigestMismatch): New exception class.
  (PadSession._make_inner_header, PadSession.finish): Adjust for all above.
  (PadSession.convert): Fix possible latent bug in variable initialization,
    by fixing the name of the initialized variable to be the same as
    the name actually used -- fortunately, the variable was being
    reliably initialized anyway because of the conditional flow in
    which the usages were embedded -- and initializing it to
    non-usable type None.  Simultaneously, rename that variable from
    `num_bytes_to_verify_now` to `num_bytes_to_consume_now`, and
    change another inner variable similarly.

* check.sh: Update expected pad IDs.
  ("tampering with message digest causes authentication error"):
    Adjust expected error.
  ("tampering with head fuzz causes authentication error",
   "tampering with tail fuzz causes authentication error"): Rename to...
  ("tampering with head fuzz should have no effect",
   "tampering with head fuzz should have no effect"): ...here, and
    adjust, using new 'zap' wildcard feature from commit 7b4b5caa.

* changes-tmpl: Update discussion of pad ID changes.

Consequently, also update the probed range in probe.sh, and update the
Pad ID as per commit e9dc370d.