cryptocol/lib.rs
1// Copyright 2023, 2024 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 crate provides libraries for cryptography.
13//!
14//! This crate is optimized for Little-endian CPUs because Little-Endian CPUs
15//! are far more popular than Big-endian CPUs. For the information about
16//! Endianness (including Little-endian and Big-endian)
17//! [Read more](https://en.wikipedia.org/wiki/Endianness).
18//!
19//! # Big-endian issue
20//! This crate is just experimental for Big-endian CPUs. So, you are not
21//! encouraged to use this crate for Big-endian CPUs for serious purpose.
22//! Only use this crate for Big-endian CPUs with your own full responsibility.
23//!
24//! # Road Map for Version 1.0
25//! This crate Cryptocol is planned to provide the following functionalities.
26//! The checked items have already been implemented including documentation
27//! at least 95%. The unchecked items have been implemented including
28//! documentation less than 95% or have not yet even been started to implement.
29//!
30//! ## Small Numbers: meaningful as itself, and also foundations mainly for Big Numbers as well as for other modules
31//! - [X] Unions for primitive data types and their implementation, and the
32//! implementation of trait SmallUInt for the Unions ---
33//! [`ShortUnion`](number/short_union/union.ShortUnion.html#union.ShortUnion),
34//! [`IntUnion`](number/int_union/union.IntUnion.html#union.IntUnion),
35//! [`LongUnion`](number/long_union/union.LongUnion.html#union.LongUnion),
36//! [`LongerUnion`](number/longer_union/union.LongerUnion.html#union.LongerUnion),
37//! [`SizeUnion`](number/size_union/union.SizeUnion.html#union.SizeUnion),
38//! [`SharedValues`](number/shared_values/union.SharedValues.html#union.SharedValues), and
39//! [`SharedArrays`](number/shared_arrays/union.SharedArrays.html#union.SharedArrays)
40//! - [X] Trait SmallUInt, its implementation for primitive data types, and the
41//! implementation of it for the Unions ---
42//! [`SmallUInt`](number/small_uint/trait.SmallUInt.html#trait.SmallUInt)
43// ! - [ ] Trait SmallSInt, its implementation for primitive data types, and the
44// ! implementation of it for the Unions ---
45// ! [`SmallSInt`](number/small_sint/trait.SmallSInt.html#trait.SmallSInt)
46// ! _--> Thinking about postponing to Roadmap for ver. 2.0_
47//!
48//! ## Big Numbers: meaningful as itself and also the foundation for Asymmetric-Key Algorithms
49//! - [X] Fixed Sized Big Unsigned Integer Operation --- You can find most of
50//! the methods you need for big integer calculation at
51//! [`BigUInt`](number/big_uint/struct.BigUInt.html#struct.BigUInt).
52//! - [X] Auxiliary Fixed Sized Big Unsigned Integer Operations --- If you don't
53//! find what you need at
54//! [`BigUInt`](number/big_uint/struct.BigUInt.html#struct.BigUInt),
55//! you may find it at
56//! [`BigUInt_More`](number/trait_big_uint_more/trait.BigUInt_More.html#trait.BigUInt_More).
57//! You can't find modular-related methods at
58//! [`BigUInt`](number/big_uint/struct.BigUInt.html#struct.BigUInt),
59//! but you may find them at
60//! [`BigUInt_Modular`](number/trait_big_uint_modular/trait.BigUInt_Modular.html#trait.BigUInt_Modular).
61//! You can't find panic-free-releated methods at
62//! [`BigUInt`](number/big_uint/struct.BigUInt.html#struct.BigUInt),
63//! but you may find it at
64//! [`BigUInt_Panic_Free`](number/trait_big_uint_panic_free/trait.BigUInt_Panic_Free.html#trait.BigUInt_Panic_Free).
65//! You can't find prime number-related methods at
66//! [`BigUInt`](number/big_uint/struct.BigUInt.html#struct.BigUInt),
67//! you may find it at
68//! [`BigUInt_Prime`](number/trait_big_uint_prime/trait.BigUInt_Prime.html#trait.BigUInt_Prime).
69// ! - [ ] Fixed Sized Big Signed Integer Operation --- BigSInt
70// ! _--> Thinking about postponing to Roadmap for ver. 2.0_
71// ! - [ ] Variable Sized Big Signed Integer Operation --- LargeInt
72// ! _--> Thinking about postponing to Roadmap for ver. 2.0 or higher_
73//!
74//! ## Hash Algorithms
75//! - [X] SHA-3 and Keccak hash algorithms based on 8/16/32/64 bits
76//! --- Includes SHA3-224, SHA3-256, SHA3-384, SHA3-512, SHAKE 128, SHAKE 256, cSHAKE-128, cSHAKE-256, Keccak family and their expanded versions.
77//! [`Keccak_Generic`](hash/keccak/struct.Keccak_Generic.html#struct.Keccak_Generic)
78//! - [X] SHA-2 hash algorithms based on 512/t bits
79//! --- Includes 512/256, SHA-512/224, and their expanded versions.
80//! [`SHA2_512_t_Generic`](hash/sha2_512_t/struct.SHA2_512_t_Generic.html#struct.SHA2_512_t_Generic)
81//! - [X] SHA-2 hash algorithms based on 512 bits
82//! --- Includes SHA-512, SHA-384, SHA-512/256, and their expanded versions.
83//! [`SHA2_512_Generic`](hash/sha2_512/struct.SHA2_512_Generic.html#struct.SHA2_512_Generic)
84//! - [X] SHA-2 hash algorithms based on 256 bits
85//! --- Includes SHA-256, SHA-224, and their expanded versions.
86//! [`SHA2_256_Generic`](hash/sha2_256/struct.SHA2_256_Generic.html#struct.SHA2_256_Generic)
87//! - [X] SHA-1 hash algorithms based on 160 bits
88//! --- Includes SHA-1, SHA-0, and their expanded versions.
89//! [`SHA1_Generic`](hash/sha1/struct.SHA1_Generic.html#struct.SHA1_Generic)
90// ! - [ ] RIPEMD hash algorithms based on 256 bits
91// ! --- Includes RIPEMD and its expanded versions.
92// ! ===> Moved to Roadmap for ver. 2.0
93// ! - [ ] BLAKE3 hash algorithms based on 256 bits
94// ! --- Includes BLAKE3 and its expanded versions.
95// ! ===> Moved to Roadmap for ver. 2.0
96// ! - [ ] BLAKE2 hash algorithms based on 256 bits
97// ! --- Includes BLAKE2 and its expanded versions.
98// ! ===> Moved to Roadmap for ver. 2.0
99// ! - [ ] MD6 hash algorithms based on 256 bits
100// ! --- Includes MD4 and its expanded versions.
101// ! ===> Moved to Roadmap for ver. 2.0
102//! - [X] MD5 hash algorithms based on 128 bits
103//! --- Includes MD5 and its expanded versions.
104//! [`MD5_Generic`](hash/md5/struct.MD5_Generic.html#struct.MD5_Generic)
105//! - [X] MD4 hash algorithms based on 128 bits
106//! --- Includes MD4 and its expanded versions.
107//! [`MD4_Generic`](hash/md4/struct.MD4_Generic.html#struct.MD4_Generic)
108// ! - [ ] MD2 hash algorithms based on 128 bits
109// ! --- Includes MD4 and its expanded versions.
110// ! ===> Moved to Roadmap for ver. 2.0
111//!
112//! ## Symmetric-key Algorithms for the Encryption/Decryption of digital data
113//! - [X] AES and Rijdael symmetric-key encryption/decryption algorithm and the trait implementations of Operation modes and padding bits for AES_Generic
114//! --- Includes AES and its expanded versions, and ECB, CBC, PCBC, CFB, OFB, and CTR modes, and padding bits
115//! according to PKCS#7 and ISO 7816-4.
116//! [`Rijdael_Generic`](symmetric/rijndael/struct.Rijndael_Generic.html#struct.Rijndael_Generic),
117//! [`ECB_PKCS7`](symmetric/trait.ECB_PKCS7.html#trait.ECB_PKCS7),
118//! [`ECB_ISO`](symmetric/trait.ECB_ISO.html#trait.ECB_ISO),
119//! [`CBC_PKCS7`](symmetric/trait.CBC_PKCS7.html#trait.ECB_PKCS7),
120//! [`CBC_ISO`](symmetric/trait.CBC_ISO.html#trait.CBC_ISO),
121//! [`PCBC_PKCS7`](symmetric/trait.PCBC_PKCS7.html#trait.PCBC_PKCS7),
122//! [`PCBC_ISO`](symmetric/trait.PCBC_ISO.html#trait.PCBC_ISO),
123//! [`CFB`](symmetric/trait.CFB.html#trait.CFB),
124//! [`OFB`](symmetric/trait.OFB.html#trait.OFB), and
125//! [`CTR`](symmetric/trait.CTR.html#trait.CTR).
126//! (symmetric/aes/struct.AES_Generic.html#struct.AES_Generic)
127// ! - [ ] MARS symmetric-key encryption/decryption algorithm
128// ! --- Includes MARS and its expanded versions. `MARS_Generic`
129// ! ===> Moved to Roadmap for ver. 2.0
130// ! - [ ] Serpent symmetric-key encryption/decryption algorithm
131// ! --- Includes RC6 and its expanded versions. `RC6_Generic`
132// ! ===> Moved to Roadmap for ver. 2.0
133// ! - [ ] Twofish symmetric-key encryption/decryption algorithm
134// ! --- Includes Twofish and its expanded versions. `Twofish_Generic`
135// ! ===> Moved to Roadmap for ver. 2.0
136// ! - [ ] RC6 symmetric-key encryption/decryption algorithm
137// ! --- Includes RC6 and its expanded versions. `RC6_Generic`
138// ! ===> Moved to Roadmap for ver. 2.0
139// ! - [ ] SEED symmetric-key encryption/decryption algorithm
140// ! --- Includes SEED and its expanded versions. `SEED_Generic`
141// ! ===> Moved to Roadmap for ver. 2.0
142// ! - [ ] HIGHT symmetric-key encryption/decryption algorithm
143// ! --- Includes HIGHT and its expanded versions. `HIGHT_Generic`
144// ! ===> Moved to Roadmap for ver. 2.0
145// ! - [ ] ARIA symmetric-key encryption/decryption algorithm
146// ! --- Includes ARIA and its expanded versions. `ARIA_Generic`
147// ! ===> Moved to Roadmap for ver. 2.0
148// ! - [ ] LEA symmetric-key encryption/decryption algorithm
149// ! --- Includes LEA and its expanded versions. `LEA_Generic`
150// ! ===> Moved to Roadmap for ver. 2.0
151// ! - [ ] IDEA symmetric-key encryption/decryption algorithm
152// ! --- Includes IDEA and its expanded versions. `IDEA_Generic`
153// ! ===> Moved to Roadmap for ver. 2.0
154// ! - [ ] Bluefish symmetric-key encryption/decryption algorithm
155// ! --- Includes Bluefish and its expanded versions. `Bluefish_Generic`
156// ! ===> Moved to Roadmap for ver. 2.0
157// ! - [ ] Chacha20 symmetric-key encryption/decryption algorithm
158// ! --- Includes Chacha20 and its expanded versions. `Chacha20_Generic`
159// ! ===> Moved to Roadmap for ver. 2.0
160// ! - [ ] Salsa20 symmetric-key encryption/decryption algorithm
161// ! --- Includes Salsa20 and its expanded versions. `Salsa20_Generic`
162// ! ===> Moved to Roadmap for ver. 2.0
163// ! - [ ] RC5 symmetric-key encryption/decryption algorithm
164// ! --- Includes RC5 and its expanded versions. `RC5_Generic`
165// ! ===> Moved to Roadmap for ver. 2.0
166// ! - [ ] RC4 symmetric-key encryption/decryption algorithm
167// ! --- Includes RC4 and its expanded versions. `RC4_Generic`
168// ! ===> Moved to Roadmap for ver. 2.0
169// ! - [ ] RC2 symmetric-key encryption/decryption algorithm
170// ! --- Includes RC2 and its expanded versions. `RC2_Generic`
171// ! ===> Moved to Roadmap for ver. 2.0
172//! - [X] DES symmetric-key encryption/decryption algorithm and the traits and its implementations of Operation modes and padding bits for DES_Generic
173//! --- Includes DES and its expanded versions, and ECB, CBC, PCBC, CFB, OFB, and CTR modes, and padding bits
174//! according to PKCS#7 and ISO 7816-4.
175//! [`DES_Generic`](symmetric/des/struct.DES_Generic.html#struct.DES_Generic)
176//! [`ECB_PKCS7`](symmetric/trait.ECB_PKCS7.html#trait.ECB_PKCS7),
177//! [`ECB_ISO`](symmetric/trait.ECB_ISO.html#trait.ECB_ISO),
178//! [`CBC_PKCS7`](symmetric/trait.CBC_PKCS7.html#trait.CBC_PKCS7),
179//! [`CBC_ISO`](symmetric/trait.CBC_ISO.html#trait.CBC_ISO),
180//! [`PCBC_PKCS7`](symmetric/trait.PCBC_PKCS7.html#trait.PCBC_PKCS7),
181//! [`PCBC_ISO`](symmetric/trait.PCBC_ISO.html#trait.PCBC_ISO),
182//! [`CFB`](symmetric/trait.CFB.html#trait.CFB),
183//! [`OFB`](symmetric/trait.OFB.html#trait.OFB), and
184//! [`CTR`](symmetric/trait.CTR.html#trait.CTR).
185// ! - [ ] Lucifer symmetric-key encryption/decryption algorithm
186// ! --- Includes Lucifer and its expanded versions. `Lucifer_Generic`
187// ! ===> Moved to Roadmap for ver. 2.0
188//! - [X] BigCryptor128 combinations of symmetric-key encryption/decryption algorithms and the trait implementations of Operation modes and padding bits for BigCryptor128
189//! --- Includes 2AES, 3AES, 4AES, etc., and their expanded versions, and
190//! ECB, CBC, PCBC, CFB, OFB, and CTR modes, and padding bits according to PKCS#7 and ISO 7816-4.
191//! [`BigCryptor128`](symmetric/big_cryptor/struct.BigCryptor128.html#struct.BigCryptor128)
192//! [`ECB_PKCS7`](symmetric/trait.ECB_PKCS7.html#trait.ECB_PKCS7),
193//! [`ECB_ISO`](symmetric/trait.ECB_ISO.html#trait.ECB_ISO),
194//! [`CBC_PKCS7`](symmetric/trait.CBC_PKCS7.html#trait.CBC_PKCS7),
195//! [`CBC_ISO`](symmetric/trait.CBC_ISO.html#trait.CBC_ISO),
196//! [`PCBC_PKCS7`](symmetric/trait.PCBC_PKCS7.html#trait.PCBC_PKCS7),
197//! [`PCBC_ISO`](symmetric/trait.PCBC_ISO.html#trait.PCBC_ISO),
198//! [`CFB`](symmetric/trait.CFB.html#trait.CFB),
199//! [`OFB`](symmetric/trait.OFB.html#trait.OFB), and
200//! [`CTR`](symmetric/trait.CTR.html#trait.CTR).
201//! However, it is considered that 2AES, 3AES, 4AES, etc. are not very meaningful because AES-256, Rijndael_128_384, Rijndael_128_512, etc. are considered to be better than 2AES, 3AES, 4AES, etc.
202//! - [X] BigCryptor64 combinations of symmetric-key encryption/decryption algorithms and the trait implementations of Operation modes and padding bits for BigCryptor64
203//! --- Includes 2DES, 3DES, 4DES, etc., and their expanded versions, and
204//! ECB, CBC, PCBC, CFB, OFB, and CTR modes, and padding bits according to PKCS#7 and ISO 7816-4.
205//! [`BigCryptor64`](symmetric/big_cryptor/struct.BigCryptor64.html#struct.BigCryptor64)
206//! [`ECB_PKCS7`](symmetric/trait.ECB_PKCS7.html#trait.ECB_PKCS7),
207//! [`ECB_ISO`](symmetric/trait.ECB_ISO.html#trait.ECB_ISO),
208//! [`CBC_PKCS7`](symmetric/trait.CBC_PKCS7.html#trait.CBC_PKCS7),
209//! [`CBC_ISO`](symmetric/trait.CBC_ISO.html#trait.CBC_ISO),
210//! [`PCBC_PKCS7`](symmetric/trait.PCBC_PKCS7.html#trait.PCBC_PKCS7),
211//! [`PCBC_ISO`](symmetric/trait.PCBC_ISO.html#trait.PCBC_ISO),
212//! [`CFB`](symmetric/trait.CFB.html#trait.CFB),
213//! [`OFB`](symmetric/trait.OFB.html#trait.OFB), and
214//! [`CTR`](symmetric/trait.CTR.html#trait.CTR).
215//!
216//! ## Pseudo-Random Number Generator Algorithms
217//! - [ ] Pseudo-random number generator --- struct
218//! [`Random_Generic`](random/random/struct.Random_Generic.html#struct.Random_Generic)
219//! and trait
220//! [Random_Engine](random/trait_random_engine/trait.Random_Engine.html#trait.Random_Engine)
221//! - [ ] Pseudo-random number generator engines using hash algorithms ---
222//! [`Random_BIG_KECCAK_1024`](random/random/struct.Random_BIG_KECCAK_1024.html#struct.Random_BIG_KECCAK_1024)
223//! [`Random_SHA3_512`](random/random/struct.Random_SHA3_512.html#struct.Random_SHA3_512),
224//! [`Random_SHA2_512`](random/random/struct.Random_SHA2_512.html#struct.Random_SHA2_512),
225//! [`Any_SHAKE_256`](random/random/struct.Any_SHAKE_256.html#struct.Any_SHAKE_256),
226//! [`Any_SHAKE_128`](random/random/struct.Any_SHAKE_128.html#struct.Any_SHAKE_128),
227//! [`Any_SHA3_512`](random/random/struct.Any_SHA3_512.html#struct.Any_SHA3_512),
228//! [`Any_SHA3_256`](random/random/struct.Any_SHA3_256.html#struct.Any_SHA3_256),
229//! [`Any_SHA2_512`](random/random/struct.Any_SHA2_512.html#struct.Any_SHA2_512),
230//! [`Any_SHA2_256`](random/random/struct.Any_SHA2_256.html#struct.Any_SHA2_256),
231//! [`Any_SHA1`](random/random/struct.Any_SHA1.html#struct.Any_SHA1),
232//! [`Any_SHA0`](random/random/struct.Any_SHA0.html#struct.Any_SHA0),
233//! [`Any_MD5`](random/random/struct.Any_MD5.html#struct.Any_MD5), and,
234//! [`Any_MD4`](random/random/struct.Any_MD4.html#struct.Any_MD4).
235//! - [ ] Pseudo-random number generator engines using symmetric-key encryption algorithms ---
236//! [`Random_Rijndael`](random/random/struct.Random_Rijndael.html#struct.Random_Rijndael),
237//! [`Any_Rijndael`](random/random/struct.Any_Rijndael.html#struct.Any_Rijndael), and
238//! [`Any_DES`](random/random/struct.Any_DES.html#struct.Any_DES).
239//! - [ ] Pseudo-random number generator engines using simple randomization algorithm
240//! --- [`Any_Num_C`](random/random/struct.Any_Num.html#struct.Any_Num_C)
241//!
242//! ## Asymmetric-Key Algorithms for the Encryption/Decryption of digital data
243//! - [ ] ECC (Elliptic Curve Cryptosystem)
244//! - [ ] RSA (Ron Rivest, Adi Shamir, Leonard Adleman)
245// ! - [ ] Rabin --> Moved to Roadmap for ver. 2.0
246// ! - [ ] ElGamal --> Moved to Roadmap for ver. 2.0
247// ! - [ ] Diffie-Hellman --> Thinking about postponing to Roadmap for ver. 2.0
248//!
249//! When the implementation of all the above functionalitis are completed,
250//! the version number 1.0.0.0 will be given. After that whenever another
251//! functionality is added to this crate, the version number will get higher
252//! beyond 1.0.0.0. Before the version number 1.0.0.0, the maximum version
253//! number will be 0.21.x.x since there are all twenty-five functionalities
254//! listed above. So, for example, even if the version number is 0.5.0.0,
255//! it does not mean that 50% of all functionalities are implemented.
256
257
258#![doc(
259 html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png",
260 html_favicon_url = "https://www.rust-lang.org/favicon.ico",
261 html_root_url = "https://rust-random.github.io/rand/"
262)]
263
264pub mod number;
265pub mod hash;
266pub mod symmetric;
267pub mod random;