confium_api/plugin/
cipher.rs

1//! `CipherPlugin` trait — the Rust-side counterpart of the symmetric
2//! cipher v0 wire protocol.
3//!
4//! Plugin authors implement this trait on their cipher state type, then
5//! apply `#[plugin_interface(name = "cipher", version = 0)]` to the impl
6//! block. The macro emits the eight canonical `cfmp_cipher_*` FFI symbols,
7//! one per trait method.
8//!
9//! Method → symbol mapping (see `crates/confium-core/src/ffi/cipher.rs`
10//! for the loader-side wire types):
11//!
12//! | trait method | FFI symbol | purpose |
13//! |--------------|------------|---------|
14//! | [`CipherPlugin::create_with_key`] | `cfmp_cipher_create`       | construct a new instance |
15//! | [`CipherPlugin::block_size`]      | `cfmp_cipher_block_size`   | block size in bytes |
16//! | [`CipherPlugin::key_size`]        | `cfmp_cipher_key_size`     | key length in bytes |
17//! | [`CipherPlugin::iv_size`]         | `cfmp_cipher_iv_size`      | nonce/IV length in bytes |
18//! | [`CipherPlugin::update`]          | `cfmp_cipher_update`       | encrypt/decrypt a chunk |
19//! | [`CipherPlugin::finalize`]        | `cfmp_cipher_finalize`     | flush remaining output |
20//! | [`CipherPlugin::reset`]           | `cfmp_cipher_reset`        | reset to initial state |
21//! | `Drop`                            | `cfmp_cipher_destroy`      | reclaim the boxed state |
22
23use crate::error::{PluginError, PluginResult};
24use crate::options::OptionView;
25
26/// Trait implemented by symmetric cipher plugins. The macro-generated
27/// `cfmp_cipher_create` calls [`CipherPlugin::create_with_key`]; all
28/// other symbols dispatch through `OpaqueHandle::<Self>::borrow_raw`
29/// and the corresponding trait method.
30pub trait CipherPlugin: Sized {
31    /// Construct a new cipher instance for the named algorithm with the
32    /// given key and IV. Either `key` or `iv` may be empty when the
33    /// algorithm does not require them.
34    fn create_with_key(
35        algorithm: &str,
36        key: &[u8],
37        iv: &[u8],
38        opts: Option<OptionView<'_>>,
39    ) -> PluginResult<Self>;
40
41    /// Block size in bytes for this instance.
42    fn block_size(&self) -> u32;
43
44    /// Key length in bytes for this instance's algorithm.
45    fn key_size(&self) -> u32;
46
47    /// IV / nonce length in bytes for this instance's algorithm.
48    fn iv_size(&self) -> u32;
49
50    /// Process `input` and write as many output bytes as fit into
51    /// `output`. Returns the number of bytes written. The caller
52    /// guarantees `output.len()` is large enough to hold one block of
53    /// ciphertext per block of input.
54    fn update(&mut self, input: &[u8], output: &mut [u8]) -> PluginResult<usize>;
55
56    /// Flush any buffered output (e.g. the final partial block after
57    /// padding) into `output`. Returns the number of bytes written.
58    fn finalize(&mut self, output: &mut [u8]) -> PluginResult<usize>;
59
60    /// Reset to the initial state (post-`create`).
61    fn reset(&mut self) -> PluginResult<()>;
62}
63
64/// Convenience used by macro-generated code to surface a buffer-too-small
65/// condition as a [`PluginError`] without repeating the boilerplate at
66/// every call site.
67pub fn insufficient_buffer(message: &str) -> PluginError {
68    PluginError::new(crate::ErrorCode::INSUFFICIENT_BUFFER, message)
69}
confium_api/plugin/cipher.rs

confium_api/plugin/
cipher.rs
