1.1. General Overview

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

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.

Note: At this time Xsupplicant can be used in conjunction with wpa_supplicant to provide WPA keying, but does not currently provide its own WPA hooks.

1.2. Do I Need Open1x?

The short answer is that if you need to authenticate to an 802.1X-enabled network using Linux, then Open1x is probably for you. The Open1x project provides 802.1X functionality for the Linux operating system. 802.1X is an IEEE standard (ratified in 2001) that provides port-based authentication at layer 2 of the OSI model. 802.1X prevents unauthorized network access until appropriate credentials are supplied to access the network. The Open1x project provides the necessary software to connect to an 802.1X-enabled network.

1.3. Supplicant versus Authenticator

The Open1x project contains source code for both the "Supplicant" and "Authenticator" pieces of the 802.1X standard. This document will only focus on the Open1x Supplicant (xsupplicant), as the Authenticator isn't being actively worked on at this point in time.

1.4. Purpose Of This Guide

This guide is aimed towards both the general user, and the system administrator with the intent of explaining how to install and configure xsupplicant.

2.1. About Xsupplicant

Xsupplicant is designed to work with Linux. Early versions of xsupplicant also supported *BSD and Mac OS X, but this support was pulled out when xsupplicant was rewritten.

Mac OS X support was pulled because Apple is now providing a built-in supplicant as of Mac OS X 10.3 (Panther). *BSD support was initially removed largely due to a lack of active *BSD development. Some *BSD code does remain, however, and we encourage any *BSD developers out there to test xsupplicant and submit patches or file bug reports to improve *BSD support. There has been talk of adding Mac OS X support back into xsupplicant, because Apple's client only works with their own Airport cards. Xsupplicant could potentially fill the gap left by Apple for those users that wish to use 3rd party cards, or wireless standards not supported by Apple, such as 802.11a, but such support would require 3rd party APIs to properly handle Dynamic WEP.

The Open1x team would like to reprovide support for *BSD platforms, but doing so will require some additional hacking on the codebase. This project is maintained in our spare time, and we already feel stretched, so we hope you understand our current dilemma in providing *BSD support. If you are interested in helping us with *BSD support, please let us know.

Xsupplicant releases are primarily tested and developed on Slackware Linux.

2.2. EAP Support

Xsupplicant 1.0.1 supports the following EAP types:

• EAP-AKA

• EAP-GTC

• EAP-MD5

• EAP-MSCHAPv2

• EAP-OTP

• EAP-SIM

• LEAP

• PEAP (MSCHAPv2)

• EAP-TLS

• EAP-TTLS (CHAP, MSCHAP, MSCHAPv2, PAP)

• EAP-FAST

• PEAP-GTC

See Chapter 5: EAP Options for details on configuring a specific EAP type with Xsupplicant.

2.3. Authentication Server Compatibility Matrix

The following is a compatibility matrix that lists tested EAP/Authentication Server combinations. Servers listed with a "+" mean that a particular EAP type is supported by that server. A Server/EAP combination listed with a "*" indicates xsupplicant compatibility. A Server/EAP combination listed with a "!" indicates an incompatibility with Xsupplicant.

Lack of a "*" in an entry does not indicate that a particular combination will not work, only that it has not been tested. This list is not meant to be a complete list of tested combinations, as we do not have the resources to keep the list up to date.

2.4. Supplicants

The goal of this section is to help inform the reader of general 802.1X compatibility. The following list is probably not complete, but should provide a fairly comprehensive supplicant/operating system list.

3.1. Download Stable Releases

Users should normally download a stable release from http://sourceforge.net/project/showfiles.php?group_id=60236

3.2. Pre-Packaged Releases for Some Distibutions

At some point we plan on releasing pre-packaged versions of xsupplicant for distributions such as Debian, RedHat, SuSe, Slackware, etc... If you would like to see your favorite distribution supported, please let us know (Or better yet, send us the package)!

3.3. CVS

We do not recommend CVS downloads for people unfamiliar with it. CVS often contains new features that have not yet made it into a stable release, but it can also be extremely unstable. We also do not have the time to explain how CVS works (there is good documentation on the web regarding CVS and its many features/options). We encourage users to submit patches against CVS, but patches may not necessarily be commited immediately.

To download xsupplicant via CVS you can use the following command:

cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/open1x co xsupplicant

4.1. Prerequisites

You will need to have the following installed on your system before installing xsupplicant:

OpenSSL - http://www.openssl.org/

libpcsclite (For EAP-SIM/EAP-AKA support) - http://www.linuxnet.com/

Pthreads Support (For EAP-SIM/EAP-AKA support)

4.2. Quick Start Guide

Generally speaking you should be able to type: ./configure; make; make install to configure and install the Open1x supplicant.

If you run into problems, please read the rest of this chapter.

4.3. Running the Configure Script

The following configuration options are available for xsupplicant:

--enable-eap-sim - Enables EAP SIM/AKA authentication. (Requires libpcsclite)

--enable-experimental - Enable the use of experimental features/code.

--with-ossl-root - Specify the path to the directory holding the OpenSSL source tree.

--enable-radiator-test - Enable use of the AKA test vectors from Radiator. (Doesn't require a SIM card).

--enable-static-openssl - Statically link OpenSSL into the xsupplicant binary.

4.4. When Things go Wrong.

If you experience a problem building xsupplicant, you should:

• Check config.log for any interesting error messages.

• Double check the xsupplicant prerequisites.

• E-mail the xsupplicant mailing list with a detailed explanation of the problem you are experiencing, including any error messages you got and please include a copy of your configuration file and any command line options you used to run xsupplicant. The more information you provide to us, the easier it will be for us to help you fix your problem.

5.1. Overview

5.2. Commandline Options

-W

Allow Xsupplicant to work with wpa_supplicant.

-c /path/to/config_file

You can specify a configuration file to be used with the "-c" option. Xsupplicant will automatically look for and use "/etc/xsupplicant.conf" if it exists.

-i device

Provide the interface on which to listen for EAPoL packets. Please note that xsupplicant will currently look for any valid interfaces and fork to handle each valid interface it finds. You do not need to run multiple instances of xsupplicant yourself.

-d debug_level

<debug_level> can be any of:

• 0 - 7 Old style debug flags.

• A - Enable ALL debug flags.

• c - Enable CONFIG debug flag.

• s - Enable STATE debug flag.

• a - Enable AUTHTYPES debug flag.

• i - Enable INT debug flag.

• n - Enable SNMP debug flag.

• e - Enable EVERYTHING debug flag.

• x - Enable EXCESSIVE debug flag.

Debug flags can be stacked such as: xsupplicant -d csai. This would provide CONFIG, STATE, AUTHTYPES, and INT debug output.

5.3. System Wide Config File

Xsupplicant will look for a file in /etc/xsupplicant.conf by default, unless the -c option is used at runtime. The xsupplicant configuration file consists of several global variables and a set of network-specific configurations. Each network profile definition contains one or more EAP sections, which contain specific configuration information for the network in question.

5.4. Global Configuration Options

The following is a complete list of the global options available in xsupplicant 1.0.1. These options should be defined outside of any xsupplicant network profiles contained in your configuration file.

5.5. Network Profile Configuration Options

A network profile consists of a declaration, such as "default". A complete profile definition is defined by a beginning and ending brace, "{" and "}" respectively. The profile defines network specific attributes for 802.1X operation, such as allowed EAP-types, the username for a given EAP-type, and any EAP-type specific options.

Each network profile section may include one or more valid EAP-types. When the Authentication Server requests a given EAP type, xsupplicant will use that EAP type if a valid configuration exists. Otherwise, xsupplicant will NAK the Authentication Server, and request the first EAP type defined by the "allow_types" configuration option. If xsupplicant and the Authentication server cannot agree on an EAP type, the authentication will not take place, so be sure to define an appropriate EAP-type for your network!

5.6. EAP Options

Each network profile in the xsupplicant configuration file may have one or more EAP sections defined. Each EAP section must be associated to a network profile. Each EAP section may also have one or more subsections associated with it.

For instance, a configuration for EAP-TTLS may have any of CHAP, MSCHAP, MSCHAPv2, or PAP subsections defined. Some EAP types do not contain any subsections.

logfile = /var/log/xsupplicant.log

startup_command = <BEGIN_COMMAND>dhclient %i<END_COMMAND>

default {
  allow_types = eap-aka

  identity = <BEGIN_ID>myid@mynet.net<END_ID>

  eap-aka {
      username = <BEGIN_UNAME>akauser<END_UNAME>
      password = <BEGIN_PASS>akauserpass!<END_PASS>     
      auto_realm = yes
  }
}

logfile = /var/log/xsupplicant.log

startup_command = <BEGIN_COMMAND>dhclient %i<END_COMMAND>

default {
  allow_types = eap-gtc

  identity = <BEGIN_ID>myid@mynet.net<END_ID>

  eap-gtc {
      
  }
}

logfile = /var/log/xsupplicant.log

startup_command = <BEGIN_COMMAND>dhclient %i<END_COMMAND>

default {
  allow_types = eap-md5

  identity = <BEGIN_ID>myid@mynet.net<END_ID>

  eap-md5 {
      password = <BEGIN_PASS>password<END_PASS>
  }
}

logfile=/var/log/xsupplicant.log

startup_command = <BEGIN_COMMAND>dhclient %i<END_COMMAND>

default {
  allow_types = eap-mschapv2

  identity = <BEGIN_ID>myid@mynet.net<END_ID>
  
  eap-mschapv2 {      
      password = <BEGIN_PASS>password<END_PASS>
  }
}

logfile = /var/log/xsupplicant.log

startup_command = <BEGIN_COMMAND>dhclient %i<END_COMMAND>

default {
  allow_types = eap-otp

  identity = <BEGIN_ID>myid@mynet.net<END_ID>

  eap-otp {
       
  }
}

logfile = /var/log/xsupplicant.log

startup_command = <BEGIN_COMMAND>dhclient %i<END_COMMAND>

default {
  allow_types = eap-sim

  identity = <BEGIN_ID>myid@mynet.net<END_ID>

  eap-sim {
      username = <BEGIN_UNAME>simuser<END_UNAME>
      password = <BEGIN_PASS>simuserpass!<END_PASS>     
      auto_realm = yes
  }
}

logfile = /var/log/xsupplicant.log

startup_command = <BEGIN_COMMAND>dhclient %i<END_CLIENT>

default {

  allow_types = all

  identity = <BEGIN_ID>myid@mynet.net<END_ID>

  eap-peap {
      root_cert = /home/user/certificates/root.pem
      chunk_size = 1398
      random_file = /dev/urandom
      cncheck = radiusserver.mynet.net         
      cnexact = yes
      session_resume = no

      eap-mschapv2 {
        username = <BEGIN_UNAME>myid@mynet.net<END_UNAME>
        password = <BEGIN_PASS>password<END_PASS>
      }
  }
}

logfile = /var/log/xsupplicant.log

startup_command = <BEGIN_COMMAND>dhclient %i<END_CLIENT>

default {

  allow_types = all

  identity = <BEGIN_ID>myid@mynet.net<END_ID>

  eap_tls {
     user_cert = /home/user/certificates/user-cert.pem
     user_key  = /home/user/certificates/user-key.pem
     user_key_pass = <BEGIN_PASS>password for user-key.pem<END_PASS>
     root_cert = /home/user/certificates/root.pem
     crl_dir = /home/user/certificates/revoked


     chunk_size = 1398
     random_file = /dev/urandom
     session_resume = no
  }
}

logfile = /var/log/xsupplicant.log

startup_command = <BEGIN_COMMAND>dhclient %i<END_COMMAND>

default {
  allow_types = eap-ttls

  identity = <BEGIN_ID>myid@mynet.net<END_ID>

  eap-ttls {
      root_cert = /home/user/certificates/root.pem
      chunk_size = 1398
      random_file = /dev/urandom
      cncheck = myradius.radius.com          
      cnexact = no                          
      session_resume = no
      phase2_type = pap

      pap {
        username = <BEGIN_UNAME>myid@mynet.net<END_UNAME>
        password = <BEGIN_PASS>password<END_PASS>
      }
  }
}

logfile = /var/log/xsupplicant.log

startup_command = <BEGIN_COMMAND>dhclient %i<END_COMMAND>

default {
  allow_types = leap

  identity = <BEGIN_ID>myid@mynet.net<END_ID>

  leap {
      password = <BEGIN_PASS>password<END_PASS>
  }
}

5.7. User Config File

We hope to provide the ability to specify both a global configuration file and a more specific user configuration file capability in a future release of xsupplicant.

5.8. Using a GUI for Configuration

The current version of Xsupplicant does not provide a mechanism to configure itself from a Graphical User Interface, except for providing a password. We hope to provide such tools in the future. Fortunately, the 1.0 config file format is much easier to read than older versions.

If you have the QT development tools installed, you can compile and use the qt-gremlin, or xsup_monitor programs, to provided with Xsupplicant for real-time password prompting in X11. We hope to extend this tool so it can also display EAP-Notifications as well.

7.1. A Guide to Troubleshooting

If you experience any problems with xsupplicant, please use the following guide to troubleshoot your issues:

• Send us a debug output of xsupplicant, and any relevant xsupplicant options.

• Tell us what card driver you are using, including revision (which can usually be found with dmesg)!

• Send us a gdb backtrace, if possible.

• Send us a copy of your configuration file.

• Please make sure you *DO NOT* include passwords in your configuration file, or in your -d 7 output.

Run xsupplicant in debug mode by using the "-d 7" and "-f" switches and gather the output. If you are segfaulting, run xsupplicant in gdb, if possible and provide a backtrace:

gdb xsupplicant
(gdb) set args (any args you normally use)
(gdb) run
(gdb) backtrace (after segfault)

This will help us find the problem easier.

Send us a copy of your configuration (but remove the passwords please).

7.2. Known Problems

The following is a summary of the known issues with this version of xsupplicant.

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

• Cisco 340/350 cards do not work correctly with Xsupplicant 1.0. This appears to be due to the driver (or firmware?) hijacking the 0x888e frames, which prevents 802.1X authentication from being possible.

  UPDATE: We have been successful getting a Cisco 350 card to work with the built-in Linux 2.6.7 Aironet driver to the extent that it will authenticate. The driver still has the (common) rekeying bug.

  This means that it should be fairly easy to fix the Kernel driver. We are still unsure what caused this.