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//! ## 1. 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//! ## 2. 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//! ## 3. Hash Algorithms
75//! ### 3-1. Official SHA-series
76//! - [X] SHA-3 and Keccak hash algorithms based on 8/16/32/64 bits
77//! --- Includes SHA3-224, SHA3-256, SHA3-384, SHA3-512, SHAKE 128, SHAKE 256, cSHAKE-128, cSHAKE-256, Keccak family and their expanded versions.
78//! [`Keccak_Generic`](hash/keccak/struct.Keccak_Generic.html#struct.Keccak_Generic)
79//! - [X] SHA-2 hash algorithms based on 512/t bits
80//! --- Includes 512/256, SHA-512/224, and their expanded versions.
81//! [`SHA2_512_t_Generic`](hash/sha2_512_t/struct.SHA2_512_t_Generic.html#struct.SHA2_512_t_Generic)
82//! - [X] SHA-2 hash algorithms based on 512 bits
83//! --- Includes SHA-512, SHA-384, SHA-512/256, and their expanded versions.
84//! [`SHA2_512_Generic`](hash/sha2_512/struct.SHA2_512_Generic.html#struct.SHA2_512_Generic)
85//! - [X] SHA-2 hash algorithms based on 256 bits
86//! --- Includes SHA-256, SHA-224, and their expanded versions.
87//! [`SHA2_256_Generic`](hash/sha2_256/struct.SHA2_256_Generic.html#struct.SHA2_256_Generic)
88//!
89//! ### 3-2. Insecure Hash algorithms ONLY for educational purposes
90//! - [X] SHA-1 hash algorithms based on 160 bits
91//! --- Includes SHA-1, SHA-0, and their expanded versions.
92//! [`SHA1_Generic`](hash/sha1/struct.SHA1_Generic.html#struct.SHA1_Generic)
93// ! - [ ] RIPEMD hash algorithms based on 256 bits
94// ! --- Includes RIPEMD and its expanded versions.
95// ! ===> Moved to Roadmap for ver. 2.0
96// ! - [ ] BLAKE3 hash algorithms based on 256 bits
97// ! --- Includes BLAKE3 and its expanded versions.
98// ! ===> Moved to Roadmap for ver. 2.0
99// ! - [ ] BLAKE2 hash algorithms based on 256 bits
100// ! --- Includes BLAKE2 and its expanded versions.
101// ! ===> Moved to Roadmap for ver. 2.0
102// ! - [ ] MD6 hash algorithms based on 256 bits
103// ! --- Includes MD4 and its expanded versions.
104// ! ===> Moved to Roadmap for ver. 2.0
105//! - [X] MD5 hash algorithms based on 128 bits
106//! --- Includes MD5 and its expanded versions.
107//! [`MD5_Generic`](hash/md5/struct.MD5_Generic.html#struct.MD5_Generic)
108//! - [X] MD4 hash algorithms based on 128 bits
109//! --- Includes MD4 and its expanded versions.
110//! [`MD4_Generic`](hash/md4/struct.MD4_Generic.html#struct.MD4_Generic)
111// ! - [ ] MD2 hash algorithms based on 128 bits
112// ! --- Includes MD4 and its expanded versions.
113// ! ===> Moved to Roadmap for ver. 2.0
114//!
115//! ## 4. Symmetric-key Algorithms for Block Encryption/Decryption of digital data
116//! ### 4-1. AES Finalists
117//! - [X] AES (Advanced Encryption Standard) and Rijndael symmetric-key encryption/decryption algorithm, and the trait implementations of Operation modes and Padding bits for AES_Generic
118//! --- Includes AES and its expanded versions, and ECB, CBC, PCBC, CFB, OFB, and CTR modes, and padding bits
119//! according to PKCS#7 and ISO 7816-4.
120//! [`Rijndael_Generic`](symmetric/struct.Rijndael_Generic.html#struct.Rijndael_Generic),
121//! [`ECB_PKCS7`](symmetric/trait.ECB_PKCS7.html#trait.ECB_PKCS7),
122//! [`ECB_ISO`](symmetric/trait.ECB_ISO.html#trait.ECB_ISO),
123//! [`CBC_PKCS7`](symmetric/trait.CBC_PKCS7.html#trait.ECB_PKCS7),
124//! [`CBC_ISO`](symmetric/trait.CBC_ISO.html#trait.CBC_ISO),
125//! [`PCBC_PKCS7`](symmetric/trait.PCBC_PKCS7.html#trait.PCBC_PKCS7),
126//! [`PCBC_ISO`](symmetric/trait.PCBC_ISO.html#trait.PCBC_ISO),
127//! [`CFB`](symmetric/trait.CFB.html#trait.CFB),
128//! [`OFB`](symmetric/trait.OFB.html#trait.OFB), and
129//! [`CTR`](symmetric/trait.CTR.html#trait.CTR).
130//! (symmetric/aes/struct.AES_Generic.html#struct.AES_Generic)
131// ! - [ ] MARS symmetric-key encryption/decryption algorithm
132// ! --- Includes MARS and its expanded versions. `MARS_Generic`
133// ! ===> Moved to Roadmap for ver. 2.0
134// ! - [ ] Serpent symmetric-key encryption/decryption algorithm
135// ! --- Includes RC6 and its expanded versions. `RC6_Generic`
136// ! ===> Moved to Roadmap for ver. 2.0
137// ! - [ ] Twofish symmetric-key encryption/decryption algorithm
138// ! --- Includes Twofish and its expanded versions. `Twofish_Generic`
139// ! ===> Moved to Roadmap for ver. 2.0
140// ! - [ ] RC6 symmetric-key encryption/decryption algorithm
141// ! --- Includes RC6 and its expanded versions. `RC6_Generic`
142// ! ===> Moved to Roadmap for ver. 2.0
143// !
144// ! ### South Korean Encryption/Decryption algorithms
145// ! - [ ] SEED symmetric-key encryption/decryption algorithm
146// ! --- Includes SEED and its expanded versions. `SEED_Generic`
147// ! ===> Moved to Roadmap for ver. 2.0
148// ! - [ ] HIGHT symmetric-key encryption/decryption algorithm
149// ! --- Includes HIGHT and its expanded versions. `HIGHT_Generic`
150// ! ===> Moved to Roadmap for ver. 2.0
151// ! - [ ] ARIA symmetric-key encryption/decryption algorithm
152// ! --- Includes ARIA and its expanded versions. `ARIA_Generic`
153// ! ===> Moved to Roadmap for ver. 2.0
154// ! - [ ] LEA symmetric-key encryption/decryption algorithm
155// ! --- Includes LEA and its expanded versions. `LEA_Generic`
156// ! ===> Moved to Roadmap for ver. 2.0
157// ! - [ ] IDEA symmetric-key encryption/decryption algorithm
158// ! --- Includes IDEA and its expanded versions. `IDEA_Generic`
159// ! ===> Moved to Roadmap for ver. 2.0
160// !
161// ! ### Miscellaneous Encryption/Decryption algorithms
162// ! - [ ] Bluefish symmetric-key encryption/decryption algorithm
163// ! --- Includes Bluefish and its expanded versions. `Bluefish_Generic`
164// ! ===> Moved to Roadmap for ver. 2.0
165// ! - [ ] RC5 symmetric-key encryption/decryption algorithm
166// ! --- Includes RC5 and its expanded versions. `RC5_Generic`
167// ! ===> Moved to Roadmap for ver. 2.0
168// !
169//! ### 4-2. Insecure Block Encryption/Decryption algorithms
170// ! - [ ] RC4 symmetric-key encryption/decryption algorithm
171// ! --- Includes RC4 and its expanded versions. `RC4_Generic`
172// ! ===> Moved to Roadmap for ver. 2.0
173// ! - [ ] RC2 symmetric-key encryption/decryption algorithm
174// ! --- Includes RC2 and its expanded versions. `RC2_Generic`
175// ! ===> Moved to Roadmap for ver. 2.0
176//! - [X] DES (Data Encryption Standard) symmetric-key encryption/decryption algorithm, and the traits and its implementations of Operation modes and Padding bits for DES_Generic
177//! --- Includes DES and its expanded versions, and ECB, CBC, PCBC, CFB, OFB, and CTR modes, and padding bits
178//! according to PKCS#7 and ISO 7816-4.
179//! [`DES_Generic`](symmetric/struct.DES_Generic.html#struct.DES_Generic)
180//! [`ECB_PKCS7`](symmetric/trait.ECB_PKCS7.html#trait.ECB_PKCS7),
181//! [`ECB_ISO`](symmetric/trait.ECB_ISO.html#trait.ECB_ISO),
182//! [`CBC_PKCS7`](symmetric/trait.CBC_PKCS7.html#trait.CBC_PKCS7),
183//! [`CBC_ISO`](symmetric/trait.CBC_ISO.html#trait.CBC_ISO),
184//! [`PCBC_PKCS7`](symmetric/trait.PCBC_PKCS7.html#trait.PCBC_PKCS7),
185//! [`PCBC_ISO`](symmetric/trait.PCBC_ISO.html#trait.PCBC_ISO),
186//! [`CFB`](symmetric/trait.CFB.html#trait.CFB),
187//! [`OFB`](symmetric/trait.OFB.html#trait.OFB), and
188//! [`CTR`](symmetric/trait.CTR.html#trait.CTR).
189// ! - [ ] Lucifer symmetric-key encryption/decryption algorithm
190// ! --- Includes Lucifer and its expanded versions. `Lucifer_Generic`
191// ! ===> Moved to Roadmap for ver. 2.0
192// !
193//! ### 4-3. Containers for combining encryption/decryption algorithms
194//! - [X] BigCryptor128 combinations of symmetric-key encryption/decryption algorithms, and the trait implementations of Operation modes and Padding bits for BigCryptor128
195//! --- Includes 2AES, 3AES, 4AES, etc., and their expanded versions, and
196//! ECB, CBC, PCBC, CFB, OFB, and CTR modes, and padding bits according to PKCS#7 and ISO 7816-4.
197//! [`BigCryptor128`](symmetric/struct.BigCryptor128.html#struct.BigCryptor128)
198//! [`ECB_PKCS7`](symmetric/trait.ECB_PKCS7.html#trait.ECB_PKCS7),
199//! [`ECB_ISO`](symmetric/trait.ECB_ISO.html#trait.ECB_ISO),
200//! [`CBC_PKCS7`](symmetric/trait.CBC_PKCS7.html#trait.CBC_PKCS7),
201//! [`CBC_ISO`](symmetric/trait.CBC_ISO.html#trait.CBC_ISO),
202//! [`PCBC_PKCS7`](symmetric/trait.PCBC_PKCS7.html#trait.PCBC_PKCS7),
203//! [`PCBC_ISO`](symmetric/trait.PCBC_ISO.html#trait.PCBC_ISO),
204//! [`CFB`](symmetric/trait.CFB.html#trait.CFB),
205//! [`OFB`](symmetric/trait.OFB.html#trait.OFB), and
206//! [`CTR`](symmetric/trait.CTR.html#trait.CTR).
207//! 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.
208//! - [X] BigCryptor64 combinations of symmetric-key encryption/decryption algorithms, and the trait implementations of Operation modes and Padding bits for BigCryptor64
209//! --- Includes 2DES, 3DES, 4DES, etc., and their expanded versions, and
210//! ECB, CBC, PCBC, CFB, OFB, and CTR modes, and padding bits according to PKCS#7 and ISO 7816-4.
211//! [`BigCryptor64`](symmetric/struct.BigCryptor64.html#struct.BigCryptor64)
212//! [`ECB_PKCS7`](symmetric/trait.ECB_PKCS7.html#trait.ECB_PKCS7),
213//! [`ECB_ISO`](symmetric/trait.ECB_ISO.html#trait.ECB_ISO),
214//! [`CBC_PKCS7`](symmetric/trait.CBC_PKCS7.html#trait.CBC_PKCS7),
215//! [`CBC_ISO`](symmetric/trait.CBC_ISO.html#trait.CBC_ISO),
216//! [`PCBC_PKCS7`](symmetric/trait.PCBC_PKCS7.html#trait.PCBC_PKCS7),
217//! [`PCBC_ISO`](symmetric/trait.PCBC_ISO.html#trait.PCBC_ISO),
218//! [`CFB`](symmetric/trait.CFB.html#trait.CFB),
219//! [`OFB`](symmetric/trait.OFB.html#trait.OFB), and
220//! [`CTR`](symmetric/trait.CTR.html#trait.CTR).
221//!
222// ! ### Symmetric-key Algorithms for Stream Encryption/Decryption of digital data
223// ! - [ ] Chacha20 symmetric-key encryption/decryption algorithm
224// ! --- Includes Chacha20 and its expanded versions. `Chacha20_Generic`
225// ! ===> Moved to Roadmap for ver. 2.0
226// ! - [ ] Salsa20 symmetric-key encryption/decryption algorithm
227// ! --- Includes Salsa20 and its expanded versions. `Salsa20_Generic`
228// ! ===> Moved to Roadmap for ver. 2.0
229// !
230// ! ### Insecure Stream Encryption/Decryption algorithms
231// !- [ ] RC4 symmetric-key encryption/decryption algorithm
232// ! --- Includes RC4 and its expanded versions. `RC4_Generic`
233// ! ===> Moved to Roadmap for ver. 2.0
234// !
235//! ## 5. Pseudo-Random Number Generator Algorithms
236//! - [X] Pseudo-random number generator --- struct
237//! [`Random_Generic`](random/struct.Random_Generic.html#struct.Random_Generic)
238//! and trait
239//! [Random_Engine](random/trait_random_engine/trait.Random_Engine.html#trait.Random_Engine)
240//! - [X] Pseudo-random number generator engines using hash algorithms ---
241//! [`Random_BIG_KECCAK_1024`](random/struct.Random_BIG_KECCAK_1024.html#struct.Random_BIG_KECCAK_1024)
242//! [`Random_SHA3_512`](random/struct.Random_SHA3_512.html#struct.Random_SHA3_512),
243//! [`Random_SHA2_512`](random/struct.Random_SHA2_512.html#struct.Random_SHA2_512),
244//! [`Any_SHAKE_256`](random/struct.Any_SHAKE_256.html#struct.Any_SHAKE_256),
245//! [`Any_SHAKE_128`](random/struct.Any_SHAKE_128.html#struct.Any_SHAKE_128),
246//! [`Any_SHA3_512`](random/struct.Any_SHA3_512.html#struct.Any_SHA3_512),
247//! [`Any_SHA3_256`](random/struct.Any_SHA3_256.html#struct.Any_SHA3_256),
248//! [`Any_SHA2_512`](random/struct.Any_SHA2_512.html#struct.Any_SHA2_512),
249//! [`Any_SHA2_256`](random/struct.Any_SHA2_256.html#struct.Any_SHA2_256),
250//! [`Slapdash_SHA1`](random/struct.Slapdash_SHA1.html#struct.Slapdash_SHA1),
251//! [`Slapdash_SHA0`](random/struct.Slapdash_SHA0.html#struct.Slapdash_SHA0),
252//! [`Slapdash_MD5`](random/struct.Slapdash_MD5.html#struct.Slapdash_MD5), and,
253//! [`Slapdash_MD4`](random/struct.Slapdash_MD4.html#struct.Slapdash_MD4).
254//! - [X] Pseudo-random number generator engines using symmetric-key block encryption algorithms ---
255//! [`Random_Rijndael`](random/struct.Random_Rijndael.html#struct.Random_Rijndael),
256//! [`Any_Rijndael`](random/struct.Any_Rijndael.html#struct.Any_Rijndael), and
257//! [`Slapdash_DES`](random/struct.Slapdash_DES.html#struct.Slapdash_DES).
258//! - [X] Pseudo-random number generator engines using simple randomization algorithm
259//! --- [`Slapdash_Num_C`](random/struct.Slapdash_Num.html#struct.Slapdash_Num_C).
260//!
261//! ## 6. Asymmetric-Key Algorithms for Encryption/Decryption of digital data
262//! - [ ] ECC (Elliptic Curve Cryptosystem)
263//! - [ ] RSA (Ron Rivest, Adi Shamir, Leonard Adleman) asymmetric-key encryption/decryption algorithm, and the traits and its implementations of Padding bits for RSA_Generic
264//! --- Includes RSA and its expanded versions, and Padding bits according to PKCS #1 ver. 1.5 and OAEP (Optimal Asymmetric Encryption Padding) according to PKCS #1 ver. 2.0 and RFC 2437.
265//! [`RSA_Generic`](asymmetric/struct.RSA_Generic.html#struct.RSA_Generic),
266//! [`PKCS1V15`](asymmetric/trait.PKCS1V15.html#trait.PKCS1V15), and
267//! OAEP.
268// ! - [ ] Rabin --> Moved to Roadmap for ver. 2.0
269// ! - [ ] ElGamal --> Moved to Roadmap for ver. 2.0
270// ! - [ ] Diffie-Hellman --> Thinking about postponing to Roadmap for ver. 2.0
271//!
272//! When the implementation of all the above functionalitis are completed,
273//! the version number 1.0.0.0 will be given. After that whenever another
274//! functionality is added to this crate, the version number will get higher
275//! beyond 1.0.0.0. Before the version number 1.0.0.0, the maximum version
276//! number will be 0.21.x.x since there are all twenty-five functionalities
277//! listed above. So, for example, even if the version number is 0.5.0.0,
278//! it does not mean that 50% of all functionalities are implemented.
279
280
281#![doc(
282 html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png",
283 html_favicon_url = "https://www.rust-lang.org/favicon.ico",
284 html_root_url = "https://rust-random.github.io/rand/"
285)]
286
287pub mod number;
288pub mod hash;
289pub mod symmetric;
290pub mod random;
291pub mod asymmetric;
292pub(crate) mod concurrency;