CSecurityDesc Class
This class is a wrapper for the SECURITY_DESCRIPTOR structure.
Important
This class and its members cannot be used in applications that execute in the Windows Runtime.
Syntax
class CSecurityDesc
Members
Public Constructors
| Name | Description |
|---|---|
| CSecurityDesc::CSecurityDesc | The constructor. |
| CSecurityDesc::~CSecurityDesc | The destructor. |
Public Methods
| Name | Description |
|---|---|
| CSecurityDesc::FromString | Converts a string-format security descriptor into a valid, functional security descriptor. |
| CSecurityDesc::GetControl | Retrieves control information from the security descriptor. |
| CSecurityDesc::GetDacl | Retrieves discretionary access-control list (DACL) information from the security descriptor. |
| CSecurityDesc::GetGroup | Retrieves the primary group information from the security descriptor. |
| CSecurityDesc::GetOwner | Retrieves owner informaton from the security descriptor. |
| CSecurityDesc::GetPSECURITY_DESCRIPTOR | Returns a pointer to the SECURITY_DESCRIPTOR structure. |
| CSecurityDesc::GetSacl | Retrieves system access-control list (SACL) information from the security descriptor. |
| CSecurityDesc::IsDaclAutoInherited | Determines if the DACL is configured to support automatic propagation. |
| CSecurityDesc::IsDaclDefaulted | Determines if the security descriptor is configured with a default DACL. |
| CSecurityDesc::IsDaclPresent | Determines if the security descriptor contains a DACL. |
| CSecurityDesc::IsDaclProtected | Determines if the DACL is configured to prevent modifications. |
| CSecurityDesc::IsGroupDefaulted | Determines if the security descriptor's group security identifier (SID) was set by default. |
| CSecurityDesc::IsOwnerDefaulted | Determines if the security descriptor's owner SID was set by default. |
| CSecurityDesc::IsSaclAutoInherited | Determines if the SACL is configured to support automatic propagation. |
| CSecurityDesc::IsSaclDefaulted | Determines if the security descriptor is configured with a default SACL. |
| CSecurityDesc::IsSaclPresent | Determines if the security descriptor contains a SACL. |
| CSecurityDesc::IsSaclProtected | Determines if the SACL is configured to prevent modifications. |
| CSecurityDesc::IsSelfRelative | Determines if the security descriptor is in self-relative format. |
| CSecurityDesc::MakeAbsolute | Call this method to convert the security descriptor to absolute format. |
| CSecurityDesc::MakeSelfRelative | Call this method to convert the security descriptor to self-relative format. |
| CSecurityDesc::SetControl | Sets the control bits of a security descriptor. |
| CSecurityDesc::SetDacl | Sets information in a DACL. If a DACL is already present in the security descriptor, it is replaced. |
| CSecurityDesc::SetGroup | Sets the primary group information of an absolute format security descriptor, replacing any primary group information already present. |
| CSecurityDesc::SetOwner | Sets the owner information of an absolute format security descriptor, replacing any owner information already present. |
| CSecurityDesc::SetSacl | Sets information in a SACL. If a SACL is already present in the security descriptor, it is replaced. |
| CSecurityDesc::ToString | Converts a security descriptor to a string format. |
Public Operators
| Name | Description |
|---|---|
| CSecurityDesc::operator const SECURITY_DESCRIPTOR * | Returns a pointer to the SECURITY_DESCRIPTOR structure. |
| CSecurityDesc::operator = | Assignment operator. |
Remarks
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. See also AtlGetSecurityDescriptor.
Applications should not modify the SECURITY_DESCRIPTOR structure directly, and instead should use the class methods provided.
For an introduction to the access control model in Windows, see Access Control in the Windows SDK.
Requirements
Header: atlsecurity.h
CSecurityDesc::CSecurityDesc
The constructor.
CSecurityDesc() throw();
CSecurityDesc(const CSecurityDesc& rhs) throw(... );
CSecurityDesc(const SECURITY_DESCRIPTOR& rhs) throw(...);
Parameters
rhs
The CSecurityDesc object or SECURITY_DESCRIPTOR structure to assign to the new CSecurityDesc object.
Remarks
The CSecurityDesc object can optionally be created using a SECURITY_DESCRIPTOR structure or a previously defined CSecurityDesc object.
CSecurityDesc::~CSecurityDesc
The destructor.
virtual ~CSecurityDesc() throw();
Remarks
The destructor frees all allocated resources.
CSecurityDesc::FromString
Converts a string-format security descriptor into a valid, functional security descriptor.
bool FromString(LPCTSTR pstr) throw(...);
Parameters
pstr
Pointer to a null-terminated string that contains the string-format security descriptor to be converted.
Return Value
Returns true on success. Throws an exception on failure.
Remarks
The string can be created by using CSecurityDesc::ToString. Converting the security descriptor into a string makes it easier to store and transmit.
This method calls ConvertStringSecurityDescriptorToSecurityDescriptor.
CSecurityDesc::GetControl
Retrieves control information from the security descriptor.
bool GetControl(SECURITY_DESCRIPTOR_CONTROL* psdc) const throw();
Parameters
psdc
Pointer to a SECURITY_DESCRIPTOR_CONTROL structure that receives the security descriptor's control information.
Return Value
Returns true if the method succeeds, false if it fails.
Remarks
This method calls GetSecurityDescriptorControl.
CSecurityDesc::GetDacl
Retrieves discretionary access-control list (DACL) information from the security descriptor.
bool GetDacl(
CDacl* pDacl,
bool* pbPresent = NULL,
bool* pbDefaulted = NULL) const throw(...);
Parameters
pDacl
Pointer to an CDacl structure in which to store a copy of the security descriptor's DACL. If a discretionary ACL exists, the method sets pDacl to the address of the security descriptor's discretionary ACL. If a discretionary ACL does not exist, no value is stored.
pbPresent
Pointer to a value that indicates the presence of a discretionary ACL in the specified security descriptor. If the security descriptor contains a discretionary ACL, this parameter is set to true. If the security descriptor does not contain a discretionary ACL, this parameter is set to false.
pbDefaulted
Pointer to a flag set to the value of the SE_DACL_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure if a discretionary ACL exists for the security descriptor. If this flag is true, the discretionary ACL was retrieved by a default mechanism; if false, the discretionary ACL was explicitly specified by a user.
Return Value
Returns true if the method succeeds, false if it fails.
CSecurityDesc::GetGroup
Retrieves the primary group information from the security descriptor.
bool GetGroup(
CSid* pSid,
bool* pbDefaulted = NULL) const throw(...);
Parameters
pSid
Pointer to a CSid (security identifier) that receives a copy of the group stored in the CDacl.
pbDefaulted
Pointer to a flag set to the value of the SE_GROUP_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure when the method returns.
Return Value
Returns true if the method succeeds, false if it fails.
CSecurityDesc::GetOwner
Retrieves owner informaton from the security descriptor.
bool GetOwner(
CSid* pSid,
bool* pbDefaulted = NULL) const throw(...);
Parameters
pSid
Pointer to a CSid (security identifier) that receives a copy of the group stored in the CDacl.
pbDefaulted
Pointer to a flag set to the value of the SE_OWNER_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure when the method returns.
Return Value
Returns true if the method succeeds, false if it fails.
CSecurityDesc::GetPSECURITY_DESCRIPTOR
Returns a pointer to the SECURITY_DESCRIPTOR structure.
const SECURITY_DESCRIPTOR* GetPSECURITY_DESCRIPTOR() const throw();
Return Value
Returns a pointer to the SECURITY_DESCRIPTOR structure.
CSecurityDesc::GetSacl
Retrieves system access-control list (SACL) information from the security descriptor.
bool GetSacl(
CSacl* pSacl,
bool* pbPresent = NULL,
bool* pbDefaulted = NULL) const throw(...);
Parameters
pSacl
Pointer to an CSacl structure in which to store a copy of the security descriptor's SACL. If a system ACL exists, the method sets pSacl to the address of the security descriptor's system ACL. If a system ACL does not exist, no value is stored.
pbPresent
Pointer to a flag the method sets to indicate the presence of a system ACL in the specified security descriptor. If the security descriptor contains a system ACL, this parameter is set to true. If the security descriptor does not contain a system ACL, this parameter is set to false.
pbDefaulted
Pointer to a flag set to the value of the SE_SACL_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure if a system ACL exists for the security descriptor.
Return Value
Returns true if the method succeeds, false if it fails.
CSecurityDesc::IsDaclAutoInherited
Determines if the discretionary access-control list (DACL) is configured to support automatic propagation.
bool IsDaclAutoInherited() const throw();
Return Value
Returns true if the security descriptor contains a DACL which is set up to support automatic propagation of inheritable access-control entries (ACEs) to existing child objects. Returns false otherwise.
Remarks
The system sets this bit when it performs the automatic inheritance algorithm for the object and its existing child objects.
CSecurityDesc::IsDaclDefaulted
Determines if the security descriptor is configured with a default discretionary access-control list (DACL).
bool IsDaclDefaulted() const throw();
Return Value
Returns true if the security descriptor contains a default DACL, false otherwise.
Remarks
This flag can affect how the system treats the DACL, with respect to access-control entry (ACE) inheritance. For example, if an object's creator does not specify a DACL, the object receives the default DACL from the creator's access token. The system ignores this flag if the SE_DACL_PRESENT flag is not set.
This flag is used to determine how the final DACL on the object is to be computed and is not stored physically in the security descriptor control of the securable object.
To set this flag, use the CSecurityDesc::SetDacl method.
CSecurityDesc::IsDaclPresent
Determines if the security descriptor contains a discretionary access-control list (DACL).
bool IsDaclPresent() const throw();
Return Value
Returns true if the security descriptor contains a DACL, false otherwise.
Remarks
If this flag is not set, or if this flag is set and the DACL is NULL, the security descriptor allows full access to everyone.
This flag is used to hold the security information specified by a caller until the security descriptor is associated with a securable object. Once the security descriptor is associated with a securable object, the SE_DACL_PRESENT flag is always set in the security descriptor control.
To set this flag, use the CSecurityDesc::SetDacl method.
CSecurityDesc::IsDaclProtected
Determines if the discretionary access-control list (DACL) is configured to prevent modifications.
bool IsDaclProtected() const throw();
Return Value
Returns true if the DACL is configured to prevent the security descriptor from being modified by inheritable access-control entries (ACEs). Returns false otherwise.
Remarks
To set this flag, use the CSecurityDesc::SetDacl method.
This method supports automatic propagation of inheritable ACEs.
CSecurityDesc::IsGroupDefaulted
Determines if the security descriptor's group security identifier (SID) was set by default.
bool IsGroupDefaulted() const throw();
Return Value
Returns true if a default mechanism, rather than the original provider of the security descriptor, provided the security descriptor's group SID. Returns false otherwise.
Remarks
To set this flag, use the CSecurityDesc::SetGroup method.
CSecurityDesc::IsOwnerDefaulted
Determines if the security descriptor's owner security identifier (SID) was set by default.
bool IsOwnerDefaulted() const throw();
Return Value
Returns true if a default mechanism, rather than the original provider of the security descriptor, provided the security descriptor's owner SID. Returns false otherwise.
Remarks
To set this flag, use the CSecurityDesc::SetOwner method.
CSecurityDesc::IsSaclAutoInherited
Determines if the system access-control list (SACL) is configured to support automatic propagation.
bool IsSaclAutoInherited() const throw();
Return Value
Returns true if the security descriptor contains a SACL which is set up to support automatic propagation of inheritable access-control entries (ACEs) to existing child objects. Returns false otherwise.
Remarks
The system sets this bit when it performs the automatic inheritance algorithm for the object and its existing child objects.
CSecurityDesc::IsSaclDefaulted
Determines if the security descriptor is configured with a default system access-control list (SACL).
bool IsSaclDefaulted() const throw();
Return Value
Returns true if the security descriptor contains a default SACL, false otherwise.
Remarks
This flag can affect how the system treats the SACL, with respect to access-control entry (ACE) inheritance. The system ignores this flag if the SE_SACL_PRESENT flag is not set.
To set this flag, use the CSecurityDesc::SetSacl method.
CSecurityDesc::IsSaclPresent
Determines if the security descriptor contains a system access-control list (SACL).
bool IsSaclPresent() const throw();
Return Value
Returns true if the security descriptor contains a SACL, false otherwise.
Remarks
To set this flag, use the CSecurityDesc::SetSacl method.
CSecurityDesc::IsSaclProtected
Determines if the system access-control list (SACL) is configured to prevent modifications.
bool IsSaclProtected() const throw();
Return Value
Returns true if the SACL is configured to prevent the security descriptor from being modified by inheritable access-control entries (ACEs). Returns false otherwise.
Remarks
To set this flag, use the CSecurityDesc::SetSacl method.
This method supports automatic propagation of inheritable ACEs.
CSecurityDesc::IsSelfRelative
Determines if the security descriptor is in self-relative format.
bool IsSelfRelative() const throw();
Return Value
Returns true if the security descriptor is in self-relative format with all the security information in a contiguous block of memory. Returns false if the security descriptor is in absolute format. For more information, see Absolute and Self-Relative Security Descriptors.
CSecurityDesc::MakeAbsolute
Call this method to convert the security descriptor to absolute format.
bool MakeAbsolute() throw(...);
Return Value
Returns true if the method succeeds, false otherwise.
Remarks
A security descriptor in absolute format contains pointers to the information it contains, rather than the information itself. A security descriptor in self-relative format contains the information in a contiguous block of memory. In a self-relative security descriptor, a SECURITY_DESCRIPTOR structure always starts the information, but the security descriptor's other components can follow the structure in any order. Instead of using memory addresses, the components of the self-relative security descriptor are identified by offsets from the beginning of the security descriptor. This format is useful when a security descriptor must be stored on a disk or transmitted by means of a communications protocol. For more information, see Absolute and Self-Relative Security Descriptors.
CSecurityDesc::MakeSelfRelative
Call this method to convert the security descriptor to self-relative format.
bool MakeSelfRelative() throw(...);
Return Value
Returns true if the method succeeds, false otherwise.
Remarks
A security descriptor in absolute format contains pointers to the information it contains, rather than containing the information itself. A security descriptor in self-relative format contains the information in a contiguous block of memory. In a self-relative security descriptor, a SECURITY_DESCRIPTOR structure always starts the information, but the security descriptor's other components can follow the structure in any order. Instead of using memory addresses, the components of the security descriptor are identified by offsets from the beginning of the security descriptor. This format is useful when a security descriptor must be stored on a disk or transmitted by means of a communications protocol. For more information, see Absolute and Self-Relative Security Descriptors.
CSecurityDesc::operator =
Assignment operator.
CSecurityDesc& operator= (const SECURITY_DESCRIPTOR& rhs) throw(...);
CSecurityDesc& operator= (const CSecurityDesc& rhs) throw(...);
Parameters
rhs
The SECURITY_DESCRIPTOR structure or CSecurityDesc object to assign to the CSecurityDesc object.
Return Value
Returns the updated CSecurityDesc object.
CSecurityDesc::operator const SECURITY_DESCRIPTOR *
Casts a value to a pointer to the SECURITY_DESCRIPTOR structure.
operator const SECURITY_DESCRIPTOR *() const throw();
CSecurityDesc::SetControl
Sets the control bits of a security descriptor.
bool SetControl(
SECURITY_DESCRIPTOR_CONTROL ControlBitsOfInterest,
SECURITY_DESCRIPTOR_CONTROL ControlBitsToSet) throw();
Parameters
ControlBitsOfInterest
A SECURITY_DESCRIPTOR_CONTROL mask that indicates the control bits to set. For a list of the flags which can be set, see SetSecurityDescriptorControl.
ControlBitsToSet
A SECURITY_DESCRIPTOR_CONTROL mask that indicates the new values for the control bits specified by the ControlBitsOfInterest mask. This parameter can be a combination of the flags listed for the ControlBitsOfInterest parameter.
Return Value
Returns true on success, false on failure.
Remarks
This method calls SetSecurityDescriptorControl.
CSecurityDesc::SetDacl
Sets information in a discretionary access-control list (DACL). If a DACL is already present in the security descriptor, it is replaced.
inline void SetDacl(
bool bPresent = true,
bool bDefaulted = false) throw(...);
inline void SetDacl(
const CDacl& Dacl,
bool bDefaulted = false) throw(...);
Parameters
Dacl
Reference to a CDacl object specifying the DACL for the security descriptor. This parameter must not be NULL. To set a NULL DACL in the security descriptor, the first form of the method should be used with bPresent set to false.
bPresent
Specifies a flag indicating the presence of a DACL in the security descriptor. If this parameter is true, the method sets the SE_DACL_PRESENT flag in the SECURITY_DESCRIPTOR_CONTROL structure and uses the values in the Dacl and bDefaulted parameters. If it is false, the method clears the SE_DACL_PRESENT flag, and bDefaulted is ignored.
bDefaulted
Specifies a flag indicating the source of the DACL. If this flag is true, the DACL has been retrieved by some default mechanism. If false, the DACL has been explicitly specified by a user. The method stores this value in the SE_DACL_DEFAULTED flag of the SECURITY_DESCRIPTOR_CONTROL structure. If this parameter is not specified, the SE_DACL_DEFAULTED flag is cleared.
Return Value
Returns true on success, false on failure.
Remarks
There is an important difference between an empty and a nonexistent DACL. When a DACL is empty, it contains no access-control entries and no access rights have been explicitly granted. As a result, access to the object is implicitly denied. When an object has no DACL, on the other hand, no protection is assigned to the object, and any access request is granted.
CSecurityDesc::SetGroup
Sets the primary group information of an absolute format security descriptor, replacing any primary group information already present.
bool SetGroup(const CSid& Sid, bool bDefaulted = false) throw(...);
Parameters
Sid
Reference to a CSid object for the security descriptor's new primary group. This parameter must not be NULL. A security descriptor can be marked as not having a DACL or a SACL, but it must have a group and an owner, even it these are the NULL SID (which is a built-in SID with a special meaning).
bDefaulted
Indicates whether the primary group information was derived from a default mechanism. If this value is true, it is default information, and the method stores this value as the SE_GROUP_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure. If this parameter is zero, the SE_GROUP_DEFAULTED flag is cleared.
Return Value
Returns true on success, false on failure.
CSecurityDesc::SetOwner
Sets the owner information of an absolute format security descriptor. It replaces any owner information already present.
bool SetOwner(const CSid& Sid, bool bDefaulted = false) throw(...);
Parameters
Sid
The CSid object for the security descriptor's new primary owner. This parameter must not be NULL.
bDefaulted
Indicates whether the owner information is derived from a default mechanism. If this value is true, it is default information. The method stores this value as the SE_OWNER_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure. If this parameter is zero, the SE_OWNER_DEFAULTED flag is cleared.
Return Value
Returns true on success, false on failure.
CSecurityDesc::SetSacl
Sets information in a system access-control list (SACL). If a SACL is already present in the security descriptor, it is replaced.
bool SetSacl(const CSacl& Sacl, bool bDefaulted = false) throw(...);
Parameters
Sacl
Pointer to an CSacl object specifying the SACL for the security descriptor. This parameter must not be NULL, and must be a CSacl object. Unlike DACLs, there is no difference between NULL and an empty SACL, as SACL objects do not specify access rights, only auditing information.
bDefaulted
Specifies a flag indicating the source of the SACL. If this flag is true, the SACL has been retrieved by some default mechanism. If false, the SACL has been explicitly specified by a user. The method stores this value in the SE_SACL_DEFAULTED flag of the SECURITY_DESCRIPTOR_CONTROL structure. If this parameter is not specified, the SE_SACL_DEFAULTED flag is cleared.
Return Value
Returns true on success, false on failure.
CSecurityDesc::ToString
Converts a security descriptor to a string format.
bool ToString(
CString* pstr, SECURITY_INFORMATION si = OWNER_SECURITY_INFORMATION |
GROUP_SECURITY_INFORMATION | DACL_SECURITY_INFORMATION |
SACL_SECURITY_INFORMATION) const throw(...);
Parameters
pstr
Pointer to a null-terminated string which will receive the string-format security descriptor.
si
Specifies a combination of SECURITY_INFORMATION bit flags to indicate the components of the security descriptor to include in the output string.
Return Value
Returns true on success, false on failure.
Remarks
Once the security descriptor is in string format, it can more easily be stored or transmitted. Use the CSecurityDesc::FromString method to convert the string back into a security descriptor.
The si parameter can contain the following SECURITY_INFORMATION flags:
| Value | Meaning |
|---|---|
| OWNER_SECURITY_INFORMATION | Include the owner. |
| GROUP_SECURITY_INFORMATION | Include the primary group. |
| DACL_SECURITY_INFORMATION | Include the DACL. |
| SACL_SECURITY_INFORMATION | Include the SACL. |
If the DACL is NULL and the SE_DACL_PRESENT control bit is set in the input security descriptor, the method fails.
If the DACL is NULL and the SE_DACL_PRESENT control bit is not set in the input security descriptor, the resulting security descriptor string does not have a D: component. See Security Descriptor String Format for more details.
This method calls ConvertStringSecurityDescriptorToSecurityDescriptor.
See also
Security Sample
SECURITY_DESCRIPTOR
Class Overview
Security Global Functions
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for