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> ]
	    [-d <debug_level>] [-W]

   -i provide the interface on which to listen for EAPOL packets
   -c configuration file to use (/etc/xsupplicant.conf default)
   -W allow XSupplicant to work with wpa_supplicant.
   -d display different levels of debug information.

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


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.