[PATCH] rust: cred: add safe abstractions for capable() and ns_capable()

[PATCH] rust: cred: add safe abstractions for capable() and ns_capable()

[Arnav Sharma]

The capable() function is the primary privilege gate in the Linux kernel,
used to check if the current task possesses a specific POSIX capability.
While bindings for capable() and ns_capable() exist, there are currently
no safe Rust abstractions for them.

Introduce safe Rust wrappers for capable() and ns_capable() in the
kernel::cred module. These functions validate that the requested
capability is within the valid [0, CAP_LAST_CAP] bounds before calling
into the C side, ensuring that safe Rust code cannot inadvertently
trigger a kernel BUG() on invalid inputs.

The abstractions take a `u32` parameter to ergonomically match the
generated `bindings::CAP_*` constants without requiring explicit caller
casts.

Signed-off-by: Arnav Sharma <arnav4324@gmail.com>
---
 rust/kernel/cred.rs | 79 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/rust/kernel/cred.rs b/rust/kernel/cred.rs
index ffa156b9df37..6525b52b81ae 100644
--- a/rust/kernel/cred.rs
+++ b/rust/kernel/cred.rs
@@ -90,3 +90,82 @@ unsafe fn dec_ref(obj: core::ptr::NonNull<Credential>) {
         unsafe { bindings::put_cred(obj.cast().as_ptr()) };
     }
 }
+
+/// Checks whether the current task has the given capability in the init user namespace.
+///
+/// This function tests whether the current task has the specified POSIX capability available for
+/// use. The check is performed against the initial user namespace (`init_user_ns`).
+///
+/// When the check succeeds, the kernel sets the `PF_SUPERPRIV` flag on the current task. This
+/// marks the task as having used superuser privileges, which is visible in process accounting
+/// and auditing.
+///
+/// The capability constants are available as `bindings::CAP_*` values (for example,
+/// [`bindings::CAP_NET_ADMIN`], [`bindings::CAP_SYS_ADMIN`]). These constants are defined in
+/// `include/uapi/linux/capability.h`.
+///
+/// This function must be called from task (process) context only. Calling it from a context where
+/// there is no valid `current` task (such as hard interrupt context) is not permitted.
+///
+/// # Preconditions
+///
+/// `cap` must be a valid capability constant in the range `[0, CAP_LAST_CAP]`.
+/// Passing a value outside this range is a programming error and will trigger
+/// a kernel `BUG()`.
+///
+/// C header: [`include/linux/capability.h`](srctree/include/linux/capability.h)
+///
+/// # Examples
+///
+/// ```
+/// use kernel::bindings;
+/// use kernel::cred::capable;
+///
+/// if !capable(bindings::CAP_SYS_ADMIN) {
+///     return Err(EPERM);
+/// }
+/// # Ok::<(), Error>(())
+/// ```
+#[inline]
+pub fn capable(cap: u32) -> bool {
+    // SAFETY: `capable()` is safe to call from task context. It checks `current_cred()` against
+    // the init user namespace and returns whether the specified capability is granted.
+    unsafe { bindings::capable(cap as i32) }
+}
+
+/// Checks whether the current task has the given capability in the specified user namespace.
+///
+/// This is the namespace-aware variant of [`capable`]. It tests whether the current task has the
+/// specified capability in the given user namespace, rather than in the init user namespace.
+///
+/// This function is relevant for code that must respect user namespace boundaries (for example,
+/// operations inside unprivileged containers). For most driver code that is not namespace-aware,
+/// [`capable`] is the correct function to use instead.
+///
+/// Like [`capable`], this function sets `PF_SUPERPRIV` on the current task when the check
+/// succeeds, and it must be called from task context only.
+///
+/// # Preconditions
+///
+/// `cap` must be a valid capability constant in the range `[0, CAP_LAST_CAP]`.
+/// Passing a value outside this range is a programming error and will trigger
+/// a kernel `BUG()`.
+///
+/// C header: [`include/linux/capability.h`](srctree/include/linux/capability.h)
+///
+/// # Safety
+///
+/// The caller must ensure that:
+///
+/// - `ns` is a non-null pointer to a fully initialized `struct user_namespace`.
+/// - The `user_namespace` pointed to by `ns` remains valid and is not freed for
+///   the duration of this call.
+#[inline]
+pub unsafe fn ns_capable(ns: *mut bindings::user_namespace, cap: u32) -> bool {
+    // SAFETY: The caller guarantees that `ns` is a non-null, valid pointer to a fully initialized
+    // `struct user_namespace` that remains valid for the duration of this call.
+    // `ns_capable()` checks `current_cred()` against the provided namespace and returns whether
+    // the specified capability is granted.
+    unsafe { bindings::ns_capable(ns, cap as i32) }
+}
+
-- 
2.43.0

Re: [PATCH] rust: cred: add safe abstractions for capable() and ns_capable()

[Onur Özkan]

On Thu, 07 May 2026 02:19:13 +0530
Arnav Sharma <arnav4324@gmail.com> wrote:

> The capable() function is the primary privilege gate in the Linux kernel,
> used to check if the current task possesses a specific POSIX capability.
> While bindings for capable() and ns_capable() exist, there are currently
> no safe Rust abstractions for them.
> 
> Introduce safe Rust wrappers for capable() and ns_capable() in the
> kernel::cred module. These functions validate that the requested
> capability is within the valid [0, CAP_LAST_CAP] bounds before calling
> into the C side, ensuring that safe Rust code cannot inadvertently
> trigger a kernel BUG() on invalid inputs.
> 
> The abstractions take a `u32` parameter to ergonomically match the
> generated `bindings::CAP_*` constants without requiring explicit caller
> casts.

Do we have any users who need this? What's the use case and where will this be
used?

-Onur

> 
> Signed-off-by: Arnav Sharma <arnav4324@gmail.com>
> ---
>  rust/kernel/cred.rs | 79 +++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 79 insertions(+)
> 
> diff --git a/rust/kernel/cred.rs b/rust/kernel/cred.rs
> index ffa156b9df37..6525b52b81ae 100644
> --- a/rust/kernel/cred.rs
> +++ b/rust/kernel/cred.rs
> @@ -90,3 +90,82 @@ unsafe fn dec_ref(obj: core::ptr::NonNull<Credential>) {
>          unsafe { bindings::put_cred(obj.cast().as_ptr()) };
>      }
>  }
> +
> +/// Checks whether the current task has the given capability in the init user namespace.
> +///
> +/// This function tests whether the current task has the specified POSIX capability available for
> +/// use. The check is performed against the initial user namespace (`init_user_ns`).
> +///
> +/// When the check succeeds, the kernel sets the `PF_SUPERPRIV` flag on the current task. This
> +/// marks the task as having used superuser privileges, which is visible in process accounting
> +/// and auditing.
> +///
> +/// The capability constants are available as `bindings::CAP_*` values (for example,
> +/// [`bindings::CAP_NET_ADMIN`], [`bindings::CAP_SYS_ADMIN`]). These constants are defined in
> +/// `include/uapi/linux/capability.h`.
> +///
> +/// This function must be called from task (process) context only. Calling it from a context where
> +/// there is no valid `current` task (such as hard interrupt context) is not permitted.
> +///
> +/// # Preconditions
> +///
> +/// `cap` must be a valid capability constant in the range `[0, CAP_LAST_CAP]`.
> +/// Passing a value outside this range is a programming error and will trigger
> +/// a kernel `BUG()`.
> +///
> +/// C header: [`include/linux/capability.h`](srctree/include/linux/capability.h)
> +///
> +/// # Examples
> +///
> +/// ```
> +/// use kernel::bindings;
> +/// use kernel::cred::capable;
> +///
> +/// if !capable(bindings::CAP_SYS_ADMIN) {
> +///     return Err(EPERM);
> +/// }
> +/// # Ok::<(), Error>(())
> +/// ```
> +#[inline]
> +pub fn capable(cap: u32) -> bool {
> +    // SAFETY: `capable()` is safe to call from task context. It checks `current_cred()` against
> +    // the init user namespace and returns whether the specified capability is granted.
> +    unsafe { bindings::capable(cap as i32) }
> +}
> +
> +/// Checks whether the current task has the given capability in the specified user namespace.
> +///
> +/// This is the namespace-aware variant of [`capable`]. It tests whether the current task has the
> +/// specified capability in the given user namespace, rather than in the init user namespace.
> +///
> +/// This function is relevant for code that must respect user namespace boundaries (for example,
> +/// operations inside unprivileged containers). For most driver code that is not namespace-aware,
> +/// [`capable`] is the correct function to use instead.
> +///
> +/// Like [`capable`], this function sets `PF_SUPERPRIV` on the current task when the check
> +/// succeeds, and it must be called from task context only.
> +///
> +/// # Preconditions
> +///
> +/// `cap` must be a valid capability constant in the range `[0, CAP_LAST_CAP]`.
> +/// Passing a value outside this range is a programming error and will trigger
> +/// a kernel `BUG()`.
> +///
> +/// C header: [`include/linux/capability.h`](srctree/include/linux/capability.h)
> +///
> +/// # Safety
> +///
> +/// The caller must ensure that:
> +///
> +/// - `ns` is a non-null pointer to a fully initialized `struct user_namespace`.
> +/// - The `user_namespace` pointed to by `ns` remains valid and is not freed for
> +///   the duration of this call.
> +#[inline]
> +pub unsafe fn ns_capable(ns: *mut bindings::user_namespace, cap: u32) -> bool {
> +    // SAFETY: The caller guarantees that `ns` is a non-null, valid pointer to a fully initialized
> +    // `struct user_namespace` that remains valid for the duration of this call.
> +    // `ns_capable()` checks `current_cred()` against the provided namespace and returns whether
> +    // the specified capability is granted.
> +    unsafe { bindings::ns_capable(ns, cap as i32) }
> +}
> +
> -- 
> 2.43.0
> 

Re: [PATCH] rust: cred: add safe abstractions for capable() and ns_capable()

[Alice Ryhl]

On Thu, May 07, 2026 at 02:19:13AM +0530, Arnav Sharma wrote:
> The capable() function is the primary privilege gate in the Linux kernel,
> used to check if the current task possesses a specific POSIX capability.
> While bindings for capable() and ns_capable() exist, there are currently
> no safe Rust abstractions for them.
> 
> Introduce safe Rust wrappers for capable() and ns_capable() in the
> kernel::cred module. These functions validate that the requested
> capability is within the valid [0, CAP_LAST_CAP] bounds before calling
> into the C side, ensuring that safe Rust code cannot inadvertently
> trigger a kernel BUG() on invalid inputs.
> 
> The abstractions take a `u32` parameter to ergonomically match the
> generated `bindings::CAP_*` constants without requiring explicit caller
> casts.
> 
> Signed-off-by: Arnav Sharma <arnav4324@gmail.com>

I have the same question about what the use-case for this is.

> +/// # Safety
> +///
> +/// The caller must ensure that:
> +///
> +/// - `ns` is a non-null pointer to a fully initialized `struct user_namespace`.
> +/// - The `user_namespace` pointed to by `ns` remains valid and is not freed for
> +///   the duration of this call.
> +#[inline]
> +pub unsafe fn ns_capable(ns: *mut bindings::user_namespace, cap: u32) -> bool {

I would add a UserNamespace struct so that this raw pointer could be
avoided, before I add this method.

Alice