96 lines
3.5 KiB
Rust
96 lines
3.5 KiB
Rust
// SPDX-License-Identifier: GPL-3.0-or-later
|
|
#![cfg_attr(docsrs, feature(doc_cfg))]
|
|
//! ## Usage
|
|
//! False Bottom is a [deniable encryption](https://en.wikipedia.org/wiki/Deniable_encryption) scheme.
|
|
//! Unlike traditional encryption algorithms that map a given plaintext to ciphertext,
|
|
//! False Bottom works by "adding" messages to an existing ciphertext.
|
|
//! As such, the initial ciphertext and the keybase are generated from random data.
|
|
//! The ciphertext then grows as messages are added whereas the keybase is fixed
|
|
//! after initialization and is used to generate message specific keys for the ciphertext.
|
|
//! The parameters for the [`init()`](FalseBottom::init()) function determine the size
|
|
//! (in number of blocks) of the initial ciphertext and keybase respectively.
|
|
//! Type aliases [`Fb128`], [`Fb256`] and [`Fb512`] are provided to pick a block size.
|
|
//!
|
|
//! ### Cipher Initialization:
|
|
//! ```
|
|
//! use false_bottom::{FalseBottom, Fb128};
|
|
//! // Initialize 15 blocks of ciphertext and 12 blocks of keybase with a block size of 128 bits.
|
|
//! let fb = Fb128::init(15, 12);
|
|
//! ```
|
|
//!
|
|
//! ### Adding Messages:
|
|
//! Multiple messages can be added using the [`add()`](FalseBottom::add()) method.
|
|
//! This method returns an object [`FbKey`] that represents the message specific key for this message.
|
|
//! Only this key can decrypt the added message.
|
|
//! ```
|
|
//! # use false_bottom::{FalseBottom, Fb128};
|
|
//! # let mut fb = Fb128::init(15, 12);
|
|
//! let msg = "Hello World!";
|
|
//! let key = fb.add(msg.as_bytes());
|
|
//! ```
|
|
//!
|
|
//! ### Decryption:
|
|
//! The [`decrypt()`](FalseBottom::decrypt()) method returns the message that corresponds
|
|
//! to the provided [`FbKey`].
|
|
//! ```
|
|
//! # use false_bottom::{FalseBottom, Fb128};
|
|
//! # let mut fb = Fb128::init(15, 12);
|
|
//! # let msg = "Hello World!";
|
|
//! # let key = fb.add(msg.as_bytes());
|
|
//! let decrypted = fb.decrypt(&key).unwrap();
|
|
//! ```
|
|
//! An example has been provided [here](https://codeberg.org/skran/false-bottom/src/branch/main/examples/encryption.rs).
|
|
//!
|
|
//! ### Import and Export
|
|
//! Available formats: Raw bytes and Base64 encoded.
|
|
//! #### Raw Bytes:
|
|
//! The [`Encode`] trait provides methods for export and import of data.
|
|
//! ```
|
|
//! use false_bottom::{Encode, FalseBottom, Fb128, FbError, FbKey};
|
|
//! # let mut fb = Fb128::init(15, 12);
|
|
//! # let key = fb.add(b"Hello");
|
|
//! // Exporting
|
|
//! let (ciphertext_bytes, keybase_bytes) = fb.to_bytes();
|
|
//! let key_bytes = key.to_bytes();
|
|
//! // Importing
|
|
//! let fb_imported = Fb128::from_bytes(&ciphertext_bytes, &keybase_bytes)?;
|
|
//! let key_imported = FbKey::from_bytes(&key_bytes)?;
|
|
//! # Ok::<(), FbError>(())
|
|
//! ```
|
|
//! #### Base64 Encoded:
|
|
//! The feature `base64` needs to be enabled in your `Cargo.toml`.
|
|
//! ```
|
|
//! use false_bottom::{Encode, FalseBottom, Fb128, FbError, FbKey};
|
|
//! # let mut fb = Fb128::init(15, 12);
|
|
//! # let key = fb.add(b"Hello");
|
|
//! // Exporting
|
|
//! let (ciphertext_base64, keybase_base64) = fb.to_base64();
|
|
//! let key_base64 = key.to_base64();
|
|
//! // Importing
|
|
//! let fb_imported = Fb128::from_base64(&ciphertext_base64, &keybase_base64)?;
|
|
//! let key_imported = FbKey::from_base64(&key_base64)?;
|
|
//! # Ok::<(), FbError>(())
|
|
//! ```
|
|
//! An example has been provided [here](https://codeberg.org/skran/false-bottom/src/branch/main/examples/export.rs).
|
|
|
|
mod encode;
|
|
mod falsebottom;
|
|
mod fberror;
|
|
mod fbkey;
|
|
mod fbobj;
|
|
mod primefield;
|
|
mod packing;
|
|
|
|
pub use crate::{
|
|
encode::Encode,
|
|
falsebottom::FalseBottom,
|
|
fbobj::{Fb128, Fb256, Fb512, FbObj},
|
|
fbkey::FbKey,
|
|
fberror::FbError,
|
|
};
|
|
|
|
use crate::{
|
|
packing::Packing,
|
|
primefield::PrimeField,
|
|
};
|