doc/rlm_mschap

   1 RADIUS MS-CHAP v1/v2 + MPPE support module
   2
   3 0. Introduction
   4
   5   rlm_mschap allows FreeRADIUS to authenticate users via MS-CHAPv1 or
   6 MS-CHAPv2 protocol. To authenticate users via MS-CHAPv1, either
   7 NT-Password or LM-Password is required (this depends on the NAS and
   8 client settings).  Unless the client is some outdated system (like
   9 Windows for Workgroups) NT-Password is usually enough.
  10
  11   rlm_mschap may also be used to perform PAP authentication against
  12 stored NT-Password or LM-Password.
  13
  14   Only NT-Password may be used to authenticate user via MS-CHAPv2.  NT
  15 and LM passwords are one way hashes taken with different algorithms
  16 used in the Windows network, instead of clear text password.  Clear
  17 text password can't be recovered from the hash by some universal
  18 method, but, in fact, unlike Unix hashes, someone who knows the hash
  19 can use all network resources without any knowlege of the clear text
  20 password.  You should make sure that the hashes are stored and
  21 transmitted over the network securely!
  22
  23   rlm_mschap also implements generation of MPPE initial keys and
  24 related attributes.
  25
  26 1. What does it do
  27
  28   The task for authorization part in RADIUS is to obtain user's
  29 parameters from storage. For MS-CHAP you should either store
  30 NT-Password/LM-Password in some source (LDAP, database, users file,
  31 SAMBA password file, etc) or to store cleartext password. In second
  32 case cleartext should be converted to NT/LM hashes. To perform this
  33 task rlm_mschap should be included in authorize{} section of config.cf
  34 (at the end of this section). Another reason to include rlm_mschap in
  35 authorize{} is to auto-detect MS-CHAP authentication attempt by
  36 specific attrbiutes. For this case authtype = MS-CHAP should be
  37 present in config section for mschap.
  38
  39 During authentication rlm_mschap checks challenge/response and adds
  40 MPPE attributes (if required).
  41
  42 2. How should I configure it
  43
  44 First, edit radiusd.conf file, in the 'mschap' section.
  45
  46 Config section parameters:
  47
  48
  49    authtype = MS-CHAP
  50
  51 This parameter is only required if you want to allow user to select
  52 between MS-CHAP and other authentication type (such as PAP or
  53 CHAP). In this case you need to include mschap in authorize{}
  54 section. If mschap find attributes related to MS-CHAP authentication
  55 it will replace Auth-Type parameter with one specified in in authtype.
  56
  57
  58   use_mppe = no
  59   use_mppe = yes (default)
  60
  61 If use_mppe is set to 'no', mschap will not generate MPPE-soecific attributes.
  62 MPPE is only used then you need data encryption (PPTP tunnel or PPP
  63 connection with data encryption supported by Microsoft RAS. For example
  64 you needn't MPPE if you use Cisco ASxxxx).
  65
  66
  67   require_encryption = no (default)
  68   require_encryption = yes
  69
  70 If require_encryption is set to 'no', the NAS will allow the client to
  71 choose if he wants to encrypt data inside PPTP or PPP connection. If
  72 require_encryption = yes NAS will force data encryption and client
  73 without Microsoft data encryption support will be disconnected.
  74
  75
  76   require_strong = no (default)
  77   require_strong = yes
  78
  79 If require_strong is set to 'no', the client is allowed to use any key
  80 length, if 'yes', only strong 128-bit keys are allowed.
  81
  82
  83 Authorize{} section:
  84
  85  You may want to include mschap in authorize{} section if either:
  86   - you need mschap was launched only if NAS requests MS-CHAP authentication
  87   - you store plain text passwords
  88  In last case mschap should follow the last module which retrieves user's
  89  information (for example after rlm_ldap if you store information in LDAP)
  90
  91 Authenticate{} section:
  92
  93  Of cause, mschap should be included in authenticate{} section.
  94
  95 Second, you should place passwords or hashes in some place. Yes, you can use
  96 SAMBA password file format (see rlm_passwd). If you prefer to store hashed
  97 passwords you can use smbencrypt utility located in the src/modules/rlm_mschap.
  98 Hint: use `cut` to obtain LM and NT hashes separately.
  99
 100 3. Known bugs:
 101
 102 - MS-CHAP doesn't work after upgrading from older FreeRADIUS version.
 103
 104   The reason is dictionary incompatibility. Make sure to update
 105   dictionary.microsoft located in raddb directory.
 106
 107 - Only ASCII passwords are supported.
 108
 109   Unicode conversion is not fully implemented yet and passwords with
 110   extended characters will not work unless you exported NT/LM hashes
 111   from some some external source (for example from NT domain with
 112   pwdump).
 113
 114 - FreeRADIUS doesn't correctly proxies MS-CHAP-MPPE-Keys reply for
 115 MS-CHAPv1 MPPE support between RRAS and ISA servers.
 116
 117   Data in this attribute is encoded in a same fashion as User-Password
 118   attribute and attribute should be reassembled. FreeRADIUS
 119   architecture allows things like this (and it works for MS-CHAPv2
 120   MPPE support), but for this specific type of encoding it's not
 121   implemented yet. If you really need this feature - call developers
 122   and it will be implemented.
 123
 124 - 128 bit MPPE support is not implemented like RFC 3079 says.
 125
 126   It's a bug of RFC 3079 commited by developers. Glenn Zorn
 127   <gwz@cisco.com> has promised to submit a correction to the RFC.
 128
 129
 130 4. FAQ
 131
 132 Q: Can I use rlm_mschap to authenticate against NT or Win2K domain?
 133 A: NO. rlm_mschap is supposed to perform MS-CHAP authentication, not
 134    authentication against domain.
 135
 136 Q: Can I migrate my dialup users from NT or Win2K domain to FreeRADIUS?
 137 A: Yes. You can use pwdump2 utility by Todd Sabin to obtain NT/LM hashed
 138    passwords. Check http://www.packetstormsecurity.org for pwdump and same
 139    tools. This will produce SAMBA passwd file you can use with rlm_passwd
 140    module or you can export this data to some database.
 141
 142 Q: I see integrated support for SAMBA passwd format in rlm_mschap. May
 143    I use it?
 144 A: You shouldn't, because this functionality is moved to rlm_passwd module
 145    and will be excluded from future rlm_mschap versions.
 146
 147 Q: Can I synchronize my SAMBA domain with NT/2K domain to obtain hashed
 148    passwords into passwd file or LDAP automatically?
 149 A: At current time (Wed Jul 17 18:14:34 MSD 2002) SAMBA doesn't support
 150    BDC role and undocumented domain syncrhonization API. But the work is
 151    in progress. If somebody really interested it's really possible to
 152    create a daemon based on pwdump2 code which will dump NT/LM hashes from
 153    domain controller to file or to give 'em other the network by request.
 154
 155 Q: If I store only NT-Password and LM-Password can user do PAP?
 156 A: Yes. Just add rlm_mschap to authenticate{} and set Auth-Type to MS-CHAP
 157
 158 Q: If I store only NT-Password and LM-Password can user do CHAP?
 159 A: NO. For CHAP you have to store cleartext password.
 160
 161 5. Acknowlegements:
 162
 163    Jay Miller, <jaymiller@socket.net> initial MS-CHAPv1 realization
 164    Takahiro Wagatsuma, <waga@sic.shibaura-it.ac.jp> MPPE support
 165    ZARAZA, <3APA3A@security.nnov.ru> modifications, MS-CHAPv2, documentation