AddAuditAccessObjectAce 関数 (securitybaseapi.h)

[アーティクル]
03/01/2024

AddAuditAccessObjectAce 関数は、システム監査アクセス制御エントリ (ACE) をシステムアクセス制御リスト (SACL) の末尾に追加します。新しい ACE は、オブジェクト、またはオブジェクトのプロパティセットまたはプロパティへのアクセスを監査できます。 AddAuditAccessObjectAce を使用して、指定した種類の子オブジェクトのみが継承できる ACE を追加することもできます。

構文

BOOL AddAuditAccessObjectAce(
  [in, out]      PACL  pAcl,
  [in]           DWORD dwAceRevision,
  [in]           DWORD AceFlags,
  [in]           DWORD AccessMask,
  [in, optional] GUID  *ObjectTypeGuid,
  [in, optional] GUID  *InheritedObjectTypeGuid,
  [in]           PSID  pSid,
  [in]           BOOL  bAuditSuccess,
  [in]           BOOL  bAuditFailure
);

パラメーター

[in, out] pAcl

SACL へのポインター。 AddAuditAccessObjectAce 関数は、この SACL の末尾にシステム監査 ACE を追加します。 ACE は、 SYSTEM_AUDIT_OBJECT_ACE 構造体の形式です。

[in] dwAceRevision

変更する SACL のリビジョンレベルを指定します。この値はACL_REVISION_DSする必要があります。 SACL のリビジョンレベルがACL_REVISION_DSよりも低い場合、関数はそれを ACL_REVISION_DS に変更します。

[in] AceFlags

ACE の継承とアクセスの種類を制御するビットフラグのセットが監査を試みます。関数は、新しい ACE のACE_HEADER構造体の AceFlags メンバーにこれらのフラグを設定します。このパラメーターは、次の値と組み合わせて使用できます。

値	意味
CONTAINER_INHERIT_ACE	ACE はコンテナーオブジェクトによって継承されます。
FAILED_ACCESS_ACE_FLAG	このフラグを設定するか、bAuditFailure パラメーターに TRUE を指定した場合、指定したアクセス権を使用しようとして失敗すると、システムはセキュリティイベントログに監査レコードを生成します。
INHERIT_ONLY_ACE	ACE は、アクセス制御リスト (ACL) が割り当てられているオブジェクトには適用されませんが、子オブジェクトによって継承できます。
INHERITED_ACE	継承された ACE を示します。このフラグを使用すると、オブジェクトのツリーのセキュリティを変更する操作で、オブジェクトに直接適用された ACE は変更されず、継承された ACE を変更できます。
NO_PROPAGATE_INHERIT_ACE	OBJECT_INHERIT_ACEビットとCONTAINER_INHERIT_ACE ビットは、継承された ACE には反映されません。
OBJECT_INHERIT_ACE	ACE は、非コンテナーオブジェクトによって継承されます。
SUCCESSFUL_ACCESS_ACE_FLAG	このフラグを設定するか、bAuditSuccess パラメーターに TRUE を指定すると、指定したアクセス権が正常に使用されると、システムはセキュリティイベントログに監査レコードを生成します。

[in] AccessMask

新しい ACE が指定したセキュリティ識別子 (SID) に対して監査するアクセス権を指定するACCESS_MASK。

[in, optional] ObjectTypeGuid

新しい ACE によって保護されるオブジェクト、プロパティセット、またはプロパティの種類を識別する GUID 構造体へのポインター。このパラメーターが NULL の場合、新しい ACE は ACL が割り当てられているオブジェクトを保護します。

[in, optional] InheritedObjectTypeGuid

新しい ACE を継承できるオブジェクトの種類を識別する GUID 構造体へのポインター。このパラメーターが NULL 以外の場合は、指定したオブジェクト型のみが ACE を継承できます。 NULL の場合、任意の種類の子オブジェクトが ACE を継承できます。どちらの場合も、継承は AceFlags パラメーターの値と、子オブジェクトに配置された継承に対する保護によっても制御されます。

[in] pSid

新しい ACE がアクセスを監査するユーザー、グループ、またはログオンセッションを識別する SID へのポインター。

[in] bAuditSuccess

指定したアクセス権が正常に使用され、システムがセキュリティイベントログに監査レコードを生成するかどうかを指定します。このフラグが TRUE の 場合、または AceFlags パラメーターに SUCCESSFUL_ACCESS_ACE_FLAG フラグが指定されている場合、システムは正常なアクセス試行を記録します。それ以外の場合は、行われません。

[in] bAuditFailure

指定したアクセス権を使用しようとして失敗した場合に、システムがセキュリティイベントログに監査レコードを生成するかどうかを指定します。このフラグが TRUE の 場合、または AceFlags パラメーターで FAILED_ACCESS_ACE_FLAG フラグが指定されている場合、システムはアクセス試行に失敗したことを記録します。それ以外の場合は、行われません。

戻り値

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

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

リターンコード	説明
ERROR_ALLOTTED_SPACE_EXCEEDED	新しい ACE は ACL に適合しません。より大きな ACL バッファーが必要です。
ERROR_INVALID_ACL	指定された ACL が正しく形成されていません。
ERROR_INVALID_FLAGS	AceFlags パラメーターが無効です。
ERROR_INVALID_SID	指定された SID が構造的に有効ではありません。
ERROR_REVISION_MISMATCH	指定されたリビジョンが不明であるか、ACL のリビジョンと互換性がありません。
ERROR_SUCCESS	ACE が正常に追加されました。

注釈

ObjectTypeGuid と InheritedObjectTypeGuid の両方が NULL の場合は、AddAuditAccessObjectAce ではなく AddAuditAccessAceEx 関数を使用します。これは、SYSTEM_AUDIT_ACEがSYSTEM_AUDIT_OBJECT_ACEよりも小さく効率的であるためです。

要件

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