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