bouncycastle_sha2/
lib.rs

1//! Implements SHA2 as per NIST FIPS 180-4.
2//!
3//! # Examples
4//! ## Hash
5//! Hash functionality is accessed via the [`bouncycastle_core::traits::Hash`] trait,
6//! which is implemented by [`SHA224`], [`SHA256`], [`SHA384`] and [`SHA512`].
7//!
8//! The simplest usage is via the static functions.
9//! ```
10//! use bouncycastle_core::traits::Hash;
11//! use bouncycastle_sha2 as sha2;
12//!
13//! let data: &[u8] = b"Hello, world!";
14//! let output: Vec<u8> = sha2::SHA256::new().hash(data);
15//! ```
16//!
17//! More advanced usage will require creating a SHA3 or SHAKE object to hold state between successive calls,
18//! for example if input is received in chunks and not all available at the same time:
19//!
20//! ```
21//! use bouncycastle_sha2 as sha2;
22//! use bouncycastle_core::traits::Hash;
23//!
24//! let data: &[u8] = b"\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F
25//!                     \x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1A\x1B\x1C\x1D\x1E\x1F
26//!                     \x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F
27//!                     \x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1A\x1B\x1C\x1D\x1E\x1F";
28//! let mut sha2 = sha2::SHA256::new();
29//!
30//! for chunk in data.chunks(16) {
31//!     sha2.do_update(chunk);
32//! }
33//!
34//! let output: Vec<u8> = sha2.do_final();
35//! ```
36//!
37//! # Suspending and resuming execution
38//!
39//! When hashing a large message, it can be advantageous to be able to suspend the operation
40//! to a cache and resume it later; for example if waiting for the message to stream over a slow network
41//! connection.
42//!
43//! For this reason, all SHA2 algorithms impl [`Suspendable`].
44//!
45//! ```rust
46//! use bouncycastle_sha2 as sha2;
47//! use bouncycastle_core::traits::{Hash, Suspendable};
48//!
49//! let msg_part1 = b"The quick brown fox";
50//! let msg_part2 = b" jumped over the lazy dog";
51//!
52//! let mut sha2 = sha2::SHA256::new();
53//! sha2.do_update(msg_part1);
54//!
55//! // suspend the in-progress extract while "waiting" for the second part of the message.
56//! let serialized_state = sha2.suspend();
57//!
58//! // ...
59//! // do other things in the meantime
60//! // ...
61//!
62//! // ... later, possibly on another host: resume from the serialized state.
63//! let mut sha2_resumed = sha2::SHA256::from_suspended(serialized_state).unwrap();
64//! sha2_resumed.do_update(msg_part2);
65//! let h: Vec<u8> = sha2_resumed.do_final();
66//! ```
67
68#![forbid(unsafe_code)]
69#![forbid(missing_docs)]
70#![allow(private_bounds)]
71
72mod sha256;
73mod sha512;
74
75pub use self::sha256::SHA256Internal;
76pub use self::sha512::SHA512Internal;
77use bouncycastle_core::traits::{Algorithm, AlgorithmOID, HashAlgParams, SecurityStrength};
78
79/*** Imports needed for docs ***/
80#[allow(unused_imports)]
81use bouncycastle_core::traits::Suspendable;
82
83/*** String constants ***/
84///
85pub const SHA224_NAME: &str = "SHA224";
86///
87pub const SHA256_NAME: &str = "SHA256";
88///
89pub const SHA384_NAME: &str = "SHA384";
90///
91pub const SHA512_NAME: &str = "SHA512";
92
93/*** pub types ***/
94/// Public type for SHA224.
95pub type SHA224 = SHA256Internal<SHA224Params>;
96/// Public type for SHA256.
97pub type SHA256 = SHA256Internal<SHA256Params>;
98/// Public type for SHA384.
99pub type SHA384 = SHA512Internal<SHA384Params>;
100/// Public type for SHA512.
101pub type SHA512 = SHA512Internal<SHA512Params>;
102
103/*** Param traits ***/
104/// Private trait on purpose so that only the NIST-approved params can be used.
105trait SHA2Params: HashAlgParams {}
106
107/*** SHA224 ***/
108impl HashAlgParams for SHA224 {
109    const OUTPUT_LEN: usize = 28;
110    const BLOCK_LEN: usize = 64;
111}
112/// The parameters for SHA224.
113#[derive(Clone)]
114pub struct SHA224Params;
115impl Algorithm for SHA224Params {
116    const ALG_NAME: &'static str = SHA224_NAME;
117    const MAX_SECURITY_STRENGTH: SecurityStrength = SecurityStrength::_112bit;
118}
119impl HashAlgParams for SHA224Params {
120    const OUTPUT_LEN: usize = 28;
121    const BLOCK_LEN: usize = 64;
122}
123/// Assigned by NIST in the Computer Security Objects Register: id-sha224 { hashAlgs 4 }
124impl AlgorithmOID for SHA224 {
125    const OID: &'static [u32] = &[2, 16, 840, 1, 101, 3, 4, 2, 4];
126    const OID_DER: &'static [u8] =
127        &[0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x04];
128}
129impl SHA2Params for SHA224Params {}
130
131/*** SHA256 ***/
132impl HashAlgParams for SHA256 {
133    const OUTPUT_LEN: usize = 32;
134    const BLOCK_LEN: usize = 64;
135}
136/// The parameters for SHA256.
137#[derive(Clone)]
138pub struct SHA256Params;
139impl Algorithm for SHA256Params {
140    const ALG_NAME: &'static str = SHA256_NAME;
141    const MAX_SECURITY_STRENGTH: SecurityStrength = SecurityStrength::_128bit;
142}
143/// Assigned by NIST in the Computer Security Objects Register: id-sha256 { hashAlgs 1 }
144impl AlgorithmOID for SHA256 {
145    const OID: &'static [u32] = &[2, 16, 840, 1, 101, 3, 4, 2, 1];
146    const OID_DER: &'static [u8] =
147        &[0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01];
148}
149impl HashAlgParams for SHA256Params {
150    const OUTPUT_LEN: usize = 32;
151    const BLOCK_LEN: usize = 64;
152}
153impl SHA2Params for SHA256Params {}
154
155/*** SHA384 ***/
156impl HashAlgParams for SHA384 {
157    const OUTPUT_LEN: usize = 48;
158    const BLOCK_LEN: usize = 128;
159}
160/// The parameters for SHA384.
161#[derive(Clone)]
162pub struct SHA384Params;
163impl Algorithm for SHA384Params {
164    const ALG_NAME: &'static str = SHA384_NAME;
165    const MAX_SECURITY_STRENGTH: SecurityStrength = SecurityStrength::_192bit;
166}
167/// Assigned by NIST in the Computer Security Objects Register: id-sha384 { hashAlgs 2 }
168impl AlgorithmOID for SHA384 {
169    const OID: &'static [u32] = &[2, 16, 840, 1, 101, 3, 4, 2, 2];
170    const OID_DER: &'static [u8] =
171        &[0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x02];
172}
173impl HashAlgParams for SHA384Params {
174    const OUTPUT_LEN: usize = 48;
175    const BLOCK_LEN: usize = 128;
176}
177impl SHA2Params for SHA384Params {}
178
179/*** SHA512 ***/
180/// The parameters for SHA512.
181#[derive(Clone)]
182pub struct SHA512Params;
183impl HashAlgParams for SHA512 {
184    const OUTPUT_LEN: usize = 64;
185    const BLOCK_LEN: usize = 128;
186}
187impl Algorithm for SHA512Params {
188    const ALG_NAME: &'static str = SHA512_NAME;
189    const MAX_SECURITY_STRENGTH: SecurityStrength = SecurityStrength::_256bit;
190}
191impl HashAlgParams for SHA512Params {
192    const OUTPUT_LEN: usize = 64;
193    const BLOCK_LEN: usize = 128;
194}
195/// Assigned by NIST in the Computer Security Objects Register: id-sha512 { hashAlgs 3 }
196impl AlgorithmOID for SHA512 {
197    const OID: &'static [u32] = &[2, 16, 840, 1, 101, 3, 4, 2, 3];
198    const OID_DER: &'static [u8] =
199        &[0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x03];
200}
201impl SHA2Params for SHA512Params {}
202
203pub use sha256::SUSPENDED_SHA256_STATE_LEN;
204pub use sha512::SUSPENDED_SHA512_STATE_LEN;
bouncycastle_sha2/lib.rs

bouncycastle_sha2/
lib.rs
