Creating a Security Descriptor for a New Object in C++

SECURITY_ATTRIBUTES
The SECURITY_ATTRIBUTES structure contains the security descriptor for an object and specifies whether the handle retrieved by specifying this structure is inheritable. This structure provides security settings for objects created by various functions, such as CreateFile, CreatePipe, CreateProcess, RegCreateKeyEx, or RegSaveKeyEx.

typedef struct _SECURITY_ATTRIBUTES {
  DWORD  nLength;
  LPVOID lpSecurityDescriptor;
  BOOL   bInheritHandle;
} SECURITY_ATTRIBUTES, *PSECURITY_ATTRIBUTES, *LPSECURITY_ATTRIBUTES;

lpSecurityDescriptor
A pointer to a SECURITY_DESCRIPTOR structure that controls access to the object. If the value of this member is NULL, the object is assigned the default security descriptor associated with the access token of the calling process. This is not the same as granting access to everyone by assigning a NULL discretionary access control list (DACL). By default, the default DACL in the access token of a process allows access only to the user represented by the access token.

-------
SECURITY_DESCRIPTOR
The SECURITY_DESCRIPTOR structure contains the security information associated with an object. Applications use this structure to set and query an object's security status.
Because the internal format of a security descriptor can vary, we recommend that applications not modify the SECURITY_DESCRIPTOR structure directly. For creating and manipulating a security descriptor, use the functions listed in See Also.

A security descriptor includes information that specifies the following components of an object's security:
An owner security identifier (SID)
A primary group SID
A discretionary access control list (DACL)
A system access control list (SACL)
Qualifiers for the preceding items

--------
InitializeSecurityDescriptor

The InitializeSecurityDescriptor function initializes a new security descriptor.
---------
Creating a Security Descriptor for a New Object in C++

access control entry
(ACE) An entry in an access control list (ACL). An ACE contains a set of access rights and a security identifier (SID) that identifies a trustee for whom the rights are allowed, denied, or audited.

access control list
(ACL) A list of security protections that applies to an object. (An object can be a file, process, event, or anything else having a security descriptor.) An entry in an access control list (ACL) is an access control entry (ACE). There are two types of access control list, discretionary and system.

EXPLICIT_ACCESS
The EXPLICIT_ACCESS structure defines access control information for a specified trustee. Access control functions, such as SetEntriesInAcl and GetExplicitEntriesFromAcl, use this structure to describe the information in an access control entry (ACE) of an access control list (ACL).

security identifier
(SID) A data structure of variable length that identifies user, group, and computer accounts. Every account on a network is issued a unique SID when the account is first created. Internal processes in Windows refer to an account's SID rather than the account's user or group name.

//SID介绍
http://blogs.technet.com/b/apgceps/archive/2011/09/06/how_2d00_to_2d00_check_2d00_sid.aspx
安全标识符SID。

说到安全标识符SID就要先说说安全主体（Security Principals），安全主体是一个能够对它分配权限的对象，例如，用户、组和计算机； 对于每一个Windows 200x域中的安全主体都有一个惟一的安全标识符SID。

 那什么是安全标识符SID呢？安全标识符SID是一个值，这个值唯一地标识一个组织内的用户、组、计算机或服务。每一个帐户在被创建时会分配到一个安全标识符，Windows 200x域中通过安全标识符SID来实现访问控制机制。

 那么访问控制机制又是如何实现的呢？对于网络的每个对象（例如一个文件），都有一组访问控制信息，该信息称为安全描述符（Security Descriptor），它控制用户和组允许使用的访问类型。安全描述符由以下三部分组成：所有者安全标识符，自由访问控制列表（DACL）和安全访问控制列表（SACL）。自由访问控制列表（DACL）通过用户（组）的SID确定哪些用户（组）被允许/拒绝访问当前对象。而安全访问控制列表（SACL）则控制如何审计用户（组）对当前对象的访问。

--------
http://msdn.microsoft.com/en-us/library/windows/desktop/aa379598(v=vs.85).aspx
http://msdn.microsoft.com/en-us/library/windows/desktop/aa446595(v=vs.85).aspx
--------
The following example creates a security descriptor for a new registry key using the following process. Similar code can be used to create a security descriptor for other object types.

?The example fills an array of EXPLICIT_ACCESS structures with the information for two ACEs. One ACE allows read access to everyone; the other ACE allows full access to administrators.
?The EXPLICIT_ACCESS array is passed to the SetEntriesInAcl function to create a DACL for the security descriptor.
?After allocating memory for the security descriptor, the example calls the InitializeSecurityDescriptor and SetSecurityDescriptorDacl functions to initialize the security descriptor and attach the DACL.
?The security descriptor is then stored in a SECURITY_ATTRIBUTES structure and passed to the RegCreateKeyEx function, which attaches the security descriptor to the newly created key.
C++Copy
 
#pragma comment(lib, "advapi32.lib")

#include <windows.h>
#include <stdio.h>
#include <aclapi.h>
#include <tchar.h>

void main()
{

    DWORD dwRes, dwDisposition;
    PSID pEveryoneSID = NULL, pAdminSID = NULL;
    PACL pACL = NULL;
    PSECURITY_DESCRIPTOR pSD = NULL;
    EXPLICIT_ACCESS ea[2];
    SID_IDENTIFIER_AUTHORITY SIDAuthWorld =
            SECURITY_WORLD_SID_AUTHORITY;
    SID_IDENTIFIER_AUTHORITY SIDAuthNT = SECURITY_NT_AUTHORITY;
    SECURITY_ATTRIBUTES sa;
    LONG lRes;
    HKEY hkSub = NULL;

    // Create a well-known SID for the Everyone group.
    if(!AllocateAndInitializeSid(&SIDAuthWorld, 1,
                     SECURITY_WORLD_RID,
                     0, 0, 0, 0, 0, 0, 0,
                     &pEveryoneSID))
    {
        _tprintf(_T("AllocateAndInitializeSid Error %u\n"), GetLastError());
        goto Cleanup;
    }

    // Initialize an EXPLICIT_ACCESS structure for an ACE.
    // The ACE will allow Everyone read access to the key.
    ZeroMemory(&ea, 2 * sizeof(EXPLICIT_ACCESS));
    ea[0].grfAccessPermissions = KEY_READ;
    ea[0].grfAccessMode = SET_ACCESS;
    ea[0].grfInheritance= NO_INHERITANCE;
    ea[0].Trustee.TrusteeForm = TRUSTEE_IS_SID;
    ea[0].Trustee.TrusteeType = TRUSTEE_IS_WELL_KNOWN_GROUP;
    ea[0].Trustee.ptstrName  = (LPTSTR) pEveryoneSID;

    // Create a SID for the BUILTIN\Administrators group.
    if(! AllocateAndInitializeSid(&SIDAuthNT, 2,
                     SECURITY_BUILTIN_DOMAIN_RID,
                     DOMAIN_ALIAS_RID_ADMINS,
                     0, 0, 0, 0, 0, 0,
                     &pAdminSID))
    {
        _tprintf(_T("AllocateAndInitializeSid Error %u\n"), GetLastError());
        goto Cleanup;
    }

    // Initialize an EXPLICIT_ACCESS structure for an ACE.
    // The ACE will allow the Administrators group full access to
    // the key.
    ea[1].grfAccessPermissions = KEY_ALL_ACCESS;
    ea[1].grfAccessMode = SET_ACCESS;
    ea[1].grfInheritance= NO_INHERITANCE;
    ea[1].Trustee.TrusteeForm = TRUSTEE_IS_SID;
    ea[1].Trustee.TrusteeType = TRUSTEE_IS_GROUP;
    ea[1].Trustee.ptstrName  = (LPTSTR) pAdminSID;

    // Create a new ACL that contains the new ACEs.
    dwRes = SetEntriesInAcl(2, ea, NULL, &pACL);
    if (ERROR_SUCCESS != dwRes)
    {
        _tprintf(_T("SetEntriesInAcl Error %u\n"), GetLastError());
        goto Cleanup;
    }

    // Initialize a security descriptor. 
    pSD = (PSECURITY_DESCRIPTOR) LocalAlloc(LPTR,
                             SECURITY_DESCRIPTOR_MIN_LENGTH);
    if (NULL == pSD)
    {
        _tprintf(_T("LocalAlloc Error %u\n"), GetLastError());
        goto Cleanup;
    }
 
    if (!InitializeSecurityDescriptor(pSD,
            SECURITY_DESCRIPTOR_REVISION))
    { 
        _tprintf(_T("InitializeSecurityDescriptor Error %u\n"),
                                GetLastError());
        goto Cleanup;
    }
 
    // Add the ACL to the security descriptor.
    if (!SetSecurityDescriptorDacl(pSD,
            TRUE,     // bDaclPresent flag  
            pACL,
            FALSE))   // not a default DACL
    { 
        _tprintf(_T("SetSecurityDescriptorDacl Error %u\n"),
                GetLastError());
        goto Cleanup;
    }

    // Initialize a security attributes structure.
    sa.nLength = sizeof (SECURITY_ATTRIBUTES);
    sa.lpSecurityDescriptor = pSD;
    sa.bInheritHandle = FALSE;

    // Use the security attributes to set the security descriptor
    // when you create a key.
    lRes = RegCreateKeyEx(HKEY_CURRENT_USER, _T("mykey"), 0, _T(""), 0,
            KEY_READ | KEY_WRITE, &sa, &hkSub, &dwDisposition);
    _tprintf(_T("RegCreateKeyEx result %u\n"), lRes );

Cleanup:

    if (pEveryoneSID)
        FreeSid(pEveryoneSID);
    if (pAdminSID)
        FreeSid(pAdminSID);
    if (pACL)
        LocalFree(pACL);
    if (pSD)
        LocalFree(pSD);
    if (hkSub)
        RegCloseKey(hkSub);

    return;

}