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
}
93

94