sha3/
lib.rs

Help
1//! An implementation of the [SHA-3][1] cryptographic hash algorithms.
2//!
3//! There are 6 standard algorithms specified in the SHA-3 standard:
4//!
5//! * `SHA3-224`
6//! * `SHA3-256`
7//! * `SHA3-384`
8//! * `SHA3-512`
9//! * `SHAKE128`, an extendable output function (XOF)
10//! * `SHAKE256`, an extendable output function (XOF)
11//! * `Keccak224`, `Keccak256`, `Keccak384`, `Keccak512` (NIST submission
12//!    without padding changes)
13//!
14//! Additionally supports `TurboSHAKE`.
15//!
16//! # Examples
17//!
18//! Output size of SHA3-256 is fixed, so its functionality is usually
19//! accessed via the `Digest` trait:
20//!
21//! ```
22//! use hex_literal::hex;
23//! use sha3::{Digest, Sha3_256};
24//!
25//! // create a SHA3-256 object
26//! let mut hasher = Sha3_256::new();
27//!
28//! // write input message
29//! hasher.update(b"abc");
30//!
31//! // read hash digest
32//! let result = hasher.finalize();
33//!
34//! assert_eq!(result[..], hex!("
35//!     3a985da74fe225b2045c172d6bd390bd855f086e3e9d525b46bfe24511431532
36//! ")[..]);
37//! ```
38//!
39//! SHAKE functions have an extendable output, so finalization method returns
40//! XOF reader from which results of arbitrary length can be read. Note that
41//! these functions do not implement `Digest`, so lower-level traits have to
42//! be imported:
43//!
44//! ```
45//! use sha3::{Shake128, digest::{Update, ExtendableOutput, XofReader}};
46//! use hex_literal::hex;
47//!
48//! let mut hasher = Shake128::default();
49//! hasher.update(b"abc");
50//! let mut reader = hasher.finalize_xof();
51//! let mut res1 = [0u8; 10];
52//! reader.read(&mut res1);
53//! assert_eq!(res1, hex!("5881092dd818bf5cf8a3"));
54//! ```
55//!
56//! Also see [RustCrypto/hashes][2] readme.
57//!
58//! [1]: https://en.wikipedia.org/wiki/SHA-3
59//! [2]: https://github.com/RustCrypto/hashes
60
61#![no_std]
62#![doc(
63    html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg",
64    html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg"
65)]
66#![forbid(unsafe_code)]
67#![warn(missing_docs, rust_2018_idioms)]
68
69pub use digest::{self, Digest};
70
71use core::fmt;
72#[cfg(feature = "oid")]
73use digest::const_oid::{AssociatedOid, ObjectIdentifier};
74use digest::{
75    block_buffer::Eager,
76    consts::{U104, U136, U144, U168, U200, U28, U32, U48, U64, U72},
77    core_api::{
78        AlgorithmName, Block, BlockSizeUser, Buffer, BufferKindUser, CoreWrapper,
79        ExtendableOutputCore, FixedOutputCore, OutputSizeUser, Reset, UpdateCore, XofReaderCore,
80        XofReaderCoreWrapper,
81    },
82    generic_array::typenum::Unsigned,
83    HashMarker, Output,
84};
85
86#[macro_use]
87mod macros;
88mod state;
89
90use crate::state::Sha3State;
91
92// Paddings
93const KECCAK: u8 = 0x01;
94const SHA3: u8 = 0x06;
95const SHAKE: u8 = 0x1f;
96const CSHAKE: u8 = 0x4;
97
98// Round counts
99const TURBO_SHAKE_ROUND_COUNT: usize = 12;
100
101impl_sha3!(Keccak224Core, Keccak224, U28, U144, KECCAK, "Keccak-224");
102impl_sha3!(Keccak256Core, Keccak256, U32, U136, KECCAK, "Keccak-256");
103impl_sha3!(Keccak384Core, Keccak384, U48, U104, KECCAK, "Keccak-384");
104impl_sha3!(Keccak512Core, Keccak512, U64, U72, KECCAK, "Keccak-512");
105
106impl_sha3!(
107    Keccak256FullCore,
108    Keccak256Full,
109    U200,
110    U136,
111    KECCAK,
112    "SHA-3 CryptoNight variant",
113);
114
115impl_sha3!(
116    Sha3_224Core,
117    Sha3_224,
118    U28,
119    U144,
120    SHA3,
121    "SHA-3-224",
122    "2.16.840.1.101.3.4.2.7",
123);
124impl_sha3!(
125    Sha3_256Core,
126    Sha3_256,
127    U32,
128    U136,
129    SHA3,
130    "SHA-3-256",
131    "2.16.840.1.101.3.4.2.8",
132);
133impl_sha3!(
134    Sha3_384Core,
135    Sha3_384,
136    U48,
137    U104,
138    SHA3,
139    "SHA-3-384",
140    "2.16.840.1.101.3.4.2.9",
141);
142impl_sha3!(
143    Sha3_512Core,
144    Sha3_512,
145    U64,
146    U72,
147    SHA3,
148    "SHA-3-512",
149    "2.16.840.1.101.3.4.2.10",
150);
151
152impl_shake!(
153    Shake128Core,
154    Shake128,
155    Shake128ReaderCore,
156    Shake128Reader,
157    U168,
158    SHAKE,
159    "SHAKE128",
160    "2.16.840.1.101.3.4.2.11",
161);
162impl_shake!(
163    Shake256Core,
164    Shake256,
165    Shake256ReaderCore,
166    Shake256Reader,
167    U136,
168    SHAKE,
169    "SHAKE256",
170    "2.16.840.1.101.3.4.2.11",
171);
172
173impl_turbo_shake!(
174    TurboShake128Core,
175    TurboShake128,
176    TurboShake128ReaderCore,
177    TurboShake128Reader,
178    U168,
179    "TurboSHAKE128",
180);
181impl_turbo_shake!(
182    TurboShake256Core,
183    TurboShake256,
184    TurboShake256ReaderCore,
185    TurboShake256Reader,
186    U136,
187    "TurboSHAKE256",
188);
189
190impl_cshake!(
191    CShake128Core,
192    CShake128,
193    CShake128ReaderCore,
194    CShake128Reader,
195    U168,
196    SHAKE,
197    CSHAKE,
198    "CSHAKE128",
199);
200impl_cshake!(
201    CShake256Core,
202    CShake256,
203    CShake256ReaderCore,
204    CShake256Reader,
205    U136,
206    SHAKE,
207    CSHAKE,
208    "CSHAKE256",
209);
210
211#[inline(always)]
212pub(crate) fn left_encode(val: u64, b: &mut [u8; 9]) -> &[u8] {
213    b[1..].copy_from_slice(&val.to_be_bytes());
214    let i = b[1..8].iter().take_while(|&&a| a == 0).count();
215    b[i] = (8 - i) as u8;
216    &b[i..]
217}
sha3/lib.rs

sha3/
lib.rs
