ホーム › Security.Authorization › SetNamedSecurityInfoA

SetNamedSecurityInfoA

関数

名前付きオブジェクトのセキュリティ情報を設定する(ANSI版)。

DLLADVAPI32.dll文字セットANSI (-A)呼出規約winapi対応OSWindows XP 以降

シグネチャ

// ADVAPI32.dll  (ANSI / -A)
#include <windows.h>

WIN32_ERROR SetNamedSecurityInfoA(
    LPSTR pObjectName,
    SE_OBJECT_TYPE ObjectType,
    OBJECT_SECURITY_INFORMATION SecurityInfo,
    PSID psidOwner,   // optional
    PSID psidGroup,   // optional
    ACL* pDacl,   // optional
    ACL* pSacl   // optional
);

パラメーター

名前	型	方向	説明
pObjectName	LPSTR	in	セキュリティ情報を設定する対象オブジェクトの名前を指定する null 終端文字列へのポインターです。NTFS ファイルシステム上のローカルまたはリモートのファイルやディレクトリ、ネットワーク共有、レジストリキー、セマフォ、イベント、ミューテックス、ファイルマッピング、または待機可能タイマーの名前を指定できます。オブジェクトの種類ごとの文字列形式については、 SE_OBJECT_TYPE を参照してください。
ObjectType	SE_OBJECT_TYPE	in	pObjectName パラメーターで指定したオブジェクトの種類を示す SE_OBJECT_TYPE 列挙の値です。
SecurityInfo	OBJECT_SECURITY_INFORMATION	in	設定するセキュリティ情報の種類を示すビットフラグのセットです。このパラメーターには、SECURITY_INFORMATION ビットフラグの組み合わせを指定できます。
psidOwner	PSID	inoptional	オブジェクトの所有者を識別する SID 構造体へのポインターです。呼び出し元が SeRestorePrivilege 定数(Privilege Constants を参照)を持たない場合、この SID は呼び出し元のトークンに含まれており、かつ SE_GROUP_OWNER アクセス許可が有効である必要があります。SecurityInfo パラメーターには OWNER_SECURITY_INFORMATION フラグを含める必要があります。所有者を設定するには、呼び出し元がオブジェクトに対する WRITE_OWNER アクセス権を持つか、SE_TAKE_OWNERSHIP_NAME 特権を有効にしている必要があります。所有者 SID を設定しない場合、このパラメーターには NULL を指定できます。
psidGroup	PSID	inoptional	オブジェクトのプライマリグループを識別する SID へのポインターです。SecurityInfo パラメーターには GROUP_SECURITY_INFORMATION フラグを含める必要があります。プライマリグループ SID を設定しない場合、このパラメーターには NULL を指定できます。
pDacl	ACL*	inoptional	オブジェクトの新しい DACL へのポインターです。SecurityInfo パラメーターには DACL_SECURITY_INFORMATION フラグを含める必要があります。呼び出し元はオブジェクトに対する WRITE_DAC アクセス権を持つか、オブジェクトの所有者である必要があります。DACL を設定しない場合、このパラメーターには NULL を指定できます。
pSacl	ACL*	inoptional	オブジェクトの新しい SACL へのポインターです。SecurityInfo パラメーターには、次のいずれかのフラグを含める必要があります。SACL_SECURITY_INFORMATION、LABEL_SECURITY_INFORMATION、ATTRIBUTE_SECURITY_INFORMATION、SCOPE_SECURITY_INFORMATION、または BACKUP_SECURITY_INFORMATION。 SACL_SECURITY_INFORMATION または SCOPE_SECURITY_INFORMATION を設定する場合、呼び出し元は SE_SECURITY_NAME 特権を有効にしている必要があります。SACL を設定しない場合、このパラメーターには NULL を指定できます。

戻り値の型: WIN32_ERROR

公式ドキュメント

指定したオブジェクトのセキュリティ記述子に、指定したセキュリティ情報を設定します。(ANSI)

戻り値

関数が成功した場合、ERROR_SUCCESS を返します。

関数が失敗した場合、WinError.h で定義されている 0 以外のエラーコードを返します。

解説(Remarks)

オブジェクトの discretionary access control list(DACL)または system access control list(SACL)内の要素を設定すると、システムは継承規則に従って、継承可能な access control entries(ACE)を既存の子オブジェクトに自動的に伝播します。

SetNamedSecurityInfo 関数は、次の種類のオブジェクトで使用できます。

NTFS 上のローカルまたはリモートのファイルやディレクトリ
ローカルまたはリモートのプリンター
ローカルまたはリモートの Windows サービス
ネットワーク共有
レジストリキー
セマフォ、イベント、ミューテックス、および待機可能タイマー
ファイルマッピングオブジェクト
ディレクトリサービスオブジェクト

SetNamedSecurityInfo 関数は、推奨される順序に基づいてアクセス許可 ACE やアクセス拒否 ACE を並べ替えることはありません。継承可能な ACE を既存の子オブジェクトに伝播する際、SetNamedSecurityInfo は、子オブジェクトの DACL 内のすべての非継承 ACE の後に、継承された ACE を配置します。

この関数は情報を plaintext で転送します。この関数で転送される情報は、システムで署名が無効化されていない限り署名されますが、暗号化は行われません。

\Test\TestFolder のような UNC パスで示されるフォルダーのアクセス権を更新すると、元の継承された ACE が削除され、ボリュームのフルパスは含まれません。

例

この関数を使用する例については、Modifying the ACLs of an Object または Taking Object Ownership を参照してください。

メモ

aclapi.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして SetNamedSecurityInfo を定義しています。エンコーディング中立のエイリアスの使用と、エンコーディング中立でないコードを混在させると、不一致が生じ、コンパイルエラーや実行時エラーの原因となる場合があります。詳細については、Conventions for Function Prototypes を参照してください。

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

各言語での呼び出し定義

// ADVAPI32.dll  (ANSI / -A)
#include <windows.h>

WIN32_ERROR SetNamedSecurityInfoA(
    LPSTR pObjectName,
    SE_OBJECT_TYPE ObjectType,
    OBJECT_SECURITY_INFORMATION SecurityInfo,
    PSID psidOwner,   // optional
    PSID psidGroup,   // optional
    ACL* pDacl,   // optional
    ACL* pSacl   // optional
);

[DllImport("ADVAPI32.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern uint SetNamedSecurityInfoA(
    [MarshalAs(UnmanagedType.LPStr)] string pObjectName,   // LPSTR
    int ObjectType,   // SE_OBJECT_TYPE
    uint SecurityInfo,   // OBJECT_SECURITY_INFORMATION
    IntPtr psidOwner,   // PSID optional
    IntPtr psidGroup,   // PSID optional
    IntPtr pDacl,   // ACL* optional
    IntPtr pSacl   // ACL* optional
);

<DllImport("ADVAPI32.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function SetNamedSecurityInfoA(
    <MarshalAs(UnmanagedType.LPStr)> pObjectName As String,   ' LPSTR
    ObjectType As Integer,   ' SE_OBJECT_TYPE
    SecurityInfo As UInteger,   ' OBJECT_SECURITY_INFORMATION
    psidOwner As IntPtr,   ' PSID optional
    psidGroup As IntPtr,   ' PSID optional
    pDacl As IntPtr,   ' ACL* optional
    pSacl As IntPtr   ' ACL* optional
) As UInteger
End Function

' pObjectName : LPSTR
' ObjectType : SE_OBJECT_TYPE
' SecurityInfo : OBJECT_SECURITY_INFORMATION
' psidOwner : PSID optional
' psidGroup : PSID optional
' pDacl : ACL* optional
' pSacl : ACL* optional
Declare PtrSafe Function SetNamedSecurityInfoA Lib "advapi32" ( _
    ByVal pObjectName As String, _
    ByVal ObjectType As Long, _
    ByVal SecurityInfo As Long, _
    ByVal psidOwner As LongPtr, _
    ByVal psidGroup As LongPtr, _
    ByVal pDacl As LongPtr, _
    ByVal pSacl As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

SetNamedSecurityInfoA = ctypes.windll.advapi32.SetNamedSecurityInfoA
SetNamedSecurityInfoA.restype = wintypes.DWORD
SetNamedSecurityInfoA.argtypes = [
    wintypes.LPCSTR,  # pObjectName : LPSTR
    ctypes.c_int,  # ObjectType : SE_OBJECT_TYPE
    wintypes.DWORD,  # SecurityInfo : OBJECT_SECURITY_INFORMATION
    wintypes.HANDLE,  # psidOwner : PSID optional
    wintypes.HANDLE,  # psidGroup : PSID optional
    ctypes.c_void_p,  # pDacl : ACL* optional
    ctypes.c_void_p,  # pSacl : ACL* optional
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ADVAPI32.dll')
SetNamedSecurityInfoA = Fiddle::Function.new(
  lib['SetNamedSecurityInfoA'],
  [
    Fiddle::TYPE_VOIDP,  # pObjectName : LPSTR
    Fiddle::TYPE_INT,  # ObjectType : SE_OBJECT_TYPE
    -Fiddle::TYPE_INT,  # SecurityInfo : OBJECT_SECURITY_INFORMATION
    Fiddle::TYPE_VOIDP,  # psidOwner : PSID optional
    Fiddle::TYPE_VOIDP,  # psidGroup : PSID optional
    Fiddle::TYPE_VOIDP,  # pDacl : ACL* optional
    Fiddle::TYPE_VOIDP,  # pSacl : ACL* optional
  ],
  -Fiddle::TYPE_INT)

#[link(name = "advapi32")]
extern "system" {
    fn SetNamedSecurityInfoA(
        pObjectName: *mut u8,  // LPSTR
        ObjectType: i32,  // SE_OBJECT_TYPE
        SecurityInfo: u32,  // OBJECT_SECURITY_INFORMATION
        psidOwner: *mut core::ffi::c_void,  // PSID optional
        psidGroup: *mut core::ffi::c_void,  // PSID optional
        pDacl: *mut ACL,  // ACL* optional
        pSacl: *mut ACL  // ACL* optional
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("ADVAPI32.dll", CharSet = CharSet.Ansi)]
public static extern uint SetNamedSecurityInfoA([MarshalAs(UnmanagedType.LPStr)] string pObjectName, int ObjectType, uint SecurityInfo, IntPtr psidOwner, IntPtr psidGroup, IntPtr pDacl, IntPtr pSacl);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ADVAPI32_SetNamedSecurityInfoA' -Namespace Win32 -PassThru
# $api::SetNamedSecurityInfoA(pObjectName, ObjectType, SecurityInfo, psidOwner, psidGroup, pDacl, pSacl)

#uselib "ADVAPI32.dll"
#func global SetNamedSecurityInfoA "SetNamedSecurityInfoA" sptr, sptr, sptr, sptr, sptr, sptr, sptr
; SetNamedSecurityInfoA pObjectName, ObjectType, SecurityInfo, psidOwner, psidGroup, varptr(pDacl), varptr(pSacl)   ; 戻り値は stat
; pObjectName : LPSTR -> "sptr"
; ObjectType : SE_OBJECT_TYPE -> "sptr"
; SecurityInfo : OBJECT_SECURITY_INFORMATION -> "sptr"
; psidOwner : PSID optional -> "sptr"
; psidGroup : PSID optional -> "sptr"
; pDacl : ACL* optional -> "sptr"
; pSacl : ACL* optional -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ADVAPI32.dll"
#cfunc global SetNamedSecurityInfoA "SetNamedSecurityInfoA" str, int, int, sptr, sptr, var, var
; res = SetNamedSecurityInfoA(pObjectName, ObjectType, SecurityInfo, psidOwner, psidGroup, pDacl, pSacl)
; pObjectName : LPSTR -> "str"
; ObjectType : SE_OBJECT_TYPE -> "int"
; SecurityInfo : OBJECT_SECURITY_INFORMATION -> "int"
; psidOwner : PSID optional -> "sptr"
; psidGroup : PSID optional -> "sptr"
; pDacl : ACL* optional -> "var"
; pSacl : ACL* optional -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ADVAPI32.dll"
#cfunc global SetNamedSecurityInfoA "SetNamedSecurityInfoA" str, int, int, sptr, sptr, sptr, sptr
; res = SetNamedSecurityInfoA(pObjectName, ObjectType, SecurityInfo, psidOwner, psidGroup, varptr(pDacl), varptr(pSacl))
; pObjectName : LPSTR -> "str"
; ObjectType : SE_OBJECT_TYPE -> "int"
; SecurityInfo : OBJECT_SECURITY_INFORMATION -> "int"
; psidOwner : PSID optional -> "sptr"
; psidGroup : PSID optional -> "sptr"
; pDacl : ACL* optional -> "sptr"
; pSacl : ACL* optional -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。