How LanWarden Works

From the frontpage you know that all the data LanWarden uses and needs is stored in an LDAP directory and that it depends on using patched versions of ISC DHCP and FreeRADIUS, this page explains how all these bits function and are glued together; it does not explain how 802.1X works.

What is actually LanWarden? A kind of specification/blueprint of how an LDAP server, FreeRADIUS and ISC DHCP operate amongst one plus a perl library that can be used to easy change the contents of the LDAP directory; however if you are feeling clever enough you could just go swinging in with your favourite LDAP browser/editor. In addition to this there is an SQL server to log the 802.1X logs to and all your edge kit needs to be able to be SNMP queryable.

If you have this kind of environment configured then you should find the Perl module Net::LanWarden really lets you build custom applications yourself, such as asset tracking, report generators, Intrusion Detection Systems and all. Bulk host import tools, EAP-TLS enrollers, whatever you need.

It is assumed that you understand already:

The LDAP directory is used to hold everything from workstation VLAN assignment to notes and dynamic DNS entries regarding the workstation. An workstation/device object is built on the objectClass 'lanwardenHost' that inherits 'dhcpHost' and 'device'. All hosts are considered to have unique MAC addresses, live under the branch 'ou=Hosts' and their 'cn' is always the MAC address with the hyphens removed. 

dn: cn=001122334455,ou=Hosts,ou=LanWarden,dc=example,dc=com
objectClass: top
objectClass: device
objectClass: dhcpHost
objectClass: lanwardenHost
cn: 001122334455
owner: uid=bob,ou=People,dc=example,dc=com
serialNumber: 123456
l: A special place
o: Example Corp
ou: IT Department
description: Bob's laptop, tracked by cheese.example.com
lanwardenHostAuthenticateMethod: mac
lanwardenHostRegisteredBy: uid=helldesk,ou=People,dc=example,dc=com
lanwardenHostRegisteredTime: YYYYMMDDHHMMSSZ
lanwardenHostRegisteredTC: example.com aup
lanwardenHostRegisteredTC: blood-of-first-born
lanwardenHostState: enable
lanwardenHostNotes: 20080109103032Z - private - this user is a pain in the ass and thinks they know everything
lanwardenHostNotes: 20080109103032Z - public - seems clean re-enabled
lanwardenHostNotes: 20080108183010Z - public - disabled due to portscanning
lanwardenHostNotes: 20080110145643Z - public - disabled due to portscanning
dhcpHWAddress: ethernet 00:11:22:33:44:55
dhcpStatements: ddns-hostname "cheese"

From the above you can see a number obvious fields whilst the DHCP server borrows this object to decide how each individual host needs to be treated, does it have a dynamic DNS entry that follows it around (to give you a MAC address to DNS mapping) and if you wanted to give it two fixed IP addresses (highly discouraged, especially as it breaks DDNS) then you could add an additional 'dhcpStatements' line stating: 

dhcpStatements: fixed-address 1.2.3.4, 5.6.7.8

You will probably notice this, in the ISC DHCP world, is similar to stating: 

host 001122334455 {
  hardware ethernet 00:11:22:33:44:55;
  ddns-hostname "cheese"
  fixed-address 1.2.3.4, 5.6.7.8;
}

Easy eh? This dual purpose device object is useful as you do not need to worry about garbage collection and when you scrub a host it is gone (okay not strictly true, as it has a network membership also that needs to be tidied but we cover this later).

The non-DHCP related attributes are used by LanWarden directly to decide how a host is handled, the real decision making in regards to how a host is treated (from a 802.1X perspective) is all handled by looking up what group network membership the device is permitted in (along with optionally the user themselves); done by the RADIUS server. The majority of information in the device object is data in regards to who is responsible for the machine along with notes that cover the history of the machine (in the above example you can see that the user has been disabled again after they were re-enabled). Also included is how the machine is permitted to authenticate which can be either:

mac

The device is not 802.1X aware and so it's MAC address should be used to do host authentication

x509

The device is 802.1X aware and uses EAP-TLS (a client side certificate) to authenticate and confirm it's MAC address

none

The device is 802.1X aware (or should be) and the user credentials are 'borrowed' to validate the MAC address

Network's and VLAN's are treated in the context (under the class 'lanwardenNetwork') of groups and under a declared network definition it has a number of members. The following is an example network definition: 

dn: cn=laptops,cn=Networks,ou=LanWarden,dc=example,dc=com
objectClass: top
objectClass: dhcpService
objectClass: lanwardenNetwork
ou: 78
o: example
dhcpOption: ntp-servers time.example.com
dhcpOption: domain-name-servers ns1.example.com, ns2.example.com
dhcpOption: domain-name "example.com"
cn: laptops
member: cn=001122334455,ou=Hosts,ou=LanWarden,dc=example,dc=com
member: cn=005544332211,ou=Hosts,ou=LanWarden,dc=example,dc=com
member: uid=bob,ou=People,dc=example,dc=com

As you can see a network definition has a member of it's parent whilst the workstations with the MAC addressess 00:11:22:33:44:55 and 00:55:44:33:22:11 are members of that network. User's are also members of networks as you can see above. 'ou' is the VLAN number and 'o' is the domain of that VLAN (in Cisco-ese you could say VTP-domain). It is worth noting that users themselves (and when I add the support user group's) are members of networks too in LanWarden; this lets us permit a workstation to move between several VLAN's depending on which user's credentials where used to validate it's MAC address. For the IP related information, this lurks in deeper branches of the network definition in the 'dhcpSharedNetwork' (zones), 'dhcpSubnet' (networks) and 'dhcpPool' (pools) objectclasses.

Now this is pretty much the foundation of LanWarden. The steps to put a host on a 802.1X network are:

  • the RADIUS server authenticates the MAC address (either with EAP-TLS or against the user's credentials, alternatively you might want to rely on MAC based authentication alone and assume MAC spoofing is not a problem). If it is unable to authenticate the MAC address then the machine is assumed to be non-802.1X aware and needs to have a supplicant installed, the device is placed into a "install a 802.1X supplicant" state and can go no further until they deal with this
  • looks up the MAC address in the LDAP directory (with 'lanwardenHostState=enable' to be matched), if it is not found then the machine needs registering and is put into a "unauthorised" VLAN and so can go no further until registered (or alternatively it has been disabled for whatever reason)
  • if found the 'dn' of the host object is used to look for network memberships
  • if the user credentials were used to validate the MAC address then the user object 'dn' is looked up and the network membership found is used as a mask over the workstation membership (to trim non-permitted ones)
  • the result of permitted networks should only be one, otherwise something has gone adrift and the user will be placed into a network to state something has gone horribly wrong
  • the VLAN id is used to pass back to the 802.1X enabled edge equipment to state which VLAN the device is to be placed in

With this we can get a lot of power from just changing the group membership of a workstation. To disable a workstation you change 'lanwardenHostState' to 'disable', send an SNMP message to the edge equipment to reinitialise the 802.1X state machine of the port the workstation is plugged into (although typically to kick off the DHCP requests we actually shutdown the port for a couple of seconds and re-enable it) and then the machine is placed into its approiate unauthorised network.