From 5fa1e68f9978708db43aa82f70c92fe992419bb0 Mon Sep 17 00:00:00 2001 From: Christian Brauner Date: Tue, 21 Jul 2026 16:13:56 +0200 Subject: [PATCH] binfmt_misc: document the transparent identity contract Describe what a transparent dispatch constructs and the loader contract behind AT_FLAGS_TRANSPARENT_INTERP. Also note what deliberately stays different (the address space layout) and what stays unchanged (credential derivation without 'C'). Link: https://patch.msgid.link/20260721-work-bpf-binfmt_misc-ptinterp-v2-14-e57866e4ae0f@kernel.org Signed-off-by: Christian Brauner (Amutable) --- Documentation/admin-guide/binfmt-misc.rst | 26 +++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/Documentation/admin-guide/binfmt-misc.rst b/Documentation/admin-guide/binfmt-misc.rst index 4547ebdfcaa5..d46130be0891 100644 --- a/Documentation/admin-guide/binfmt-misc.rst +++ b/Documentation/admin-guide/binfmt-misc.rst @@ -224,6 +224,32 @@ The entry keeps the handler alive; deleting the struct_ops map only prevents new activations. +Transparent interpreters +------------------------ + +With the ``T`` flag or ``BPF_BINPRM_TRANSPARENT`` the dispatch is invisible +to the resulting process. The argument vector is left exactly as the caller +built it. The binary is passed through ``AT_EXECFD``. The kernel also labels +``/proc/pid/exe`` correctly. The binary's file is write-denied while the +process runs and the interpreter's is not, exactly as if the binary had been +executed directly. A transparent entry does not change how credentials are +derived. As +with any other entry, set*id bits of the binary are only honored with ``C`` (or +``BPF_BINPRM_CREDENTIALS``). + +The interpreter has to be built for this contract. The kernel announces it +with ``AT_FLAGS_TRANSPARENT_INTERP`` in the ``AT_FLAGS`` aux vector entry +next to ``AT_EXECFD``. The argument vector belongs entirely to the program, +nothing was spliced in, so the interpreter doesn't consume arguments and +simply loads the program from the descriptor. The bit is also the loader's +license to finish the identity. After mapping the program it may retarget the +``AT_PHDR``/``AT_ENTRY``/``AT_BASE`` entries of ``/proc/pid/auxv`` and the +code/data statistics markers via one ``PR_SET_MM_MAP`` which completes +what attaching debuggers observe. What remains visibly different from a +direct execution is the address space layout. The interpreter occupies +the main-image position and the program lives in the mmap region. + + Hints -----