Restructure public API and implement `kem` + `zeroize`

[faern]

TLDR

Replace the existing public API with one that has 1) Clearly typed keys (#11) 1) Less abbreviated variable names, at least in the public API, to make it easier to read and understand 1) Ergonomic usage of both stack based and heap alloc based buffers for key storage 1) Support for automatically clearing sensitve key material by default (zeroize) 1) Opt-in support for the RustCrypto kem APIs 1) Add feature labels to the generated documentation for discoverability (doc_cfg requires nightly)

Full description

This work is based off of #16 but then heavily modified after. This is both according to discussions in that PR and a bunch of stuff I came up with. These are some of the main differences from what that PR contains at the time of writing this:

• Make the old public API private. I don't think this crate should have a myriad of public facing APIs. I think we should aim for one very nice and easy to use but flexible API that is always available, plus the opt in kem way of doing things.
• Don't allow the huge pubkeys or the secret keys on the stack. Since they will take too much space, or increase the risk of leaking key material.
• Add the kem feature and implement that API. But keep it off by default. It is a less ergonomic and harder to use API than the new default API exposed via the standalone functions encapsulate and decapsulate. I'd recommend anyone to use the "normal" API unless they need to interface with a crate requiring the kem traits.
• I opted for calling stuff "buffer" instead of "storage" after going back and fourth a couple of times :)
• Implement the zeroize traits on the appropriate key types. This feature is optional but on by default since it's good practice.

opinionated, could be controversial?: I tried to remove abbreviations as much as I could. I know one and two letter names are common in cryptography code. But they do not make anything easier to read. Especially keep abbreviations away from the public interface of the crate.

Sadly kem requires alloc due to how it's very hard to use the Encapsulator trait with non-static pubkeys. Any input in how to make this more flexible would be nice!

The git history here is trash at the moment. Very much just commit and run style history. My plan is to squash/clean it if/when we want to move ahead of this approach.

Hey @dkales sorry for just creating another PR. But I felt I wanted to show my solution, and this was way more efficient than trying to show/argue for it over in the other PR. Now we can discuss multiple types of solutions in parallel.

[faern]

I find no sane way to use this library on Windows without the alloc (implies std) feature. Because if you don't have heap allocation, you also don't have the ability to start a separate thread with more stack. And the default stack size on Windows simply is too small. In general, every Windows developer would likely have the alloc feature enabled and use Boxes. But I need to find a way to make the tests look nice and readable, and preferable work on Windows... I'll look into that

[faern]

I replaced the external_doc_test!(include_str!("../README.md")); solution to running the tests in the README.md with #![doc = include_str!("../README.md")] instead. This has the added benefit of the entire readme also ending up in the generated documentation for the crate. Otherwise those docs were a bit sparse.

I'm sorry that I do a lot of very different stuff in the same PR here. I'm all for structure and breaking down a problem into smaller pieces. So if you'd like me to I can submit separate PRs for these small improvements that are not really related to the core change.

[faern]

When we have solved #21 and get rid of the variants as features, we can test all combinations of features easily with the help of cargo hack test. But let's save that for a future effort :sweat_smile:

[dkales]

This seems quite ready to merge into v2 now, so I'll just do that. We should try to get a list of things missing from a version 2.0 in a tracking issue, and then probably release this soonish.

I would see the larger effort to split out the variants in a later v3.

[faern]

Great! :partying_face: I have a few more ideas that I want to experiment with before we settle on the new API... For example, now when we have the _boxed variants of everything. Maybe we don't need the entire KeyBuffer type at all :see_noevil:. Maybe we can have the non-boxed functions just straight up take `&mut [u8; ]` arrays, like the original API, but with the difference that they return better key types.

Should we try to fix all variants in the same binary for v2 also or do we postpone that to v3? I think the current design with just a single variant is extremely limiting in how you can use this crate. But rewriting that part is also not going to be trivial, and having v2 soon would be great. So depend on how fast you are comfortable going from v2 -> v3.