GetNamedSecurityInfo function
Applies to: desktop apps only
The GetNamedSecurityInfo function retrieves a copy of the security descriptor for an object specified by name.
Syntax
DWORD WINAPI GetNamedSecurityInfo( __in LPTSTR pObjectName, __in SE_OBJECT_TYPE ObjectType, __in SECURITY_INFORMATION SecurityInfo, __out_opt PSID *ppsidOwner, __out_opt PSID *ppsidGroup, __out_opt PACL *ppDacl, __out_opt PACL *ppSacl, __out_opt PSECURITY_DESCRIPTOR *ppSecurityDescriptor );
Parameters
- pObjectName [in]
-
A pointer to a null-terminated string that specifies the name of the object from which to retrieve security information. For descriptions of the string formats for the different object types, see SE_OBJECT_TYPE.
- ObjectType [in]
-
Specifies a value from 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 retrieve. 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. - ppsidOwner [out, optional]
-
A pointer to a variable that receives a pointer to the owner SID in the security descriptor returned in ppSecurityDescriptor or NULL if the security descriptor has no owner SID. The returned pointer is valid only if you set the OWNER_SECURITY_INFORMATION flag. Also, this parameter can be NULL if you do not need the owner SID.
- ppsidGroup [out, optional]
-
A pointer to a variable that receives a pointer to the primary group SID in the returned security descriptor or NULL if the security descriptor has no group SID. The returned pointer is valid only if you set the GROUP_SECURITY_INFORMATION flag. Also, this parameter can be NULL if you do not need the group SID.
- ppDacl [out, optional]
-
A pointer to a variable that receives a pointer to the DACL in the returned security descriptor or NULL if the security descriptor has no DACL. The returned pointer is valid only if you set the DACL_SECURITY_INFORMATION flag. Also, this parameter can be NULL if you do not need the DACL.
- ppSacl [out, optional]
-
A pointer to a variable that receives a pointer to the SACL in the returned security descriptor or NULL if the security descriptor has no SACL. The returned pointer is valid only if you set the SACL_SECURITY_INFORMATION flag. Also, this parameter can be NULL if you do not need the SACL.
- ppSecurityDescriptor [out, optional]
-
A pointer to a variable that receives a pointer to the security descriptor of the object. When you have finished using the pointer, free the returned buffer by calling the LocalFree function.
This parameter is required if any one of the ppsidOwner, ppsidGroup, ppDacl, or ppSacl parameters is not NULL.
Return value
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is a nonzero error code defined in WinError.h.
Remarks
If any of the ppsidOwner, ppsidGroup, ppDacl, or ppSacl parameters are non-NULL, and the SecurityInfo parameter specifies that they be retrieved from the object, those parameters will point to the corresponding parameters in the security descriptor returned in ppSecurityDescriptor. If the security descriptor does not contain the requested information, the corresponding parameter will be set to NULL.
To read the owner, group, or DACL from the object's security descriptor, the object's DACL must grant READ_CONTROL access to the caller, or the caller must be the owner of the object.
To read the system access control list of the object, the SE_SECURITY_NAME privilege must be enabled for the calling process. For information about the security implications of enabling privileges, see Running with Special Privileges.
You can use the GetNamedSecurityInfo function with the following types of objects:
- Local or remote files or directories on an NTFS file system
- 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
This function does not handle race conditions. If your thread calls this function at the approximate time that another thread changes the object's security descriptor, then this function could fail.
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.
For more information about controlling access to objects through user accounts, group accounts, or logon sessions, see How DACLs Control Access to an Object.
Examples
For an example that uses GetNamedSecurityInfo, see Modifying the ACLs of an Object.
Requirements
|
Minimum supported client | Windows XP |
|---|---|
|
Minimum supported server | Windows 2000 Server |
|
Header |
|
|
Library |
|
|
DLL |
|
|
Unicode and ANSI names | GetNamedSecurityInfoW (Unicode) and GetNamedSecurityInfoA (ANSI) |
See also
- Access Control
- Basic Access Control Functions
- Privilege Constants
- ACL
- GetSecurityInfo
- LocalFree
- SE_OBJECT_TYPE
- SECURITY_DESCRIPTOR
- SECURITY_INFORMATION
- SetNamedSecurityInfo
- SetSecurityInfo
- SID
Send comments about this topic to Microsoft
Build date: 3/7/2012
[tfl - 16 02 10] Hi - and thanks for your post. You should post questions like this to the MSDN Forums at http://forums.microsoft.com/msdn or the MSDN Newsgroups at http://www.microsoft.com/communities/newsgroups/en-us/. You are much more likely get a quicker response using the forums than through the Community Content. For specific help about:
.NET Framework : http://groups.google.com/groups/dir?sel=usenet%3Dmicrosoft.public.dotnet.framework
PowerShell : http://groups.google.com/group/microsoft.public.windows.powershell/topics?pli=1
SQL Server : http://groups.google.com/groups/dir?sel=usenet%3Dmicrosoft.public.sqlserver%2C&
Visual Studio : http://groups.google.com/groups/dir?sel=usenet%3Dmicrosoft.public.vstudio%2C&
Windows : http://groups.google.com/groups/dir?sel=usenet%3Dmicrosoft.public.windows%2C&
All Public : http://groups.google.com/groups/dir?sel=usenet%3Dmicrosoft.public%2C&
- 10/8/2009
- vikie
- 2/16/2010
- Thomas Lee
You can use the MSDN Forums (http://forums.microsoft.com/msdn/) or the Microsoft public security newsgroups (http://www.microsoft.com/technet/community/newsgroups/security/) to ask questions or participate in discussions about the APIs.
If you receive useful information from the forums that you want to share with other developers, we welcome you to post the information here in the community content.
Thank you.
- 1/26/2010
- Jo Lines - MSFT
The workaround is to create a 64-bit DLL (or EXE) and distribute both with your application.
