1 2**** FUZZY HASHING API **** 3 4This file documents the fuzzy hashing API. Information on how to use the 5fuzzy hashing program ssdeep can be found in the man page. On *nix 6systems you can view this file with: 7 8$ man ./ssdeep.1 9 10Windows users can get the ssdeep usage information from README.TXT. 11 12 13** Using the API in Your Own Progrms ** 14 15You can use the fuzzy hashing API in your own programs by doing 16the following: 17 181. Include the fuzzy hashing header 19 20#include <fuzzy.h> 21 22 232. Call one of the functions: 24 25* Fuzzy hashing a buffer of text: 26 27int fuzzy_hash_buf(const unsigned char *buf, 28 uint32_t buf_len, 29 char *result); 30 31This function computes the fuzzy hash of the buffer 'buf' and stores the 32result in result. You MUST allocate result to hold FUZZY_MAX_RESULT 33characters before calling this function. The length of the buffer should 34be passed in via buf_len. It is the user's responsibility to append the 35filename, if any, to the output. The function returns zero on success, 36one on error. 37 38 39* Fuzzy hashing a file: 40 41There are in fact two ways to fuzzy hash a file. If you already 42have an open file handle you can use: 43 44int fuzzy_hash_file(FILE *handle, 45 char *result); 46 47This function computes the fuzzy hash of the file pointed to by handle 48and stores the result in result. You MUST allocate result to hold 49FUZZY_MAX_RESULT characters before calling this function. It is the 50user's responsibility to append the filename to the output. 51The function returns zero on success, one on error. 52 53The other function to hash a file takes a file name: 54 55int fuzzy_hash_filename(const char * filename, 56 char * result); 57 58Like the function above, this function stores the fuzzy hash result 59in the parameter result. You MUST allocate result to hold 60FUZZY_MAX_RESULT characters before calling this function. 61 62 63* Compare two fuzzy hash signatures: 64 65int fuzzy_compare(const char *sig1, const char *sig2); 66 67This function returns a value from 0 to 100 indicating the match 68score of the two signatures. A match score of zero indicates the \ 69signatures did not match. 70 71 723. Compile 73 74To compile the program using gcc: 75 76 $ gcc -Wall -I/usr/local/include -L/usr/local/lib sample.c -lfuzzy 77 78Using mingw: 79 80 C:\> gcc -Wall -Ic:\path\to\includes sample.c fuzzy.dll 81 82Using Microsoft Visual C (MSVC): 83 84To paraphrase the MinGW documentation, 85http://www.mingw.org/mingwfaq.shtml#faq-msvcdll: 86 87The Windows ssdeep package includes a Win32 DLL and a .def file. Although 88MSVC users can't use the DLL directly, they can easily create a .lib file 89using the Microsoft LIB tool: 90 91 C:\> lib /machine:i386 /def:fuzzy.def 92 93You can then compile your program using the resulting library: 94 95 C:\> cl sample.c fuzzy.lib 96 97 98 99** Sample Program ** 100 101A sample program that uses the API is in sample.c. 102 103 104 105** See Also ** 106 107- Jesse D. Kornblum, "Identifying almost identical files using context 108triggered piecewise hashing", Digital Investigaton, 3(S):91-97, 109September 2006, http://dx.doi.org/10.1016/j.diin.2006.06.015, 110The Proceedings of the 6th Annual Digital Forensic Research Workshop 111