MSChapSrvChangePassword function (mschapp.h)

Article
10/13/2021

The MSChapSrvChangePassword function changes the password of a user account.

Syntax

DWORD MSChapSrvChangePassword(
  [in] PWSTR            ServerName,
  [in] PWSTR            UserName,
  [in] BOOLEAN          LmOldPresent,
  [in] PLM_OWF_PASSWORD LmOldOwfPassword,
  [in] PLM_OWF_PASSWORD LmNewOwfPassword,
  [in] PNT_OWF_PASSWORD NtOldOwfPassword,
  [in] PNT_OWF_PASSWORD NtNewOwfPassword
);

Parameters

[in] ServerName

A pointer to a null-terminated Unicode string that specifies the Universal Naming Convention (UNC) name of the server on which to operate. If this parameter is NULL, the function operates on the local computer.

[in] UserName

A pointer to a null-terminated Unicode string that specifies the name of the user whose password is being changed.

[in] LmOldPresent

A BOOLEAN that specifies whether the password designated by LmOldOwfPassword is valid. LmOldPresent is FALSE if the LmOldOwfPassword password is greater than 128-bits in length, and therefore cannot be represented by a Lan Manager (LM) one-way function (OWF) password. Otherwise, it is TRUE.

[in] LmOldOwfPassword

A pointer to a LM_OWF_PASSWORD structure that contains the OWF of the user's current LM password. This parameter is ignored if LmOldPresent is FALSE.

[in] LmNewOwfPassword

A pointer to a LM_OWF_PASSWORD structure that contains the OWF of the user's new LM password.

[in] NtOldOwfPassword

A pointer to a NT_OWF_PASSWORD structure that contains the OWF of the user's current NT password.

[in] NtNewOwfPassword

A pointer to a NT_OWF_PASSWORD structure that contains the OWF of the user's new NT password.

Return value

If the function succeeds, the return value is STATUS_SUCCESS (0x00000000).

If the function fails, the return value is one of the following error codes from ntstatus.h.

Return code/value	Description
STATUS_ACCESS_DENIED 0xC0000022	The calling application does not have the appropriate privilege to complete the operation.
STATUS_INVALID_HANDLE 0xC0000008	The specified server or user name was not valid.
STATUS_ILL_FORMED_PASSWORD 0xC000006B	New password is poorly formed, for example, it contains characters that cannot be entered from the keyboard.
STATUS_PASSWORD_RESTRICTION 0xC000006C	A restriction prevents the password from being changed. Possible restrictions include time restrictions on how often a password is allowed to be changed or length restrictions on the provided password. This error is also returned if the new password matched a password in the recent history log for the account. Security administrators specify how many of the most recently used passwords are not available for re-use. These are kept in the password recent history log.
STATUS_WRONG_PASSWORD 0xC000006A	The old password parameter does not match the user's current password.
STATUS_INVALID_DOMAIN_STATE 0xC00000DD	The domain controller is not in an enabled state. The domain controller must be enabled for this operation.
STATUS_INVALID_DOMAIN_ROLE 0xC00000DE	The domain controller is serving in the incorrect role to perform the requested operation. The operation can only be performed by the primary domain controller.
STATUS_INVALID_PARAMETER_MIX 0xC0000030	The value of the LmOldPresent parameter is not correct for the contents of the old and new parameter pairs.

Remarks

The value specified by LmNewOwfPassword must always contain a valid OWF. If the new password is greater than 128-bits long, and therefore cannot be represented by a LAN Manager (LM) password, then LmNewOwfPassword should be the LM OWF of a NULL password.

This function allows users to change their own passwords only if they have the access: USER_CHANGE_PASSWORD.

This function fails with STATUS_PASSWORD_RESTRICTION if the attempt to change the password conflicts with an administrative password restriction.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	mschapp.h
Library	Advapi32.lib
DLL	Advapi32.dll