Uses old Rust 2015
0.8.1 |
|
---|
#38 in #sha-3
520KB
242 lines
RustCrypto hashes
Collection of cryptographic hash functions written in pure Rust.
All algorithms reside in the separate crates and implemented using traits from
digest
crate. Additionally all crates do not
require the standard library (i.e. no_std
capable) and can be easily used for
bare-metal or WebAssembly programming.
Supported algorithms
Note: For new applications, or where compatibility with other existing standards is not a primary concern, we strongly recommend to use either BLAKE2, SHA-2 or SHA-3.
Name | Alt name | Crates.io | Documentation | Security Level |
---|---|---|---|---|
BLAKE2 | π | |||
GOST94 | GOST R 34.11-94 | π | ||
GrΓΈstl | Groestl | π | ||
MD2 | π | |||
MD4 | π | |||
MD5 β | π | |||
RIPEMD-160 | π | |||
SHA-1 β | π | |||
SHA-2 | π | |||
SHA-3 | Keccak | π | ||
Streebog | GOST R 34.11-2012 | π | ||
Whirlpool | π |
Security Level Legend
The following describes the security level ratings associated with each hash function (i.e. algorithms, not the specific implementation):
Heart | Description |
---|---|
π | No known successful attacks |
π | Theoretical break: security lower than claimed |
π | Attack demonstrated in practice: avoid if at all possible |
Minimum Supported Rust Version (MSRV)
All crates in this repository support Rust 1.21 or higher. In future minimally supported version of Rust can be changed, but it will be done with a minor version bump.
Crate names
Whenever possible crates are published under the the same name as the crate
folder. Owners of md5
and sha1
crates refused
(1,
2) to participate in this
project. This is why crates marked by β are published under
md-5
and sha-1
names respectively.
Usage
Let us demonstrate how to use crates in this repository using BLAKE2b as an example.
First add blake2
crate to your Cargo.toml
:
[dependencies]
blake2 = "0.8"
blake2
and other crates re-export digest
crate and Digest
trait for
convenience, so you don't have to add digest
crate as an explicit dependency.
Now you can write the following code:
use blake2::{Blake2b, Digest};
let mut hasher = Blake2b::new();
let data = b"Hello world!";
hasher.input(data);
// `input` can be called repeatedly and is generic over `AsRef<[u8]>`
hasher.input("String data");
// Note that calling `result()` consumes hasher
let hash = hasher.result();
println!("Result: {:x}", hash);
In this example hash
has type GenericArray<u8, U64>
, which is a generic
alternative to [u8; 64]
.
Alternatively you can use chained approach, which is equivalent to the previous example:
let hash = Blake2b::new()
.chain(b"Hello world!")
.chain("String data")
.result();
println!("Result: {:x}", hash);
If the whole message is available you also can use convinience digest
method:
let hash = Blake2b::digest(b"my message");
println!("Result: {:x}", hash);
Hashing Read
able objects
If you want to hash data from Read
trait (e.g. from file) you can rely on
implementation of Write
trait (requires enabled-by-default std
feature):
use blake2::{Blake2b, Digest};
use std::{fs, io};
let mut file = fs::File::open(&path)?;
let mut hasher = Blake2b::new();
let n = io::copy(&mut file, &mut hasher)?;
let hash = hasher.result();
println!("Path: {}", path);
println!("Bytes processed: {}", n);
println!("Hash value: {:x}", hash);
Hash-based Message Authentication Code (HMAC)
If you want to calculate Hash-based Message Authentication Code (HMAC),
you can use generic implementation from hmac
crate,
which is a part of the RustCrypto/MACs repository.
Generic code
You can write generic code over Digest
(or other traits from digest
crate)
trait which will work over different hash functions:
use digest::Digest;
// Toy example, do not use it in practice!
// Instead use crates from: https://github.com/RustCrypto/password-hashing
fn hash_password<D: Digest>(password: &str, salt: &str, output: &mut [u8]) {
let mut hasher = D::new();
hasher.input(password.as_bytes());
hasher.input(b"$");
hasher.input(salt.as_bytes());
output.copy_from_slice(hasher.result().as_slice())
}
use blake2::Blake2b;
use sha2::Sha256;
hash_password::<Blake2b>("my_password", "abcd", &mut buf);
hash_password::<Sha256>("my_password", "abcd", &mut buf);
If you want to use hash functions with trait objects, use digest::DynDigest
trait.
License
All crates licensed under either of
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.