Struct SecurityDescriptor

Source

pub struct SecurityDescriptor { /* private fields */ }

Expand description

An owned, self-relative copy of a caller’s security descriptor.

Whatever form the caller supplied, this holds the self-relative form in one contiguous, DWORD-aligned blob, so it names nothing outside itself and can be carried to another thread.

Implementations§

Source §

impl SecurityDescriptor

Source

pub fn from_sddl(sddl: &Wtf16String) -> Result<Self, SecurityCaptureError>

A descriptor from its SDDL text, such as D:P(A;;FA;;;WD).

The result is the self-relative form this type always holds, copied out of the memory Windows allocated for it, which is then freed.

The string is not interpreted here: Windows parses it, accepts what it defines and refuses the rest, and a string with no parts, such as an empty one, is its to answer. A string with an interior NUL is refused before the call, because Windows would read only up to it and build a different descriptor than the string says.

§Example

A DACL granting everyone full access, read back through the descriptor:

use win_authorization_sys::{AclState, SecurityDescriptor};
use wtf_string::Wtf16String;

let descriptor = SecurityDescriptor::from_sddl(&Wtf16String::from("D:P(A;;GA;;;WD)"))?;
assert_eq!(descriptor.dacl()?, AclState::Populated(1));

§Errors

SecurityCaptureFailure::InvalidSddl with Windows’ own code, unaltered, when it refuses the string; SecurityCaptureFailure::InteriorNul for a string with an interior NUL; or the failures of capturing the descriptor Windows returned, including SecurityCaptureFailure::Allocate when the memory for the copy cannot be allocated.

Source

pub fn to_sddl( &self, information: SecurityInformation, ) -> Result<Wtf16String, SecurityCaptureError>

The descriptor’s parts selected by information, as SDDL text.

Windows’ rendering of the descriptor, which is not necessarily the string it was built from: the text form is not canonical.

§Example

use win_authorization_sys::{SecurityDescriptor, SecurityInformation};
use wtf_string::Wtf16String;

let descriptor = SecurityDescriptor::from_sddl(&Wtf16String::from("D:P(A;;GA;;;WD)"))?;
let text = descriptor.to_sddl(SecurityInformation::DACL)?;
assert_eq!(text.to_string_lossy(), "D:P(A;;GA;;;WD)");

The length Windows reports for the text is not used. It is documented to count the terminator, and was measured to be the string’s length plus one, plus two, and plus none, depending on the string; the text is read up to the terminator the documentation promises.

§Errors

SecurityCaptureFailure::ToSddl with Windows’ own code, unaltered, when it refuses.

Source §

impl SecurityDescriptor

Source

pub fn try_clone(&self) -> Result<Self, SecurityCaptureError>

Copies the descriptor.

Not Clone, because the copy allocates and the allocation can fail.

§Errors

Returns SecurityCaptureFailure::Allocate when the memory for the copy cannot be allocated.

Source

pub unsafe fn capture( descriptor: *const c_void, ) -> Result<Self, SecurityCaptureError>

Captures the descriptor at descriptor.

An absolute descriptor is converted to self-relative form. A self-relative one is taken apart and built again, not copied byte for byte: its parts are found by their offsets, and two may share a SID or have space between them, so no one span of bytes is the descriptor. Either way the result owns every byte it refers to.

§Errors

Returns a SecurityCaptureError when Windows rejects the descriptor as malformed, when the conversion fails, or, as SecurityCaptureFailure::Allocate, when the memory for the copy cannot be allocated.

§Safety

descriptor must be non-null and point to a security descriptor that stays valid for the duration of this call, including everything an absolute descriptor points at.

Source