From nobody Wed Dec 04 14:12:03 2024 X-Original-To: dev-commits-src-main@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4Y3KGC4nMkz5fdj4; Wed, 04 Dec 2024 14:12:03 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R10" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Y3KGC4Tbxz4NjM; Wed, 4 Dec 2024 14:12:03 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1733321523; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=GKBLonmcWy/9xzADzR7u7G3h1aWbFkkN+ftFA+bicy8=; b=aM7TjAmitxSToFk9qJHPCA47VGYLBxVMax3/u5waCDJbi80UkWCmqK7iMT9G3KWMkAtRrY 9ffgN7TvFq+JwicAGXZulhpM5EJyh48dk0ixHIadx28JpL/ZtpCw0/AkM0J3X7gZ3iok8H ALEwsPSap/Q3uMU+wjO8KN34l1ZfdR65AchaCGFFaSEWLMVKq2Z7A8c1yYuo6UGPM1UU3W I/r7Zhryqdj47Yq3NT5lkJhnowfd6y3Pz5fVPMOzcybOgfs/cIA3aRKdpGMMgdqNILoElP Q7NLeN0Uo8pqbuJSXT9j0X9jKdGPfkHNmzZZqlXk2qcc6Pe6+Q8Qc7VsMtcjzw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1733321523; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=GKBLonmcWy/9xzADzR7u7G3h1aWbFkkN+ftFA+bicy8=; b=kCxXOagr6PJDDU+bqrI4SUxYX41l/wD9dT3/NJFzX+4RASBsn5TF9HjTe01+igpcndTy2q FZNB0NKnfP2t5eyHgeobxTrm7BCcUepSud6ggiJ6GyfYlQ7uJXvWBJ2oDHumvMuUD8qU/v kT7v7wh3xLL1XvTRFOjR49tVpXwfeKPgP4GlfNGwgt41keLCL+qRIXLWKnC4q6d/kphcEU Rt+vc6UrEnVu8brURvp3cW/B4eiGjo9kg5pHNuKpaKJ7wagw/I3/aSkxK57xEnbbXfBn41 SVQoDaxPdGu1Q4j9j/MbsQ/k8Fxdw6tayk8B4qES6knHoB5p2Q2SkoEThKLv9g== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1733321523; a=rsa-sha256; cv=none; b=RafvTmv0h35mszDB285ZT8q/Vig+BzwEI1siQygYMhfZze9db1pJ8pAfkdwoe5KF087GSI 6hznAK4S+eDC3BewjHXNbFEu/nY2aVIDQ04CWAl33mb6fjDVyQ3wxIZ8J4ZKlstKjoA6L+ xJzmSptNiOJKcKSXHJVlNTV0sWzy+CjpDHtLNiSllB4JcMYaQrOboIAgCJWYkVYlzqxEI0 kmf86phniZeemtm+TxGdHtxi4+LMKT22es0LEXFijhLQ8/NPgdMKt7nDFP3jSaMi1WqaHN BHXLEbp1/kAYrwXYsHwuEsy226UNNRHpPAkpATLZHYwtbKoPmkZP1zFaA9OdAA== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4Y3KGC40bkz196q; Wed, 4 Dec 2024 14:12:03 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 4B4EC3Ig090128; Wed, 4 Dec 2024 14:12:03 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 4B4EC33C090125; Wed, 4 Dec 2024 14:12:03 GMT (envelope-from git) Date: Wed, 4 Dec 2024 14:12:03 GMT Message-Id: <202412041412.4B4EC33C090125@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: John Baldwin Subject: git: 8277c7901793 - main - procctl.2: Editing pass List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-main@freebsd.org Sender: owner-dev-commits-src-main@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: jhb X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 8277c790179304159c2e4dcb1d99552518d5be8e Auto-Submitted: auto-generated The branch main has been updated by jhb: URL: https://cgit.FreeBSD.org/src/commit/?id=8277c790179304159c2e4dcb1d99552518d5be8e commit 8277c790179304159c2e4dcb1d99552518d5be8e Author: John Baldwin AuthorDate: 2024-12-04 14:11:19 +0000 Commit: John Baldwin CommitDate: 2024-12-04 14:11:56 +0000 procctl.2: Editing pass - Add some missing .Pp macros after the end of literal blocks and some lists to ensure there is a blank line before the following text. - Use an indent of Ds for nested lists to reduce excessive indentation and make the bodies of the nested list items easier to read. - Various and sundry rewordings and clarifications. Reviewed by: kib, emaste Differential Revision: https://reviews.freebsd.org/D47782 --- lib/libsys/procctl.2 | 412 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 244 insertions(+), 168 deletions(-) diff --git a/lib/libsys/procctl.2 b/lib/libsys/procctl.2 index efb1812b284c..2d443a1ae4bd 100644 --- a/lib/libsys/procctl.2 +++ b/lib/libsys/procctl.2 @@ -27,7 +27,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd October 26, 2023 +.Dd December 4, 2024 .Dt PROCCTL 2 .Os .Sh NAME @@ -72,16 +72,16 @@ The control request to perform is specified by the argument. .Pp All status changing requests -.Dv *_CTL +.Pq Dv *_CTL require the caller to have the right to debug the target. All status query requests -.Dv *_STATUS +.Pq Dv *_STATUS require the caller to have the right to observe the target. .Pp The following commands are supported: .Bl -tag -width PROC_TRAPCAP_STATUS .It Dv PROC_ASLR_CTL -Controls the Address Space Layout Randomization (ASLR) in the program +Controls Address Space Layout Randomization (ASLR) in program images created by .Xr execve 2 @@ -89,28 +89,35 @@ in the specified process or its descendants that do not either change the control or modify it by other means. The .Fa data -parameter must point to the integer variable holding one of the following +parameter must point to an integer variable holding one of the following values: -.Bl -tag -width PROC_ASLR_FORCE_DISABLE +.Bl -tag -width Ds .It Dv PROC_ASLR_FORCE_ENABLE Request that ASLR is enabled after execution, even if it is disabled system-wide. -The image flag and set-uid might prevent ASLR enablement still. .It Dv PROC_ASLR_FORCE_DISABLE -Request that ASLR is disabled after execution. -Same notes as for -.Dv PROC_ASLR_FORCE_ENABLE -apply. +Request that ASLR is disabled after execution, even if it is enabled +system-wide. .It Dv PROC_ASLR_NOFORCE Use the system-wide configured policy for ASLR. .El +.Pp +Note that the +.Xr elfctl 1 +.Dq noaslr +flag takes precedence over this control. +Executing a binary with this flag set will never use ASLR. +Similarly, executing a set-user-ID or set-group-ID binary ignores this +control and only honors the +.Xr elfctl 1 +flag and system-wide policy. .It Dv PROC_ASLR_STATUS Returns the current status of ASLR enablement for the target process. The .Fa data -parameter must point to the integer variable, where one of the +parameter must point to an integer variable, where one of the following values is written: -.Bl -tag -width PROC_ASLR_FORCE_DISABLE +.Bl -tag -width Ds .It Dv PROC_ASLR_FORCE_ENABLE .It Dv PROC_ASLR_FORCE_DISABLE .It Dv PROC_ASLR_NOFORCE @@ -121,56 +128,79 @@ the .Dv PROC_ASLR_ACTIVE flag is or-ed with the value listed above. .It Dv PROC_PROTMAX_CTL -Controls implicit application of PROT_MAX protection equal to the -.Fa prot -argument of the +Controls the maximum protection used for .Xr mmap 2 -syscall, in the target process. +requests in the target process that do not specify +an explicit maximum protection in the +.Fa prot +argument via +.Dv PROT_MAX . +The maximum protection limits the permissions a mapping can be assigned by +.Xr mprotect 2 . +If an explicit maximum protection is not provided, +the maximum protection for a new mapping is set to either +.Dv PROT_READ | PROT_WRITE | PROT_EXEC +.Pq RWX +or the protection specified in +.Fa prot . +Mappings created with +.Fa prot +set to +.Dv PROT_NONE +always use RWX maximum protection. +.Pp The .Fa data -parameter must point to the integer variable holding one of the following +parameter must point to an integer variable holding one of the following values: -.Bl -tag -width PROC_PROTMAX_FORCE_DISABLE +.Bl -tag -width Ds .It Dv PROC_PROTMAX_FORCE_ENABLE -Enables implicit PROT_MAX application, -even if it is disabled system-wide by the sysctl +Use the permissions in +.Fa prot +as the implicit maximum protection, +even if RWX permissions are requested by the sysctl .Va vm.imply_prot_max . -The image flag might still prevent the enablement. .It Dv PROC_PROTMAX_FORCE_DISABLE -Request that implicit application of PROT_MAX be disabled. -Same notes as for -.Dv PROC_PROTMAX_FORCE_ENABLE -apply. +Use RWX as the implicit maximum protection, +even if constrained permissions are requested by the sysctl +.Va vm.imply_prot_max . .It Dv PROC_PROTMAX_NOFORCE -Use the system-wide configured policy for PROT_MAX. +Use the system-wide configured policy for the implicit PROT_MAX control. .El +.Pp +Note that the +.Xr elfctl 1 +.Dq noprotmax +flag takes precedence over this control. +Executing a binary with this flag set will always use RWX as the implicit +maximum protection. .It Dv PROC_PROTMAX_STATUS -Returns the current status of implicit PROT_MAX enablement for the +Returns the current status of the implicit PROT_MAX control for the target process. The .Fa data -parameter must point to the integer variable, where one of the +parameter must point to an integer variable, where one of the following values is written: -.Bl -tag -width PROC_PROTMAX_FORCE_DISABLE +.Bl -tag -width Ds .It Dv PROC_PROTMAX_FORCE_ENABLE .It Dv PROC_PROTMAX_FORCE_DISABLE .It Dv PROC_PROTMAX_NOFORCE .El .Pp -If the currently executed image in the process itself has implicit PROT_MAX -application enabled, the +If the currently executed image in the process itself has the implicit PROT_MAX +control enabled, the .Dv PROC_PROTMAX_ACTIVE flag is or-ed with the value listed above. .It Dv PROC_SPROTECT Set process protection state. This is used to mark a process as protected from being killed if the system -exhausts the available memory and swap. +exhausts available memory and swap. The .Fa data parameter must point to an integer containing an operation and zero or more optional flags. The following operations are supported: -.Bl -tag -width PPROT_CLEAR +.Bl -tag -width Ds .It Dv PPROT_SET Mark the selected processes as protected. .It Dv PPROT_CLEAR @@ -178,7 +208,7 @@ Clear the protected state of selected processes. .El .Pp The following optional flags are supported: -.Bl -tag -width PPROT_DESCEND +.Bl -tag -width Ds .It Dv PPROT_DESCEND Apply the requested operation to all child processes of each selected process in addition to each selected process. @@ -189,25 +219,41 @@ mark all future child processes of each selected process as protected. Future child processes will also mark all of their future child processes. .El .It Dv PROC_REAP_ACQUIRE -Acquires the reaper status for the current process. -Reaper status means that children orphaned by the reaper's descendants -that were forked after the acquisition of reaper status are reparented to the -reaper process. +Enable orphaned process reaping for future children of the current process. +.Pp +If a parent process exits before one or more of its children processes, +the remaining children processes are orphaned. +When an orphaned process exits, +it is reparented to a reaper process that is responsible for harvesting +the terminated process via +.Xr wait 2 . +When this control is enabled, +the current process becomes the reaper process for future children and their +descendants. +Existing child processes continue to use the reaper assigned when the child +was created via +.Xr fork 2 . +If a reaper process exits, +all of the processes for whom it was the reaper are reassigned to the reaper +process's reaper. +.Pp After system initialization, .Xr init 8 is the default reaper. .It Dv PROC_REAP_RELEASE -Release the reaper state for the current process. -The reaper of the current process becomes the new reaper of the -current process's descendants. +Disable orphaned process reaping for the current process. +.Pp +Any processes for whom the current process was the reaper are reassigned to +the current process's reaper. .It Dv PROC_REAP_STATUS -Provides information about the reaper of the specified process, -or the process itself when it is a reaper. +Provides a consistent snapshot of information about the reaper +of the specified process, +or the process itself if it is a reaper. The .Fa data argument must point to a .Vt procctl_reaper_status -structure which is filled in by the syscall on successful return. +structure which is filled in by the system call on successful return. .Bd -literal struct procctl_reaper_status { u_int rs_flags; @@ -217,16 +263,16 @@ struct procctl_reaper_status { pid_t rs_pid; }; .Ed +.Pp The .Fa rs_flags may have the following flags returned: -.Bl -tag -width REAPER_STATUS_REALINIT +.Bl -tag -width Ds .It Dv REAPER_STATUS_OWNED -The specified process has acquired reaper status and has not -released it. -When the flag is returned, the specified process +The specified process is a reaper. +When this flag is returned, the specified process .Fa id , -pid, identifies the reaper, otherwise the +pid, identifies a reaper, otherwise the .Fa rs_reaper field of the structure is set to the pid of the reaper for the specified process id. @@ -237,23 +283,25 @@ The specified process is the root of the reaper tree, i.e., .Pp The .Fa rs_children -field returns the number of children of the reaper among the descendants. +field returns the number of processes that can be reaped by the reaper that +are also children of the reaper. It is possible to have a child whose reaper is not the specified process, -since the reaper for any existing children is not reset on the -.Dv PROC_REAP_ACQUIRE -operation. +since the reaper for existing children is not changed by +.Dv PROC_REAP_ACQUIRE . The .Fa rs_descendants -field returns the total number of descendants of the reaper(s), -not counting descendants of the reaper in the subtree. +field returns the total number of processes that can be reaped by the reaper. The .Fa rs_reaper -field returns the reaper pid. +field returns the reaper's pid. The .Fa rs_pid -returns the pid of one reaper child if there are any descendants. +returns the pid of one reaper child if there are any processes that can be +reapead; +otherwise, it is set to \-1. .It Dv PROC_REAP_GETPIDS -Queries the list of descendants of the reaper of the specified process. +Queries the list of processes that can be reaped +by the reaper of the specified process. The request takes a pointer to a .Vt procctl_reaper_pids structure in the @@ -265,17 +313,15 @@ struct procctl_reaper_pids { struct procctl_reaper_pidinfo *rp_pids; }; .Ed +.Pp When called, the .Fa rp_pids field must point to an array of -.Vt procctl_reaper_pidinfo -structures, to be filled in on return, -and the .Fa rp_count -field must specify the size of the array, -into which no more than -.Fa rp_count -elements will be filled in by the kernel. +.Vt procctl_reaper_pidinfo +structures. +The kernel will populate these structures with information about the +reaper's descendants. .Pp The .Vt "struct procctl_reaper_pidinfo" @@ -290,17 +336,18 @@ struct procctl_reaper_pidinfo { u_int pi_flags; }; .Ed +.Pp The .Fa pi_pid field is the process id of the descendant. The .Fa pi_subtree -field provides the pid of the child of the reaper, which is the (grand-)parent -of the process. +field provides the pid of the direct child of the reaper which is +the (grand-)parent of the descendant process. The .Fa pi_flags field returns the following flags, further describing the descendant: -.Bl -tag -width REAPER_PIDINFO_EXITING +.Bl -tag -width Ds .It Dv REAPER_PIDINFO_VALID Set to indicate that the .Vt procctl_reaper_pidinfo @@ -314,7 +361,7 @@ of the returned array. .It Dv REAPER_PIDINFO_CHILD The .Fa pi_pid -field identifies the direct child of the reaper. +field identifies a direct child of the reaper. .It Dv REAPER_PIDINFO_REAPER The reported process is itself a reaper. The descendants of the subordinate reaper are not reported. @@ -341,6 +388,7 @@ struct procctl_reaper_kill { pid_t rk_fpid; }; .Ed +.Pp The .Fa rk_sig field specifies the signal to be delivered. @@ -350,7 +398,7 @@ The .Fa rk_flags field further directs the operation. It is or-ed from the following flags: -.Bl -tag -width REAPER_KILL_CHILDREN +.Bl -tag -width Ds .It Dv REAPER_KILL_CHILDREN Deliver the specified signal only to direct children of the reaper. .It Dv REAPER_KILL_SUBTREE @@ -359,6 +407,7 @@ the direct child with pid specified in the .Fa rk_subtree field. .El +.Pp If neither the .Dv REAPER_KILL_CHILDREN nor the @@ -376,22 +425,22 @@ field is set to the pid of the first process for which signal delivery failed, e.g., due to permission problems. If no such process exists, the .Fa rk_fpid -field is set to -1. +field is set to \-1. .It Dv PROC_TRACE_CTL Enable or disable tracing of the specified process(es), according to the value of the integer argument. -Tracing includes attachment to the process using the -.Xr ptrace 2 -and +Tracing includes inspecting the process via +.Xr ptrace 2 , .Xr ktrace 2 , debugging sysctls, .Xr hwpmc 4 , -.Xr dtrace 1 , -and core dumping. +or +.Xr dtrace 1 +as well as dumping core. Possible values for the .Fa data argument are: -.Bl -tag -width PROC_TRACE_CTL_DISABLE_EXEC +.Bl -tag -width Ds .It Dv PROC_TRACE_CTL_ENABLE Enable tracing, after it was disabled by .Dv PROC_TRACE_CTL_DISABLE . @@ -401,7 +450,7 @@ Disable tracing for the specified process. Tracing is re-enabled when the process changes the executing program with the .Xr execve 2 -syscall. +system call. A child inherits the trace settings from the parent on .Xr fork 2 . .It Dv PROC_TRACE_CTL_DISABLE_EXEC @@ -416,10 +465,10 @@ the integer variable pointed to by .Fa data . If tracing is disabled, .Fa data -is set to -1. +is set to \-1. If tracing is enabled, but no debugger is attached by the .Xr ptrace 2 -syscall, +system call, .Fa data is set to 0. If a debugger is attached, @@ -427,23 +476,24 @@ If a debugger is attached, is set to the pid of the debugger process. .It Dv PROC_TRAPCAP_CTL Controls the capability mode sandbox actions for the specified -sandboxed processes, -on a return from any syscall which gives either a +sandboxed processes +on a return from any system call which fails with either an .Er ENOTCAPABLE or .Er ECAPMODE error. -If the control is enabled, such errors from the syscalls cause -delivery of the synchronous +If this control is enabled and a system call fails with one of these errors, +a synchronous .Dv SIGTRAP -signal to the thread immediately before returning from the syscalls. +signal is delivered to the thread immediately before returning from the +system call. .Pp Possible values for the .Fa data argument are: -.Bl -tag -width PROC_TRAPCAP_CTL_DISABLE +.Bl -tag -width Ds .It Dv PROC_TRAPCAP_CTL_ENABLE -Enable the +Enable .Dv SIGTRAP signal delivery on capability mode access violations. The enabled mode is inherited by the children of the process, @@ -451,7 +501,9 @@ and is kept after .Xr fexecve 2 calls. .It Dv PROC_TRAPCAP_CTL_DISABLE -Disable the signal delivery on capability mode access violations. +Disable +.Dv SIGTRAP +signal delivery on capability mode access violations. Note that the global sysctl .Dv kern.trap_enotcap might still cause the signal to be delivered. @@ -463,7 +515,7 @@ On signal delivery, the .Va si_errno member of the .Fa siginfo -signal handler parameter is set to the syscall error value, +signal handler parameter is set to the system call error value, and the .Va si_code member is set to @@ -481,15 +533,18 @@ signal handler. .Pp See .Xr capsicum 4 -for more information about the capability mode. +for more information about capability mode. .It Dv PROC_TRAPCAP_STATUS -Return the current status of signalling capability mode access -violations for the specified process. +Return the current status of raising +.Dv SIGTRAP +for capability mode access violations by the specified process. The integer value pointed to by the .Fa data argument is set to the .Dv PROC_TRAPCAP_CTL_ENABLE -value if the process control enables signal delivery, and to +value if +.Dv SIGTRAP +delivery is enabled, and to .Dv PROC_TRAPCAP_CTL_DISABLE otherwise. .Pp @@ -528,39 +583,42 @@ must point to a memory location that can hold a value of type If signal delivery has not been requested, it will contain zero on return. .It Dv PROC_STACKGAP_CTL -Controls the stack gaps in the specified process. -A stack gap is the part of the growth area for a +Controls stack gaps in the specified process. +A stack gap is one or more virtual memory pages at the end of the +growth area for a .Dv MAP_STACK -mapped region that is reserved and never filled by memory. -Instead, the process is guaranteed to receive a +mapping that is reserved and never backed by memory. +Instead, the process is guaranteed to receive a synchronous .Dv SIGSEGV -signal on accessing pages in the gap. -Gaps protect against stack overflow corrupting memory adjacent -to the stack. +signal for each access to pages in the gap. +The number of pages reserved for each stack is set by the sysctl +.Va security.bsd.stack_guard_page . +.Pp +Gaps protect against stack overflows by preventing them from corrupting memory +adjacent to the stack. .Pp The .Fa data argument must point to an integer variable containing flags. The following flags are allowed: -.Bl -tag -width PROC_STACKGAP_DISABLE_EXEC +.Bl -tag -width Ds .It Dv PROC_STACKGAP_ENABLE This flag is only accepted for consistency with .Dv PROC_STACKGAP_STATUS . If stack gaps are enabled, the flag is ignored. -If disabled, the flag causes an -.Ev EINVAL -error to be returned. +If stack gaps are disabled, the request fails with +.Ev EINVAL . After gaps are disabled in a process, they can only be re-enabled when an .Xr execve 2 is performed. .It Dv PROC_STACKGAP_DISABLE Disable stack gaps for the process. -For existing stacks, the gap is no longer a reserved part of the growth -area and can be filled by memory on access. +For existing stacks, the gap is no longer reserved +and can be filled by memory on access. .It Dv PROC_STACKGAP_ENABLE_EXEC -Enable stack gaps for programs started after an +Enable stack gaps for the new address space constructed by any future .Xr execve 2 -by the specified process. +in the specified process. .It Dv PROC_STACKGAP_DISABLE_EXEC Inherit disabled stack gaps state after .Xr execve 2 . @@ -576,7 +634,7 @@ Returns the current stack gap state for the specified process. .Fa data must point to an integer variable, which is used to return a bitmask consisting of the following flags: -.Bl -tag -width PROC_STACKGAP_DISABLE_EXEC +.Bl -tag -width Ds .It Dv PROC_STACKGAP_ENABLE Stack gaps are enabled. .It Dv PROC_STACKGAP_DISABLE @@ -588,82 +646,99 @@ Stack gaps are enabled in the process after Stack gaps are disabled in the process after .Xr execve 2 . .El +.Pp +Note that the +.Xr elfctl 1 +.Dq nostackgap +flag takes precedence over this setting for individual process address spaces. +Executing a binary with this flag set will never use stack gaps in the address +space constructed by +.Xr execve 2 . +However, the controls value can still be inherited by child processes, and +executing a binary without this flag set will revert to the behavior specified +by the control. .It Dv PROC_NO_NEW_PRIVS_CTL -Allows one to ignore the SUID and SGID bits on the program +Allows one to ignore the set-user-ID and set-group-ID bits on the program images activated by .Xr execve 2 in the specified process and its future descendants. The .Fa data -parameter must point to the integer variable holding the following +parameter must point to an integer variable holding the following value: -.Bl -tag -width PROC_NO_NEW_PRIVS_ENABLE +.Bl -tag -width Ds .It Dv PROC_NO_NEW_PRIVS_ENABLE -Request SUID and SGID bits to be ignored. +Request set-user-ID and set-group-ID bits to be ignored. .El .Pp -It is not possible to disable it once it has been enabled. +It is not possible to disable this control once it has been enabled. .It Dv PROC_NO_NEW_PRIVS_STATUS -Returns the current status of SUID/SGID enablement for the target process. +Returns the current status of set-ID bits enablement for the target process. The .Fa data -parameter must point to the integer variable, where one of the +parameter must point to an integer variable, where one of the following values is written: -.Bl -tag -width PROC_NO_NEW_PRIVS_DISABLE +.Bl -tag -width Ds .It Dv PROC_NO_NEW_PRIVS_ENABLE .It Dv PROC_NO_NEW_PRIVS_DISABLE .El .It Dv PROC_WXMAP_CTL -Controls the 'write exclusive against execution' permissions for the -mappings in the process address space. -It overrides the global settings established by the -.Dv kern.elf{32/64}.allow_wx -sysctl, -and the corresponding bit in the ELF control note, see -.Xr elfctl 1 . -.Pp +Controls the creation of mappings with both write and execute permissions +in a process's address space. The .Fa data -parameter must point to the integer variable holding one of the +parameter must point to an integer variable holding one of the following values: -.Bl -tag -width PROC_WX_MAPPINGS_DISALLOW_EXEC +.Bl -tag -width Ds .It Dv PROC_WX_MAPPINGS_PERMIT Enable creation of mappings that have both write and execute -protection attributes, in the specified process' address space. +permissions in the specified process' current and future address spaces. .It Dv PROC_WX_MAPPINGS_DISALLOW_EXEC -In the new address space created by +In a new address space created by a future call to .Xr execve 2 , disallow creation of mappings that have both write and execute permissions. .El .Pp -Once creation of writeable and executable mappings is allowed, -it is impossible (and pointless) to disallow it. +If both flags are set, +.Dv PROC_WX_MAPPINGS_DISALLOW_EXEC +takes precedence during +.Xr execve 2 . +If neither flag is set, +mappings with write and execute permissions are only permitted if the +.Dv kern.elf{32/64}.allow_wx +sysctl is non-zero or the +.Xr elfctl 1 +.Dq wxneeded +flag is set in the ELF control note. +.Pp +Once creation of writeable and executable mappings is enabled for a process, +it is impossible (and pointless) to disable it. The only way to ensure the absence of such mappings after they -were enabled in a given process, is to set the +were enabled in a given process is to set the .Dv PROC_WX_MAPPINGS_DISALLOW_EXEC flag and .Xr execve 2 an image. .It Dv PROC_WXMAP_STATUS -Returns the current status of the 'write exclusive against execution' -enforcement for the specified process. +Returns the current status of the controls over creation of mappings with +both write and execute permissions for the specified process. The .Dv data -parameter must point to the integer variable, where one of the +parameter must point to an integer variable, where one of the following values is written: -.Bl -tag -width PROC_WX_MAPPINGS_DISALLOW_EXEC +.Bl -tag -width Ds .It Dv PROC_WX_MAPPINGS_PERMIT -Creation of simultaneously writable and executable mapping is permitted, -otherwise the process cannot create such mappings. +Creation of simultaneously writable and executable mappings are permitted; +otherwise, the process cannot create such mappings. .It Dv PROC_WX_MAPPINGS_DISALLOW_EXEC After .Xr execve 2 , -the new address space should disallow creation of simultaneously +the new address space will not permit creation of simultaneously writable and executable mappings. .El .Pp -Additionally, if the address space of the process disallows +Additionally, if the address space of the process does not permit creation of simultaneously writable and executable mappings and it is guaranteed that no such mapping was created since address space creation, the @@ -676,19 +751,18 @@ flag is set in the returned value. AMD64 only. Controls the Kernel Page Table Isolation (KPTI) option for the children of the specified process. -For the command to work, the +This control is only meaningful if KPTI has been enabled globally by the .Va vm.pmap.kpti -tunable must be enabled on boot. +tunable. It is not possible to change the KPTI setting for a running process, -except at the -.Xr execve 2 , -where the address space is reinitialized. +only for new address spaces constructed by a future +.Xr execve 2 . .Pp The .Fa data parameter must point to an integer variable containing one of the following commands: -.Bl -tag -width PROC_KPTI_CTL_DISABLE_ON_EXEC +.Bl -tag -width Ds .It Dv PROC_KPTI_CTL_ENABLE_ON_EXEC Enable KPTI after .Xr execve 2 . @@ -697,36 +771,36 @@ Disable KPTI after .Xr execve 2 . Only root or a process having the .Va PRIV_IO -privilege might use this option. +privilege can use this option. .El .It Dv PROC_KPTI_STATUS Returns the current KPTI status for the specified process. .Fa data -must point to the integer variable, which returns the -following statuses: -.Bl -tag -width PROC_KPTI_CTL_DISABLE_ON_EXEC +must point to an integer variable, where one of the +following values is written: +.Bl -tag -width Ds .It Dv PROC_KPTI_CTL_ENABLE_ON_EXEC .It Dv PROC_KPTI_CTL_DISABLE_ON_EXEC .El .Pp -The status is or-ed with the +The status is or-ed with .Va PROC_KPTI_STATUS_ACTIVE -in case KPTI is active for the current address space of the process. +if KPTI is active for the current address space of the process. .El .Sh NOTES Disabling tracing on a process should not be considered a security -feature, as it is bypassable both by the kernel and privileged processes, +feature, as it is bypassable both by the kernel and privileged processes and via other system mechanisms. As such, it should not be utilized to reliably protect cryptographic keying material or other confidential data. .Pp Note that processes can trivially bypass the 'no simultaneously writable and executable mappings' policy by first marking some mapping -as writeable and write code to it, then removing write and adding +as writeable, writing code to it, then removing write and adding execute permission. -This may be legitimately required by some programs, such as JIT compilers. +This may be legitimately required by some programs such as JIT compilers. .Sh RETURN VALUES -If an error occurs, a value of -1 is returned and +If an error occurs, a value of \-1 is returned and .Va errno is set to indicate the error. .Sh ERRORS @@ -786,22 +860,21 @@ An invalid or zero signal number was requested for a .Dv PROC_REAP_KILL request. .It Bq Er EINVAL -The +A .Dv PROC_REAP_RELEASE request was issued by the .Xr init 8 process. .It Bq Er EBUSY -The +A .Dv PROC_REAP_ACQUIRE -request was issued by a process that had already acquired reaper status -and has not yet released it. +request was issued by a process that is already a reaper process. .It Bq Er EBUSY -The +A .Dv PROC_TRACE_CTL -request was issued for a process already being traced. +request was issued for a process being traced. .It Bq Er EPERM -The +A .Dv PROC_TRACE_CTL request to re-enable tracing of the process .Po Dv PROC_TRACE_CTL_ENABLE Pc , @@ -809,7 +882,7 @@ or to disable persistence of .Dv PROC_TRACE_CTL_DISABLE on .Xr execve 2 -was issued for a non-current process. +specified a target process other than the calling process. .It Bq Er EINVAL The value of the integer .Fa data @@ -830,6 +903,7 @@ or invalid signal number. .El .Sh SEE ALSO .Xr dtrace 1 , +.Xr elfctl 1 , .Xr proccontrol 1 , .Xr protect 1 , .Xr cap_enter 2 , @@ -848,15 +922,17 @@ The function appeared in .Fx 9.3 . .Pp -The reaper facility is based on a similar feature of Linux and +The reaper facility is based on a similar feature in Linux and DragonflyBSD, and first appeared in .Fx 10.2 . .Pp The .Dv PROC_PDEATHSIG_CTL -facility is based on the prctl(PR_SET_PDEATHSIG, ...) feature of Linux, +facility is based on the +.Ql prctl(PR_SET_PDEATHSIG, ...) +feature in Linux, and first appeared in .Fx 11.2 . .Pp -The ASLR support was added to system for the checklists compliance in +ASLR support was added for checklist compliance in .Fx 13.0 .