Функция 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

Указатель на константную строку Юникода, указывающую имя удаленного сервера, на котором выполняется функция. Эта строка должна начинаться с \ и имя удаленного сервера. Если этот параметр имеет значение 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 . Приложение должно проверить элемент ValidationStatus в структуре NET_VALIDATE_OUTPUT_ARG, на которую указывает параметр OutputArg, чтобы определить результаты проверки политики паролей проверка. Структура 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	Недостаточно памяти для выполнения операции.

Код возврата

Описание

ERROR_INVALID_PARAMETER

Неправильный параметр. Эта ошибка возвращается, если параметры InputArg или OutputArg имеют значение NULL. Эта ошибка также возвращается, если параметр квалификатора не равен NULL или параметр ValidationType не является одним из допустимых значений.

ERROR_NOT_ENOUGH_MEMORY

Недостаточно памяти для выполнения операции.

Функция NetValidatePasswordPolicy позволяет приложениям проверять пароли пользователей, которые находятся в базе данных учетной записи, предоставленной приложением. Эта функция также может использоваться для проверки соответствия паролей требованиям к сложности, устареению, минимальной длине и повторному использованию журнала политики паролей. Эта функция также предоставляет приложениям средства для реализации механизма блокировки учетной записи.

Функция NetValidatePasswordPolicy не проверяет пароли в учетных записях Active Directory и не может использоваться для этой цели. Единственная политика, которую эта функция проверяет пароль в учетных записях Active Directory, — это сложность пароля (надежность пароля).

Типичным сценарием использования функции NetValidatePasswordPolicy является принудительное выбор надежных паролей пользователями для веб-приложений и приложений, которые разрешают защиту паролем документов. Другой вариант использования этой функции — проверка сложности пароля в ситуации, когда пароль присоединяется к функциональной операции, а не к учетной записи пользователя; например, пароли, используемые с открытыми ключами на основе сертификата S/MIME.

Если функция NetValidatePasswordPolicy вызывается на контроллере домена, на котором выполняется Active Directory, доступ разрешен или запрещен на основе ACL для защищаемого объекта. Список управления доступом по умолчанию позволяет просматривать сведения всем пользователям, прошедшим проверку подлинности, и членам группы "Доступ, совместимый с Windows 2000". Если вы вызываете эту функцию на рядовом сервере или рабочей станции, все пользователи, прошедшие проверку подлинности, смогут просматривать сведения. Сведения об анонимном доступе и ограничении анонимного доступа на этих платформах см. в разделе Требования к безопасности для функций управления сетью. Дополнительные сведения о списках управления доступом, ACE и маркерах доступа см. в разделе модель контроль доступа.

Дескриптор безопасности объекта Domain используется для выполнения проверка доступа для функции NetValidatePasswordPolicy.

Чтобы вызвать NetValidatePasswordPolicy в контексте безопасности, который не используется по умолчанию, сначала вызовите функцию LogonUser , указав LOGON32_LOGON_NEW_CREDENTIALS в параметре dwLogonType , а затем вызовите NetValidatePasswordPolicy под олицетворением. Дополнительные сведения об олицетворении см. в разделе Олицетворение клиента.

Если код возврата функции NetValidatePasswordPolicyNerr_Success функция выделяет буфер, на который указывает параметр OutputArg , который содержит структуру NET_VALIDATE_OUTPUT_ARG с результатами операции. Приложение должно проверить элемент ValidationStatus в структуре NET_VALIDATE_OUTPUT_ARG, чтобы определить результаты проверки политики паролей проверка. Дополнительные сведения см. в разделе NET_VALIDATE_OUTPUT_ARG.

Обратите внимание, что приложение несет ответственность за сохранение всех данных в элементе ChangedPersistedFieldsструктуры NET_VALIDATE_OUTPUT_ARG , а также за любые сведения об объекте User. При следующем вызове NetValidatePasswordPolicy в том же экземпляре объекта User приложение должно предоставить обязательные поля из постоянных сведений.

При вызове NetValidatePasswordPolicy и указании NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG или NET_VALIDATE_PASSWORD_RESET_INPUT_ARG в параметре InputArg , вызов также проверяет пароль, передавая его через библиотеку DLL фильтра паролей, для использования на компьютере. Дополнительные сведения о фильтрах паролей см. в разделе Использование фильтров паролей.

Если возвращаемое значение из функции NetValidatePasswordPolicy не равно нулю, то параметру OutputArg присваивается значение NULL и не удается проверить политику паролей.

Функция NetValidatePasswordPolicyFree должна вызываться после вызова NetValidatePasswordPolicy , чтобы освободить память, выделенную для параметра OutputArg , возвращаемого вызовом функции NetValidatePasswordPolicy .

Требования

Требование	Значение
Минимальная версия клиента	Ни одна версия не поддерживается
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	lmaccess.h (включая Lm.h)
Библиотека	Netapi32.lib
DLL	Netapi32.dll