libqabu/

lib.rs

#![cfg_attr(test, feature(test))]
#![cfg_attr(not(feature = "std"), no_std)]
#![warn(
	missing_docs,
	missing_copy_implementations,
	missing_debug_implementations
)]

//! **This library provides various cryptographic primitives and strives to be durable, readable, auditable, and versatile.**
//!
//! 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(())
//! # }
//! # error().unwrap();
//! ```
//!
//! # Important remarks
//!
//! - The library exposes a vast amount of very low lever primitives
//! and **these will be insecure when used wrongly** 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.
//! - 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.
//!
//! # Usage
//!
//! Currently the library exposes the following primitives:
//!
//! *it is important to remark that almost everything here requires you
//! to include `libqabu::prelude::*`*
//!
//! ### Block ciphers
//!
//! If you just want to use a cipher for operations on single blocks,
//! simply pick one of the [Block Ciphers](crate::traits::Block), and
//! construct it while providing it a key.
//!
//! eg. for a cipher which simply accepts a array of some length as a key:
//!
//! ```
//! # use libqabu::prelude::*;
//! # use libqabu::symmetric::Blowfish;
//! # fn error() -> Result<(), Box<dyn std::error::Error>> {
//! //							  key
//! let cipher = Blowfish::new([0u8; 30])?;
//! # Ok(())
//! # }
//! # error().unwrap();
//! ```
//! and then you can use the functions exposed in [Block Ciphers](crate::traits::Block).
//!
//! ### Modes
//! if you need to encrypt more than one block (almost always the case) use one
//! of the [Modes](crate::traits::Mode)
//!
//! eg. for our previous example :
//!
//! ```
//! # use libqabu::prelude::*;
//! # use libqabu::symmetric::Blowfish;
//! # use libqabu::mode::CTR;
//! # fn error() -> Result<(), Box<dyn std::error::Error>> {
//! let cipher = Blowfish::new([0u8; 30])?;
//! let mode = CTR::with_counter(&cipher, [0u8; 8])?;
//! # Ok(())
//! # }
//! # error().unwrap();
//! ```
//! and then you can use the functions exposed in [Mode](crate::traits::Mode).
//!
//! ### Stream ciphers
//!
//! Construction is the same as block ciphers, afterwards use functions from
//! [Stream Ciphers](crate::traits::Stream)

/// Results and errors.
///
/// Contains the error types used
/// in this crate.
pub mod result;

/// All traits.
///
/// Contains all traits implemented by
/// components of the library.
pub mod traits;

/// Clears sensitive data from memory.
///
/// When the shred feature is enabled all ciphers will
/// clear out their keys and states on drop or when
/// the shred() function is called.
#[cfg(feature = "shred")]
pub mod shred;

#[cfg(feature = "apn")]
/// Contains number related structures
pub mod num;

#[cfg(feature = "shred")]
#[allow(unused)]
macro_rules! shred_on_drop {
	(
    	$ident: tt
    ) => {
		impl Drop for $ident {
			fn drop(&mut self) { self.shred(); }
		}
	};
}

/// The prelude module.
///
/// Much alike other preludes, imports traits
/// which are required to operate most algorithms
pub mod prelude {
	pub use crate::traits::*;

	#[cfg(feature = "shred")]
	pub use crate::shred::*;
}

/// Symmetric ciphers.
///
/// Block and stream symmetric ciphers.
///
/// Each algorithm can be included or excluded in compilation via feature choice.
pub mod symmetric;

/// Message digests.
///
/// This module contains both XOFs and static length output hash functions.
///
/// Each algorithm can be included or excluded in compilation via feature choice.
pub mod digest;

#[cfg(test)]
/// This module contains various test vectors.
pub mod tests;

/// Block cipher mode of operation.
///
/// Use this if you want to encrypt more than
/// one block worth of data with a block cipher.
pub mod mode;