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, WPA, or WPA2/802.11i
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:
=============

For a basic, no frills installation :

1. ./configure
2. make
3. make install

For an installation that includes WPA support for the madwifi driver, you
will need to add --with-madwifi-path=<path to madwifi driver source> in order
to enable WPA support for madwifi!

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> ]
	    [-d <debug_level>] [-W] [-w] [-f] [-D <driver name>] [-z] [-t]
            [-q] [-a]

   -i provide the interface on which to listen for EAPOL packets
   -c configuration file to use (/etc/xsupplicant.conf default)
   -W allow XSupplicant to use wpa_supplicant for WPA keying.
   -d display different levels of debug information.
   -w don't attempt to use WPA support
   -f run in the forground
   -D use WPA support for driver <driver name>
   -z zero WEP keys on roam (Needed for Orinoco and some other drivers)
   -t don't use IW_ENCODE_TEMP when setting keys
   -q terminate when defaulting to authenticated state
   -a what (interface index)-1 for wireless events (needed for hostap driver)

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). 

NOTE: if you are using dynamic WEP, make sure that your network card is 
associated to the correct network before starting xsupplicant or bringing 
up the interface.

CONFIGURATION FILE:
===================
An example configuration file has been provided. The default path for
the configuration file is /etc/xsupplicant.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.

Please see the example config files in the etc directory.

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

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

WPA/WPA2/802.11i:  Wireless extensions 18, or special driver support is 
                   required to use WPA/WPA2/802.11i.  Please see the
		   README.wpa in the doc directory.

BUGS:
=====

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

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

2. Attempting to run Xsupplicant against an interface that is down, or does
   not exist will fail.  (Will be fixed in next release.)