You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

ReadMe.html 32KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562
  1. <!-- Copyright 2009, ARM Research Labs, LLC -->
  2. <html>
  3. <body>
  4. <font face="sans-serif">
  5. <h1>Message Sniffer SDK for Win* V3.1</h1>
  6. <h2>Contents</h2>
  7. </font><h3><ol>
  8. <p><font face="sans-serif">Introduction</font></p>
  9. <li><font face="sans-serif"><a href="#Begin">Before you begin!</a></font></li>
  10. <li><font face="sans-serif"><a href="#Contents">Contents of the SDK</a></font></li>
  11. <li><font face="sans-serif"><a href="#Description">SNFMulti DLL Description</a></font></li>
  12. <li><font face="sans-serif"><a href="ChangeLog.txt">Change Log</a></font></li>
  13. <p><font face="sans-serif">Setup notes and important instructions</font></p>
  14. <li><font face="sans-serif"><a href="SNFServer_readme.txt">SNFServer Setup Readme</a></font></li>
  15. <li><font face="sans-serif"><a href="SNFClient_readme.txt">SNFClient Setup Readme</a></font></li>
  16. <p><font face="sans-serif">Code Samples</font></p>
  17. <li><font face="sans-serif"><a href="32bitDll/snfmultidll.h">C Header File (snfmultidll.h></a></font></li>
  18. <li><font face="sans-serif"><a href="32bitDll/libsnfmulti.def">Module Definition File (libsnfmulti.def)</a></font></li>
  19. <li><font face="sans-serif"><a href="C++/main.cpp">C++ Sample Code</a></font></li>
  20. <li><font face="sans-serif"><a href="VB/SNFMulti_in_VB.Net.txt">VB.Net Sample Code</a></font></li>
  21. <p><font face="sans-serif">API Reference - Functions listed in the order they should be used</font></p>
  22. <li><font face="sans-serif"><a href="#startupSNF">startupSNF()</a> - Initializes the SNF engine and loads the rule base</font></li>
  23. <li><font face="sans-serif"><a href="#startupSNFAuthenticated">startupSNFAuthenticated()</a> - Initializes SNF with license info</font></li>
  24. <li><font face="sans-serif"><a href="#setThrottle">setThrottle()</a> - Sets a concurrent thread limit (if desired)</font></li>
  25. <li><font face="sans-serif"><a href="#testIP">testIP()</a> - Returns the GBUdb reputation range for an IP</font></li>
  26. <li><font face="sans-serif"><a href="#getIPReputation">getIPReputation()</a> - Returns IP Reputation Figure for an IP</font></li>
  27. <li><font face="sans-serif"><a href="#scanBuffer">scanBuffer()</a> - Scans a message buffer</font></li>
  28. <li><font face="sans-serif"><a href="#scanFile">scanFile()</a> - Scans a message file</font></li>
  29. <li><font face="sans-serif"><a href="#getScanXHeaders">getScanXHeaders()</a> - Returns the scan result and XHeaders</font></li>
  30. <li><font face="sans-serif"><a href="#getScanXMLLog">getScanXMLLog()</a> - Returns the scan result and XML Log data</font></li>
  31. <li><font face="sans-serif"><a href="#getScanClassicLog">getScanClassicLog()</a> - Returns the scan result and Classic Log Data</font></li>
  32. <li><font face="sans-serif"><a href="#getScanResult">getScanResult()</a> - Returns the scan result (nothing else)</font></li>
  33. <li><font face="sans-serif"><a href="#closeScan">closeScan()</a> - Closes the scan and releases resources</font></li>
  34. <li><font face="sans-serif"><a href="#shutdownSNF">shutdownSNF()</a> - Shuts down the SNF engine</font></li>
  35. <p><font face="sans-serif">Miscellaneous</font></p>
  36. <li><font face="sans-serif"><a href="#ResultCodes">Result Codes</a> - Error and Scan Result Mnemonics</font></li>
  37. </ol></h3><font face="sans-serif">
  38. <hr/>
  39. <a name="Begin"><h3>Before you begin!</h3></a>
  40. <p>This SDK contains a complete Message Sniffer engine. You MUST be familiar with that engine
  41. before you can effectively use this SDK. If you do not already have an OEM license or trial
  42. SNF rule base license then please <a href="http://www.armresearch.com/">visit our web site first
  43. and get one!</a> The engine won't run without it.</p>
  44. <p>We highly recommend that you have some experience with our SNFServer and SNFClient applications
  45. before you begin writing your own or begin integrating the SNF engine into your own software.</p>
  46. <p>We're not saying it's hard to do -- quite the opposite actually, BUT SNF is a sophisticated
  47. piece of software with a lot of capabilities and options. You will have much better results
  48. if you are familiar with these before you begin ;-)</p>
  49. <hr/>
  50. <a name="Contents"><h3>Contents of the SDK</h3></a>
  51. <p>This SDK contains the following:
  52. <ol>
  53. <li><font face="sans-serif">Documentation files, including
  54. this file.</font></li>
  55. <li><font face="sans-serif">DLLs (both 32 bit and 64 bit
  56. versions) and the required header files (in
  57. directory <b>include</b>).</font></li>
  58. <li><font face="sans-serif">Sample programs in C++ (in
  59. directory <b>CPPSample</b>), C# (<b>CSSample</b>), and Visual
  60. Basic (<b>VBSample</b>).</font></li>
  61. <li><font face="sans-serif">VS 2008 Solution files to build
  62. the sample program in C++ (in
  63. directory <b>VS2008CPPSample</b>), in C#
  64. (<b>VS2008CSSample</b>), and Visual Basic
  65. (<b>VS2008VBSample</b>).<br>
  66. The <b>VS2008CPPSample\README</b> contains instructions for
  67. creating the SNFMulti import libraries for use with VS 2008.
  68. </font></li>
  69. <li><font face="sans-serif">Other applications
  70. (<b>curl</b>, <b>SNFClient</b>, and <b>getRulebase</b>) and
  71. configuration files needed to support SNF
  72. operation.</font></li>
  73. </ol>
  74. There are also directions for building VS 2008 import libraries in <b>VS2008CPPSample\README</b>.
  75. </p>
  76. <hr/>
  77. <a name="Description"><h3>SNFMulti DLL Description</h3></a>
  78. <p>The SNF SDK for Win* is based on a DLL. The DLLs for both the 32 bit
  79. and 64 bit versions are included here.
  80. </p>
  81. <p>The DLL contains the entire SNFServer engine and provides a simple API for starting the
  82. engine, scanning messages, and retrieving the results. Since the entire SNFServer engine is
  83. included you also have the option of using the SNFClient utility once your application has
  84. started the SNF engine. You can also make calls to the engine using the XCI protocol (which
  85. is how SNFClient does it's work)</p>
  86. <p>Of course the best way to use the DLL is to perform scans directly through the API. The
  87. best performance can be achieved by scanning a message in memory via the scanBuffer() function
  88. since this can be done at the full speed of the processor without waiting for IO operations.</p>
  89. <p>The DLL is fully thread-safe so you can perform as many concurrent scans as you wish. Also,
  90. just in case it will make things easier for you, the DLL provides a throttling function which
  91. can limit the number of concurrent scans. (It won't unless you ask it to.)</p>
  92. <p>The general form of an application using the DLL will first start the engine, then
  93. optionally set the throttle, then perform scans (perform a scan, get results, close the scan, repeat),
  94. and finally it will shutdown the engine.</p>
  95. <p>Since the DLL contains the entire SNFServer engine, it can (and must) be configured in
  96. exactly the same way as SNFServer. <a href="http://www.armresearch.com/support/articles/software/snfServer/config/index.jsp">
  97. Documentation for configuring SNFServer can be found on our web site.</a></p>
  98. <p>New in snfmulti.dll V3.0!</p>
  99. <p>OEM developers can now protect their licenseID and Authentication string by providing it directly to the SNF engine at run-time. When combined with an internal mechanism for downloading rule base files this makes it practical to control SNF license information entirely within the OEM's application. <a href="#startupSNFAuthenticated">See startupSNFAuthenticated() for details.</a></p>
  100. <hr/>
  101. <a name="startupSNF"><h3>int startupSNF(char* path);</h3></a>
  102. <p>This function initializes the SNF scanning engine using the configuration file provided.
  103. The configuration file identifies all of the operational parameters for the SNF engine including
  104. the location of the working directories and rule base file, SNF license information, and
  105. much more. <a href="http://www.armresearch.com/support/articles/software/snfServer/config/index.jsp">
  106. See our web site for details on configuring the SNF engine.</a></p>
  107. <dl>
  108. <dd><b>path</b> = The full path to the snf_engine.xml file as a null terminated string.</dd>
  109. <dd><b>returns</b> snf_SUCCESS when successful, otherwise see <a href="#ResultCodes">Error Codes</a>.</dd>
  110. </dl>
  111. <hr/>
  112. <a name="startupSNFAuthenticated"><h3>int startupSNFAuthenticated(char* path, char* lic, char* auth);</h3></a>
  113. <p>This function initializes the SNF scanning engine using the configuration file and authentication
  114. information provided. When SNF is started with this function the identity.xml file can be omitted and
  115. the identity= attribute of the &lt;node/&gt; element in snf_engine.xml can be omitted. This allows OEM
  116. developers to protect their authentication string by retrieving it from an encrypted source at run-time
  117. and providing it directly to the SNF engine.</p>
  118. <p>In all other ways the SNF engine is configured in the same as when using <a href="#startupSNF">startupSNF() (see above)</a></p>
  119. <p>Note that if you intend to use this mechanism to protect your SNF license information you will also need to
  120. address the mechanism you use to download and verify rule base files. Either build a mechanism to download and
  121. authenticate your rule base file without exposing your authentication string or you might modify the existing
  122. getRulebase script to remove the snf2check operation and the associated authentication string. The SNF engine will
  123. check all rule base files before they are loaded for scanning and will refuse to load a rule base file that does
  124. not authenticate properly.</p>
  125. <dl>
  126. <dd><b>path</b> = The full path to the snf_engine.xml file as a null terminated string.</dd>
  127. <dd><b>lic</b> = The 8 character license id as a null terminated string.</dd>
  128. <dd><b>auth</b> = The 16 character authentication string as a null terminated string.</dd>
  129. <dd><b>returns</b> snf_SUCCESS when successful, otherwise see <a href="#ResultCodes">Error Codes</a>.</dd>
  130. </dl>
  131. <hr/>
  132. <a name="setThrottle"><h3>int setThrottle(int Threads);</h3></a>
  133. <p>This function establishes a limit on the number of concurrent scans that can run. Any additional
  134. threads will block until at least one of the active scans is completed.</p>
  135. <p>The default value for the throttle setting is zero. When the throttle is set to zero then no limits
  136. are placed on the number of concurrent scans. In this mode the application must limit the number of
  137. concurrent scans.</p>
  138. <dl>
  139. <dd><b>Threads</b> = The number of concurrent scans allowed.</dd>
  140. <dd><b>returns</b> the number of Threads if successful otherwise snf_ERROR_EXCEPTION.</dd>
  141. </dl>
  142. <hr/>
  143. <a name="testIP"><h3>int testIP(unsigned long int IPToCheck);</h3></a>
  144. <p>This function tests an IP against the GBUdb. This function returns very quickly and can be called
  145. as often as required without any follow-up actions as long as the SNF Engine is active (between startupSNF()
  146. and shutdownSNF()). This function is thread-safe and does not interfere with other scanning functions.</p>
  147. <p>GBUdb gathers it's statistics based on the message scans that are performed. Information about those
  148. scans is also shared with other SNF nodes approximately once every minute. No external queries are
  149. performed to gather GBUdb data. As a result GBUdb can only provide an IP reputation for IPs that sourced
  150. messages scanned by this SNF node.</p>
  151. <p>Put another way - GBUdb does not work like a conventional real-time black list. Message scans must
  152. be performed in order for GBUdb to provide IP reputation information.</p>
  153. <p>For more information on how GBUdb works visit the
  154. <a href="http://www.armresearch.com/support/articles/technology/GBUdb/index.jsp">
  155. GBUdb Technology section of our web site.</a></p>
  156. <dl>
  157. <dd><b>IPToCheck</b> = The IP to test.</dd>
  158. <dd><b>returns</b> an integer representing the GBUdb Range associated with the IP if successful
  159. otherwise snf_ERROR_EXCEPTION.</dd>
  160. </dl>
  161. <h4>GBUdb Range MNemonics from enum snfIPRange</h4>
  162. <dl>
  163. <dd>Unknown, snf_IP_Unknown = 0</dd>
  164. <dd>White, snf_IP_White = 1</dd>
  165. <dd>Normal, snf_IP_Normal = 2</dd>
  166. <dd>New, snf_IP_New = 3</dd>
  167. <dd>Caution, snf_IP_Caution = 4</dd>
  168. <dd>Black, snf_IP_Black = 5</dd>
  169. <dd>Truncate, snf_IP_Truncate = 6</dd>
  170. </dl>
  171. <hr/>
  172. <a name="getIPReputation"><h3>double getIPReputation(unsigned long int IPToCheck);</h3></a>
  173. <p>This function returns a number representing the overall reputation of the IP based on local GBUdb statistics.
  174. This number (Reputation Figure) can be easily manipulated to provide additional weight values in systems that combine
  175. multiple tests using a weight based scoring system. The Reputation Figure is calculated by combining the Probability figure and the Confidence figure using the formula:</p>
  176. <pre>R = sign(P) * sqrt(abs(P * C))</pre>
  177. <p>This function returns very quickly and can be called as often as required without any follow-up actions as long
  178. as the SNF Engine is active (between startupSNF...() and shutdownSNF()). This function is thread-safe and does not interfere with other scanning functions.</p>
  179. <dl>
  180. <dd><b>IPToCheck</b> = The IP to test.</dd>
  181. <dd><b>returns</b> a number between -1.0 and +1.0 representing the combined probability that the IP will produce spam.</dd>
  182. </dl>
  183. <h4>Converting IP Reputation Figures To Weights</h4>
  184. <p>There are a number of ways to convert a Reputation figure to a weight value. The simplest is to simply multiply
  185. the Reputation figure by the maximum weight you wish to give to this test.</p>
  186. <pre>SimpleWeight = R * MaxReputationWeight</pre>
  187. <p>Since many legitimate ISPs also produce a lot of spam it might be useful to apply a bias to this weight so that
  188. these systems appear closer to zero. For example if you applied a maximum weight of 10 and found that many ISPs
  189. regularly scored 5 or more then you might add a Bias of -5 to bring those systems toward zero.</p>
  190. <pre>BiasedWeight = (R * MaxReputationWeight) + Bias</pre>
  191. <p>A more sophisticated system might allow for different weights on the positive and negative going Reputation
  192. figures so that the amount of negative or positive weight that can be applied can be adjusted independently. Such
  193. a system might also wish to apply a bias directly to the reputation figure before doing that calculation so that
  194. the zero point can be adjusted to compensate for averages.</p>
  195. <p>In a system like this if legitimate ISPs tended to get a Reputation Figure of 0.5 then the bias might be -0.5
  196. so that this would become the zero point. Then the positive and negative weight factors could be adjusted so that
  197. the desired maximum and minimum weights can be achieved... Note that in this scenario the positive and negative
  198. weight settings are not maximum values.
  199. <pre>SplitWeight = (0 > (R + Bias)) ? ((R + Bias) * NegativeWeightFactor) : ((R + Bias) * PositiveWeightFactor)
  200. MaximumNegativeWeight is given by (-1.0 + Bias) * NegativeWeightFactor
  201. MaximumPositiveWeight is given by (+1.0 + Bias) * PositiveWeightFactor
  202. When R + Bias == 0.0, the weight will be 0.</pre>
  203. <p>The most sophisticated system might provide a graphic interface that maps the reputation figure directly
  204. to a desired weight. This would allow the user to shape the effect of the Reputation figure any way they wish in
  205. order to gain very tight control over their systems accuracy.</p>
  206. <hr/>
  207. <a name="scanBuffer"><h3>int scanBuffer(unsigned char* Bfr, int Length, char* Name, int Setup);</h3></a>
  208. <p>This function scans an SMTP message from a buffer. A scan result block is allocated for the scan
  209. and a handle representing the scan result block is returned. The application can then use this handle to retrieve
  210. the scan results using the get...() functions. When the application is finished it MUST release the
  211. scan result block with a call to closeScan().</p>
  212. <p>The message buffer is expected to contain the raw SMTP data for the message with the local Received:
  213. header at the top. The message should not be broken into MIME segments before it is scanned by SNFMulti.
  214. This is important because Message Sniffer examines the entire message as well as how the message was
  215. assembled by the originating system. Any additional processing is both unnecessary and may remove subtle
  216. defects and artifacts that will help Message Sniffer classify the message.</p>
  217. <p>If the message is particularly large it is acceptable to scan only the first 32K bytes of the message.
  218. This means that if the calling application wants to scan a large incoming message before it has received
  219. all of the DATA during the SMTP connection then it can scan the first 32K of the message and potentially
  220. reject the remainder based on the scan result.</p>
  221. <p>When the application is finished with the results from this scan it must release the scan result block
  222. with a call to closeScan(). Scan result blocks are allocated as needed and then recycled in order to improve
  223. performance. If the application fails to close the scan result blocks then the DLL will continue to
  224. allocate additional blocks until there is no more RAM.</p>
  225. <p>The entire scan is performed before this function returns. After that the scanning thread is no longer
  226. considered to be active. The resulting scan result buffer may be accessed as often as needed to gather
  227. results data from this scan without impacting any other scan operations.</p>
  228. <p>Any number of scan...() operations may be active concurrently up to the limits of the platform.</p>
  229. <p>The scanBuffer() function accepts two additional parameters that are passed on to the logging system
  230. to aid in debugging.</p>
  231. <p>The Name parameter is a null terminated string containing an identifier for the
  232. message being scanned. This can be any name that can be used later to identify this particular message
  233. in the log files such as a serial number, unique hash, or the message-id. For example, when the
  234. scanFile() function is called this parameter is filled in with the path to the file that was scanned.</p>
  235. <p>The Setup parameter is an integer representing the number of milliseconds spent so far setting up
  236. the message to be scanned. This can be any useful metric - but generally it should represent how much
  237. time the system has spent working on preparing and evaluating the message so far. For example, when the
  238. scanFile() function is called this value is automatically established with the amount of time spent
  239. opening and reading the message file.</p>
  240. <p><b>IMPORTANT:</b> SNF expects to identify the source IP for the message by searching Received: headers
  241. in the message. The application must ensure that the local Received: header is present as the first
  242. Received: header in the message in order for this search to be accurate. If necessary the calling application can
  243. simulate the local received header using the following minimal form:</p>
  244. <p><pre>Received: from connecting.mta.example.com [12.34.56.78] by this.scanning.system</pre></p>
  245. <p>where <b><i>connecting.mta.example.com</i></b> is the optional reverse DNS resolved for the connecting MTA;
  246. <b><i>12.34.56.78</i></b> is the IP of the connecting MTA; and <b><i>by this.scanning.system</i></b> is an optional
  247. reference to the calling application.</p>
  248. </font><dl>
  249. <dd><font face="sans-serif"><b>Bfr</b> = a pointer to the buffer that is to be scanned.</font></dd>
  250. <dd><font face="sans-serif"><b>Length</b> = the length of the message buffer in bytes.</font></dd>
  251. <dd><font face="sans-serif"><b>Name</b> = a message identifier as a null terminated string.</font></dd>
  252. <dd><font face="sans-serif"><b>Setup</b> = the time in milliseconds already spent setting up this message for scanning.</font></dd>
  253. <dd><font face="sans-serif"><b>returns</b> a handle to the scan result block upon success otherwise an error code:
  254. </font><dl>
  255. <dd><font face="sans-serif">snf_ERROR_NO_HANDLE - There was a problem allocating a scan result block.</font></dd>
  256. <dd><font face="sans-serif">snf_ERROR_SCAN_FAILED - There was a problem performing the scan.</font></dd>
  257. </dl>
  258. <p><font face="sans-serif">In general a result > 0 indicates a valid scan handle and a result <= 0 indicates an error.
  259. NOTE that the scan may have failed even if you get a valid handle. The scan result code you retrieve
  260. from get...() may indicate an error. <a href="#ResultCodes">See Result Codes</a> for details.</font></p>
  261. </dd>
  262. </dl><font face="sans-serif">
  263. <hr/>
  264. <a name="scanFile"><h3>int scanFile(char* FilePath, int Setup);</h3></a>
  265. <p>This function scans an SMTP message from a file. A scan result block is allocated for the scan
  266. and a handle representing the results is returned. The application can then use this handle to retrieve
  267. the scan results using the get...() functions. When the application is finished it MUST release the
  268. scan result block with a call to closeScan().</p>
  269. <p>The scanFile() function is nearly identical to the <a href="#scanBuffer">scanBuffer() function (see above)</a>
  270. except that this function accepts the path to a file (null terminated string) instead of a pointer to a message
  271. buffer.</p>
  272. <p>One other key difference with between scanBuffer() and scanFile() is that the SNF engine can be configured
  273. to inject it's X- headers when scanFile() is used. These same X- headers are available to the calling application
  274. when using scanBuffer(), however if the application wishes to pass the message file on to other additional
  275. scanners and external processes then scanFile() might be more convenient.</p>
  276. <p>NOTE: There are significant performance implications to scanning files and injecting headers. Each time
  277. headers are injected into a message the message file must be rewritten. For optimal performance it is best
  278. to collect headers from scanning tools before writing the message to disk so that the message only needs to
  279. be written once. Extra file IO is the cost of the convenience of passing a message file to external processes.</p>
  280. <p>The Setup time passed to scanFile() will be added to the time required to open and read the message file
  281. prior to scanning. This value will be passed on to the logging system. For example, the calling application
  282. might include the number of milliseconds required to perform any previous message testing and the time it
  283. has taken to create a temporary message file for scanning. The log will then reflect the complete setup time
  284. separately from the time required to perform the SNF message scan.</p>
  285. <p>The FilePath will be passed on to the logging system to identify this message scan in the logs.</p>
  286. </font><dl>
  287. <dd><font face="sans-serif"><b>FilePath</b> = The full path (a null terminated string) to the message file to be scanned.</font></dd>
  288. <dd><font face="sans-serif"><b>Setup</b> = The time in milliseconds spent so far preparing this message to be scanned.</font></dd>
  289. <dd><font face="sans-serif"><b>returns</b> a handle to the scan result block upon success otherwise an error code:
  290. </font><dl>
  291. <dd><font face="sans-serif">snf_ERROR_NO_HANDLE - There was a problem allocating a scan result block.</font></dd>
  292. <dd><font face="sans-serif">snf_ERROR_SCAN_FAILED - There was a problem performing the scan.</font></dd>
  293. </dl>
  294. <p><font face="sans-serif">In general a result > 0 indicates a valid scan handle and a result <= 0 indicates an error.
  295. NOTE that the scan may have failed even if you get a valid handle. The scan result code you retrieve
  296. from get...() may indicate an error. <a href="#ResultCodes">See Result Codes</a> for details.</font></p>
  297. </dd>
  298. </dl><font face="sans-serif">
  299. <hr/>
  300. <a name="getScanXHeaders"><h3>int getScanXHeaders(int ScanHandle, char** Bfr, int* Length);</h3></a>
  301. <p>This function returns the scan result code <a href="#ResultCodes">(see Result Codes)</a> and a pointer
  302. to a buffer containing any X- headers that were produced for the scan associated with the ScanHandle.</p>
  303. <p>The function is passed a valid ScanHandle which identifies the scan result block to query; the address of
  304. a char* which will be changed to point to a buffer containing any X- headers that
  305. were produced; and the address of an integer which will be changed to the length of the
  306. X- headers buffer.</p>
  307. <p>If no X- headers were produced for the scan then the pointer Bfr will point to a safe empty string
  308. and Length will be set to zero. Put another way, Bfr and Length will be consistent with an empty null terminated
  309. string.</p>
  310. <p>The char* Bfr and the int Length will remain valid until closeScan() is called for this ScanHandle.</p>
  311. <p>In order for X- headers to be produced the engine must be configured properly. For details visit the
  312. <a href="http://www.armresearch.com/support/articles/software/snfServer/config/node/logs/scan/xheaders/index.jsp">
  313. XHeader configuration documentation</a> on our web site.</p>
  314. <dl>
  315. <dd><b>ScanHandle</b> = a valid scan handle from scanBuffer() or scanFile().</dd>
  316. <dd><b>Bfr</b> = a pointer to a char* where the char* will be changed to point to the XHeaders.</dd>
  317. <dd><b>Length</b> = a pointer to an int where the int will be changed to the length of the XHeaders.</dd>
  318. <dd><b>returns</b> the scan result code upon success otherwise an error code:
  319. <dl>
  320. <dd>snf_ERROR_NO_HANDLE - The ScanHandle is not valid.</dd>
  321. <dd>snf_ERROR_EXCEPTION - There was a problem retrieving the data.</dd>
  322. <dd><a href="#ResultCodes">See Result Codes</a> for other possible return values.</dd>
  323. </dl>
  324. </dd>
  325. </dl>
  326. <hr/>
  327. <a name="getScanXMLLog"><h3>int getScanXMLLog(int ScanHandle, char** Bfr, int* Length);</h3></a>
  328. <p>This function returns the scan result code <a href="#ResultCodes">(see Result Codes)</a> and a pointer
  329. to a buffer containing any XML Log Data that was produced for the scan associated with the ScanHandle.</p>
  330. <p>The function is passed a valid ScanHandle which identifies the scan result block to query; the address of
  331. a char* which will be changed to point to a buffer containing any XML Log Data that
  332. was produced; and the address of an integer which will be changed to the length of the
  333. XML Log Data buffer.</p>
  334. <p>If no XML Log Data was produced for the scan then the pointer Bfr will point to a safe empty string
  335. and Length will be set to zero. Put another way, Bfr and Length will be consistent with an empty null terminated
  336. string.</p>
  337. <p>The char* Bfr and the int Length will remain valid until closeScan() is called for this ScanHandle.</p>
  338. <p>In order for XML Log Data to be produced the engine must be configured properly. For details visit the
  339. <a href="http://www.armresearch.com/support/articles/software/snfServer/config/node/logs/scan/xml.jsp">
  340. XML Log configuration documentation</a> on our web site.</p>
  341. <dl>
  342. <dd><b>ScanHandle</b> = a valid scan handle from scanBuffer() or scanFile().</dd>
  343. <dd><b>Bfr</b> = a pointer to a char* where the char* will be changed to point to the XML Log Data.</dd>
  344. <dd><b>Length</b> = a pointer to an int where the int will be changed to the length of the XML Log Data.</dd>
  345. <dd><b>returns</b> the scan result code upon success otherwise an error code:
  346. <dl>
  347. <dd>snf_ERROR_NO_HANDLE - The ScanHandle is not valid.</dd>
  348. <dd>snf_ERROR_EXCEPTION - There was a problem retrieving the data.</dd>
  349. <dd><a href="#ResultCodes">See Result Codes</a> for other possible return values.</dd>
  350. </dl>
  351. </dd>
  352. </dl>
  353. <hr/>
  354. <a name="getScanClassicLog"><h3>int getScanClassicLog(int ScanHandle, char** Bfr, int* Length);</h3></a>
  355. <p>This function returns the scan result code <a href="#ResultCodes">(see Result Codes)</a> and a pointer
  356. to a buffer containing any Classic Log Data that was produced for the scan associated with the ScanHandle.</p>
  357. <p>The function is passed a valid ScanHandle which identifies the scan result block to query; the address of
  358. a char* which will be changed to point to a buffer containing any Classic Log Data that
  359. was produced; and the address of an integer which will be changed to the length of the
  360. Classic Log Data buffer.</p>
  361. <p>If no Classic Log Data was produced for the scan then the pointer Bfr will point to a safe empty string
  362. and Length will be set to zero. Put another way, Bfr and Length will be consistent with an empty null terminated
  363. string.</p>
  364. <p>The char* Bfr and the int Length will remain valid until closeScan() is called for this ScanHandle.</p>
  365. <p>In order for XML Log Data to be produced the engine must be configured properly. For details visit the
  366. <a href="http://www.armresearch.com/support/articles/software/snfServer/config/node/logs/scan/classic.jsp">
  367. Classic Log configuration documentation</a> on our web site.</p>
  368. <dl>
  369. <dd><b>ScanHandle</b> = a valid scan handle from scanBuffer() or scanFile().</dd>
  370. <dd><b>Bfr</b> = a pointer to a char* where the char* will be changed to point to the Classic Log Data.</dd>
  371. <dd><b>Length</b> = a pointer to an int where the int will be changed to the length of the Classic Log Data.</dd>
  372. <dd><b>returns</b> the scan result code upon success otherwise an error code:
  373. <dl>
  374. <dd>snf_ERROR_NO_HANDLE - The ScanHandle is not valid.</dd>
  375. <dd>snf_ERROR_EXCEPTION - There was a problem retrieving the data.</dd>
  376. <dd><a href="#ResultCodes">See Result Codes</a> for other possible return values.</dd>
  377. </dl>
  378. </dd>
  379. </dl>
  380. <hr/>
  381. <a name="getScanResult"><h3>int getScanResult(int ScanHandle);</h3></a>
  382. <p>This function returns the scan result code <a href="#ResultCodes">(see Result Codes)</a>
  383. for the scan associated with the ScanHandle.</p>
  384. <dl>
  385. <dd><b>ScanHandle</b> = a valid scan handle from scanBuffer() or scanFile().</dd>
  386. <dd><b>returns</b> the scan result code upon success otherwise an error code:
  387. <dl>
  388. <dd>snf_ERROR_NO_HANDLE - The ScanHandle is not valid.</dd>
  389. <dd><a href="#ResultCodes">See Result Codes</a> for other possible return values.</dd>
  390. </dl>
  391. </dd>
  392. </dl>
  393. <hr/>
  394. <a name="closeScan"><h3>int closeScan(int ScanHandle);</h3></a>
  395. <p>This function closes a ScanHandle and releases the associated Scan Result Block to the pool. This
  396. function MUST be called once for each ScanHandle produced in a scan...() function. Once this function
  397. is called the ScanHandle is no longer valid and any pointers returned by previous
  398. calls to get...() functions should be discarded (forgotten, not freed!)</p>
  399. <dl>
  400. <dd><b>ScanHandle</b> = a valid scan handle from scanBuffer() or scanFile().</dd>
  401. <dd><b>returns:</b>
  402. <dl>
  403. <dd>snf_SUCCESS - The ScanHandle was closed successfully.</dd>
  404. <dd>snf_ERROR_NO_HANDLE - The ScanHandle is not valid.</dd>
  405. <dd>snf_ERROR_EXCEPTION - There was a problem closing the ScanHandle.</dd>
  406. </dl>
  407. </dd>
  408. </dl>
  409. <hr/>
  410. <a name="shutdownSNF"><h3>int shutdownSNF();</h3></a>
  411. <p>This function shuts down the SNFMulti engine. All previously allocated ScanHandles MUST be closed
  412. before this function is called. This should be the last function in the DLL that is called by your
  413. application (call no other SNFMultiDLL functions after this).</p>
  414. <dl>
  415. <dd><b>returns:</b>
  416. <dl>
  417. <dd>snf_SUCCESS - The shutdown was successful.</dd>
  418. <dd>snf_ERROR_EXCEPTION - An error occurred during shutdown.</dd>
  419. </dl>
  420. </dd>
  421. </dl>
  422. <hr/>
  423. <a name="ResultCodes"><h3>Result Codes</h3></a>
  424. <h4>Error Codes</h4>
  425. </font><dl>
  426. <dd><font face="sans-serif">snf_SUCCESS = 0</font></dd>
  427. <dd><font face="sans-serif">snf_ERROR_CMD_LINE = 65</font></dd>
  428. <dd><font face="sans-serif">snf_ERROR_LOG_FILE = 66</font></dd>
  429. <dd><font face="sans-serif">snf_ERROR_RULE_FILE = 67</font></dd>
  430. <dd><font face="sans-serif">snf_ERROR_RULE_DATA = 68</font></dd>
  431. <dd><font face="sans-serif">snf_ERROR_RULE_AUTH = 73</font></dd>
  432. <dd><font face="sans-serif">snf_ERROR_MSG_FILE = 69</font></dd>
  433. <dd><font face="sans-serif">snf_ERROR_ALLOCATION = 70</font></dd>
  434. <dd><font face="sans-serif">snf_ERROR_BAD_MATRIX = 71</font></dd>
  435. <dd><font face="sans-serif">snf_ERROR_MAX_EVALS = 72</font></dd>
  436. <dd><font face="sans-serif">snf_ERROR_UNKNOWN = 99</font></dd>
  437. <font face="sans-serif"><br/>
  438. <dd>snf_ERROR_NO_HANDLE = -1, Invalid scan handle used or created.</dd></font>
  439. <dd><font face="sans-serif">snf_ERROR_SCAN_FAILED = -2, An unexpected exception during a scan. </font></dd>
  440. <dd><font face="sans-serif">snf_ERROR_EXCEPTION = -3, An unexpected exception occurred.</font></dd>
  441. </dl><font face="sans-serif">
  442. <p>
  443. <a href="http://www.armresearch.com/support/articles/software/snfServer/errors.jsp">
  444. See our web site for more detailed descriptions of these error codes.</a></p>
  445. <h4>Scan Result Codes</h4>
  446. <p>Scan results codes 0 through 63 represent normal scan results. By convention a result of
  447. 0 indicates ham (not spam); a result of 1 indicates a white-ruled message; and other non-zero
  448. result values that are less than 64 indicate some kind of spam or malware was detected.
  449. <a href="http://www.armresearch.com/support/articles/software/snfServer/core.jsp">
  450. For more details on message scan result codes please see our web site.</a></p>
  451. <hr/>
  452. <div align="right"><font size="-3">Copyright (C) 2009 ARM Research Labs, LLC</font></div>
  453. </font>
  454. </body>
  455. </html>