win-custody 0.1.6

Take custody of Windows child processes: exact handle inheritance, kill-on-close jobs, launches into another session's token, SDDL-secured pipes, and opt-in AppContainer confinement.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
//! SIDs and DACLs as validated byte structures.
#![allow(unsafe_code)]

use std::ffi::c_void;
use std::fmt;
use std::io;
use std::mem::{offset_of, size_of};
use std::ptr::{self, NonNull};

use windows_sys::Win32::Foundation::LocalFree;
use windows_sys::Win32::Security::Authorization::ConvertStringSidToSidW;
use windows_sys::Win32::Security::{
    GetLengthSid, IsValidSid, ACCESS_ALLOWED_ACE, ACE_HEADER, ACL, PSID,
};

use crate::wide::wide_null;

const ACCESS_ALLOWED_ACE_KIND: u8 = 0;
const SID_FIXED_BYTES: usize = 8;
const SID_SUB_AUTHORITY_BYTES: usize = size_of::<u32>();
const ACE_HEADER_BYTES: usize = size_of::<ACE_HEADER>();
const ACL_HEADER_BYTES: usize = size_of::<ACL>();
const ACCESS_ALLOWED_SID_OFFSET: usize = offset_of!(ACCESS_ALLOWED_ACE, SidStart);

/// Why a descriptor's bytes did not form the structure Windows claims.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum AclValidationError {
    /// A pointer Windows returned lies outside the descriptor block.
    DescriptorRange,
    /// The descriptor has no DACL.
    MissingDacl,
    /// The descriptor has no owner.
    MissingOwner,
    /// The ACL is shorter than its header.
    AclTooShort,
    /// The ACL's declared size is smaller than its header or larger than the
    /// bytes available.
    InvalidAclSize,
    /// An ACE header runs past the end of the ACL.
    TruncatedAceHeader,
    /// An ACE declares a size that is too small or not a multiple of four.
    InvalidAceSize,
    /// An ACE runs past the end of the ACL.
    AceOutOfRange,
    /// An ACE is not an `ACCESS_ALLOWED_ACE`. Deny and audit entries are
    /// rejected so a policy check cannot overlook them.
    UnsupportedAceType,
    /// A SID runs past the end of its container.
    TruncatedSid,
    /// Windows rejected a SID's structure.
    InvalidSid,
}

impl fmt::Display for AclValidationError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        let message = match self {
            Self::DescriptorRange => "a descriptor pointer lies outside the descriptor",
            Self::MissingDacl => "the descriptor has no DACL",
            Self::MissingOwner => "the descriptor has no owner",
            Self::AclTooShort => "the ACL is shorter than its header",
            Self::InvalidAclSize => "the ACL size is out of range",
            Self::TruncatedAceHeader => "an ACE header is truncated",
            Self::InvalidAceSize => "an ACE size is invalid",
            Self::AceOutOfRange => "an ACE runs past the end of the ACL",
            Self::UnsupportedAceType => "the ACL contains an ACE that is not access-allowed",
            Self::TruncatedSid => "a SID is truncated",
            Self::InvalidSid => "a SID is invalid",
        };
        formatter.write_str(message)
    }
}

impl std::error::Error for AclValidationError {}

/// A failure while reading part of a security descriptor.
#[derive(Debug)]
#[non_exhaustive]
pub enum SecurityAclError {
    /// The Win32 call failed.
    Io(io::Error),
    /// The bytes Windows returned did not validate.
    Invalid(AclValidationError),
}

impl fmt::Display for SecurityAclError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Io(error) => error.fmt(formatter),
            Self::Invalid(error) => error.fmt(formatter),
        }
    }
}

impl std::error::Error for SecurityAclError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::Io(error) => Some(error),
            Self::Invalid(error) => Some(error),
        }
    }
}

impl From<io::Error> for SecurityAclError {
    fn from(value: io::Error) -> Self {
        Self::Io(value)
    }
}

impl From<AclValidationError> for SecurityAclError {
    fn from(value: AclValidationError) -> Self {
        Self::Invalid(value)
    }
}

/// A SID converted from its string form, kept both as the Windows allocation
/// (for APIs that need a pointer) and as validated bytes (for comparison).
#[derive(Debug)]
pub struct OwnedSid {
    raw: NonNull<c_void>,
    bytes: Vec<u8>,
}

impl OwnedSid {
    /// Converts a SID in string form, such as `S-1-5-18` or the SDDL alias
    /// `SY`.
    pub fn from_string(value: &str) -> io::Result<Self> {
        let value = wide_null(value)?;
        let mut sid = ptr::null_mut();
        // SAFETY: the SDDL string is NUL-terminated and `sid` is a live out
        // pointer; on success the LocalAlloc block is owned below.
        if unsafe { ConvertStringSidToSidW(value.as_ptr(), &mut sid) } == 0 || sid.is_null() {
            return Err(io::Error::last_os_error());
        }
        let raw = NonNull::new(sid).expect("checked non-null SID");
        let free = |raw: NonNull<c_void>| {
            // SAFETY: the failed validation path still uniquely owns the block.
            unsafe { LocalFree(raw.as_ptr()) };
        };
        // SAFETY: `raw` was just returned by the converter.
        if unsafe { IsValidSid(raw.as_ptr()) } == 0 {
            free(raw);
            return Err(invalid_data("Windows returned an invalid converted SID"));
        }
        // SAFETY: IsValidSid accepted this block.
        let length = unsafe { GetLengthSid(raw.as_ptr()) } as usize;
        if length < SID_FIXED_BYTES {
            free(raw);
            return Err(invalid_data("Windows returned a truncated converted SID"));
        }
        // SAFETY: GetLengthSid reported the initialized length of this block.
        let bytes =
            unsafe { std::slice::from_raw_parts(raw.as_ptr().cast::<u8>(), length) }.to_vec();
        Ok(Self { raw, bytes })
    }

    pub(crate) fn as_ptr(&self) -> PSID {
        self.raw.as_ptr()
    }
}

impl Drop for OwnedSid {
    fn drop(&mut self) {
        // SAFETY: this value uniquely owns the converter's LocalAlloc block.
        unsafe { LocalFree(self.raw.as_ptr()) };
    }
}

/// A SID copied out of a descriptor after its structure was verified.
#[derive(Debug)]
pub struct ValidatedSid {
    bytes: Vec<u8>,
}

impl ValidatedSid {
    pub(crate) fn from_bounded_bytes(bytes: &[u8]) -> Result<Self, AclValidationError> {
        if bytes.len() < SID_FIXED_BYTES {
            return Err(AclValidationError::TruncatedSid);
        }
        let sub_authorities = usize::from(bytes[1]);
        let length = sub_authorities
            .checked_mul(SID_SUB_AUTHORITY_BYTES)
            .and_then(|tail| SID_FIXED_BYTES.checked_add(tail))
            .ok_or(AclValidationError::TruncatedSid)?;
        if length > bytes.len() {
            return Err(AclValidationError::TruncatedSid);
        }
        // Windows SID routines expect an aligned SID. Copying the bounded
        // bytes into u32 storage keeps that invariant local to this function.
        let mut aligned = vec![0_u32; length.div_ceil(size_of::<u32>())];
        // SAFETY: the byte view covers exactly the initialized u32 allocation,
        // does not outlive `aligned`, and keeps its four-byte alignment.
        let aligned_bytes = unsafe {
            std::slice::from_raw_parts_mut(
                aligned.as_mut_ptr().cast::<u8>(),
                aligned.len() * size_of::<u32>(),
            )
        };
        aligned_bytes[..length].copy_from_slice(&bytes[..length]);
        let sid = aligned.as_mut_ptr().cast::<c_void>();
        // SAFETY: the structural check above proved every sub-authority byte
        // is present in this aligned allocation.
        if unsafe { IsValidSid(sid) } == 0 {
            return Err(AclValidationError::InvalidSid);
        }
        // SAFETY: IsValidSid accepted the bounded, aligned SID.
        let windows_length = unsafe { GetLengthSid(sid) } as usize;
        if windows_length != length {
            return Err(AclValidationError::InvalidSid);
        }
        Ok(Self {
            bytes: bytes[..length].to_vec(),
        })
    }

    /// Whether this SID is byte-for-byte the same as `expected`.
    pub fn matches(&self, expected: &OwnedSid) -> bool {
        self.bytes == expected.bytes
    }
}

/// One `ACCESS_ALLOWED_ACE`, reduced to the fields policy checks read.
#[derive(Debug)]
pub struct AllowedAce {
    flags: u8,
    mask: u32,
    trustee: ValidatedSid,
}

impl AllowedAce {
    /// The ACE flags, such as `OBJECT_INHERIT_ACE` and `INHERITED_ACE`.
    pub const fn flags(&self) -> u8 {
        self.flags
    }

    /// The access mask the ACE grants.
    pub const fn mask(&self) -> u32 {
        self.mask
    }

    /// Whether the ACE grants its rights to `expected`.
    pub fn trustee_matches(&self, expected: &OwnedSid) -> bool {
        self.trustee.matches(expected)
    }
}

/// A DACL whose every ACE was an in-bounds `ACCESS_ALLOWED_ACE` with a
/// well-formed SID. Any other ACE type fails validation, so a policy that
/// iterates this list has already excluded deny and audit entries.
#[derive(Debug)]
pub struct ValidatedDacl {
    allowed_aces: Vec<AllowedAce>,
}

impl ValidatedDacl {
    pub(crate) fn from_bytes(bytes: &[u8]) -> Result<Self, AclValidationError> {
        if bytes.len() < ACL_HEADER_BYTES {
            return Err(AclValidationError::AclTooShort);
        }
        let acl_size = usize::from(u16::from_le_bytes([bytes[2], bytes[3]]));
        if acl_size < ACL_HEADER_BYTES || acl_size > bytes.len() {
            return Err(AclValidationError::InvalidAclSize);
        }
        let ace_count = usize::from(u16::from_le_bytes([bytes[4], bytes[5]]));
        let bytes = &bytes[..acl_size];
        if ace_count > (bytes.len() - ACL_HEADER_BYTES) / ACE_HEADER_BYTES {
            return Err(AclValidationError::TruncatedAceHeader);
        }
        let mut offset = ACL_HEADER_BYTES;
        let mut allowed_aces = Vec::with_capacity(ace_count);
        for _ in 0..ace_count {
            let header_end = offset
                .checked_add(ACE_HEADER_BYTES)
                .filter(|end| *end <= bytes.len())
                .ok_or(AclValidationError::TruncatedAceHeader)?;
            let ace_type = bytes[offset];
            let flags = bytes[offset + 1];
            let ace_size = usize::from(u16::from_le_bytes([bytes[offset + 2], bytes[offset + 3]]));
            if ace_size < ACE_HEADER_BYTES || ace_size % size_of::<u32>() != 0 {
                return Err(AclValidationError::InvalidAceSize);
            }
            let ace_end = offset
                .checked_add(ace_size)
                .filter(|end| *end <= bytes.len())
                .ok_or(AclValidationError::AceOutOfRange)?;
            debug_assert!(header_end <= ace_end);
            if ace_type != ACCESS_ALLOWED_ACE_KIND {
                return Err(AclValidationError::UnsupportedAceType);
            }
            if ace_size < ACCESS_ALLOWED_SID_OFFSET + SID_FIXED_BYTES {
                return Err(AclValidationError::InvalidAceSize);
            }
            let mask_offset = offset + offset_of!(ACCESS_ALLOWED_ACE, Mask);
            let mask = u32::from_le_bytes(
                bytes[mask_offset..mask_offset + size_of::<u32>()]
                    .try_into()
                    .expect("validated access mask range"),
            );
            let trustee = ValidatedSid::from_bounded_bytes(
                &bytes[offset + ACCESS_ALLOWED_SID_OFFSET..ace_end],
            )?;
            allowed_aces.push(AllowedAce {
                flags,
                mask,
                trustee,
            });
            offset = ace_end;
        }
        Ok(Self { allowed_aces })
    }

    /// The number of ACEs.
    pub fn len(&self) -> usize {
        self.allowed_aces.len()
    }

    /// Whether the DACL has no ACEs, which denies everyone.
    pub fn is_empty(&self) -> bool {
        self.allowed_aces.is_empty()
    }

    /// The ACEs in order.
    pub fn allowed_aces(&self) -> impl Iterator<Item = &AllowedAce> {
        self.allowed_aces.iter()
    }
}

fn invalid_data(message: &str) -> io::Error {
    io::Error::new(io::ErrorKind::InvalidData, message)
}

#[cfg(test)]
mod tests {
    use super::{AclValidationError, OwnedSid, ValidatedDacl};

    const SYSTEM_SID_BYTES: [u8; 12] = [1, 1, 0, 0, 0, 0, 0, 5, 18, 0, 0, 0];

    fn valid_acl() -> Vec<u8> {
        let ace_size = 8 + SYSTEM_SID_BYTES.len();
        let acl_size = 8 + ace_size;
        let mut acl = vec![0_u8; acl_size];
        acl[0] = 2;
        acl[2..4].copy_from_slice(&(acl_size as u16).to_le_bytes());
        acl[4..6].copy_from_slice(&1_u16.to_le_bytes());
        acl[9] = 0x10;
        acl[10..12].copy_from_slice(&(ace_size as u16).to_le_bytes());
        acl[12..16].copy_from_slice(&0x001f_0001_u32.to_le_bytes());
        acl[16..].copy_from_slice(&SYSTEM_SID_BYTES);
        acl
    }

    #[test]
    fn a_valid_allowed_ace_exposes_only_validated_fields() {
        let dacl = ValidatedDacl::from_bytes(&valid_acl()).unwrap();
        let system = OwnedSid::from_string("S-1-5-18").unwrap();
        let ace = dacl.allowed_aces().next().unwrap();
        assert_eq!(dacl.len(), 1);
        assert_eq!(ace.flags(), 0x10);
        assert_eq!(ace.mask(), 0x001f_0001);
        assert!(ace.trustee_matches(&system));
    }

    #[test]
    fn malformed_acls_are_rejected_at_the_first_inconsistent_field() {
        assert_eq!(
            ValidatedDacl::from_bytes(&[0; 7]).unwrap_err(),
            AclValidationError::AclTooShort
        );
        let mut undersized = valid_acl();
        undersized[2..4].copy_from_slice(&7_u16.to_le_bytes());
        assert_eq!(
            ValidatedDacl::from_bytes(&undersized).unwrap_err(),
            AclValidationError::InvalidAclSize
        );
        let mut short_ace = valid_acl();
        short_ace[10..12].copy_from_slice(&12_u16.to_le_bytes());
        assert_eq!(
            ValidatedDacl::from_bytes(&short_ace).unwrap_err(),
            AclValidationError::InvalidAceSize
        );
        let mut long_ace = valid_acl();
        let ace_size = long_ace.len() as u16;
        long_ace[10..12].copy_from_slice(&ace_size.to_le_bytes());
        assert_eq!(
            ValidatedDacl::from_bytes(&long_ace).unwrap_err(),
            AclValidationError::AceOutOfRange
        );
        let mut truncated_sid = valid_acl();
        truncated_sid[10..12].copy_from_slice(&16_u16.to_le_bytes());
        assert_eq!(
            ValidatedDacl::from_bytes(&truncated_sid).unwrap_err(),
            AclValidationError::TruncatedSid
        );
        let mut invalid_sid = valid_acl();
        invalid_sid[16] = 0;
        assert_eq!(
            ValidatedDacl::from_bytes(&invalid_sid).unwrap_err(),
            AclValidationError::InvalidSid
        );
        let mut deny = valid_acl();
        deny[8] = 1;
        assert_eq!(
            ValidatedDacl::from_bytes(&deny).unwrap_err(),
            AclValidationError::UnsupportedAceType
        );
    }
}