#  -*- text -*-
#
#
#  $Id: 721b9b378b430abd2eacdfbc58c455795ef8002b $

#######################################################################
#
#  = Microsoft CHAP authentication Module
#
#  The `mschap` module performs `MS-CHAP` and `MS-CHAPv2` authentication.
#
#  MS-CHAP authentication requires access to either the
#  Password.Cleartext or Password.NT attribute for the user.  Due to
#  the limitations of MS-CHAP, no other password "encryption" methods
#  are possible.
#
#  This module validates a user with `MS-CHAP` or `MS-CHAPv2` authentication.
#  If called in `recv Access-Request`, it will look for `MS-CHAP` Challenge/Response
#  attributes in the `request` list and adds an `Auth-Type` attribute set to
#  `mschap` in the Config-Items list unless Auth-Type has already set.
#
#  The module also enforces the `SMB-Account-Ctrl` attribute. See the
#  Samba documentation for the meaning of SMB account control. The
#  module does not read Samba password files. Instead, the rlm_passwd
#  module can be used to read a Samba password file, and then supply
#  an `Password.NT` attribute which this module can use.
#
#  The `mschap` module registers a few `xlat` functions.
#
#  [options="header,autowidth"]
#  |===
#  | Function          | Description
#  | `Challenge`       | The MS-CHAP challenge.
#  | `Domain-Name`     | The full domain name, taken from the `User-Name` attribute
#  | `NT-Domain`       | The NT domain portion of the domain name, taken from the `User-Name` attribute
#  | `NT-Hash`         | Take the NT-Hash of the string passed into the xlat
#  | `NT-Response`     | The MS-CHAP response.
#  | `User-Name`       | The MS-CHAP username portion of the `User-Name` attribute.
#  |===
#
#  [NOTE]
#  ====
#  For more documentation on integrating FreeRADIUS with Active Directory, please
#  see the following web page:
#  http://deployingradius.com/documents/configuration/active_directory.html
#  ====
#

#
#  ## Configuration Settings
#
#  NOTE: If you are using `/etc/smbpasswd`, see the `passwd` module
#  for an example of how to use `/etc/smbpasswd`
#
mschap {
	#
	#  normalise::
	#
	#  By default the server will use heuristics to try and automatically
	#  handle base64 or hex encoded passwords or hashes.
	#  This behaviour can be disabled by setting the following to `no`.
	#
	#  The default is `yes`
	#
#	normalise = no

	#
	#  use_mppe::
	#
	#  By default the `mschap` will add `MS-CHAP-MPPE-Keys` for `MS-CHAPv1` and
	#  `MS-MPPE-Recv-Key` and `MS-MPPE-Send-Key` for `MS-CHAPv2`.  Set this
	#  configuration item to `no` in order to not add the MPPE keys.
	#
	#  Default is `yes`.
	#
#	use_mppe = no

	#
	#  require_encryption::
	#
	#  if `use_mppe` is enabled, the `require_encryption` makes encryption moderate.
	#
	#  Default is `no`.
	#
#	require_encryption = yes

	#
	#  require_strong::
	#
	#  It always requires 128 bit key encryption.
	#
	#  Default is `no`.
	#
#	require_strong = yes

	#
	#  with_ntdomain_hack:: Windows clients send `User-Name` in the form of "DOMAIN\User",
	#  but send the challenge/response based only on the User portion.
	#
	#  Default is `yes`.
	#
#	with_ntdomain_hack = no

	#
	#  ntlm_auth:: Path and arguments to the `ntlm_auth` program.
	#
	#  The module can perform authentication itself, OR
	#  use a Windows Domain Controller.  This configuration
	#  directive tells the module to call the `ntlm_auth`
	#  program, which will do the authentication, and return
	#  the `NT-Key`.
	#
	#  NOTE: you MUST have the such services "winbindd" and "nmbd"
	#  running on the local machine for `ntlm_auth` to work.
	#
	#  See the `ntlm_auth` program documentation for details.
	#
	#  If `ntlm_auth` is configured below, then the `mschap` module
	#  will call `ntlm_auth` for every `MS-CHAP` authentication request.
	#
	#  If there is a cleartext or NT hashed password available, you can set
	#  `MS-CHAP-Use-NTLM-Auth := No` in the control items, and the `mschap`
	#  module will do the authentication itself, without calling `ntlm_auth`.
	#
	#  You can also set `MS-CHAP-Use-NTLM-Auth := Auto`.  If a password is available,
	#  it will be used.  Otherwise the module will fall back to ntlm_auth.
	#
	#  You can also try setting the user name as:
	#
	#  `... --username=%mschap(User-Name) ...`
	#
	#  In that case, the `mschap` module will look at the `User-Name`
	#  attribute, and do prefix/suffix checks in order to obtain the _best_
	#  user name for the request.
	#
	#  Depending on the AD / Samba configuration, you may also need to add:
	#
	#  `--allow-mschapv2`
	#
	#  to the list of command-line options.
	#
	#  WARNING: Be VERY careful when editing the following line!
	#  Change the path, and ideally nothing else.
	#
#	ntlm_auth = "/path/to/ntlm_auth --request-nt-key  --allow-mschapv2 --username=%{&Stripped-User-Name || &User-Name || 'None'} --challenge=%{%mschap(Challenge) || 00} --nt-response=%{%mschap(NT-Response) || 00}"

	#
	#  ntlm_auth_timeout:: Time to wait for `ntlm_auth` to run.
	#
	#  This is a long time, and if `ntlm_auth` is taking that long
	#  then you likely have other problems in your domain.
	#
	#  The length of time can be decreased with the following
	#  option, which can save clients waiting if your `ntlm_auth`
	#  usually finishes quicker.
	#
	#  Range `1` to `10` seconds.
	#
	#  Default is `10` seconds.
	#
#	ntlm_auth_timeout = 10

	#
	#  winbind { ...}:: Configuration options for talking to Winbind.
	#
	winbind {
		#
		#  username:: User name for winbind
		#  domain:: Domain name for winbind
		#
		#  An alternative to using `ntlm_auth` is to connect to the
		#  winbind daemon directly for authentication. This option
		#  is likely to be faster and may be useful on busy systems.
		#
		#  Performance seems to be about twice that of `ntlm_auth`,
		#  which still isn't a lot.
		#
		#  Using this option requires libwbclient from Samba 4.2.1 or
		#  later to be installed. Make sure that `ntlm_auth` above is
		#  commented out.
		#
#		username = "%mschap(User-Name)"
#		domain = "%mschap(NT-Domain)"

		#
		#  retry_with_normalised_username::
		#
		#  When using single sign-on with a winbind connection and the
		#  client uses a different casing for the username than the
		#  casing is according to the backend, reauth may fail because
		#  of some Windows internals.
		#  This switch tries to find the user in the correct casing in
		#  the backend, and retry authentication with that username.
		#
#		retry_with_normalised_username = no

		#
		#  .Reusable Handles
		#
		#  Reusable connection handles are allocated in blocks.  These
		#  parameters allow for tuning how that is done.
		#
		reuse {
			#
			#  min:: The minimum number of connection handles to
			#  keep allocated
			#
#			min = 10

			#
			#  max:: The maximum number of reusable connection
			#  handles to allocate.
			#
#			max = 100

			#
			#  cleanup_interval:: How often to free un-used
			#  connection handles.
			#
#			cleanup_interval = 30s
		}
	}

	#
	#  .Pass Change
	#
	passchange {
		#
		#  ntlm_auth:: Path and arguments to ntlm_auth for password change.
		#
		#  ntlm_auth_username:: The user name for ntlm_auth password change.
		#
		#  ntlm_auth_domain:: The domain name for ntlm_auth password change.
		#
		#  This module support `MS-CHAPv2` (not v1) password
		#  change requests.  See `doc/howto/modules/mschap.adoc` for
		#  some IMPORTANT information.
		#
		#  Samba/ntlm_auth - if you are using `ntlm_auth` to validate
		#  passwords, you will need to use `ntlm_auth` to change passwords.
		#
		#  Uncomment the three lines below, and change the path to `ntlm_auth.
		#
#		ntlm_auth = "/usr/bin/ntlm_auth --helper-protocol=ntlm-change-password-1"
#		ntlm_auth_username = "username: %mschap(User-Name)"
#		ntlm_auth_domain = "nt-domain: %mschap(NT-Domain)"

		#
		#  local_cpw::
		#
		#  To implement a local password change, you need to supply a string
		#  which is then expanded, so that the password can be placed somewhere.
		#
		#  e.g. passed to a script (`exec`), or written to SQL (UPDATE/INSERT).
		#
		#  TIP: We give both examples here, but *only one should be used*.
		#
#		local_cpw = %exec('/path/to/script', %mschap(User-Name), %{MS-CHAP-New-Cleartext-Password})
#		local_cpw = %sql("UPDATE radcheck set value='%{MS-CHAP-New-NT-Password}' where username='%{User-Name}' and attribute='Password.NT'")

	}

	#
	#  use_open_directory::
	#
	#  For Apple Server, when running on the same machine as Open Directory.
	#  It has no effect on other systems.
	#
#	use_open_directory = yes

	#
	#  allow_retry::
	#
	#  On failure, set (or not) the `MS-CHAP` error code saying _retries allowed_.
	#
#	allow_retry = yes

	#
	#  retry_msg::
	#
	#  An optional retry message.
	#
#	retry_msg = "Re-enter (or reset) the password"

	#
	#  .Attributes
	#
	#  The `mschap` module needs to be configured with which attributes contain
	#  MS-CHAP data in the request and which should be used for MS-CHAP data
	#  in the reply.
	#
	#  This varies for different protocols.  The defaults show below are for
	#  RADIUS.
	#
	attributes {
		#
		#  username:: The attribute containing the user name.
		#
		username = &User-Name

		#
		#  chap_challenge::  The attribute containing the CHAP Challenge.
		#
		chap_challenge = &Vendor-Specific.Microsoft.CHAP-Challenge

		#
		#  chap_response::  The attribute containing the CHAP Response for MS-CHAPv1.
		#
		chap_response = &Vendor-Specific.Microsoft.CHAP-Response

		#
		#  chap2_response::  The attribute containing the CHAP Response for MS-CHAPv2.
		#
		chap2_response = &Vendor-Specific.Microsoft.CHAP2-Response

		#
		#  chap2_success::  The attribute MS-CHAPv2 success messages are returned in.
		#
		chap2_success = &Vendor-Specific.Microsoft.CHAP2-Success

		#
		#  chap_error::  The attribute CHAP error messages are returned in.
		#
		chap_error = &Vendor-Specific.Microsoft.CHAP-Error

		#
		#  chap_mppe_keys::  The attribute MPPE keys are returned in for MS-CHAPv1
		#
		chap_mppe_keys = &Vendor-Specific.Microsoft.CHAP-MPPE-Keys

		#
		#  mppe_recv_key::  The attribute MPPE recv key is returned in for MS-CHAPv2
		#
		mppe_recv_key = &Vendor-Specific.Microsoft.MPPE-Recv-Key

		#
		#  mppe_send_key::  The attribute MPPE send key is returned in for MS-CHAPv2
		#
		mppe_send_key = &Vendor-Specific.Microsoft.MPPE-Send-Key

		#
		#  mppe_encryption_policy::  The attribute that MPPE encryption policy is returned in.
		#
		mppe_encryption_policy = &Vendor-Specific.Microsoft.MPPE-Encryption-Policy

		#
		#  mppe_encryption_types::  The attribute that MPPE encryption type is returned in.
		#
		mppe_encryption_types = &Vendor-Specific.Microsoft.MPPE-Encryption-Types

		#
		#  chap2_cpw::  The attribute used to change a users' password
		#
		chap2_cpw =  &Vendor-Specific.Microsoft.CHAP2-CPW

		#
		#  chap_nt_enc_pw:: The attribute containing the encrypted new NT password
		#
		chap_nt_enc_pw = &Vendor-Specific.Microsoft.CHAP-NT-Enc-PW
	}

	#
	#  To use this instance of the mschap module to handle TACACS+ the attribute
	#  section should be replaced with the following.
	#
	#  TACACS+ does not have any inherent support for MPPE keys or password
	#  changing using MSCHAP.
	#
#	attributes {
#		username = &User-Name
#		chap_challenge = &MS-CHAP-Challenge
#		chap_response = &MS-CHAP-Response
#		chap2_response = &MS-CHAP2-Response

		#
		#  TACACS+ puts the MS-CHAP2-Success information in the Data field,
		#  but we call it MS-CHAP2-Success for simplicity.
		#  See the ALIAS definition in dictionary/tacacs/dictionary.freeradius.internal
		#
#		chap2_success = &MS-CHAP2-Success

		#
		#  Similarly, TACACS+ puts the MS-CHAP-Error into the Server-Message
		#  field.
		#
#		chap_error = &MS-CHAP-Error
#	}
}
