AccessCheckByTypeResultListAndAuditAlarmByHandleW 関数 (securitybaseapi.h)
AccessCheckByTypeResultListAndAuditAlarmByHandle 関数は、セキュリティ記述子が、呼び出し元のスレッドが偽装しているクライアントに対して、指定したアクセス権のセットを許可するかどうかを決定します。 この関数と AccessCheckByTypeResultListAndAuditAlarm の違いは、呼び出し元のスレッドがクライアントを偽装する前にアクセスチェックを実行できる点です。
関数は、オブジェクト、そのプロパティ セット、プロパティなどのオブジェクトの階層にアクセスチェック。 この関数は、階層内の各オブジェクトの種類に対して付与または拒否されたアクセス権を報告します。 セキュリティ記述子に、クライアントに適用されるアクセス制御エントリ (ACE) を含むシステム アクセス制御リスト (SACL) がある場合、この関数はセキュリティ イベント ログに必要な監査メッセージを生成します。 アラームは現在サポートされていません。
構文
BOOL AccessCheckByTypeResultListAndAuditAlarmByHandleW(
[in] LPCWSTR SubsystemName,
[in] LPVOID HandleId,
[in] HANDLE ClientToken,
[in] LPCWSTR ObjectTypeName,
[in, optional] LPCWSTR ObjectName,
[in] PSECURITY_DESCRIPTOR SecurityDescriptor,
[in, optional] PSID PrincipalSelfSid,
[in] DWORD DesiredAccess,
[in] AUDIT_EVENT_TYPE AuditType,
[in] DWORD Flags,
[in, out, optional] POBJECT_TYPE_LIST ObjectTypeList,
[in] DWORD ObjectTypeListLength,
[in] PGENERIC_MAPPING GenericMapping,
[in] BOOL ObjectCreation,
LPDWORD GrantedAccessList,
[out] LPDWORD AccessStatusList,
[out] LPBOOL pfGenerateOnClose
);
パラメーター
[in] SubsystemName
関数を呼び出すサブシステムの名前を指定する null で終わる文字列へのポインター。 この文字列は、関数によって生成されるすべての監査メッセージに表示されます。
[in] HandleId
オブジェクトへのクライアントのハンドルを表す一意の値へのポインター。 アクセスが拒否された場合、システムはこの値を無視します。
[in] ClientToken
操作を要求したクライアントを表すトークン オブジェクトへのハンドル。 このハンドルは、セキュリティ ポリシー違反の可能性を防ぐために、ローカルの名前付きパイプなどの通信セッション 層を介して取得する必要があります。 呼び出し元は、指定したトークンTOKEN_QUERYアクセス権を持っている必要があります。
[in] ObjectTypeName
作成またはアクセスされるオブジェクトの種類を指定する null で終わる文字列へのポインター。 この文字列は、関数によって生成されるすべての監査メッセージに表示されます。
[in, optional] ObjectName
作成またはアクセスされるオブジェクトの名前を指定する null で終わる文字列へのポインター。 この文字列は、関数によって生成されるすべての監査メッセージに表示されます。
[in] SecurityDescriptor
アクセスがチェックされる SECURITY_DESCRIPTOR 構造体へのポインター。
[in, optional] PrincipalSelfSid
SID へのポインター。 セキュリティ記述子がプリンシパル (ユーザー オブジェクトなど) を表すオブジェクトに関連付けられている場合、 PrincipalSelfSid パラメーターはオブジェクトの SID である必要があります。 アクセスを評価する場合、この SID は、既知のPRINCIPAL_SELF SID (S-1-5-10) を含む ACE 内の SID を論理的に置き換えます。 既知の SID の詳細については、「 既知の SID」を参照してください。
保護されたオブジェクトがプリンシパルを表していない場合は、このパラメーターを NULL に設定します。
[in] DesiredAccess
チェックへのアクセス権を指定するアクセス マスク。 このマスクは、汎用アクセス権を含めないように 、MapGenericMask 関数によってマップされている必要があります。
このパラメーターがMAXIMUM_ALLOWEDの場合、この関数は GrantedAccess のアクセス マスクを設定して、セキュリティ記述子がクライアントに許可する最大アクセス権を示します。
[in] AuditType
生成する監査の種類。 これは、 AUDIT_EVENT_TYPE 列挙型の値のいずれかになります。
[in] Flags
呼び出し元 プロセス でSE_AUDIT_NAME特権が有効になっていない場合に、関数の動作を制御するフラグ。 AUDIT_ALLOW_NO_PRIVILEGE フラグが設定されている場合、特権が有効になっていない場合、関数は監査メッセージを生成せずにアクセスチェックを実行します。 このパラメーターが 0 の場合、特権が有効になっていない場合、関数は失敗します。
[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}である可能性があります。 オブジェクトの種類の一覧が順不同の場合、 AccessCheckByTypeResultListAndAuditAlarmByHandle は失敗し、 GetLastError は ERROR_INVALID_PARAMETERを返します。
[in] ObjectTypeListLength
ObjectTypeList 配列内の要素の数。
[in] GenericMapping
アクセスがチェックされるオブジェクトに関連付けられている GENERIC_MAPPING 構造体へのポインター。
[in] ObjectCreation
アクセスが許可されたときに呼び出し元のアプリケーションが新しいオブジェクトを作成するかどうかを決定するフラグ。 TRUE の値は、アプリケーションが新しいオブジェクトを作成することを示します。 FALSE の値は、アプリケーションが既存のオブジェクトを開きます。
GrantedAccessList
[out] AccessStatusList
オブジェクト型リスト内の対応する要素の状態コードの配列へのポインター。 関数は、アクセスチェック中に特定のエラーを示すために、成功を示す要素を 0 に設定するか、0 以外の値に設定します。 関数が失敗した場合、配列内の要素は設定されません。
[out] pfGenerateOnClose
関数が戻るときに監査生成ルーチンによって設定されたフラグへのポインター。 オブジェクト ハンドルが閉じられたときに、このフラグを ObjectCloseAuditAlarm 関数に渡します。
戻り値
関数が成功した場合、関数は 0 以外の値を返します。
関数が失敗すると、0 が返されます。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
詳細については、「 AccessCheck のしくみ の概要」を参照してください。
AccessCheckByTypeResultListAndAuditAlarm と同様に、AccessCheckByTypeResultListAndAuditAlarmByHandle 関数は AccessCheckByTypeResultList 関数と AccessCheckAndAuditAlarm 関数の組み合わせです。 ただし、 AccessCheckByTypeResultListAndAuditAlarmByHandle には、クライアントにセキュリティ情報を提供するためのクライアント トークン ハンドルも必要です。
ObjectTypeList 配列は、定義されたオブジェクト全体を必ずしも表すわけではありません。 代わりに、アクセスをチェックするオブジェクトのサブセットを表します。 たとえば、プロパティ セット内の 2 つのプロパティにアクセスチェックするには、4 つの要素 (レベル 0 のオブジェクト自体、レベル 1 で設定されたプロパティ、レベル 2 の 2 つのプロパティ) を含むオブジェクト型リストを指定します。
AccessCheckByTypeResultListAndAuditAlarmByHandle 関数は、オブジェクト自体に適用される ACE と ObjectTypeList 配列にリストされているオブジェクト型のオブジェクト固有の ACE を評価します。 この関数は、 ObjectTypeList 配列にリストされていないオブジェクト型のオブジェクト固有の ACE を無視します。
ACE の階層がオブジェクトとそのサブオブジェクトへのアクセスを制御する方法の詳細については、「 オブジェクトのプロパティへのアクセスを制御する ACE」を参照してください。
セキュリティ イベント ログで監査メッセージを生成するには、呼び出し元プロセスでSE_AUDIT_NAME特権が有効になっている必要があります。 システムは、スレッドの偽装 トークン ではなく、呼び出し元プロセスのプライマリ トークン でこの特権をチェックします。 Flags パラメーターに AUDIT_ALLOW_NO_PRIVILEGE フラグが含まれている場合、特権が有効になっていない場合、関数は監査メッセージを生成せずにアクセス チェックを実行します。
呼び出し元のスレッドがクライアントを偽装していない場合、 AccessCheckByTypeResultListAndAuditAlarmByHandle 関数は失敗します。
セキュリティ記述子に所有者 SID とグループ SID が含まれていない場合、 AccessCheckByTypeResultListAndAuditAlarmByHandle はERROR_INVALID_SECURITY_DESCRで失敗します。
要件
要件 | 値 |
---|---|
サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
対象プラットフォーム | Windows |
ヘッダー | securitybaseapi.h (Windows.h を含む) |
Library | Advapi32.lib |
[DLL] | Advapi32.dll |
こちらもご覧ください
AUDIT_EVENT_TYPE
AccessCheck
AccessCheckAndAuditAlarm
AccessCheckByType
AccessCheckByTypeResultList
AccessCheckByTypeResultListAndAuditAlarmクライアント/サーバー Access Control
クライアント/サーバー Access Control関数
GENERIC_MAPPING
AccessCheck のしくみ
MakeAbsoluteSD
MapGenericMask
OBJECT_TYPE_LIST
ObjectCloseAuditAlarm
PRIVILEGE_SET
SECURITY_DESCRIPTOR