From: Wedson Almeida Filho <wedsonaf@gmail.com>

Add a wrapper around `struct cred` called `Credential`, and provide
functionality to get the `Credential` associated with a `File`.

Rust Binder must check the credentials of processes when they attempt to
perform various operations, and these checks usually take a
`&Credential` as parameter. The security_binder_set_context_mgr function
would be one example. This patch is necessary to access these security_*
methods from Rust.

Signed-off-by: Wedson Almeida Filho <wedsonaf@gmail.com>
Co-developed-by: Alice Ryhl <aliceryhl@google.com>
Signed-off-by: Alice Ryhl <aliceryhl@google.com>
---
 rust/bindings/bindings_helper.h |  1 +
 rust/helpers.c                  | 13 +++++++
 rust/kernel/cred.rs             | 65 +++++++++++++++++++++++++++++++++
 rust/kernel/file.rs             | 13 +++++++
 rust/kernel/lib.rs              |  1 +
 5 files changed, 93 insertions(+)
 create mode 100644 rust/kernel/cred.rs

diff --git a/rust/bindings/bindings_helper.h b/rust/bindings/bindings_helper.h
index ed06970d789a..fb7d4b0b0554 100644
--- a/rust/bindings/bindings_helper.h
+++ b/rust/bindings/bindings_helper.h
@@ -7,6 +7,7 @@
  */
 
 #include <kunit/test.h>
+#include <linux/cred.h>
 #include <linux/errname.h>
 #include <linux/file.h>
 #include <linux/fs.h>
diff --git a/rust/helpers.c b/rust/helpers.c
index 03141a3608a4..10ed69f76424 100644
--- a/rust/helpers.c
+++ b/rust/helpers.c
@@ -23,6 +23,7 @@
 #include <kunit/test-bug.h>
 #include <linux/bug.h>
 #include <linux/build_bug.h>
+#include <linux/cred.h>
 #include <linux/err.h>
 #include <linux/errname.h>
 #include <linux/fs.h>
@@ -164,6 +165,18 @@ struct file *rust_helper_get_file(struct file *f)
 }
 EXPORT_SYMBOL_GPL(rust_helper_get_file);
 
+const struct cred *rust_helper_get_cred(const struct cred *cred)
+{
+	return get_cred(cred);
+}
+EXPORT_SYMBOL_GPL(rust_helper_get_cred);
+
+void rust_helper_put_cred(const struct cred *cred)
+{
+	put_cred(cred);
+}
+EXPORT_SYMBOL_GPL(rust_helper_put_cred);
+
 /*
  * `bindgen` binds the C `size_t` type as the Rust `usize` type, so we can
  * use it in contexts where Rust expects a `usize` like slice (array) indices.
diff --git a/rust/kernel/cred.rs b/rust/kernel/cred.rs
new file mode 100644
index 000000000000..ccec77242dfd
--- /dev/null
+++ b/rust/kernel/cred.rs
@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Credentials management.
+//!
+//! C header: [`include/linux/cred.h`](../../../../include/linux/cred.h)
+//!
+//! Reference: <https://www.kernel.org/doc/html/latest/security/credentials.html>
+
+use crate::{
+    bindings,
+    types::{AlwaysRefCounted, Opaque},
+};
+
+/// Wraps the kernel's `struct cred`.
+///
+/// # Invariants
+///
+/// Instances of this type are always ref-counted, that is, a call to `get_cred` ensures that the
+/// allocation remains valid at least until the matching call to `put_cred`.
+#[repr(transparent)]
+pub struct Credential(Opaque<bindings::cred>);
+
+// SAFETY: By design, the only way to access a `Credential` is via an immutable reference or an
+// `ARef`. This means that the only situation in which a `Credential` can be accessed mutably is
+// when the refcount drops to zero and the destructor runs. It is safe for that to happen on any
+// thread, so it is ok for this type to be `Send`.
+unsafe impl Send for Credential {}
+
+// SAFETY: It's OK to access `Credential` through shared references from other threads because
+// we're either accessing properties that don't change or that are properly synchronised by C code.
+unsafe impl Sync for Credential {}
+
+impl Credential {
+    /// Creates a reference to a [`Credential`] from a valid pointer.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that `ptr` is valid and remains valid for the lifetime of the
+    /// returned [`Credential`] reference.
+    pub unsafe fn from_ptr<'a>(ptr: *const bindings::cred) -> &'a Credential {
+        // SAFETY: The safety requirements guarantee the validity of the dereference, while the
+        // `Credential` type being transparent makes the cast ok.
+        unsafe { &*ptr.cast() }
+    }
+
+    /// Returns the effective UID of the given credential.
+    pub fn euid(&self) -> bindings::kuid_t {
+        // SAFETY: By the type invariant, we know that `self.0` is valid.
+        unsafe { (*self.0.get()).euid }
+    }
+}
+
+// SAFETY: The type invariants guarantee that `Credential` is always ref-counted.
+unsafe impl AlwaysRefCounted for Credential {
+    fn inc_ref(&self) {
+        // SAFETY: The existence of a shared reference means that the refcount is nonzero.
+        unsafe { bindings::get_cred(self.0.get()) };
+    }
+
+    unsafe fn dec_ref(obj: core::ptr::NonNull<Credential>) {
+        // SAFETY: The safety requirements guarantee that the refcount is nonzero. The cast is okay
+        // because `Credential` has the same representation as `struct cred`.
+        unsafe { bindings::put_cred(obj.cast().as_ptr()) };
+    }
+}
diff --git a/rust/kernel/file.rs b/rust/kernel/file.rs
index b7ded0cdd063..a2ee9d82fc8c 100644
--- a/rust/kernel/file.rs
+++ b/rust/kernel/file.rs
@@ -7,6 +7,7 @@
 
 use crate::{
     bindings,
+    cred::Credential,
     error::{code::*, Error, Result},
     types::{ARef, AlwaysRefCounted, Opaque},
 };
@@ -204,6 +205,18 @@ pub fn as_ptr(&self) -> *mut bindings::file {
         self.0.get()
     }
 
+    /// Returns the credentials of the task that originally opened the file.
+    pub fn cred(&self) -> &Credential {
+        // SAFETY: It's okay to read the `f_cred` field without synchronization because `f_cred` is
+        // never changed after initialization of the file.
+        let ptr = unsafe { (*self.as_ptr()).f_cred };
+
+        // SAFETY: The signature of this function ensures that the caller will only access the
+        // returned credential while the file is still valid, and the C side ensures that the
+        // credential stays valid at least as long as the file.
+        unsafe { Credential::from_ptr(ptr) }
+    }
+
     /// Returns the flags associated with the file.
     ///
     /// The flags are a combination of the constants in [`flags`].
diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
index ce9abceab784..097fe9bb93ed 100644
--- a/rust/kernel/lib.rs
+++ b/rust/kernel/lib.rs
@@ -33,6 +33,7 @@
 #[cfg(not(testlib))]
 mod allocator;
 mod build_assert;
+pub mod cred;
 pub mod error;
 pub mod file;
 pub mod init;
-- 
2.43.0.381.gb435a96ce8-goog

On 1/18/24 15:36, Alice Ryhl wrote:
> diff --git a/rust/kernel/cred.rs b/rust/kernel/cred.rs
> new file mode 100644
> index 000000000000..ccec77242dfd
> --- /dev/null
> +++ b/rust/kernel/cred.rs
> @@ -0,0 +1,65 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! Credentials management.
> +//!
> +//! C header: [`include/linux/cred.h`](../../../../include/linux/cred.h)

IIRC you can use `srctree/include/..` to avoid the `../..` madness.

> +//!
> +//! Reference: <https://www.kernel.org/doc/html/latest/security/credentials.html>
> +
> +use crate::{
> +    bindings,
> +    types::{AlwaysRefCounted, Opaque},
> +};
> +
> +/// Wraps the kernel's `struct cred`.
> +///
> +/// # Invariants
> +///
> +/// Instances of this type are always ref-counted, that is, a call to `get_cred` ensures that the
> +/// allocation remains valid at least until the matching call to `put_cred`.
> +#[repr(transparent)]
> +pub struct Credential(Opaque<bindings::cred>);
> +
> +// SAFETY: By design, the only way to access a `Credential` is via an immutable reference or an
> +// `ARef`. This means that the only situation in which a `Credential` can be accessed mutably is
> +// when the refcount drops to zero and the destructor runs. It is safe for that to happen on any
> +// thread, so it is ok for this type to be `Send`.

IMO the only important part is that calling `drop`/`dec_ref` is OK from
any thread.

In general I think it might be a good idea to make
`AlwaysRefCounted: Send + Sync`. But that is outside the scope of this
patch.

> +unsafe impl Send for Credential {}
> +
> +// SAFETY: It's OK to access `Credential` through shared references from other threads because
> +// we're either accessing properties that don't change or that are properly synchronised by C code.
> +unsafe impl Sync for Credential {}
> +
> +impl Credential {
> +    /// Creates a reference to a [`Credential`] from a valid pointer.
> +    ///
> +    /// # Safety
> +    ///
> +    /// The caller must ensure that `ptr` is valid and remains valid for the lifetime of the
> +    /// returned [`Credential`] reference.
> +    pub unsafe fn from_ptr<'a>(ptr: *const bindings::cred) -> &'a Credential {
> +        // SAFETY: The safety requirements guarantee the validity of the dereference, while the
> +        // `Credential` type being transparent makes the cast ok.
> +        unsafe { &*ptr.cast() }
> +    }
> +
> +    /// Returns the effective UID of the given credential.
> +    pub fn euid(&self) -> bindings::kuid_t {
> +        // SAFETY: By the type invariant, we know that `self.0` is valid.

Is `euid` an immutable property, or why does this memory access not race
with something?

-- 
Cheers,
Benno

> +        unsafe { (*self.0.get()).euid }
> +    }
> +}
> +
> +// SAFETY: The type invariants guarantee that `Credential` is always ref-counted.
> +unsafe impl AlwaysRefCounted for Credential {
> +    fn inc_ref(&self) {
> +        // SAFETY: The existence of a shared reference means that the refcount is nonzero.
> +        unsafe { bindings::get_cred(self.0.get()) };
> +    }
> +
> +    unsafe fn dec_ref(obj: core::ptr::NonNull<Credential>) {
> +        // SAFETY: The safety requirements guarantee that the refcount is nonzero. The cast is okay
> +        // because `Credential` has the same representation as `struct cred`.
> +        unsafe { bindings::put_cred(obj.cast().as_ptr()) };
> +    }
> +}

On Fri, Jan 19, 2024 at 10:37 AM Benno Lossin <benno.lossin@proton.me> wrote:
> On 1/18/24 15:36, Alice Ryhl wrote:
> > +    /// Returns the effective UID of the given credential.
> > +    pub fn euid(&self) -> bindings::kuid_t {
> > +        // SAFETY: By the type invariant, we know that `self.0` is valid.
>
> Is `euid` an immutable property, or why does this memory access not race
> with something?

Yes. These properties are changed by replacing the credential, so the
credentials themselves are immutable.

Alice

On 19.01.24 10:52, Alice Ryhl wrote:
> On Fri, Jan 19, 2024 at 10:37 AM Benno Lossin <benno.lossin@proton.me> wrote:
>> On 1/18/24 15:36, Alice Ryhl wrote:
>>> +    /// Returns the effective UID of the given credential.
>>> +    pub fn euid(&self) -> bindings::kuid_t {
>>> +        // SAFETY: By the type invariant, we know that `self.0` is valid.
>>
>> Is `euid` an immutable property, or why does this memory access not race
>> with something?
> 
> Yes. These properties are changed by replacing the credential, so the
> credentials themselves are immutable.

I see that's good to know, I think that should be mentioned
on the docs of `Credential`.

-- 
Cheers,
Benno