In Linux 4.8 (through a series of commits, 93e35efb8de45393cf61ed07f7b407629bf698ea being the actual reordering on x86), the order of PTRACE_EVENT_SECCOMP and syscall-entry-stops was reversed. Document both behaviors and their interaction with the various forms of restart. Signed-off-by: Keno Fischer <keno@xxxxxxxxxxxxxxxxxx> --- man2/ptrace.2 | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 74 insertions(+), 5 deletions(-) diff --git a/man2/ptrace.2 b/man2/ptrace.2 index cb1b976..a821b7b 100644 --- a/man2/ptrace.2 +++ b/man2/ptrace.2 @@ -646,8 +646,8 @@ value such that While this triggers a .BR PTRACE_EVENT -stop, it is similar to a syscall-enter-stop, in that the tracee has -not yet entered the syscall that seccomp triggered on. +stop, it is similar to a syscall-enter-stop. For details, +see the note on PTRACE_EVENT_SECCOMP below. The seccomp event message data (from the .BR SECCOMP_RET_DATA portion of the seccomp filter rule) can be retrieved with @@ -1133,6 +1133,7 @@ be further subdivided into .IR signal-delivery-stop , .IR group-stop , .IR syscall-stop , +.IR PTRACE_EVENT stops, and so on. These stopped states are described in detail below. .LP @@ -1553,7 +1554,8 @@ has been set by the tracer. The seccomp event message data (from the .BR SECCOMP_RET_DATA portion of the seccomp filter rule) can be retrieved with -.BR PTRACE_GETEVENTMSG . +.BR PTRACE_GETEVENTMSG . The semantics of this stop are described in +detail in a separate section below. .LP .B PTRACE_GETSIGINFO on @@ -1599,7 +1601,7 @@ However, even if the tracee is was continued using , it is not guaranteed that the next stop will be a syscall-exit-stop. Other possibilities are that the tracee may stop in a .B PTRACE_EVENT -stop, exit (if it entered +stop (including seccomp stops), exit (if it entered .BR _exit (2) or .BR exit_group (2)), @@ -1690,11 +1692,14 @@ indistinguishable from each other by the tracer. The tracer needs to keep track of the sequence of ptrace-stops in order to not misinterpret syscall-enter-stop as syscall-exit-stop or vice versa. -The rule is that syscall-enter-stop is +In general a syscall-enter-stop is always followed by syscall-exit-stop, .B PTRACE_EVENT stop or the tracee's death; no other kinds of ptrace-stop can occur in between. +However, note that seccomp stops (see below) can cause syscall-exit-stops, +without preceeding syscall-entry-stops. If seccomp is in use, care needs +to be taken not to mis-interpret such stops as syscall-entry-stops. .LP If after syscall-enter-stop, the tracer uses a restarting command other than @@ -1712,6 +1717,70 @@ set to .B SIGTRAP or .IR (SIGTRAP|0x80) . +.SS PTRACE_EVENT_SECCOMP stops (Linux 3.5 - 4.7) +The behavior of +.BR PTRACE_EVENT_SECCOMP +stops and their interaction with other kinds +of ptrace stops has changed between kernel versions. This documents the behavior +from their introduction until Linux 4.7 (inclusive). The behavior in later kernel +versions is documented in the next section. + +A +.BR PTRACE_EVENT_SECCOMP +stop occurs whenever a +.BR SECCOMP_RET_TRACE +rule is triggered. This is independent of which methods was used to restart +the system call. Notably, seccomp still runs even if the tracee +was restarted using +.BR PTRACE_SYSEMU +and this system call is unconditionally skipped. + +Restarts from this stop will behave as if the stop had occurred right +before the system call in question. In particular, both +.BR PTRACE_SYSCALL +and +.BR PTRACE_SYSEMU +will normally cause a subsequent syscall-entry-stop. However, if after the +.BR PTRACE_EVENT_SECCOMP +the system call number is negative, both the syscall-entry-stop +and the system call itself will be skipped. This means that if the +system call number is negative after a +.BR PTRACE_EVENT_SECCOMP +and the tracee is restarted using +.BR PTRACE_SYSCALL, +the next observed stop will be a syscall-exit-stop, +rather than the syscall-entry-stop +that may have been expected. + +.SS PTRACE_EVENT_SECCOMP stops (Linux 4.8+) + +In Linux 4.8, the +.BR PTRACE_EVENT_SECCOMP +stop was re-ordered to occur between syscall-entry-stop and +syscall-exit-stop. Note that, seccomp no longer +runs (and no `PTRACE_EVENT_SECCOMP` will be reported) if +the system call is skipped +due to +.BR PTRACE_SYSEMU +. + +Functionally, a PTRACE_EVENT_SECCOMP stop functions comparably +to a syscall-entry-stop (i.e. continuations using +.BR PTRACE_SYSCALL +will cause syscall-exit-stops, the system call number may be changed +and any other modified registers are visible to the to-be-executed syscall as well). +Note that there may, but need not have been a preceeding syscall-entry-stop. + +After a +.BR PTRACE_EVENT_SECCOMP +stop, seccomp will be re-run, with a +.BR SECCOMP_RET_TRACE +rule now functioning the same as a +.BR SECCOMP_RET_ALLOW +. Specifically, this means that if registers are not modified during the +.BR PTRACE_EVENT_SECCOMP +stop, the system call will then be allowed. + .SS PTRACE_SINGLESTEP stops [Details of these kinds of stops are yet to be documented.] .\" -- 2.8.1 -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
