doc/rlm_mschap

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