AccessCheckByTypeResultList 함수(securitybaseapi.h)

아티클
08/25/2023

AccessCheckByTypeResultList 함수는 보안 설명자가 액세스 토큰으로 식별된 클라이언트에 지정된 액세스 권한 집합을 부여하는지 여부를 결정합니다. 함수는 개체, 해당 속성 집합 및 속성과 같은 개체의 계층 구조에 대한 클라이언트의 액세스를 검사 수 있습니다. 함수는 계층의 각 개체 형식에 부여되거나 거부된 액세스 권한을 보고합니다. 일반적으로 서버 애플리케이션은 이 함수를 사용하여 프라이빗 개체에 대한 액세스를 검사.

구문

BOOL AccessCheckByTypeResultList(
  [in]                PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                HANDLE               ClientToken,
  [in]                DWORD                DesiredAccess,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [out]               PGENERIC_MAPPING     GenericMapping,
  [out, optional]     PPRIVILEGE_SET       PrivilegeSet,
  [in, out]           LPDWORD              PrivilegeSetLength,
  [out]               LPDWORD              GrantedAccessList,
  [out]               LPDWORD              AccessStatusList
);

매개 변수

[in] pSecurityDescriptor

액세스가 검사되는 SECURITY_DESCRIPTOR 구조체에 대한 포인터입니다.

[in, optional] PrincipalSelfSid

SID( 보안 식별자 )에 대한 포인터입니다. 보안 설명자가 보안 주체를 나타내는 개체(예: 사용자 개체)와 연결된 경우 PrincipalSelfSid 매개 변수는 개체의 SID여야 합니다. 액세스를 평가할 때 이 SID는 잘 알려진 PRINCIPAL_SELF SID(S-1-5-10)가 포함된 ACE( 액세스 제어 항목 )의 SID를 논리적으로 대체합니다. 잘 알려진 SID에 대한 자세한 내용은 잘 알려진 SID를 참조하세요.

보호된 개체가 보안 주체를 나타내지 않는 경우 이 매개 변수를 NULL로 설정합니다.

[in] ClientToken

액세스 권한을 얻으려고 시도하는 클라이언트를 나타내는 가장 토큰 에 대한 핸들입니다. 핸들에는 토큰에 대한 TOKEN_QUERY 액세스 권한이 있어야 합니다. 그렇지 않으면 함수가 ERROR_ACCESS_DENIED 실패합니다.

[in] DesiredAccess

검사 대한 액세스 권한을 지정하는 액세스 마스크입니다. 이 마스크는 제네릭 액세스 권한이 없도록 MapGenericMask 함수에 의해 매핑되어야 합니다.

이 매개 변수가 MAXIMUM_ALLOWED 경우 함수는 GrantedAccess 배열의 액세스 마스크를 설정하여 개체 형식 목록의 각 요소에 대한 클라이언트의 최대 액세스 권한을 나타냅니다.

[in, out, optional] ObjectTypeList

액세스를 검사 개체 형식의 계층 구조를 식별하는 OBJECT_TYPE_LIST 구조체 배열에 대한 포인터입니다. 배열의 각 요소는 개체 형식을 식별하는 GUID와 개체 형식의 계층 구조에서 개체 형식의 수준을 나타내는 값을 지정합니다. 배열에는 동일한 GUID를 가진 두 개의 요소가 없어야 합니다.

배열에는 하나 이상의 요소가 있어야 합니다. 배열의 첫 번째 요소는 수준 0이어야 하며 개체 자체를 식별해야 합니다. 배열에는 하나의 수준 0 요소만 있을 수 있습니다. 두 번째 요소는 수준 1의 속성 집합과 같은 하위 개체입니다. 각 수준 1 항목 다음에는 수준 2~4 하위 개체에 대한 하위 항목이 있습니다. 따라서 배열의 요소 수준은 {0, 1, 2, 2, 1, 2, 3}일 수 있습니다. 개체 형식 목록이 순서를 벗어나면 AccessCheckByTypeResultList 가 실패하고 GetLastError가 ERROR_INVALID_PARAMETER 반환합니다.

[in] ObjectTypeListLength

ObjectTypeList 배열의 요소 수입니다. 이는 GrantedAccessList 및 AccessStatusList 매개 변수가 가리키는 배열의 요소 수이기도 합니다.

[out] GenericMapping

액세스가 검사되는 개체와 연결된 GENERIC_MAPPING 구조체에 대한 포인터입니다.

[out, optional] PrivilegeSet

액세스 유효성 검사를 수행하는 데 사용되는 권한을 받는 PRIVILEGE_SET 구조체에 대한 포인터입니다. 권한이 사용되지 않은 경우 함수는 PrivilegeCount 멤버를 0으로 설정합니다.

[in, out] PrivilegeSetLength

PrivilegeSet 매개 변수가 가리키는 버퍼의 크기(바이트)입니다.

[out] GrantedAccessList

액세스 마스크 배열에 대한 포인터입니다. 함수는 각 액세스 마스크를 설정하여 개체 형식 목록의 해당 요소에 부여된 액세스 권한을 나타냅니다. 함수가 실패하면 액세스 마스크를 설정하지 않습니다.

[out] AccessStatusList

개체 형식 목록의 해당 요소에 대한 상태 코드 배열에 대한 포인터입니다. 함수는 요소를 0으로 설정하여 성공을 나타내거나 0이 아닌 값을 설정하여 액세스 검사 동안 특정 오류를 나타냅니다. 함수가 실패하면 배열의 요소를 설정하지 않습니다.

반환 값

함수가 성공하면 함수는 0이 아닌 값을 반환합니다.

함수가 실패하면 0을 반환합니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

설명

자세한 내용은 AccessCheck 작동 방법 개요를 참조하세요.

AccessCheckByTypeResultList 함수는 지정된 보안 설명자를 지정된 액세스 토큰과 비교하고 AccessStatusList 매개 변수에서 개체 유형 목록의 각 요소에 대해 액세스 권한이 부여되거나 거부되는지 여부를 나타냅니다.

ObjectTypeList 배열이 정의된 전체 개체를 반드시 나타내는 것은 아닙니다. 대신 액세스를 검사 개체의 하위 집합을 나타냅니다. instance 경우 속성 집합의 두 속성에 대한 액세스를 검사 4개의 요소가 있는 개체 유형 목록을 지정합니다. 즉, 개체 자체는 수준 0에, 속성은 수준 1에, 두 속성은 수준 2에 있습니다.

AccessCheckByTypeResultList 함수는 ObjectTypeList 배열에 나열된 개체 형식에 대해 개체 자체 및 개체별 ACE에 적용되는 ACE를 평가합니다. 함수는 ObjectTypeList 배열에 나열되지 않은 개체 형식에 대해 개체별 ACE를 무시합니다. 따라서 AccessStatusList 매개 변수의 요소 0에 대해 반환된 결과는 전체 개체가 아니라 ObjectTypeList 매개 변수로 정의된 개체의 하위 집합에 허용되는 액세스를 나타냅니다.

AES 계층 구조에서 개체 및 해당 하위 개체에 대한 액세스를 제어하는 방법에 대한 자세한 내용은 개체 의 속성에 대한 액세스 제어를 참조하세요.

보안 설명자의 DACL(임의 액세스 제어 목록 )이 NULL인 경우 함수는 요청된 개체 형식 목록의 모든 요소에 대한 액세스 권한을 부여합니다.

보안 설명자에 소유자 및 그룹 SID가 포함되어 있지 않으면 AccessCheckByTypeResultList 가 ERROR_INVALID_SECURITY_DESCR 실패합니다.

요구 사항

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