crypto_hash/
lib.rs

1// Copyright (c) 2015, 2016, 2017 Mark Lee
2//
3// Permission is hereby granted, free of charge, to any person obtaining a copy
4// of this software and associated documentation files (the "Software"), to deal
5// in the Software without restriction, including without limitation the rights
6// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7// copies of the Software, and to permit persons to whom the Software is
8// furnished to do so, subject to the following conditions:
9//
10// The above copyright notice and this permission notice shall be included in
11// all copies or substantial portions of the Software.
12//
13// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
16// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
19// THE SOFTWARE.
20
21//! A set of [cryptographic hash
22//! functions](https://en.wikipedia.org/wiki/Cryptographic_hash_function) provided by the operating
23//! system, when available.
24//!
25//! The purpose of this crate is to provide access to hash algorithms with as few dependencies as
26//! possible. This means that when possible, the library uses the hashing functions that are
27//! provided by the given operating system's bundled cryptographic libraries.
28//!
29//! # Supported Implementations
30//!
31//! By operating system:
32//!
33//! * Windows: `CryptoAPI`
34//! * Mac OS X: `CommonCrypto`
35//! * Linux/BSD/etc.: `OpenSSL`
36//!
37//! # Supported Algorithms
38//!
39//! * MD5
40//! * SHA1
41//! * SHA256
42//! * SHA512
43
44#![warn(missing_docs)]
45
46#[cfg(any(target_os = "macos", target_os = "ios"))]
47extern crate commoncrypto;
48extern crate hex;
49#[cfg(not(any(target_os = "macos", target_os = "ios", target_os = "windows")))]
50extern crate openssl;
51#[cfg(target_os = "windows")]
52extern crate winapi;
53
54use std::io::Write;
55
56#[cfg(any(target_os = "macos", target_os = "ios"))]
57#[path = "imp/commoncrypto.rs"]
58mod imp;
59#[cfg(target_os = "windows")]
60#[path = "imp/cryptoapi.rs"]
61mod imp;
62#[cfg(not(any(target_os = "macos", target_os = "ios", target_os = "windows")))]
63#[path = "imp/openssl.rs"]
64mod imp;
65
66mod test;
67
68pub use imp::Hasher;
69
70/// Available cryptographic hash functions.
71#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
72pub enum Algorithm {
73    /// Popular message digest algorithm, only available for backwards compatibility purposes.
74    MD5,
75    /// SHA-1 algorithm from NIST FIPS, only available for backwards compatibility purposes.
76    SHA1,
77    /// SHA-2 family algorithm (256 bits).
78    SHA256,
79    /// SHA-2 family algorithm (512 bits).
80    SHA512,
81}
82
83/// Helper function for `Hasher` which generates a cryptographic digest from the given
84/// data and algorithm.
85///
86/// # Examples
87///
88/// ```rust
89/// use crypto_hash::{Algorithm, digest};
90///
91/// let data = b"crypto-hash";
92/// let result = digest(Algorithm::SHA256, data);
93/// let expected =
94///     b"\xfd\x1a\xfb`\"\xcdMG\xc8\x90\x96\x1cS9(\xea\xcf\xe8!\x9f\x1b%$\xf7\xfb*a\x84}\xdf\x8c'"
95///     .to_vec();
96/// assert_eq!(expected, result)
97/// ```
98pub fn digest(algorithm: Algorithm, data: &[u8]) -> Vec<u8> {
99    let mut hasher = imp::Hasher::new(algorithm);
100    hasher.write_all(data).expect("Could not write hash data");
101    hasher.finish()
102}
103
104/// Helper function for `Hasher` which generates a cryptographic digest serialized in
105/// hexadecimal from the given data and algorithm.
106///
107/// # Examples
108///
109/// ```rust
110/// use crypto_hash::{Algorithm, hex_digest};
111///
112/// let data = b"crypto-hash";
113/// let result = hex_digest(Algorithm::SHA256, data);
114/// let expected = "fd1afb6022cd4d47c890961c533928eacfe8219f1b2524f7fb2a61847ddf8c27";
115/// assert_eq!(expected, result)
116/// ```
117pub fn hex_digest(algorithm: Algorithm, data: &[u8]) -> String {
118    hex::encode(digest(algorithm, data))
119}
crypto_hash/lib.rs

crypto_hash/
lib.rs
