kem: use byte arrays for EK and SS

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 `Kem`
trait which defines two associated `ArraySize`s:
- `Kem::CiphertextSize`: size of the ciphertext
- `Kem::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/Cargo.toml

@@ -17,11 +17,11 @@ Traits for Key Encapsulation Mechanisms (KEMs): public-key cryptosystems designe
 """
 
 [dependencies]
-crypto-common = { version = "0.2.0-rc.12", features = ["rand_core"] }
+common = { package = "crypto-common", version = "0.2.0-rc.12", features = ["rand_core"] }
 rand_core = "0.10.0-rc-5"
 
 [features]
-getrandom = ["crypto-common/getrandom"]
+getrandom = ["common/getrandom"]
 
 [package.metadata.docs.rs]
 all-features = true

kem/src/lib.rs

@@ -8,45 +8,123 @@
 #![forbid(unsafe_code)]
 #![warn(missing_docs, unused_qualifications, missing_debug_implementations)]
 
-pub use crypto_common::{Generate, KeyExport, KeySizeUser, TryKeyInit, typenum::consts};
+pub use common::{self, Generate, InvalidKey, KeyExport, KeySizeUser, TryKeyInit, typenum::consts};
 
+use common::array::{self, ArraySize};
+use core::{array::TryFromSliceError, convert::Infallible};
 use rand_core::TryCryptoRng;
 
 #[cfg(feature = "getrandom")]
-use {crypto_common::getrandom::SysRng, rand_core::TryRngCore};
+use {common::getrandom::SysRng, 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 [`Kem`], such as an encapsulator or decapsulator.
+pub type Ciphertext<K> = array::Array<u8, <K as Kem>::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 [`Kem`], such as an encapsulator or decapsulator.
+pub type SharedSecret<K> = array::Array<u8, <K as Kem>::SharedSecretSize>;
+
+/// Key encapsulation mechanism.
+///
+/// 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 Kem {
+    /// 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: Kem + 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>) {
         let Ok(ret) = self.encapsulate_with_rng(&mut SysRng.unwrap_err());
         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: Kem {
+    /// Encapsulator which corresponds to this decapsulator.
+    type Encapsulator: Encapsulate
+        + Kem<CiphertextSize = Self::CiphertextSize, SharedSecretSize = Self::SharedSecretSize>;
+
+    /// Retrieve the encapsulator associated with this decapsulator.
+    fn encapsulator(&self) -> Self::Encapsulator;
+}
+
+/// 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))
+    }
 }