Share via

NetUserChangePassword-Funktion (lmaccess.h)

  • Artikel

Die NetUserChangePassword-Funktion ändert das Kennwort eines Benutzers für einen angegebenen Netzwerkserver oder eine angegebene Domäne.

Syntax

NET_API_STATUS NET_API_FUNCTION NetUserChangePassword(
  [in] LPCWSTR domainname,
  [in] LPCWSTR username,
  [in] LPCWSTR oldpassword,
  [in] LPCWSTR newpassword
);

Parameter

[in] domainname

Ein Zeiger auf eine konstante Zeichenfolge, die den DNS- oder NetBIOS-Namen eines Remoteservers oder einer Remotedomäne angibt, auf dem die Funktion ausgeführt werden soll. Wenn dieser Parameter NULL ist, wird die Anmeldedomäne des Aufrufers verwendet.

[in] username

Ein Zeiger auf eine konstante Zeichenfolge, die einen Benutzernamen angibt. Die NetUserChangePassword-Funktion ändert das Kennwort für den angegebenen Benutzer.

Wenn dieser Parameter NULL ist, wird der Anmeldename des Aufrufers verwendet. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in] oldpassword

Ein Zeiger auf eine konstante Zeichenfolge, die das alte Kennwort des Benutzers angibt.

[in] newpassword

Ein Zeiger auf eine konstante Zeichenfolge, die das neue Kennwort des Benutzers angibt.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert NERR_Success.

Wenn die Funktion fehlschlägt, kann der Rückgabewert einer der folgenden Fehlercodes sein.

Rückgabecode Beschreibung
ERROR_ACCESS_DENIED
 Der Benutzer besitzt keinen Zugriff auf die angeforderten Informationen.
ERROR_INVALID_PASSWORD
 Der Benutzer hat ein ungültiges Kennwort eingegeben.
NERR_InvalidComputer
 Der Computername ist ungültig.
NERR_NotPrimary
 Der Vorgang ist nur auf dem primären Domänencontroller der Domäne zulässig.
NERR_UserNotFound
 Der Benutzername konnte nicht gefunden werden.
NERR_PasswordTooShort
 Das Kennwort ist kürzer als erforderlich. (Das Kennwort kann möglicherweise auch zu lang, nicht über ausreichend Sonderzeichen verfügen, dessen Änderung noch nicht wirksam sein oder es stimmt nicht mit anderen Kennwortrichtlinien überein.)

Hinweise

Wenn Sie für Active Directory programmieren, können Sie möglicherweise bestimmte ADSI-Methoden (Active Directory Service Interface) aufrufen, um dasselbe Ergebnis zu erzielen, das Sie durch Aufrufen der Benutzerfunktionen der Netzwerkverwaltung erzielen können. Weitere Informationen finden Sie unter IADsUser und IADsComputer.

Wenn eine Anwendung die NetUserChangePassword-Funktion auf einem Domänencontroller aufruft, auf dem Active Directory ausgeführt wird, wird der Zugriff basierend auf der Zugriffssteuerungsliste (Access Control List, ACL) für das sicherungsfähige Objekt zugelassen oder verweigert. Die Standard-ACL erlaubt nur Domänenadministratoren und Kontooperatoren, diese Funktion aufzurufen. Auf einem Mitgliedsserver oder einer Arbeitsstation können nur Administratoren und Power Users diese Funktion aufrufen. Ein Benutzer kann sein eigenes Kennwort ändern. Weitere Informationen finden Sie unter Sicherheitsanforderungen für die Netzwerkverwaltungsfunktionen. Weitere Informationen zu ACLs, ACEs und Zugriffstoken finden Sie unter Access Control Modell.

Der Sicherheitsdeskriptor des User-Objekts wird verwendet, um die Zugriffsüberprüfung für diese Funktion durchzuführen. Darüber hinaus muss der Aufrufer über das Zugriffssteuerungsrecht "Kennwort ändern" für das User-Objekt verfügen. Dieses Recht wird standardmäßig anonymen Anmeldungen und Jedem gewährt.

Beachten Sie, dass der oldpassword-Parameter mit dem Kennwort übereinstimmen muss, damit die Funktion erfolgreich ist.

In einigen Fällen muss für den Prozess, der die NetUserChangePassword-Funktion aufruft, auch die berechtigung SE_CHANGE_NOTIFY_NAME aktiviert sein. Andernfalls schlägt NetUserChangePassword fehl, und GetLastError gibt ERROR_ACCESS_DENIED zurück. Diese Berechtigung ist für das LocalSystem-Konto oder für Konten, die Mitglieder der Administratorgruppe sind, nicht erforderlich. Standardmäßig ist SE_CHANGE_NOTIFY_NAME für alle Benutzer aktiviert, aber einige Administratoren können die Berechtigung für alle Benutzer deaktivieren. Weitere Informationen zu Kontoberechtigungen finden Sie unter Berechtigungen und Autorisierungskonstanten.

Unter Erzwingen eines Benutzers zum Ändern des Anmeldekennworts finden Sie ein Codebeispiel, in dem veranschaulicht wird, wie ein Benutzer das Ändern des Anmeldekennworts bei der nächsten Anmeldung mithilfe der Funktionen NetUserGetInfo und NetUserSetInfo erzwingt.

Benutzerkontennamen sind auf 20 Zeichen und Gruppennamen auf 256 Zeichen beschränkt. Darüber hinaus können Kontonamen nicht durch einen Punkt beendet werden, und sie dürfen keine Kommas oder eines der folgenden druckbaren Zeichen enthalten: ", /, , [, ], ], :, |, <, , >+, =, ;, ?, *. Namen können auch keine Zeichen im Bereich 1 bis 31 enthalten, die nicht druckbar sind.

Die NetUserChangePassword-Funktion steuert nicht, wie die Parameter oldpassword und newpassword geschützt werden, wenn sie über das Netzwerk an einen Remoteserver gesendet werden. Jede Verschlüsselung dieser Parameter wird vom RPC-Mechanismus (Remote Procedure Call) verarbeitet, der von der Netzwerkumleitung unterstützt wird, die den Netzwerktransport bereitstellt. Die Verschlüsselung wird auch durch die sicherheitsrelevanten Mechanismen gesteuert, die vom lokalen Computer unterstützt werden, und den Sicherheitsmechanismen, die vom Remotenetzwerkserver oder der im Parameter domainname angegebenen Remotenetzwerk-Server oder Domäne unterstützt werden. Weitere Informationen zur Sicherheit, wenn der Microsoft-Netzwerkumleitungsor verwendet wird und auf dem Remotenetzwerkserver Microsoft Windows ausgeführt wird, finden Sie in der Protokolldokumentation für MS-RPCE, MS-SAMR, MS-SPNG und MS-NLMP.

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie das Kennwort eines Benutzers mit einem Aufruf der NetUserChangePassword-Funktion geändert wird. Alle Parameter für die Funktion sind erforderlich.

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")

#include <stdio.h>
#include <windows.h> 
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwError = 0;
   NET_API_STATUS nStatus;
   //
   // All parameters are required.
   //
   if (argc != 5)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName UserName OldPassword NewPassword\n", argv[0]);
      exit(1);
   }
   //
   // Call the NetUserChangePassword function.
   //
   nStatus = NetUserChangePassword(argv[1], argv[2], argv[3], argv[4]);
   //
   // If the call succeeds, inform the user.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"User password has been changed successfully\n");
   //
   // Otherwise, print the system error.
   //
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   return 0;
}

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile lmaccess.h (lm.h einschließen)
Bibliothek Netapi32.lib
DLL Netapi32.dll

Weitere Informationen

NetUserGetInfo

NetUserSetInfo

Netzwerkverwaltungsfunktionen

Übersicht über die Netzwerkverwaltung

Benutzerfunktionen