Re: nselib-bin

[David Fifield <david () bamsoftware com>]

On Fri, Sep 05, 2008 at 12:02:24AM -0600, David Fifield wrote:
> On Thu, Sep 04, 2008 at 11:55:24PM -0600, David Fifield wrote:
> > On Wed, Sep 03, 2008 at 12:02:29PM +0100, jah wrote:
> > > What's happening with nselib-bin?  I ask because I see it's now static
> > > linked, and I'm seeing some build and runtime errors because of this change.
> > >
> > > Specifically, mswin32/Release/nselib-bin (created by a post build event
> > > in nse_bitlib.vcproj) is referenced in mswin32/makefile and because it
> > > doesn't exist, halts the build.
> > > Next, mswin32/nsi/nmap.nsi references nselib-bin and fails when it's not
> > > present.
> > > During script execution:
> > > SCRIPT ENGINE: error while initializing Lua State:
> > > 'nselib-bin/' not a directory
> >
> > Thanks for these reports. We were keeping the directory around while we
> > made sure the static linking worked, but it's gone now (I just removed
> > it).
>
> And another thing: I removed the section on creating C modules from
> docs/scripting.xml. However then I reflected that such a section on
> making static modules could be useful.

I wrote the section on building shared modules. I haven't written a
shared module myself, the closest I've come was migrating the pcre
module from dynamic to static a while back. So I wrote what I could from
observation. I'm including the text of the new section so anyone who has
developed a module can point out anything I've gotten wrong.

I used an example from nse_hash.cc to illustrate. I chose hash because
its implementation is small and straightforward. bit is even smaller but
nse_bit.cc contains a lot of preprocessor magic that distracts from the
real issues in building a module. The hash module might be subsumed by
an openssl module: http://seclists.org/nmap-dev/2008/q3/0638.html, but
in that case I think the openssl module would make a good replacement.

David Fifield


Adding C Modules to Nselib

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, 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_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>.

Two of the smaller compiled modules that come with NSE are bit and hash,
and they serve as good examples of how to write such modules. The source
code for bit is in the files nse_bit.cc and nse_bit.h, and likewise the
source for hash is in nse_hash.cc and nse_hash.h. The other compiled
modules follow this naming convention.

Let us look at the hash module. One of the functions in nse_hash.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 luaL_reg hashlib[] =
{
        {"md5", l_md5},
        {NULL,  NULL}
};

Then the library is registered with a call to luaL_register inside the
initialization function luaopen_hashlib:

LUALIB_API int luaopen_hashlib (lua_State *L) {
  luaL_register(L, NSE_HASHLIBNAME, hashlib);
  return 1;
}

(NSE_HASHLIBNAME is just the string "hash".) luaopen_hashlib is the only
function in the file that is exposed in nse_hash.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.

_______________________________________________
Sent through the nmap-dev mailing list
http://cgi.insecure.org/mailman/listinfo/nmap-dev
Archived at http://SecLists.Org