SetSecurityDescriptor method of the Win32_LogicalFileSecuritySetting class

The SetSecurityDescriptorWMI class method sets a security descriptor to the specified structure. A security descriptor contains information about the owner of the object and the object's primary group. The security descriptor also contains the discretionary access control list (DACL) and the system access control list (SACL). DACLs specify which groups and accounts have access to an object and what type of access to grant. SACLs specify who has access to the auditing entries in the Security event log.

This topic uses Managed Object Format (MOF) syntax. For more information about using this method, see Calling a Method.

Syntax

uint32 SetSecurityDescriptor(
  [in] Win32_SecurityDescriptor Descriptor
);

Parameters

Descriptor [in]

An expression that resolves to an instance of Win32_SecurityDescriptor.

Return value

The SetSecurityDescriptor method can return the error codes listed in the following list. For more information, see WMI_Return Codes.

Success (0)

Access denied (2)

Unknown failure (8)

Privilege missing (9)

Invalid parameter (21)

Other (22 4294967295)

Remarks

The SeSecurityPrivilege privilege is required to execute this method. For more information, see Executing Privileged Operations.

When a new SACL is not specified in a call to a SetSecurityDescriptor method, then the security descriptor SACL on the target securable object is set to NULL so that the previous SACL setting does not persist.

Examples

The following script calls the Win32_LogicalFileSecuritySetting::GetSecurityDescriptor method to retrieve an instance of the Win32_SecurityDescriptor class for the target object, that is, C:\TestFolder. GetSecurityDescriptor returns the SecurityDescriptor parameter with an instance of the Win32_SecurityDescriptor class that corresponds to the security descriptor for the target object. The access mask for each trustee in each access control entry (ACE) in the security descriptor changes to allow read access. For more information about security entities, see Security Descriptors.

' Connect to WMI and get the file security
' object for the testfolder directory
Set wmiFileSecSetting = GetObject ( _
    "winmgmts:Win32_LogicalFileSecuritySetting." & _
    "path='c:\\testfolder'")

' Use the Win32_LogicalFileSecuritySetting Caption
' property to create a simple header before
' clearing the discretionary access control list (DACL).
Wscript.Echo wmiFileSecSetting.Caption & ":" & vbCrLf

' Obtain the existing security descriptor for folder
RetVal = wmiFileSecSetting. _
    GetSecurityDescriptor(wmiSecurityDescriptor)
If Err <> 0 Then
    WScript.Echo "GetSecurityDescriptor failed" & _
        VBCRLF & Err.Number & VBCRLF & Err.Description
    WScript.Quit
Else
    WScript.Echo "GetSecurityDescriptor suceeded"
End If

' Retrieve the content of Win32_SecurityDescriptor
' DACL property.
' The DACL is an array of Win32_ACE objects.
DACL = wmiSecurityDescriptor.DACL

' Display the control flags in the descriptor.
Wscript.Echo "Control Flags:  " & _
    wmiSecurityDescriptor.ControlFlags

' Obtain the trustee for each access
' control entry (ACE) and change the permissions
' in the AccessMask for each ACE to read, write, and delete.
For each wmiAce in DACL
    
' Get Win32_Trustee object from ACE 
       Set Trustee = wmiAce.Trustee
'    wscript.echo "Trustee Domain: "  & Trustee.Domain
    wscript.echo "Trustee Name: "    & Trustee.Name
    wscript.echo "Access Mask: "     & wmiAce.AccessMask
' Set read access to the owner, group,
' and DACL of the security descriptor (131072) 
    wmiAce.AccessMask = 131072
    wscript.echo "Access Mask: "     & wmiAce.AccessMask            
Next

' Call the Win32_LogicalFileSecuritySetting.
' SetSecurityDescriptor method 
' to write the new security descriptor.
RetVal = wmiFileSecSetting. _
    SetSecurityDescriptor(wmiSecurityDescriptor)

Wscript.Echo "ReturnValue is:  " & RetVal

The following PowerShell example describes how to set the owner for a specified object.

function Set-Owner ($user, $Path) { 
if (!(Test-Path $Path)) {Write-Warning "Specified path is incorrect"} 
else { 
    # replace path from C:\Folder to C:\\Folder 
    $path = $path.replace("\", "\\") 

    # create SecurityDescriptor appropriated classes 
    $SD = ([WMIClass] "Win32_SecurityDescriptor").CreateInstance() 
    $Trustee = ([WMIClass] "Win32_Trustee").CreateInstance() 

    # translate user/group name to SID and write information to
    # Trustee properties 
    $SID = (new-object security.principal.ntaccount $user).translate([security.principal.securityidentifier]) 
    [byte[]] $SIDArray = ,0 * $SID.BinaryLength 
    $SID.GetBinaryForm($SIDArray,0) 
    $Trustee.Name = $user 
    $Trustee.SID = $SIDArray 
    $SD.Owner = $Trustee 

    # set control flag 
    $SD.ControlFlags="0x8000" 

    # get file or folder object 
    $wPrivilege = gwmi Win32_LogicalFileSecuritySetting -filter "path='$path'" 

    # enable SeRestorePrivilege (for Windows Vista and Windows Server 2008
    # not neccessary if running in privileged mode)
    $wPrivilege.psbase.Scope.Options.EnablePrivileges = $true 

    # Write  new SecurityDescriptor to file/folder object
    $wPrivilege.setsecuritydescriptor($SD)
}

Requirements

Minimum supported client
Windows Vista
Minimum supported server
Windows Server 2008
Namespace
Root\CIMv2
MOF
Secrcw32.mof
DLL
CIMWin32.dll

See also

Operating System Classes

Win32_LogicalFileSecuritySetting

Win32_SecurityDescriptor

Maintaining WMI Security

Changing Access Security on Securable Objects

WMI Security Descriptor Objects