From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-pl1-f169.google.com (mail-pl1-f169.google.com [209.85.214.169]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id AC52F3C8731 for ; Wed, 15 Jul 2026 21:20:46 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.214.169 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1784150450; cv=none; b=CQEZ8WCUcs+kEbZSQ6+SLdKnYchEzBU02fndyh01KryfZR+ExdJWzZ40cP6iOy3kyYAzxFMmsVWaqXRq9ltUDEzZjN5PLp5BiC9ySY5+ddZpwbm0KIz92bwrTataKS/dUXKvEk+8EWjwjMZvM5Myn+LuCKcEYQ97BDsE7mBKEys= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1784150450; c=relaxed/simple; bh=5HCIi5ySWkKQMRa9Wr9spZFtfcF1MXpOzBTg6XYfGww=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=AcrtVSZT9kWAQybKSqFqxg8fQMsg+UIEvSwB55PmZszUC6XeW6bnMG3TXG38416JRyQ96diEf+FwK2Rw0YP2NTuCtare2bV73mHVrmBQCTqlLsiT6SJmGRE2CuVMXCPhS782yLQpGzn7FSWJyjvC3oamxocIcGAQs6lFofiwBeE= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=ZtliBoFJ; arc=none smtp.client-ip=209.85.214.169 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="ZtliBoFJ" Received: by mail-pl1-f169.google.com with SMTP id d9443c01a7336-2ce7d2adef4so37056765ad.3 for ; Wed, 15 Jul 2026 14:20:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1784150446; x=1784755246; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to:content-type; bh=e1GNNEUTrXfcasiBfiMqOJUDgRwUpOC+gV6LgyALCys=; b=ZtliBoFJ0kwVk3K3NQQ4CtM5CUOy7GcidqdAQPDx/jndQ9Pa5PNv+pKmJLftcOzO75 RwqRSQeTv9feRqeTpboCAj0Wz+1dUU1Xx/y2r9+Z8VXDxANwr1HPM84vqo3yYPiahmL1 QtfHl7KSxh7rv/N9g9e8wSFYFi1eYl7AytHgeD4HJ0RZ493srkQz6iPQHprL+V7skuAI noYh3v5pRVswJzcNJU2jgDxqr8GNR2/pugWZlr+kBtUBwGruSSo1ijAQDljrDEIecHLd S7T3HiEiKHj6FvQW+A2eIQR75O5vr9Bc5tvTprwITswbM80T5sUJjNY5g3FnDwLZsF8J 1IxA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1784150446; x=1784755246; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to:content-type; bh=e1GNNEUTrXfcasiBfiMqOJUDgRwUpOC+gV6LgyALCys=; b=UZMxjLhp2l9L6YwITFNLtE+ns0LkYmH4eN3V7n9vXcp2cNMUDDiQ2BbnY6E9Hdfe/a NcrHqtfxhv4pycL7PwRmi33lvTCMvGC3SADjjt3BOqFtyx0qsnWs/8vNBP6WaaoIZ/kw Oz2HRWtq8WJIkqatWL3cegHAunRpnb4yPorAo8iiNUG2PmdwNbvok0cb67xLA3sWbuTH 50sPz0hw4zhS+Ar1frTBz0UPttP4yhYOCMTOFlzAxU28r9dl9zN8u88Gu/RDAmC9FbV8 ID+sKna/KH/dKu9Z6zRnFMoS4u5wth0Vwf5+CFcQ+IgePLoMnB7SHV4o+khdr4Ft54oD 0pvA== X-Forwarded-Encrypted: i=1; AHgh+RrBfvdK3J+NpywmHiP0cIdY/nN9CVBzUNnUonwktWY4yqNuyfdTlwN4hgtQtvPumCyFg74v4UzHj98zmDU=@vger.kernel.org X-Gm-Message-State: AOJu0Yw3vsTMqNetSmDwY3PHYZ6QJBh7N81/QYLBX0FEqn9gDhDTBdlU W/5dcQB+aJtcSczvW06LK+z6YRyv4+f09uMqvFWnjfrwY5qpz2YRxA6W X-Gm-Gg: AfdE7cly8uSpGFuwbv/NaehwvTfPW2s7EkLiCpGee7xPNbbAdYxOoYdzRg4lbv7YJ+s xbm0vwy1NAWlEVQMYeVT7EoDPkZH91KoZ6mDuUKdxoP2azk5RxdjvGUt3h+04539eF3hqAHYLUz 43kk3qNNBiYiHxy815e3iX4Tz62MuJye1HfOZAlW1ZO2Qff/dHI6Hs/hCeUQKxtNqjG9LzvCB0h 045ALO94KieOwUsJmFsmTMeO03ygTJJfSPcjktw86qsBPc2zU9JDeiPRHtaSNiEZzTLF1DIcjbE Cve8kyxdmA11jSPv3DK5OnBXRagpfwVPeD9mU3krP7h4rupd55JHaWeTn137YSXIIuCihPPItlz oss1sxbH3tcL+zSyC00eWFMGUU/LE4t+OGCPYf6A19MJF2Y0EPEE3pSLHQVkd1gQIae83w6Pfxq JmMWYHju95IRORgaHbp6owuclZyD+UB5pninxJkjJJXMSGTwI0KFETpF1jPQ== X-Received: by 2002:a05:6a21:4d8f:b0:3b2:a809:ffe with SMTP id adf61e73a8af0-3c11000c533mr22415567637.14.1784150446023; Wed, 15 Jul 2026 14:20:46 -0700 (PDT) Received: from pop-os.tail4adac7.ts.net ([129.210.115.107]) by smtp.gmail.com with ESMTPSA id a92af1059eb24-13cd403a7f7sm4126844c88.0.2026.07.15.14.20.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 15 Jul 2026 14:20:44 -0700 (PDT) From: Cong Wang To: Andy Lutomirski Cc: Kees Cook , linux-kernel@vger.kernel.org, Will Drewry , Christian Brauner , Andrew Morton , linux-mm@kvack.org, Cong Wang Subject: [PATCH v6 7/8] docs/seccomp: document pinned-memfd redirect ioctls Date: Wed, 15 Jul 2026 14:20:06 -0700 Message-ID: <20260715212007.2382846-8-xiyou.wangcong@gmail.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20260715212007.2382846-1-xiyou.wangcong@gmail.com> References: <20260715212007.2382846-1-xiyou.wangcong@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: Cong Wang Document SECCOMP_IOCTL_NOTIF_PIN_INSTALL and SECCOMP_IOCTL_NOTIF_SEND_REDIRECT in the userspace API guide: the SECCOMP_FILTER_FLAG_REDIRECT opt-in and the single-redirector restriction, the two response structures, and how the pair closes the user-notification TOCTOU for non-cooperative fork+execve sandboxes. Also spell out the scope the implementation deliberately enforces or relies on: read-only input pointers only, same-syscall-number only (rt_sigreturn and the clone/fork family are refused), the per-interruption re-notification of restartable syscalls and the restart-block behaviour, and the ptrace syscall-stop semantics. Assisted-by: Claude:claude-opus-4.8 Signed-off-by: Cong Wang --- .../userspace-api/seccomp_filter.rst | 109 ++++++++++++++++++ 1 file changed, 109 insertions(+) diff --git a/Documentation/userspace-api/seccomp_filter.rst b/Documentation/userspace-api/seccomp_filter.rst index cff0fa7f3175..be2c338224ac 100644 --- a/Documentation/userspace-api/seccomp_filter.rst +++ b/Documentation/userspace-api/seccomp_filter.rst @@ -289,6 +289,115 @@ above in this document: all arguments being read from the tracee's memory should be read into the tracer's memory before any policy decisions are made. This allows for an atomic decision on syscall arguments. +Non-cooperative pinned-memfd redirect +===================================== + +The TOCTOU described above means ``SECCOMP_USER_NOTIF_FLAG_CONTINUE`` cannot +enforce a policy on pointer arguments: after the supervisor inspects the +target's memory and lets the syscall continue, the target (or a thread sharing +its address space) can rewrite that memory before the kernel reads it. The +cooperative workaround, the target ``mmap()`` + ``mseal()``-ing a shared +buffer, is unavailable in the fork+execve sandbox model, where the supervisor +confines a binary it did not write. + +Two ioctls let the supervisor close this race without target cooperation. The +redirect step (below) requires a listener created with +``SECCOMP_FILTER_FLAG_REDIRECT`` (in addition to +``SECCOMP_FILTER_FLAG_NEW_LISTENER``). Because it rewrites another task's +registers, at most one such listener may exist in a task's filter chain; a +second fails with ``-EBUSY``: + +.. code-block:: c + + fd = seccomp(SECCOMP_SET_MODE_FILTER, + SECCOMP_FILTER_FLAG_NEW_LISTENER | SECCOMP_FILTER_FLAG_REDIRECT, + &prog); + +``ioctl(SECCOMP_IOCTL_NOTIF_PIN_INSTALL)`` installs a sealed mapping of a +supervisor-owned ``memfd`` directly into the trapped task's address space: + +.. code-block:: c + + struct seccomp_notif_pin_install { + __u64 id; + __u32 flags; /* reserved, must be 0 */ + __u32 memfd; + __u64 target_addr; + __u64 size; + __u64 offset; /* page-aligned offset into memfd */ + }; + +``id`` names an active notification (the trapped task to install into). +``target_addr``, ``size`` and ``offset`` are page-aligned; ``offset`` selects +where in ``memfd`` the mapping starts, so one memfd can back several pins. If +``target_addr`` is ``0`` the kernel picks a free address and writes it back; +otherwise an existing mapping there yields ``-EEXIST``. The pin is read-only +and sealed, the target and its threads cannot unmap, move, reprotect or +overwrite it, and lasts until the target calls ``execve()`` or exits. + +``memfd`` must be write-sealed (``F_SEAL_WRITE`` or ``F_SEAL_FUTURE_WRITE``) +or the ioctl returns ``-EINVAL``; otherwise the target could rewrite the pin's +bytes through a separate writable handle to the same memfd. +``F_SEAL_FUTURE_WRITE`` still lets the supervisor update the contents through +its own mapping made before the seal. + +``ioctl(SECCOMP_IOCTL_NOTIF_SEND_REDIRECT)`` then resumes the trapped syscall +like ``SECCOMP_USER_NOTIF_FLAG_CONTINUE``, but with selected argument +registers replaced: + +.. code-block:: c + + struct seccomp_notif_resp_redirect { + __u64 id; + __u32 flags; /* SECCOMP_REDIRECT_FLAG_CONTINUE must be set */ + __u32 args_mask; /* which arg registers to replace */ + __u32 ptr_mask; /* which of those are pointers into a pin */ + __u32 memfd; /* the pin's backing memfd */ + __u64 args[6]; /* replacement values */ + __u64 ptr_len[6]; /* validated access length for each pointer arg */ + }; + +Each bit in ``ptr_mask`` (a subset of ``args_mask``) marks ``args[i]`` as a +pointer; the access ``[args[i], args[i] + ptr_len[i])`` must lie within a +single read-only pin of ``memfd`` in the target, or the ioctl returns +``-EFAULT``. ``ptr_len[i]`` must be non-zero for those bits and ``0`` +otherwise. Bits in ``args_mask`` but not ``ptr_mask`` are scalar replacements +written verbatim, e.g. to set the length register that goes with a redirected +pointer. The original registers are restored at syscall exit, so the +substitution is invisible to the target and the TOCTOU is closed. + +Scope and limitations +--------------------- + +The redirect mechanism is deliberately narrow and is *not* a general syscall +rewriting facility: + +- **Read-only input pointers only.** A pin is read-only, so only an argument + the syscall *reads* (a pathname, a ``sockaddr``) may be redirected into it. + Aiming an output or in/out argument at a pin makes the syscall fail with + ``-EFAULT`` when it writes back. + +- **Same syscall only.** A redirect replaces arguments, never the syscall + number. ``rt_sigreturn()`` (and its compat variant) cannot be redirected and + return ``-EOPNOTSUPP``. + +- **Signals and restarts.** The redirected syscall really runs, so it can be + interrupted and restarted. On a restart the original arguments are restored + and the syscall re-traps, so the supervisor is notified again and must answer + consistently. Syscalls the kernel restarts without re-trapping (e.g. + ``nanosleep()``, ``futex(FUTEX_WAIT)``) keep the substituted arguments -- + safe for read-only inputs, but a reason not to redirect arguments of syscalls + that block or wait. + +- **clone()/fork().** The task-creation family (``clone``, ``clone3``, + ``fork``, ``vfork``) cannot be redirected and returns ``-EOPNOTSUPP``. A new + child inherits the substituted argument registers but not the restore, so it + would return to user space with the pinned values still in its registers. + +- **ptrace.** A tracer sees the substituted arguments at the syscall-exit stop; + they are restored before the task resumes, so a ``PTRACE_SETREGS`` of a + substituted register at that stop is overwritten. + Sysctls ======= -- 2.43.0