From 32029ac14632ba08618aaecef508cb5ffcfd42c4 Mon Sep 17 00:00:00 2001 From: Artyom Pavlov Date: Mon, 17 Jan 2022 15:00:04 +0000 Subject: [PATCH] sha1: switch name from sha-1 to sha1 (#350) --- Cargo.lock | 2 +- README.md | 48 ++++++++++++++--------- sha1/CHANGELOG.md | 99 ++--------------------------------------------- sha1/Cargo.toml | 8 ++-- sha1/src/lib.rs | 9 ++++- 5 files changed, 45 insertions(+), 121 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index a447f4c4c..67e37fead 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -191,7 +191,7 @@ dependencies = [ ] [[package]] -name = "sha-1" +name = "sha1" version = "0.10.0" dependencies = [ "cfg-if", diff --git a/README.md b/README.md index 48fab8675..f647bab9c 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Additionally all crates do not require the standard library (i.e. `no_std` capab | [MD4] | [`md4`] | [![crates.io](https://img.shields.io/crates/v/md4.svg)](https://crates.io/crates/md4) | [![Documentation](https://docs.rs/md4/badge.svg)](https://docs.rs/md4) | ![MSRV 1.41][msrv-1.41] | :broken_heart: | | [MD5] | [`md-5`] [:exclamation:] | [![crates.io](https://img.shields.io/crates/v/md-5.svg)](https://crates.io/crates/md-5) | [![Documentation](https://docs.rs/md-5/badge.svg)](https://docs.rs/md-5) | ![MSRV 1.41][msrv-1.41] | :broken_heart: | | [RIPEMD] | [`ripemd`] | [![crates.io](https://img.shields.io/crates/v/ripemd.svg)](https://crates.io/crates/ripemd) | [![Documentation](https://docs.rs/ripemd/badge.svg)](https://docs.rs/ripemd) | ![MSRV 1.41][msrv-1.41] | :green_heart: | -| [SHA-1] | [`sha-1`] [:exclamation:] | [![crates.io](https://img.shields.io/crates/v/sha-1.svg)](https://crates.io/crates/sha-1) | [![Documentation](https://docs.rs/sha-1/badge.svg)](https://docs.rs/sha-1) | ![MSRV 1.41][msrv-1.41] | :broken_heart: | +| [SHA-1] | [`sha1`] | [![crates.io](https://img.shields.io/crates/v/sha1.svg)](https://crates.io/crates/sha1) | [![Documentation](https://docs.rs/sha1/badge.svg)](https://docs.rs/sha1) | ![MSRV 1.41][msrv-1.41] | :broken_heart: | | [SHA-2] | [`sha2`] | [![crates.io](https://img.shields.io/crates/v/sha2.svg)](https://crates.io/crates/sha2) | [![Documentation](https://docs.rs/sha2/badge.svg)](https://docs.rs/sha2) | ![MSRV 1.41][msrv-1.41] | :green_heart: | | [SHA-3] (Keccak) | [`sha3`] | [![crates.io](https://img.shields.io/crates/v/sha3.svg)](https://crates.io/crates/sha3) | [![Documentation](https://docs.rs/sha3/badge.svg)](https://docs.rs/sha3) | ![MSRV 1.41][msrv-1.41] | :green_heart: | | [SHABAL] | [`shabal`] | [![crates.io](https://img.shields.io/crates/v/shabal.svg)](https://crates.io/crates/shabal) | [![Documentation](https://docs.rs/shabal/badge.svg)](https://docs.rs/shabal) | ![MSRV 1.41][msrv-1.41] | :green_heart: | @@ -31,7 +31,7 @@ Additionally all crates do not require the standard library (i.e. `no_std` capab | [Tiger] | [`tiger`] | [![crates.io](https://img.shields.io/crates/v/tiger.svg)](https://crates.io/crates/tiger) | [![Documentation](https://docs.rs/tiger/badge.svg)](https://docs.rs/tiger) | ![MSRV 1.41][msrv-1.41] | :green_heart: | | [Whirlpool] | [`whirlpool`] | [![crates.io](https://img.shields.io/crates/v/whirlpool.svg)](https://crates.io/crates/whirlpool) | [![Documentation](https://docs.rs/whirlpool/badge.svg)](https://docs.rs/whirlpool) | ![MSRV 1.41][msrv-1.41] | :green_heart: | -NOTE: the [BLAKE3 crate](https://github.com/BLAKE3-team/BLAKE3) implements the `digest` traits used by the rest of the hashes in this repository, but is maintained by the BLAKE3 team. +NOTE: the [`blake3`] crate implements the `digest` traits used by the rest of the hashes in this repository, but is maintained by the BLAKE3 team. [Security]: https://en.wikipedia.org/wiki/Hash_function_security_summary [:exclamation:]: #crate-names @@ -39,9 +39,13 @@ NOTE: the [BLAKE3 crate](https://github.com/BLAKE3-team/BLAKE3) implements the ` ### Crate Names Whenever possible crates are published under the the same name as the crate folder. -Owners of `md5` and `sha1` declined ([1](https://github.com/stainless-steel/md5/pull/2), [2](https://github.com/mitsuhiko/rust-sha1/issues/17)) to participate in this project. -Those crates do not implement the [`digest`] traits, so they are not interoperable with the RustCrypto ecosystem. -This is why crates marked by :exclamation: are published under `md-5` and `sha-1` names, but the libraries themselves are named as `md5` and `sha1`, i.e. inside `use` statements you should use `sha1`/`md5`, not `sha_1`/`md_5`. +Owners of `md5` [declined](https://github.com/stainless-steel/md5/pull/) to participate in this project. +This crate does not implement the [`digest`] traits, so it is not interoperable with the RustCrypto ecosystem. +This is why we publish our MD5 implementation as `md-5` and mark it with the :exclamation: mark. +Note that the library itselv is named as `md5`, i.e. inside `use` statements you should use `md5`, not `md_5`. + +The SHA-1 implementation was previosuly published as `sha-1`, but migrated to `sha1` since v0.10.0. +`sha-1` will continue to recieve v0.10.x patch updates, but will be deprecated after `sha1` v0.11 release. ### Security Level Legend @@ -92,12 +96,22 @@ hasher.update(data); hasher.update("String data"); // Note that calling `finalize()` consumes hasher let hash = hasher.finalize(); -println!("Result: {:x}", hash); +println!("Binary hash: {:?}", hash); ``` In this example `hash` has type `GenericArray`, which is a generic alternative to `[u8; 32]` defined in the [`generic-array`] crate. +If you need to serialize hash value into string, you can use crates like [`base16ct`] and [`base64ct`]: +```rust +use base64ct::{Base64, Encoding}; + +let base64_hash = Base64::encode_string(&hash); +println!("Base64-encoded hash: {}", hex_hash); -Alternatively, you can use a chained approach, which is equivalent to the previous example: +let hex_hash = base16ct::lower::encode_string(&hash); +println!("Hex-encoded hash: {}", hex_hash); +``` + +Instead of calling `update`, you also can use a chained approach: ```rust use sha2::{Sha256, Digest}; @@ -106,16 +120,14 @@ let hash = Sha256::new() .chain_update(b"Hello world!") .chain_update("String data") .finalize(); -println!("Result: {:x}", hash); ``` -If a complete message is available, then you also can use the convenience [`Digest::digest`] method: +If a complete message is available, then you can use the convenience [`Digest::digest`] method: ```rust use sha2::{Sha256, Digest}; let hash = Sha256::digest(b"my message"); -println!("Result: {:x}", hash); ``` ### Hashing `Read`able Objects @@ -130,9 +142,6 @@ let mut file = fs::File::open(&path)?; let mut hasher = Sha256::new(); let n = io::copy(&mut file, &mut hasher)?; let hash = hasher.finalize(); - -println!("Bytes processed: {}", n); -println!("Hash value: {:x}", hash); ``` ### Hash-based Message Authentication Code (HMAC) @@ -176,10 +185,10 @@ fn dyn_hash(hasher: &mut dyn DynDigest, data: &[u8]) -> Box<[u8]> { let mut sha256_hasher = Sha256::default(); let mut sha512_hasher = Sha512::default(); -let res1 = dyn_hash(&mut sha256_hasher, b"foo"); -let res2 = dyn_hash(&mut sha256_hasher, b"bar"); -let res3 = dyn_hash(&mut sha512_hasher, b"foo"); -let res4 = dyn_hash(&mut sha512_hasher, b"bar"); +let hash1 = dyn_hash(&mut sha256_hasher, b"foo"); +let hash2 = dyn_hash(&mut sha256_hasher, b"bar"); +let hash3 = dyn_hash(&mut sha512_hasher, b"foo"); +let hash4 = dyn_hash(&mut sha512_hasher, b"bar"); ``` ## License @@ -215,7 +224,7 @@ Unless you explicitly state otherwise, any contribution intentionally submitted [`md4`]: ./md4 [`md-5`]: ./md-5 [`ripemd`]: ./ripemd -[`sha-1`]: ./sha1 +[`sha1`]: ./sha1 [`sha2`]: ./sha2 [`sha3`]: ./sha3 [`shabal`]: ./shabal @@ -227,6 +236,9 @@ Unless you explicitly state otherwise, any contribution intentionally submitted [//]: # (footnotes) [1]: https://en.wikipedia.org/wiki/Cryptographic_hash_function +[`blake3`]: https://github.com/BLAKE3-team/BLAKE3 +[`base16ct`]: https://docs.rs/base16ct +[`base64ct`]: https://docs.rs/base64ct [`digest`]: https://docs.rs/digest [`Digest`]: https://docs.rs/digest/0.10.0/digest/trait.Digest.html [`Digest::digest`]: https://docs.rs/digest/0.10.0/digest/trait.Digest.html#tymethod.digest diff --git a/sha1/CHANGELOG.md b/sha1/CHANGELOG.md index 3e99c8436..12e08dc6d 100644 --- a/sha1/CHANGELOG.md +++ b/sha1/CHANGELOG.md @@ -5,101 +5,8 @@ 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.10.0 (2021-12-07) +## 0.10.0 (2022-01-17) ### Changed -- Update to `digest` v0.10 ([#217]) +- The crate is transferred to the RustCrypto organization. New implementation is identical to the `sha-1 v0.10.0` crate and expressed in terms of traits from the `digest` crate. ([#350]) -[#217]: https://github.com/RustCrypto/hashes/pull/217 - -## 0.9.8 (2021-08-27) -### Changed -- Bump `cpufeatures` dependency to 0.2 ([#306]) - -[#306]: https://github.com/RustCrypto/hashes/pull/306 - -## 0.9.7 (2021-07-18) -### Changed -- Make `aarch64` CPU feature detection OS-independent ([#276]) -- Bump `sha1-asm` to v0.5; support ARMv8 Crypto Extensions on Apple targets ([#289]) - -[#276]: https://github.com/RustCrypto/hashes/pull/276 -[#289]: https://github.com/RustCrypto/hashes/pull/289 - -## 0.9.6 (2021-05-11) -### Changed -- Use `cpufeatures` to detect intrinsics support on `aarch64` targets ([#268]) - -[#268]: https://github.com/RustCrypto/hashes/pull/268 - -## 0.9.5 (2021-05-05) -### Changed -- Switch from `cpuid-bool` to `cpufeatures` ([#263]) - -[#263]: https://github.com/RustCrypto/hashes/pull/263 - -## 0.9.4 (2021-02-16) -### Added -- Expose compression function under the `compress` feature flag. ([#238]) - -[#238]: https://github.com/RustCrypto/hashes/pull/238 - -## 0.9.3 (2021-02-01) -### Changed -- Use SHA1 intrinsics when `asm` feature is enabled. ([#225]) - -[#225]: https://github.com/RustCrypto/hashes/pull/225 - -## 0.9.2 (2020-11-04) -### Added -- `force-soft` feature to enforce use of software implementation. ([#203]) - -### Changed -- `cfg-if` dependency updated to v1.0. ([#197]) - -[#197]: https://github.com/RustCrypto/hashes/pull/197 -[#203]: https://github.com/RustCrypto/hashes/pull/203 - -## 0.9.1 (2020-06-24) -### Added -- x86 hardware acceleration via SHA extension instrinsics. ([#167]) - -[#167]: https://github.com/RustCrypto/hashes/pull/167 - -## 0.9.0 (2020-06-09) -### Changed -- Update to `digest` v0.9 release; MSRV 1.41+ ([#155]) -- Use new `*Dirty` traits from the `digest` crate ([#153]) -- Bump `block-buffer` to v0.8 release ([#151]) -- Rename `*result*` to `finalize` ([#148]) -- Upgrade to Rust 2018 edition ([#132]) -- Use `libc` for `aarch64` consts ([#94]) -- Allow compile-time detection of crypto on `aarch64` ([#94]) - -[#155]: https://github.com/RustCrypto/hashes/pull/155 -[#153]: https://github.com/RustCrypto/hashes/pull/153 -[#151]: https://github.com/RustCrypto/hashes/pull/151 -[#148]: https://github.com/RustCrypto/hashes/pull/148 -[#132]: https://github.com/RustCrypto/hashes/pull/132 -[#94]: https://github.com/RustCrypto/hashes/pull/94 - -## 0.8.2 (2020-01-06) - -## 0.8.1 (2018-11-14) - -## 0.8.0 (2018-10-02) - -## 0.7.0 (2017-11-15) - -## 0.4.1 (2017-06-13) - -## 0.4.0 (2017-06-12) - -## 0.3.4 (2017-06-04) - -## 0.3.3 (2017-05-09) - -## 0.3.2 (2017-05-02) - -## 0.3.1 (2017-04-18) - -## 0.3.0 (2017-04-06) +[#350]: https://github.com/RustCrypto/hashes/pull/350 diff --git a/sha1/Cargo.toml b/sha1/Cargo.toml index 3c8c14624..0ed7c60f1 100644 --- a/sha1/Cargo.toml +++ b/sha1/Cargo.toml @@ -1,19 +1,17 @@ [package] -name = "sha-1" +name = "sha1" version = "0.10.0" # Also update html_root_url in lib.rs when bumping this +# on v0.10.x releases also release the sha-1 crate as well description = "SHA-1 hash function" authors = ["RustCrypto Developers"] license = "MIT OR Apache-2.0" readme = "README.md" edition = "2018" -documentation = "https://docs.rs/sha-1" +documentation = "https://docs.rs/sha1" repository = "https://github.com/RustCrypto/hashes" keywords = ["crypto", "sha1", "hash", "digest"] categories = ["cryptography", "no-std"] -[lib] -name = "sha1" - [dependencies] digest = "0.10" cfg-if = "1.0" diff --git a/sha1/src/lib.rs b/sha1/src/lib.rs index 134108e77..96b1c8a90 100644 --- a/sha1/src/lib.rs +++ b/sha1/src/lib.rs @@ -29,16 +29,23 @@ //! //! Also see [RustCrypto/hashes][3] readme. //! +//! # Note for users of `sha1 v0.6` +//! +//! This crate has been transferred to the RustCrypto organization and uses +//! implementation previously published as the `sha-1` crate. The previous +//! zero dependencies version is now published as the [`sha1_smoll`] crate. +//! //! [1]: https://en.wikipedia.org/wiki/SHA-1 //! [2]: https://sha-mbles.github.io/ //! [3]: https://github.com/RustCrypto/hashes +//! [`sha1_smoll`]: https://github.com/mitsuhiko/sha1-smol/ #![no_std] #![cfg_attr(docsrs, feature(doc_cfg))] #![doc( html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg", html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg", - html_root_url = "https://docs.rs/sha-1/0.10.0" + html_root_url = "https://docs.rs/sha1/0.10.0" )] #![warn(missing_docs, rust_2018_idioms)]