Struct SecurityDescriptor 

pub struct SecurityDescriptor { /* private fields */ }

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

impl SecurityDescriptor

pub fn from_sddl( sddl: &WtfString<Wtf16>, ) -> Result<SecurityDescriptor, 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.

pub fn to_sddl( &self, information: SecurityInformation, ) -> Result<WtfString<Wtf16>, 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.

impl SecurityDescriptor

pub fn try_clone(&self) -> Result<SecurityDescriptor, 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.

pub unsafe fn capture( descriptor: *const c_void, ) -> Result<SecurityDescriptor, 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.

pub fn as_ptr(&self) -> *const c_void

The captured descriptor’s address, for handing to a Win32 call.

The pointer borrows from this value and must not outlive it.

pub fn len(&self) -> usize

The captured descriptor’s length in bytes.

pub fn is_empty(&self) -> bool

Whether the captured descriptor is empty, which a valid one never is.

pub fn as_bytes(&self) -> &[u8]

The captured descriptor’s bytes.

pub fn dacl(&self) -> Result<AclState, SecurityCaptureError>

What the descriptor says about its discretionary access-control list.

Errors

Returns a SecurityCaptureError if Windows will not report the list, which a descriptor that validated at capture should not do.

pub fn sacl(&self) -> Result<AclState, SecurityCaptureError>

What the descriptor says about its system access-control list.

Errors

As dacl.

Trait Implementations

impl Debug for SecurityDescriptor

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Eq for SecurityDescriptor

impl PartialEq for SecurityDescriptor

fn eq(&self, other: &SecurityDescriptor) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for SecurityDescriptor