1=============================================================================== 2 3TOPIC: plugins 4 5ABSTRACT: this file describes how to write a plugin for ettercap NG 6 7NOTE: the plugin system has been modified since ettercap NG 0.7.0, all 8 plugins coded for the 0.6.x series must be ported to the new api. 9 10=============================================================================== 11 12 13 We believe that an example tells much more than thousand words. So we wrote 14 a plugin templates to demonstrate how to write a simple plugin. 15 The template is called "dummy". Look at its source code (well commented). 16 17 However here there are some directive you have to respect. 18 19 1) THE INCLUDES 20 21 #include <ec.h> /* required for global variables */ 22 #include <ec_plugins.h> /* required for plugin ops */ 23 24 these are required, but you can include as many includes as you want. 25 26 2) PLUGIN OPERATION 27 28 struct plugin_ops ops = { 29 .ettercap_version = EC_VERSION, 30 .name = "plugin name", 31 .info = "description of the plugin", 32 .version = "x.y", 33 .init = &init_function, 34 .fini = &fini_function, 35 }; 36 37 for every plugin you have to fill this structure with the appropriate 38 fields. This structure MUST be passed to plugin_register() in the 39 plugin_load() function. (see below) 40 41 ettercap_version: MUST be the global EC_VERSION. this variable is used 42 for internal check to prevent that a plugin compiled 43 for an ettercap version will be used with a different 44 api version. 45 46 name: is a string containing the name of the plugin 47 48 info: is a string with the description of the plugin 49 50 version: is a string with the version of the plugin 51 52 init: is a pointer to the function ettercap has to call on 53 when the user selects the plugin 54 55 fini: is a pointer to the function to be executed to 56 deactivate the plugin 57 58 59 3) INITIALIZATION AND FINALIZATION 60 61 Every plugin MUST contain a function called plugin_load(). This function 62 is called by ettercap when the plugin is loaded by lt_dlopen(). It is 63 used to register the plugin in the plugin list. To do this, it MUST 64 return to value returned by plugin_register(). 65 The plugin_register() wants two parameter, the handle passed to 66 plugin_load and the plugin_ops described above. 67 68 69 int plugin_load(void *handle) 70 { 71 . . . 72 73 return plugin_register(handle, &ops); 74 } 75 76 77 When the user activate the plugin, ettercap calls the function registered 78 in the plugin_ops as 'init'. If the user wants to deactivate the plugins, 79 ettercap calls the registered 'fini' function. 80 You can do whatever you want in this functions, the only thing to be 81 respected is the return value. 82 There are two different return value: 83 84 PLUGIN_FINISHED: the plugin has finished its execution. The fini 85 function will never be called. 86 This is usually used if the plugin perform an 87 operation and exit (as for the old external plugins) 88 89 90 PLUGIN_RUNNING: the plugin is still running and will be deactivated 91 with the fini function. 92 This is used if the plugin spawns a thread or it has 93 hooked to an ettercap hookpoint. In case the plugin 94 has created a thread, it must be killed in the 95 'fini' function. 96 97 98 4) HOOKING POINTS 99 100 An hooking function must be declared as: 101 102 void func(struct packet_object *po) 103 104 Every hook point recall the function passing the packet object as the 105 parameter. 106 107 108 HOOK_RECEIVED the raw packet, the L* structures are not filled. you 109 can modify the packet before the protocol analysis 110 starts. 111 112 HOOK_DECODED all the packet after the protocol stack parsing and 113 after the dissectors. here you can find interesting 114 information such as passwords and fingerprints. 115 116 HOOK_PRE_FORWARD right before the forward point. the hook is executed 117 only if it has to be forwarded. 118 119 HOOK_HANDLED top of the protocol stack but before the dissectors. 120 you can set/unset the PO_IGNORE flag to decide to not 121 pass the packet to the top_half 122 123 HOOK_FILTER the content filtering point. the hook point is right 124 after the filtering engine. 125 126 HOOK_DISPATCHER in the top_half (the packet is a copy). if you modify 127 the packet here there is no change to see the 128 modification on the wire :) 129 You can use this hook for operations that requires much 130 time but don't modify the packet. Since the capture 131 thread must be fast (to forward all the packets) the 132 cpu consuming task (such as connection tracking and 133 profiles management) are performed in the top_half. 134 135 HOOK_PACKET_* Every packet type as a different hook point. If you 136 want to receive only tcp packet, hook to the 137 HOOK_PACKET_TCP, if you want ppp packet, hook to 138 HOOK_PACKET_PPP and so on... 139 These hooks are declared in the protocol decoder 140 (./src/protocols/*.c) 141 142 HOOK_PROTO_* Some protocols declare an hookpoint. Look in 143 ./src/dissectors/*.c to have a list of hooks. 144 145 146 refer to the 'capture' document in order to have a complete view of the 147 hooking system. 148 149 150 5) ETTERCAP API 151 152 + USER_MSG() same as printf(), but required in order to output to 153 the user interface. use this function if the plugin 154 has to communicate with the user. 155 156 + INSTANT_USER_MSG() same as USER_MSG but without buffering. the buffer 157 flush is called immediately. usually is the GUI that 158 call the flush periodically (every 10 msec). 159 160 161 + ui_input() if the plugin needs some input from the user. 162 you can provide a callback or not, depending of what 163 the function does. 164 165 166 Obviously a plugin can use all the ettercap function and its global 167 variables. They are not described here because it is out of the document 168 scope. 169 170 171feel free to write an email to the developer to have further information. 172 173 174EOF 175