# This library provides various cryptographic primitives.

Just to get your taste buds wet...
### A minimal unpadded AES-CBC example

```rust
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](https://github.com/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](https://en.wikipedia.org/wiki/Intel_Management_Engine)

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.