BuildSecurityDescriptorW 함수(aclapi.h)

아티클
03/14/2023

BuildSecurityDescriptor 함수는 새 보안 설명자를 할당하고 초기화합니다. 이 함수는 지정된 보안 정보를 기존 보안 설명자의 정보와 병합하여 새 보안 설명자를 초기화할 수 있습니다. 기존 보안 설명자를 지정하지 않으면 함수는 지정된 보안 정보를 기반으로 새 보안 설명자를 초기화합니다.

BuildSecurityDescriptor 함수는 자체 상대 보안 설명자를 만듭니다. 자체 상대 형식을 사용하면 보안 설명자가 스트림에 저장하기에 적합합니다.

구문

DWORD BuildSecurityDescriptorW(
  [in, optional] PTRUSTEE_W           pOwner,
  [in, optional] PTRUSTEE_W           pGroup,
  [in]           ULONG                cCountOfAccessEntries,
  [in, optional] PEXPLICIT_ACCESS_W   pListOfAccessEntries,
  [in]           ULONG                cCountOfAuditEntries,
  [in, optional] PEXPLICIT_ACCESS_W   pListOfAuditEntries,
  [in, optional] PSECURITY_DESCRIPTOR pOldSD,
  [out]          PULONG               pSizeNewSD,
  [out]          PSECURITY_DESCRIPTOR *pNewSD
);

매개 변수

[in, optional] pOwner

새 보안 설명자의 소유자를 식별하는 TRUSTEE 구조체에 대한 포인터입니다. 구조체가 TRUSTEE_IS_NAME 양식을 사용하는 경우 BuildSecurityDescriptor 는 지정된 트러스티 이름과 연결된 SID( 보안 식별자 )를 조회합니다.

이 매개 변수가 NULL인 경우 함수는 pOldSD가 가리키는 원래 보안 설명자의 소유자 SID를 사용합니다. pOldSD가 NULL이거나 pOldSD의 소유자 SID가 NULL인 경우 소유자 SID는 새 보안 설명자의 NULL입니다.

[in, optional] pGroup

새 보안 설명자에 대한 기본 그룹 SID를 식별하는 TRUSTEE 구조체에 대한 포인터입니다. 구조체가 TRUSTEE_IS_NAME 양식을 사용하는 경우 BuildSecurityDescriptor 는 지정된 트러스티 이름과 연결된 SID를 조회합니다.

이 매개 변수가 NULL인 경우 함수는 pOldSD가 가리키는 원래 보안 설명자의 그룹 SID를 사용합니다. pOldSD가 NULL이거나 pOldSD의 그룹 SID가 NULL인 경우 그룹 SID는 새 보안 설명자의 NULL입니다.

[in] cCountOfAccessEntries

pListOfAccessEntries 배열의 EXPLICIT_ACCESS 구조체 수입니다.

[in, optional] pListOfAccessEntries

새 보안 설명자의 DACL(임의 액세스 제어 목록)에 대한 액세스 제어 정보를 설명하는 EXPLICIT_ACCESS 구조 배열에 대한 포인터입니다. 함수는 배열의 정보를 pOldSD의 DACL(있는 경우)과 병합하여 새 DACL을 만듭니다. pOldSD가 NULL이거나 pOldSD의 DACL이 NULL인 경우 함수는 배열의 정보만을 기반으로 새 DACL을 만듭니다. EXPLICIT_ACCESS 구조체 배열에서 ACL을 만드는 규칙에 대한 설명은 SetEntriesInAcl 함수를 참조하세요.

pListOfAccessEntries가 NULL인 경우 새 보안 설명자는 pOldSD에서 DACL을 가져옵니다. 이 경우 pOldSD 가 NULL이거나 pOldSD 의 DACL이 NULL인 경우 새 DACL은 NULL입니다.

[in] cCountOfAuditEntries

pListOfAuditEntries 배열의 EXPLICIT_ACCESS 구조체 수입니다.

[in, optional] pListOfAuditEntries

새 보안 설명자의 SACL에 대한 감사 제어 정보를 설명하는 EXPLICIT_ACCESS 구조체 배열에 대한 포인터입니다. 함수는 배열의 정보를 pOldSD의 SACL(있는 경우)과 병합하여 새 SACL을 만듭니다. pOldSD가 NULL이거나 pOldSD의 SACL이 NULL인 경우 함수는 배열의 정보만을 기반으로 새 SACL을 만듭니다.

pListOfAuditEntries가 NULL인 경우 새 보안 설명자는 pOldSD에서 SACL을 가져옵니다. 이 경우 pOldSD 가 NULL이거나 pOldSD 의 SACL이 NULL인 경우 새 SACL은 NULL입니다.

[in, optional] pOldSD

기존 자체 상대 SECURITY_DESCRIPTOR 구조 및 관련 보안 정보에 대한 포인터입니다. 함수는 지정된 소유자, 그룹, 액세스 제어 및 감사 제어 정보를 이 보안 설명자의 정보와 병합하여 새 보안 설명자를 빌드합니다. 이 매개 변수는 NULL일 수 있습니다.

[out] pSizeNewSD

보안 설명자의 크기(바이트)를 수신하는 변수에 대한 포인터입니다.

[out] pNewSD

새 보안 설명자에 대한 포인터를 수신하는 변수에 대한 포인터입니다. 함수는 새 보안 설명자에 대한 메모리를 할당합니다. 반환된 버퍼를 해제하려면 LocalFree 함수를 호출해야 합니다.

반환 값

함수가 성공하면 함수는 ERROR_SUCCESS 반환합니다.

함수가 실패하면 WinError.h에 정의된 0이 아닌 오류 코드를 반환합니다.

설명

BuildSecurityDescriptor 함수는 자체 개체에 대한 보안을 구현하거나 노출하는 신뢰할 수 있는 서버를 위한 것입니다. 이 함수는 신뢰할 수 있는 서버에 필요할 수 있으므로 스트림으로 직렬화하고 디스크에 저장하는 데 적합한 자체 상대 보안 설명자를 사용합니다.

참고

aclapi.h 헤더는 BUILDSecurityDescriptor를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

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