false_bottom/lib.rs
1// SPDX-License-Identifier: GPL-3.0-or-later
2#![cfg_attr(docsrs, feature(doc_cfg))]
3//! ## Usage
4//! False Bottom is a [deniable encryption](https://en.wikipedia.org/wiki/Deniable_encryption) scheme.
5//! Unlike traditional encryption algorithms that map a given plaintext to ciphertext,
6//! False Bottom works by "adding" messages to an existing ciphertext.
7//! As such, the initial ciphertext and the keybase are generated from random data.
8//! The ciphertext then grows as messages are added whereas the keybase is fixed
9//! after initialization and is used to generate message specific keys for the ciphertext.
10//! The parameters for the [`init()`](FalseBottom::init()) function determine the size
11//! (in number of blocks) of the initial ciphertext and keybase respectively.
12//! Type aliases [`Fb128`], [`Fb256`] and [`Fb512`] are provided to pick a block size.
13//!
14//! ### Cipher Initialization:
15//! ```
16//! use false_bottom::{FalseBottom, Fb128};
17//! // Initialize 15 blocks of ciphertext and 12 blocks of keybase with a block size of 128 bits.
18//! let fb = Fb128::init(15, 12);
19//! ```
20//!
21//! ### Adding Messages:
22//! Multiple messages can be added using the [`add()`](FalseBottom::add()) method.
23//! This method returns an object [`FbKey`] that represents the message specific key for this message.
24//! Only this key can decrypt the added message.
25//! ```
26//! # use false_bottom::{FalseBottom, Fb128};
27//! # let mut fb = Fb128::init(15, 12);
28//! let msg = "Hello World!";
29//! let key = fb.add(msg.as_bytes());
30//! ```
31//!
32//! ### Decryption:
33//! The [`decrypt()`](FalseBottom::decrypt()) method returns the message that corresponds
34//! to the provided [`FbKey`].
35//! ```
36//! # use false_bottom::{FalseBottom, Fb128};
37//! # let mut fb = Fb128::init(15, 12);
38//! # let msg = "Hello World!";
39//! # let key = fb.add(msg.as_bytes());
40//! let decrypted = fb.decrypt(&key).unwrap();
41//! ```
42//! An example has been provided [here](https://codeberg.org/skran/false-bottom/src/branch/main/examples/encryption.rs).
43//!
44//! ### Import and Export
45//! Available formats: Raw bytes and Base64 encoded.
46//! #### Raw Bytes:
47//! The [`Encode`] trait provides methods for export and import of data.
48//! ```
49//! use false_bottom::{Encode, FalseBottom, Fb128, FbError, FbKey};
50//! # let mut fb = Fb128::init(15, 12);
51//! # let key = fb.add(b"Hello");
52//! // Exporting
53//! let (ciphertext_bytes, keybase_bytes) = fb.to_bytes();
54//! let key_bytes = key.to_bytes();
55//! // Importing
56//! let fb_imported = Fb128::from_bytes(&ciphertext_bytes, &keybase_bytes)?;
57//! let key_imported = FbKey::from_bytes(&key_bytes)?;
58//! # Ok::<(), FbError>(())
59//! ```
60//! #### Base64 Encoded:
61//! The feature `base64` needs to be enabled in your `Cargo.toml`.
62//! ```
63//! use false_bottom::{Encode, FalseBottom, Fb128, FbError, FbKey};
64//! # let mut fb = Fb128::init(15, 12);
65//! # let key = fb.add(b"Hello");
66//! // Exporting
67//! let (ciphertext_base64, keybase_base64) = fb.to_base64();
68//! let key_base64 = key.to_base64();
69//! // Importing
70//! let fb_imported = Fb128::from_base64(&ciphertext_base64, &keybase_base64)?;
71//! let key_imported = FbKey::from_base64(&key_base64)?;
72//! # Ok::<(), FbError>(())
73//! ```
74//! An example has been provided [here](https://codeberg.org/skran/false-bottom/src/branch/main/examples/export.rs).
75
76mod encode;
77mod falsebottom;
78mod fberror;
79mod fbkey;
80mod fbobj;
81mod primefield;
82mod packing;
83
84pub use crate::{
85 encode::Encode,
86 falsebottom::FalseBottom,
87 fbobj::{Fb128, Fb256, Fb512, FbObj},
88 fbkey::FbKey,
89 fberror::FbError,
90};
91
92use crate::{
93 packing::Packing,
94 primefield::PrimeField,
95};