138 lines
5.1 KiB
Markdown
138 lines
5.1 KiB
Markdown
# RustCrypto: SHA-2
|
|
|
|
[![crate][crate-image]][crate-link]
|
|
[![Docs][docs-image]][docs-link]
|
|
![Apache2/MIT licensed][license-image]
|
|
![Rust Version][rustc-image]
|
|
[![Project Chat][chat-image]][chat-link]
|
|
[![Build Status][build-image]][build-link]
|
|
|
|
Pure Rust implementation of the [SHA-2] cryptographic hash algorithms.
|
|
|
|
There are 6 standard algorithms specified in the SHA-2 standard:
|
|
`Sha224`, `Sha256`, `Sha512_224`, `Sha512_256`, `Sha384`, and `Sha512`.
|
|
|
|
Algorithmically, there are only 2 core algorithms: SHA-256 and SHA-512.
|
|
All other algorithms are just applications of these with different initial
|
|
hash values, and truncated to different digest bit lengths. The first two
|
|
algorithms in the list are based on SHA-256, while the last four are based
|
|
on SHA-512.
|
|
|
|
## Examples
|
|
|
|
### One-shot API
|
|
|
|
```rust
|
|
use sha2::{Sha256, Digest};
|
|
use hex_literal::hex;
|
|
|
|
let hash = Sha256::digest(b"hello world");
|
|
assert_eq!(hash, hex!("b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"));
|
|
```
|
|
|
|
### Incremental API
|
|
|
|
```rust
|
|
use sha2::{Sha256, Sha512, Digest};
|
|
use hex_literal::hex;
|
|
|
|
let mut hasher = Sha256::new();
|
|
hasher.update(b"hello ");
|
|
hasher.update(b"world");
|
|
let hash256 = hasher.finalize();
|
|
|
|
assert_eq!(hash256, hex!("b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"));
|
|
|
|
let mut hasher = Sha512::new();
|
|
hasher.update(b"hello world");
|
|
let hash512 = hasher.finalize();
|
|
|
|
assert_eq!(hash512, hex!(
|
|
"309ecc489c12d6eb4cc40f50c902f2b4d0ed77ee511a7c7a9bcd3ca86d4cd86f"
|
|
"989dd35bc5ff499670da34255b45b0cfd830e81f605dcf7dc5542e93ae9cd76f"
|
|
));
|
|
```
|
|
|
|
See the [`digest`] crate docs for additional examples.
|
|
|
|
## Backends
|
|
|
|
This crate supports a number of different backends.
|
|
|
|
SHA-256 and SHA-512 backends:
|
|
- `soft`: portable software implementation
|
|
- `loongarch64-asm`: `asm!`-based implementation for LoongArch64 targets
|
|
- `riscv-zknh`: uses the RISC-V `Zknh` scalar crypto extension. Experimental,
|
|
requires Nightly compiler and to enable `Zknh` and `Zbkb` (or `Zbb`)
|
|
target features at compile time.
|
|
- `wasm32-simd128`: uses the WASM `simd128` extension.
|
|
|
|
SHA-256 only backends:
|
|
- `aarch64-sha2`: uses the AArch64 `sha2` extension.
|
|
- `x86-sha`: uses the x86 SHA-NI extension.
|
|
|
|
SHA-512 only backends:
|
|
- `aarch64-sha3`: uses the AArch64 `sha3` extension.
|
|
- `x86-avx2`: uses the x86 AVX2 extension.
|
|
|
|
By default the following backends are used:
|
|
- `target_arch = "aarch64"`: use `aarch64-sha2` and `aarch64-sha3` when the required
|
|
target features are detected at runtime; otherwise fall back to `soft`.
|
|
- `any(target_arch = "x86", target_arch = "x86_64")`: use `x86-sha` and `x86-avx` when
|
|
the required target features are detected at runtime; otherwise fall back to `soft`.
|
|
- `target_arch = "loongarch64"`: use `loongarch64-asm`.
|
|
- `all(target_arch = "wasm32", target_feature = "simd128")`: use `wasm32-simd128`.
|
|
- All other targets: use `soft`.
|
|
|
|
You can force backend selection using the following configuration flags:
|
|
- `sha2_backend`: select SHA-256 and SHA-512 backends. Supported values: `soft`, `riscv-zknh`.
|
|
- `sha2_256_backend`: select SHA-256 backend. Supported values: `aarch64-sha2`, `soft`,
|
|
`riscv-zknh`, `x86-sha`.
|
|
- `sha2_512_backend`: select SHA-512 backend. Supported values: `aarch64-sha3`, `soft`,
|
|
`riscv-zknh`, `x86-avx2`.
|
|
|
|
They can be enabled using either the `RUSTFLAGS` environment variable
|
|
(e.g. `RUSTFLAGS='--cfg sha2_backend="soft"'`), or by modifying your `.cargo/config.toml` file.
|
|
|
|
Note that `sha2_backend` has higher priority than `sha2_256_backend` and `sha2_512_backend`.
|
|
In other words, using `--cfg sha2_backend="soft" --cfg sha2_256_backend="x86_sha"` will result
|
|
in selection of the software backend for SHA-256.
|
|
|
|
By default `soft` and `riscv-zknh` backends unroll round loops, which results in a better
|
|
performance at the cost of a bigger resulting binary. You can disable unrolling in the backends
|
|
by using `sha2_backend_soft = "compact"` and `sha2_backend_riscv_zknh = "compact"` configuration
|
|
flags respectively.
|
|
|
|
## License
|
|
|
|
The crate is licensed under either of:
|
|
|
|
* [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
|
|
* [MIT license](http://opensource.org/licenses/MIT)
|
|
|
|
at your option.
|
|
|
|
### Contribution
|
|
|
|
Unless you explicitly state otherwise, any contribution intentionally submitted
|
|
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
|
|
dual licensed as above, without any additional terms or conditions.
|
|
|
|
[//]: # (badges)
|
|
|
|
[crate-image]: https://img.shields.io/crates/v/sha2.svg
|
|
[crate-link]: https://crates.io/crates/sha2
|
|
[docs-image]: https://docs.rs/sha2/badge.svg
|
|
[docs-link]: https://docs.rs/sha2/
|
|
[license-image]: https://img.shields.io/badge/license-Apache2.0/MIT-blue.svg
|
|
[rustc-image]: https://img.shields.io/badge/rustc-1.85+-blue.svg
|
|
[chat-image]: https://img.shields.io/badge/zulip-join_chat-blue.svg
|
|
[chat-link]: https://rustcrypto.zulipchat.com/#narrow/stream/260041-hashes
|
|
[build-image]: https://github.com/RustCrypto/hashes/actions/workflows/sha2.yml/badge.svg?branch=master
|
|
[build-link]: https://github.com/RustCrypto/hashes/actions/workflows/sha2.yml?query=branch:master
|
|
|
|
[//]: # (general links)
|
|
|
|
[SHA-2]: https://en.wikipedia.org/wiki/SHA-2
|
|
[`digest`]: https://docs.rs/digest
|