Expand description
Safe borrowed and owned wrappers for Windows security identifiers (SIDs).
A SID identifies a user, group, logon session, or other security principal. This crate represents one with the same in-memory layout used by Windows:
SidBuf dereferences to Sid, and both types implement equality, ordering,
hashing, and formatting. This makes owned SIDs suitable as map and set keys
while still allowing lookup with a borrowed &Sid.
§Creating SIDs
Build a SID from its six-byte identifier authority and its sub-authorities:
use safe_sid::SidBuf;
// S-1-5-32-544 is the BUILTIN\Administrators SID.
let administrators = SidBuf::new([0, 0, 0, 0, 0, 5], &[32, 544])?;
assert_eq!(administrators.to_string(), "S-1-5-32-544");Or ask Windows to create a well-known SID:
use safe_sid::{SidBuf, WinLocalSystemSid};
let local_system = SidBuf::well_known(WinLocalSystemSid, None)?;
assert_eq!(local_system.to_string(), "S-1-5-18");Numeric SID strings can be parsed without calling Windows:
use safe_sid::SidBuf;
let sid: SidBuf = "S-1-5-18".parse()?;
assert_eq!(sid.authority(), 5);
assert_eq!(sid.sub_authorities(), [18]);SidBuf::from_cstr_with_alias additionally accepts Windows aliases such
as BA (BUILTIN\Administrators).
§Windows API interoperability
The default feature set has no dependency on the full windows crate.
Sid::as_ptr and Sid::from_psid use raw c_void pointers in that
configuration.
Enable the windows-full feature to also accept and return
windows::Win32::Security::PSID
values directly:
[dependencies]
safe-sid = { version = "0.1", features = ["windows-full"] }
windows = { version = "0.62", features = ["Win32_Security"] }A borrowed SID can be passed to an API for the duration of the call:
use safe_sid::SidBuf;
use windows::Win32::Security::GetLengthSid;
let sid: SidBuf = "S-1-5-18".parse().unwrap();
// The API must not retain or mutate the borrowed pointer.
let byte_len = unsafe { GetLengthSid(sid.as_psid()) };
assert_eq!(byte_len as usize, sid.as_bytes().len());Use SidBuf::with_capacity and SidBuf::as_mut_ptr for APIs that fill
a caller-supplied SID buffer. The usual Windows two-call pattern is:
- Call the API with no buffer to obtain the required byte count.
- Allocate that many bytes with
SidBuf::with_capacity. - Pass
SidBuf::as_mut_ptrto the API. - Read the buffer only after the API has successfully written a valid SID.
See SidBuf::as_mut_ptr for a complete buffer-filling example.
Re-exports§
pub use well_known::*;
Modules§
- well_
known - Constants for the SID types accepted by
SidBuf::well_knownandSid::is_well_known.
Structs§
- Parse
Error - The error returned when a string is not a valid numeric SID.
- Sid
- A borrowed SID.
- SidBuf
- An owned copy of a SID’s bytes.
Traits§
- AsSid
Ptr - Converts a supported pointer wrapper to the raw pointer used by SID APIs.
- AsWell
Known SidType - Converts a well-known SID type to the value expected by Windows.