Function get_security_info 

pub fn get_security_info(
    handle: BorrowedHandle<'_>,
    object_type: ObjectType,
    information: SecurityInformation,
) -> Result<SecurityDescriptor, SecurityCaptureError>

The parts information selects of the security descriptor of the object handle names, as an owned SecurityDescriptor: GetSecurityInfo, for the kinds that read any handle.

GetSecurityInfo reads ObjectType as the kind of the object the handle names, and a BorrowedHandle says nothing about that kind. So this safe entry passes only the kinds ObjectType::reads_any_handle names – file, kernel object, window object, and UNKNOWN – under which Windows was measured reading whatever handle it is given. Any other kind is refused before the call, as this crate’s own narrowing; a caller who knows the handle names an object of that kind uses get_security_info_unchecked.

What is read is what the handle was opened with the right to read: READ_CONTROL for the owner, the group and the DACL, and ACCESS_SYSTEM_SECURITY for the SACL, which Windows grants only to a caller holding the privilege for it. A part the handle cannot read is Windows’ refusal, with its code, and not an absent part: nothing here retries with less. Windows reads a handle’s security whichever of the file, kernel-object and window kinds is named (measured), so the kind does not make a handle of another kind an error, and an object that has no descriptor reads as one with no parts. A part that was not selected is absent from the result, and one that was and the object does not have reads as an absent list (AclState::Absent).

Example

The DACL a file was created with, read back through an open handle:

use std::fs::File;
use std::os::windows::io::AsHandle;

use win_authorization_sys::{get_security_info, AclState, ObjectType, SecurityInformation};

let path = std::env::temp_dir().join(format!("wa-doc-{}.tmp", std::process::id()));
let file = File::create(&path)?;

let descriptor = get_security_info(file.as_handle(), ObjectType::FILE, SecurityInformation::DACL)?;
assert!(matches!(descriptor.dacl()?, AclState::Populated(_)));

Errors

SecurityCaptureFailure::UnsupportedObjectType for a kind ObjectType::reads_any_handle does not name, before any call is made, with ERROR_INVALID_PARAMETER, which this crate supplies. SecurityCaptureFailure::ReadSecurity with Windows’ own code, unaltered, when it refuses the query: ERROR_ACCESS_DENIED for a handle opened without the right to read what was selected, ERROR_INVALID_PARAMETER for ObjectType::UNKNOWN. Otherwise the failures of capturing the descriptor Windows returned, including SecurityCaptureFailure::Allocate when the memory for the copy cannot be allocated.