pyke/, ...: Extract utilities into a sort-of reusable library.

This commit changes no code, but it moves a lot of it about.  Tidying up
will come later.

(Pruned history of `catacomb-python' begins here.)

The code which is now the `Pyke' library used to be part of the Catacomb
Python bindings.  Beginning here is a pruned version of that history,
limited to the files which actually contributed to the `Pyke' codebase.
It was constructed from the original history, starting at revision
10e6f88a407ce04807b6ad76a81be553f8d7abaa, by running

git filter-branch --prune-empty --index-filter '
git ls-files -s | {
  mode=old
  keep=
  while read m h s f; do
    case $mode,$f in
      old,util.c | old,catacomb.c | old,catacomb-python.h)
keep="$keep $m,$h,$f" ;;
      old,pyke/*)
keep="$m,$h,${f#*/}" mode=new ;;
      new,pyke/*)
keep="$keep $m,$h,${f#*/}" ;;
    esac
    git update-index --force-remove $f
  done
  for i in $keep; do
    git update-index --add --cacheinfo $i
  done
}
' pyke-prehistory.head -- pyke/ util.c catacomb.c catacomb-python.h

and the tucking this empty commit beneath the head which actually
introduces the `pyke/' directory.  (This subterfuge is, unfortunately,
necessary for `git subtree' to construct the right history.)

pyke/, ...: Extract utilities into a sort-of reusable library.

This commit changes no code, but it moves a lot of it about.  Tidying up
will come later.

catacomb-python.h: Delete a stray trailing `\'.

This doesn't actually hurt anything because of the following blank line,
but, umm, ...

catacomb-python.h: Delete a stray trailing `\'.

This doesn't actually hurt anything because of the following blank line,
but, umm, ...

catacomb-python.h: Add a macro to declare module init functions.

catacomb-python.h: Add a macro to declare module init functions.

util.c: Replace mLib `DISCARD' with a plain `(void)' cast.

util.c: Replace mLib `DISCARD' with a plain `(void)' cast.

util.c: Rewrite `addmethods' to remove dependency on <mLib/darray.h>.

util.c: Rewrite `addmethods' to remove dependency on <mLib/darray.h>.

catacomb.c: Use a less awful version comparison.

catacomb.c: Use a less awful version comparison.

catacomb.c, util.c: Export `modname' and set it in main entry point.

This is preliminary work in splitting out the Catacomb-independent
utilities so that they can be used by other projects.

catacomb.c, util.c: Export `modname' and set it in main entry point.

This is preliminary work in splitting out the Catacomb-independent
utilities so that they can be used by other projects.

*.c: Use `Py_XDECREF' where applicable.

The Python 2.5 version of `Py_DECREF' isn't properly braced, so `if (x)
Py_DECREF(x);' provokes a dangling-`else' warning from the compiler.

*.c: Use `Py_XDECREF' where applicable.

The Python 2.5 version of `Py_DECREF' isn't properly braced, so `if (x)
Py_DECREF(x);' provokes a dangling-`else' warning from the compiler.

*.c: Reformat docstrings.

No functional changes here: just changing how the strings are
represented in the source.

*.c: Reformat docstrings.

No functional changes here: just changing how the strings are
represented in the source.

catacomb-python.h: Give up on Python versions prior to 2.5.

mp.c: Improve docstring.

*.c: Use Python macros rather than functions where possible.

pgen.c: Write a `pgen' status code as `PGST' consistently in docstrings.

catacomb-python.h, *.c: Move definitions back into implementation files.

The header was chock full of implementation details which weren't
needed by anything.  Move things which aren't needed further afield back
into their home files, and delete things like conversion functions which
aren't actually being used.

Also, some light reordering of the things that are left.

(This patch turns out to be remarkably commutative through the enormous
pile of changes coming up.)

key.c: Delete the `barf' function.

What even?

I think this must have been ancient debugging code, but it should never
have seen release.

bytestring.c: Delete unused buffer methods on `C.ByteString'.

I think this was needed in some ancient Python in order to inherit the
buffer methods from `str', but Python 2.5 certainly works fine without.

buffer.c: Give `BufferError' a text message.

catacomb-python.h: Give up on Python versions prior to 2.5.

field.c: Push field-polynomial property into binary-field base class.

Using the same code as for prime fields was a mistake, but sharing the
same code between polynomial- and normal-basis fields works just fine;
but there's no point in duplicating the property-table entry when
there's a perfectly good superclass to hang the property off -- and it
already has a property table!

*.c: Use Python macros rather than functions where possible.

catacomb-python.h, *.c: Move definitions back into implementation files.

The header was chock full of implementation details which weren't
needed by anything.  Move things which aren't needed further afield back
into their home files, and delete things like conversion functions which
aren't actually being used.

Also, some light reordering of the things that are left.

(This patch turns out to be remarkably commutative through the enormous
pile of changes coming up.)

.gitignore: Reorder the patterns and make them more specific.

Place recursively applicable patterns at the top (just `*.pyc' for
now).  Prefix others with `/' to keep them local.  Suffix directory
names with `/' for clarity's sake.

.gitignore: Delete some obsolete things.

I think `dist' and `deb-build' were from old private workflow that
shouldn't have leaked into the master repository.  I have a vague
recollection that `build-stamp' was from CDBS, which we no longer use.
I honestly have no idea what `py' and `test.py' were, but they've been
there from the beginning.

catacomb/.gitignore: Delete obsolete file.

I think this was only created because Subversion ignore patterns didn't
affect subdirectories.

.gdbinit: Delete this obsolete file.

It's set up for my particular development environment, using a Python
version that's not even supported any more.  And project-specific
`.gdbinit' files really don't work very well as things to distribute,
for vaguely obvious security reasons.

Merge branch '1.3.x' into HEAD

* 1.3.x:
  t/t-rand.py: Set the correct refernce seed value for `dsarand'.
  rand.c: More `Py_ssize_t' fixes.

t/t-rand.py: Set the correct refernce seed value for `dsarand'.

The number of steps taken is different on 32- and 64-bit platforms, with
no especially easy way to calculate it in a principled way.  Just use a
stupid case analysis to get the right answer.

Merge branch '1.2.x' into 1.3.x

* 1.2.x:
  rand.c: More `Py_ssize_t' fixes.

rand.c: More `Py_ssize_t' fixes.

Merge branch '1.3.x'

* 1.3.x:
  ec.c: Fix length type which should have been `Py_ssize_t'.

Merge branch '1.2.x' into 1.3.x

* 1.2.x:
  ec.c: Fix length type which should have been `Py_ssize_t'.

ec.c: Fix length type which should have been `Py_ssize_t'.

Merge branch '1.3.x'

* 1.3.x: (101 commits)
  rand.c: Show keyword argument as optional.
  mp.c: Fix punctuation error in docstrings.
  t/t-*.py: Use the `WriteBuffer.contents' property.
  t/t-bytes.py: Check that indexing, slicing, etc. return `C.ByteString'.
  t/t-algorithms.py: Add a simple test for `Keccak1600.copy'.
  t/t-algorithms.py: Add tests for other HSalsa20 and HChaCha key sizes.
  t/t-algorithms.py: Add AEAD tests.
  t/t-algorithms.py: Add tests for the new `KeySZ.pad' method.
  catacomb/__init__.py (KeySZRange.pad): Return correct value.
  algorithms.c: Propagate `AEADF_NOAAD' to `aad' objects.
  algorithms.c (AEADAAD.copy): Propagate the hashed length to the copy.
  t/: Add a test suite.
  ec.c: Don't lose error status when constructing points from a sequence.
  ec.c: Free partially constructed points coordinatewise.
  *.c: Be more careful about `PySequence_Size'.
  key.c: Reformat the rest of the `KeyError' constructor.
  key.c: Parse `KeyError' constructor arguments by hand.
  catacomb-python.h: Add a macro for raising `OverflowError'.
  key.c: Collect `KeyError' argument count as a separate step.
  key.c: Use tuple functions on `KeyError' argument tuple.
  ...

Merge branch '1.3.x'

* 1.3.x: (101 commits)
  rand.c: Show keyword argument as optional.
  mp.c: Fix punctuation error in docstrings.
  t/t-*.py: Use the `WriteBuffer.contents' property.
  t/t-bytes.py: Check that indexing, slicing, etc. return `C.ByteString'.
  t/t-algorithms.py: Add a simple test for `Keccak1600.copy'.
  t/t-algorithms.py: Add tests for other HSalsa20 and HChaCha key sizes.
  t/t-algorithms.py: Add AEAD tests.
  t/t-algorithms.py: Add tests for the new `KeySZ.pad' method.
  catacomb/__init__.py (KeySZRange.pad): Return correct value.
  algorithms.c: Propagate `AEADF_NOAAD' to `aad' objects.
  algorithms.c (AEADAAD.copy): Propagate the hashed length to the copy.
  t/: Add a test suite.
  ec.c: Don't lose error status when constructing points from a sequence.
  ec.c: Free partially constructed points coordinatewise.
  *.c: Be more careful about `PySequence_Size'.
  key.c: Reformat the rest of the `KeyError' constructor.
  key.c: Parse `KeyError' constructor arguments by hand.
  catacomb-python.h: Add a macro for raising `OverflowError'.
  key.c: Collect `KeyError' argument count as a separate step.
  key.c: Use tuple functions on `KeyError' argument tuple.
  ...

rand.c: Show keyword argument as optional.

mp.c: Fix punctuation error in docstrings.

t/t-*.py: Use the `WriteBuffer.contents' property.

t/t-bytes.py: Check that indexing, slicing, etc. return `C.ByteString'.

t/t-algorithms.py: Add a simple test for `Keccak1600.copy'.

t/t-algorithms.py: Add tests for other HSalsa20 and HChaCha key sizes.

t/t-algorithms.py: Add AEAD tests.

t/t-algorithms.py: Add tests for the new `KeySZ.pad' method.

catacomb/__init__.py (KeySZRange.pad): Return correct value.

If the input is already a multiple of the modulus, then don't round up
to the next one.

algorithms.c: Propagate `AEADF_NOAAD' to `aad' objects.

algorithms.c (AEADAAD.copy): Propagate the hashed length to the copy.

Merge branch '1.2.x' into 1.3.x

* 1.2.x: (89 commits)
  t/: Add a test suite.
  ec.c: Don't lose error status when constructing points from a sequence.
  ec.c: Free partially constructed points coordinatewise.
  *.c: Be more careful about `PySequence_Size'.
  key.c: Reformat the rest of the `KeyError' constructor.
  key.c: Parse `KeyError' constructor arguments by hand.
  catacomb-python.h: Add a macro for raising `OverflowError'.
  key.c: Collect `KeyError' argument count as a separate step.
  key.c: Use tuple functions on `KeyError' argument tuple.
  key.c: Rename sad-path label to `end'.
  key.c: Delete duplicate setting of `errstring'.
  util.c (mkexc): Populate dictionary before constructing exception class.
  key.c: Only set the error code.
  catacomb.c, util.c: Publish negative constants correctly.
  field.c: Delete the completely unused `getfe' function.
  key.c (convfilter): Fix sense of error tests.
  buffer.c, ec.c: Fix required size for EC `buffer' encoding.
  algorithms.c: Fix `max' property name in docstrings.
  catacomb/__init__.py (_HashBase): Check that integers are within bounds.
  debian/rules: Build using the provided Makefile.
  ...

Merge branch '1.2.x' into 1.3.x

* 1.2.x: (89 commits)
  t/: Add a test suite.
  ec.c: Don't lose error status when constructing points from a sequence.
  ec.c: Free partially constructed points coordinatewise.
  *.c: Be more careful about `PySequence_Size'.
  key.c: Reformat the rest of the `KeyError' constructor.
  key.c: Parse `KeyError' constructor arguments by hand.
  catacomb-python.h: Add a macro for raising `OverflowError'.
  key.c: Collect `KeyError' argument count as a separate step.
  key.c: Use tuple functions on `KeyError' argument tuple.
  key.c: Rename sad-path label to `end'.
  key.c: Delete duplicate setting of `errstring'.
  util.c (mkexc): Populate dictionary before constructing exception class.
  key.c: Only set the error code.
  catacomb.c, util.c: Publish negative constants correctly.
  field.c: Delete the completely unused `getfe' function.
  key.c (convfilter): Fix sense of error tests.
  buffer.c, ec.c: Fix required size for EC `buffer' encoding.
  algorithms.c: Fix `max' property name in docstrings.
  catacomb/__init__.py (_HashBase): Check that integers are within bounds.
  debian/rules: Build using the provided Makefile.
  ...

t/: Add a test suite.

It's fairly substantial, but far from complete.  It's also a little
strange in places because it's been sent backwards in time from the
future.

When building the Debian package, run the tests verbosely, so that if
the test crashes I stand a chance of figuring out where.

*.c: Be more careful about `PySequence_Size'.

This can be implemented by Python, so it can throw exceptions.
Fortunately, Python checks that the result is nonnegative, so we don't
have to worry about that.

ec.c: Don't lose error status when constructing points from a sequence.

The code would call `ecptxl_2' or `ecptxl_3' as appropriate, stash the
error status in `rc', and then fall out of the `if/else if' ladder to
`ok' -- which clobbers `rc', losing the error.  This is unfortunate if
the point has been partially filled in.

The right fix is to go unconditionally to `end'.  We already have `rc'
set appropriately, so `ok' isn't necessary; `ecptxl_2' has already
converted the point to internal form, and `ecptxl_3' constructs the
point in internal form anyway, so it would be wrong to drop into `fix'.

catacomb-python.h: Add a macro for raising `OverflowError'.

ec.c: Free partially constructed points coordinatewise.

The `EC_DESTROY' macro assumes that the other coordinates are null if
and only if `p->x' is.  This works badly with the current code
structure, which fills in coordinates as it goes along, and I think this
is a better fix than trying to maintain the coordinates in temporaries
until we're done.

*.c: Be more careful about `PySequence_Size'.

This can be implemented by Python, so it can throw exceptions.
Fortunately, Python checks that the result is nonnegative, so we don't
have to worry about that.

key.c: Reformat the rest of the `KeyError' constructor.

key.c: Parse `KeyError' constructor arguments by hand.

This allows additional arguments to be stored, as is conventional for
exception classes.

catacomb-python.h: Add a macro for raising `OverflowError'.

key.c: Collect `KeyError' argument count as a separate step.

util.c (mkexc): Populate dictionary before constructing exception class.

It turns out that the dictionary contents are copied into the new class
rather than being used by reference, so populating it later doesn't
actually do anything.

key.c: Use tuple functions on `KeyError' argument tuple.

catacomb.c, util.c: Publish negative constants correctly.

The various `KERR_...' constants and `PGEN_ABORT' are canonically
negative integers, but weren't published correctly.  Add a flags word to
`struct nameval' to identify constants which should really be signed,
and some fancy footwork to convert unsigned integers back to negative
values without upsetting C.  Adjust the `C' macro to spot negative
constants and mark them specially.

Not all is well.  In particular, the `KEXP_...' constants should /not/
be published as signed values, even if `time_t' is signed on the target
platform, because the Python bindings handle them exclusively as
`unsigned long' values.  To make this work, also introduce `CF' which
allows us to set the flags explicitly, and use it for `KEXP_...'.

key.c: Rename sad-path label to `end'.

Now we can use our exception-raising macros.

key.c: Delete duplicate setting of `errstring'.

This code is a total mess, and doesn't work anyway.  Let's start
cleaning it up.

util.c (mkexc): Populate dictionary before constructing exception class.

It turns out that the dictionary contents are copied into the new class
rather than being used by reference, so populating it later doesn't
actually do anything.

key.c: Only set the error code.

This briefly makes the error string unavailable, but only because the
actual constructor isn't wired up -- and if it were wired up then it
would fail immediately because it's programmed to accept only a single
argument.

catacomb.c, util.c: Publish negative constants correctly.

The various `KERR_...' constants and `PGEN_ABORT' are canonically
negative integers, but weren't published correctly.  Add a flags word to
`struct nameval' to identify constants which should really be signed,
and some fancy footwork to convert unsigned integers back to negative
values without upsetting C.  Adjust the `C' macro to spot negative
constants and mark them specially.

Not all is well.  In particular, the `KEXP_...' constants should /not/
be published as signed values, even if `time_t' is signed on the target
platform, because the Python bindings handle them exclusively as
`unsigned long' values.  To make this work, also introduce `CF' which
allows us to set the flags explicitly, and use it for `KEXP_...'.

field.c: Delete the completely unused `getfe' function.

It was introduced in the original commit, and never used at all.

field.c: Delete the completely unused `getfe' function.

It was introduced in the original commit, and never used at all.

key.c (convfilter): Fix sense of error tests.

So this never worked either.

buffer.c, ec.c: Fix required size for EC `buffer' encoding.

The problem is zero coordinates: the point at infinity is encoded as a
zero length word, so zero coordinates must be encoded as a single zero
byte, preceded by a length word of 1 -- which overruns the output buffer
provided, unless we take special care, which we haven't.

algorithms.c: Fix `max' property name in docstrings.

How embarrassing.

catacomb/__init__.py (_HashBase): Check that integers are within bounds.

The version of the `struct' module included with Python 2.5 writes a
warning to `stderr' and truncates rather than raising an exception.  Do
the work ourselves.

debian/rules: Build using the provided Makefile.

There were several problems with the old system.  Firstly, it only
actually worked by accident: setting an explicit build directory caused
Debhelper to search there for a makefile (which it didn't find, for
obvious reasons) and fall back to the Python distutils system.  That
would be OK, but only because there's only been one Python version I've
wanted to support in Debian for ages; but that's likely to change.  And
it won't run tests properly.

Instead, delete the `-B' option (which will break the upcoming tests).
Now Debhelper will build via the Makefile.  Set the `PYTHONS'
environment variable to the Python versions supported in Debian.  And
set the prefix correctly during installation.

debian/control: Add an explicit build-dependency on `dh-python'.

catacomb.c: Publish `RAND_IBITS' constant.

This is a limit on how much you can request in `seed', so it's sort of
important.

catacomb/__init__.py: Make KMAC `copy' work.

Two fixes needed:

  * Return the `new' object from `copy'.

  * Introduce a `_bare_new' class method to handle constructing the
    destination object, because `KMAC...' objects need a key argument.

util.c: Make `default' arguments optional in `get', `setdefault', `pop'.

Alas, `pop' is a little trickier than the others.

catacomb.c: Publish `RAND_IBITS' constant.

This is a limit on how much you can request in `seed', so it's sort of
important.

util.c: Fix sense of error check in `popitem'.

rand.c: Fix `TrueRand' constructor so it can possibly work.

pubkey.c (RSAPriv): Fix segfault if `p' is provided but not `q'.

Stupid typo.

catacomb/__init__.py (_ShakeBase._copy): Actally copy the hash state.

Rather than sharing because that doesn't end well.

algorithms.c (ShakeNN.copy): Return the copy rather than the original.

algorithms.c (KECCAK.extract): Fix method name in keyword-args string.

algorithms.c (hLATIN_prf): Allow all supported sizes of key.

algorithms.c: Add missing guard for `del' to property `set' functions.

Continuing the work of 9444777c58c60253afdabf5b45011440845770e0.

util.c: Make `default' arguments optional in `get', `setdefault', `pop'.

Alas, `pop' is a little trickier than the others.

util.c: Fix sense of error check in `popitem'.

catacomb-python.h, *.c: Fix how Python `pgen' handlers handle exceptions.

Oh, this was a mess.  The old code would convert an exception from a
Python handler into `PGEN_ABORT', and hope that the exception state was
still available when the overall operation ended.

This doesn't work.  In particular, steppers and testers are finalized by
calling them with `PGEN_DONE', and the interpreter doesn't like
re-entering Python with an exception set.  (In debug builds, this is an
assertion failure.)

Overhaul all of this nonsense.

  * Add a collection of utilities for saving and restoring the exception
    state.

  * Add a hook, in the `catacomb' module, for reporting `lost'
    exceptions, for the case where further exceptions are raised while
    responding to a first exception.

  * Use a larger `pypgev' structure to track the state of a Python event
    handler through the framework.  This structure holds a reference to
    the Python object itself, and a slot for recording an exception.

  * When a Python handler fails, stash the exception state in the slot
    provided by the `pypgev' structure if there isn't one already, and
    clear the pending exception.  If there is already an exception in
    the slot, then report the new exception through the hook described
    above.

  * Once a `pgen' operation completes, if it raised any exceptions at
    all, then the first of these is left in the exception slot.  If it
    fails otherwise, then we supply a generic exception.

rand.c, pgen.c: Invalidate random generators from pgen events.

I've not actually seen a crash from a Python program which keeps hold of
the random generator from a prime-generation event and tries to use it
after the operation has finished, but it was certainly possible.

Arrange for the event object to retain the random generator object (so
it always hands out the same one when requested), and invalidates it
when the event is itself invalidated.

This also involves messing with the `grand' code to cope with the idea
of invalidated random generators.

(cherry picked from commit d65d80d7c096e6afc500270ee29909f64869e5dc)

mp.c, util.c: Use `Py_ssize_t' for lengths.

Missed some from the earlier pass.