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] 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 /// Returns a raw pointer to the inner credential. 58 #[inline] 59 pub fn as_ptr(&self) -> *const bindings::cred { 60 self.0.get() 61 } 62 63 /// Get the id for this security context. 64 #[inline] 65 pub fn get_secid(&self) -> u32 { 66 let mut secid = 0; 67 // SAFETY: The invariants of this type ensures that the pointer is valid. 68 unsafe { bindings::security_cred_getsecid(self.0.get(), &mut secid) }; 69 secid 70 } 71 72 /// Returns the effective UID of the given credential. 73 #[inline] 74 pub fn euid(&self) -> Kuid { 75 // SAFETY: By the type invariant, we know that `self.0` is valid. Furthermore, the `euid` 76 // field of a credential is never changed after initialization, so there is no potential 77 // for data races. 78 Kuid::from_raw(unsafe { (*self.0.get()).euid }) 79 } 80 } 81 82 // SAFETY: The type invariants guarantee that `Credential` is always ref-counted. 83 unsafe impl AlwaysRefCounted for Credential { 84 #[inline] 85 fn inc_ref(&self) { 86 // SAFETY: The existence of a shared reference means that the refcount is nonzero. 87 unsafe { bindings::get_cred(self.0.get()) }; 88 } 89 90 #[inline] 91 unsafe fn dec_ref(obj: core::ptr::NonNull<Credential>) { 92 // SAFETY: The safety requirements guarantee that the refcount is nonzero. The cast is okay 93 // because `Credential` has the same representation as `struct cred`. 94 unsafe { bindings::put_cred(obj.cast().as_ptr()) }; 95 } 96 } 97