From 6aa82f606dafe0362a1341c3c4defa9a5254c33d Mon Sep 17 00:00:00 2001 From: fyodor Date: Sat, 8 Nov 2008 10:11:04 +0000 Subject: [PATCH] edited the section Adding C Modules to Nselib, and moved it from Implementation Details into the NSE Libraries section --- docs/scripting.xml | 194 ++++++++++++++++++++++++--------------------- 1 file changed, 102 insertions(+), 92 deletions(-) diff --git a/docs/scripting.xml b/docs/scripting.xml index 08b703013..c952f9721 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -830,6 +830,8 @@ action refer to . the default libraries in order to use them. + + List of All Libraries This list is just an overview to give an idea of what libraries are available. Developers will want to consult the complete @@ -837,6 +839,106 @@ action refer to . &nse-modules; + + + + Adding C Modules to Nselib + Nmap Scripting Engine (NSE)C modules + + + A few of the modules included in nselib are written in C or C++ + rather than Lua. Two examples are bit + and pcre. We recommend that modules + be written in Lua if possible, but C and C++ may be more + appropriate if performance is critical or (as with + the pcre and openssl + modules) you are linking to an existing C library. This section + describes how to write your own compiled extensions to nselib. + + + + The Lua C API is described at length in + Programming in Lua, Second Edition, + Programming in Lua, Second Edition, + so this is a short summary. C modules consist of functions that + follow the protocol of the + lua_CFunction + type. The functions are registered with Lua and assembled into a + library by calling the + luaL_registerluaL_register + function. A special initialization function provides the interface + between the module and the rest of the NSE code. By convention the + initialization function is named in the form + luaopen_module. + + + + The smallest compiled module that comes with NSE is + bit,bit NSE module + and one of the most straightforward is + openssl.openssl NSE module + These modules serve as good examples for a beginning module + writer. The + source code for bit is found in + nse_bit.cc and + nse_bit.h, while the + openssl source is in nse_openssl.cc and + nse_openssl.h. Most of the other compiled modules + follow this nse_module name.cc naming convention. + + + Reviewing the openssl module shows that one of the + functions in nse_openssl.cc is + l_md5, which calculates an MD5 digest. Its + function prototype is: + +static int l_md5(lua_State *L); + + The prototype shows that l_md5 matches the + lua_CFunction type. The function is static because it + does not have to be visible to other compiled code. Only an address is required + to register it with Lua. Later in the file, + l_md5 is entered into an array of type + luaL_reg and associated with the name + md5: + +static const struct luaL_reg openssllib[] = { + { "md5", l_md5 }, + { NULL, NULL } +}; + + + This function will now be known as md5 to NSE. Next the library is registered with a call to + luaL_register inside the initialization + function luaopen_openssl, as shown + next. Some lines relating to the registration of + OpenSSL BIGNUM types have been omitted: + + +LUALIB_API int luaopen_openssl(lua_State *L) { + luaL_register(L, OPENSSLLIBNAME, openssllib); + return 1; +} + + +The function luaopen_openssl + is the only function in the file that is exposed in + nse_openssl.h. OPENSSLLIBNAME is simply the string + "openssl". + + + + After a compiled module is written, it must be added to NSE by including + it in the list of standard libraries in + nse_init.cc. Then the module's + source file names must be added to + Makefile.in in the appropriate places. For both these tasks you can + simply follow the example of the other C modules. For the + Windows build, the new source files must be added to the + mswin32/nmap.vcproj project file using MS Visual Studio (see ). + + + @@ -2331,97 +2433,5 @@ The mainloop function will work on each runlevel grouping of threads in order. repeated until no threads exist in either waiting or running. - - Adding C Modules to Nselib - Nmap Scripting Engine (NSE)C modules - - - Some of the modules included in nselib are not written in Lua but - in C or C++. bit and pcre - are two examples. This section describes how to write your own - compiled extensions to nselib. - - - - The C API of Lua is described at length in - Programming in Lua, Second Edition, - Programming in Lua, Second Edition, - so this is a short summary. C modules consist of functions that - follow the protocol of the - lua_CFunction - type. The functions are registered with Lua and assembled into a - library by calling the - luaL_registerluaL_register - function. A special initialization function provides the interface - between the module and the rest of the NSE code. By convention the - initialization function has a name of the form - luaopen_module. - - - - The smallest compiled module that comes with NSE is - bit,bit NSE module - and one of the most straightforward is - openssl.openssl NSE module - These modules serve as good examples for a beginning module - writer. The - source code for bit is in the files - nse_bit.cc and - nse_bit.h, and likewise the source for - openssl is in nse_openssl.cc and - nse_openssl.h. The other compiled modules - usually follow this naming convention. - - - Let us look at the openssl module. One of the - functions in nse_openssl.cc is - l_md5, which calculates an MD5 digest. Its - function prototype is - -static int l_md5(lua_State *L); - - The prototype shows that l_md5 matches the - lua_CFunction type. The function is static because it - does not have to be visible to other compiled code, it just needs - an address so it can be registered with Lua. Later in the file we - see l_md5 entered into an array of type - luaL_reg and associated with the name - md5, the name it will be known by to NSE: - -static const struct luaL_reg openssllib[] = { - { "md5", l_md5 }, - { NULL, NULL } -}; - - Then the library is registered with a call to - luaL_register inside the initialization - function luaopen_openssl. Some lines relating - to the registration of OpenSSL BIGNUM types have been - omitted. - -LUALIB_API int luaopen_openssl(lua_State *L) { - luaL_register(L, OPENSSLLIBNAME, openssllib); - return 1; -} - - (OPENSSLLIBNAME is just the string - "openssl", the name of the module.) - luaopen_openssl - is the only function in the file that is exposed in - nse_openssl.h. - - - - Once a compiled module is written, it is added to NSE by including - it in the list of standard libraries in - nse_init.cc. Just follow the example of the - modules that are already there. Then the names of the module's - source files of the must be added to - Makefile.in in the appropriate places. Again - it is easiest to follow the example of the other modules. For the - Windows build the new source files must be added to the - mswin32/nmap.vcproj project file. - -