AUTHORS:
========
Bryan D. Payne (bdpayne@cs.umd.edu)
Nick L. Petroni Jr. (npetroni@cs.umd.edu)
Chris Hessing  (Chris.Hessing@utah.edu)
Terry Simons   (Terry.Simons@utah.edu)

This work funded by a grant from National Institute of Standards and
Technology Critical Infrastructure Grants Program.

GENERAL OVERVIEW:
=================
This software allows a GNU/Linux or BSD workstation to authenticate with
a RADIUS server using 802.1x and various EAP protocols.  The intended 
use is for computers with wireless LAN connections to complete a strong
authentication before joining the network.

Note: BSD support is not yet complete.

This provides a good complement to WEP, which provides confidentiality.
Even though it is well documented that WEP has technical flaws, it is still
better than simply sending data in the clear.  Therefore, we recommend using
this software (802.1x) for authentication *and* WEP for confidentiality.
And, as always, be prepared to update your network(s) as better security
solutions become available.

Our test setup for wireless access used Cisco Aironet 340 series access points 
and a Microsoft Windows 2000 RADIUS server (IAS on Win2k Advanced Server).  
The Windows 2000 RADUIS server should have the "high encryption pack" 
installed.

Our test setup for wired access used a Foundry FastIron 4802, HP 2425,
and FreeRADIUS 0.7.1 and Radiator 3.7.1 running on Slackware Linux 9.1.  
We have also had success with Proxim AP-2000 APs with FreeRADIUS and Radiator.

INSTALLATION:
=============
1. ./configure
2. make
3. make install

DEPENDENCIES:
=============
The following packages must be installed before configuring and building
this software package:
Openssl 0.9.7 (or greater) http://www.openssl.org

NOTE: Previous versions of xsupplicant relied on the libdnet and 
      libpcap libraries.  These dependencies have been removed.
 
PROGRAM USAGE:
==============
xsupplicant [-i <interface>] [-c <config file> ]
            [-n <network id>] [-a <auth MAC>] [-D]
	    [-u <user name>]  [-p <password>] [-w]

   -i provide the interface on which to listen for EAPOL packets
   -D go into daemon mode after getting the password
   -c configuration file to use (/etc/1x/1x.conf default)
   -n the name of the network to use in the configuration file
   -a force a specific authenticator's MAC address
   -u override the username specified in the configuration file
   -p pass the password in from the command line **(See note below)
   -w force the connection to be a wired connection

While the program can be started from the command line directly,
it will most commonly be used as part of a script to bring up
a network interface and be started in daemon mode. Example network
scripts ifup and ifdown have been provided and tested in FreeBSD4.4, 
RedHat Linux, and Debian Linux and have been written to work on any
system with ifconfig and either dhcpcd or pump. It is suggested that
these scripts be used in place of the usual ones whenever bringing
up or down an interface for 802.1x authentication. Furthermore, for
802.11 networks it is recommended that the interface is brought
down and back up in the case of changing networks (going to a new
essid). 

The "-w" command line option is the same as executing the "-n default" 
option.  It is provided to handle the case where a wired network card
returns a value from the bssid calls.  (Such as the Intel iANS card. 
See the BUGS section for more information.)

NOTE: make sure that your network card is associated to the correct
network before starting xsupplicant or bringing up the interface.

**NOTE: For security reasons, it is suggested that you only use the -p 
option when testing the client.  When xsupplicant is invoked with the -p
option, the password will be visable to anyone that can execute a "ps" on
your computer!

CONFIGURATION FILE:
===================
An example configuration file has been provided. The default path for
the configuration file is /etc/1x/1x.conf, however, a different file
can be specified at startup with the -c flag. There are a different 
number of values required depending on the authentication method used.

the general format is as follows: <network-id>:<tag> = <value>
where <network-id> is the network name (in the case of wireless
networks the essid, for wired networks this should be set to "default"), 
<tag> is a specific property of the authentication process associated 
with that nework, and <value> is the value of that property. Currently 
supported tags and their explanation can be found in etc/1x.conf.

x.509 FORMATS:
==============
More on certificates can be found in README.certificates
The following formats MUST be used at this time for the respective 
certificates/keys. Openssl can be used to convert certificate formats
and an example script called pkcs12toDERandPEM.sh has been provided. This
script takes a single argument of a pkcs#12 file, containing the user's
certificate and private key, and produces the files key.pem and cert.cer
to be used by xsupplicant. The following are the required formats:

User Certificate:       DER format
User Private Key:       PEM format
Root Certificate store: PEM format

PROTOCOL SPECIFIC INFORMATION :
===============================

EAP-MD5: This form of authentication should not be used on wireless 
	 connections!  MD5 cannot be used to generate keying material.

EAP-MSCHAPv2: This EAP type doesn't currently generate keying information, so
	      it should not be used as a primary authentication method.  
              Instead, it should only be used as an inner authentication type
 	      for PEAP.

EAP-PEAP: This PEAP implementation may not work correctly when authenticating
	  against a Microsoft IAS server.

EAP-SIM: Is not enabled by default.  To enable it, you will need to add the
	 --enable-eap-sim argument to configure.  Turning EAP-SIM on, also
	 requires the following additional libraries : PCSC 
	 (http://www.musclecard.com), and pthreads.


CONTRIB:
========
Thanks to Dug Song for porting to libdnet. 


BUGS:
=====

The following bugs are known to exist with this release of xsupplicant.

1. The Intel iANS drivers using 802.1q support return a value other than 
   -1 when the SIOCGIWAP ioctl is used.  This causes the supplicant to 
   believe that it is on a wireless interface.  This in turn attempts to 
   load a profile that doesn't exist in the configuration file.

2. The supplicant may get confused on wired ports that are set up to allow
   more than one client per port.

3. Wireless support for MacOS-X is not complete.  If you are authenticating 
   over a wired port, make sure you use the -w option, or that your 
   wireless card is disabled.

4. Xsupplicant sometimes sends an EAP Response instead of an EAP-Protocol-
   Response, which will confuse some authentications.  This will cause some
   authenticators to report a failed attempt on some connections.