Open1x User's Guide

Chris Hessing

Nick Petroni

Bryan Payne

Terry Simons
     _________________________________________________________________

   Table of Contents
   1. About Open1x And This Guide

        1.1. General Overview
        1.2. Do I Need Open1x?
        1.3. Supplicant versus Authenticator
        1.4. Purpose Of This Guide

   2. Supported Platforms

        2.1. About Xsupplicant
        2.2. EAP Support
        2.3. Authentication Server Compatibility Matrix
        2.4. Supplicants

   3. Getting The Software

        3.1. Download Stable Releases
        3.2. Pre-Packaged Releases for Some Distibutions
        3.3. CVS

   4. Installation

        4.1. Prerequisites
        4.2. Quick Start Guide
        4.3. Running the Configure Script
        4.4. When Things go Wrong.

   5. Configuration

        5.1. Overview
        5.2. Commandline Options
        5.3. System Wide Config File
        5.4. Global Configuration Options

   6. Advanced Usage
   7. Troubleshooting

        7.1. A Guide to Troubleshooting
        7.2. Known Problems

   A. Setup for Authenticators and RADIUS Servers

        A.1. Authenticators
        A.2. Authentication Servers

   B. Links to Related Resources

        B.1. Companies that Support Open1x
        B.2. 802.1X Related Open Source Projects
        B.3. 802.1X related proprietary projects
        B.4. Standards
        B.5. Other Resources

   List of Tables
   2-1. Supported Authentication Servers
   2-2. Supplicant Support Matrix

   List of Examples
   5-1. Global Option "default_netname"
   5-2. Global Option "logfile"
   5-3. Global Option "log_facility"
   5-4. Global Option "allmulti"
   5-5. Global Option "destination"
   5-6. Global Option "network_list"
   5-7. Profile Option "allow_types"
   5-8. Profile Option "dest_mac"
   5-9. Profile Option "identity"
   5-10. Profile Option "type"
   5-11. Profile Option "wireless_control"
   5-12. Common EAP Option "chunk_size"
   5-13. Common EAP Option cncheck
   5-14. Common EAP Option "cnexact"
   5-15. Common EAP Option "crl_dir"
   5-16. Common EAP Option "password"
   5-17. Common EAP Option "random_file"
   5-18. Common EAP Option "root_cert"
   5-19. Common EAP Option "root_dir"
   5-20. Common EAP Option "session_resume"
   5-21. Common EAP Option "username"
   5-22. Common EAP Option "user_cert"
   5-23. Common EAP Option "user_key"
   5-24. Common EAP Option "user_key_pass"
   5-25. Common EAP Option "proper_peap_v1_keying"
   5-26. Common EAP Option "inner_id"
   5-27. Example EAP-AKA Configuration
   5-28. Example EAP-GTC Configuration
   5-29. Example EAP-MD5 Configuration
   5-30. Example EAP-MSCHAPv2 Configuration
   5-31. Example EAP-OTP Configuration
   5-32. Example EAP-SIM Configuration
   5-33. EAP-SIM Option "auto_realm"
   5-34. Example PEAP Configuration
   5-35. Example EAP-TLS Configuration
   5-36. Example EAP-TTLS Configuration
   5-37. EAP-TTLS Option "phase2_type"
   5-38. EAP-TTLS Option "chap"
   5-39. EAP-TTLS Option "mschap"
   5-40. EAP-TTLS Option "mschapv2"
   5-41. EAP-TTLS Option "pap"
   5-42. Example LEAP Configuration
   7-1. Getting a GDB Backtrace
     _________________________________________________________________

Chapter 1. About Open1x And This Guide

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,  WPA, or WPA2/802.11i for confidentiality.
   And,  as  always,  be  prepared  to  update  your network(s) as better
   security solutions become available.
     _________________________________________________________________

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

Chapter 2. Supported Platforms

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

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

   Future versions of Xsupplicant may include support for:

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

   Table 2-1. Supported Authentication Servers
     Cisco ACS FreeRADIUS Funk SBR Infoblox Meetinghouse AEGIS Microsoft
   IAS Radiator Roving Planet CSD
   EAP-AKA - - - - - - * -
   EAP-FAST + - - - - - - -
   EAP-GTC - - - - - - * -
   EAP-MD5 * * * * * - * *
   EAP-OTP - - - - - - * -
   EAP-SIM - * - - - - * -
   EAP-TLS + + + + + + * +
   LEAP + + + - + - * +
   PEAP-GTC + - - - + - + -
   PEAP-MSCHAPv2 * * * ! * * * +
   TTLS-CHAP - * + + + - * +
   TTLS-MSCHAP - * + + + - * +
   TTLS-MSCHAPv2 - + + + + - * +
   TTLS-PAP - + * ! * - * +
     _________________________________________________________________

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.

   Table 2-2. Supplicant Support Matrix
     *BSD Linux Mac OS X 10.2.x Mac OS X 10.3.x Pocket PC 2002 Pocket PC
   2003 Windows 98 Windows Me Windows 2k Windows XP
   Alfa+Ariss SecureW2 - - - - - + - - + +
   Funk Odyssey - - - - + + + + + +
   Meetinghouse Aegis - + + + + + + + + +
   Native - - - + - + - - - +
   Open1x - + - - - - - - - -
   wEAP - - - - - - - - + +
   Wire1x - - - - - - + + + +
     _________________________________________________________________

Chapter 3. Getting The Software

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
     _________________________________________________________________

Chapter 4. Installation

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.

   The  only  exception would be if you intend to use the WPA support for
   MADwifi.  In  that case you need to add the --with-madwifi-path option
   when  you run configure. This should point to the directory where your
   MADwifi source is located.

   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.

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

   --with-madwifi-path  -  Provide  the  path  to the MADwifi source, and
   enable support for WPA on cards that use the MADwifi driver.
     _________________________________________________________________

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

Chapter 5. Configuration

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.2.  These  options  should  be  defined  outside of any
   xsupplicant network profiles contained in your configuration file.
     _________________________________________________________________

5.4.1. Global Options

   The  following  list  is  a  complete list of the global configuration
   options for the xsupplicant configuration file.

   Xsupplicant Config - Global Options

   default_netname
          If  this  option  is not used, xsupplicant will attempt to read
          the  profile  "default" from the configuration file. Some users
          may actually have a network named "default", so this option can
          be  used  to  redefine  which  profile  is  used as the default
          profile.

          Example 5-1. Global Option "default_netname"

          default_netname = default

   logfile
          When running in daemon, or non-foreground mode, you may want to
          have  the  output  of  the program. So, define a log file here.
          Each  time  XSupplicant is started, this file will be replaced.
          So,  there is no need to roll the log file. If the logfile name
          is  set  to  "syslog",  then  all  messages will be sent to the
          syslog.   If   syslog   is  defined,  you  should  also  define
          "log_facility" to specify which logging facility will be used.

          Example 5-2. Global Option "logfile"

          logfile = /var/log/xsupplicant.log

   log_facility
          If you have set the logfile option to "syslog", then you should
          define  log_facility in order to tell Xsupplicant where to send
          log  messages.  Valid  settings  are  cron,  daemon, ftp, kern,
          local0, local1, local2, local3, local4, local5, local6, local7,
          lpr, news, user, and uucp.

          Example 5-3. Global Option "log_facility"

          log_facility = local0

   allmulti
          For  most  people, the default setting for "allmulti" will work
          just fine. In some cases, wireless cards have been known to not
          work  when ALLMULTI is enabled. (Such as certain Orinoco cards,
          with  older drivers.) If "allmulti" is set to "no", XSupplicant
          will  not  attempt  to  change  the state of the setting in the
          driver.  So,  you  should  make  sure  to  do an "ifconfig ethX
          -allmulti".

          Example 5-4. Global Option "allmulti"

          allmulti = no

   destination
          destination:  defines  how  Xsupplicant  should  determine  the
          destination   address  that  should  be  used  for  the  802.1X
          conversation.  Valid  Options  are  :  Auto - respond to source
          address  from  the  last  packet  we saw. Source - same as Auto
          BSSID  - Always answer to the BSSID of the AP we are associated
          to.  Multicast  -  always  use the multicast address defined in
          802.1X-2001.

          Example 5-5. Global Option "destination"

          destination = auto

   network_list
          This directive defines all of the network profiles which should
          be  kept  in  memory and used.Comma delimited list or "all" for
          keeping  all  defined configurations in memory. For efficiency,
          keep  only  the  networks you might roam to in memory. To avoid
          errors,  make  sure  your  default  network  is  always  in the
          network_list.  In  general,  you will want to leave this set to
          "all".

          Example 5-6. Global Option "network_list"

          network_list = all
     _________________________________________________________________

5.4.1.1. State Machine Variables

     * auth_period
     * max_starts
     * held_period

   The  auth_period, held_period, and max_starts modify the timers in the
   state  machine. (Please reference the 802.1X spec for info on how they
   are used.) For most people, there is no reason to define these values,
   as the defaults should work.
     _________________________________________________________________

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

   Xsupplicant Config - Network Profile Options

   allow_types
          This  option describes which EAP types this network will allow.
          The  first type listed will be requested if the server tries to
          use  something  not  in  this list. Individual EAP types can be
          specified,  or the keyword "all" can be used to specify all EAP
          types.  Additionally,  it  is legal to use either an underscore
          (_)  or  dash (-) for the separator character between "eap" and
          the type. For instance, "eap-tls" and "eap_tls" are both valid.

          Example 5-7. Profile Option "allow_types"

          allow_types = eap-tls, eap-md5, eap-gtc, eap-otp

          allow_types = all

   dest_mac
          This  option  forces  xsupplicant  to  send its packets to this
          destination  MAC address. In most cases, this isn't needed, and
          shouldn't be defined.

          Example 5-8. Profile Option "dest_mac"

          dest_mac = 00:aA:bB:cC:dD:eE

   identity
          This  defines  the  EAP  Response  Identity,  also known as the
          "outer  identity" , or, what xsupplicant will respond with when
          presented  with  an EAP Identity Request. This is typically the
          username  for  this  network.  If  the  identity  contains  any
          characters  other  than  A  through  Z and 0 through 9, then it
          should be defined in quotes.

          Example 5-9. Profile Option "identity"

          identity = myid@mynet.net

   type
          Xsupplicant  will  attempt to determine if a given interface is
          wired  or  wireless,  but  some  drivers misbehave. This option
          forces  xsupplicant  to  recognize interfaces in a certain way.
          Use  this  option  if your interface is detected incorrectly by
          xsupplicant. Valid options are "wired" and "wireless".

          Example 5-10. Profile Option "type"

          type = wireless

   wireless_control
          If  the  profile is forced to wired, this will not do anything.
          However, if the interface is forced, or detected to be wireless
          XSupplicant  will  take control of re/setting WEP keys when the
          machine  first  starts, and when it jumps to a different AP. In
          general,  you  won't  need  to define, or set this value. Valid
          options are "yes" and "no".

          Example 5-11. Profile Option "wireless_control"

          wireless_control = yes
     _________________________________________________________________

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

5.4.3.1. Reused EAP Options

   The  following  options  are  re-used  in many of the EAP types listed
   below.

   Common EAP Options

   chunk_size
          The  chunk_size  directive  specifies  the  maximum size that a
          certificate chunk can be. Use this option in EAP types that use
          either one or both of client or server certificates (TLS, PEAP,
          TTLS).

          Example 5-12. Common EAP Option "chunk_size"

          chunk_size = 1398

   cncheck
          The  cncheck  directive  provides  the ability to verify the CN
          field  of  an  authentication  server certificate for EAP types
          that use server-side certificates (TTLS, PEAP).

          Use  this  directive in conjunction with cnexact to control how
          granular the server certificate check should be.

          Example 5-13. Common EAP Option cncheck

          cncheck = someradius.mynet.net

   cnexact
          The cnexact directive forces a failure on authentication if the
          CN field of the server's certificate does not exactly match the
          cncheck  option in the specified Network/EAP configuration. Set
          this  to  "no"  to  only  match the end of the string, which is
          useful   in   a   situation   where  there  might  be  mulitple
          authentication servers for your organization.

          For example, a "cncheck = utah.edu" with a "cnexact = no" would
          match  on  "foo.utah.edu"  and  "bar.utah.edu",  which might be
          separate servers on a campus utilizing 802.1X.

          Example 5-14. Common EAP Option "cnexact"

          cnexact = yes

   crl_dir
          The  crl_dir  option  is used to specify a directory containing
          certificate  revocation  lists.  This option can be used in EAP
          types  that  use  either  one  or  both  of  client  or  server
          certificates (TLS, PEAP, TTLS).

          Example 5-15. Common EAP Option "crl_dir"

          crl_dir = /home/user/certificates/revoked

   password
          The  password  directive  is  used  in EAP types that require a
          password for authentication.

          Example 5-16. Common EAP Option "password"

          password = password

   random_file
          This  option  is  used  to specify the random file used to grab
          random   data  used  during  certificate  based  authentication
          methods..  Use  this option in EAP types that use either one or
          both of client or server certificates (TLS, PEAP, TTLS).

          This  option  is  typically  /dev/urandom, but may be different
          depending  on  the  operating  system you are using. You should
          probably  not  use  /dev/random,  since  it blocks and can slow
          authentication  down.  In most cases, leaving this blank is the
          best choice.

          Example 5-17. Common EAP Option "random_file"

          random_file = /dev/urandom

   root_cert
          The  root_cert  option  is  used  to specify the path to the CA
          public  certificate which signed one or both of your server and
          client  certificates. The root_cert option is used in EAP types
          that  use  either  one or both of client or server certificates
          (TLS, PEAP, TTLS).

          This  certificate  is  used to verify, on the client side, that
          the   server's   certificate  was  signed  by  the  appropriate
          certificate  authority,  and on the server side, to verify that
          the  user  certificate  was  signed  by  the proper certificate
          authority.  This certificate should be the same for both client
          and  server,  since  it  is  simply  the  public  key  for  the
          certificate   authority  that  signed  the  client  and  server
          certificates.

          You  can  specify a value of "NONE" to prevent xsupplicant from
          verifying  the server certificate, but this is *HIGHLY* frowned
          upon.  If you use this option, you are opening yourself up to a
          very  easy  to  execute  man-in-the-middle  attack  that  could
          compromise   your  username  and  password.  Consider  yourself
          warned!

          Example 5-18. Common EAP Option "root_cert"

          root_cert = /home/user/certificates/root_cert.pem

   root_dir
          The  root_dir  option  is used to specify a path to a directory
          containing  root  certificates.  This  can  be  used  to  force
          Xsupplicant  to allow any combination of root certificates in a
          given directory to help simplify configuration. This option can
          be  used  instead  of the root_cert directive in EAP types that
          use  either  one or both of client or server certificates (TLS,
          PEAP, TTLS).

          Example 5-19. Common EAP Option "root_dir"

          root_dir = /home/user/certificates

   session_resume
          The  session_resume directive is used to specify whether or not
          to  attempt  to  initiate "TLS Session Resumption" (Also called
          "Fast Reconnect") when re-authenticating with a server.

          Example 5-20. Common EAP Option "session_resume"

          session_resume = yes

   username
          The  username  option  is  used  in  EAP  types  that require a
          username  for  authentication.  If  your  username contains any
          characters  other  than A through Z and 0 through 9, you should
          enclose it in quotes.

          Example 5-21. Common EAP Option "username"

          username = myid@mynet.net

   user_cert
          This  option,  which is required for TLS, specifies the path to
          the  user  certificate  used  for  TLS  authentication.  A user
          certificate  in  TLS is similar to a username in password-based
          authentication mechanisms.

          User  certificates can also be used with PEAP and TTLS, but are
          not required, and most people will not need this functionality.

          Example 5-22. Common EAP Option "user_cert"

          user_cert = /home/user/certificates/user-cert.pem

   user_key
          This option is the key for the user_cert file.

          As  with  user_cert, this option is required for TLS and can be
          used  with  TTLS  or  PEAP  if  using  a  user  certificate for
          authentication.

          Example 5-23. Common EAP Option "user_key"

          user_key = /home/user/certificates/user-key.pem

   user_key_pass
          This  is  the  password  for  the  user_key. If it contains any
          characters other than A through Z and 0 through 9, it should be
          enclosed in quotes.

          Example 5-24. Common EAP Option "user_key_pass"

          user_key_pass = password

   proper_peap_v1_keying
          This  option  will  force  Xsupplicant to use the proper string
          constant for PEAPv1 authentication. Most authentication servers
          use the string constant from PEAPv0.

          Example 5-25. Common EAP Option "proper_peap_v1_keying"

          proper_peap_v1_keying = no

   inner_id
          This  is  the  identity  value  that will be sent to the server
          inside of the PEAP phase 1 tunnel.

          Example 5-26. Common EAP Option "inner_id"

          inner_id = no
     _________________________________________________________________

5.4.3.2. EAP-AKA

   EAP-AKA allows the following options: username, password, auto_realm.

   Example 5-27. Example EAP-AKA Configuration
   logfile = /var/log/xsupplicant.log

   default {
     allow_types = eap-aka

     identity = "myid@mynet.net"

     eap-aka {
         username = akauser
         password = "akauserpass!"
         auto_realm = yes
     }
   }
     _________________________________________________________________

5.4.3.3. EAP-GTC

   Example 5-28. Example EAP-GTC Configuration
   logfile = /var/log/xsupplicant.log

   default {
     allow_types = eap-gtc

     identity = "myid@mynet.net"

     eap-gtc {

     }
   }
     _________________________________________________________________

5.4.3.4. EAP-MD5

   EAP-MD5 allows the following option(s): password.

   Example 5-29. Example EAP-MD5 Configuration
   logfile = /var/log/xsupplicant.log

   default {
     allow_types = eap-md5

     identity = "myid@mynet.net"

     eap-md5 {
         password = password
     }
   }
     _________________________________________________________________

5.4.3.5. EAP-MSCHAPv2

   Valid  eap-mschapv2  options  are:  username  (only  needed when using
   mshcapv2 as a phase 2 type), password.

   eap-mschapv2  can  also  be  defined  as a sub-option inside of a PEAP
   profile. See the PEAP section for an example.

   Example 5-30. Example EAP-MSCHAPv2 Configuration
   logfile=/var/log/xsupplicant.log

   default {
     allow_types = eap-mschapv2

     identity = "myid@mynet.net"

     eap-mschapv2 {
         password = password
     }
   }
     _________________________________________________________________

5.4.3.6. EAP-OTP

   Example 5-31. Example EAP-OTP Configuration
   logfile = /var/log/xsupplicant.log

   default {
     allow_types = eap-otp

     identity = "myid@mynet.net"

     eap-otp {

     }
   }
     _________________________________________________________________

5.4.3.7. EAP-SIM

   EAP-SIM allows the following options: username, password, auto_realm.

   Example 5-32. Example EAP-SIM Configuration
   logfile = /var/log/xsupplicant.log

   default {
     allow_types = eap-sim

     identity = "myid@mynet.net"

     eap-sim {
         username = simuser
         password = "simuserpass!"
         auto_realm = yes
     }
   }
     _________________________________________________________________

5.4.3.7.1. EAP-SIM Specific Options

   The following list defines options specific to "eap-sim":

   auto_realm
          The auto_realm option determines whether or not your realm will
          be  automatically  appended to your username on authentication,
          or  whether  the  user will do this manually in the xsupplicant
          configuration.  This  option  is  fairly  dependent on how your
          service  is  set up, so check with your provider to see if this
          option should be enabled.

          Valid auto_realm options are: yes, no.

          Example 5-33. EAP-SIM Option "auto_realm"

          auto_realm = yes
     _________________________________________________________________

5.4.3.8. PEAP

   Valid  options  for  PEAP  are: chunk_size, cncheck, cnexact. crl_dir,
   random_file, root_cert, root_dir, session_resume, user_cert, user_key,
   user_key_pass, proper_peap_v1_keying, inner_id

   PEAP  currently requires eap-mschapv2 as a sub-option. Future versions
   of  xsupplicant  may include support for other embedded EAP-types such
   as  eap-gtc.  In  addition,  the  "inner_id" directive is required for
   inner-eap types used with PEAP.

   Example 5-34. Example PEAP Configuration
   logfile = /var/log/xsupplicant.log

   default {

     allow_types = all

     identity = "myid@mynet.net"

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

         eap-mschapv2 {
           password = password
         }
     }
   }
     _________________________________________________________________

5.4.3.9. EAP-TLS

   Valid  options  for  EAP-TLS  are:  chunk_size,  crl_dir, random_file,
   root_cert,     root_dir,    session_resume,    user_cert,    user_key,
   user_key_pass,

   Example 5-35. Example EAP-TLS Configuration
   logfile = /var/log/xsupplicant.log

   default {

     allow_types = all

     identity = "myid@mynet.net"

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


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

5.4.3.10. EAP-TTLS

   Valid options for EAP-TTLS are: chunk_size, cncheck, cnexact. crl_dir,
   random_file, root_cert, root_dir, session_resume, user_cert, user_key,
   user_key_pass, phase2_type

   EAP-TTLS  may  also  have  one  or  more  sub-options:  chap,  mschap,
   mschapv2, pap.

   Example 5-36. Example EAP-TTLS Configuration
   logfile = /var/log/xsupplicant.log

   default {
     allow_types = eap-ttls

     identity = "myid@mynet.net"

     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 = "myid@mynet.net"
           password = password
         }
     }
   }
     _________________________________________________________________

5.4.3.10.1. EAP-TTLS Specific Option(s)

   The following list defines options specifc to "eap-ttls":

   phase2_type
          The  phase2_type  directive  specifies which phase2 type to use
          when authenticating with TTLS.

          Valid phase 2 types are: chap, mschap, mschapv2, pap.

          Example 5-37. EAP-TTLS Option "phase2_type"

          phase2_type = pap

   chap
          Use  this option in TTLS to specify a username and password for
          a CHAP authentication.

          Most people will probably want to use PAP with TTLS, however.

          Valid chap options are: username, password,

          Example 5-38. EAP-TTLS Option "chap"

                chap {
                  username = "myid@mynet.net"
                  password = password
                }

   mschap
          Use  this option in TTLS to specify a username and password for
          an MSCHAP authentication.

          Most people will probably want to use PAP with TTLS, however.

          Valid mschap options are: username, password,

          Example 5-39. EAP-TTLS Option "mschap"

                mschap {
                  username = "myid@mynet.net"
                  password = password
                }

   mschapv2
          Use  this option in TTLS to specify a username and password for
          an  MSCHAPv2  authentication.  This  option  is  different than
          eap-mschapv2.

          Most people will probably want to use PAP with TTLS, however.

          Valid mschapv2 options are: username, password,

          Example 5-40. EAP-TTLS Option "mschapv2"

                mschapv2 {
                  username = "myid@mynet.net"
                  password = password
                }

   pap
          Use  this option in TTLS to specify a username and password for
          a PAP authentication.

          Most  people  will  probably  want  to  use  this  option  when
          authenticating with TTLS.

          Valid pap options are: username, password,

          Example 5-41. EAP-TTLS Option "pap"

                pap {
                  username = "myid@mynet.net"
                  password = password
                }
     _________________________________________________________________

5.4.3.11. LEAP

   Valid options for LEAP are: password

   Example 5-42. Example LEAP Configuration
   logfile = /var/log/xsupplicant.log

   default {
     allow_types = leap

     identity = "myid@mynet.net"

     leap {
         password = password
     }
   }
     _________________________________________________________________

5.4.4. 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.4.5. 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.
     _________________________________________________________________

Chapter 6. Advanced Usage

   This  chapter  is  intended to provide examples for making xsupplicant
   easier to use.
     _________________________________________________________________

Chapter 7. Troubleshooting

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:

   Example 7-1. Getting a GDB 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.
     _________________________________________________________________

Appendix A. Setup for Authenticators and RADIUS Servers

A.1. Authenticators

A.1.1. Open Source Authenticator Projects

     * HostAP (http://hostap.epitest.fi/)
     * Rose (http://www.rosewlan.com/)
     _________________________________________________________________

A.1.2. Commercial Authenticators

     *

   not  a  complete  setup  guide for all APs on the market, instead some
   comments on how to setup the more common APs to work with open1x. also
   provide pointers to more complete setup & config guides
     _________________________________________________________________

A.2. Authentication Servers

A.2.1. Open Source Authentication Servers

   See the Authentication Server Compatibility Matrix for a complete list
   of supported EAP types.

     * FreeRADIUS
     _________________________________________________________________

A.2.2. Commercial Authentication Servers

   See the Authentication Server Compatibility Matrix for a complete list
   of supported EAP types.

     * Cisco ACS
     * Funk SBR
     * Infoblox
     * Meetinghouse AEGIS
     * Microsoft IAS
     * Radiator (Source Code Included with Purchase)
     * Roving Planet CSD (Based on FreeRADIUS)
     _________________________________________________________________

Appendix B. Links to Related Resources

B.1. Companies that Support Open1x

   The  following  entities  have donated hardware/software to the Open1x
   project:

   Contributions are listed in the order they were received.

   The companies listed below do not endorse Open1x.

     * Proactive Network Management & Proxim
          + ORiNOCO AP-600 (802.11b/g)
          + http://www.pnmc.com/
          + http://www.proxim.com/
     * Radiator
          + Many bug fixes, and added features in a very timely manner.
          + http://www.open.com.au/
     * Hewlett-Packard
          + HP Procurve 420 AP (802.11b/g)
          + http://www.hp.com/
     * 3Com
          + 3Com 8200 AP & 802.11a/b/g Wireless Card (3CRPAG175)
          + http://www.3com.com/
     * University of Utah Center for High Performance Computing
          + Funding for the Networld + Interop HotStage 2004
          + http://www.chpc.utah.edu/
     * Cisco Systems
          + Cisco 1200 AP (802.11b/g)
          + http://www.cisco.com/
     * Brad Midgley
          + Many different types of Mini-PCI wireless cards.
          +
     _________________________________________________________________

B.2. 802.1X Related Open Source Projects

   Wire1x - An Open Source xsupplicant port for Windows.

   wEAP - An Open Source project for Windows EAP Plugins.
     _________________________________________________________________

B.3. 802.1X related proprietary projects
     _________________________________________________________________

B.4. Standards

   The 802.11 Specification [ieee.org]

   Wireless Ethernet [wirelessethernet.com]

   IEEE Working Groups [ieee.org]

   IEEE 802.11b Specification [ieee.org]

   IEEE 802.1X [ieee.org]

   RADIUS with IEEE 802.1X [local]

   Wireless LAN Resources for Linux [hpl.hp.com]
     _________________________________________________________________

B.5. Other Resources

B.5.1. Howtos

   Sniffing a wireless network with a Cisco WLAN card. [umd.edu]

   Setting  up  802.1X  using  a  WinXP client and a Win2K Radius server.
   [umd.edu]

   Setting up 802.1X using Xsupplicant and FreeRADIUS [umd.edu]

   Using the Orinoco (Hermes) card with Xsupplicant. [oreillynet.com]
     _________________________________________________________________

B.5.2. Related Links

   Ethereal Patches for 802.1X Decoding [umd.edu]

   Support for 802.1X in WinXP [microsoft.com]

   The University of Utah 802.1X Wireless Website [utah.edu]
