kernel/
cred.rs

1// SPDX-License-Identifier: GPL-2.0
2
3// Copyright (C) 2024 Google LLC.
4
5//! Credentials management.
6//!
7//! C header: [`include/linux/cred.h`](srctree/include/linux/cred.h).
8//!
9//! Reference: <https://www.kernel.org/doc/html/latest/security/credentials.html>
10
11use crate::{
12    bindings,
13    task::Kuid,
14    types::{AlwaysRefCounted, Opaque},
15};
16
17/// Wraps the kernel's `struct cred`.
18///
19/// Credentials are used for various security checks in the kernel.
20///
21/// Most fields of credentials are immutable. When things have their credentials changed, that
22/// happens by replacing the credential instead of changing an existing credential. See the [kernel
23/// documentation][ref] for more info on this.
24///
25/// # Invariants
26///
27/// Instances of this type are always ref-counted, that is, a call to `get_cred` ensures that the
28/// allocation remains valid at least until the matching call to `put_cred`.
29///
30/// [ref]: https://www.kernel.org/doc/html/latest/security/credentials.html
31#[repr(transparent)]
32pub struct Credential(Opaque<bindings::cred>);
33
34// SAFETY:
35// - `Credential::dec_ref` can be called from any thread.
36// - It is okay to send ownership of `Credential` across thread boundaries.
37unsafe impl Send for Credential {}
38
39// SAFETY: It's OK to access `Credential` through shared references from other threads because
40// we're either accessing properties that don't change or that are properly synchronised by C code.
41unsafe impl Sync for Credential {}
42
43impl Credential {
44    /// Creates a reference to a [`Credential`] from a valid pointer.
45    ///
46    /// # Safety
47    ///
48    /// The caller must ensure that `ptr` is valid and remains valid for the lifetime of the
49    /// returned [`Credential`] reference.
50    #[inline]
51    pub unsafe fn from_ptr<'a>(ptr: *const bindings::cred) -> &'a Credential {
52        // SAFETY: The safety requirements guarantee the validity of the dereference, while the
53        // `Credential` type being transparent makes the cast ok.
54        unsafe { &*ptr.cast() }
55    }
56
57    /// Get the id for this security context.
58    #[inline]
59    pub fn get_secid(&self) -> u32 {
60        let mut secid = 0;
61        // SAFETY: The invariants of this type ensures that the pointer is valid.
62        unsafe { bindings::security_cred_getsecid(self.0.get(), &mut secid) };
63        secid
64    }
65
66    /// Returns the effective UID of the given credential.
67    #[inline]
68    pub fn euid(&self) -> Kuid {
69        // SAFETY: By the type invariant, we know that `self.0` is valid. Furthermore, the `euid`
70        // field of a credential is never changed after initialization, so there is no potential
71        // for data races.
72        Kuid::from_raw(unsafe { (*self.0.get()).euid })
73    }
74}
75
76// SAFETY: The type invariants guarantee that `Credential` is always ref-counted.
77unsafe impl AlwaysRefCounted for Credential {
78    #[inline]
79    fn inc_ref(&self) {
80        // SAFETY: The existence of a shared reference means that the refcount is nonzero.
81        unsafe { bindings::get_cred(self.0.get()) };
82    }
83
84    #[inline]
85    unsafe fn dec_ref(obj: core::ptr::NonNull<Credential>) {
86        // SAFETY: The safety requirements guarantee that the refcount is nonzero. The cast is okay
87        // because `Credential` has the same representation as `struct cred`.
88        unsafe { bindings::put_cred(obj.cast().as_ptr()) };
89    }
90}
kernel/cred.rs

kernel/
cred.rs
