kem: use byte arrays for EK and SS (#2220)

Some terminology:
- `EK`: encapsulated key, i.e. ciphertext, not to be confused with
"encapsulation key", the public key
- `SS`: shared secret, output of the decapsulator when given a
ciphertext a.k.a. encapsulated key

`EK` and `SK` were previously generic parameters on the `Encapsulate`
and `Decapsulate` traits, however KEMs don't benefit from overlapping
impls and have relatively fixed notions of what these types should be.

This commit replaces them with new type aliases `Ciphertext` and
`SharedSecret`:

- `Ciphertext<K>`: type alias for `Array<u8, K::CiphertextSize>`, a.k.a.
"encapsulated key", where `Array` is from `hybrid-array`.
- `SharedSecret<K>`: type alias for `Array<u8, K::SharedSecretSize>`

This means consumers of the traits always use bytestrings, which should
hopefully make it dramatically simpler to implement things generically
across KEMs.

The `K` generic parameter above is for types which impl a new
`KemParams` trait which defines two associated `ArraySize`s:
- `KemParams::CiphertextSize`: size of the ciphertext
- `KemParams::SharedSecretSize`: size of the shared secret

This was split out into its own trait so the `Ciphertext<K>` and
`SharedSecret<K>` type aliases work with either encapsulators or
decapsulators.

Next, `Decapsulate` was split into three(!) traits to handle fallible
decapsulation:

- `Decapsulate`: what we had before with the `Decapsulate::Encapsulator`
associated type extracted into a supertrait `Decapsulator`, which it now
bounds on. It has a provided `decapsulate_slice` method which returns
`core::array::TryFromSliceError` in the event the provided slice does
not match `CiphertextSize`
- `TryDecapsulate`: fallible equivalent of `Decapsulate`, kind of like
what we had prior to #2216, with an associated `Error` type and with a
`try_decapsulate` method that returns a result. It also bounds on
`Decapsulator` as its supertrait.
- `Decapsulator`: common supertrait of `Decapsulate` and
`TryDecapsulate` which defines the associated `Encapsulator` and
provides the `Decapsulator::encapsulator` method for retrieving it.

A blanket impl of `TryDecapsulate` is provided for types which impl
`Decapsulate` which uses `Infallible` as the error type, so any type
which impls `Decapsulate` can be used as a `TryDecapsulate`-bounded
argument. Likewise `Decapsulate` carries a `TryDecapsulate<Error =
Infallible>` bound which is satisfied by the blanket impl but also
enforces this property.

The reason we need to reintroduce fallible decapsulation is `dhkem`:
when I was scanning over our KEMs repo looking at the error types,
`dhkem` has `Error = Infallible`, but this hides that it was using
`elliptic_curve::PublicKey<C>` as its "encapsulated key" / ciphertext
type, which is a well-typed wrapper for a valid curve point.

With this type now being a raw byte slice, `dhkem` needs to handle
decoding the curve point in the `TryDecapsulate` impl, and if the point
fails to decode return an error (there are ways we could pseudorandomly
select a different point in constant time to compute a rejection symbol,
but having it return an error in this case seems like a straightforward
way to start).

Closes #2219

Author: tarcieri

kem/src/lib.rs

@@ -12,44 +12,131 @@ pub use common::{
     self, Generate, InvalidKey, Key, KeyExport, KeyInit, KeySizeUser, TryKeyInit, typenum::consts,
 };
 
+use common::array::{self, ArraySize};
+use core::{array::TryFromSliceError, convert::Infallible};
 use rand_core::TryCryptoRng;
 
 #[cfg(feature = "getrandom")]
 use {common::getrandom, rand_core::TryRngCore};
 
+/// Ciphertext message (a.k.a. "encapsulated key") produced by [`Encapsulate::encapsulate`] which is
+/// an encrypted [`SharedSecret`] that can be decrypted using [`Decapsulate::decapsulate`].
+///
+/// `K` is expected to be a type that impls [`KemParams`], such as an encapsulator or decapsulator.
+pub type Ciphertext<K> = array::Array<u8, <K as KemParams>::CiphertextSize>;
+
+/// Shared secret: plaintext produced after decapsulation by [`Decapsulate::decapsulate`] which is
+/// also returned by [`Encapsulate::encapsulate`].
+///
+/// `K` is expected to be a type that impls [`KemParams`], such as an encapsulator or decapsulator.
+pub type SharedSecret<K> = array::Array<u8, <K as KemParams>::SharedSecretSize>;
+
+/// Key encapsulation mechanism parameters: sizes of the ciphertext and decrypted plaintext.
+///
+/// This trait is impl'd by types that impl either [`Encapsulate`] or [`Decapsulate`] and defines
+/// the sizes of the encapsulated key and shared secret.
+pub trait KemParams {
+    /// Size of the ciphertext (a.k.a. "encapsulated key") produced by [`Encapsulate::encapsulate`].
+    type CiphertextSize: ArraySize;
+
+    /// Size of the shared secret after decapsulation by [`Decapsulate::decapsulate`].
+    type SharedSecretSize: ArraySize;
+}
+
 /// Encapsulator for shared secrets.
 ///
 /// Often, this will just be a public key. However, it can also be a bundle of public keys, or it
 /// can include a sender's private key for authenticated encapsulation.
-pub trait Encapsulate<EK, SS>: TryKeyInit + KeyExport {
-    /// Encapsulates a fresh shared secret
-    fn encapsulate_with_rng<R>(&self, rng: &mut R) -> Result<(EK, SS), R::Error>
-    where
-        R: TryCryptoRng + ?Sized;
+pub trait Encapsulate: KemParams + TryKeyInit + KeyExport {
+    /// Encapsulates a fresh [`SharedSecret`] generated using the supplied random number
+    /// generator `R`.
+    fn encapsulate_with_rng<R: TryCryptoRng + ?Sized>(
+        &self,
+        rng: &mut R,
+    ) -> Result<(Ciphertext<Self>, SharedSecret<Self>), R::Error>;
 
     /// Encapsulate a fresh shared secret generated using the system's secure RNG.
     #[cfg(feature = "getrandom")]
-    fn encapsulate(&self) -> (EK, SS) {
+    fn encapsulate(&self) -> (Ciphertext<Self>, SharedSecret<Self>) {
         match self.encapsulate_with_rng(&mut getrandom::SysRng.unwrap_err()) {
             Ok(ret) => ret,
         }
     }
 }
 
-/// Decapsulator for an encapsulated keys, with an associated encapsulator.
+/// Trait for decapsulators, which is a supertrait bound of both [`Decapsulate`] and
+/// [`TryDecapsulate`].
+pub trait Decapsulator:
+    KemParams<
+        CiphertextSize = <Self::Encapsulator as KemParams>::CiphertextSize,
+        SharedSecretSize = <Self::Encapsulator as KemParams>::SharedSecretSize,
+    >
+{
+    /// Encapsulator which corresponds to this decapsulator.
+    type Encapsulator: Encapsulate + Clone + KemParams;
+
+    /// Retrieve the encapsulator associated with this decapsulator.
+    fn encapsulator(&self) -> &Self::Encapsulator;
+}
+
+impl<K: Decapsulator> KemParams for K {
+    type CiphertextSize = <K::Encapsulator as KemParams>::CiphertextSize;
+    type SharedSecretSize = <K::Encapsulator as KemParams>::SharedSecretSize;
+}
+
+/// Decapsulator for encapsulated keys, with an associated `Encapsulator` bounded by the
+/// [`Encapsulate`] trait.
 ///
 /// Often, this will just be a secret key. But, as with [`Encapsulate`], it can be a bundle
 /// of secret keys, or it can include a sender's private key for authenticated encapsulation.
+/// It could also be a hardware device like an HSM, TPM, or SEP.
 ///
 /// When possible (i.e. for software / non-HSM implementations) types which impl this trait should
 /// also impl the [`Generate`] trait to support key generation.
-pub trait Decapsulate<EK, SS> {
-    /// Encapsulator which corresponds to this decapsulator.
-    type Encapsulator: Encapsulate<EK, SS>;
+pub trait Decapsulate: Decapsulator + TryDecapsulate<Error = Infallible> {
+    /// Decapsulates the given [`Ciphertext`] a.k.a. "encapsulated key".
+    fn decapsulate(&self, ct: &Ciphertext<Self>) -> SharedSecret<Self>;
 
-    /// Decapsulates the given encapsulated key
-    fn decapsulate(&self, encapsulated_key: &EK) -> SS;
+    /// Decapsulate the given byte slice containing a  [`Ciphertext`] a.k.a. "encapsulated key".
+    ///
+    /// # Errors
+    /// - If the length of `ct` is not equal to `<Self as Kem>::CiphertextSize`.
+    fn decapsulate_slice(&self, ct: &[u8]) -> Result<SharedSecret<Self>, TryFromSliceError> {
+        ct.try_into().map(|ct| self.decapsulate(&ct))
+    }
+}
 
-    /// Retrieve the encapsulator associated with this decapsulator.
-    fn encapsulator(&self) -> Self::Encapsulator;
+/// Decapsulator for encapsulated keys with failure handling, with an associated `Encapsulator`
+/// bounded by the [`Encapsulate`] trait.
+///
+/// Prefer to implement the [`Decapsulate`] trait if possible. See that trait's documentation for
+/// more information.
+pub trait TryDecapsulate: Decapsulator {
+    /// Decapsulation error
+    type Error: core::error::Error;
+
+    /// Decapsulates the given [`Ciphertext`] a.k.a. "encapsulated key".
+    fn try_decapsulate(&self, ct: &Ciphertext<Self>) -> Result<SharedSecret<Self>, Self::Error>;
+
+    /// Decapsulate the given byte slice containing a  [`Ciphertext`] a.k.a. "encapsulated key".
+    ///
+    /// # Errors
+    /// - If the length of `ct` is not equal to `<Self as Kem>::CiphertextSize`.
+    fn try_decapsulate_slice(&self, ct: &[u8]) -> Result<SharedSecret<Self>, Self::Error>
+    where
+        Self::Error: From<TryFromSliceError>,
+    {
+        self.try_decapsulate(ct.try_into()?)
+    }
+}
+
+impl<D> TryDecapsulate for D
+where
+    D: Decapsulate,
+{
+    type Error = Infallible;
+
+    fn try_decapsulate(&self, ct: &Ciphertext<Self>) -> Result<SharedSecret<Self>, Infallible> {
+        Ok(self.decapsulate(ct))
+    }
 }