From 7e82c3441ce8032708a469ec3144df26da5861e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Konrad=20Go=C5=82awski?= Date: Thu, 21 Dec 2023 16:11:36 +0100 Subject: [PATCH] Initial commit --- .cargo/README.md | 86 +++++++++++++++++++ .github/workflows/rust.yml | 140 +++++++++++++++++++++++++++++++ .gitignore | 3 + CHANGELOG.md | 14 ++++ Cargo.toml | 29 +++++++ LICENSE | 21 +++++ README.md | 86 +++++++++++++++++++ rustfmt.toml | 17 ++++ src/lib.rs | 167 +++++++++++++++++++++++++++++++++++++ 9 files changed, 563 insertions(+) create mode 100644 .cargo/README.md create mode 100644 .github/workflows/rust.yml create mode 100644 .gitignore create mode 100644 CHANGELOG.md create mode 100644 Cargo.toml create mode 100644 LICENSE create mode 100644 README.md create mode 100644 rustfmt.toml create mode 100644 src/lib.rs diff --git a/.cargo/README.md b/.cargo/README.md new file mode 100644 index 0000000..ed10676 --- /dev/null +++ b/.cargo/README.md @@ -0,0 +1,86 @@ +# chksum-hash-sha2 + +[![GitHub](https://img.shields.io/badge/github-chksum--rs%2Fhash--sha2-24292e?style=flat-square&logo=github "GitHub")](https://github.com/chksum-rs/hash-sha2) +[![Build](https://img.shields.io/github/actions/workflow/status/chksum-rs/hash-sha2/rust.yml?branch=master&style=flat-square&logo=github "Build")](https://github.com/chksum-rs/hash-sha2/actions/workflows/rust.yml) +[![docs.rs](https://img.shields.io/docsrs/chksum-hash-sha2?style=flat-square&logo=docsdotrs "docs.rs")](https://docs.rs/chksum-hash-sha2/) +[![MSRV](https://img.shields.io/badge/MSRV-1.63.0-informational?style=flat-square "MSRV")](https://github.com/chksum-rs/hash-sha2/blob/master/Cargo.toml) +[![deps.rs](https://deps.rs/crate/chksum-hash-sha2/0.0.0/status.svg?style=flat-square "deps.rs")](https://deps.rs/crate/chksum-hash-sha2/0.0.0) +[![unsafe forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg?style=flat-square "unsafe forbidden")](https://github.com/rust-secure-code/safety-dance) +[![LICENSE](https://img.shields.io/github/license/chksum-rs/hash-sha2?style=flat-square "LICENSE")](https://github.com/chksum-rs/hash-sha2/blob/master/LICENSE) + +An implementation of SHA-2 hash algorithms for batch and stream computation. + +## Setup + +To use this crate, add the following entry to your `Cargo.toml` file in the `dependencies` section: + +```toml +[dependencies] +chksum-hash-sha2 = "0.0.0" +``` + +Alternatively, you can use the [`cargo add`](https://doc.rust-lang.org/cargo/commands/cargo-add.html) subcommand: + +```shell +cargo add chksum-hash-sha2 +``` + +## Usage + +Use the `hash` function for batch digest calculation. + +```rust +use chksum_hash_sha2::sha2_256; + +let digest = sha2_256::hash(b"example data"); +assert_eq!( + digest.to_hex_lowercase(), + "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061" +); +``` + +Use the `default` function to create a hash instance for stream digest calculation. + +```rust +use chksum_hash_sha2::sha2_512; + +let digest = sha2_512::default() + .update("example") + .update(b"data") + .update([0, 1, 2, 3]) + .digest(); +assert_eq!( + digest.to_hex_lowercase(), + "57f35477757af6734892604de3846a97d2cc17cd37068373075e56a4843b3e9c83f9b435beae9fcf1da590e73e62fe20468f52ff13b095241fec77884086b090" +); +``` + +For more usage examples, refer to the documentation available at [docs.rs](https://docs.rs/chksum-hash-sha2/). + +## Features + +Cargo features are used to enable or disable specific algorithm functions. + +* `224` enables SHA-2 224, accessible via the `sha2_224` module, +* `256` enables SHA-2 256, accessible via the `sha2_256` module, +* `384` enables SHA-2 384, accessible via the `sha2_384` module, +* `512` enables SHA-2 512, accessible via the `sha2_512` module. + +By default all of them are enabled. + +To customize your setup, turn off the default features and enable only those that you want in your `Cargo.toml` file: + +```toml +[dependencies] +chksum-hash-sha2 = { version = "0.0.0", default-features = no, features = ["256", "512"] } +``` + +Alternatively, you can use the [`cargo add`](https://doc.rust-lang.org/cargo/commands/cargo-add.html) subcommand: + +```shell +cargo add chksum-hash-sha2 --no-default-features --features 256,512 +``` + +## License + +This crate is licensed under the MIT License. diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml new file mode 100644 index 0000000..0d1276f --- /dev/null +++ b/.github/workflows/rust.yml @@ -0,0 +1,140 @@ +name: Rust + +env: + CARGO_TERM_COLOR: always + +permissions: + contents: read + +on: + push: + branches: + - master + paths: + - ".github/workflows/*.yml" + - "Cargo.toml" + - "src/**.rs" + pull_request: + branches: + - master + paths: + - ".github/workflows/*.yml" + - "Cargo.toml" + - "src/**.rs" + +jobs: + lint: + runs-on: ubuntu-latest + name: Lint + permissions: + checks: write + contents: write + pull-requests: write + steps: + - name: Repository checkout + uses: actions/checkout@v3 + - name: Setup Rust + uses: actions-rs/toolchain@v1 + with: + toolchain: nightly + default: true + profile: minimal + components: rustfmt, clippy + - name: Run cargo fmt + uses: actions-rs/cargo@v1 + with: + command: fmt + args: --check --verbose + - name: Run cargo clippy + uses: actions-rs/clippy-check@v1 + with: + token: ${{ secrets.GITHUB_TOKEN }} + args: --all-features -- --deny clippy::cargo + + build-and-test-linux: + needs: + - lint + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + toolchain: [1.63.0, stable, nightly] + name: "Build and test (OS: Linux, Toolchain: ${{ matrix.toolchain }})" + steps: + - name: Repository checkout + uses: actions/checkout@v3 + - name: Setup Rust + uses: actions-rs/toolchain@v1 + with: + toolchain: ${{ matrix.toolchain }} + default: true + profile: minimal + - name: Run cargo build + uses: actions-rs/cargo@v1 + with: + command: build + args: --all-features --verbose + - name: Run cargo test + uses: actions-rs/cargo@v1 + with: + command: test + args: --all-features --verbose + + build-and-test-macos: + needs: + - lint + runs-on: macos-latest + strategy: + fail-fast: false + matrix: + toolchain: [1.63.0, stable, nightly] + name: "Build and test (OS: MacOS, Toolchain: ${{ matrix.toolchain }})" + steps: + - name: Repository checkout + uses: actions/checkout@v3 + - name: Setup Rust + uses: actions-rs/toolchain@v1 + with: + toolchain: ${{ matrix.toolchain }} + default: true + profile: minimal + - name: Run cargo build + uses: actions-rs/cargo@v1 + with: + command: build + args: --all-features --verbose + - name: Run cargo test + uses: actions-rs/cargo@v1 + with: + command: test + args: --all-features --verbose + + build-and-test-windows: + needs: + - lint + runs-on: windows-latest + strategy: + fail-fast: false + matrix: + toolchain: [1.63.0, stable, nightly] + name: "Build and test (OS: Windows, Toolchain: ${{ matrix.toolchain }})" + steps: + - name: Repository checkout + uses: actions/checkout@v3 + - name: Setup Rust + uses: actions-rs/toolchain@v1 + with: + toolchain: ${{ matrix.toolchain }} + default: true + profile: minimal + - name: Run cargo build + uses: actions-rs/cargo@v1 + with: + command: build + args: --all-features --verbose + - name: Run cargo test + uses: actions-rs/cargo@v1 + with: + command: test + args: --all-features --verbose + \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8e725f7 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +# Cargo +Cargo.lock +target/ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..b1bb63b --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,14 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [0.0.0] - 2023-12-21 + +### Added + +- Initial release. + +[0.0.0]: https://github.com/chksum-rs/hash-sha2/releases/tag/v0.0.0 diff --git a/Cargo.toml b/Cargo.toml new file mode 100644 index 0000000..41edb3c --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,29 @@ +[package] +name = "chksum-hash-sha2" +version = "0.0.0" +authors = ["Konrad Goławski "] +edition = "2021" +rust-version = "1.63.0" +description = "An implementation of SHA-2 hash algorithms for batch and stream computation." +readme = ".cargo/README.md" +repository = "https://github.com/chksum-rs/hash-sha2" +license = "MIT" +keywords = ["checksum", "digest", "hash", "sha2", "sha-2"] +categories = ["algorithms", "cryptography"] + +[package.metadata.docs.rs] +all-features = true +rustdoc-args = ["--cfg", "docsrs"] + +[dependencies] +chksum-hash-sha2-224 = { version = "0.0.0", optional = true } +chksum-hash-sha2-256 = { version = "0.0.0", optional = true } +chksum-hash-sha2-384 = { version = "0.0.0", optional = true } +chksum-hash-sha2-512 = { version = "0.0.0", optional = true } + +[features] +default = ["224", "256", "384", "512"] +224 = ["chksum-hash-sha2-224"] +256 = ["chksum-hash-sha2-256"] +384 = ["chksum-hash-sha2-384"] +512 = ["chksum-hash-sha2-512"] diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..10c2349 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2023 Konrad Goławski + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..80af5e0 --- /dev/null +++ b/README.md @@ -0,0 +1,86 @@ +# chksum-hash-sha2 + +[![crates.io](https://img.shields.io/crates/v/chksum-hash-sha2?style=flat-square&logo=rust "crates.io")](https://crates.io/crates/chksum-hash-sha2) +[![Build](https://img.shields.io/github/actions/workflow/status/chksum-rs/hash-sha2/rust.yml?branch=master&style=flat-square&logo=github "Build")](https://github.com/chksum-rs/hash-sha2/actions/workflows/rust.yml) +[![docs.rs](https://img.shields.io/docsrs/chksum-hash-sha2?style=flat-square&logo=docsdotrs "docs.rs")](https://docs.rs/chksum-hash-sha2/) +[![MSRV](https://img.shields.io/badge/MSRV-1.63.0-informational?style=flat-square "MSRV")](https://github.com/chksum-rs/hash-sha2/blob/master/Cargo.toml) +[![deps.rs](https://deps.rs/crate/chksum-hash-sha2/0.0.0/status.svg?style=flat-square "deps.rs")](https://deps.rs/crate/chksum-hash-sha2/0.0.0) +[![unsafe forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg?style=flat-square "unsafe forbidden")](https://github.com/rust-secure-code/safety-dance) +[![LICENSE](https://img.shields.io/github/license/chksum-rs/hash-sha2?style=flat-square "LICENSE")](https://github.com/chksum-rs/hash-sha2/blob/master/LICENSE) + +An implementation of SHA-2 hash algorithms for batch and stream computation. + +## Setup + +To use this crate, add the following entry to your `Cargo.toml` file in the `dependencies` section: + +```toml +[dependencies] +chksum-hash-sha2 = "0.0.0" +``` + +Alternatively, you can use the [`cargo add`](https://doc.rust-lang.org/cargo/commands/cargo-add.html) subcommand: + +```shell +cargo add chksum-hash-sha2 +``` + +## Usage + +Use the `hash` function for batch digest calculation. + +```rust +use chksum_hash_sha2::sha2_256; + +let digest = sha2_256::hash(b"example data"); +assert_eq!( + digest.to_hex_lowercase(), + "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061" +); +``` + +Use the `default` function to create a hash instance for stream digest calculation. + +```rust +use chksum_hash_sha2::sha2_512; + +let digest = sha2_512::default() + .update("example") + .update(b"data") + .update([0, 1, 2, 3]) + .digest(); +assert_eq!( + digest.to_hex_lowercase(), + "57f35477757af6734892604de3846a97d2cc17cd37068373075e56a4843b3e9c83f9b435beae9fcf1da590e73e62fe20468f52ff13b095241fec77884086b090" +); +``` + +For more usage examples, refer to the documentation available at [docs.rs](https://docs.rs/chksum-hash-sha2/). + +## Features + +Cargo features are used to enable or disable specific algorithm functions. + +* `224` enables SHA-2 224, accessible via the `sha2_224` module, +* `256` enables SHA-2 256, accessible via the `sha2_256` module, +* `384` enables SHA-2 384, accessible via the `sha2_384` module, +* `512` enables SHA-2 512, accessible via the `sha2_512` module. + +By default all of them are enabled. + +To customize your setup, turn off the default features and enable only those that you want in your `Cargo.toml` file: + +```toml +[dependencies] +chksum-hash-sha2 = { version = "0.0.0", default-features = no, features = ["256", "512"] } +``` + +Alternatively, you can use the [`cargo add`](https://doc.rust-lang.org/cargo/commands/cargo-add.html) subcommand: + +```shell +cargo add chksum-hash-sha2 --no-default-features --features 256,512 +``` + +## License + +This crate is licensed under the MIT License. diff --git a/rustfmt.toml b/rustfmt.toml new file mode 100644 index 0000000..7a65644 --- /dev/null +++ b/rustfmt.toml @@ -0,0 +1,17 @@ +combine_control_expr = false +edition = "2021" +force_multiline_blocks = true +format_code_in_doc_comments = true +format_generated_files = true +format_strings = true +group_imports = "StdExternalCrate" +hex_literal_case = "Upper" +imports_granularity = "Module" +imports_layout = "HorizontalVertical" +match_block_trailing_comma = true +max_width = 120 +normalize_comments = true +normalize_doc_attributes = true +reorder_impl_items = true +use_field_init_shorthand = true +use_try_shorthand = true diff --git a/src/lib.rs b/src/lib.rs new file mode 100644 index 0000000..bb992c9 --- /dev/null +++ b/src/lib.rs @@ -0,0 +1,167 @@ +//! This crate provides an implementation of SHA-2 hash functions based on [FIPS PUB 180-4: Secure Hash Standard](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf). +//! +//! # Setup +//! +//! To use this crate, add the following entry to your `Cargo.toml` file in the `dependencies` section: +//! +//! ```toml +//! [dependencies] +//! chksum-hash-sha2 = "0.0.0" +//! ``` +//! +//! Alternatively, you can use the [`cargo add`](https://doc.rust-lang.org/cargo/commands/cargo-add.html) subcommand: +//! +//! ```sh +//! cargo add chksum-hash-sha2 +//! ``` +//! +//! # Batch Processing +//! +//! The digest of known-size data can be calculated with the `hash` function. +//! +//! ```rust +//! use chksum_hash_sha2::sha2_256; +//! +//! let digest = sha2_256::hash("example data"); +//! assert_eq!( +//! digest.to_hex_lowercase(), +//! "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061" +//! ); +//! ``` +//! +//! # Stream Processing +//! +//! The digest of data streams can be calculated chunk-by-chunk with a consumer created by calling the `default` function. +//! +//! ```rust +//! // Import all necessary items +//! # use std::io; +//! # use std::path::PathBuf; +//! use std::fs::File; +//! use std::io::Read; +//! +//! use chksum_hash_sha2::sha2_512; +//! +//! # fn wrapper(path: PathBuf) -> io::Result<()> { +//! // Create a hash instance +//! let mut hash = sha2_512::default(); +//! +//! // Open a file and create a buffer for incoming data +//! let mut file = File::open(path)?; +//! let mut buffer = vec![0; 64]; +//! +//! // Iterate chunk by chunk +//! while let Ok(count) = file.read(&mut buffer) { +//! // EOF reached, exit loop +//! if count == 0 { +//! break; +//! } +//! +//! // Update the hash with data +//! hash.update(&buffer[..count]); +//! } +//! +//! // Calculate the digest +//! let digest = hash.digest(); +//! // Cast the digest to hex and compare +//! assert_eq!( +//! digest.to_hex_lowercase(), +//! "ed59c5759a9ece516cec0c0623142d0e9fe70a27d750eee7fd38f4550d50addd873d0fa1a51fc823c1e3d5cada203f4a05d8325caacb7d3e0727a701f3f07e5f" +//! ); +//! # Ok(()) +//! # } +//! ``` +//! +//! # Algorithms +//! +//! ## SHA-2 224 +//! +//! ```rust +//! use chksum_hash_sha2::sha2_224; +//! +//! let digest = sha2_224::hash("example data"); +//! assert_eq!( +//! digest.to_hex_lowercase(), +//! "90382cbfda2656313ad61fd74b32ddfa4bcc118f660bd4fba9228ced" +//! ); +//! ``` +//! +//! ## SHA-2 256 +//! +//! ```rust +//! use chksum_hash_sha2::sha2_256; +//! +//! let digest = sha2_256::hash("example data"); +//! assert_eq!( +//! digest.to_hex_lowercase(), +//! "44752f37272e944fd2c913a35342eaccdd1aaf189bae50676b301ab213fc5061" +//! ); +//! ``` +//! +//! ## SHA-2 384 +//! +//! ```rust +//! use chksum_hash_sha2::sha2_384; +//! +//! let digest = sha2_384::hash("example data"); +//! assert_eq!( +//! digest.to_hex_lowercase(), +//! "12ecdfd463a85a301b7c29a43bf4b19cdfc6e5e86a5f40396aa6ae3368a7e5b0ed31f3bef2eb3071577ba610b4ed1cb8" +//! ); +//! ``` +//! +//! ## SHA-2 512 +//! +//! ```rust +//! use chksum_hash_sha2::sha2_512; +//! +//! let digest = sha2_512::hash("example data"); +//! assert_eq!( +//! digest.to_hex_lowercase(), +//! "ed59c5759a9ece516cec0c0623142d0e9fe70a27d750eee7fd38f4550d50addd873d0fa1a51fc823c1e3d5cada203f4a05d8325caacb7d3e0727a701f3f07e5f" +//! ); +//! ``` +//! +//! # Features +//! +//! Cargo features are utilized to enable or disable specific SHA-2 algorithm variants. +//! +//! * `224` enables SHA-2 224, accessible via the [`sha2_224`] module. +//! * `256` enables SHA-2 256, accessible via the [`sha2_256`] module. +//! * `384` enables SHA-2 384, accessible via the [`sha2_384`] module. +//! * `512` enables SHA-2 512, accessible via the [`sha2_512`] module. +//! +//! By default, all of these features are enabled. +//! +//! To customize your setup, disable the default features and enable only those that you need in your `Cargo.toml` file: +//! +//! ```toml +//! [dependencies] +//! chksum-hash-sha2 = { version = "0.0.0", default-features = false, features = ["256", "512"] } +//! ``` +//! +//! Alternatively, you can use the [`cargo add`](https://doc.rust-lang.org/cargo/commands/cargo-add.html) subcommand: +//! +//! ```shell +//! cargo add chksum-hash-sha2 --no-default-features --features 256,512 +//! ``` +//! +//! # License +//! +//! This crate is licensed under the MIT License. + +#![cfg_attr(docsrs, feature(doc_auto_cfg))] +#![forbid(unsafe_code)] + +#[cfg(feature = "224")] +#[doc(no_inline)] +pub use chksum_hash_sha2_224 as sha2_224; +#[cfg(feature = "256")] +#[doc(no_inline)] +pub use chksum_hash_sha2_256 as sha2_256; +#[cfg(feature = "384")] +#[doc(no_inline)] +pub use chksum_hash_sha2_384 as sha2_384; +#[cfg(feature = "512")] +#[doc(no_inline)] +pub use chksum_hash_sha2_512 as sha2_512;