chksum_hash/
lib.rs

1//! This crate provides an implementation of various hash functions.
2//!
3//! # Setup
4//!
5//! To use this crate, add the following entry to your `Cargo.toml` file in the `dependencies` section:
6//!
7//! ```toml
8//! [dependencies]
9//! chksum-hash = "0.5.1"
10//! ```
11//!
12//! Alternatively, you can use the [`cargo add`](https://doc.rust-lang.org/cargo/commands/cargo-add.html) subcommand:
13//!
14//! ```sh
15//! cargo add chksum-hash
16//! ```     
17//!
18//! # Batch Processing
19//!
20//! The digest of known-size data can be calculated with the `hash` function.
21//!
22//! ```rust
23//! use chksum_hash::sha2_224;
24//!
25//! let digest = sha2_224::hash("example data");
26//! assert_eq!(
27//!     digest.to_hex_lowercase(),
28//!     "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
29//! );
30//! ```
31//!
32//! # Stream Processing
33//!
34//! The digest of data streams can be calculated chunk-by-chunk with a consumer created by calling the `default` function.
35//!
36//! ```rust
37//! // Import all necessary items
38//! # use std::io;
39//! # use std::path::PathBuf;
40//! use std::fs::File;
41//! use std::io::Read;
42//!
43//! use chksum_hash::sha2_384;
44//!
45//! # fn wrapper(path: PathBuf) -> io::Result<()> {
46//! // Create a hash instance
47//! let mut hash = sha2_384::default();
48//!
49//! // Open a file and create a buffer for incoming data
50//! let mut file = File::open(path)?;
51//! let mut buffer = vec![0; 64];
52//!
53//! // Iterate chunk by chunk
54//! while let Ok(count) = file.read(&mut buffer) {
55//!     // EOF reached, exit loop
56//!     if count == 0 {
57//!         break;
58//!     }
59//!
60//!     // Update the hash with data
61//!     hash.update(&buffer[..count]);
62//! }
63//!
64//! // Calculate the digest
65//! let digest = hash.digest();
66//! // Cast the digest to hex and compare
67//! assert_eq!(
68//!     digest.to_hex_lowercase(),
69//!     "12ecdfd463a85a301b7c29a43bf4b19cdfc6e5e86a5f40396aa6ae3368a7e5b0ed31f3bef2eb3071577ba610b4ed1cb8"
70//! );
71//! # Ok(())
72//! # }
73//! ```
74//!
75//! # Algorithms
76//!
77//! ## MD5
78//!
79//! ```rust
80//! use chksum_hash::md5;
81//!
82//! let digest = md5::hash("example data");
83//! assert_eq!(
84//!     digest.to_hex_lowercase(),
85//!     "5c71dbb287630d65ca93764c34d9aa0d"
86//! );
87//! ```
88//!
89//! ## SHA-1
90//!
91//! ```rust
92//! use chksum_hash::sha1;
93//!
94//! let digest = sha1::hash("example data");
95//! assert_eq!(
96//!     digest.to_hex_lowercase(),
97//!     "9fc42adac31303d68b444e6129f13f6093a0e045"
98//! );
99//! ```
100//!
101//! ## SHA-2 224
102//!
103//! ```rust
104//! use chksum_hash::sha2_224;
105//!
106//! let digest = sha2_224::hash("example data");
107//! assert_eq!(
108//!     digest.to_hex_lowercase(),
109//!     "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
110//! );
111//! ```
112//!
113//! ## SHA-2 256
114//!
115//! ```rust
116//! use chksum_hash::sha2_256;
117//!
118//! let digest = sha2_256::hash("example data");
119//! assert_eq!(
120//!     digest.to_hex_lowercase(),
121//!     "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
122//! );
123//! ```
124//!
125//! ## SHA-2 384
126//!
127//! ```rust
128//! use chksum_hash::sha2_384;
129//!
130//! let digest = sha2_384::hash("example data");
131//! assert_eq!(
132//!     digest.to_hex_lowercase(),
133//!     "12ecdfd463a85a301b7c29a43bf4b19cdfc6e5e86a5f40396aa6ae3368a7e5b0ed31f3bef2eb3071577ba610b4ed1cb8"
134//! );
135//! ```
136//!
137//! ## SHA-2 512
138//!
139//! ```rust
140//! use chksum_hash::sha2_512;
141//!
142//! let digest = sha2_512::hash("example data");
143//! assert_eq!(
144//!     digest.to_hex_lowercase(),
145//!     "ed59c5759a9ece516cec0c0623142d0e9fe70a27d750eee7fd38f4550d50addd873d0fa1a51fc823c1e3d5cada203f4a05d8325caacb7d3e0727a701f3f07e5f"
146//! );
147//! ```
148//!
149//! # Features
150//!
151//! Cargo features are utilized to enable or disable specific hash algorithms.
152//!
153//! * `md5` enables MD5, accessible via the [`md5`] module.
154//! * `sha1` enables SHA-1, accessible via the [`sha1`] module.
155//! * `sha2-224` enables SHA-2 224, accessible via the [`sha2_224`] module.
156//! * `sha2-256` enables SHA-2 256, accessible via the [`sha2_256`] module.
157//! * `sha2-384` enables SHA-2 384, accessible via the [`sha2_384`] module.
158//! * `sha2-512` enables SHA-2 512, accessible via the [`sha2_512`] module.
159//!
160//! By default, all of these features are enabled.
161//!
162//! To customize your setup, disable the default features and enable only those that you need in your `Cargo.toml` file:
163//!
164//! ```toml
165//! [dependencies]
166//! chksum-hash = { version = "0.5.1", default-features = false, features = ["md5", "sha2-512"] }
167//! ```
168//!
169//! Alternatively, you can use the [`cargo add`](https://doc.rust-lang.org/cargo/commands/cargo-add.html) subcommand:
170//!
171//! ```shell
172//! cargo add chksum-hash --no-default-features --features sha1,sha2-512
173//! ```
174//!
175//! # License
176//!
177//! This crate is licensed under the MIT License.
178
179#![cfg_attr(docsrs, feature(doc_auto_cfg))]
180#![forbid(unsafe_code)]
181
182#[doc(no_inline)]
183pub use chksum_hash_core::{default, hash, Digest, Finalize, Update};
184#[cfg(feature = "md5")]
185#[doc(no_inline)]
186pub use chksum_hash_md5 as md5;
187#[cfg(feature = "sha1")]
188#[doc(no_inline)]
189pub use chksum_hash_sha1 as sha1;
190#[cfg(feature = "sha2-224")]
191#[doc(no_inline)]
192pub use chksum_hash_sha2::sha2_224;
193#[cfg(feature = "sha2-256")]
194#[doc(no_inline)]
195pub use chksum_hash_sha2::sha2_256;
196#[cfg(feature = "sha2-384")]
197#[doc(no_inline)]
198pub use chksum_hash_sha2::sha2_384;
199#[cfg(feature = "sha2-512")]
200#[doc(no_inline)]
201pub use chksum_hash_sha2::sha2_512;
chksum_hash/lib.rs

chksum_hash/
lib.rs
