kem: allow calculating encapsulation keys instead of borrowing

[tarcieri]

Eagerly calculating entire keypairs at a time, particularly for post-quantum algorithms that use relatively large keys, uses up a lot of stack space. This is particularly problematic for no_alloc users who can't easily shove the relevant types in a Box.

Decapsulator::encapsulation_key currently enforces that the decapsulator eagerly compute the relevant encapsulation key and make it always borrowable.

In RustCrypto/signatures#1261 ml-dsa was changed to use signature::Keypair instead of signature::KeypairRef in order to relieve stack pressure. Handling these kind of use cases is exactly why there are two traits to handle computing versus borrowing, with a blanket impl of the former for the latter that links them.

That isn't true of kem though, where Decapsulator currently requires borrowing. Though DecapsulatorRef is probably not a good name. Regardless, it would be good to either change Decapsulator to allow computing the EncapsulationKey on the fly, or have a pair of traits where one preserves the current behavior and the other permits OTF calculation.

cc @baloo @rozbb

[rozbb]

I agree having a trait that returns an owned encapsulation key is a natural solution. Silly thought: how necessary is this method at all? If a function really needs the encap key for some reason, can’t they just take the encap key as another arg? Or else take a 32B seed and do a full keypair generation from it?

[tarcieri]

Without a trait to obtain an encapsulation key, you’ll never have one to begin with