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 identifier authority and its sub-authorities. The
authority can be one of the constants in authority, its raw six-byte
form, or a plain integer:
use safe_sid::SidBuf;
use safe_sid::authority::SECURITY_NT_AUTHORITY;
// S-1-5-32-544 is the BUILTIN\Administrators SID.
let administrators = SidBuf::new(SECURITY_NT_AUTHORITY, &[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;
use safe_sid::well_known::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_string_sid additionally accepts Windows aliases such
as BA (BUILTIN\Administrators).
§Windows API interoperability
This crate does not depend on the windows crate. Sid::as_ptr and
Sid::from_psid use raw c_void pointers so applications can choose
their own Windows bindings and versions.
A borrowed SID can be passed to an API for the duration of the call:
use safe_sid::SidBuf;
use windows::Win32::Security::{GetLengthSid, PSID};
let sid: SidBuf = "S-1-5-18".parse().unwrap();
// The API must not retain or mutate the borrowed pointer.
let byte_len = unsafe { GetLengthSid(PSID(sid.as_ptr().cast_mut())) };
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.
Modules§
- authority
- Constants for the identifier authorities defined by Windows, for use with
SidBuf::new. - well_
known - Constants for the SID types accepted by
SidBuf::well_knownandSid::is_well_known.
Structs§
- Sid
- A borrowed SID.
- SidBuf
- An owned copy of a SID’s bytes.
- SidParse
Error - The error returned when a string is not a valid SID.
- Well
Known SidType - A Windows well-known SID type.
Enums§
- Error
- An error reported while creating, validating, or querying a SID.
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.
- Into
Authority - Converts a value into a SID’s six-byte identifier authority.
Type Aliases§
- Result
- A result returned by fallible
safe-sidoperations.