MSChapSrvChangePassword function (mschapp.h)
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 |
|---|---|
|
The calling application does not have the appropriate privilege to complete the operation. |
|
The specified server or user name was not valid. |
|
New password is poorly formed, for example, it contains characters that cannot be entered from the keyboard. |
|
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. |
|
The old password parameter does not match the user's current password. |
|
The domain controller is not in an enabled state. The domain controller must be enabled for this operation. |
|
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. |
|
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 |