tlsh2/
lib.rs

1//! TLSH
2//!
3//! A Rust implementation of the TLSH algorithm.
4//! The code is kept close to the original C++ version, to limit bugs and help
5//! maintainability.
6//!
7//! This crate is `no_std` and different configurations of bucket numbers and
8//! checksum length are handled as generics, making every configuration properly
9//! optimized.
10//!
11//! ```
12//! // The default builder uses 128 buckets and a 1-byte checksum.
13//! // Other builders are also available.
14//! let mut builder = tlsh2::TlshDefaultBuilder::new();
15//! builder.update(b"Sed ut perspiciatis unde omnis iste natus");
16//! builder.update(b"error sit voluptatem accusantium");
17//! let tlsh = builder.build()
18//!     .ok_or_else(|| "could not generate TLSH from payload")?;
19//!
20//! // Alternatively, a TLSH object can be generated directly from
21//! // a byte slice.
22//! let tlsh2 = tlsh2::TlshDefaultBuilder::build_from(
23//!     b"odit aut fugit, sed quia consequuntur magni dolores"
24//! ).ok_or_else(|| "could not generate TLSH from second payload")?;
25//!
26//! // Then, the TLSH object can be used to generated a hash or compute
27//! // distances
28//! assert_eq!(
29//!     tlsh.hash(),
30//!     b"T184A022B383C2A2A20ACB0830880CF0202CCAC080033A023800338\
31//!       A30B0880AA8E0BE38".as_slice(),
32//! );
33//! // The `diff` feature is required for this computation.
34//! #[cfg(feature = "diff")]
35//! assert_eq!(tlsh.diff(&tlsh2, true), 209);
36//! # Ok::<(), Box<dyn std::error::Error>>(())
37//! ```
38#![no_std]
39#![deny(clippy::all)]
40#![deny(unsafe_code)]
41#![deny(missing_docs)]
42#![deny(clippy::cargo)]
43
44mod pearson;
45mod quartile;
46mod tlsh;
47mod util;
48
49const BUCKETS: usize = 256;
50
51pub use crate::tlsh::{Tlsh, TlshBuilder};
52
53/// Builder with 256 buckets and a 1 byte checksum.
54pub type TlshBuilder256_1 = TlshBuilder<256, 1, 64, 136, 50>;
55/// TLSH with 256 buckets and a 1 byte checksum.
56pub type Tlsh256_1 = Tlsh<1, 136, 64>;
57
58/// Builder with 128 buckets and a 1 byte checksum.
59pub type TlshBuilder128_1 = TlshBuilder<128, 1, 32, 72, 50>;
60/// TLSH with 128 buckets and a 1 byte checksum.
61pub type Tlsh128_1 = Tlsh<1, 72, 32>;
62
63/// Builder with 48 buckets and a 1 byte checksum.
64pub type TlshBuilder48_1 = TlshBuilder<48, 1, 12, 32, 10>;
65/// TLSh with 48 buckets and a 1 byte checksum.
66pub type Tlsh48_1 = Tlsh<1, 32, 12>;
67
68/// Builder with 256 buckets and a 3 bytes checksum.
69pub type TlshBuilder256_3 = TlshBuilder<256, 3, 64, 140, 50>;
70/// TLSH with 256 buckets and a 3 bytes checksum.
71pub type Tlsh256_3 = Tlsh<3, 140, 64>;
72
73/// Builder with 128 buckets and a 3 bytes checksum.
74pub type TlshBuilder128_3 = TlshBuilder<128, 3, 32, 76, 50>;
75/// TLSH with 128 buckets and a 3 bytes checksum.
76pub type Tlsh128_3 = Tlsh<3, 76, 32>;
77
78/// Default builder, using 128 buckets and a 1 byte checksum.
79pub type TlshDefaultBuilder = TlshBuilder128_1;
80/// Default TLSH, using 128 buckets and a 1 byte checksum.
81pub type TlshDefault = Tlsh128_1;
tlsh2/lib.rs

tlsh2/
lib.rs
