chksum_sha2/lib.rs
1//! This crate provides an implementation of SHA-2 hash functions with a straightforward interface for computing digests of bytes, files, directories, and more.
2//!
3//! For a low-level interface, you can explore the [`chksum_hash_sha2`] crate.
4//!
5//! # Setup
6//!
7//! To use this crate, add the following entry to your `Cargo.toml` file in the `dependencies` section:
8//!
9//! ```toml
10//! [dependencies]
11//! chksum-sha2 = "0.1.0"
12//! ```
13//!
14//! Alternatively, you can use the [`cargo add`](https://doc.rust-lang.org/cargo/commands/cargo-add.html) subcommand:
15//!
16//! ```sh
17//! cargo add chksum-sha2
18//! ```
19//!
20//! # Usage
21//!
22//! Use the [`chksum`] function to calculate digest of file, directory and so on.
23//!
24//! ```rust
25//! # use std::path::Path;
26//! use std::fs::File;
27//!
28//! # use chksum_sha2::sha2_256::Result;
29//! use chksum_sha2::sha2_256;
30//!
31//! # fn wrapper(path: &Path) -> Result<()> {
32//! let file = File::open(path)?;
33//! let digest = sha2_256::chksum(file)?;
34//! assert_eq!(
35//! digest.to_hex_lowercase(),
36//! "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
37//! );
38//! # Ok(())
39//! # }
40//! ```
41//!
42//! ## Asynchronous Runtime
43//!
44//! Use the [`async_chksum`] function to calculate digest of file, directory and so on.
45//!
46//! ```rust
47//! # #[cfg(feature = "async-runtime-tokio")]
48//! # {
49//! # use std::path::Path;
50//! # use chksum_sha2::sha2_256::Result;
51//! use chksum_sha2::sha2_256;
52//! use tokio::fs::File;
53//!
54//! # async fn wrapper(path: &Path) -> Result<()> {
55//! let file = File::open(path).await?;
56//! let digest = sha2_256::async_chksum(file).await?;
57//! assert_eq!(
58//! digest.to_hex_lowercase(),
59//! "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
60//! );
61//! # Ok(())
62//! # }
63//! # }
64//! ```
65//!
66//! # Input Types
67//!
68//! ## Bytes
69//!
70//! ### Array
71//!
72//! ```rust
73//! # use chksum_sha2::sha2_256::Result;
74//! use chksum_sha2::sha2_256;
75//!
76//! # fn wrapper() -> Result<()> {
77//! let data = [0, 1, 2, 3];
78//! let digest = sha2_256::chksum(data)?;
79//! assert_eq!(
80//! digest.to_hex_lowercase(),
81//! "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
82//! );
83//! # Ok(())
84//! # }
85//! ```
86//!
87//! ### Vec
88//!
89//! ```rust
90//! # use chksum_sha2::sha2_256::Result;
91//! use chksum_sha2::sha2_256;
92//!
93//! # fn wrapper() -> Result<()> {
94//! let data = vec![0, 1, 2, 3];
95//! let digest = sha2_256::chksum(data)?;
96//! assert_eq!(
97//! digest.to_hex_lowercase(),
98//! "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
99//! );
100//! # Ok(())
101//! # }
102//! ```
103//!
104//! ### Slice
105//!
106//! ```rust
107//! # use chksum_sha2::sha2_256::Result;
108//! use chksum_sha2::sha2_256;
109//!
110//! # fn wrapper() -> Result<()> {
111//! let data = &[0, 1, 2, 3];
112//! let digest = sha2_256::chksum(data)?;
113//! assert_eq!(
114//! digest.to_hex_lowercase(),
115//! "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
116//! );
117//! # Ok(())
118//! # }
119//! ```
120//!
121//! ## Strings
122//!
123//! ### str
124//!
125//! ```rust
126//! # use chksum_sha2::sha2_256::Result;
127//! use chksum_sha2::sha2_256;
128//!
129//! # fn wrapper() -> Result<()> {
130//! let data = "&str";
131//! let digest = sha2_256::chksum(data)?;
132//! assert_eq!(
133//! digest.to_hex_lowercase(),
134//! "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
135//! );
136//! # Ok(())
137//! # }
138//! ```
139//!
140//! ### String
141//!
142//! ```rust
143//! # use chksum_sha2::sha2_256::Result;
144//! use chksum_sha2::sha2_256;
145//!
146//! # fn wrapper() -> Result<()> {
147//! let data = String::from("String");
148//! let digest = sha2_256::chksum(data)?;
149//! assert_eq!(
150//! digest.to_hex_lowercase(),
151//! "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
152//! );
153//! # Ok(())
154//! # }
155//! ```
156//!
157//! ## File
158//!
159//! ```rust
160//! # use std::path::Path;
161//! use std::fs::File;
162//!
163//! # use chksum_sha2::sha2_256::Result;
164//! use chksum_sha2::sha2_256;
165//!
166//! # fn wrapper(path: &Path) -> Result<()> {
167//! let file = File::open(path)?;
168//! let digest = sha2_256::chksum(file)?;
169//! assert_eq!(
170//! digest.to_hex_lowercase(),
171//! "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
172//! );
173//! # Ok(())
174//! # }
175//! ```
176//!
177//! ## Directory
178//!
179//! ```rust
180//! # use std::path::Path;
181//! use std::fs::read_dir;
182//!
183//! # use chksum_sha2::sha2_256::Result;
184//! use chksum_sha2::sha2_256;
185//!
186//! # fn wrapper(path: &Path) -> Result<()> {
187//! let readdir = read_dir(path)?;
188//! let digest = sha2_256::chksum(readdir)?;
189//! assert_eq!(
190//! digest.to_hex_lowercase(),
191//! "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
192//! );
193//! # Ok(())
194//! # }
195//! ```
196//!
197//! ## Path
198//!
199//! ```rust
200//! # use std::path::Path;
201//! use std::path::PathBuf;
202//!
203//! # use chksum_sha2::sha2_256::Result;
204//! use chksum_sha2::sha2_256;
205//!
206//! # fn wrapper(path: &Path) -> Result<()> {
207//! let path = PathBuf::from(path);
208//! let digest = sha2_256::chksum(path)?;
209//! assert_eq!(
210//! digest.to_hex_lowercase(),
211//! "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
212//! );
213//! # Ok(())
214//! # }
215//! ```
216//!
217//! ## Standard Input
218//!
219//! ```rust
220//! use std::io::stdin;
221//!
222//! # use chksum_sha2::sha2_256::Result;
223//! use chksum_sha2::sha2_256;
224//!
225//! # fn wrapper() -> Result<()> {
226//! let stdin = stdin();
227//! let digest = sha2_256::chksum(stdin)?;
228//! assert_eq!(
229//! digest.to_hex_lowercase(),
230//! "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
231//! );
232//! # Ok(())
233//! # }
234//! ```
235//!
236//! # Algorithms
237//!
238//! ## SHA-2 224
239//!
240//! ```rust
241//! # use std::path::Path;
242//! use std::fs::File;
243//!
244//! # use chksum_sha2::sha2_224::Result;
245//! use chksum_sha2::sha2_224;
246//!
247//! # fn wrapper(path: &Path) -> Result<()> {
248//! let file = File::open(path)?;
249//! let digest = sha2_224::chksum(file)?;
250//! assert_eq!(
251//! digest.to_hex_lowercase(),
252//! "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced"
253//! );
254//! # Ok(())
255//! # }
256//! ```
257//!
258//! ## SHA-2 256
259//!
260//! ```rust
261//! # use std::path::Path;
262//! use std::fs::File;
263//!
264//! # use chksum_sha2::sha2_256::Result;
265//! use chksum_sha2::sha2_256;
266//!
267//! # fn wrapper(path: &Path) -> Result<()> {
268//! let file = File::open(path)?;
269//! let digest = sha2_256::chksum(file)?;
270//! assert_eq!(
271//! digest.to_hex_lowercase(),
272//! "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061"
273//! );
274//! # Ok(())
275//! # }
276//! ```
277//!
278//! ## SHA-2 384
279//!
280//! ```rust
281//! # use std::path::Path;
282//! use std::fs::File;
283//!
284//! # use chksum_sha2::sha2_384::Result;
285//! use chksum_sha2::sha2_384;
286//!
287//! # fn wrapper(path: &Path) -> Result<()> {
288//! let file = File::open(path)?;
289//! let digest = sha2_384::chksum(file)?;
290//! assert_eq!(
291//! digest.to_hex_lowercase(),
292//! "12ecdfd463a85a301b7c29a43bf4b19cdfc6e5e86a5f40396aa6ae3368a7e5b0ed31f3bef2eb3071577ba610b4ed1cb8"
293//! );
294//! # Ok(())
295//! # }
296//! ```
297//!
298//! ## SHA-2 512
299//!
300//! ```rust
301//! # use std::path::Path;
302//! use std::fs::File;
303//!
304//! # use chksum_sha2::sha2_512::Result;
305//! use chksum_sha2::sha2_512;
306//!
307//! # fn wrapper(path: &Path) -> Result<()> {
308//! let file = File::open(path)?;
309//! let digest = sha2_512::chksum(file)?;
310//! assert_eq!(
311//! digest.to_hex_lowercase(),
312//! "ed59c5759a9ece516cec0c0623142d0e9fe70a27d750eee7fd38f4550d50addd873d0fa1a51fc823c1e3d5cada203f4a05d8325caacb7d3e0727a701f3f07e5f"
313//! );
314//! # Ok(())
315//! # }
316//! ```
317//!
318//! # Features
319//!
320//! ## Algorithms
321//!
322//! Cargo features are utilized to enable or disable specific SHA-2 algorithm variants.
323//!
324//! * `224` enables SHA-2 224, accessible via the [`sha2_224`] module.
325//! * `256` enables SHA-2 256, accessible via the [`sha2_256`] module.
326//! * `384` enables SHA-2 384, accessible via the [`sha2_384`] module.
327//! * `512` enables SHA-2 512, accessible via the [`sha2_512`] module.
328//!
329//! By default, all of these features are enabled.
330//!
331//! To customize your setup, disable the default features and enable only those that you need in your `Cargo.toml` file:
332//!
333//! ```toml
334//! [dependencies]
335//! chksum-sha2 = { version = "0.1.0", default-features = false, features = ["256", "512"] }
336//! ```
337//!
338//! Alternatively, you can use the [`cargo add`](https://doc.rust-lang.org/cargo/commands/cargo-add.html) subcommand:
339//!
340//! ```shell
341//! cargo add chksum-sha2 --no-default-features --features 256,512
342//! ```
343//!
344//! ## Extra Options
345//!
346//! Cargo features are also utilized to enable extra options.
347//!
348//! * `reader` enables the `reader` module with the `Reader` struct within each variant module.
349//! * `writer` enables the `writer` module with the `Writer` struct within each variant module.
350//!
351//! By default, neither of these features is enabled.
352//!
353//! To customize your setup, disable the default features and enable only those that you need in your `Cargo.toml` file:
354//!
355//! ```toml
356//! [dependencies]
357//! chksum-sha2 = { version = "0.1.0", features = ["reader", "writer"] }
358//! ```
359//!
360//! Alternatively, you can use the [`cargo add`](https://doc.rust-lang.org/cargo/commands/cargo-add.html) subcommand:
361//!
362//! ```shell
363//! cargo add chksum-sha2 --features reader,writer
364//! ```
365//!
366//! ## Asynchronous Runtime
367//!
368//! * `async-runtime-tokio`: Enables async interface for Tokio runtime.
369//!
370//! By default, neither of these features is enabled.
371//!
372//! # License
373//!
374//! This crate is licensed under the MIT License.
375
376#![cfg_attr(docsrs, feature(doc_auto_cfg))]
377#![forbid(unsafe_code)]
378
379#[cfg(feature = "async-runtime-tokio")]
380#[doc(no_inline)]
381pub use chksum_core::async_chksum;
382#[doc(no_inline)]
383pub use chksum_core::{chksum, Digest, Error, Hash, Result};
384#[doc(no_inline)]
385pub use chksum_hash_sha2 as hash;
386#[cfg(feature = "224")]
387#[doc(no_inline)]
388pub use chksum_sha2_224 as sha2_224;
389#[cfg(feature = "224")]
390#[doc(no_inline)]
391pub use chksum_sha2_224::SHA2_224;
392#[cfg(feature = "256")]
393#[doc(no_inline)]
394pub use chksum_sha2_256 as sha2_256;
395#[cfg(feature = "256")]
396#[doc(no_inline)]
397pub use chksum_sha2_256::SHA2_256;
398#[cfg(feature = "384")]
399#[doc(no_inline)]
400pub use chksum_sha2_384 as sha2_384;
401#[cfg(feature = "384")]
402#[doc(no_inline)]
403pub use chksum_sha2_384::SHA2_384;
404#[cfg(feature = "512")]
405#[doc(no_inline)]
406pub use chksum_sha2_512 as sha2_512;
407#[cfg(feature = "512")]
408#[doc(no_inline)]
409pub use chksum_sha2_512::SHA2_512;