Article ID: 316440
Article Last Modified on 11/21/2006
APPLIES TO
- Microsoft Win32 Application Programming Interface, when used with:
- Microsoft Windows NT 4.0
- Microsoft Windows 2000 Standard Edition
- Microsoft Windows XP Professional
This article was previously published under Q316440
SUMMARY
The Win32 Application Programming Interface (API) provides two sets of APIs for working with security descriptors and access control lists (ACLs): low-level and high-level. This article provides a link to a complete set of Microsoft Visual Basic code samples that use low-level access control APIs to create, as well as modify, an existing discretionary ACL (DACL) on a kernel object, user object, shared resource (such as a shared folder or shared printer), registry key, or printer.
Note New applications should not use the low-level access control API; low-level access control APIs should be used only on Windows NT 4.0-and-earlier operating systems. The low-level access control API does not perform inheritance propagation and does not format the ACL for user interface (UI) ordering requirements on Windows 2000, Windows XP, and later operating systems. Applications that run on Windows 2000, Windows XP, and later operating systems should use the high-level access control API when manipulating object security descriptors.
MORE INFORMATION
The Visual Basic code samples from the Microsoft Download Center link in this article use the User1, User2, and User3 user accounts, and the Group1 group account to demonstrate how local or domain accounts can be specified by the caller to add them to a new or existing DACL of any securable object.
The CreateObjectSecurityDescriptor function in the sample code is used to create a new security descriptor that can be used for the SECURITY_ATTRIBUTES parameter when you create any securable object.
The UpdatePermissionsOfKernelObject function in the sample code uses the GetKernelObjectSecurity() and SetKernelObjectSecurity() functions to modify an existing DACL of any kernel object. UpdatePermissionsOfFolder is used to call this helper function to modify permissions on an NTFS file or folder (c:\temp\test).
The UpdatePermissionsOfRegistryKey function in the sample code uses the RegGetKeySecurity() and RegSetKeySecurity() functions to modify an existing DACL of a registry key. UpdatePermissionsOfHKLM is used to call this helper function to modify permissions on a SOFTWARE\TEST registry key under HKEY_LOCAL_MACHINE.
The UpdatePermissionsOfShare function in the sample code uses NetShareGetInfo() and NetShareSetInfo() functions at level 502 to modify an existing DACL of a shared resource. UpdatePermissionsOfTestShare is used to call this helper function to modify permissions on a "TestShare" shared printer or shared folder resource.
The UpdatePermissionsOfUserObject function in the sample code uses the GetUserObjectSecurity() and SetUserObjectSecurity() functions to modify an existing DACL of any user object. UpdatePermissionsOfDesktop is used to call this helper function to modify permissions of the "Default" desktop in the current window station.
The UpdatePermissionsOfPrinter function in the sample code uses the GetPrinter() and SetPrinter() functions at level 3 to modify an existing DACL of a printer. UpdatePermissionsOfTestPrinter is used to call this helper function to modify permissions of the "TestPrinter" printer.
The following file is available for download from the Microsoft Download Center:
![[GRAPHIC: Download]](/wiki/index.php?title=File:Download.gif){kind=small}
Release Date: June-11-2002
For more information about how to download Microsoft Support files, click the following article number to view the article in the Microsoft Knowledge Base:
119591 How to obtain Microsoft support files from online services
Microsoft scanned this file for viruses. Microsoft used the most current virus-detection software that was available on the date that the file was posted. The file is stored on security-enhanced servers that help prevent any unauthorized changes to the file. The Visual Basic sample code from the preceding Download Center link uses the following generic structure to represent the permissions for a user or group account
Public Type AccountPerm
AccountName As String
AccessMask As Long
AceFlags As Byte
AceType As Byte
pSid As Long
SidPassedByCaller As Boolean
End Type
where AccountName is any user or group account name, and AccessMask is any of the generic or object-specific access masks. All the access mask constants for any securable object are defined in the sample code. AceFlags and AceType structure members have the same values as documented in the ACE_HEADER data structure in the Microsoft Platform SDK.
As demonstrated in some of the code samples available through the preceding link, the caller can specify an array of AccountPerm structures to either construct a new security descriptor or add to an existing security descriptor of any securable object. If the caller wants to pass a well known SID, the caller can allocate the SID by using the AllocateAndInitializeSid() function and then specify it in the pSid structure member, with SidPassedByCaller set to True.
For more information about well known SIDs, click the following article number to view the article in the Microsoft Knowledge Base:
288900 How to use Visual Basic to construct a well-known SID
REFERENCES
For more information about how to use high-level Access Control APIs, click the following article number to view the article in the Microsoft Knowledge Base:
295004 How to use high-level access control APIs from Visual Basic
Keywords: kbdownload kbapi kbhowto kbinfo kbkernbase kbsample kbsecurity KB316440
