AccessCheckByTypeAndAuditAlarmW

セキュリティ記述子が、呼び出し元スレッドが偽装しているクライアントに対して指定された一連のアクセス権を許可するかどうかを判定する。(AccessCheckByTypeAndAuditAlarmW)

AccessCheckByTypeAndAuditAlarmW SubsystemName, HandleId, ObjectTypeName, ObjectName, SecurityDescriptor, PrincipalSelfSid, DesiredAccess, AuditType, Flags, ObjectTypeList, ObjectTypeListLength, GenericMapping, ObjectCreation, GrantedAccess, AccessStatus, pfGenerateOnClose

SubsystemName : [wstr] 関数を呼び出しているサブシステムの名前を指定する、null 終端文字列へのポインタ。この文字列は関数が生成する監査メッセージに表示される。
HandleId : [intptr] クライアントのオブジェクトに対するハンドルを表す一意な値へのポインタ。アクセスが拒否された場合、システムはこの値を無視する。
ObjectTypeName : [wstr] 作成中またはアクセス中のオブジェクトの種類を指定する、null 終端文字列へのポインタ。この文字列は関数が生成する監査メッセージに表示される。
ObjectName : [wstr] 作成中またはアクセス中のオブジェクトの名前を指定する、null 終端文字列へのポインタ。この文字列は関数が生成する監査メッセージに表示される。
SecurityDescriptor : [int] アクセスチェック対象の SECURITY_DESCRIPTOR 構造体へのポインタ。
PrincipalSelfSid : [int] SID へのポインタ。セキュリティ記述子がプリンシパルを表すオブジェクト（ユーザーオブジェクトなど）に関連付けられている場合、PrincipalSelfSid パラメータにはそのオブジェクトの SID を指定する。アクセス評価時には、この SID は周知 SID PRINCIPAL_SELF (S-1-5-10) を含む任意の ACE 内の SID を論理的に置き換える。周知 SID の詳細は「Well-known SIDs」を参照のこと。保護対象オブジェクトがプリンシパルを表さない場合、このパラメータは NULL に設定する。
DesiredAccess : [int] チェックするアクセス権を指定するアクセスマスク。このマスクは MapGenericMask 関数によって汎用アクセス権を含まないようにマッピング済みでなければならない。このパラメータが MAXIMUM_ALLOWED の場合、関数はセキュリティ記述子がクライアントに対して許可する最大のアクセス権を示すように GrantedAccess アクセスマスクを設定する。
AuditType : [int] 生成する監査の種類。AUDIT_EVENT_TYPE 列挙型の値のいずれかを指定する。
Flags : [int] 呼び出し元プロセスが SE_AUDIT_NAME 特権を有効にしていない場合の関数の挙動を制御するフラグ。AUDIT_ALLOW_NO_PRIVILEGE フラグがセットされている場合、特権が有効になっていないときに関数は監査メッセージを生成せずにアクセスチェックを実行する。このパラメータが 0 の場合、特権が有効になっていないと関数は失敗する。
ObjectTypeList : [var] アクセスをチェックするオブジェクト型の階層を識別する OBJECT_TYPE_LIST 構造体の配列へのポインタ。配列の各要素には、オブジェクト型を識別する GUID と、オブジェクト型階層におけるレベルを示す値を指定する。配列内に同じ GUID を持つ要素が 2 つ存在してはならない。配列には少なくとも 1 つの要素が必要である。配列の最初の要素はレベル 0 でなければならず、オブジェクト自体を識別する。配列にはレベル 0 の要素を 1 つだけ含めることができる。2 番目の要素はサブオブジェクト（プロパティセットなど）であり、レベル 1 となる。各レベル 1 のエントリの後には、レベル 2 から 4 のサブオブジェクトに対する下位エントリが続く。したがって、配列要素のレベルは例えば {0, 1, 2, 2, 1, 2, 3} のようになる。オブジェクト型リストの順序が不正な場合、AccessCheckByTypeAndAuditAlarm は失敗し、GetLastError は ERROR_INVALID_PARAMETER を返す。
ObjectTypeListLength : [int] ObjectTypeList 配列の要素数。
GenericMapping : [var] アクセスチェック対象のオブジェクトに関連付けられた GENERIC_MAPPING 構造体へのポインタ。
ObjectCreation : [int] アクセスが許可されたときに呼び出し側アプリケーションが新しいオブジェクトを作成するかどうかを決定するフラグ。TRUE はアプリケーションが新しいオブジェクトを作成することを示し、FALSE はアプリケーションが既存のオブジェクトを開くことを示す。
GrantedAccess : [var] 許可されたアクセス権を受け取るアクセスマスクへのポインタ。AccessStatus が FALSE に設定された場合、関数はアクセスマスクを 0 に設定する。関数が失敗した場合は、アクセスマスクを設定しない。
AccessStatus : [var] アクセスチェックの結果を受け取る変数へのポインタ。セキュリティ記述子がクライアントに対して要求されたアクセス権を許可する場合、AccessStatus には TRUE が設定される。そうでない場合は FALSE が設定され、GetLastError を呼び出すことで拡張エラー情報を取得できる。
pfGenerateOnClose : [var] 関数の復帰時に監査生成ルーチンがセットするフラグへのポインタ。オブジェクトハンドルを閉じるときに ObjectCloseAuditAlarm 関数にこのフラグを渡す。

(プラグイン / モジュール : advapi32.dll)

解説

セキュリティ記述子が、呼び出し元スレッドが偽装しているクライアントに対して指定された一連のアクセス権を許可するかどうかを判定する。(AccessCheckByTypeAndAuditAlarmW)

[戻り値]
関数が成功した場合、戻り値は 0 以外となる。関数が失敗した場合、戻り値は 0 となる。拡張エラー情報を取得するには
GetLastError を呼び出す。

[備考]
詳細は「How AccessCheck Works」概説を参照のこと。PrincipalSelfSid パラメータと
ObjectTypeList パラメータが NULL、AuditType パラメータが
AuditEventObjectAccess、Flags パラメータが 0
の場合、AccessCheckByTypeAndAuditAlarm は AccessCheckAndAuditAlarm
関数と同じ動作をする。ObjectTypeList
配列は必ずしも定義済みオブジェクト全体を表すものではなく、アクセスをチェックしたいオブジェクトのサブセットを表す。たとえば、プロパティセット内の
2 つのプロパティへのアクセスをチェックするには、レベル 0 にオブジェクト自体、レベル 1 にプロパティセット、レベル 2 に 2
つのプロパティという 4 要素のオブジェクト型リストを指定する。AccessCheckByTypeAndAuditAlarm
関数は、オブジェクト自体に適用される ACE と、ObjectTypeList 配列に列挙されたオブジェクト型に対するオブジェクト固有の
ACE を評価する。配列に列挙されていないオブジェクト型に対するオブジェクト固有の ACE
は無視される。したがって、AccessStatus パラメータで返される結果は、オブジェクト全体ではなく ObjectTypeList
パラメータで定義されたオブジェクトのサブセットに対して許可されたアクセスを示す。ACE
の階層がオブジェクトおよびそのサブオブジェクトへのアクセスをどのように制御するかの詳細は「ACEs to Control Access
to an Object's
Properties」を参照のこと。セキュリティイベントログに監査メッセージを生成するには、呼び出し元プロセスが
SE_AUDIT_NAME
特権を有効にしている必要がある。システムはこの特権を、スレッドの偽装トークンではなく呼び出し元プロセスのプライマリトークンに対して確認する。Flags
パラメータに AUDIT_ALLOW_NO_PRIVILEGE
フラグが含まれている場合、特権が有効になっていないときに関数は監査メッセージを生成せずにアクセスチェックを実行する。呼び出し元スレッドがクライアントを偽装していない場合、AccessCheckByTypeAndAuditAlarm
関数は失敗する。セキュリティ記述子が所有者 SID とグループ SID
を含まない場合、AccessCheckByTypeAndAuditAlarm は ERROR_INVALID_SECURITY_DESCR
で失敗する。

情報