Skip to main content

landlock/
access.rs

1// SPDX-License-Identifier: Apache-2.0 OR MIT
2
3use crate::{
4    private, AccessError, AddRuleError, AddRulesError, BitFlags, CompatError, CompatResult,
5    Compatibility, HandleAccessError, HandleAccessesError, Ruleset, RulesetCreated,
6    TailoredCompatLevel, TryCompat, ABI,
7};
8use enumflags2::BitFlag;
9use std::marker::PhantomData;
10
11#[cfg(test)]
12use crate::{make_bitflags, AccessFs, CompatLevel, CompatState};
13
14pub trait Access: BitFlag + private::Sealed {
15    /// Gets the access rights defined by a specific [`ABI`].
16    fn from_all(abi: ABI) -> BitFlags<Self>;
17}
18
19// This HandledAccess trait is useful to document the API.
20pub trait HandledAccess: Access {}
21
22#[derive(Clone, Copy, Debug, Eq, PartialEq)]
23pub(crate) enum Requested {}
24
25#[derive(Clone, Copy, Debug, Eq, PartialEq)]
26pub(crate) enum Effective {}
27
28/// Requested or ABI-resolved ruleset attribute masks for one
29/// [`Access`] category.
30#[derive(Clone, Copy, Debug, Eq, PartialEq)]
31pub(crate) struct RulesetMasks<A, S>
32where
33    A: Access,
34{
35    /// The handled access mask, or the scoped mask when `A` is
36    /// [`Scope`](crate::Scope).
37    pub(crate) access: BitFlags<A>,
38    pub(crate) quiet: BitFlags<A>,
39    _state: PhantomData<S>,
40}
41
42impl<A> Default for RulesetMasks<A, Requested>
43where
44    A: Access,
45{
46    fn default() -> Self {
47        // Ruleset masks must start empty independently of BitFlags' customizable default.
48        Self {
49            access: BitFlags::EMPTY,
50            quiet: BitFlags::EMPTY,
51            _state: PhantomData,
52        }
53    }
54}
55
56impl<A> RulesetMasks<A, Requested>
57where
58    A: Access,
59{
60    const QUIET_SINCE: ABI = ABI::V10;
61
62    pub(crate) fn supports_quiet(abi: ABI) -> bool {
63        abi >= Self::QUIET_SINCE
64    }
65
66    pub(crate) fn request(
67        &mut self,
68        access: BitFlags<A>,
69        compat: &mut Compatibility,
70    ) -> Result<(), CompatError<A>> {
71        self.access |= access;
72        // Keep this call for validation, compatibility-state transitions, and errors.
73        // Its filtered mask is redundant: resolve() derives it from the ruleset mask and ABI.
74        let _ = access.try_compat(compat.abi(), compat.level, &mut compat.state)?;
75        Ok(())
76    }
77
78    pub(crate) fn request_quiet(
79        &mut self,
80        access: BitFlags<A>,
81        compat: &mut Compatibility,
82    ) -> Result<(), CompatError<A>> {
83        self.quiet |= access;
84        // Keep both checks for their compatibility-state transitions and errors.
85        let _ = access.try_compat(compat.abi(), compat.level, &mut compat.state)?;
86        let _ = compat.try_compat_binary(Self::supports_quiet(compat.abi()), || {
87            CompatError::<A>::QuietNotSupported
88        })?;
89        Ok(())
90    }
91
92    pub(crate) fn resolve(self, abi: ABI) -> RulesetMasks<A, Effective> {
93        let effective_access = self.access & A::from_all(abi);
94        RulesetMasks {
95            access: effective_access,
96            quiet: if Self::supports_quiet(abi) {
97                self.quiet & effective_access
98            } else {
99                BitFlags::EMPTY
100            },
101            _state: PhantomData,
102        }
103    }
104
105    pub(crate) fn incompatible_quiet(self) -> BitFlags<A> {
106        self.quiet & !self.access
107    }
108}
109
110#[test]
111fn ruleset_masks_resolve() {
112    let supports_quiet = RulesetMasks::<AccessFs, Requested>::supports_quiet;
113    assert!(!supports_quiet(ABI::V9));
114    assert!(supports_quiet(ABI::V10));
115
116    let requested_masks = RulesetMasks::<_, Requested> {
117        access: make_bitflags!(AccessFs::{Execute | Refer}),
118        quiet: AccessFs::Execute.into(),
119        _state: PhantomData,
120    };
121    for (abi, expected_access, expected_quiet) in [
122        (ABI::Unsupported, BitFlags::EMPTY, BitFlags::EMPTY),
123        (ABI::V1, AccessFs::Execute.into(), BitFlags::EMPTY),
124        (
125            ABI::V2,
126            make_bitflags!(AccessFs::{Execute | Refer}),
127            BitFlags::EMPTY,
128        ),
129        (
130            ABI::V9,
131            make_bitflags!(AccessFs::{Execute | Refer}),
132            BitFlags::EMPTY,
133        ),
134        (
135            ABI::V10,
136            make_bitflags!(AccessFs::{Execute | Refer}),
137            AccessFs::Execute.into(),
138        ),
139    ] {
140        assert_eq!(
141            requested_masks.resolve(abi),
142            RulesetMasks::<_, Effective> {
143                access: expected_access,
144                quiet: expected_quiet,
145                _state: PhantomData,
146            }
147        );
148    }
149}
150
151pub trait PrivateHandledAccess: HandledAccess {
152    fn ruleset_handle_access(
153        ruleset: &mut Ruleset,
154        access: BitFlags<Self>,
155    ) -> Result<(), HandleAccessesError>
156    where
157        Self: Access;
158
159    fn ruleset_quiet_access(
160        ruleset: &mut Ruleset,
161        access: BitFlags<Self>,
162    ) -> Result<(), HandleAccessesError>
163    where
164        Self: Access;
165
166    fn ruleset_has_effective_quiet_access(ruleset: &RulesetCreated, abi: ABI) -> bool;
167
168    fn into_add_rules_error(error: AddRuleError<Self>) -> AddRulesError
169    where
170        Self: Access;
171
172    fn into_handle_accesses_error(error: HandleAccessError<Self>) -> HandleAccessesError
173    where
174        Self: Access;
175}
176
177// Creates an illegal/overflowed BitFlags<T> with all its bits toggled, including undefined ones.
178fn full_negation<T>(flags: BitFlags<T>) -> BitFlags<T>
179where
180    T: Access,
181{
182    unsafe { BitFlags::<T>::from_bits_unchecked(!flags.bits()) }
183}
184
185#[test]
186fn bit_flags_full_negation() {
187    let scoped_negation = !BitFlags::<AccessFs>::all();
188    assert_eq!(scoped_negation, BitFlags::<AccessFs>::empty());
189    // !BitFlags::<AccessFs>::all() could be equal to full_negation(BitFlags::<AccessFs>::all()))
190    // if all the 64-bits would be used, which is not currently the case.
191    assert_ne!(scoped_negation, full_negation(BitFlags::<AccessFs>::all()));
192}
193
194impl<A> TailoredCompatLevel for BitFlags<A> where A: Access {}
195
196impl<A> TryCompat<A> for BitFlags<A>
197where
198    A: Access,
199{
200    fn try_compat_inner(&mut self, abi: ABI) -> Result<CompatResult<A>, CompatError<A>> {
201        if self.is_empty() {
202            // Empty access-rights would result to a runtime error.
203            Err(AccessError::Empty.into())
204        } else if !Self::all().contains(*self) {
205            // Unknown access-rights (at build time) would result to a runtime error.
206            // This can only be reached by using the unsafe BitFlags::from_bits_unchecked().
207            Err(AccessError::Unknown {
208                access: *self,
209                unknown: *self & full_negation(Self::all()),
210            }
211            .into())
212        } else {
213            let compat = *self & A::from_all(abi);
214            let ret = if compat.is_empty() {
215                Ok(CompatResult::No(
216                    AccessError::Incompatible { access: *self }.into(),
217                ))
218            } else if compat != *self {
219                let error = AccessError::PartiallyCompatible {
220                    access: *self,
221                    incompatible: *self & full_negation(compat),
222                }
223                .into();
224                Ok(CompatResult::Partial(error))
225            } else {
226                Ok(CompatResult::Full)
227            };
228            *self = compat;
229            ret
230        }
231    }
232}
233
234#[test]
235fn compat_bit_flags() {
236    use crate::ABI;
237
238    let mut compat: Compatibility = ABI::V1.into();
239    assert!(compat.state == CompatState::Init);
240
241    let ro_access = make_bitflags!(AccessFs::{Execute | ReadFile | ReadDir});
242    assert_eq!(
243        ro_access,
244        ro_access
245            .try_compat(compat.abi(), compat.level, &mut compat.state)
246            .unwrap()
247            .unwrap()
248    );
249    assert!(compat.state == CompatState::Full);
250
251    let empty_access = BitFlags::<AccessFs>::empty();
252    assert!(matches!(
253        empty_access
254            .try_compat(compat.abi(), compat.level, &mut compat.state)
255            .unwrap_err(),
256        CompatError::Access(AccessError::Empty)
257    ));
258
259    let all_unknown_access = unsafe { BitFlags::<AccessFs>::from_bits_unchecked(1 << 63) };
260    assert!(matches!(
261        all_unknown_access.try_compat(compat.abi(), compat.level, &mut compat.state).unwrap_err(),
262        CompatError::Access(AccessError::Unknown { access, unknown }) if access == all_unknown_access && unknown == all_unknown_access
263    ));
264    // An error makes the state final.
265    assert!(compat.state == CompatState::Dummy);
266
267    let some_unknown_access = unsafe { BitFlags::<AccessFs>::from_bits_unchecked((1 << 63) | 1) };
268    assert!(matches!(
269        some_unknown_access.try_compat(compat.abi(), compat.level, &mut compat.state).unwrap_err(),
270        CompatError::Access(AccessError::Unknown { access, unknown }) if access == some_unknown_access && unknown == all_unknown_access
271    ));
272    assert!(compat.state == CompatState::Dummy);
273
274    compat = ABI::Unsupported.into();
275
276    // Tests that the ruleset is marked as unsupported.
277    assert!(compat.state == CompatState::Init);
278
279    // Access-rights are valid (but ignored) when they are not required for the current ABI.
280    assert_eq!(
281        None,
282        ro_access
283            .try_compat(compat.abi(), compat.level, &mut compat.state)
284            .unwrap()
285    );
286
287    assert!(compat.state == CompatState::No);
288
289    // Access-rights are not valid when they are required for the current ABI.
290    compat.level = Some(CompatLevel::HardRequirement);
291    assert!(matches!(
292        ro_access.try_compat(compat.abi(), compat.level, &mut compat.state).unwrap_err(),
293        CompatError::Access(AccessError::Incompatible { access }) if access == ro_access
294    ));
295
296    compat = ABI::V1.into();
297
298    // Tests that the ruleset is marked as the unknown compatibility state.
299    assert!(compat.state == CompatState::Init);
300
301    // Access-rights are valid (but ignored) when they are not required for the current ABI.
302    assert_eq!(
303        ro_access,
304        ro_access
305            .try_compat(compat.abi(), compat.level, &mut compat.state)
306            .unwrap()
307            .unwrap()
308    );
309
310    // Tests that the ruleset is in an unsupported state, which is important to be able to still
311    // enforce no_new_privs.
312    assert!(compat.state == CompatState::Full);
313
314    let v2_access = ro_access | AccessFs::Refer;
315
316    // Access-rights are not valid when they are required for the current ABI.
317    compat.level = Some(CompatLevel::HardRequirement);
318    assert!(matches!(
319        v2_access.try_compat(compat.abi(), compat.level, &mut compat.state).unwrap_err(),
320        CompatError::Access(AccessError::PartiallyCompatible { access, incompatible })
321            if access == v2_access && incompatible == AccessFs::Refer
322    ));
323}