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 
11 use 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)]
32 pub 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.
37 unsafe 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.
41 unsafe impl Sync for Credential {}
42 
43 impl 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]
from_ptr<'a>(ptr: *const bindings::cred) -> &'a Credential51     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]
get_secid(&self) -> u3259     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]
euid(&self) -> Kuid68     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.
77 unsafe impl AlwaysRefCounted for Credential {
78     #[inline]
inc_ref(&self)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]
dec_ref(obj: core::ptr::NonNull<Credential>)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 }
91