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 구조체에 대한 포인터를 포함합니다. 애플리케이션은 OutputArg 매개 변수가 가리키는 NET_VALIDATE_OUTPUT_ARG 구조에서 ValidationStatus 멤버를 검사하여 암호 정책 유효성 검사 검사 결과를 확인해야 합니다. NET_VALIDATE_OUTPUT_ARG 구조에는 영구 암호 관련 정보가 변경된 NET_VALIDATE_PERSISTED_FIELDS 구조와 암호 유효성 검사 결과가 포함됩니다. 애플리케이션은 ValidationStatus 멤버를 제외하고 NET_VALIDATE_PERSISTED_FIELDS 구조의 모든 지속형 필드를 사용자 개체 정보와 함께 정보로 유지하도록 계획하고 나중에 동일한 사용자 개체에서 이 함수를 호출할 때 지속형 정보의 필수 필드를 제공해야 합니다.

NetValidatePasswordPolicy 함수가 실패하면(반환 값이 0이 아님) 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 함수를 사용하는 일반적인 시나리오는 암호로 보호되는 문서를 허용하는 웹 애플리케이션 및 애플리케이션에 대한 사용자가 강력한 암호를 선택하는 것입니다. 이 함수의 또 다른 사용은 암호가 사용자 계정이 아닌 기능 작업에 연결된 상황에서 암호 복잡성을 확인하는 것일 수 있습니다. 예를 들어 S/MIME(Secure Multipurpose Internet Mail Extensions) 인증서 기반 공개 키와 함께 사용되는 암호입니다.

Active Directory를 실행하는 도메인 컨트롤러에서 NetValidatePasswordPolicy 함수가 호출되면 보안 개체에 대한 ACL에 따라 액세스가 허용되거나 거부됩니다. 기본 ACL은 "Pre-Windows 2000 호환 액세스" 그룹의 모든 인증된 사용자와 구성원이 정보를 볼 수 있도록 허용합니다. 멤버 서버 또는 워크스테이션에서 이 함수를 호출하는 경우 인증된 모든 사용자가 정보를 볼 수 있습니다. 이러한 플랫폼에서 익명 액세스 및 익명 액세스를 제한하는 방법에 대한 자세한 내용은 네트워크 관리 함수에 대한 보안 요구 사항을 참조하세요. ACL, ACL 및 액세스 토큰에 대한 자세한 내용은 Access Control 모델을 참조하세요.

도메인 개체의 보안 설명자는 NetValidatePasswordPolicy 함수에 대한 액세스 검사 수행하는 데 사용됩니다.

기본값이 아닌 보안 컨텍스트에서 NetValidatePasswordPolicy 를 호출하려면 먼저 LogonUser 함수를 호출하고 dwLogonType 매개 변수에 LOGON32_LOGON_NEW_CREDENTIALS 지정한 다음 가장에서 NetValidatePasswordPolicy 를 호출합니다. 가장에 대한 자세한 내용은 클라이언트 가장을 참조하세요.

NetValidatePasswordPolicy 함수의 반환 코드가 Nerr_Success 경우 함수는 작업의 결과와 함께 NET_VALIDATE_OUTPUT_ARG 구조를 포함하는 OutputArg 매개 변수가 가리키는 버퍼를 할당합니다. 애플리케이션은 NET_VALIDATE_OUTPUT_ARG 구조에서 ValidationStatus 멤버를 검사하여 암호 정책 유효성 검사 검사 결과를 확인해야 합니다. 자세한 내용은 NET_VALIDATE_OUTPUT_ARG 참조하세요.

NET_VALIDATE_OUTPUT_ARG 구조의ChangedPersistedFields 멤버에 있는 모든 데이터와 User 개체 정보를 저장하는 것은 애플리케이션의 책임입니다. 다음에 애플리케이션이 User 개체의 동일한 instance NetValidatePasswordPolicy를 호출할 때 애플리케이션은 영구 정보의 필수 필드를 제공해야 합니다.

NetValidatePasswordPolicy를 호출하고 InputArg 매개 변수에서 NET_VALIDATE_PASSWORD_CHANGE_INPUT_ARG 또는 NET_VALIDATE_PASSWORD_RESET_INPUT_ARG 지정하면 컴퓨터에서 사용하도록 구성된 암호 필터 DLL을 통해 암호를 전달하여 암호의 유효성을 검사합니다. 암호 필터에 대한 자세한 내용은 암호 필터 사용을 참조하세요.

NetValidatePasswordPolicy 함수의 반환 값이 0이 아니면 OutputArg 매개 변수가 NULL로 설정되고 암호 정책을 검사할 수 없습니다.

NetValidatePasswordPolicyPolicy 함수를 호출한 후 NetValidatePasswordPolicy 함수를 호출하여 OutputArg 매개 변수에 할당된 메모리를 해제한 후 NetValidatePasswordPolicy 함수를 호출해야 합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	지원되는 버전 없음
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	lmaccess.h(Lm.h 포함)
라이브러리	Netapi32.lib
DLL	Netapi32.dll