From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-pl1-f180.google.com (mail-pl1-f180.google.com [209.85.214.180]) (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 3EF4F36C597 for ; Sat, 4 Jul 2026 23:19:12 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.214.180 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1783207155; cv=none; b=o0u3Vff6gLcbnzW7G50Wwj2eQIhJLENnaBeR7J0FIzJDwXI0Ds/sxhNqVng51D/EhkDZ/ZufOFtpEs1cQpGdEchpcW1yA8F4Ybpm2ImBfQ5EnXsmM03uPU/rDgCQ9/UtHeAlz9FYfBtISE6vGVOmOFck0qfNshfZD95WyWa4J40= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1783207155; c=relaxed/simple; bh=3ZjqH7JShfEhfA4zmf1brHRmxWa94tTVOU7SInnMgDI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=dcfbzc4/NxAdk6xCXJJ2U0Gr+yQfbZA0KNJfnxb6T9VY5szb33MQ+DIPeR4aT/Kec2kwfVotaGD91YzXoMTZMcVkSmmv/oZp23EoqUBIWniaDwdwaLfIxcNzpjDYCatCvhsbSJxewOm3JTQzRGyylHhPx4kgR+N5wlCRw6W8Mig= 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=HpjpSui3; arc=none smtp.client-ip=209.85.214.180 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="HpjpSui3" Received: by mail-pl1-f180.google.com with SMTP id d9443c01a7336-2cacf197759so26615415ad.2 for ; Sat, 04 Jul 2026 16:19:12 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1783207151; x=1783811951; 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=JsafSmJFi4yY0T+vpMQ3AUtMEkHeCj5xJ0OnO8eYDKg=; b=HpjpSui3d/vailOA0DIM8WOxm49lP3b+5vNQPj3gP7AcDA+wSI2YQyJ1/ag9mTnuOH X1N43/ERe/5IonD7uH0vKQfku+bMAERtW0AW8Ky3UZ9ttodqUxXI+a7mr/mXF6sXQxwM whHPqqAfNUjWeogMN2LtQl/oaREu2F+1pwJX3eS8Iw3UUBlqobRvMPeNREjXj2WoozBQ YIK2G245CpvjclRKgCv8oMRu2E2HcUIUVO/XvJZVcHaJGWmPQjosBubsqJ4XpYnlN4ke wuB5Io5nq6NHxC0aaR689Hv5kEwPnGUCISBHdsZzqvZtwVmdad0T1dOHkGZ3yAocC/mN DVuw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1783207151; x=1783811951; 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=JsafSmJFi4yY0T+vpMQ3AUtMEkHeCj5xJ0OnO8eYDKg=; b=Zt9xe/mbxKJqq8XD9Mpl2gxdGtjGM9sqMbdgJj9EIrxBgRi6DiodAfBCpe5NGm/tuN XkPdu97W87d8ZXS730jrQ5H+wjOfK+F33lSo6gv5oJDJHYZsdL5BPkLe9KgHBenlfaNo Az12WzGuqlEYi7IHnVWYAVA+3Ih5P3ZGURHqltuLhJNZeR9iJc13SKmU9cq6rdqZw08C Q0yzb8UWirobdfMDVwrJaWcovm7Nr35N8MAspjTGBX272vph8PT7WZOExT84cb87FIDH oC4bBTiL8jZ+iK2ocjtNqto6JWjZmVftWvav5ot8k8ILdYiQpxTzuBZum8bRxcfcqcDB nieg== X-Forwarded-Encrypted: i=1; AHgh+RqmDzrXqQddSYhRz4mEIghqa8He+xDprY/aWIZRdM6EEvLWo0MFw7MNd4DEMJZKC66ec5vMRxEz5XXVHgg=@vger.kernel.org X-Gm-Message-State: AOJu0YxytXlX+oLAmrIBr+QFXbdMiloSD9DXVfFW2OOaUUcMbc2/J47N XLHoexhStLqFplTMVfVTUj2LQDVpACWWgpUwXbmT6fwphdbmWKjLylVY X-Gm-Gg: AfdE7cm195620JG76lai7GryVS370JbajHnXR67WTJQTQKDC0zvQm/4Wo8vOel7WpsT F4Y4R3hezbA7X+eerP95qI12f3r1kvAs7KDbW++XJgs0Z/Ffh669XqXGGcbjLp0FvctIQ9rbU3N 68Ows/rC09Ghw5h07dESqyuBFnnchCYS92Z/skQQg91X1aq8moDVxyKEnEtA2fMbZ7SUiBOK/4j hxbNJQs2nKSj03a1rxUQ89M6czqrCkMrk3JZcyOrxpKzWyJIJ8ot/U4sI0zE5/nC+PLA/fpg2hH qtxQou64O1KZGZ1+AW2Gz3U1UTY/ZHnXusnf/kbUZPH32si66IHdMNpuUMLo6NSRpqCI6tMuFGz IU2keFrjN0t4hnitWb8wjxeN5gAdQxtNgkT55KSiC80EZixXmhHtKZdNDeGl5wv6kAX4HLRHB01 R2RgPB56ifdEi/Nm/uKYzl9r9nKFEAFnZaS7cWI+6CttDZO75z4w== X-Received: by 2002:a17:903:2284:b0:2ca:d91d:d3a7 with SMTP id d9443c01a7336-2cb97e4428fmr47808265ad.10.1783207151480; Sat, 04 Jul 2026 16:19:11 -0700 (PDT) Received: from pop-os.. ([2601:647:6802:dbc0:55ba:96cc:892f:32d7]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-2cad776589fsm27088215ad.43.2026.07.04.16.19.10 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 04 Jul 2026 16:19:10 -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 v5 6/7] docs/seccomp: document pinned-memfd redirect ioctls Date: Sat, 4 Jul 2026 16:18:30 -0700 Message-ID: <20260704231831.354543-7-xiyou.wangcong@gmail.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20260704231831.354543-1-xiyou.wangcong@gmail.com> References: <20260704231831.354543-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..e868a2900574 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 ``execve()``s 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