NetValidatePasswordPolicy, fonction (lmaccess.h)

Article
08/24/2023

La fonction NetValidatePasswordPolicy permet à une application de case activée conformité des mots de passe par rapport à une base de données de compte fournie par l’application et de vérifier que les mots de passe répondent aux exigences de complexité, de vieillissement, de longueur minimale et de réutilisation de l’historique d’une stratégie de mot de passe.

Syntaxe

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
);

Paramètres

[in] ServerName

Pointeur vers une chaîne Unicode constante spécifiant le nom du serveur distant sur lequel la fonction doit s’exécuter. Cette chaîne doit commencer par \ suivie du nom du serveur distant. Si ce paramètre a la valeur NULL, l’ordinateur local est utilisé.

[in] Qualifier

Réservé pour un usage futur. Ce paramètre doit avoir la valeur NULL.

[in] ValidationType

Type de validation de mot de passe à effectuer. Ce paramètre doit être l’une des valeurs constantes énumérées suivantes.

typedef enum _NET_VALIDATE_PASSWORD_TYPE {

    NetValidateAuthentication = 1,
    NetValidatePasswordChange,
    NetValidatePasswordReset,

} NET_VALIDATE_PASSWORD_TYPE, *PNET_VALIDATE_PASSWORD_TYPE;

Ces valeurs ont les significations suivantes.

Valeur	Signification
NetValidateAuthentication	L’application demande la validation du mot de passe pendant l’authentification. Le paramètre InputArg pointe vers une structure NET_VALIDATE_AUTHENTICATION_INPUT_ARG . Ce type de validation applique l’expiration du mot de passe et la stratégie de verrouillage de compte.
NetValidatePasswordChange	L’application demande la validation du mot de passe lors d’une opération de modification de mot de passe. Le paramètre InputArg pointe vers une structure NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG .
NetValidatePasswordReset	L’application demande la validation du mot de passe lors d’une opération de réinitialisation de mot de passe. Le paramètre InputArg pointe vers une structure NET_VALIDATE_PASSWORD_RESET_INPUT_ARG . Vous pouvez également réinitialiser l’état de verrouillage d’un compte d’utilisateur en spécifiant cette structure.

[in] InputArg

Pointeur vers une structure qui dépend du type de validation de mot de passe à effectuer. Le type de structure dépend de la valeur du paramètre ValidationType . Pour plus d’informations, consultez la description du paramètre ValidationType .

[out] OutputArg

Si la fonction NetValidatePasswordPolicy réussit (la valeur renvoyée est Nerr_Success), la fonction alloue une mémoire tampon qui contient les résultats de l’opération. Le paramètre OutputArg contient un pointeur vers une structure NET_VALIDATE_OUTPUT_ARG . L’application doit examiner le membre ValidationStatus dans la structure NET_VALIDATE_OUTPUT_ARG pointée par le paramètre OutputArg pour déterminer les résultats de la case activée de validation de la stratégie de mot de passe. La structure NET_VALIDATE_OUTPUT_ARG contient une structure NET_VALIDATE_PERSISTED_FIELDS avec des modifications apportées aux informations persistantes liées au mot de passe et les résultats de la validation du mot de passe. L’application doit prévoir de conserver tous les champs conservés dans la structure NET_VALIDATE_PERSISTED_FIELDS à l’exception du membre ValidationStatus en tant qu’informations avec les informations de l’objet utilisateur et fournir les champs requis à partir des informations persistantes lors de l’appel de cette fonction à l’avenir sur le même objet utilisateur.

Si la fonction NetValidatePasswordPolicy échoue (la valeur de retour est différente de zéro), le paramètre OutputArg est défini sur un pointeur NULL et la stratégie de mot de passe n’a pas pu être examinée.

Pour plus d’informations, consultez les sections Valeurs de retour et Remarques.

Valeur retournée

Si la fonction réussit et que le mot de passe est authentifié, modifié ou réinitialisé, la valeur de retour est NERR_Success et la fonction alloue un paramètre OutputArg .

Si la fonction échoue, le paramètre OutputArg a la valeur NULL et la valeur renvoyée est un code d’erreur système qui peut être l’un des codes d’erreur suivants. Pour obtenir la liste de tous les codes d’erreur possibles, consultez Codes d’erreur système.

Code de retour	Description
ERROR_INVALID_PARAMETER	Un paramètre est incorrect. Cette erreur est retournée si les paramètres InputArg ou OutputArg ont la valeur NULL. Cette erreur est également retournée si le paramètre Qualifier n’a pas la valeur NULL ou si le paramètre ValidationType n’est pas l’une des valeurs autorisées.
ERROR_NOT_ENOUGH_MEMORY	La mémoire n'est pas suffisante pour terminer cette opération.

Remarques

La fonction NetValidatePasswordPolicy est conçue pour permettre aux applications de valider les mots de passe des utilisateurs qui se trouvent dans une base de données de compte fournie par l’application. Cette fonction peut également être utilisée pour vérifier que les mots de passe répondent aux exigences de complexité, de vieillissement, de longueur minimale et de réutilisation de l’historique d’une stratégie de mot de passe. Cette fonction fournit également les moyens pour une application d’implémenter un mécanisme de verrouillage de compte.

La fonction NetValidatePasswordPolicy ne valide pas les mots de passe dans les comptes Active Directory et ne peut pas être utilisée à cette fin. La seule stratégie pour laquelle cette fonction vérifie un mot de passe dans les comptes Active Directory est la complexité du mot de passe (la force du mot de passe).

Un scénario classique pour l’utilisation de la fonction NetValidatePasswordPolicy consiste à appliquer le choix de mots de passe forts par les utilisateurs pour les applications web et les applications qui autorisent les documents protégés par mot de passe. Une autre utilisation de cette fonction peut consister à vérifier la complexité des mots de passe dans une situation où un mot de passe est attaché à une opération fonctionnelle plutôt qu’à un compte d’utilisateur ; par exemple, les mots de passe utilisés avec des clés publiques basées sur des certificats S/MIME (Secure Multipurpose Internet Mail Extensions).

Si la fonction NetValidatePasswordPolicy est appelée sur un contrôleur de domaine qui exécute Active Directory, l’accès est autorisé ou refusé en fonction de la liste de contrôle d’accès de l’objet sécurisable. La liste de contrôle d’accès par défaut permet à tous les utilisateurs authentifiés et aux membres du groupe « Accès compatible pré-Windows 2000 » d’afficher les informations. Si vous appelez cette fonction sur un serveur membre ou une station de travail, tous les utilisateurs authentifiés peuvent afficher les informations. Pour plus d’informations sur l’accès anonyme et la restriction de l’accès anonyme sur ces plateformes, consultez Exigences de sécurité pour les fonctions de gestion réseau. Pour plus d’informations sur les listes de contrôle d’accès, les ACL et les jetons d’accès, consultez Access Control Modèle.

Le descripteur de sécurité de l’objet Domain est utilisé pour effectuer l’case activée d’accès pour la fonction NetValidatePasswordPolicy.

Pour appeler NetValidatePasswordPolicy dans un contexte de sécurité qui n’est pas la valeur par défaut, appelez d’abord la fonction LogonUser , en spécifiant LOGON32_LOGON_NEW_CREDENTIALS dans le paramètre dwLogonType , puis appelez NetValidatePasswordPolicy sous emprunt d’identité. Pour plus d’informations sur l’emprunt d’identité, consultez Emprunt d’identité client.

Si le code de retour de la fonction NetValidatePasswordPolicy est Nerr_Success la fonction alloue une mémoire tampon pointée vers le paramètre OutputArg qui contient une structure NET_VALIDATE_OUTPUT_ARG avec les résultats de l’opération. L’application doit examiner le membre ValidationStatus dans la structure NET_VALIDATE_OUTPUT_ARG pour déterminer les résultats de la case activée de validation de la stratégie de mot de passe. Pour plus d’informations, consultez NET_VALIDATE_OUTPUT_ARG.

Notez qu’il incombe à l’application d’enregistrer toutes les données dans le membre ChangedPersistedFields de la structure NET_VALIDATE_OUTPUT_ARG , ainsi que les informations de l’objet Utilisateur. La prochaine fois que l’application appelle NetValidatePasswordPolicy sur le même instance de l’objet User, l’application doit fournir les champs requis à partir des informations persistantes.

Lorsque vous appelez NetValidatePasswordPolicy et spécifiez NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG ou NET_VALIDATE_PASSWORD_RESET_INPUT_ARG dans le paramètre InputArg , l’appel valide également le mot de passe en le transmettant via la DLL de filtre de mot de passe que l’ordinateur est configuré pour utiliser. Pour plus d’informations sur les filtres de mot de passe, consultez Utilisation de filtres de mot de passe.

Si la valeur de retour de la fonction NetValidatePasswordPolicy n’est pas nulle, le paramètre OutputArg est défini sur NULL et la stratégie de mot de passe n’a pas pu être examinée.

La fonction NetValidatePasswordPolicyFree doit être appelée après l’appel de NetValidatePasswordPolicy pour libérer la mémoire allouée pour le paramètre OutputArg retourné par l’appel à la fonction NetValidatePasswordPolicy .

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Aucun pris en charge
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	lmaccess.h (include Lm.h)
Bibliothèque	Netapi32.lib
DLL	Netapi32.dll