#cipher #security #key #symmetric #auditable #primitive

no-std libqabu

A auditable and versitile Rust cryptography library

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

GPL-3.0 license

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 of libstd and provides some features (mostly related to String, things such as cipher names etc.). If excluded the library does not depend on libstd or alloc - useful for building for embedded targets.
  • ciphers = block_ciphers and stream_ciphers
  • modes = ecb, cbc, cfb, ctr, ofb, and pcbc
  • block_ciphers = rijndael, des, twofish, aria, threefish, blowfish, and camellia
  • stream_ciphers = salsa20 and chacha20
  • digests = md5
  • These are self explanatory:
    • rijndael
    • des
    • desede (depends on des)
    • 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.

No runtime deps