crown/lib.rs
1//! # KittyTLS Cryptographic Library
2//!
3//! A comprehensive cryptographic library designed to provide first-class documentation,
4//! easy-to-use APIs, and wide deployment compatibility across different environments.
5//!
6//! ## 🚀 Quick Start
7//!
8//! For most use cases, we recommend using the high-level [`envelope`] module, which provides
9//! unified interfaces for common cryptographic operations:
10//!
11//! ```rust
12//! use crown::envelope::*;
13//! use crown::core::CoreWrite;
14//!
15//! // Hash operations
16//! let mut hasher = EvpHash::new_sha256()?;
17//! hasher.write(b"hello world")?;
18//! let digest = hasher.sum();
19//!
20//! // AEAD encryption
21//! # let key = [0u8; 16];
22//! # let nonce = [0u8; 12];
23//! # let mut data = [0u8; 1024];
24//! let cipher = EvpAeadCipher::new_aes_gcm(&key)?;
25//! cipher.seal_in_place_separate_tag(&mut data, &nonce, &[])?;
26//! # Ok::<(), Box<dyn std::error::Error>>(())
27//! ```
28//!
29//! ## 📚 Library Structure
30//!
31//! - **[`envelope`]** - High-level unified interfaces (recommended for most users)
32//! - **[`aead`]** - Authenticated encryption with associated data implementations
33//! - **[`block`]** - Low-level block cipher implementations
34//! - **[`stream`]** - Stream cipher implementations
35//! - **[`hash`]** - Cryptographic hash functions (fixed and variable length)
36//! - **[`mac`]** - Message authentication codes
37//! - **[`modes`]** - Cipher modes of operation for block ciphers
38//! - **[`padding`]** - Padding schemes for block alignment
39//! - **[`kdf`]** - Key derivation functions
40//! - **[`password_hash`]** - Specialized password hashing functions
41//!
42//! ## 🔒 Security Recommendations
43//!
44//! Users should understand which algorithms are secure and which are not. For beginners,
45//! we recommend the following modern, secure algorithms:
46//!
47//! - **Encryption**: Always use ChaCha20-Poly1305 or AES-GCM for authenticated encryption
48//! - **Hashing**: Use SHA-256, SHA-3, or BLAKE2 for general purposes
49//! - **Password Hashing**: Use Argon2, scrypt, or bcrypt for password storage
50//! <div class="warning">
51//! Avoid legacy algorithms like MD5, SHA-1, DES, and RC4 which are cryptographically broken.
52//! </div>
53//!
54//! ## Design Goals
55//!
56//! - **Ease of Use**: Simple, intuitive APIs with comprehensive documentation
57//! - **Performance**: Optimized implementations with platform-specific acceleration
58//! - **Security**: Constant-time operations and secure defaults
59//! - **Compatibility**: Support for `no_std` environments and various platforms
60//!
61//! ## Feature flags
62#![doc = document_features::document_features!()]
63#![cfg_attr(not(feature = "std"), no_std)]
64#![allow(clippy::needless_range_loop)]
65
66#[cfg(feature = "alloc")]
67extern crate alloc;
68
69pub mod aead;
70pub mod block;
71pub mod envelope;
72pub mod hash;
73pub mod kdf;
74pub mod mac;
75pub mod modes;
76pub mod padding;
77pub mod password_hash;
78pub mod stream;
79
80pub mod core;
81
82pub mod cuda;
83
84pub mod error;
85
86#[cfg(not(feature = "unstable"))]
87mod utils;
88#[cfg(feature = "unstable")]
89pub mod utils;
90
91#[cfg(feature = "unstable")]
92mod simd;