Document TLS session cache

[freeradius.git] / raddb / eap.conf

# -*- text -*-
##
##  eap.conf -- Configuration for EAP types (PEAP, TTLS, etc.)
##
##      $Id$

#######################################################################
#
#  Whatever you do, do NOT set 'Auth-Type := EAP'.  The server
#  is smart enough to figure this out on its own.  The most
#  common side effect of setting 'Auth-Type := EAP' is that the
#  users then cannot use ANY other authentication method.
#
#  EAP types NOT listed here may be supported via the "eap2" module.
#  See experimental.conf for documentation.
#
        eap {
                #  Invoke the default supported EAP type when
                #  EAP-Identity response is received.
                #
                #  The incoming EAP messages DO NOT specify which EAP
                #  type they will be using, so it MUST be set here.
                #
                #  For now, only one default EAP type may be used at a time.
                #
                #  If the EAP-Type attribute is set by another module,
                #  then that EAP type takes precedence over the
                #  default type configured here.
                #
                default_eap_type = md5

                #  A list is maintained to correlate EAP-Response
                #  packets with EAP-Request packets.  After a
                #  configurable length of time, entries in the list
                #  expire, and are deleted.
                #
                timer_expire     = 60

                #  There are many EAP types, but the server has support
                #  for only a limited subset.  If the server receives
                #  a request for an EAP type it does not support, then
                #  it normally rejects the request.  By setting this
                #  configuration to "yes", you can tell the server to
                #  instead keep processing the request.  Another module
                #  MUST then be configured to proxy the request to
                #  another RADIUS server which supports that EAP type.
                #
                #  If another module is NOT configured to handle the
                #  request, then the request will still end up being
                #  rejected.
                ignore_unknown_eap_types = no

                # Cisco AP1230B firmware 12.2(13)JA1 has a bug.  When given
                # a User-Name attribute in an Access-Accept, it copies one
                # more byte than it should.
                #
                # We can work around it by configurably adding an extra
                # zero byte.
                cisco_accounting_username_bug = no

                #
                #  Help prevent DoS attacks by limiting the number of
                #  sessions that the server is tracking.  Most systems
                #  can handle ~30 EAP sessions/s, so the default limit
                #  of 2048 is more than enough.
                max_sessions = 2048

                # Supported EAP-types

                #
                #  We do NOT recommend using EAP-MD5 authentication
                #  for wireless connections.  It is insecure, and does
                #  not provide for dynamic WEP keys.
                #
                md5 {
                }

                # Cisco LEAP
                #
                #  We do not recommend using LEAP in new deployments.  See:
                #  http://www.securiteam.com/tools/5TP012ACKE.html
                #
                #  Cisco LEAP uses the MS-CHAP algorithm (but not
                #  the MS-CHAP attributes) to perform it's authentication.
                #
                #  As a result, LEAP *requires* access to the plain-text
                #  User-Password, or the NT-Password attributes.
                #  'System' authentication is impossible with LEAP.
                #
                leap {
                }

                #  Generic Token Card.
                #
                #  Currently, this is only permitted inside of EAP-TTLS,
                #  or EAP-PEAP.  The module "challenges" the user with
                #  text, and the response from the user is taken to be
                #  the User-Password.
                #
                #  Proxying the tunneled EAP-GTC session is a bad idea,
                #  the users password will go over the wire in plain-text,
                #  for anyone to see.
                #
                gtc {
                        #  The default challenge, which many clients
                        #  ignore..
                        #challenge = "Password: "

                        #  The plain-text response which comes back
                        #  is put into a User-Password attribute,
                        #  and passed to another module for
                        #  authentication.  This allows the EAP-GTC
                        #  response to be checked against plain-text,
                        #  or crypt'd passwords.
                        #
                        #  If you say "Local" instead of "PAP", then
                        #  the module will look for a User-Password
                        #  configured for the request, and do the
                        #  authentication itself.
                        #
                        auth_type = PAP
                }

                ## EAP-TLS
                #
                #  See raddb/certs/README for additional comments
                #  on certificates.
                #
                #  If OpenSSL was not found at the time the server was
                #  built, the "tls", "ttls", and "peap" sections will
                #  be ignored.
                #
                #  Otherwise, when the server first starts in debugging
                #  mode, test certificates will be created.  See the
                #  "make_cert_command" below for details, and the README
                #  file in raddb/certs
                #
                #  These test certificates SHOULD NOT be used in a normal
                #  deployment.  They are created only to make it easier
                #  to install the server, and to perform some simple
                #  tests with EAP-TLS, TTLS, or PEAP.
                #
                #  See also:
                #
                #  http://www.dslreports.com/forum/remark,9286052~mode=flat
                #
                tls {
                        #
                        #  These is used to simplify later configurations.
                        #
                        certdir = ${confdir}/certs
                        cadir = ${confdir}/certs

                        private_key_password = whatever
                        private_key_file = ${certdir}/server.pem

                        #  If Private key & Certificate are located in
                        #  the same file, then private_key_file &
                        #  certificate_file must contain the same file
                        #  name.
                        #
                        #  If CA_file (below) is not used, then the
                        #  certificate_file below MUST include not
                        #  only the server certificate, but ALSO all
                        #  of the CA certificates used to sign the
                        #  server certificate.
                        certificate_file = ${certdir}/server.pem

                        #  Trusted Root CA list
                        #
                        #  ALL of the CA's in this list will be trusted
                        #  to issue client certificates for authentication.
                        #
                        #  In general, you should use self-signed
                        #  certificates for 802.1x (EAP) authentication.
                        #  In that case, this CA file should contain
                        #  *one* CA certificate.
                        #
                        #  This parameter is used only for EAP-TLS,
                        #  when you issue client certificates.  If you do
                        #  not use client certificates, and you do not want
                        #  to permit EAP-TLS authentication, then delete
                        #  this configuration item.
                        CA_file = ${cadir}/ca.pem

                        #
                        #  For DH cipher suites to work, you have to
                        #  run OpenSSL to create the DH file first:
                        #
                        #       openssl dhparam -out certs/dh 1024
                        #
                        dh_file = ${certdir}/dh
                        random_file = ${certdir}/random

                        #
                        #  This can never exceed the size of a RADIUS
                        #  packet (4096 bytes), and is preferably half
                        #  that, to accomodate other attributes in
                        #  RADIUS packet.  On most APs the MAX packet
                        #  length is configured between 1500 - 1600
                        #  In these cases, fragment size should be
                        #  1024 or less.
                        #
                #       fragment_size = 1024

                        #  include_length is a flag which is
                        #  by default set to yes If set to
                        #  yes, Total Length of the message is
                        #  included in EVERY packet we send.
                        #  If set to no, Total Length of the
                        #  message is included ONLY in the
                        #  First packet of a fragment series.
                        #
                #       include_length = yes

                        #  Check the Certificate Revocation List
                        #
                        #  1) Copy CA certificates and CRLs to same directory.
                        #  2) Execute 'c_rehash <CA certs&CRLs Directory>'.
                        #    'c_rehash' is OpenSSL's command.
                        #  3) uncomment the line below.
                        #  5) Restart radiusd
                #       check_crl = yes
                #       CA_path = /path/to/directory/with/ca_certs/and/crls/

                       #
                       #  If check_cert_issuer is set, the value will
                       #  be checked against the DN of the issuer in
                       #  the client certificate.  If the values do not
                       #  match, the cerficate verification will fail,
                       #  rejecting the user.
                       #
                #       check_cert_issuer = "/C=GB/ST=Berkshire/L=Newbury/O=My Company Ltd"

                       #
                       #  If check_cert_cn is set, the value will
                       #  be xlat'ed and checked against the CN
                       #  in the client certificate.  If the values
                       #  do not match, the certificate verification
                       #  will fail rejecting the user.
                       #
                       #  This check is done only if the previous
                       #  "check_cert_issuer" is not set, or if
                       #  the check succeeds.
                       #
                #       check_cert_cn = %{User-Name}
                #
                        # Set this option to specify the allowed
                        # TLS cipher suites.  The format is listed
                        # in "man 1 ciphers".
                        cipher_list = "DEFAULT"

                        #

                        #  This configuration entry should be deleted
                        #  once the server is running in a normal
                        #  configuration.  It is here ONLY to make
                        #  initial deployments easier.
                        #
                        make_cert_command = "${certdir}/bootstrap"

                        #
                        #  Session resumption / fast reauthentication
                        #  cache.
                        #
                        cache {
                              #
                              #  Enable it.  The default is "no".
                              #  Deleting the entire "cache" subsection
                              #  Also disables caching.
                              #
                              enable = yes

                              #
                              #  Lifetime of the cached entries, in hours.
                              #  The sessions will be deleted after this
                              #  time.
                              #
                              lifetime = 24 # hours

                              #
                              #  The maximum number of entries in the
                              #  cache.  Set to "0" for "infinite".
                              #
                              #  This could be set to the number of users
                              #  who are logged in... which can be a LOT.
                              #
                              max_entries = 255
                        }
                }

                #  The TTLS module implements the EAP-TTLS protocol,
                #  which can be described as EAP inside of Diameter,
                #  inside of TLS, inside of EAP, inside of RADIUS...
                #
                #  Surprisingly, it works quite well.
                #
                #  The TTLS module needs the TLS module to be installed
                #  and configured, in order to use the TLS tunnel
                #  inside of the EAP packet.  You will still need to
                #  configure the TLS module, even if you do not want
                #  to deploy EAP-TLS in your network.  Users will not
                #  be able to request EAP-TLS, as it requires them to
                #  have a client certificate.  EAP-TTLS does not
                #  require a client certificate.
                #
                #  You can make TTLS require a client cert by setting
                #
                #       EAP-TLS-Require-Client-Cert = Yes
                #
                #  in the control items for a request.
                #
                ttls {
                        #  The tunneled EAP session needs a default
                        #  EAP type which is separate from the one for
                        #  the non-tunneled EAP module.  Inside of the
                        #  TTLS tunnel, we recommend using EAP-MD5.
                        #  If the request does not contain an EAP
                        #  conversation, then this configuration entry
                        #  is ignored.
                        default_eap_type = md5

                        #  The tunneled authentication request does
                        #  not usually contain useful attributes
                        #  like 'Calling-Station-Id', etc.  These
                        #  attributes are outside of the tunnel,
                        #  and normally unavailable to the tunneled
                        #  authentication request.
                        #
                        #  By setting this configuration entry to
                        #  'yes', any attribute which NOT in the
                        #  tunneled authentication request, but
                        #  which IS available outside of the tunnel,
                        #  is copied to the tunneled request.
                        #
                        # allowed values: {no, yes}
                        copy_request_to_tunnel = no

                        #  The reply attributes sent to the NAS are
                        #  usually based on the name of the user
                        #  'outside' of the tunnel (usually
                        #  'anonymous').  If you want to send the
                        #  reply attributes based on the user name
                        #  inside of the tunnel, then set this
                        #  configuration entry to 'yes', and the reply
                        #  to the NAS will be taken from the reply to
                        #  the tunneled request.
                        #
                        # allowed values: {no, yes}
                        use_tunneled_reply = no

                        #
                        #  The inner tunneled request can be sent
                        #  through a virtual server constructed
                        #  specifically for this purpose.
                        #
                        #  If this entry is commented out, the inner
                        #  tunneled request will be sent through
                        #  the virtual server that processed the
                        #  outer requests.
                        #
                        virtual_server = "inner-tunnel"
                }

                ##################################################
                #
                #  !!!!! WARNINGS for Windows compatibility  !!!!!
                #
                ##################################################
                #
                #  If you see the server send an Access-Challenge,
                #  and the client never sends another Access-Request,
                #  then
                #
                #               STOP!
                #
                #  The server certificate has to have special OID's
                #  in it, or else the Microsoft clients will silently
                #  fail.  See the "scripts/xpextensions" file for
                #  details, and the following page:
                #
                #       http://support.microsoft.com/kb/814394/en-us
                #
                #  For additional Windows XP SP2 issues, see:
                #
                #       http://support.microsoft.com/kb/885453/en-us
                #
                #  Note that we do not necessarily agree with their
                #  explanation... but the fix does appear to work.
                #
                ##################################################

                #
                #  The tunneled EAP session needs a default EAP type
                #  which is separate from the one for the non-tunneled
                #  EAP module.  Inside of the TLS/PEAP tunnel, we
                #  recommend using EAP-MS-CHAPv2.
                #
                #  The PEAP module needs the TLS module to be installed
                #  and configured, in order to use the TLS tunnel
                #  inside of the EAP packet.  You will still need to
                #  configure the TLS module, even if you do not want
                #  to deploy EAP-TLS in your network.  Users will not
                #  be able to request EAP-TLS, as it requires them to
                #  have a client certificate.  EAP-PEAP does not
                #  require a client certificate.
                #
                #
                #  You can make PEAP require a client cert by setting
                #
                #       EAP-TLS-Require-Client-Cert = Yes
                #
                #  in the control items for a request.
                #
                peap {
                        #  The tunneled EAP session needs a default
                        #  EAP type which is separate from the one for
                        #  the non-tunneled EAP module.  Inside of the
                        #  PEAP tunnel, we recommend using MS-CHAPv2,
                        #  as that is the default type supported by
                        #  Windows clients.
                        default_eap_type = mschapv2

                        #  the PEAP module also has these configuration
                        #  items, which are the same as for TTLS.
                        copy_request_to_tunnel = no
                        use_tunneled_reply = no

                        #  When the tunneled session is proxied, the
                        #  home server may not understand EAP-MSCHAP-V2.
                        #  Set this entry to "no" to proxy the tunneled
                        #  EAP-MSCHAP-V2 as normal MSCHAPv2.
                #       proxy_tunneled_request_as_eap = yes

                        #
                        #  The inner tunneled request can be sent
                        #  through a virtual server constructed
                        #  specifically for this purpose.
                        #
                        #  If this entry is commented out, the inner
                        #  tunneled request will be sent through
                        #  the virtual server that processed the
                        #  outer requests.
                        #
                        virtual_server = "inner-tunnel"
                }

                #
                #  This takes no configuration.
                #
                #  Note that it is the EAP MS-CHAPv2 sub-module, not
                #  the main 'mschap' module.
                #
                #  Note also that in order for this sub-module to work,
                #  the main 'mschap' module MUST ALSO be configured.
                #
                #  This module is the *Microsoft* implementation of MS-CHAPv2
                #  in EAP.  There is another (incompatible) implementation
                #  of MS-CHAPv2 in EAP by Cisco, which FreeRADIUS does not
                #  currently support.
                #
                mschapv2 {
                }
        }