[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

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

[kernel test robot]

Hi Arnav,

kernel test robot noticed the following build errors:

[auto build test ERROR on rust/rust-next]
[also build test ERROR on linus/master v7.1-rc3 next-20260508]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Arnav-Sharma/rust-cred-add-safe-abstractions-for-capable-and-ns_capable/20260513-154340
base:   https://github.com/Rust-for-Linux/linux rust-next
patch link:    https://lore.kernel.org/r/20260506204913.26022-1-arnav4324%40gmail.com
patch subject: [PATCH] rust: cred: add safe abstractions for capable() and ns_capable()
config: loongarch-randconfig-001 (https://download.01.org/0day-ci/archive/20260513/202605132018.249x1thF-lkp@intel.com/config)
compiler: clang version 18.1.8 (https://github.com/llvm/llvm-project 3b5b5c1ec4a3095ab096dd780e84d7ab81f3d7ff)
rustc: rustc 1.88.0 (6b00bc388 2025-06-23)
reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20260513/202605132018.249x1thF-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202605132018.249x1thF-lkp@intel.com/

All errors (new ones prefixed by >>):

>> error[E0425]: cannot find function `capable` in crate `bindings`
   --> rust/kernel/cred.rs:133:24
   |
   133 |     unsafe { bindings::capable(cap as i32) }
   |                        ^^^^^^^ not found in `bindings`
--
>> error[E0425]: cannot find function `ns_capable` in crate `bindings`
   --> rust/kernel/cred.rs:169:24
   |
   169    |       unsafe { bindings::ns_capable(ns, cap as i32) }
   |                          ^^^^^^^^^^ help: a function with a similar name exists: `cap_capable`
   |
   ::: rust/bindings/bindings_generated.rs:107518:5
   |
   107518 | /     pub fn cap_capable(
   107519 | |         cred: *const cred,
   107520 | |         ns: *mut user_namespace,
   107521 | |         cap: ffi::c_int,
   107522 | |         opts: ffi::c_uint,
   107523 | |     ) -> ffi::c_int;
   | |____________________- similarly named function `cap_capable` defined here

--
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

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

[kernel test robot]

Hi Arnav,

kernel test robot noticed the following build errors:

[auto build test ERROR on rust/rust-next]
[also build test ERROR on linus/master v7.1-rc3 next-20260508]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Arnav-Sharma/rust-cred-add-safe-abstractions-for-capable-and-ns_capable/20260513-154340
base:   https://github.com/Rust-for-Linux/linux rust-next
patch link:    https://lore.kernel.org/r/20260506204913.26022-1-arnav4324%40gmail.com
patch subject: [PATCH] rust: cred: add safe abstractions for capable() and ns_capable()
config: x86_64-rhel-9.4-rust (https://download.01.org/0day-ci/archive/20260513/202605131729.NXF18q0f-lkp@intel.com/config)
compiler: clang version 20.1.8 (https://github.com/llvm/llvm-project 87f0227cb60147a26a1eeb4fb06e3b505e9c7261)
rustc: rustc 1.88.0 (6b00bc388 2025-06-23)
reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20260513/202605131729.NXF18q0f-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202605131729.NXF18q0f-lkp@intel.com/

All errors (new ones prefixed by >>):

   PATH=/opt/cross/clang-20/bin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
   INFO PATH=/opt/cross/rustc-1.88.0-bindgen-0.72.1/cargo/bin:/opt/cross/clang-20/bin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
   /usr/bin/timeout -k 100 12h /usr/bin/make KCFLAGS=\ -fno-crash-diagnostics\ -Wno-error=return-type\ -Wreturn-type\ -funsigned-char\ -Wundef\ -falign-functions=64 W=1 --keep-going LLVM=1 -j384 -C source O=/kbuild/obj/consumer/x86_64-rhel-9.4-rust ARCH=x86_64 SHELL=/bin/bash rustfmtcheck 
   make: Entering directory '/kbuild/src'
   make[1]: Entering directory '/kbuild/obj/consumer/x86_64-rhel-9.4-rust'
>> Diff in rust/kernel/cred.rs:168:
        // the specified capability is granted.
        unsafe { bindings::ns_capable(ns, cap as i32) }
    }
   -
    
>> Diff in rust/kernel/cred.rs:168:
        // the specified capability is granted.
        unsafe { bindings::ns_capable(ns, cap as i32) }
    }
   -
    
   make[2]: *** [Makefile:1954: rustfmt] Error 123
   make[2]: Target 'rustfmtcheck' not remade because of errors.
   make[1]: Leaving directory '/kbuild/obj/consumer/x86_64-rhel-9.4-rust'
   make[1]: *** [Makefile:248: __sub-make] Error 2
   make[1]: Target 'rustfmtcheck' not remade because of errors.
   make: *** [Makefile:248: __sub-make] Error 2
   make: Target 'rustfmtcheck' not remade because of errors.
   make: Leaving directory '/kbuild/src'

--
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki