AccessCheckByType 関数 (securitybaseapi.h)

[アーティクル]
08/25/2023

AccessCheckByType 関数は、セキュリティ記述子が、アクセストークンによって識別されるクライアントに対して、指定されたアクセス権のセットを許可するかどうかを決定します。関数は、オブジェクト、そのプロパティセット、プロパティなどのオブジェクトの階層に対するクライアントのアクセスをチェックできます。関数は、階層全体へのアクセスを許可または拒否します。通常、サーバーアプリケーションはこの関数を使用して、プライベートオブジェクトへのアクセスをチェックします。

構文

BOOL AccessCheckByType(
  [in]                PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                HANDLE               ClientToken,
  [in]                DWORD                DesiredAccess,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [in]                PGENERIC_MAPPING     GenericMapping,
  [out, optional]     PPRIVILEGE_SET       PrivilegeSet,
  [in, out]           LPDWORD              PrivilegeSetLength,
  [out]               LPDWORD              GrantedAccess,
  [out]               LPBOOL               AccessStatus
);

パラメーター

[in] pSecurityDescriptor

アクセスがチェックされる SECURITY_DESCRIPTOR 構造体へのポインター。

[in, optional] PrincipalSelfSid

セキュリティ識別子 (SID) へのポインター。セキュリティ記述子がプリンシパル (ユーザーオブジェクトなど) を表すオブジェクトに関連付けられている場合、 PrincipalSelfSid パラメーターはオブジェクトの SID である必要があります。アクセスを評価する場合、この SID は、既知のPRINCIPAL_SELF SID (S-1-5-10) を含むアクセス制御エントリ内の 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 を持つ 2 つの要素を含めてはなりません。

配列には、少なくとも 1 つの要素が必要です。配列の最初の要素はレベル 0 で、オブジェクト自体を識別する必要があります。配列には、レベル 0 要素を 1 つだけ指定できます。 2 番目の要素は、レベル 1 のプロパティセットなどのサブオブジェクトです。各レベル 1 エントリの後には、レベル 2 から 4 のサブオブジェクトの下位エントリがあります。したがって、配列内の要素のレベルは{0、1、2、2、1、2、3}である可能性があります。オブジェクトの種類の一覧が順不同の場合、 AccessCheckByType は失敗し、 GetLastError は ERROR_INVALID_PARAMETERを返します。

ObjectTypeList が NULL の場合、AccessCheckByType は AccessCheck 関数と同じです。

[in] ObjectTypeListLength

ObjectTypeList 配列内の要素の数を指定します。

[in] GenericMapping

アクセスがチェックされるオブジェクトに関連付けられている GENERIC_MAPPING 構造体へのポインター。 GENERIC_MAPPING構造体の GenericAll メンバーには、リソースマネージャーが付与できるすべてのアクセス権 (STANDARD_RIGHTS_ALL、GenericRead、GenericWrite、および GenericExecute メンバーに設定されているすべての権限を含む) が含まれている必要があります。

[out, optional] PrivilegeSet

アクセス検証の実行に使用される特権を受け取るPRIVILEGE_SET構造体へのポインター。特権が使用されなかった場合、この関数は PrivilegeCount メンバーを 0 に設定します。

[in, out] PrivilegeSetLength

PrivilegeSet パラメーターが指すバッファーのサイズをバイト単位で指定します。

[out] GrantedAccess

付与されたアクセス権を受け取るアクセスマスクへのポインター。 AccessStatus が FALSE に設定されている場合、関数はアクセスマスクを 0 に設定します。関数が失敗した場合、アクセスマスクは設定されません。

[out] AccessStatus

アクセスチェックの結果を受け取る変数へのポインター。セキュリティ記述子で、アクセストークンによって識別されたクライアントに対する要求されたアクセス権が許可されている場合、 AccessStatus は TRUE に設定されます。それ以外の場合、 AccessStatus は FALSE に設定され、 GetLastError を呼び出して拡張エラー情報を取得できます。

戻り値

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合は、0 を返します。詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

詳細については、「 AccessCheck のしくみの概要」を参照してください。

AccessCheckByType 関数は、指定されたセキュリティ記述子と指定したアクセストークンを比較し、AccessStatus パラメーターでアクセスが許可されているか拒否されているかを示します。

ObjectTypeList 配列は、定義されたオブジェクト全体を必ずしも表すわけではありません。代わりに、アクセスをチェックするオブジェクトのサブセットを表します。たとえば、プロパティセット内の 2 つのプロパティにアクセスチェックするには、4 つの要素 (レベル 0 のオブジェクト自体、レベル 1 で設定されたプロパティ、レベル 2 の 2 つのプロパティ) を含むオブジェクト型リストを指定します。

AccessCheckByType 関数は、オブジェクト自体に適用される ACE と ObjectTypeList 配列にリストされているオブジェクト型のオブジェクト固有の ACE を評価します。この関数は、 ObjectTypeList 配列にリストされていないオブジェクト型のオブジェクト固有の ACE を無視します。したがって、 AccessStatus パラメーターで返される結果は、オブジェクト全体ではなく、 ObjectTypeList パラメーターによって定義されたオブジェクトのサブセットへのアクセスが許可されていることを示します。

ACE の階層がオブジェクトとそのサブオブジェクトへのアクセスを制御する方法の詳細については、「オブジェクトのプロパティへのアクセスを制御する ACE」を参照してください。

セキュリティ記述子の DACL が NULL の場合、 AccessStatus パラメーターは TRUE を返し、クライアントが要求されたアクセス権を持っていることを示します。

セキュリティ記述子に所有者 SID とグループ SID が含まれていない場合、 AccessCheckByType はERROR_INVALID_SECURITY_DESCRで失敗します。

要件

要件	値
サポートされている最小のクライアント	Windows XP (デスクトップアプリのみ)
サポートされている最小のサーバー	Windows Server 2003 (デスクトップアプリのみ)
対象プラットフォーム	Windows
ヘッダー	securitybaseapi.h (Windows.h を含む)
Library	Advapi32.lib
[DLL]	Advapi32.dll