AdjustTokenPrivileges 함수(securitybaseapi.h)

아티클
08/25/2023

AdjustTokenPrivileges 함수는 지정된 액세스 토큰에서 권한을 사용하거나 사용하지 않도록 설정합니다. 액세스 토큰에서 권한을 사용하거나 사용하지 않도록 설정하려면 TOKEN_ADJUST_PRIVILEGES 액세스가 필요합니다.

구문

BOOL AdjustTokenPrivileges(
  [in]            HANDLE            TokenHandle,
  [in]            BOOL              DisableAllPrivileges,
  [in, optional]  PTOKEN_PRIVILEGES NewState,
  [in]            DWORD             BufferLength,
  [out, optional] PTOKEN_PRIVILEGES PreviousState,
  [out, optional] PDWORD            ReturnLength
);

매개 변수

[in] TokenHandle

수정할 권한이 포함된 액세스 토큰에 대한 핸들입니다. 핸들에는 토큰에 대한 TOKEN_ADJUST_PRIVILEGES 액세스 권한이 있어야 합니다. PreviousState 매개 변수가 NULL이 아닌 경우 핸들에도 TOKEN_QUERY 액세스 권한이 있어야 합니다.

[in] DisableAllPrivileges

함수가 토큰의 모든 권한을 사용하지 않도록 설정할지 여부를 지정합니다. 이 값이 TRUE이면 함수는 모든 권한을 사용하지 않도록 설정하고 NewState 매개 변수를 무시합니다. FALSE이면 함수는 NewState 매개 변수가 가리키는 정보에 따라 권한을 수정합니다.

[in, optional] NewState

권한 배열과 해당 특성을 지정하는 TOKEN_PRIVILEGES 구조체에 대한 포인터입니다. DisableAllPrivileges 매개 변수가 FALSE이면 AdjustTokenPrivileges 함수는 토큰에 대해 이러한 권한을 사용하거나 사용하지 않도록 설정하거나 제거합니다. 다음 표에서는 Privilege 특성에 따라 AdjustTokenPrivileges 함수에서 수행한 작업에 대해 설명합니다.

값	의미
SE_PRIVILEGE_ENABLED	함수는 권한을 사용하도록 설정합니다.
SE_PRIVILEGE_REMOVED	토큰의 권한 목록에서 권한이 제거됩니다. 목록의 다른 권한은 연속된 상태로 유지되도록 순서를 다시 지정합니다. SE_PRIVILEGE_REMOVED SE_PRIVILEGE_ENABLED 대체합니다. 토큰에서 권한이 제거되었으므로 권한의 결과를 다시 활성화하려고 하면 권한이 없는 것처럼 경고가 ERROR_NOT_ALL_ASSIGNED. 토큰에 없는 권한을 제거하려고 시도하면 ERROR_NOT_ALL_ASSIGNED 반환됩니다. 제거된 권한에 대한 권한 검사로 인해 STATUS_PRIVILEGE_NOT_HELD. 실패한 권한 검사 감사는 정상적으로 수행됩니다. 권한 제거는 되돌릴 수 없으므로 AdjustTokenPrivileges를 호출한 후 제거된 권한의 이름이 PreviousState 매개 변수에 포함되지 않습니다. WINDOWS XP SP1: 함수는 권한을 제거할 수 없습니다. 이 값은 지원되지 않습니다.
없음	함수는 권한을 사용하지 않도록 설정합니다.

값

의미

SE_PRIVILEGE_ENABLED

함수는 권한을 사용하도록 설정합니다.

SE_PRIVILEGE_REMOVED

토큰의 권한 목록에서 권한이 제거됩니다. 목록의 다른 권한은 연속된 상태로 유지되도록 순서를 다시 지정합니다.

SE_PRIVILEGE_REMOVED SE_PRIVILEGE_ENABLED 대체합니다.

토큰에서 권한이 제거되었으므로 권한의 결과를 다시 활성화하려고 하면 권한이 없는 것처럼 경고가 ERROR_NOT_ALL_ASSIGNED.

토큰에 없는 권한을 제거하려고 시도하면 ERROR_NOT_ALL_ASSIGNED 반환됩니다.

제거된 권한에 대한 권한 검사로 인해 STATUS_PRIVILEGE_NOT_HELD. 실패한 권한 검사 감사는 정상적으로 수행됩니다.

권한 제거는 되돌릴 수 없으므로 AdjustTokenPrivileges를 호출한 후 제거된 권한의 이름이 PreviousState 매개 변수에 포함되지 않습니다.

WINDOWS XP SP1: 함수는 권한을 제거할 수 없습니다. 이 값은 지원되지 않습니다.

없음

함수는 권한을 사용하지 않도록 설정합니다.

DisableAllPrivileges가 TRUE이면 함수는 이 매개 변수를 무시합니다.

[in] BufferLength

PreviousState 매개 변수가 가리키는 버퍼의 크기(바이트)를 지정합니다. PreviousState 매개 변수가 NULL인 경우 이 매개 변수는 0일 수 있습니다.

[out, optional] PreviousState

함수가 수정하는 모든 권한의 이전 상태를 포함하는 TOKEN_PRIVILEGES 구조로 채우는 버퍼에 대한 포인터입니다. 즉, 이 함수에서 권한을 수정한 경우 권한 및 이전 상태는 PreviousState에서 참조하는 TOKEN_PRIVILEGES 구조에 포함됩니다. TOKEN_PRIVILEGESPrivilegeCount 멤버가 0이면 이 함수에서 권한이 변경되지 않았습니다. 이 매개 변수는 NULL일 수 있습니다.

수정된 권한의 전체 목록을 받기에는 너무 작은 버퍼를 지정하면 함수가 실패하고 권한을 조정하지 않습니다. 이 경우 함수는 ReturnLength 매개 변수가 가리키는 변수를 수정된 권한의 전체 목록을 보유하는 데 필요한 바이트 수로 설정합니다.

[out, optional] ReturnLength

PreviousState 매개 변수가 가리키는 버퍼의 필요한 크기(바이트)를 수신하는 변수에 대한 포인터입니다. PreviousState가 NULL인 경우 이 매개 변수는 NULL일 수 있습니다.

반환 값

함수가 성공하면 반환 값이 0이 아닙니다. 함수가 지정된 모든 권한을 조정했는지 여부를 확인하려면 GetLastError를 호출합니다. 이 값은 함수가 성공할 때 다음 값 중 하나를 반환합니다.

반환 코드	설명
ERROR_SUCCESS	함수는 지정된 모든 권한을 조정했습니다.
ERROR_NOT_ALL_ASSIGNED	토큰에 NewState 매개 변수에 지정된 권한이 하나 이상 없습니다. 권한이 조정되지 않은 경우에도 이 오류 값으로 함수가 성공할 수 있습니다. PreviousState 매개 변수는 조정된 권한을 나타냅니다.

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

설명

AdjustTokenPrivileges 함수는 액세스 토큰에 새 권한을 추가할 수 없습니다. 토큰의 기존 권한만 사용하거나 사용하지 않도록 설정할 수 있습니다. 토큰의 권한을 확인하려면 GetTokenInformation 함수를 호출합니다.

NewState 매개 변수는 함수가 실패하지 않고 토큰에 없는 권한을 지정할 수 있습니다. 이 경우 함수는 토큰에 있는 권한을 조정하고 함수가 성공하도록 다른 권한을 무시합니다. GetLastError 함수를 호출하여 함수가 지정된 모든 권한을 조정했는지 여부를 확인합니다. PreviousState 매개 변수는 조정된 권한을 나타냅니다.

PreviousState 매개 변수는 조정된 권한의 원래 상태를 포함하는 TOKEN_PRIVILEGES 구조를 검색합니다. 원래 상태를 복원하려면 AdjustTokenPrivileges 함수에 대한 후속 호출에서 PreviousState 포인터를 NewState 매개 변수로 전달합니다.

예제

이 함수를 사용하는 예제는 권한 사용 및 비활성화를 참조하세요.

요구 사항

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