Update structure of SHA3

[marsella]

Addresses part of #132, but doesn't complete it.

This PR updates the high-level structure of SHA-3 to more closely imitate the spec. In particular, it:

• adds parameters to the keccak implementation to reduce per-function parameterization
• rearranges code to more closely match the order that things appear in the spec and to make many methods private.
• adds documentation on the high-level functions

One effect of this is to change the way that the hash and XOF functions are called; a remaining TODO for this PR is to fix all of the downstream failures that result from this API change. Addressed this with clarified types instead of changing a dozen downstream files! Yay!

Several things here are being left to future PRs. I'll write up issues for these before this PR is merged.

• many functions don't really look like their spec equivalents. Lower-level modifications of this kind are being saved for a separate PR
• some of the keccak implementation is overly specific to the SHA-3 instantiation parameters, when the spec writes it as more generic. Reducing hard-coded parameters (nr specifically) that don't affect the SHA-3 instantiations is being saved for a separate PR.

[weaversa]

It kind of feels like something is wrong the with sha3 if join (toBytes ... is needed every time its run. I've struggled quite a bit with SHA3's bit reorganization routine and haven't yet found an elegant way to avoid asking the user to rejigger values at the function boundary. If you consider updates here, please keep in in the loop.

[marsella]

It kind of feels like something is wrong the with sha3 if join (toBytes ... is needed every time its run. I've struggled quite a bit with SHA3's bit reorganization routine and haven't yet found an elegant way to avoid asking the user to rejigger values at the function boundary. If you consider updates here, please keep in in the loop.

Hm, that's a good point. I'll make a follow-up issue about it. It actually seems like we could package up the to/fromBytes calls into the SHA functions for any non-infinite return type, so at least the caller wouldn't have to do it -- that would cover most use cases in here except for some functions that operate over infinite streams out of SHAKE. Technically SHAKE is supposed to take a finite length parameter so I could dive into those (old versions of Dilithium, mostly) to see if we could refactor them and add a fin d constraint to the output length of Keccak.

I also have on my list to look more carefully at the state representation in this implementation. As you mention, the spec has a fairly weird indexing scheme and I'm not exactly sure that we're implementing that fully faithfully. I wonder if getting that in line would solve the input/output format inconsistency.

Edit: Added #138.

[mccleeary-galois]

Good step in the right direction, as the diff is getting a bit unwieldy I would prefer to get this in and punt most things to the next PR as you had stated.

[marsella]

@weaversa: It kind of feels like something is wrong the with sha3 if join (toBytes ... is needed every time its run. I've struggled quite a bit with SHA3's bit reorganization routine and haven't yet found an elegant way to avoid asking the user to rejigger values at the function boundary. If you consider updates here, please keep in in the loop.

I made #142 that introduces what I think is a nicer API for interacting with the SHA3 functions. Biggest caveat is that it's not quite as obvious how it correlates with the spec. Would appreciate your input on whether it aligns with your expectations / hopes for this spec!