ic_hash/lib.rs
1//! # ic-hash — FIPS 180-4 and FIPS 202 hash functions
2//!
3//! Pure-Rust, `no_std`, allocation-free implementations of the SHA-2 and SHA-3
4//! families plus the SHAKE extendable-output functions.
5//!
6//! ```
7//! use ic_hash::Sha256;
8//! use ic_core::traits::Digest;
9//!
10//! let d = Sha256::digest(b"abc");
11//! assert_eq!(
12//! ic_core::codec::hex(d.as_ref()),
13//! "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
14//! );
15//! ```
16//!
17//! Every type here implements [`ic_core::traits::Digest`] (or [`ic_core::traits::Xof`])
18//! and [`ic_core::traits::SelfTest`], so `ic-fips` can drive their known-answer
19//! tests generically.
20#![cfg_attr(not(feature = "std"), no_std)]
21// `deny` rather than `forbid`, and the difference is the point: one module is
22// allowed unsafe and every other line in this crate is a compile error. The
23// allowance below marks the only place a CPU intrinsic is called. This crate
24// forbade it outright until SHA-256 gained a SHA-NI backend, which was worth
25// roughly seven times the throughput on hardware that has it and cannot be
26// written any other way.
27#![deny(unsafe_code)]
28#![deny(missing_docs)]
29#![warn(clippy::all)]
30
31pub mod blake2;
32// SHA-NI, behind runtime detection. See `sha2::x86`.
33#[allow(unsafe_code)]
34mod sha2;
35mod sha3;
36pub mod sp800_185;
37
38pub use blake2::{blake2b_long, Blake2b};
39pub use sha2::{Sha224, Sha256, Sha384, Sha512, Sha512_224, Sha512_256};
40pub use sha3::{Sha3_224, Sha3_256, Sha3_384, Sha3_512, Shake128, Shake256, XofReader};
41pub use sp800_185::{CShake128, CShake256};
42pub use sp800_185::{ParallelHash128, ParallelHash256, TupleHash128, TupleHash256};
43
44/// Dynamic identifiers for the digests in this crate, as used by the ontology
45/// and the agent-facing dispatch layer.
46pub const DIGEST_IDS: &[&str] = &[
47 "blake2b",
48 "sha2-224",
49 "sha2-256",
50 "sha2-384",
51 "sha2-512",
52 "sha2-512-224",
53 "sha2-512-256",
54 "sha3-224",
55 "sha3-256",
56 "sha3-384",
57 "sha3-512",
58];
59
60/// Dynamic identifiers for the extendable-output functions in this crate.
61pub const XOF_IDS: &[&str] = &["shake128", "shake256"];