fast-tlsh 0.1.9

Library to generate / parse / compare TLSH locality sensitive hashes
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

// SPDX-License-Identifier: Apache-2.0 OR MIT
// SPDX-FileCopyrightText: Copyright (C) 2024 Tsukasa OI <floss_ssdeep@irq.a4lg.com>.

//! The easy wrapper for generator functionalities (for `std` environment).

#![cfg(all(feature = "std", feature = "easy-functions"))]

use std::fs::File;
use std::io::Read;
use std::path::Path;

use crate::errors::GeneratorOrIOError;
use crate::generate::Generator;
use crate::macros::{invariant, optionally_unsafe};
use crate::params::ConstrainedFuzzyHashType;
use crate::{GeneratorType, Tlsh};

/// Constant temporary buffer size for "easy" functions.
const BUFFER_SIZE: usize = 1048576;

/// Generates a fuzzy hash from a given reader stream.
///
/// This is a common function grouping buffering part.
///
/// # Performance Consideration
///
/// It doesn't use [`BufReader`](std::io::BufReader) because the internal buffer
/// is large enough.  Note that the default buffer size of `BufReader` is
/// normally 8KiB (while [buffer size](BUFFER_SIZE) here has 1MiB).
#[inline]
fn hash_stream_common<R: Read, G: GeneratorType>(
    generator: &mut G,
    reader: &mut R,
) -> Result<G::Output, GeneratorOrIOError> {
    let mut buffer = vec![0u8; BUFFER_SIZE];
    loop {
        let len = reader.read(&mut buffer)?;
        if len == 0 {
            break;
        }
        optionally_unsafe! {
            invariant!(len <= buffer.len());
        }
        generator.update(&buffer[0..len]);
    }
    Ok(generator.finalize()?)
}

/// Generates a fuzzy hash from a given reader stream
/// (with specified output type).
///
/// # Example
///
/// ```
/// use std::fs::File;
///
/// type CustomTlsh = tlsh::hashes::Short;
///
/// fn main() -> Result<(), tlsh::errors::GeneratorOrIOError> {
///     let mut stream = File::open("data/examples/smallexe.exe")?;
///     let fuzzy_hash: CustomTlsh = tlsh::hash_stream_for(&mut stream)?;
///     let fuzzy_hash_str = fuzzy_hash.to_string();
///     assert_eq!(fuzzy_hash_str, "T140E0483A5DFC1B073D86A4A2C55A43");
///     Ok(())
/// }
/// ```
pub fn hash_stream_for<T: ConstrainedFuzzyHashType, R: Read>(
    reader: &mut R,
) -> Result<T, GeneratorOrIOError> {
    let mut generator = Generator::<T>::new();
    hash_stream_common(&mut generator, reader)
}

/// Generates a fuzzy hash from a given reader stream.
///
/// # Example
///
/// ```
/// use std::fs::File;
///
/// fn main() -> Result<(), tlsh::errors::GeneratorOrIOError> {
///     let mut stream = File::open("data/examples/smallexe.exe")?;
///     let fuzzy_hash = tlsh::hash_stream(&mut stream)?;
///     let fuzzy_hash_str = fuzzy_hash.to_string();
///     assert_eq!(fuzzy_hash_str, "T1FFE04C037F895471D42E5530499E47473757E5E456D28B13ED1944654C8534C7CE9E01");
///     Ok(())
/// }
/// ```
pub fn hash_stream<R: Read>(reader: &mut R) -> Result<Tlsh, GeneratorOrIOError> {
    hash_stream_for::<Tlsh, _>(reader)
}

/// Generates a fuzzy hash from a given file
/// (with specified output type).
///
/// # Example
///
/// ```
/// type CustomTlsh = tlsh::hashes::Short;
///
/// fn main() -> Result<(), tlsh::errors::GeneratorOrIOError> {
///     let fuzzy_hash: CustomTlsh = tlsh::hash_file_for("data/examples/smallexe.exe")?;
///     let fuzzy_hash_str = fuzzy_hash.to_string();
///     assert_eq!(fuzzy_hash_str, "T140E0483A5DFC1B073D86A4A2C55A43");
///     Ok(())
/// }
/// ```
pub fn hash_file_for<T: ConstrainedFuzzyHashType, P: AsRef<Path>>(
    path: P,
) -> Result<T, GeneratorOrIOError> {
    let mut file = File::open(path)?;
    let mut generator = Generator::new();
    hash_stream_common(&mut generator, &mut file)
}

/// Generates a fuzzy hash from a given file.
///
/// # Example
///
/// ```
/// fn main() -> Result<(), tlsh::errors::GeneratorOrIOError> {
///     let fuzzy_hash = tlsh::hash_file("data/examples/smallexe.exe")?;
///     let fuzzy_hash_str = fuzzy_hash.to_string();
///     assert_eq!(fuzzy_hash_str, "T1FFE04C037F895471D42E5530499E47473757E5E456D28B13ED1944654C8534C7CE9E01");
///     Ok(())
/// }
/// ```
pub fn hash_file<P: AsRef<Path>>(path: P) -> Result<Tlsh, GeneratorOrIOError> {
    hash_file_for::<Tlsh, _>(path)
}

mod tests;