diff options
Diffstat (limited to 'static/freebsd/man4/mac_do.4 3.html')
| -rw-r--r-- | static/freebsd/man4/mac_do.4 3.html | 380 |
1 files changed, 0 insertions, 380 deletions
diff --git a/static/freebsd/man4/mac_do.4 3.html b/static/freebsd/man4/mac_do.4 3.html deleted file mode 100644 index 90ecc0ad..00000000 --- a/static/freebsd/man4/mac_do.4 3.html +++ /dev/null @@ -1,380 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">MAC_DO(4)</td> - <td class="head-vol">Device Drivers Manual</td> - <td class="head-rtitle">MAC_DO(4)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">mac_do</code> — <span class="Nd">policy - allowing unprivileged users to change process credentials</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp">To compile the - <a class="permalink" href="#mac_do"><b class="Sy" id="mac_do">mac_do</b></a> - policy into your kernel, place the following lines in your kernel - configuration file:</p> -<div class="Bd Pp Bd-indent"><code class="Cd">options MAC</code> -<br/> -<code class="Cd">options MAC_DO</code></div> -<p class="Pp">Alternately, to load this policy module at boot time, place the - following line in your kernel configuration file:</p> -<div class="Bd Pp Bd-indent"><code class="Cd">options MAC</code></div> -<p class="Pp">and in <a class="Xr">loader.conf(5)</a>:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>mac_do_load="YES"</pre> -</div> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">mac_do</code> policy module allows - unprivileged users to change process credentials according to rules - configured by the administrator. It supports per-jail configuration.</p> -<p class="Pp">Currently, the <code class="Nm">mac_do</code> policy module only - produces effects to processes spawned from the - <span class="Pa">/usr/bin/mdo</span> executable, please see - <a class="Xr">mdo(1)</a> for more details on this program.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="CREDENTIALS_RULES"><a class="permalink" href="#CREDENTIALS_RULES">CREDENTIALS - RULES</a></h1> -<p class="Pp">Rules specify which transitions of process credentials - <code class="Nm">mac_do</code> 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.</p> -<section class="Ss"> -<h2 class="Ss" id="Top-Level_List_of_Rules"><a class="permalink" href="#Top-Level_List_of_Rules">Top-Level - List of Rules</a></h2> -<p class="Pp">At the top, rules are a possibly empty list of individual rules - separated by a semi-colon (‘<code class="Li">;</code>’):</p> -<div class="Bd Bd-indent"><code class="Li">⟨rules⟩ -  ⟶  [⟨rule⟩ [‘;’ - ⟨rule⟩]*]</code></div> -They form a disjunction, i.e., <code class="Nm">mac_do</code> authorizes a - credentials transition as soon as at least one rule in the list matches. -<p class="Pp">One rule is composed of a ⟨from⟩ part (also called - “match”) and a ⟨to⟩ part (also called - “target”), in this order, separated by a greater-than sign - (‘<code class="Li">></code>’):</p> -<div class="Bd Bd-indent"><code class="Li">⟨rule⟩ -  ⟶  ⟨from⟩ ‘>’ - ⟨to⟩</code></div> -</section> -<section class="Ss"> -<h2 class="Ss" id="Rule's_from_Part"><a class="permalink" href="#Rule's_from_Part">Rule's - ⟨from⟩ Part</a></h2> -<p class="Pp">The first part of a rule, ⟨from⟩, is matched against - the credentials of the process requesting some credentials transition. It - has the form:</p> -<div class="Bd Bd-indent"><code class="Li">⟨from⟩ -  ⟶  ⟨type⟩ ‘=’ - ⟨id⟩</code></div> -<p class="Pp">⟨type⟩ must be:</p> -<div class="Bd Bd-indent"><code class="Li">⟨type⟩ -  ⟶  [‘uid’ | - ‘gid’]</code></div> -i.e., one of the literal strings ‘<code class="Li">uid</code>’ or - ‘<code class="Li">gid</code>’. ⟨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 - ‘<code class="Li">gid</code>’ additionally against the - supplementary groups. -</section> -<section class="Ss"> -<h2 class="Ss" id="Rule's_to_Part"><a class="permalink" href="#Rule's_to_Part">Rule's - ⟨to⟩ Part</a></h2> -<p class="Pp">The second part of a rule, ⟨to⟩, is a - comma-separated (‘<code class="Li">,</code>’) non-empty list - of target clauses:</p> -<div class="Bd Bd-indent"><code class="Li">⟨to⟩ -  ⟶  ⟨target_clause⟩ [‘,’ - ⟨target_clause⟩]*</code></div> -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. -<p class="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 ⟨to⟩ part.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Target_Clauses"><a class="permalink" href="#Target_Clauses">Target - Clauses</a></h2> -<p class="Pp">A target clause in a rule's ⟨to⟩ part must be of one - of the following forms:</p> -<div class="Bd Bd-indent"><code class="Li">⟨target_clause⟩ -  ⟶  ‘any’</code></div> -<div class="Bd Bd-indent"><code class="Li">⟨target_clause⟩ -  ⟶  ⟨flags⟩ ⟨type⟩ - ‘=’ ⟨id⟩</code></div> -The first form is a compact way to specify that any target credentials are - allowed. The second form is similar to that of ⟨from⟩ clauses, - with the following extensions: -<ul class="Bl-bullet Bl-compact"> - <li>⟨id⟩ may also be a literal - ‘<code class="Li">*</code>’ or - ‘<code class="Li">any</code>’ or - ‘<code class="Li">.</code>’. - ‘<code class="Li">*</code>’ and - ‘<code class="Li">any</code>’ both designate any ID for the - specified ⟨type⟩, and are treated identically. - ‘<code class="Li">.</code>’ designates the process' current - IDs for the specified ⟨type⟩, as explained below.</li> - <li>⟨flags⟩ may contain at most one of the - ‘<code class="Li">+</code>’, - ‘<code class="Li">-</code>’ and - ‘<code class="Li">!</code>’ characters, and may be non-empty - only when ⟨type⟩ is - ‘<code class="Li">gid</code>’. Additionally, if - ⟨id⟩ is ‘<code class="Li">*</code>’ or - ‘<code class="Li">any</code>’, only the - ‘<code class="Li">+</code>’ flag may appear.</li> -</ul> -<p class="Pp">For target clauses of ‘<code class="Li">gid</code>’ - type, an absence of flag indicates that the specified group ID is allowed as - the real, effective and/or saved group IDs (the “primary” - groups). Conversely, the presence of any allowed flag indicates that the - specification concerns supplementary groups. Each flag has a specific - meaning:</p> -<ul class="Bl-bullet Bl-compact"> - <li>‘<code class="Li">+</code>’ indicates that the group ID is - allowed as a supplementary group.</li> - <li>‘<code class="Li">!</code>’ indicates that the group ID is - mandatory, i.e., it must be listed in the supplementary groups.</li> - <li>‘<code class="Li">-</code>’ indicates that the group ID must - not be listed in the supplementary groups.</li> -</ul> -A specification with ‘<code class="Li">-</code>’ is only useful in - conjunction with a ‘<code class="Li">+</code>’-tagged - specification where only one of them has - ‘<code class="Li">.</code>’ as its ⟨id⟩. Target - clauses having the ‘<code class="Li">!</code>’ or - ‘<code class="Li">-</code>’ flag are “forcing” - clauses, and as such do not take part in the disjunction of the other target - clauses but rather unconditionally apply in their rule. -<p class="Pp">‘<code class="Li">.</code>’ is a placeholder for IDs - that the calling process already has on privilege check. For type - ‘<code class="Li">uid</code>’, it designates any of the - process' real, effective or saved user IDs. For type - ‘<code class="Li">gid</code>’, 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.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Defaults_for_the_to_Part"><a class="permalink" href="#Defaults_for_the_to_Part">Defaults - for the ⟨to⟩ Part</a></h2> -<p class="Pp">If the ⟨to⟩ part does not list a target clause with - type ‘<code class="Li">uid</code>’, any of the current user - IDs of the calling process is accepted. In other words, in this case, - <code class="Nm">mac_do</code> behaves as if a target clause of:</p> -<div class="Bd Bd-indent"><code class="Li">uid=.</code></div> -had been listed. -<p class="Pp">Similarly, if the ⟨to⟩ part does not list a target - clause with type ‘<code class="Li">gid</code>’, 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 ⟨to⟩ part had - contained the following two clauses:</p> -<div class="Bd Bd-indent"><code class="Li">gid=.,!gid=.</code></div> -</section> -<section class="Ss"> -<h2 class="Ss" id="Non-Redundancy_and_Non-Contradiction_in_a_to_Part"><a class="permalink" href="#Non-Redundancy_and_Non-Contradiction_in_a_to_Part">Non-Redundancy - and Non-Contradiction in a ⟨to⟩ Part</a></h2> -<p class="Pp">No two target clauses of a single rule may express the exact same - logical intent nor contradictory ones.</p> -<p class="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 ‘<code class="Li">+</code>’ and - ‘<code class="Li">-</code>’ will cause rejection of the - rule.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Parsing_Specifics"><a class="permalink" href="#Parsing_Specifics">Parsing - Specifics</a></h2> -<p class="Pp">Any amount of whitespace is allowed around tokens of the above - grammar, except that there may be no spaces between ⟨flags⟩ - and ⟨id⟩ in target clauses.</p> -<p class="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 <var class="Vt">uid_t</var> and <var class="Vt">gid_t</var> - types, which are both 64-bit unsigned integers.</p> -</section> -</section> -<section class="Sh"> -<h1 class="Sh" id="RUNTIME_CONFIGURATION"><a class="permalink" href="#RUNTIME_CONFIGURATION">RUNTIME - CONFIGURATION</a></h1> -<p class="Pp">The following <a class="Xr">sysctl(8)</a> knobs are available:</p> -<dl class="Bl-tag"> - <dt id="security.mac.do.enabled"><var class="Va">security.mac.do.enabled</var></dt> - <dd>Enable the <code class="Nm">mac_do</code> policy. (Default: 1).</dd> - <dt id="security.mac.do.rules"><var class="Va">security.mac.do.rules</var></dt> - <dd>The list of credential rules, whose syntax is described in the - <a class="Sx" href="#CREDENTIALS_RULES">CREDENTIALS RULES</a> section - above. This list is specific to each jail. Please see the - <a class="Sx" href="#JAIL_SUPPORT">JAIL SUPPORT</a> section below for more - details on the interaction of <code class="Nm">mac_do</code> with - jails.</dd> - <dt id="security.mac.do.print_parse_error"><var class="Va">security.mac.do.print_parse_error</var></dt> - <dd>Logs a message on trying to set incorrect rules via the - <var class="Va">security.mac.do.rules</var> <a class="Xr">sysctl(8)</a> - knob.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="JAIL_SUPPORT"><a class="permalink" href="#JAIL_SUPPORT">JAIL - SUPPORT</a></h1> -<p class="Pp"><code class="Nm">mac_do</code> supports per-jail configuration of - rules.</p> -<p class="Pp">By default, at creation, a new jail has no credentials rules, - effectively disabling <code class="Nm">mac_do</code> for its processes.</p> -<p class="Pp">The following jail parameters are defined:</p> -<dl class="Bl-tag"> - <dt id="mac.do"><var class="Va">mac.do</var></dt> - <dd>Possible values are: - <dl class="Bl-tag Bl-compact"> - <dt>‘<code class="Li">enable</code>’</dt> - <dd><code class="Nm">mac_do</code> will enforce specific credential rules - in the jail. The <var class="Va">mac.do.rules</var> jail parameter - must also be set in this case.</dd> - <dt>‘<code class="Li">disable</code>’</dt> - <dd>Disables <code class="Nm">mac_do</code> in the jail. Strictly - equivalent to jail creation's default behavior and to setting the - rules to an empty string.</dd> - <dt>‘<code class="Li">inherit</code>’</dt> - <dd>The jail's credentials rules are inherited from the jail's parent - (which may themselves have been inherited). Modified rules propagate - to all children jails configured for inheritance.</dd> - </dl> - </dd> - <dt id="mac.do.rules"><var class="Va">mac.do.rules</var></dt> - <dd>The credentials rules for the jail. It is always equal to the value that - can be retrieved by the <a class="Xr">sysctl(8)</a> knob - <var class="Va">security.mac.do.rules</var> described in section - <a class="Sx" href="#RUNTIME_CONFIGURATION">RUNTIME CONFIGURATION</a>. If - set, and the jail parameter <var class="Va">mac.do</var> is not so - explicitly, the value of the latter will default to - ‘<code class="Li">disable</code>’ if empty, else to - ‘<code class="Li">enable</code>’.</dd> -</dl> -<p class="Pp">Each jail must have <a class="Xr">mdo(1)</a> installed at path - <span class="Pa">/usr/bin/mdo</span>, as this path is currently not - configurable.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> -<p class="Pp">Here are several examples of single rules matching processes - having a real user ID of 10001:</p> -<dl class="Bl-tag"> - <dt id="uid=10001_uid=10002"><a class="permalink" href="#uid=10001_uid=10002"><code class="Li">uid=10001>uid=10002</code></a></dt> - <dd>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.</dd> - <dt id="uid=10001_uid=10002,uid=10003"><a class="permalink" href="#uid=10001_uid=10002,uid=10003"><code class="Li">uid=10001>uid=10002,uid=10003</code></a></dt> - <dd>Same as the first example, but also allows to switch to UID 10003 instead - of 10002, or possibly having both in different user IDs.</dd> - <dt id="uid=10001_uid=10002,gid=10002"><a class="permalink" href="#uid=10001_uid=10002,gid=10002"><code class="Li">uid=10001>uid=10002,gid=10002</code></a></dt> - <dd>Same as the first example, but the new primary groups must be set to 10002 - and no supplementary groups should be set.</dd> - <dt id="uid=10001_uid=10002,gid=10002,+gid=."><a class="permalink" href="#uid=10001_uid=10002,gid=10002,+gid=."><code class="Li">uid=10001>uid=10002,gid=10002,+gid=.</code></a></dt> - <dd>Same as the previous example, but in addition allowing to retain any - current supplementary groups.</dd> - <dt id="uid=10001_uid=10002,gid=10002,!gid=."><a class="permalink" href="#uid=10001_uid=10002,gid=10002,!gid=."><code class="Li">uid=10001>uid=10002,gid=10002,!gid=.</code></a></dt> - <dd>Same as the previous example, but with the additional constraint that all - current supplementary groups must be kept.</dd> - <dt id="uid=10001_uid=10002,gid=10002,+gid=.,-gid=10001"><a class="permalink" href="#uid=10001_uid=10002,gid=10002,+gid=.,-gid=10001"><code class="Li">uid=10001>uid=10002,gid=10002,+gid=.,-gid=10001</code></a></dt> - <dd>Same as - ‘<code class="Li">uid=10001>uid=10002,gid=10002,+gid=.</code>’ - above, but 10001 cannot be retained as a supplementary group.</dd> - <dt id="uid=10001_uid=10002,gid=10002,+gid=.,!gid=10003"><a class="permalink" href="#uid=10001_uid=10002,gid=10002,+gid=.,!gid=10003"><code class="Li">uid=10001>uid=10002,gid=10002,+gid=.,!gid=10003</code></a></dt> - <dd>Same as - ‘<code class="Li">uid=10001>uid=10002,gid=10002,+gid=.</code>’ - above, with the additional constraint that 10003 must appear in the - supplementary groups.</dd> - <dt id="uid=10001_uid=10002,gid=*,+gid=*"><a class="permalink" href="#uid=10001_uid=10002,gid=*,+gid=*"><code class="Li">uid=10001>uid=10002,gid=*,+gid=*</code></a></dt> - <dd>Same as the first example, but lifting any constraints on groups, allowing - the process to become part of any groups it sees fit.</dd> -</dl> -<p class="Pp">Here are several examples of single rules matching processes - having 10001 as their real group IDs or in their supplementary groups:</p> -<dl class="Bl-tag"> - <dt id="gid=10001_uid=0"><a class="permalink" href="#gid=10001_uid=0"><code class="Li">gid=10001>uid=0</code></a></dt> - <dd>Makes 10001 a more powerful ‘<code class="Li">wheel</code>’ - group, allowing its members to switch to root without password.</dd> - <dt id="gid=10001_gid=10002"><a class="permalink" href="#gid=10001_gid=10002"><code class="Li">gid=10001>gid=10002</code></a></dt> - <dd>Allows the process to enter GID 10002 as a primary group, but only if - giving up all its supplementary groups.</dd> - <dt id="gid=10001_gid=10002,+gid=."><a class="permalink" href="#gid=10001_gid=10002,+gid=."><code class="Li">gid=10001>gid=10002,+gid=.</code></a></dt> - <dd>Same as the previous example, but allows to retain any current - supplementary groups.</dd> - <dt id="gid=10001_gid=10002,!gid=."><a class="permalink" href="#gid=10001_gid=10002,!gid=."><code class="Li">gid=10001>gid=10002,!gid=.</code></a></dt> - <dd>Same as the previous example, but with the additional constraint that all - current supplementary groups must be kept.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">mdo(1)</a>, <a class="Xr">setcred(2)</a>, - <a class="Xr">mac(4)</a>, <a class="Xr">jail(8)</a>, - <a class="Xr">sysctl(8)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp"><span class="An">Olivier Certner</span> - <<a class="Mt" href="mailto:olce@FreeBSD.org">olce@FreeBSD.org</a>> - <br/> - <span class="An">Baptiste Daroussin</span> - <<a class="Mt" href="mailto:bapt@FreeBSD.org">bapt@FreeBSD.org</a>></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> -<p class="Pp">Currently, <code class="Nm">mac_do</code> considers only - credentials transitions requested through the <a class="Xr">setcred(2)</a> - system call. This system call was in large part created so that - <code class="Nm">mac_do</code> 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.</p> -<p class="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 - <code class="Nm">mac_do</code>. Future work will lift this restriction.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SECURITY_CONSIDERATIONS"><a class="permalink" href="#SECURITY_CONSIDERATIONS">SECURITY - CONSIDERATIONS</a></h1> -<p class="Pp">The threat model for <code class="Nm">mac_do</code> 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.</p> -<p class="Pp">Consequently, <code class="Nm">mac_do</code> 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 - <a class="Xr">sysctl(3)</a> or <a class="Xr">jail(2)</a>. 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 <code class="Nm">mac_do</code> can be - trusted.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">June 11, 2025</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |