confium_api/plugin/
kem.rs

1//! `KemPlugin` trait — the Rust-side counterpart of the KEM v0 wire
2//! protocol.
3//!
4//! The KEM interface has two object types: an encapsulator (sender,
5//! holds the recipient's public key) and a decapsulator (recipient,
6//! holds the recipient's secret key). A single plugin implements both,
7//! plus keypair generation and a shared-secret size query.
8//!
9//! Plugin authors implement this trait on a state type, then apply
10//! `#[plugin_interface(name = "kem", version = 0)]` to the impl block.
11//!
12//! See `crates/confium-core/src/ffi/kem.rs` for the loader-side wire
13//! types.
14
15use crate::error::PluginResult;
16use crate::options::OptionView;
17
18/// Result of encapsulation: the ciphertext to send and the shared
19/// secret.
20pub struct KemEncapsulateResult {
21    /// Ciphertext bytes to send to the recipient.
22    pub ciphertext: Vec<u8>,
23    /// Shared secret derived on the sender side.
24    pub shared_secret: Vec<u8>,
25}
26
27/// Result of keypair generation.
28pub struct KemKeypair {
29    /// Public key bytes.
30    pub public_key: Vec<u8>,
31    /// Secret key bytes.
32    pub secret_key: Vec<u8>,
33}
34
35/// Trait implemented by KEM plugins. The type `Self` serves as both the
36/// encapsulator and decapsulator state — the plugin dispatches
37/// internally based on which entry points are called.
38pub trait KemPlugin: Sized {
39    /// Construct an encapsulator from the recipient's public key.
40    fn encapsulator_create(
41        algorithm: &str,
42        recipient_pubkey: &[u8],
43        opts: Option<OptionView<'_>>,
44    ) -> PluginResult<Self>;
45
46    /// Encapsulate: produce a ciphertext and shared secret. Writes the
47    /// ciphertext and shared secret into the provided output buffers
48    /// and returns their lengths.
49    fn encapsulate(
50        &mut self,
51        ct_out: &mut [u8],
52        ss_out: &mut [u8],
53    ) -> PluginResult<KemEncapsulateResult>;
54
55    /// Construct a decapsulator from the recipient's secret key.
56    fn decapsulator_create(
57        algorithm: &str,
58        recipient_seckey: &[u8],
59        opts: Option<OptionView<'_>>,
60    ) -> PluginResult<Self>;
61
62    /// Decapsulate: recover the shared secret from the ciphertext.
63    /// Writes the shared secret into `ss_out` and returns its length.
64    fn decapsulate(&mut self, ciphertext: &[u8], ss_out: &mut [u8]) -> PluginResult<usize>;
65
66    /// Query the shared secret size for the named algorithm.
67    fn shared_secret_size(algorithm: &str) -> PluginResult<u32>;
68
69    /// Generate a keypair for the named algorithm. If `seed` is
70    /// provided, it is used deterministically.
71    fn keypair_generate(
72        algorithm: &str,
73        seed: Option<&[u8]>,
74        opts: Option<OptionView<'_>>,
75    ) -> PluginResult<KemKeypair>;
76}
confium_api/plugin/kem.rs

confium_api/plugin/
kem.rs
