0 out of 1 rated this helpful - Rate this topic

SetNamedSecurityInfo function

Applies to: desktop apps only

The SetNamedSecurityInfo function sets specified security information in the security descriptor of a specified object. The caller identifies the object by name.

Syntax

Copy

DWORD WINAPI SetNamedSecurityInfo(
  __in      LPTSTR pObjectName,
  __in      SE_OBJECT_TYPE ObjectType,
  __in      SECURITY_INFORMATION SecurityInfo,
  __in_opt  PSID psidOwner,
  __in_opt  PSID psidGroup,
  __in_opt  PACL pDacl,
  __in_opt  PACL pSacl
);

Parameters

pObjectName [in]

A pointer to a null-terminated string that specifies the name of the object for which to set security information. This can be the name of a local or remote file or directory on an NTFS file system, network share, registry key, semaphore, event, mutex, file mapping, or waitable timer.

For descriptions of the string formats for the different object types, see SE_OBJECT_TYPE.

ObjectType [in]

A value of the SE_OBJECT_TYPE enumeration that indicates the type of object named by the pObjectName parameter.

SecurityInfo [in]

A set of bit flags that indicate the type of security information to set. This parameter can be a combination of the SECURITY_INFORMATION bit flags.

Value	Meaning
OWNER_SECURITY_INFORMATION 0x00000001	Include the owner.
GROUP_SECURITY_INFORMATION 0x00000002	Include the primary group.
DACL_SECURITY_INFORMATION 0x00000004	Include the discretionary access control list (DACL).
SACL_SECURITY_INFORMATION 0x00000008	Include the system access control list (SACL).
LABEL_SECURITY_INFORMATION 0x00000010	Include the mandatory integrity label access control entry (ACE).
ATTRIBUTE_SECURITY_INFORMATION 0x00000020	Include the attribute information of the SACL. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP: This value is not supported.
SCOPE_SECURITY_INFORMATION 0x00000040	Include the central access policy (CAP) identifier of the SACL. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP: This value is not supported.

psidOwner [in, optional]

A pointer to a SID structure that identifies the owner of the object. If the caller does not have the SeRestorePrivilege constant (see Privilege Constants), this SID must be contained in the caller's token, and must have the SE_GROUP_OWNER permission enabled. The SecurityInfo parameter must include the OWNER_SECURITY_INFORMATION flag. To set the owner, the caller must have WRITE_OWNER access to the object or have the SE_TAKE_OWNERSHIP_NAME privilege enabled. If you are not setting the owner SID, this parameter can be NULL.

psidGroup [in, optional]

A pointer to a SID that identifies the primary group of the object. The SecurityInfo parameter must include the GROUP_SECURITY_INFORMATION flag. If you are not setting the primary group SID, this parameter can be NULL.

pDacl [in, optional]

A pointer to the new DACL for the object. The SecurityInfo parameter must include the DACL_SECURITY_INFORMATION flag. The caller must have WRITE_DAC access to the object or be the owner of the object. If you are not setting the DACL, this parameter can be NULL.

pSacl [in, optional]

A pointer to the new SACL for the object. The SecurityInfo parameter must include the SACL_SECURITY_INFORMATION flag. The caller must have the SE_SECURITY_NAME privilege enabled. If you are not setting the SACL, this parameter can be NULL

Return value

If the function succeeds, the function returns ERROR_SUCCESS.

If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks

If you are setting the discretionary access control list (DACL) or system access control list (SACL) of an object, the system automatically propagates any inheritable access control entries (ACEs) to existing child objects, according to the rules of inheritance.

You can use the SetNamedSecurityInfo function with the following types of objects:

Local or remote files or directories on an NTFS
Local or remote printers
Local or remote Windows services
Network shares
Registry keys
Semaphores, events, mutexes, and waitable timers
File-mapping objects
Directory service objects

The SetNamedSecurityInfo function does not reorder access-allowed or access-denied ACEs based on the preferred order. When propagating inheritable ACEs to existing child objects, SetNamedSecurityInfo puts inherited ACEs in order after all of the noninherited ACEs in the DACLs of the child objects.

This function transfers information in plaintext. The information transferred by this function is signed unless signing has been turned off for the system, but no encryption is performed.

Examples

For an example that uses this function, see Modifying the ACLs of an Object or Taking Object Ownership.

Requirements

Minimum supported client	Windows XP
Minimum supported server	Windows Server 2003
Header	Aclapi.h
Library	Advapi32.lib
DLL	Advapi32.dll
Unicode and ANSI names	SetNamedSecurityInfoW (Unicode) and SetNamedSecurityInfoA (ANSI)

Note: The high-level security APIs (SetNamedSecurityInfo, SetSecurityInfo) use the metaflags PROTECTED_DACL_SECURITY_INFORMATION and PROTECTED_SACL_SECURITY_INFORMATION to indicate that you want to set the flag SE_DACL_PROTECTED (0x1000) or SE_SACL_PROTECTED (0x2000) in the security descriptor. In a similar fashion, the metaflags UNPROTECTED_DACL_SECURITY_INFORMATION and UNPROTECTED_SACL_SECURITY_INFORMATION indicate that you want to clear the respective flags in the security descriptor. The metaflags are not stored in the security descriptor.

History

11/24/2007
Gideon7

9/2/2011
Gideon7

No way to access 64-bit registry keys in WOW64

Note: When getting or setting the ACLs in the registry using SetNamedSecurityInfo or GetNamedSecurityInfo there is no way to access the 64-bit registry keys from a 32-bit DLL or EXE. A new SE_OBJECT_TYPE named SE_REGISTRY_WOW64_64KEY is needed that sets KEY_WOW64_64KEY in NTMARTA.DLL.

This means, for example, there is no way to create a 32/64bit agnostic SETUP.EXE that can adjust registry security settings during an installation. The workaround is to create a 64-bit DLL or EXE and distribute both.