MAC2USER.TXT - ShapeShifter Name Resolution Engine ( NRE ) Beta 3 0.51a
~~~~~~~~~~~~

The MAC2USER NRE 0.51a is a new component of the ShapeShifter family.
It acts as an initial brudge between the TSE and NDS.   MAC2USER will
search NDS to find associations between NDS Objects and network
addresses.   


Security Issues
~~~~~~~~~~~~~~~
The MAC2USER.CFG file contains PLANTEXT password and login ID used to
search the NDS trees.  This file should be located in a folder requiring
Admin equivalent rights to protect it from unauthorized access.  The
SYS:SYSTEM folder is probibly good enough.  You can also use tools like
JCMD to locate the file in the SYS:_NETWARE double-secret folder.  This
folder cannot be accessed except from the server console, and if an
intruder has access to that, you are already screwed.   Future versions
of MAC2USER will allow the file to be encrypted to prevent casual
browsing.


Security Best Practices
~~~~~~~~~~~~~~~~~~~~~~~
Create a special account for MAC2USER to login as.  Give this account
just enough rights to read the necessary attributes from the objects
you want to have MAC2USER scan.   Use Network Address Restrictions to
limit the logins from this account to the network addresses of the
servers which will run MAC2USER.   This ensures that even of the
MAC2USER.CFG file is obtained by an intruder, the IDs and passwords
contained within can only be used from the server console.  This
reduces the security issues to that of physical access.

IPX addresses for a server look like: IPXNETNO:000000000001:FFFF
where IPXNETNO is the INTERNAL IPX NET number of the server.  For
TCPIP, the address is the IP address of the server.


Moral Issues
~~~~~~~~~~~~
Unlike most traffic tracking technologies which track network usage
back to a given host ( via IP or DNS ) the MAC2USER lookup is actually
capable of resolving an IP address to a user login.   This means that
your SHAPER logs will show the NDS user object of the user generating
the traffic.   

The logs gathered by SHAPER in conjunction with MAC2USER could be used
as the basis for firing employees, as well as evidence in the subsequewnt
lawsuits, MPAA and RIAA actions, criminal proceedings, and so on. 
Users should be forewarned that these records are being maintained, and
informed about the curcumstances under which they are used and by whom.
Written policies should outline who has access to the logs, how they
are handled, secured, and how long the records are maintained in on-line
or off-line form.   Having a policy in place and adhering to it will
protect you from the grey areas.

What do you do if you inadvertently see an employees spending all day
on kiddie.porn.com?   How about the guy in accounting that downloaded
52GB in MP3s?   Or the nasty letters from MPAA and RIAA?  Having
policies in place will insure that you do not get trapped by over
zealous management ( or Sony ) into acting as Big Brother.

Obviously you can use this ting any way you want, but please 
understand the responsibility that goes with knowing everything.


How MAC2USER Works
~~~~~~~~~~~~~~~~~~

MAC2USER starts a thread for each Tree + Context you specify in the
MAC2USER.CFG file which defaults to live in SYS:SYSTEM.  This
allows you to include the contexts you wish to search.  There is no
means to exclude subcontexts, however.  ( I am aware how desirable
this feature is. )

Initially MAC2USER looks for the following:

1. Any NDS object with a "Network Address" field.

This includes User and ZFD Workstation objects where the "Network Address"
attribute is populated.   MAC2USER understands IPX, IP, TCP, and UDP
addresses and will extract the IP or MAC address from these fields.
Server and other objects which have Network Address attributes are also
used.  

2. Novell DHCP 3.x NDIP: IP Address Configuration objects.

This includes active leases, standby leases, static assignments,
and unauthorized leases.   The IP address and MAC address are
obtained from these objects.  This allows MAC2USER to cross-
reference MAC and IP so that if a User's MAC is known, its IP
address can be found.

3. DNS Resolution  ( Not Implemented Yet! )

MAC2USER acts as a DNS cache for SHAPER.   Any IP address it
learns will be looked up.    

It internally stores the information in a hash table and a set
of links between hash items.   In this way one can query a given
IP address and determine its DNS host name, MAC address, and
associated NDS user object.

MAC2USER also performs transitive searches.  A user logging into
NetWare via IPX can be associated with the IP address used on
his PC via DHCP information.   

As MAC2USER builds its mesh of associations, timestamps on the
links allow the NLM to return the "best name" available for
an address by taking the most recently added association.
The preservation of old associations allows MAC2USER to collect
historical information about which user's use what MAC and IP
addresses over time.   Eventually MAC2USER will provide robust
logging of this history as well as persistence to the 
association database currently maintained in RAM.

Programming Interface
~~~~~~~~~~~~~~~~~~~~~

MAC2USER currently exports one public lookup function to obtain
the "best name" for a given IP or MAC address.

char *M2U_GetLatestNameForAddr( char *Addr, int Len, char *Default )

Addr points to the 4 or 6 byte sequence to lookup.
Len is the size of the address.  4 for IPv4 and 6 for MAC.
Default is a character string which is returned in case the lookup fails.

For example:

char Address[4] = { 192, 168, 100, 15 );
char Default[] = "Unknown";
printf( "My UID: \"%s\"\n",
        M2U_GetLatestUIDForAddress( &Address,
                                    sizeof( Address ),
                                    &Default ) );

Might output:

My UID: Bob.Developers.MyCorp

The pointer returned will be valid for at least 1 second, so it
should be used quickly and never stored.  Values are NEVER deleted
from the memory resident MAC2USER database.  But when the NLM
is shuttong down, it will eventually free all its memory.  The NLM
will wait approximately 2 seconds after shutdown starts before it
frees its memory, making your pointer invalid.  If you think your code
might linger, memcpy the string to your own buffer.  NEVER modify
the value returned by M2U_GetLatestUIDForAddress().  NULL is only
returned when you specify NULL for Default, so check for NULL
as needed.   The value returned may be as ling as the maximum
allowed size of a NDS object ID.   

Features Added ( This Version )

The MAC2USER UNLOAD command will unload the NLM without the risk of
locking the server console.  You can, of course, unload the NLM
using the UNLOAD command.

The MAC2USER DUMP WHOIS filename command dumps the "best name" for
each MAC and IP address in the memory resident database.   This
command appends to the previous file contents or creates a new file
as needed.   If you wish to cron the creation of this file, you may
want to rename of remove the previous file contents using TOOLBOX

The MAC2USER SAVE DB filename command dumps the entire object and
linkage database to a text file.   This will be used to persist the
data between runs of the NLM and for diagnostics.  The beginning
of the file contains

	( This information is likely to change!!! )

    ENTRY: "text label", type, born_time, touched_time, confidence_TTL, stale_TTL, purge_TTL, link_count, label_size

	"text label"	- address string, object name, DNS host name, etc.
	type		- entry type
	born_time	- time_t when entry was created 
	touched_time	- time_t when entry was last touched ( found in NDS, DNS, ... )
	confidence_TTL  - seconds since last touch and still be considered "fresh"
	stale_TTL	- seconds since last touch till it is considered stale
	purge_TTL	- seonnds since last touch till we can purge
	link_count	- number of links to other entries
	label_size	- internal label size
 
    LINK: "text label" --> "text label", type, born_time, touched_time, confidence_TTL, stale_TTL, purge_TTL

	"text label"	- address string, object name, DNS host name, etc.
	type		- entry type
	born_time	- time_t when link was created 
	touched_time	- time_t when link was last touched ( found in NDS, DNS, ... )
	confidence_TTL  - seconds since last touch and still be considered "fresh"
	stale_TTL	- seconds since last touch till it is considered stale
	purge_TTL	- seonnds since last touch till we can purge

The MAC2USER SHAPER command imports the SHAPER API allowing
MAC2USER to consume SHAPER APIs.  

The MAC2USER WHOIS [ a.b.c.d | xx:xx:xx:xx:xx:xx ] command will
perform an interactive lookup of the specified address, displaying
the "best name" for the address.   Please note that the MAC address
is accepted with 0 padding, but is output without padding.  This means
that 00:23:01:45:A0:0B would be displayed as 0:23:1:45:A0:B  This is
NOT a bug, its just annoying.

The -ENTRIES=nnn startup option indicates the maximum number of 
address or name entries which MAC2USER will learn.   Each IP
or MAC address requires two entries each.   Each NDS object
for which address information is found requires an entry.
Each DNS name found for IP addresses discovered requires an
additional entry.   Each workstation will typically require
7 entries: 2 for IP, 2 for MAC, 1 for a ZFD workstation object,
1 for the logged in User object, and 1 for a DNS entry.   MAC2USER
aloocates this memory as new items are learned.  So there is no
penalty for having a large number of allowed entries which never
actually exist.

The -LINKS=nnn startup option indicates the MAXIMUM number of
associations / linkages between all the entries.   This should be
set to approximately 2 or 3 times the number of expected entries.
Since the links are small, MAC2USER manages them from a single
preallocated block of memory.   Having large numbers of unused
links wastes memory.   The defaults of 20000 entries and 50000
links should be enough for networks with up to 3000 to 5000 nodes.
Use in larger networks will require usie of these command line
options, and perhaps some titration.