ホーム › Security › AddAuditAccessAce

AddAuditAccessAce

関数

ACL（SACL）に監査用ACEを追加する。

DLLADVAPI32.dll呼出規約winapiSetLastErrorあり対応OSWindows XP 以降

シグネチャ

// ADVAPI32.dll
#include <windows.h>

BOOL AddAuditAccessAce(
    ACL* pAcl,
    ACE_REVISION dwAceRevision,
    DWORD dwAccessMask,
    PSID pSid,
    BOOL bAuditSuccess,
    BOOL bAuditFailure
);

パラメーター

名前	型	方向	説明
pAcl	ACL*	inout	ACL へのポインターです。この関数はこの ACL にシステム監査 ACE を追加します。ACE は SYSTEM_AUDIT_ACE 構造体の形式です。
dwAceRevision	ACE_REVISION	in	変更対象の ACL のリビジョンレベルを指定します。この値は ACL_REVISION または ACL_REVISION_DS のいずれかです。ACL がオブジェクト固有の ACE を含む場合は ACL_REVISION_DS を使用します。
dwAccessMask	DWORD	in	指定した SID に対して監査するアクセス権のマスクを指定します。
pSid	PSID	in	アクセスを監査する対象のプロセスを表す SID へのポインターです。
bAuditSuccess	BOOL	in	成功したアクセス試行を監査するかどうかを指定します。監査を有効にするにはこのフラグを TRUE に設定し、そうでない場合は FALSE に設定します。
bAuditFailure	BOOL	in	失敗したアクセス試行を監査するかどうかを指定します。監査を有効にするにはこのフラグを TRUE に設定し、そうでない場合は FALSE に設定します。

戻り値の型: BOOL

公式ドキュメント

システム監査アクセス制御エントリ (ACE) をシステムアクセス制御リスト (ACL) に追加します。指定したセキュリティ識別子 (SID) のアクセスが監査されます。

戻り値

関数が成功した場合、戻り値は 0 以外の値です。

関数が失敗した場合、戻り値は 0 です。拡張エラー情報を取得するには GetLastError を呼び出します。発生し得るエラー値は次のとおりです。

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

解説(Remarks)

AddAuditAccessAce 関数によって ACE に配置される ACE_HEADER 構造体は、種類とサイズを指定しますが、ACE フラグは提供しません。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// ADVAPI32.dll
#include <windows.h>

BOOL AddAuditAccessAce(
    ACL* pAcl,
    ACE_REVISION dwAceRevision,
    DWORD dwAccessMask,
    PSID pSid,
    BOOL bAuditSuccess,
    BOOL bAuditFailure
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("ADVAPI32.dll", SetLastError = true, ExactSpelling = true)]
static extern bool AddAuditAccessAce(
    IntPtr pAcl,   // ACL* in/out
    uint dwAceRevision,   // ACE_REVISION
    uint dwAccessMask,   // DWORD
    IntPtr pSid,   // PSID
    bool bAuditSuccess,   // BOOL
    bool bAuditFailure   // BOOL
);

<DllImport("ADVAPI32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function AddAuditAccessAce(
    pAcl As IntPtr,   ' ACL* in/out
    dwAceRevision As UInteger,   ' ACE_REVISION
    dwAccessMask As UInteger,   ' DWORD
    pSid As IntPtr,   ' PSID
    bAuditSuccess As Boolean,   ' BOOL
    bAuditFailure As Boolean   ' BOOL
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' pAcl : ACL* in/out
' dwAceRevision : ACE_REVISION
' dwAccessMask : DWORD
' pSid : PSID
' bAuditSuccess : BOOL
' bAuditFailure : BOOL
Declare PtrSafe Function AddAuditAccessAce Lib "advapi32" ( _
    ByVal pAcl As LongPtr, _
    ByVal dwAceRevision As Long, _
    ByVal dwAccessMask As Long, _
    ByVal pSid As LongPtr, _
    ByVal bAuditSuccess As Long, _
    ByVal bAuditFailure As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

AddAuditAccessAce = ctypes.windll.advapi32.AddAuditAccessAce
AddAuditAccessAce.restype = wintypes.BOOL
AddAuditAccessAce.argtypes = [
    ctypes.c_void_p,  # pAcl : ACL* in/out
    wintypes.DWORD,  # dwAceRevision : ACE_REVISION
    wintypes.DWORD,  # dwAccessMask : DWORD
    wintypes.HANDLE,  # pSid : PSID
    wintypes.BOOL,  # bAuditSuccess : BOOL
    wintypes.BOOL,  # bAuditFailure : BOOL
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ADVAPI32.dll')
AddAuditAccessAce = Fiddle::Function.new(
  lib['AddAuditAccessAce'],
  [
    Fiddle::TYPE_VOIDP,  # pAcl : ACL* in/out
    -Fiddle::TYPE_INT,  # dwAceRevision : ACE_REVISION
    -Fiddle::TYPE_INT,  # dwAccessMask : DWORD
    Fiddle::TYPE_VOIDP,  # pSid : PSID
    Fiddle::TYPE_INT,  # bAuditSuccess : BOOL
    Fiddle::TYPE_INT,  # bAuditFailure : BOOL
  ],
  Fiddle::TYPE_INT)

#[link(name = "advapi32")]
extern "system" {
    fn AddAuditAccessAce(
        pAcl: *mut ACL,  // ACL* in/out
        dwAceRevision: u32,  // ACE_REVISION
        dwAccessMask: u32,  // DWORD
        pSid: *mut core::ffi::c_void,  // PSID
        bAuditSuccess: i32,  // BOOL
        bAuditFailure: i32  // BOOL
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("ADVAPI32.dll", SetLastError = true)]
public static extern bool AddAuditAccessAce(IntPtr pAcl, uint dwAceRevision, uint dwAccessMask, IntPtr pSid, bool bAuditSuccess, bool bAuditFailure);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ADVAPI32_AddAuditAccessAce' -Namespace Win32 -PassThru
# $api::AddAuditAccessAce(pAcl, dwAceRevision, dwAccessMask, pSid, bAuditSuccess, bAuditFailure)

#uselib "ADVAPI32.dll"
#func global AddAuditAccessAce "AddAuditAccessAce" sptr, sptr, sptr, sptr, sptr, sptr
; AddAuditAccessAce varptr(pAcl), dwAceRevision, dwAccessMask, pSid, bAuditSuccess, bAuditFailure   ; 戻り値は stat
; pAcl : ACL* in/out -> "sptr"
; dwAceRevision : ACE_REVISION -> "sptr"
; dwAccessMask : DWORD -> "sptr"
; pSid : PSID -> "sptr"
; bAuditSuccess : BOOL -> "sptr"
; bAuditFailure : BOOL -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ADVAPI32.dll"
#cfunc global AddAuditAccessAce "AddAuditAccessAce" var, int, int, sptr, int, int
; res = AddAuditAccessAce(pAcl, dwAceRevision, dwAccessMask, pSid, bAuditSuccess, bAuditFailure)
; pAcl : ACL* in/out -> "var"
; dwAceRevision : ACE_REVISION -> "int"
; dwAccessMask : DWORD -> "int"
; pSid : PSID -> "sptr"
; bAuditSuccess : BOOL -> "int"
; bAuditFailure : BOOL -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ADVAPI32.dll"
#cfunc global AddAuditAccessAce "AddAuditAccessAce" sptr, int, int, sptr, int, int
; res = AddAuditAccessAce(varptr(pAcl), dwAceRevision, dwAccessMask, pSid, bAuditSuccess, bAuditFailure)
; pAcl : ACL* in/out -> "sptr"
; dwAceRevision : ACE_REVISION -> "int"
; dwAccessMask : DWORD -> "int"
; pSid : PSID -> "sptr"
; bAuditSuccess : BOOL -> "int"
; bAuditFailure : BOOL -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。