Skip to main content

Crate safe_sid

Crate safe_sid 

Source
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:

  • Sid is a dynamically sized, borrowed SID, analogous to str.
  • SidBuf owns a SID, analogous to String.

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:

  1. Call the API with no buffer to obtain the required byte count.
  2. Allocate that many bytes with SidBuf::with_capacity.
  3. Pass SidBuf::as_mut_ptr to the API.
  4. 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_known and Sid::is_well_known.

Structs§

ParseError
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§

AsSidPtr
Converts a supported pointer wrapper to the raw pointer used by SID APIs.
AsWellKnownSidType
Converts a well-known SID type to the value expected by Windows.