1 // tlsh.h - TrendLSH Hash Algorithm 2 3 /* 4 * TLSH is provided for use under two licenses: Apache OR BSD. 5 * Users may opt to use either license depending on the license 6 * restictions of the systems with which they plan to integrate 7 * the TLSH code. 8 */ 9 10 /* ============== 11 * Apache License 12 * ============== 13 * Copyright 2013 Trend Micro Incorporated 14 * 15 * Licensed under the Apache License, Version 2.0 (the "License"); 16 * you may not use this file except in compliance with the License. 17 * You may obtain a copy of the License at 18 * 19 * http://www.apache.org/licenses/LICENSE-2.0 20 * 21 * Unless required by applicable law or agreed to in writing, software 22 * distributed under the License is distributed on an "AS IS" BASIS, 23 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 24 * See the License for the specific language governing permissions and 25 * limitations under the License. 26 */ 27 28 /* =========== 29 * BSD License 30 * =========== 31 * Copyright (c) 2013, Trend Micro Incorporated 32 * All rights reserved. 33 * 34 * Redistribution and use in source and binary forms, with or without modification, 35 * are permitted provided that the following conditions are met: 36 * 37 * 1. Redistributions of source code must retain the above copyright notice, this 38 * list of conditions and the following disclaimer. 39 * 40 * 2. Redistributions in binary form must reproduce the above copyright notice, 41 * this list of conditions and the following disclaimer in the documentation 42 * and/or other materials provided with the distribution. 43 44 * 3. Neither the name of the copyright holder nor the names of its contributors 45 * may be used to endorse or promote products derived from this software without 46 * specific prior written permission. 47 * 48 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 49 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 50 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 51 * IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 52 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 53 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 54 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 55 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 56 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 57 * OF THE POSSIBILITY OF SUCH DAMAGE. 58 */ 59 60 #ifndef HEADER_TLSH_H 61 #define HEADER_TLSH_H 62 63 #if defined WINDOWS || defined MINGW 64 #include "win_version.h" 65 #else 66 #include "version.h" 67 #endif 68 69 #ifndef NULL 70 #define NULL 0 71 #endif 72 73 #ifdef __cplusplus 74 75 class TlshImpl; 76 77 // Define TLSH_STRING_LEN_REQ, which is the string length of "T1" + the hex value of the Tlsh hash. 78 // BUCKETS_256 & CHECKSUM_3B are compiler switches defined in CMakeLists.txt 79 #if defined BUCKETS_256 80 #define TLSH_STRING_LEN_REQ 136 81 // changed the minimum data length to 256 for version 3.3 82 #define MIN_DATA_LENGTH 50 83 // added the -force option for version 3.5 84 // added the -conservatibe option for version 3.17 85 #define MIN_CONSERVATIVE_DATA_LENGTH 256 86 #endif 87 88 #if defined BUCKETS_128 89 #define TLSH_STRING_LEN_REQ 72 90 // changed the minimum data length to 256 for version 3.3 91 #define MIN_DATA_LENGTH 50 92 // added the -force option for version 3.5 93 // added the -conservatibe option for version 3.17 94 #define MIN_CONSERVATIVE_DATA_LENGTH 256 95 #endif 96 97 #if defined BUCKETS_48 98 // No 3 Byte checksum option for 48 Bucket min hash 99 #define TLSH_STRING_LEN 30 100 // changed the minimum data length to 256 for version 3.3 101 #define MIN_DATA_LENGTH 10 102 // added the -force option for version 3.5 103 #define MIN_CONSERVATIVE_DATA_LENGTH 10 104 #endif 105 106 #define TLSH_STRING_BUFFER_LEN (TLSH_STRING_LEN_REQ+1) 107 108 #ifdef WINDOWS 109 // 27/Nov/2020 110 // #include <WinFunctions.h> 111 #define TLSH_API 112 #else 113 #if defined(__SPARC) || defined(_AS_MK_OS_RH73) 114 #define TLSH_API 115 #else 116 #define TLSH_API __attribute__ ((visibility("default"))) 117 #endif 118 #endif 119 120 class TLSH_API Tlsh{ 121 122 public: 123 Tlsh(); 124 Tlsh(const Tlsh& other); 125 126 /* allow the user to add data in multiple iterations */ 127 void update(const unsigned char* data, unsigned int len); 128 129 /* to signal the class there is no more data to be added */ 130 void final(const unsigned char* data = NULL, unsigned int len = 0, int fc_cons_option = 0); 131 132 /* to get the hex-encoded hash code */ 133 const char* getHash(int showvers=0) const ; 134 135 /* to get the hex-encoded hash code without allocating buffer in TlshImpl - bufSize should be TLSH_STRING_BUFFER_LEN */ 136 const char* getHash(char *buffer, unsigned int bufSize, int showvers=0) const; 137 138 /* to bring to object back to the initial state */ 139 void reset(); 140 141 // access functions 142 int Lvalue(); 143 int Q1ratio(); 144 int Q2ratio(); 145 int Checksum(int k); 146 int BucketValue(int bucket); 147 148 /* calculate difference */ 149 /* The len_diff parameter specifies if the file length is to be included in the difference calculation (len_diff=true) or if it */ 150 /* is to be excluded (len_diff=false). In general, the length should be considered in the difference calculation, but there */ 151 /* could be applications where a part of the adversarial activity might be to add a lot of content. For example to add 1 million */ 152 /* zero bytes at the end of a file. In that case, the caller would want to exclude the length from the calculation. */ 153 int totalDiff(const Tlsh *, bool len_diff=true) const; 154 155 /* validate TrendLSH string and reset the hash according to it */ 156 int fromTlshStr(const char* str); 157 158 /* check if Tlsh object is valid to operate */ 159 bool isValid() const; 160 161 /* display the contents of NOTICE.txt */ 162 static void display_notice(); 163 164 /* Return the version information used to build this library */ 165 static const char *version(); 166 167 // operators 168 Tlsh& operator=(const Tlsh& other); 169 bool operator==(const Tlsh& other) const; 170 bool operator!=(const Tlsh& other) const; 171 172 ~Tlsh(); 173 174 private: 175 TlshImpl* impl; 176 }; 177 178 #ifdef TLSH_DISTANCE_PARAMETERS 179 void set_tlsh_distance_parameters(int length_mult_value, int qratio_mult_value, int hist_diff1_add_value, int hist_diff2_add_value, int hist_diff3_add_value); 180 #endif 181 182 #endif 183 184 #endif 185 186