CreateSecurityDescriptor() [1/4]

AutoSecurityDescriptor Chusov::Win32::Security::CreateSecurityDescriptor	(	LPCWSTR	pszOwnerName,
		LPCWSTR	pszGroupName,
		AllowedInputIterator	itAllowedBegin,
		AllowedInputIterator	itAllowedEnd,
		DeniedInputIterator	itDeniedBegin,
		DeniedInputIterator	itDeniedEnd
	)

Allocates and constructs a self-relative security descriptor from its three components: an owner, a group and a discretionary access control list (DACL). The owner and the group are specified by respective principal names with optional domain names, which the principals belong to. The DACL is passed to the function as half-intervals, specified by two pairs of input iterators within two containers of ACCESS_ALLOWED_ACE_INFO objects and of ACCESS_DENIED_ACE_INFO objects, that respectively specify access-allowed and access-denied access control entries (ACE) to be included into the created security descriptor.

Template Parameters

AllowedInputIterator	is a type of an input iterator, specifying a range within a container of access-allowed ACEs.
DeniedInputIterator	is a type of an input iterator, specifying a range within a container of access-denied ACEs.

Parameters

[in]	pszOwnerName	is an optional pointer to a zero-terminated wide string specifying a name of a principal to be included into the created security descriptor as its owner. The name can include an optional domain name, which the principal belongs to. A principal name qualified with the corresponding domain name should be specified as "domain_name\user_name". If the domain name is omitted, a security identifier of the principal is sought in the current system domain. If the pszOwnerName is NULL, the created security descriptor does not have an owner.
[in]	pszGroupName	is an optional pointer to a zero-terminated wide string specifying a name of a principal, that is associated with a group, to be included into the created security descriptor as its group. The name can include an optional domain name, which the principal belongs to. A principal name qualified with the corresponding domain name should be specified as "domain_name\user_name". If the domain name is omitted, a security identifier of the principal is sought in the current system domain. If the pszGroupName is NULL, the created security descriptor does not have a group.
	itAllowedBegin	is an iterator specifying an inclusive first border of a range of access-allowed ACEs, which are held within some container. The iterator must be at least an input iterator.
	itAllowedEnd	is an iterator specifying an exclusive second border of a range of access-allowed ACEs, which are held within some container. The iterator must be at least an input iterator.
	itDeniedBegin	is an iterator specifying an inclusive first border of a range of access-denied ACEs, which are held within some container. The iterator must be at least an input iterator.
	itDeniedEnd	is an iterator specifying an exclusive second border of a range of access-denied ACEs, which are held within some container. The iterator must be at least an input iterator.

Returns

The function returns a smart AutoSecurityDescriptor pointer to the created self-relative security descriptor.

Each pointer to the names, which are zero-terminated wide strings, is optional. A NULL pointer to an owner name causes the function to create a security descriptor without an owner. Consequently, a NULL pointer to a group name causes the function to create security descriptor without a group.

There is no way to create a security descriptor without a DACL, because if both ranges of ACEs, specified by the iterators, are empty, the function assigns an empty (but valid) DACL to the returned security descriptor. Such descriptor will prohibit anyone from accessing the object, which the created security descriptor is assigned to. To create an empty security descriptor use the CreateSecurityDescriptor overloaded function, for which pOwner and pGroup can be retrieved by calling the GetSidByPrincipalName function.

A revision of the created DACL corresponds to ACL_REVISION constant. See InitializeAcl for more detailed information.

A call to the function is equivalent to the following code:

PSECURITY_DWSCRIPTOR pSD = CreateSecurityDescriptor(
        pszOwnerName == NULL?NULL:Chusov::Memory::AutoData<PSID>(GetSidByPrincipalName(pszOwnerName)).get(),
        pszGroupName == NULL?NULL:Chusov::Memory::AutoData<PSID>(GetSidByPrincipalName(pszGroupName)).get(),
        Chusov::Memory::AutoData<PACL>(CreateDACL(itAllowedBegin, itAllowedEnd, itDeniedBegin, itDeniedEnd, ACL_REVISION)).get());

Exceptions

std::bad_alloc	The function was unable to allocate a required amount of memory to complete the request.
Chusov::Exceptions::ArithmeticOverflowException	A size, in bytes, of the DACL to be allocated must fit 32 bits (as specified by DWORD values), but it does not.
Chusov::Exceptions::ChsvCodeException	System-level error occurred.