ホーム › Security › ConvertToAutoInheritPrivateObjectSecurity

ConvertToAutoInheritPrivateObjectSecurity

関数

セキュリティ記述子を自動継承形式に変換する。

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

シグネチャ

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

BOOL ConvertToAutoInheritPrivateObjectSecurity(
    PSECURITY_DESCRIPTOR ParentDescriptor,   // optional
    PSECURITY_DESCRIPTOR CurrentSecurityDescriptor,
    PSECURITY_DESCRIPTOR* NewSecurityDescriptor,
    GUID* ObjectType,   // optional
    BOOLEAN IsDirectoryObject,
    GENERIC_MAPPING* GenericMapping
);

パラメーター

名前	型	方向	説明
ParentDescriptor	PSECURITY_DESCRIPTOR	inoptional	オブジェクトの親コンテナーの security descriptor へのポインター。親コンテナーが存在しない場合、このパラメーターは NULL です。
CurrentSecurityDescriptor	PSECURITY_DESCRIPTOR	in	オブジェクトの現在のセキュリティ記述子へのポインター。
NewSecurityDescriptor	PSECURITY_DESCRIPTOR*	out	新しく割り当てられた self-relative security descriptor へのポインターを受け取る変数へのポインター。このセキュリティ記述子を解放するために DestroyPrivateObjectSecurity 関数を呼び出すのは、呼び出し元の責任です。
ObjectType	GUID*	inoptional	CurrentSecurityDescriptor パラメーターに関連付けられたオブジェクトの種類を識別する GUID 構造体へのポインター。オブジェクトが GUID を持たない場合、このパラメーターは NULL でなければなりません。
IsDirectoryObject	BOOLEAN	in	TRUE の場合、新しいオブジェクトはコンテナーであり、他のオブジェクトを格納できます。FALSE の場合、新しいオブジェクトはコンテナーではありません。
GenericMapping	GENERIC_MAPPING*	in	オブジェクトの各ジェネリック権利から特定の権利へのマッピングを指定する GENERIC_MAPPING 構造体へのポインター。

戻り値の型: BOOL

公式ドキュメント

セキュリティ記述子とそのアクセス制御リスト (ACL) を、継承可能なアクセス制御エントリ (ACE) の自動的な伝播をサポートする形式に変換します。

戻り値

関数が成功した場合、関数は 0 以外の値を返します。

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

解説(Remarks)

ConvertToAutoInheritPrivateObjectSecurity 関数は、現在のセキュリティ記述子の discretionary access control list (DACL) および system access control list (SACL) 内の ACE が、親セキュリティ記述子から継承されたものかどうかを判定しようとします。この関数は ParentDescriptor パラメーターを CreatePrivateObjectSecurityEx 関数に渡して、継承された ACE のみを含む ACL を取得します。次に、これらの ACE を元のセキュリティ記述子内の ACE と比較し、元の ACE のうちどれが継承されたものかを判定します。ACE は 1 対 1 で一致する必要はありません。たとえば、あるトラスティに読み取りと書き込みのアクセスを許可する 1 つの ACE は、読み取りアクセスを許可する ACE と書き込みアクセスを許可する ACE の 2 つの ACE と等価になり得ます。

親セキュリティ記述子から継承された ACE と等価な、元のセキュリティ記述子内の ACE には INHERITED_ACE フラグが付与され、新しいセキュリティ記述子に追加されます。元のセキュリティ記述子内のその他のすべての ACE は、継承されていない ACE として新しいセキュリティ記述子に追加されます。

元の DACL に継承された ACE が 1 つもない場合、関数は新しいセキュリティ記述子の制御ビットに SE_DACL_PROTECTED フラグを設定します。同様に、SACL 内のどの ACE も継承されていない場合は SE_SACL_PROTECTED フラグが設定されます。

継承された ACE を持つ DACL について、関数は ACE を 2 つのグループに並べ替えます。最初のグループには、オブジェクトに直接適用された ACE が含まれます。2 番目のグループには継承された ACE が含まれます。この順序付けにより、継承されていない ACE が継承された ACE よりも優先されることが保証されます。詳細については、 Order of ACEs in a DACL を参照してください。

関数は、新しいセキュリティ記述子の制御ビットに SE_DACL_AUTO_INHERITED フラグおよび SE_SACL_AUTO_INHERITED フラグを設定します。

関数は、DACL 内のアクセス許可 ACE とアクセス拒否 ACE の相対的な順序を変更しません。順序を変更すると、結果として得られるセキュリティ記述子のセマンティクスが変わってしまうためです。セマンティクスを変えずに DACL を変換できない場合、関数は DACL を変更せずそのままにし、SE_DACL_PROTECTED フラグを設定します。

新しいセキュリティ記述子は、元のセキュリティ記述子と同じ所有者およびプライマリグループを持ちます。

新しいセキュリティ記述子は元のセキュリティ記述子と等価であるため、呼び出し元はセキュリティ記述子を新しい形式に更新するためのアクセス権や privileges を必要としません。

この関数は ACL_REVISION および ACL_REVISION_DS の ACL で動作します。

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

各言語での呼び出し定義

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

BOOL ConvertToAutoInheritPrivateObjectSecurity(
    PSECURITY_DESCRIPTOR ParentDescriptor,   // optional
    PSECURITY_DESCRIPTOR CurrentSecurityDescriptor,
    PSECURITY_DESCRIPTOR* NewSecurityDescriptor,
    GUID* ObjectType,   // optional
    BOOLEAN IsDirectoryObject,
    GENERIC_MAPPING* GenericMapping
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("ADVAPI32.dll", SetLastError = true, ExactSpelling = true)]
static extern bool ConvertToAutoInheritPrivateObjectSecurity(
    IntPtr ParentDescriptor,   // PSECURITY_DESCRIPTOR optional
    IntPtr CurrentSecurityDescriptor,   // PSECURITY_DESCRIPTOR
    IntPtr NewSecurityDescriptor,   // PSECURITY_DESCRIPTOR* out
    IntPtr ObjectType,   // GUID* optional
    [MarshalAs(UnmanagedType.U1)] bool IsDirectoryObject,   // BOOLEAN
    IntPtr GenericMapping   // GENERIC_MAPPING*
);

<DllImport("ADVAPI32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function ConvertToAutoInheritPrivateObjectSecurity(
    ParentDescriptor As IntPtr,   ' PSECURITY_DESCRIPTOR optional
    CurrentSecurityDescriptor As IntPtr,   ' PSECURITY_DESCRIPTOR
    NewSecurityDescriptor As IntPtr,   ' PSECURITY_DESCRIPTOR* out
    ObjectType As IntPtr,   ' GUID* optional
    <MarshalAs(UnmanagedType.U1)> IsDirectoryObject As Boolean,   ' BOOLEAN
    GenericMapping As IntPtr   ' GENERIC_MAPPING*
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' ParentDescriptor : PSECURITY_DESCRIPTOR optional
' CurrentSecurityDescriptor : PSECURITY_DESCRIPTOR
' NewSecurityDescriptor : PSECURITY_DESCRIPTOR* out
' ObjectType : GUID* optional
' IsDirectoryObject : BOOLEAN
' GenericMapping : GENERIC_MAPPING*
Declare PtrSafe Function ConvertToAutoInheritPrivateObjectSecurity Lib "advapi32" ( _
    ByVal ParentDescriptor As LongPtr, _
    ByVal CurrentSecurityDescriptor As LongPtr, _
    ByVal NewSecurityDescriptor As LongPtr, _
    ByVal ObjectType As LongPtr, _
    ByVal IsDirectoryObject As Byte, _
    ByVal GenericMapping As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

ConvertToAutoInheritPrivateObjectSecurity = ctypes.windll.advapi32.ConvertToAutoInheritPrivateObjectSecurity
ConvertToAutoInheritPrivateObjectSecurity.restype = wintypes.BOOL
ConvertToAutoInheritPrivateObjectSecurity.argtypes = [
    wintypes.HANDLE,  # ParentDescriptor : PSECURITY_DESCRIPTOR optional
    wintypes.HANDLE,  # CurrentSecurityDescriptor : PSECURITY_DESCRIPTOR
    ctypes.c_void_p,  # NewSecurityDescriptor : PSECURITY_DESCRIPTOR* out
    ctypes.c_void_p,  # ObjectType : GUID* optional
    wintypes.BOOLEAN,  # IsDirectoryObject : BOOLEAN
    ctypes.c_void_p,  # GenericMapping : GENERIC_MAPPING*
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ADVAPI32.dll')
ConvertToAutoInheritPrivateObjectSecurity = Fiddle::Function.new(
  lib['ConvertToAutoInheritPrivateObjectSecurity'],
  [
    Fiddle::TYPE_VOIDP,  # ParentDescriptor : PSECURITY_DESCRIPTOR optional
    Fiddle::TYPE_VOIDP,  # CurrentSecurityDescriptor : PSECURITY_DESCRIPTOR
    Fiddle::TYPE_VOIDP,  # NewSecurityDescriptor : PSECURITY_DESCRIPTOR* out
    Fiddle::TYPE_VOIDP,  # ObjectType : GUID* optional
    Fiddle::TYPE_CHAR,  # IsDirectoryObject : BOOLEAN
    Fiddle::TYPE_VOIDP,  # GenericMapping : GENERIC_MAPPING*
  ],
  Fiddle::TYPE_INT)

#[link(name = "advapi32")]
extern "system" {
    fn ConvertToAutoInheritPrivateObjectSecurity(
        ParentDescriptor: *mut core::ffi::c_void,  // PSECURITY_DESCRIPTOR optional
        CurrentSecurityDescriptor: *mut core::ffi::c_void,  // PSECURITY_DESCRIPTOR
        NewSecurityDescriptor: *mut *mut core::ffi::c_void,  // PSECURITY_DESCRIPTOR* out
        ObjectType: *mut GUID,  // GUID* optional
        IsDirectoryObject: u8,  // BOOLEAN
        GenericMapping: *mut GENERIC_MAPPING  // GENERIC_MAPPING*
    ) -> 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 ConvertToAutoInheritPrivateObjectSecurity(IntPtr ParentDescriptor, IntPtr CurrentSecurityDescriptor, IntPtr NewSecurityDescriptor, IntPtr ObjectType, [MarshalAs(UnmanagedType.U1)] bool IsDirectoryObject, IntPtr GenericMapping);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ADVAPI32_ConvertToAutoInheritPrivateObjectSecurity' -Namespace Win32 -PassThru
# $api::ConvertToAutoInheritPrivateObjectSecurity(ParentDescriptor, CurrentSecurityDescriptor, NewSecurityDescriptor, ObjectType, IsDirectoryObject, GenericMapping)

#uselib "ADVAPI32.dll"
#func global ConvertToAutoInheritPrivateObjectSecurity "ConvertToAutoInheritPrivateObjectSecurity" sptr, sptr, sptr, sptr, sptr, sptr
; ConvertToAutoInheritPrivateObjectSecurity ParentDescriptor, CurrentSecurityDescriptor, NewSecurityDescriptor, varptr(ObjectType), IsDirectoryObject, varptr(GenericMapping)   ; 戻り値は stat
; ParentDescriptor : PSECURITY_DESCRIPTOR optional -> "sptr"
; CurrentSecurityDescriptor : PSECURITY_DESCRIPTOR -> "sptr"
; NewSecurityDescriptor : PSECURITY_DESCRIPTOR* out -> "sptr"
; ObjectType : GUID* optional -> "sptr"
; IsDirectoryObject : BOOLEAN -> "sptr"
; GenericMapping : GENERIC_MAPPING* -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ADVAPI32.dll"
#cfunc global ConvertToAutoInheritPrivateObjectSecurity "ConvertToAutoInheritPrivateObjectSecurity" sptr, sptr, sptr, var, int, var
; res = ConvertToAutoInheritPrivateObjectSecurity(ParentDescriptor, CurrentSecurityDescriptor, NewSecurityDescriptor, ObjectType, IsDirectoryObject, GenericMapping)
; ParentDescriptor : PSECURITY_DESCRIPTOR optional -> "sptr"
; CurrentSecurityDescriptor : PSECURITY_DESCRIPTOR -> "sptr"
; NewSecurityDescriptor : PSECURITY_DESCRIPTOR* out -> "sptr"
; ObjectType : GUID* optional -> "var"
; IsDirectoryObject : BOOLEAN -> "int"
; GenericMapping : GENERIC_MAPPING* -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ADVAPI32.dll"
#cfunc global ConvertToAutoInheritPrivateObjectSecurity "ConvertToAutoInheritPrivateObjectSecurity" sptr, sptr, sptr, sptr, int, sptr
; res = ConvertToAutoInheritPrivateObjectSecurity(ParentDescriptor, CurrentSecurityDescriptor, NewSecurityDescriptor, varptr(ObjectType), IsDirectoryObject, varptr(GenericMapping))
; ParentDescriptor : PSECURITY_DESCRIPTOR optional -> "sptr"
; CurrentSecurityDescriptor : PSECURITY_DESCRIPTOR -> "sptr"
; NewSecurityDescriptor : PSECURITY_DESCRIPTOR* out -> "sptr"
; ObjectType : GUID* optional -> "sptr"
; IsDirectoryObject : BOOLEAN -> "int"
; GenericMapping : GENERIC_MAPPING* -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。