cryptocol/lib.rs
1// Copyright 2023, 2024, 2025, 2026 PARK Youngho.
2//
3// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
4// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
5// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
6// This file may not be copied, modified, or distributed
7// except according to those terms.
8
9#![warn(missing_docs)]
10// #![warn(rustdoc::missing_doc_code_examples)]
11
12//! # cryptocol: A Comprehensive Cryptography Library
13//!
14//! ## Endianness Support
15//!
16//! `cryptocol` is optimized for **Little-endian** architectures, as they are
17//! the most widely used in modern computing. For more detailed information
18//! regarding Endianness (Little-endian vs. Big-endian), please read more
19//! [here](https://en.wikipedia.org/wiki/Endianness).
20//!
21//! ### Big-endian Compatibility Notice
22//!
23//! Support for __Big-endian__ architectures is currently experimental. We do
24//! not recommend using this crate on Big-endian systems for production or
25//! critical applications. Users choosing to do so assume full responsibility
26//! for any potential issues.
27//!
28//! ## Roadmap for Version 1.0
29//!
30//! The following features are planned for the `cryptocol` ecosystem.
31//!
32//! - [X] **Completed:** Implementation and documentation are at least **95%**
33//! complete.
34//! - [ ] __In Progress:__ Implementation or documentation is below __95%__, or
35//! work has not yet begun.
36//!
37//! ### 1. Small Numbers
38//! _Foundational types for Big Numbers and other cryptographic modules._
39//!
40//! - [X] **`SmallUInt` Trait:** Core implementation for primitive unsigned data
41//! types. --
42//! [`SmallUInt`](number/small_uint/trait.SmallUInt.html#trait.SmallUInt)
43//! - [X] **Primitive Unions:** Implementation of unions for primitive unsigned
44//! types. --
45//! [`ShortUnion`](number/short_union/union.ShortUnion.html#union.ShortUnion),
46//! [`IntUnion`](number/int_union/union.IntUnion.html#union.IntUnion),
47//! [`LongUnion`](number/long_union/union.LongUnion.html#union.LongUnion),
48//! [`LongerUnion`](number/longer_union/union.LongerUnion.html#union.LongerUnion),
49//! [`SizeUnion`](number/size_union/union.SizeUnion.html#union.SizeUnion),
50//! [`SharedValues`](number/shared_values/union.SharedValues.html#union.SharedValues), and
51//! [`SharedArrays`](number/shared_arrays/union.SharedArrays.html#union.SharedArrays)
52// ! - [ ] __`SmallSInt` Trait:__ (Planned) Core implementation for primitive
53// ! signed data type. -- `SmallSInt`
54// ! ===> Moved to Roadmap for ver. 2.0
55//!
56//! ### 2. Big Numbers
57//! _Essential for Asymmetric-Key Algorithms and high-precision calculations._
58//!
59//! - [X] **Fixed-Size Big Unsigned Integers:** Standard operations for large
60//! unsigned integers. --
61//! [`BigUInt`](number/big_uint/struct.BigUInt.html#struct.BigUInt).
62//! - [X] **Auxiliary Big Unsigned Integer Operations:** Specialized operations
63//! including modular arithmetic and primality testing. --
64//! [`BigUInt_More`](number/trait_big_uint_more/trait.BigUInt_More.html#trait.BigUInt_More),
65//! [`BigUInt_Modular`](number/trait_big_uint_modular/trait.BigUInt_Modular.html#trait.BigUInt_Modular),
66//! [`BigUInt_Prime`](number/trait_big_uint_prime/trait.BigUInt_Prime.html#trait.BigUInt_Prime), and
67//! [`BigUInt_Panic_Free`](number/trait_big_uint_panic_free/trait.BigUInt_Panic_Free.html#trait.BigUInt_Panic_Free).
68// ! - [ ] __Fixed-Size Big Signed Integers:__ (Planned) Standard operations for
69// ! large signed integers. -- `BigSInt`
70// ! ===> Moved to Roadmap for ver. 2.0
71// ! - [ ] __Variable-Size Big Signed Integers:__ (Planned) Standard operations
72// ! for large signed integers. -- `LargeInt`
73// ! ===> Moved to Roadmap for ver. 2.0 or higher
74//!
75//! ### 3. Hash Algorithms
76//!
77//! #### 3-1. Official SHA-series
78//! - [X] **SHA-3 & Keccak:** Supports 8/16/32/64-bit variants, including
79//! SHA3-224/256/384/512 and SHAKE 128/256. --
80//! [`Keccak_Generic`](hash/keccak/struct.Keccak_Generic.html#struct.Keccak_Generic)
81//! - [X] **SHA-2 (512/t):** Including 512/256 and 512/224 variants. --
82//! [`SHA2_512_t_Generic`](hash/sha2_512_t/struct.SHA2_512_t_Generic.html#struct.SHA2_512_t_Generic)
83//! - [X] **SHA-2 (512-bit):** SHA-512, SHA-384, and SHA-512/256. --
84//! [`SHA2_512_Generic`](hash/sha2_512/struct.SHA2_512_Generic.html#struct.SHA2_512_Generic)
85//! - [X] **SHA-2 (256-bit):** SHA-256 and SHA-224. --
86//! [`SHA2_256_Generic`](hash/sha2_256/struct.SHA2_256_Generic.html#struct.SHA2_256_Generic)
87//!
88//! #### 3-2. Educational Hash Algorithms (Insecure)
89//! **Warning:** These are intended for educational purposes only and should
90//! not be used for securing sensitive data.
91//!
92//! - [X] **SHA-1 & SHA-0:** 160-bit hash algorithms. --
93//! [`SHA1_Generic`](hash/sha1/struct.SHA1_Generic.html#struct.SHA1_Generic)
94// ! - [ ] __RIPEMD:__ (Planned) 256-bit hash algorithms. --
95// ! ===> Moved to Roadmap for ver. 2.0
96// ! - [ ] __BLAKE3:__ (Planned) 256-bit hash algorithms. --
97// ! ===> Moved to Roadmap for ver. 2.0
98// ! - [ ] __BLAKE2:__ (Planned) 256-bit hash algorithms. --
99// ! ===> Moved to Roadmap for ver. 2.0
100// ! - [ ] __MD6:__ (Planned) 256-bit hash algorithms. --
101// ! ===> Moved to Roadmap for ver. 2.0
102//! - [X] **MD5:** 128-bit hash algorithm. --
103//! [`MD5_Generic`](hash/md5/struct.MD5_Generic.html#struct.MD5_Generic)
104//! - [X] **MD4:** 128-bit hash algorithm. --
105//! [`MD4_Generic`](hash/md4/struct.MD4_Generic.html#struct.MD4_Generic)
106// ! - [ ] __MD2:__ (Planned) 128-bit hash algorithms. --
107// ! ===> Moved to Roadmap for ver. 2.0
108//!
109//! ### 4. Symmetric-Key Algorithms (Block Ciphers)
110//! #### 4-1. AES Finalists
111//! - [X] **AES (Advanced Encryption Standard) & Rijndael:** Full support for
112//! AES/Rijndael with various operation modes (ECB, CBC, PCBC, CFB, OFB,
113//! CTR) and padding schemes (PKCS#7, ISO 7816-4). --
114//! [`Rijndael_Generic`](symmetric/struct.Rijndael_Generic.html#struct.Rijndael_Generic),
115//! [`ECB_PKCS7`](symmetric/trait.ECB_PKCS7.html#trait.ECB_PKCS7),
116//! [`ECB_ISO`](symmetric/trait.ECB_ISO.html#trait.ECB_ISO),
117//! [`CBC_PKCS7`](symmetric/trait.CBC_PKCS7.html#trait.CBC_PKCS7),
118//! [`CBC_ISO`](symmetric/trait.CBC_ISO.html#trait.CBC_ISO),
119//! [`PCBC_PKCS7`](symmetric/trait.PCBC_PKCS7.html#trait.PCBC_PKCS7),
120//! [`PCBC_ISO`](symmetric/trait.PCBC_ISO.html#trait.PCBC_ISO),
121//! [`CFB`](symmetric/trait.CFB.html#trait.CFB),
122//! [`OFB`](symmetric/trait.OFB.html#trait.OFB), and
123//! [`CTR`](symmetric/trait.CTR.html#trait.CTR).
124// ! - [ ] __MARS:__ (Planned) Full support for MARS with various operation
125// ! modes (ECB, CBC, PCBC, CFB, OFB, CTR) and padding schemes (PKCS#7,
126// ! ISO 7816-4). -- `MARS_Generic`
127// ! ===> Moved to Roadmap for ver. 2.0
128// ! - [ ] __Serpent:__ (Planned) Full support for Serpent with various
129// ! operation modes (ECB, CBC, PCBC, CFB, OFB, CTR) and padding schemes
130// ! (PKCS#7, ISO 7816-4). -- `Serpent_Generic`
131// ! ===> Moved to Roadmap for ver. 2.0
132// ! - [ ] __Twofish:__ (Planned) Full support for Twofish with various
133// ! operation modes (ECB, CBC, PCBC, CFB, OFB, CTR) and padding schemes
134// ! (PKCS#7, ISO 7816-4). -- `Twofish_Generic`
135// ! ===> Moved to Roadmap for ver. 2.0
136// ! - [ ] __RC6:__ (Planned) Full support for RC6 with various operation
137// ! modes (ECB, CBC, PCBC, CFB, OFB, CTR) and padding schemes (PKCS#7,
138// ! ISO 7816-4). -- `RC6_Generic`
139// ! ===> Moved to Roadmap for ver. 2.0
140// !
141// ! #### 4-2. South Korean Encryption/Decryption algorithms
142// ! - [ ] __SEED:__ (Planned) Full support for SEED with various operation
143// ! modes (ECB, CBC, PCBC, CFB, OFB, CTR) and padding schemes (PKCS#7,
144// ! ISO 7816-4). -- `SEED_Generic`
145// ! ===> Moved to Roadmap for ver. 2.0
146// ! - [ ] __HIGHT:__ (Planned) Full support for HIGHT with various operation
147// ! modes (ECB, CBC, PCBC, CFB, OFB, CTR) and padding schemes (PKCS#7,
148// ! ISO 7816-4). -- `HIGHT_Generic`
149// ! ===> Moved to Roadmap for ver. 2.0
150// ! - [ ] __ARIA:__ (Planned) Full support for ARIA with various operation
151// ! modes (ECB, CBC, PCBC, CFB, OFB, CTR) and padding schemes (PKCS#7,
152// ! ISO 7816-4). -- `ARIA_Generic`
153// ! ===> Moved to Roadmap for ver. 2.0
154// ! - [ ] __LEA:__ (Planned) Full support for LEA with various operation
155// ! modes (ECB, CBC, PCBC, CFB, OFB, CTR) and padding schemes (PKCS#7,
156// ! ISO 7816-4). -- `LEA_Generic`
157// ! ===> Moved to Roadmap for ver. 2.0
158// ! - [ ] __IDEA:__ (Planned) Full support for IDEA with various operation
159// ! modes (ECB, CBC, PCBC, CFB, OFB, CTR) and padding schemes (PKCS#7,
160// ! ISO 7816-4). -- `IDEA_Generic`
161// ! ===> Moved to Roadmap for ver. 2.0
162// !
163// ! #### 4-3. Miscellaneous Encryption/Decryption algorithms
164// ! - [ ] __Bluefish:__ (Planned) Full support for Bluefish with various
165// ! operation modes (ECB, CBC, PCBC, CFB, OFB, CTR) and padding schemes
166// ! (PKCS#7, ISO 7816-4). -- `Bluefish_Generic`
167// ! ===> Moved to Roadmap for ver. 2.0
168// ! - [ ] __RC5:__ (Planned) Full support for RC5 with various operation
169// ! modes (ECB, CBC, PCBC, CFB, OFB, CTR) and padding schemes (PKCS#7,
170// ! ISO 7816-4). -- `RC5_Generic`
171// ! ===> Moved to Roadmap for ver. 2.0
172//!
173//! #### 4-2. Educational Block Ciphers (Insecure)
174//! **Warning:** These are intended for educational purposes only and should
175//! not be used for securing sensitive data.
176//!
177// ! - [ ] __RC2:__ (Planned) Standard DES implementation with multiple modes
178// ! (ECB, CBC, PCBC, CFB, OFB, CTR) and padding options (PKCS#7, ISO
179// ! 7816-4). -- `RC2_Generic`
180// ! ===> Moved to Roadmap for ver. 2.0
181//! - [X] **DES (Data Encryption Standard):** Standard DES implementation with
182//! multiple modes (ECB, CBC, PCBC, CFB, OFB, CTR) and padding options
183//! (PKCS#7, ISO 7816-4). --
184//! [`DES_Generic`](symmetric/struct.DES_Generic.html#struct.DES_Generic),
185//! [`ECB_PKCS7`](symmetric/trait.ECB_PKCS7.html#trait.ECB_PKCS7),
186//! [`ECB_ISO`](symmetric/trait.ECB_ISO.html#trait.ECB_ISO),
187//! [`CBC_PKCS7`](symmetric/trait.CBC_PKCS7.html#trait.CBC_PKCS7),
188//! [`CBC_ISO`](symmetric/trait.CBC_ISO.html#trait.CBC_ISO),
189//! [`PCBC_PKCS7`](symmetric/trait.PCBC_PKCS7.html#trait.PCBC_PKCS7),
190//! [`PCBC_ISO`](symmetric/trait.PCBC_ISO.html#trait.PCBC_ISO),
191//! [`CFB`](symmetric/trait.CFB.html#trait.CFB),
192//! [`OFB`](symmetric/trait.OFB.html#trait.OFB), and
193//! [`CTR`](symmetric/trait.CTR.html#trait.CTR).
194// ! - [ ] __Lucifer:__ (Planned) Standard Lucifer implementation with multiple
195// ! modes (ECB, CBC, PCBC, CFB, OFB, CTR) and padding options (PKCS#7,
196// ! ISO 7816-4). -- `Lucifer_Generic`
197// ! ===> Moved to Roadmap for ver. 2.0
198//!
199//! #### 4-3. Combined Cipher Containers
200//! - [X] **BigCryptor128:** A tool for combining multiple symmetric
201//! algorithms (e.g., 2AES, 3AES) with multiple modes (ECB, CBC, PCBC,
202//! CFB, OFB, CTR) and padding options (PKCS#7, ISO 7816-4). --
203//! [`BigCryptor128`](symmetric/struct.BigCryptor128.html#struct.BigCryptor128),
204//! [`ECB_PKCS7`](symmetric/trait.ECB_PKCS7.html#trait.ECB_PKCS7),
205//! [`ECB_ISO`](symmetric/trait.ECB_ISO.html#trait.ECB_ISO),
206//! [`CBC_PKCS7`](symmetric/trait.CBC_PKCS7.html#trait.CBC_PKCS7),
207//! [`CBC_ISO`](symmetric/trait.CBC_ISO.html#trait.CBC_ISO),
208//! [`PCBC_PKCS7`](symmetric/trait.PCBC_PKCS7.html#trait.PCBC_PKCS7),
209//! [`PCBC_ISO`](symmetric/trait.PCBC_ISO.html#trait.PCBC_ISO),
210//! [`CFB`](symmetric/trait.CFB.html#trait.CFB),
211//! [`OFB`](symmetric/trait.OFB.html#trait.OFB), and
212//! [`CTR`](symmetric/trait.CTR.html#trait.CTR).
213//!
214//! _Note: While supported, using native AES-256 or specific Rijndael variants
215//! is generally recommended over 2AES/3AES for better security and
216//! performance._
217//!
218//! - [X] **BigCryptor64:** A tool for combining multiple symmetric
219//! algorithms (e.g., 2DES, 3DES) with multiple modes (ECB, CBC, PCBC,
220//! CFB, OFB, CTR) and padding options (PKCS#7, ISO 7816-4). --
221//! [`BigCryptor64`](symmetric/struct.BigCryptor64.html#struct.BigCryptor64),
222//! [`ECB_PKCS7`](symmetric/trait.ECB_PKCS7.html#trait.ECB_PKCS7),
223//! [`ECB_ISO`](symmetric/trait.ECB_ISO.html#trait.ECB_ISO),
224//! [`CBC_PKCS7`](symmetric/trait.CBC_PKCS7.html#trait.CBC_PKCS7),
225//! [`CBC_ISO`](symmetric/trait.CBC_ISO.html#trait.CBC_ISO),
226//! [`PCBC_PKCS7`](symmetric/trait.PCBC_PKCS7.html#trait.PCBC_PKCS7),
227//! [`PCBC_ISO`](symmetric/trait.PCBC_ISO.html#trait.PCBC_ISO),
228//! [`CFB`](symmetric/trait.CFB.html#trait.CFB),
229//! [`OFB`](symmetric/trait.OFB.html#trait.OFB), and
230//! [`CTR`](symmetric/trait.CTR.html#trait.CTR).
231//!
232// ! ### 5. Symmetric-Key Algorithms (Stream Ciphers)
233// ! - [ ] __Chacha20:__ (Planned) Full support for Chacha20. --
234// ! `Chacha20_Generic`
235// ! ===> Moved to Roadmap for ver. 2.0
236// ! - [ ] __Salsa20:__ (Planned) Full support for Chacha20. --
237// ! `Salsa20_Generic`
238// ! ===> Moved to Roadmap for ver. 2.0
239// !
240// ! #### 5-1. Educational Stream Ciphers (Insecure)
241// ! - [ ] __RC4:__ (Planned) Full support for RC4. -- `RC4_Generic`
242// ! ===> Moved to Roadmap for ver. 2.0
243// !
244//! ### 5. Pseudo-Random Number Generators (PRNG)
245//! - [X] **Generic PRNG Framework**:
246//! struct [`Random_Generic`](random/struct.Random_Generic.html#struct.Random_Generic) and
247//! trait [`Random_Engine`](random/trait_random_engine/trait.Random_Engine.html#trait.Random_Engine)
248//! - [X] **Wizards to create Hash-based PRNGs**: Engines leveraging Keccak, SHA-3, SHA-2, and
249//! others. --
250//! [`Random_PRNG_Creator_BIG_KECCAK_1024`](random/struct.Random_PRNG_Creator_BIG_KECCAK_1024.html#struct.Random_PRNG_Creator_BIG_KECCAK_1024),
251//! [`Random_PRNG_Creator_SHA3_512`](random/struct.Random_PRNG_Creator_SHA3_512.html#struct.Random_PRNG_Creator_SHA3_512),
252//! [`Random_PRNG_Creator_SHA2_512`](random/struct.Random_PRNG_Creator_SHA2_512.html#struct.Random_PRNG_Creator_SHA2_512),
253//! [`Any_PRNG_Creator_SHAKE_256`](random/struct.Any_PRNG_Creator_SHAKE_256.html#struct.Any_PRNG_Creator_SHAKE_256),
254//! [`Any_PRNG_Creator_SHAKE_128`](random/struct.Any_PRNG_Creator_SHAKE_128.html#struct.Any_PRNG_Creator_SHAKE_128),
255//! [`Any_PRNG_Creator_SHA3_512`](random/struct.Any_PRNG_Creator_SHA3_512.html#struct.Any_PRNG_Creator_SHA3_512),
256//! [`Any_PRNG_Creator_SHA3_256`](random/struct.Any_PRNG_Creator_SHA3_256.html#struct.Any_PRNG_Creator_SHA3_256),
257//! [`Any_PRNG_Creator_SHA2_512`](random/struct.Any_PRNG_Creator_SHA2_512.html#struct.Any_PRNG_Creator_SHA2_512),
258//! [`An_PRNG_Creatory_SHA2_256`](random/struct.An_PRNG_Creatory_SHA2_256.html#struct.An_PRNG_Creatory_SHA2_256),
259//! [`Slapdash_PRNG_Creator_SHA1`](random/struct.Slapdash_PRNG_Creator_SHA1.html#struct.Slapdash_PRNG_Creator_SHA1),
260//! [`Slapdash_PRNG_Creator_SHA0`](random/struct.Slapdash_PRNG_Creator_SHA0.html#struct.Slapdash_PRNG_Creator_SHA0),
261//! [`Slapdash_PRNG_Creator_MD5`](random/struct.Slapdash_PRNG_Creator_MD5.html#struct.Slapdash_PRNG_Creator_MD5), and
262//! [`Slapdash_PRNG_Creator_MD4`](random/struct.Slapdash_PRNG_Creator_MD4.html#struct.Slapdash_PRNG_Creator_MD4).
263//! - [X] **Wizards to create Cipher-based PRNGs**: Engines leveraging Rijndael and DES. --
264//! [`Random_PRNG_Creator_Rijndael`](random/struct.Random_PRNG_Creator_Rijndael.html#struct.Random_PRNG_Creator_Rijndael),
265//! [`Any_PRNG_Creator_Rijndael`](random/struct.Any_PRNG_Creator_Rijndael.html#struct.Any_PRNG_Creator_Rijndael), and
266//! [`Slapdash_PRNG_Creator_DES`](random/struct.Slapdash_PRNG_Creator_DES.html#struct.Slapdash_PRNG_Creator_DES).
267//! - [X] **Wizards to create Simple PRNGs**: Basic randomization algorithms like
268//! [`Slapdash_PRNG_Creator_CPRNG_Engine`](random/struct.Slapdash_PRNG_Creator_CPRNG_Engine.html#struct.Slapdash_PRNG_Creator_CPRNG_Engine).
269//!
270//! ### 6. Asymmetric-Key Algorithms
271//!
272//! - [ ] __ECC (Elliptic Curve Cryptography):__ (Planned) Generic ECC
273//! implementation with padding support. --
274//! `ECC_Generic`.
275//! - [ ] __RSA (Ron Rivest, Adi Samir, Leonard Adleman):__ (In Progress)
276//! Implementation of RSA with PKCS #1 v1.5 and OAEP (Optimal Asymmetric
277//! Encryption Padding) (PKCS #1 v2.0/RFC 2437) padding. --
278//! [`RSA_Generic`](asymmetric/struct.RSA_Generic.html#struct.RSA_Generic),
279//! [`PKCS1V15`](asymmetric/trait.PKCS1V15.html#trait.PKCS1V15), and
280//! OAEP.
281//!
282//! ## Versioning Policy
283//! The project will reach Version 1.0.0.0 once all twenty-one functional
284//! areas listed above are fully implemented.
285//!
286//! - __Pre-v1.0:__ Versions will range up to 0.21.x.x based on the progress
287//! of the listed functionalities.
288//! - **Post-v1.0:** New features will increment the version beyond 1.0.0.0.
289//!
290//! _Note: Version numbers like 0.5.0.0 indicate progress through the
291//! functionality list, not necessarily a 50% completion of the entire
292//! codebase._
293
294
295#![doc(
296 html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png",
297 html_favicon_url = "https://www.rust-lang.org/favicon.ico",
298 html_root_url = "https://rust-random.github.io/rand/"
299)]
300
301pub mod number;
302pub mod hash;
303pub mod symmetric;
304pub mod random;
305pub mod asymmetric;
306pub(crate) mod concurrency;