3 unstable releases
0.2.9 | May 28, 2023 |
---|---|
0.2.7 | Apr 30, 2023 |
0.1.8 | Feb 25, 2023 |
#722 in Cryptography
24 downloads per month
390KB
14K
SLoC
This library provides various cryptographic primitives.
Just to get your taste buds wet...
A minimal unpadded AES-CBC example
use libqabu::prelude::*;
use libqabu::symmetric::{Rijndael, RijndaelKey};
use libqabu::mode::CBC;
fn error() -> Result<(), Box<dyn std::error::Error>> {
let mut to_encrypt = [0u8; 32]; // this is just 32 zeros.
let key = [0u8; 16]; // this is just an example of a key
let iv = [0u8; 16]; // this is just an example of a IV
let mut raw_cipher = Rijndael::new(
RijndaelKey::Small(key)
)?;
let mut cipher = CBC::new(&mut raw_cipher, iv)?;
cipher.encrypt_insitu(&mut to_encrypt)?;
println!("The encrypted data {:?}", to_encrypt);
Ok(())
}
fn main() { error().unwrap(); }
Installation
To use the library in your project clone the repository simply
download one of the releases from the main page and include it
in your Cargo.toml
.
That is:
libqabu = {path = "path/to/unpacked/tarball", features = ["feature", "list"]}
You may also use our crate registry, in ~/.cargo/config.toml
add:
[registries]
h49 = { index = "sparse+https://registry.22h49.one/" }
and then:
libqabu = { version="0.2.9", features = ["feature", "list"], registry = "h49"}
Or you can use crates.io
:
libqabu = { version="0.2.9", features = ["feature", "list"] }
Alternatively if you want to be on the bleeding edge use the git repository:
libqabu = {git = "git://22h49.one/libqabu", features = ["feature", "list"]}
Available features
shred
: Scrubs memory of sensitive data on drop (!!! important, include this !!!)std
: If included the library makes use oflibstd
and provides some features (mostly related toString
, things such as cipher names etc.). If excluded the library does not depend onlibstd
oralloc
- useful for building for embedded targets.ciphers
=block_ciphers
andstream_ciphers
modes
=ecb
,cbc
,cfb
,ctr
,ofb
, andpcbc
block_ciphers
=rijndael
,des
,twofish
,aria
,threefish
,blowfish
, andcamellia
stream_ciphers
=salsa20
andchacha20
digests
=md5
- These are self explanatory:
rijndael
des
desede
(depends ondes
)twofish
threefish
aria
camellia
salsa20
chacha20
blowfish
md5
ecb
cbc
ctr
cfb
pcbc
ofb
Building
The library contains test cases that verify the outputs of all of
the algorithms with known test vectors, running those on your machine
should verify that all implementations are output-correct. To do so
invoke cargo test
, and make sure that the result is test result: ok.
Note: these may take a second or two because large volumes of data are
being tested (About 9s on a Ryzen 7 4800u).
After verifying invoke cargo build
.
Important remarks
-
The library exposes a vast amount of very low lever primitives and these will be insecure when misused you use this only if you know exactly what you're doing. For use in applications please use a higher lever crate depending on this.
-
The library contains implementations of obscure and/or obsolete primitives (eg. DES, MD5 ...) for the sake of completeness. These are disabled by default in the build configuration but you have been warned to be weary of the build features you include.
Security and principles
- Dead simple and easy on your eyes
This code is meant to be read. If you have a notion of rust you should be able to understand all of it, and compare it with the reference implementations or the specifications of the algorithms. This is a priority for this project, and we will go as far as to sometimes sacrifice speed for code dexterity.
- Platform independent
Libqabu uses no special assembly instructions to perform cryptographic operations. This is a trade off in many ways, and if you disagree with it please consider the RustCrypto project.
What is gained?
Simplicity, dexterity, and my sanity (and a lot of it).
Crypto done completely in software , if rust runs this should as well! Better separation from things such as IntelME
What is lost?
Speed. (Highly dependent on the platform)
Side channel attacks: there is no built-in obscurity to make side channel (hardware) attacks harder in the case of this library, some platforms claim to curb these attacks with their custom instructions.
- Monolithic
This library, contrary to most other crypto suites is monolithic. It is built out of "features" rather than separate crates. The components can be included in the build or excluded via rust features.
But what does this mean for me?
- This is not meant for full disk encryption or very high speed processing of a large volume of data.
- This is not meant for applications where hardware side channels are an issue.
- When adding it to your project please pick only the features
which you use. Do not just blindly pick
features=["all"]
- How fast is this?
That, obviously, depends. Clone the project and run
cargo bench
to find out for yourself.