NetValidatePasswordPolicy 函数 (lmaccess.h)

项目
08/24/2023

NetValidatePasswordPolicy 函数允许应用程序针对应用程序提供的帐户数据库检查密码合规性，并验证密码是否满足密码策略的复杂性、老化、最小长度和历史记录重用要求。

语法

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

参数

[in] ServerName

指向常量 Unicode 字符串的指针，该字符串指定要对其执行函数的远程服务器的名称。此字符串必须以 \ 开头，后跟远程服务器名称。如果此参数为 NULL，则使用本地计算机。

[in] Qualifier

保留供将来使用。此参数必须为 NULL。

[in] ValidationType

要执行的密码验证的类型。此参数必须是下列枚举常量值之一。

typedef enum _NET_VALIDATE_PASSWORD_TYPE {

    NetValidateAuthentication = 1,
    NetValidatePasswordChange,
    NetValidatePasswordReset,

} NET_VALIDATE_PASSWORD_TYPE, *PNET_VALIDATE_PASSWORD_TYPE;

这些值具有以下含义。

值	含义
NetValidateAuthentication	应用程序在身份验证期间请求密码验证。 InputArg 参数指向NET_VALIDATE_AUTHENTICATION_INPUT_ARG结构。这种类型的验证强制实施密码过期和帐户锁定策略。
NetValidatePasswordChange	应用程序在密码更改操作期间请求密码验证。 InputArg 参数指向NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG结构。
NetValidatePasswordReset	应用程序在密码重置操作期间请求密码验证。 InputArg 参数指向NET_VALIDATE_PASSWORD_RESET_INPUT_ARG结构。还可以通过指定此结构来重置用户帐户的“锁定状态”。

[in] InputArg

指向结构的指针，该结构取决于要执行的密码验证的类型。结构的类型取决于 ValidationType 参数的值。有关详细信息，请参阅 ValidationType 参数的说明。

[out] OutputArg

如果 NetValidatePasswordPolicy 函数成功 (返回值为 Nerr_Success) ，则该函数将分配包含操作结果的缓冲区。 OutputArg 参数包含指向NET_VALIDATE_OUTPUT_ARG结构的指针。应用程序必须检查 OutputArg 参数指向的NET_VALIDATE_OUTPUT_ARG结构中的 ValidationStatus 成员，以确定密码策略验证检查的结果。 NET_VALIDATE_OUTPUT_ARG结构包含一个NET_VALIDATE_PERSISTED_FIELDS结构，其中包含对永久密码相关信息的更改以及密码验证的结果。应用程序必须计划将 NET_VALIDATE_PERSISTED_FIELDS除ValidationStatus 成员之外的所有持久化字段保留为信息以及用户对象信息，并在将来在同一用户对象上调用此函数时提供持久化信息中所需的字段。

如果 NetValidatePasswordPolicy 函数失败 (返回值为非零) ，则 OutputArg 参数设置为 NULL 指针，并且无法检查密码策略。

有关详细信息，请参阅返回值和备注部分。

返回值

如果函数成功，并且密码已经过身份验证、更改或重置，则返回值NERR_Success，并且函数分配 OutputArg 参数。

如果函数失败， OutputArg 参数为 NULL ，返回值为系统错误代码，可以是以下错误代码之一。有关所有可能的错误代码的列表，请参阅系统错误代码。

返回代码	说明
ERROR_INVALID_PARAMETER	参数不正确。如果 InputArg 或 OutputArg 参数为 NULL，则返回此错误。如果限定符参数不是 NULL ，或者 ValidationType 参数不是允许的值之一，则也会返回此错误。
ERROR_NOT_ENOUGH_MEMORY	没有足够的可用内存来完成该操作。

注解

NetValidatePasswordPolicy 函数旨在允许应用程序为应用程序提供的帐户数据库中的用户验证密码。此函数还可用于验证密码是否满足密码策略的复杂性、老化、最小长度和历史记录重用要求。此函数还为应用程序提供实现帐户锁定机制的方法。

NetValidatePasswordPolicy 函数不验证 Active Directory 帐户中的密码，不能用于此目的。此函数在 Active Directory 帐户中检查密码的唯一策略是密码复杂性 (密码强度) 。

使用 NetValidatePasswordPolicy 函数的典型方案是强制用户为允许受密码保护的文档的 Web 应用程序和应用程序强制选择强密码。此功能的另一个用途可能是检查密码的复杂性，在这种情况下，密码附加到功能操作而不是用户帐户：例如，与安全多用途 Internet 邮件扩展一起使用的密码 (S/MIME) 基于证书的公钥。

如果在运行 Active Directory 的域控制器上调用 NetValidatePasswordPolicy 函数，则会根据安全对象的 ACL 允许或拒绝访问。默认 ACL 允许所有经过身份验证的用户和“Windows 2000 前兼容访问”组的成员查看信息。如果在成员服务器或工作站上调用此函数，则所有经过身份验证的用户都可以查看信息。有关这些平台上的匿名访问和限制匿名访问的信息，请参阅网络管理功能的安全要求。有关 ACL、ACE 和访问令牌的详细信息，请参阅访问控制模型。

Domain 对象的安全描述符用于执行 NetValidatePasswordPolicy 函数的访问检查。

若要在非默认安全上下文中调用 NetValidatePasswordPolicy ，请先调用 LogonUser 函数，在 dwLogonType 参数中指定LOGON32_LOGON_NEW_CREDENTIALS，然后在模拟下调用 NetValidatePasswordPolicy 。有关模拟的详细信息，请参阅客户端模拟。

如果 NetValidatePasswordPolicy 函数的返回代码 Nerr_Success 则该函数分配 由 OutputArg 参数指向的缓冲区，该参数包含 NET_VALIDATE_OUTPUT_ARG 结构以及操作的结果。应用程序必须检查NET_VALIDATE_OUTPUT_ARG结构中的 ValidationStatus 成员，以确定密码策略验证检查的结果。有关详细信息，请参阅 NET_VALIDATE_OUTPUT_ARG。

请注意，应用程序负责将所有数据保存在 NET_VALIDATE_OUTPUT_ARG 结构的 ChangedPersistedFields 成员中，以及任何 User 对象信息。下次应用程序在 User 对象的同一实例上调用 NetValidatePasswordPolicy 时，应用程序必须提供永久性信息中的必填字段。

调用 NetValidatePasswordPolicy 并在 InputArg 参数中指定NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG或NET_VALIDATE_PASSWORD_RESET_INPUT_ARG时，该调用还会通过计算机配置为使用的密码筛选器 DLL 传递密码来验证密码。有关密码筛选器的详细信息，请参阅使用密码筛选器。

如果 NetValidatePasswordPolicy 函数的返回值非零，则 OutputArg 参数设置为 NULL ，并且无法检查密码策略。

应在调用 NetValidatePasswordPolicy 后调用 NetValidatePasswordPolicy 函数，以释放为由调用 NetValidatePasswordPolicy 函数返回的 OutputArg 参数分配的内存。

要求

要求	值
最低受支持的客户端	无受支持的版本
最低受支持的服务器	Windows Server 2003 [仅限桌面应用]
目标平台	Windows
标头	lmaccess.h (包括 Lm.h)
Library	Netapi32.lib
DLL	Netapi32.dll