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