.\"-
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.\" Copyright (c) 2024, Baptiste Daroussin <bapt@FreeBSD.org>
.\" Copyright (c) 2024, 2026, The FreeBSD Foundation
.\"
.\" Portions of this documentation were written by Olivier Certner
.\" <olce@FreeBSD.org> at Kumacom SARL under sponsorship from the FreeBSD
.\" Foundation.
.\"
.Dd May 21, 2026
.Dt MAC_DO 4
.Os
.Sh NAME
.Nm mac_do
.Nd "policy allowing unprivileged users to change process credentials"
.Sh SYNOPSIS
To compile the
.Sy mac_do
policy into your kernel, place the following lines in your kernel configuration
file:
.Bd -ragged -offset indent
.Cd "options MAC"
.Cd "options MAC_DO"
.Ed
.Pp
Alternately, to load this policy module at boot time, place the following line
in your kernel configuration file:
.Bd -ragged -offset indent
.Cd "options MAC"
.Ed
.Pp
and in
.Xr loader.conf 5 :
.Bd -literal -offset indent
mac_do_load="YES"
.Ed
.Sh DESCRIPTION
The
.Nm
policy module allows unprivileged users to change process credentials according
to rules configured by the administrator.
It supports per-jail configuration.
.Pp
The
.Nm
policy module only produces effects on processes spawned from specific
executables from a configurable whitelist.
By default, this whitelist only contains the
.Pa /usr/bin/mdo
executable, please see
.Xr mdo 1
for more details on this program.
.Pp
Section
.Sx CREDENTIALS RULES
specifies the format of credentials transition rules, and section
.Sx CONFIGURATION
explains how to configure
.Nm ,
including rules and authorized executables.
.Sh CREDENTIALS RULES
Rules specify which transitions of process credentials
.Nm
will allow, based on current process credentials and the desired final ones.
They are passed by an administrator in the form of a string having the specific
syntax described below in a top-bottom manner.
They have been designed to be able to finely describe the desired target
credentials in a safe and compact way.
.Ss Top-Level List of Rules
At the top, rules are a possibly empty list of individual rules separated by
a semi-colon
.Pq Ql ";" :
.Dl Ao rules Ac \ ⟶\  Oo Ao rule Ac Oo So ";" Sc Ao rule Ac Oc Ns * Oc
They form a disjunction, i.e.,
.Nm
authorizes a credentials transition as soon as at least one rule in the list
matches.
.Pp
One rule is composed of a
.Li Aq from
part
.Pq also called Dq match
and a
.Li Aq to
part
.Pq also called Dq target ,
in this order, separated by a greater-than sign
.Pq Ql > :
.Dl Ao rule Ac \ ⟶\  Ao from Ac So > Sc Ao to Ac
.Ss Rule's Ao from Ac Part
The first part of a rule,
.Li Aq from ,
is matched against the credentials of the process requesting some credentials
transition.
It has the form:
.Dl Ao from Ac \ ⟶\  Ao type Ac So = Sc Ao id Ac
.Pp
.Li Aq type
must be:
.Dl Ao type Ac \ ⟶\  Op So uid Sc | So gid Sc
i.e., one of the literal strings
.Ql uid
or
.Ql gid .
.Li Aq id
must be the numerical ID of a user or group and is matched against the current
process real ID of the corresponding type, and on type
.Ql gid
additionally against the supplementary groups.
.Ss Rule's Ao to Ac Part
The second part of a rule,
.Li Aq to ,
is a comma-separated
.Pq Ql ","
non-empty list of target clauses:
.Dl Ao to Ac \ ⟶\  Ao target_clause Ac Oo So "," Sc Ao target_clause Ac Oc Ns *
Target clauses of a given rule also form a disjunction, i.e., the IDs they
specify are alternatives for the target credentials, except in some cases
described below.
.Pp
The next subsections describe the syntax of target clauses, the defaults that
apply and the principle of non-redundancy and non-contradiction in each rule's
.Li Aq to
part.
.Ss Target Clauses
A target clause in a rule's
.Li Aq to
part must be of one of the following forms:
.Dl Ao target_clause Ac \ ⟶\  So any Sc
.Dl Ao target_clause Ac \ ⟶\  Ao flags Ac Ao type Ac So = Sc Ao id Ac
The first form is a compact way to specify that any target credentials are
allowed.
The second form is similar to that of
.Li Aq from
clauses, with the following extensions:
.Bl -bullet -compact
.It
.Li Aq id
may also be a literal
.Ql *
or
.Ql any
or
.Ql "." .
.Ql *
and
.Ql any
both designate any ID for the specified
.Li Aq type ,
and are treated identically.
.Ql "."
designates the process' current IDs for the specified
.Li Aq type ,
as explained below.
.It
.Li Aq flags
may contain at most one of the
.Ql + ,
.Ql -
and
.Ql "!"
characters, and may be non-empty only when
.Li Aq type
is
.Ql gid .
Additionally, if
.Li Aq id
is
.Ql *
or
.Ql any ,
only the
.Ql +
flag may appear.
.El
.Pp
For target clauses of
.Ql gid
type, an absence of flag indicates that the specified group ID is allowed as the
real, effective and/or saved group IDs
.Pq the Do primary Dc groups .
Conversely, the presence of any allowed flag indicates that the specification
concerns supplementary groups.
Each flag has a specific meaning:
.Bl -bullet -compact
.It
.Ql +
indicates that the group ID is allowed as a supplementary group.
.It
.Ql "!"
indicates that the group ID is mandatory, i.e., it must be listed in the
supplementary groups.
.It
.Ql -
indicates that the group ID must not be listed in the supplementary groups.
.El
A specification with
.Ql -
is only useful in conjunction with a
.Ql + Ns
-tagged specification where only one of them has
.Ql "."
as its
.Li Aq id .
Target clauses having the
.Ql "!"
or
.Ql -
flag are
.Dq forcing
clauses, and as such do not take part in the disjunction of the other
target clauses but rather unconditionally apply in their rule.
.Pp
.Ql "."
is a placeholder for IDs that the calling process already has on privilege
check.
For type
.Ql uid ,
it designates any of the process' real, effective or
saved user IDs.
For type
.Ql gid ,
its effect depends on whether flags are present.
If none is present, it designates any of the process' real, effective or saved
group IDs.
If one is present, it designates any of the process' supplementary groups.
.Ss Defaults for the Ao to Ac Part
If the
.Li Aq to
part does not list a target clause with type
.Ql uid ,
any of the current user IDs of the calling process is accepted.
In other words, in this case,
.Nm
behaves as if a target clause of:
.Dl uid=.
had been listed.
.Pp
Similarly, if the
.Li Aq to
part does not list a target clause with type
.Ql gid ,
all the groups of the calling process are assumed to be required.
More precisely, each of the desired real, effective and saved group IDs must be
one of the current real, effective or saved group ID, and all supplementary
groups must be the same as those that are current.
It is as if the
.Li Aq to
part had contained the following two clauses:
.Dl gid=.,!gid=.
.Ss Non-Redundancy and Non-Contradiction in a Ao to Ac Part
No two target clauses of a single rule may express the exact same logical intent
nor contradictory ones.
.Pp
In practice, no two clauses may display the same ID except for group IDs but
only if, each time the same ID appears, it does so with a different flag, or no
flags only once.
Additionally, the specified flags in multiple occurrences must not be
contradictory.
For example, the same group ID appearing with both
.Ql +
and
.Ql -
will cause rejection of the rule.
.Ss Parsing Specifics
Any amount of whitespace is allowed around tokens of the above grammar, except
that there may be no spaces between
.Li Aq flags
and
.Li Aq id
in target clauses.
.Pp
For convenience, numerical IDs may be specified as negative integers, which are
then converted to unsigned ones as specified in the C standard for the
.Vt uid_t
and
.Vt gid_t
types, which are both 32-bit unsigned integers.
.Sh CONFIGURATION
Each parameter of
.Nm
has a corresponding
.Xr sysctl 8
knob.
.Nm
supports per-jail values for most parameters.
.Ss Sysctl Knobs
The
.Xr sysctl 8
knobs presented by
.Nm
are of two types: Global ones, which influence all uses of the module, and
per-jail ones, which allow to retrieve or change the setting applicable to
a jail
.Pq or the host
from within.
They are tagged accordingly in the list below.
.Pp
The indicated default values for per-jail parameters applies to the host.
Those applying to jails are described in the
.Sx Jail Parameters
subsection below.
.Pp
The following knobs are available:
.Bl -tag -width indent
.It Va security.mac.do.enabled
Enable the
.Nm
policy.
.Pq Global. Default: 1.
.It Va security.mac.do.print_parse_error
Logs a message on trying to set incorrect rules via the
.Va security.mac.do.rules
.Xr sysctl 8
knob.
.Pq Global. Default: 1.
.It Va security.mac.do.rules
The list of credentials transition rules, whose syntax is described in the
.Sx CREDENTIALS RULES
section above.
An empty string effectively disables the policy.
.Pq Per-jail. Default: Empty.
.It Va security.mac.do.exec_paths
The list of absolute paths
.Pq relative to the current jail's root
to authorized executables, separated by colons
.Pq Ql ":" .
Only processes launched from these executables are considered by the
.Nm
policy.
An empty string effectively disables the policy.
.Po
Per-jail. Default:
.Ql "/usr/bin/mdo" .
.Pc
.El
.Ss Jail Parameters
Most parameters of
.Nm
are per-jail
.Po
see the
.Sx "Sysctl Knobs"
subsection above
.Pc .
Those that are per-jail have corresponding jail parameters that can be used to
set their initial values on jail creation or modify their values in a running
jail from outside the jail.
.Pp
By default, as it is for the host, a new jail has
.Nm
disabled for its processes, as if the
.Va mac.do
parameter below was explicitly set to
.Ql disable .
.Pp
Each unspecified parameter other than
.Va mac.do
defaults to a copy of its value in the currently applicable configuration for
a running jail, or from the parent jail on jail creation.
.Pp
The following jail parameters are available:
.Bl -tag -width indent
.It Va mac.do
Possible values are:
.Pp
.Bl -tag -width "'disable'" -compact
.It Ql new
.Nm
will use a specific configuration for the jail.
This case degrades to
.Ql disable
if one of the other jail parameters end up empty after applying the default
values rule
.Pq see the preamble .
.It Ql disable
Disables
.Nm
in the jail.
This is achieved by ensuring that at least one of the
.Va mac.do.rules
and
.Va mac.do.exec_paths
jail parameters are empty.
If none of them ends up empty after applying the default values rule
.Pq see the preamble ,
.Va mac.do.rules
is forced to an empty value.
An explicit
.Ql disable
is incompatible with explicit non-empty values for all other jail parameters and
will trigger an error.
.It Ql inherit
The other per-jail parameters are inherited from those applicable to the jail's
parent
.Pq which may themselves have been inherited .
Configuration modifications immediately propagate to all descendant jails
configured for inheritance
.Po
as long as there is no intervening jail having its own specific configuration
.Pc .
.El
.Pp
The default value depends on the absence or presence and value of the other jail
parameters.
As soon as one of the latter is present and not empty, the default value is
.Ql new ,
else it is
.Ql disable .
Inheritance is never established implicitly, it must be explicitly requested.
.It Va mac.do.rules
The credentials rules for the jail.
See the description of the corresponding
.Xr sysctl 8
knob
.Va security.mac.do.rules
in subsection
.Sx "Sysctl Knobs"
above.
See also the preamble for the default values rule.
.It Va mac.do.exec_paths
The authorized executables.
See the description of the corresponding
.Xr sysctl 8
knob
.Va security.mac.do.exec_paths
in subsection
.Sx "Sysctl Knobs"
above.
See also the preamble for the default values rule.
.El
.Ss Consistency
Values read or set from jail parameters are always consistent with their
corresponding
.Xr sysctl 8
knobs, effectively operating on the same internal
.Dq variable .
.Pp
All accesses to some parameter or some jail configuration as a whole, whether
a read or a modification, are sequentially consistent.
In other words, they appear to be atomic, and all threads see them happening in
the same order.
.Sh EXAMPLES
Here are several examples of single rules matching processes having a real user
ID of 10001:
.Bl -tag -width indent
.It Li uid=10001>uid=10002
Allows the process to switch all of its real, effective or saved user ID to
10002, but keeping the groups it is already in, and with the same
primary/supplementary groups split.
.It Li uid=10001>uid=10002,uid=10003
Same as the first example, but also allows to switch to UID 10003 instead of
10002, or possibly having both in different user IDs.
.It Li uid=10001>uid=10002,gid=10002
Same as the first example, but the new primary groups must be set to 10002 and
no supplementary groups should be set.
.It Li uid=10001>uid=10002,gid=10002,+gid=.\&
Same as the previous example, but in addition allowing to retain any current
supplementary groups.
.It Li uid=10001>uid=10002,gid=10002,!gid=.\&
Same as the previous example, but with the additional constraint that all
current supplementary groups must be kept.
.It Li uid=10001>uid=10002,gid=10002,+gid=.,-gid=10001
Same as
.Ql uid=10001>uid=10002,gid=10002,+gid=.\&
above, but 10001 cannot be retained as a supplementary group.
.It Li uid=10001>uid=10002,gid=10002,+gid=.,!gid=10003
Same as
.Ql uid=10001>uid=10002,gid=10002,+gid=.\&
above, with the additional constraint that 10003 must appear in the
supplementary groups.
.It Li uid=10001>uid=10002,gid=*,+gid=*
Same as the first example, but lifting any constraints on groups, allowing the
process to become part of any groups it sees fit.
.El
.Pp
Here are several examples of single rules matching processes having 10001 as
their real group IDs or in their supplementary groups:
.Bl -tag -width indent
.It Li gid=10001>uid=0
Makes 10001 a more powerful
.Ql wheel
group, allowing its members to switch to root without password.
.It Li gid=10001>gid=10002
Allows the process to enter GID 10002 as a primary group, but only if
giving up all its supplementary groups.
.It Li gid=10001>gid=10002,+gid=.\&
Same as the previous example, but allows to retain any current supplementary
groups.
.It Li gid=10001>gid=10002,!gid=.\&
Same as the previous example, but with the additional constraint that all
current supplementary groups must be kept.
.El
.Sh SEE ALSO
.Xr mdo 1 ,
.Xr setcred 2 ,
.Xr mac 4 ,
.Xr jail 8 ,
.Xr sysctl 8
.Sh AUTHORS
.An Olivier Certner Aq Mt olce@FreeBSD.org
.An Baptiste Daroussin Aq Mt bapt@FreeBSD.org
.An Kushagra Srivastava Aq Mt kushagra1403@gmail.com
.Sh BUGS
Currently,
.Nm
considers only credentials transitions requested through the
.Xr setcred 2
system call.
This system call was in large part created so that
.Nm
can see whole credentials transitions to decide whether to authorize them, which
the traditional UNIX's piecewise approach of successively changing different
parts of them cannot allow.
.Pp
However, calls to traditional or standard credentials-changing functions can be
considered as full transitions on their own, however limited, and as such should
be equally monitored by
.Nm .
Future work will lift this restriction.
.Sh SECURITY CONSIDERATIONS
The threat model for
.Nm
is to consider userland programs as generally untrustable to decide upon which
credentials changes are acceptable.
It is in contrast with the traditional UNIX way to change credentials, in which
specialized programs are installed with the setuid bit, giving them full
administrator privileges so that they are effectively able to establish new
ones.
Vulnerabilities in such credentials-changing programs can have catastrophic
consequences on the integrity of the system.
.Pp
Consequently,
.Nm
does not rely on companion userland programs to decide whether some credentials
transition is acceptable.
Instead, it maintains its own configuration independently from the userland
password and group databases.
Establishing this configuration currently itself relies on userland programs
issuing calls to
.Xr sysctl 3
or
.Xr jail 2 .
It should thus be established near system boot or jail start, before any
possible attacks could happen on the system, and further measures should be
taken to ensure that potential corruptions does not affect the configuration in
subsequent restarts, such as re-establishing pristine state or ensuring that the
boot procedure up to the configuration of
.Nm
can be trusted.