Edit

Share via

MSChapSrvChangePassword2 function (mschapp.h)

  • Article

The MSChapSrvChangePassword2 function changes the password of a user account while supporting mutual encryption.

Syntax

DWORD MSChapSrvChangePassword2(
  [in] PWSTR                          ServerName,
  [in] PWSTR                          UserName,
  [in] PSAMPR_ENCRYPTED_USER_PASSWORD NewPasswordEncryptedWithOldNt,
  [in] PENCRYPTED_NT_OWF_PASSWORD     OldNtOwfPasswordEncryptedWithNewNt,
  [in] BOOLEAN                        LmPresent,
  [in] PSAMPR_ENCRYPTED_USER_PASSWORD NewPasswordEncryptedWithOldLm,
  [in] PENCRYPTED_LM_OWF_PASSWORD     OldLmOwfPasswordEncryptedWithNewLmOrNt
);

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] NewPasswordEncryptedWithOldNt

A pointer to a SAMPR_ENCRYPTED_USER_PASSWORD structure that contains the new clear text password encrypted using the current NT one-way function (OWF) password hash as the encryption key.

Note  Use the NewPasswordEncryptedWithOldNtPasswordHash() function as defined in RFC 2433, section A.11 to calculate the cipher for NewPasswordEncryptedWithOldNt.
 

[in] OldNtOwfPasswordEncryptedWithNewNt

A pointer to an ENCRYPTED_NT_OWF_PASSWORD structure that contains the old NT OWF password hash encrypted using the new NT OWF password hash as the encryption key.

[in] LmPresent

A BOOLEAN that specifies if the current Lan Manager (LM) or NT OWF password hashes are used as the encryption keys to generate the NewPasswordEncryptedWithOldNt and OldNtOwfPasswordEncryptedWithNewNt ciphers. If TRUE, the LM OWF password hashes are used rather than the NT OWF password hashes.

[in] NewPasswordEncryptedWithOldLm

A pointer to a SAMPR_ENCRYPTED_USER_PASSWORD structure that contains the new clear text password encrypted using the current LM OWF password hash.

Note  Use the NewPasswordEncryptedWithOldLmPasswordHash() function as defined in RFC 2433, section A.15 to calculate the cipher for NewPasswordEncryptedWithOldLm.
 

[in] OldLmOwfPasswordEncryptedWithNewLmOrNt

A pointer to a ENCRYPTED_LM_OWF_PASSWORD structure that contains the current LM OWF password hash encrypted using the new LM OWF password hash.

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.

Remarks

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

See also

MS-CHAP Password Management Functions

MSChapSrvChangePassword