NetValidatePasswordPolicy-Funktion (lmaccess.h)

Artikel
03/01/2024

Die NetValidatePasswordPolicy-Funktion ermöglicht es einer Anwendung, die Kennwortkonformität mit einer von der Anwendung bereitgestellten Kontodatenbank zu überprüfen und zu überprüfen, ob Kennwörter die Anforderungen an Komplexität, Alterung, Mindestlänge und Verlaufswiederverwendung einer Kennwortrichtlinie erfüllen.

Syntax

NET_API_STATUS NET_API_FUNCTION NetValidatePasswordPolicy(
  [in]  LPCWSTR                    ServerName,
  [in]  LPVOID                     Qualifier,
  [in]  NET_VALIDATE_PASSWORD_TYPE ValidationType,
  [in]  LPVOID                     InputArg,
  [out] LPVOID                     *OutputArg
);

Parameter

[in] ServerName

Ein Zeiger auf eine konstante Unicode-Zeichenfolge, die den Namen des Remoteservers angibt, auf dem die Funktion ausgeführt werden soll. Diese Zeichenfolge muss mit \ beginnen, gefolgt vom Namen des Remoteservers. Wenn dieser Parameter NULL ist, wird der lokale Computer verwendet.

[in] Qualifier

Für die zukünftige Verwendung reserviert. Dieser Parameter muss NULL sein.

[in] ValidationType

Der Typ der durchzuführenden Kennwortüberprüfung. Dieser Parameter muss einer der folgenden enumerationskonstanten Werte sein.

typedef enum _NET_VALIDATE_PASSWORD_TYPE {

    NetValidateAuthentication = 1,
    NetValidatePasswordChange,
    NetValidatePasswordReset,

} NET_VALIDATE_PASSWORD_TYPE, *PNET_VALIDATE_PASSWORD_TYPE;

Diese Werte haben die folgende Bedeutung.

Wert	Bedeutung
NetValidateAuthentication	Die Anwendung fordert die Kennwortvalidierung während der Authentifizierung an. Der InputArg-Parameter verweist auf eine NET_VALIDATE_AUTHENTICATION_INPUT_ARG-Struktur . Diese Art der Überprüfung erzwingt die Richtlinie für den Kennwortablauf und die Kontosperrung.
NetValidatePasswordChange	Die Anwendung fordert die Kennwortvalidierung während eines Kennwortänderungsvorgangs an. Der InputArg-Parameter verweist auf eine NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG-Struktur .
NetValidatePasswordReset	Die Anwendung fordert die Kennwortvalidierung während eines Kennwortzurücksetzungsvorgangs an. Der InputArg-Parameter verweist auf eine NET_VALIDATE_PASSWORD_RESET_INPUT_ARG-Struktur . Sie können auch den "Sperrstatus" eines Benutzerkontos zurücksetzen, indem Sie diese Struktur angeben.

[in] InputArg

Ein Zeiger auf eine Struktur, die vom Typ der durchzuführenden Kennwortüberprüfung abhängt. Der Typ der Struktur hängt vom Wert des ValidationType-Parameters ab. Weitere Informationen finden Sie in der Beschreibung des ValidationType-Parameters .

[out] OutputArg

Wenn die NetValidatePasswordPolicy-Funktion erfolgreich ist (der Rückgabewert ist Nerr_Success), weist die Funktion einen Puffer zu, der die Ergebnisse des Vorgangs enthält. Der OutputArg-Parameter enthält einen Zeiger auf eine NET_VALIDATE_OUTPUT_ARG-Struktur . Die Anwendung muss das ValidationStatus-Element in der NET_VALIDATE_OUTPUT_ARG Struktur untersuchen, auf die der OutputArg-Parameter verweist, um die Ergebnisse der Überprüfung der Kennwortrichtlinie zu ermitteln. Die NET_VALIDATE_OUTPUT_ARG-Struktur enthält eine NET_VALIDATE_PERSISTED_FIELDS-Struktur mit Änderungen an persistenten Kennwortinformationen und den Ergebnissen der Kennwortüberprüfung. Die Anwendung muss planen, alle beibehaltenen Felder in der NET_VALIDATE_PERSISTED_FIELDS-Struktur außer dem ValidationStatus-Element als Informationen zusammen mit den Benutzerobjektinformationen beizubehalten und die erforderlichen Felder aus den persistenten Informationen bereitzustellen, wenn diese Funktion in Zukunft für dasselbe Benutzerobjekt aufgerufen wird.

Wenn die NetValidatePasswordPolicy-Funktion fehlschlägt (der Rückgabewert ist ungleich null), wird der OutputArg-Parameter auf einen NULL-Zeiger festgelegt, und die Kennwortrichtlinie konnte nicht untersucht werden.

Weitere Informationen finden Sie in den Abschnitten Rückgabewerte und Hinweise.

Rückgabewert

Wenn die Funktion erfolgreich ist und das Kennwort authentifiziert, geändert oder zurückgesetzt wird, wird der Rückgabewert NERR_Success, und die Funktion weist einen OutputArg-Parameter zu.

Wenn die Funktion fehlschlägt, ist der OutputArg-ParameterNULL , und der Rückgabewert ist ein Systemfehlercode, der einer der folgenden Fehlercodes sein kann. Eine Liste aller möglichen Fehlercodes finden Sie unter Systemfehlercodes.

Rückgabecode	Beschreibung
ERROR_INVALID_PARAMETER	Ein Parameter ist falsch. Dieser Fehler wird zurückgegeben, wenn die Parameter InputArg oder OutputArgNULL sind. Dieser Fehler wird auch zurückgegeben, wenn der Qualifier-Parameter nicht NULL ist oder wenn der ValidationType-Parameter keiner der zulässigen Werte ist.
ERROR_NOT_ENOUGH_MEMORY	Es ist nicht genügend Arbeitsspeicher verfügbar, um den Vorgang abzuschließen.

Hinweise

Die NetValidatePasswordPolicy-Funktion ist so konzipiert, dass Anwendungen Kennwörter für Benutzer überprüfen können, die sich in einer von der Anwendung bereitgestellten Kontodatenbank befinden. Diese Funktion kann auch verwendet werden, um zu überprüfen, ob Kennwörter den Anforderungen einer Kennwortrichtlinie an Komplexität, Alterung, Mindestlänge und Wiederverwendung des Verlaufs entsprechen. Diese Funktion stellt auch die Möglichkeit bereit, mit der eine Anwendung einen Mechanismus für die Kontosperrung implementieren kann.

Die NetValidatePasswordPolicy-Funktion überprüft keine Kennwörter in Active Directory-Konten und kann nicht für diesen Zweck verwendet werden. Die einzige Richtlinie, mit der diese Funktion ein Kennwort in Active Directory-Konten überprüft, ist die Kennwortkomplexität (die Kennwortstärke).

Ein typisches Szenario für die Verwendung der NetValidatePasswordPolicy-Funktion wäre die Erzwingung der Auswahl sicherer Kennwörter durch Benutzer für Webanwendungen und Anwendungen, die kennwortgeschützte Dokumente zulassen. Eine weitere Verwendung dieser Funktion könnte die Überprüfung der Kennwortkomplexität in einer Situation sein, in der ein Kennwort an einen funktionalen Vorgang und nicht an ein Benutzerkonto angefügt ist. Beispielsweise Kennwörter, die mit zertifikatbasierten öffentlichen Schlüsseln von Secure Multipurpose Internet Mail Extensions (S/MIME) verwendet werden.

Wenn die NetValidatePasswordPolicy-Funktion auf einem Domänencontroller aufgerufen wird, auf dem Active Directory ausgeführt wird, wird der Zugriff basierend auf der ACL für das sicherungsfähige Objekt zugelassen oder verweigert. Die Standard-ACL ermöglicht es allen authentifizierten Benutzern und Mitgliedern der Gruppe "Pre-Windows 2000-kompatibler Zugriff", die Informationen anzuzeigen. Wenn Sie diese Funktion auf einem Mitgliedsserver oder einer Arbeitsstation aufrufen, können alle authentifizierten Benutzer die Informationen anzeigen. Informationen zum anonymen Zugriff und zum Einschränken des anonymen Zugriffs auf diesen Plattformen finden Sie unter Sicherheitsanforderungen für die Netzwerkverwaltungsfunktionen. Weitere Informationen zu ACLs, ACEs und Zugriffstoken finden Sie unter Access Control Modell.

Der Sicherheitsdeskriptor des Domain-Objekts wird verwendet, um die Zugriffsüberprüfung für die NetValidatePasswordPolicy-Funktion durchzuführen.

Um NetValidatePasswordPolicy in einem Sicherheitskontext aufzurufen, der nicht der Standard ist, rufen Sie zuerst die LogonUser-Funktion auf, und geben Sie LOGON32_LOGON_NEW_CREDENTIALS im dwLogonType-Parameter an, und rufen Sie dann NetValidatePasswordPolicy unter Identitätswechsel auf. Weitere Informationen zum Identitätswechsel finden Sie unter Clientidentitätswechsel.

Wenn der Rückgabecode der NetValidatePasswordPolicy-FunktionNerr_Success ordnet die Funktion einen Puffer zu, auf den der OutputArg-Parameter verweist, der eine NET_VALIDATE_OUTPUT_ARG-Struktur mit den Ergebnissen des Vorgangs enthält. Die Anwendung muss das ValidationStatus-Element in der NET_VALIDATE_OUTPUT_ARG-Struktur untersuchen, um die Ergebnisse der Überprüfung der Kennwortrichtlinie zu ermitteln. Weitere Informationen finden Sie unter NET_VALIDATE_OUTPUT_ARG.

Beachten Sie, dass die Anwendung dafür verantwortlich ist, alle Daten im ChangedPersistedFields-Member der NET_VALIDATE_OUTPUT_ARG-Struktur sowie alle Benutzerobjektinformationen zu speichern. Wenn die Anwendung das nächste Mal NetValidatePasswordPolicy für dieselbe instance des User-Objekts aufruft, muss die Anwendung die erforderlichen Felder aus den persistenten Informationen bereitstellen.

Wenn Sie NetValidatePasswordPolicy aufrufen und NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG oder NET_VALIDATE_PASSWORD_RESET_INPUT_ARG im InputArg-Parameter angeben, überprüft der Aufruf auch das Kennwort, indem er es über die Kennwortfilter-DLL übergibt, für die der Computer konfiguriert ist. Weitere Informationen zu Kennwortfiltern finden Sie unter Verwenden von Kennwortfiltern.

Wenn der Rückgabewert der NetValidatePasswordPolicy-Funktion ungleich null ist, wird der OutputArg-Parameter auf NULL festgelegt, und die Kennwortrichtlinie konnte nicht untersucht werden.

Die NetValidatePasswordPolicyFree-Funktion sollte aufgerufen werden, nachdem NetValidatePasswordPolicy aufgerufen wurde, um den für den OutputArg-Parameter zugeordneten Arbeitsspeicher freizugeben, der vom Aufruf der NetValidatePasswordPolicy-Funktion zurückgegeben wird.

Anforderungen

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