diff --git a/en_US.ISO8859-1/books/arch-handbook/mac/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/mac/chapter.sgml
index dae0ee52be..b6f82c56df 100644
--- a/en_US.ISO8859-1/books/arch-handbook/mac/chapter.sgml
+++ b/en_US.ISO8859-1/books/arch-handbook/mac/chapter.sgml
@@ -1,5681 +1,5681 @@
Chris
Costello
TrustedBSD Project
chris@FreeBSD.org
Robert
Watson
TrustedBSD Project
rwatson@FreeBSD.org
Writing MAC Policies
Synopsis
MAC, or Mandatory Access Control, is a feature introduced by
the TrustedBSD Project to supplement the existing standard DAC
- (Discreationary Access Control) policies of BSD Unix systems.
+ (Discretionary Access Control) policies of BSD Unix systems.
This chapter introduces the MAC policy framework and
provides documentation for a sample MAC policy module.
Introduction
The TrustedBSD MAC framework provides a mechanism to allow
the compile-time or run-time extension of the kernel access
control model. New system policies may be implemented as
kernel modules and linked to the kernel; if multiple policy
modules are present, their results will be composed. While the
framework is intended to support a variety of access control
models, its design was derived from the requirements of a set
of specific access control models required for the TrustedBSD
and CBOSS Projects. This includes support for fixed and
floating label Biba integrity policies, the MLS
confidentiality policy, the Type Enforcement rule-based access
control policy, and the ability to support layering of the NSA
FLASK framework above the TrustedBSD MAC framework. This
document describes the rough architecture of the framework,
with the understanding that this is a work-in-progress and may
change subtantially as requirements evolve.
Kernel Architecture
The TrustedBSD MAC framework provides the opportunity for
policy modules to be augment system access control decisions.
Policies are permitted the opportunity to restrict the set of
rights available for processes at a variety of relevant points
in the kernel. In addition, they are provided the opportunity
to tag processes and various kernel objects with labels storing
access control information. Policy modules may register
interest in a subset of the total available events or objects,
and are not required to implement events or objects that are not
relevant to the policy. Multiple modules may be loaded at once,
and the results of the modules are composed as necessary to
build an over-all system policy. Policy modules may be
implemented such that they can be loaded on-demand at run-time,
or such that they may only be loaded early in the boot process.
This permits policies requiring pervasive labeling of all
objects to prevent improper use.
Userland Architecture
...
Entry Point Framework
Four classes of entry points are offered to policies
registered with the framework: entry points associated with
the registration and management of policies, entry points
denoting initialization, creation, destruction, and other life
cycle events for kernel objects, events assocated with access
control decisions that the policy module may influence, and
calls associated with the management of labels on objects. In
addition, a mac_syscall() entry point is
provided so that policies may extend the kernel interface
without registering new system calls.
Policy module writers should be aware of the kernel
locking strategy, as well as what object locks are available
during which entry points. Writers should attempt to avoid
deadlock scenarios by avoiding grabbing non-leaf locks inside
of entry points, and also follow the locking protocol for
object access and modification. In particular, writers should
be aware that while necessary locks to access objects and
their labels are generally held, sufficient locks to modify an
object or its label may not be present for all entry points.
Locking information for arguments is documented in the MAC
framework entry point document.
Policy entry points will pass a reference to the object
label along with the object itself. This permits labeled
policies to be unaware of the internals of the object yet
still make decisions based on the label. The exception to this
is the process credential, which is assumed to be understood
by policies as a first class security object in the kernel.
Policies that do not implement labels on kernel objects will
be passed NULL pointers for label arguments to entry
points.
Policy Module Registration
Modules may be declared using the
MAC_POLICY_SET() macro, which names the
policy, provides a reference to the MAC entry point vector,
provides load-time flags determining how the policy framework
should handle the policy, and optionally requests the
allocation of label state by the framework:
static struct mac_policy_op_entry mac_none_ops[] =
{
{ MAC_DESTROY,
(macop_t)mac_none_destroy },
{ MAC_INIT,
(macop_t)mac_none_init },
{ MAC_INIT_BPFDESC,
(macop_t)mac_none_init_bpfdesc },
/* ... */
{ MAC_CHECK_VNODE_STAT,
(macop_t)mac_none_check_vnode_stat },
{ MAC_CHECK_VNODE_WRITE,
(macop_t)mac_none_check_vnode_write },
{ MAC_OP_LAST, NULL }
};
The MAC policy entry point vector,
mac_none_ops in this example, associates
functions defined in the module with specific entry points. A
complete listing of available entry points and their
prototypes may be found in the MAC entry point reference
section. Of specific interest during module registration are
the MAC_DESTROY and MAC_INIT
entry points. MAC_INIT will be invoked once a
policy is successfully registered with the module framework
but prior to any other entry points becoming active. This
permits the policy to perform any policy-specific allocation
and initialization, such as initialization of any data or
locks. MAC_DESTROY will be invoked when a
policy module is unloaded to permit releasing of any allocated
memory and destruction of locks. Currently, these two entry
points are invoked with the MAC policy list mutex held to
prevent any other entry points from being invoked: this will
be changed, but in the mean time, policies should be careful
about what kernel primitives they invoke so as to avoid lock
ordering or sleeping problems.
The policy declaration's module name field exists so that
the module may be uniquely identified for the purposes of
module dependencies. An appropriate string should be selected.
The full string name of the policy is displayed to the user
via the kernel log during load and unload events, and also
exported when providing status information to userland
processes.
The policy flags field permits the module to provide the
framework with information about its loader-related
capabilities. Currently, two flags are defined:
MPC_LOADTIME_FLAG_UNLOADOK
This flag indicates that the policy module may be
unloaded. If this flag is not provided, then the policy
framework will reject requests to unload the module.
This flag might be used by modules that allocate label
state and are unable to free that state at
runtime.
MPC_LOADTIME_FLAG_NOTLATE
This flag indicates that the policy module
must be loaded and initialized early in the boot
process. If the flag is specified, attempts to register
the module following boot will be rejected. The flag
may be used by policies that require pervasive labeling
of all system objects, and cannot handle objects that
have not been properly initialized by the policy.
&mac.mpo;_init
void
&mac.mpo;_init
struct mac_policy_conf
*conf
&mac.thead;
conf
MAC policy definition
Policy load event. The policy list mutex is held, so
caution should be applied.
&mac.mpo;_destroy
void
&mac.mpo;_destroy
struct mac_policy_conf
*conf
&mac.thead;
conf
MAC policy definition
Policy load event. The policy list mutex is held, so
caution should be applied.
Label Events
This class of entry points is used by the MAC framework to
permit policies to maintain label information on kernel
objects. For each labeled kernel object of interest to a MAC
policy, entry points may be registered for relevant life cycle
events. All objects implement initialization, creation, and
destruction hooks. Some objects will also implement
relabeling, allowing user processes to change the labels on
objects. Some objects will also implement object-specific
events, such as label events associated with IP reassembly. A
typical labeled object will have the following life cycle of
entry points:
Label initialization o
(object-specific wait) \
Label creation o
\
Relabel events, o--<--.
Various object-specific, | |
Access control events ~-->--o
\
Label destruction o
Label initialization permits policies to allocate memory
and set initial values for labels without context for the use
of the object. The label slot allocated to a policy will be
zero'd by default, so some policies may not need to perform
initialization.
Label creation occurs when the kernel structure is
associated with an actual kernel object. For example, mbufs
may be allocated and remain unused in a pool until they are
required. mbuf allocation causes label initialization on the
mbuf to take place, but mbuf creation occurs when the mbuf is
associated with a datagram. Typically, context will be
provided for a creation event, including the circumstances of
the creation, and labels of other relevant objects in the
creation process. For example, when an mbuf is created from a
socket, the socket and its label will be presented to
registered policies in addition to the new mbuf and its label.
Memory allocation in creation events is discouraged, as it may
occur in performance sensitive ports of the kernel; in
addition, creation calls are not permitted to fail so a
failure to allocate memory cannot be reported.
Object specific events do not generally fall into the
other broad classes of label events, but will generally
provide an opportunity to modify or update the label on an
object based on additional context. For example, the label on
an IP fragment reassembly queue may be updated during the
MAC_UPDATE_IPQ entry point as a result of the
acceptance of an additional mbuf to that queue.
Access control events are discussed in detail in the
following section.
Label destruction permits policies to release storage or
state associated with a label during its association with an
object so that the kernel data structures supporting the
object may be reused or released.
In addition to labels associated with specific kernel
objects, an additional class of labels exists: temporary
labels. These labels are used to store update information
submitted by user processes. These labels are initialized and
destroyed as with other label types, but the creation event is
MAC_INTERNALIZE, which accepts a user label
to be converted to an in-kernel representation.
File System Object Labeling Event Operations
&mac.mpo;_create_devfs_device
void
&mac.mpo;_create_devfs_device
dev_t dev
struct devfs_dirent
*devfs_dirent
struct label
*label
&mac.thead;
dev
Device corresponding with
devfs_dirent
devfs_dirent
Devfs directory entry to be labeled.
label
Label for devfs_dirent
to be filled in.
Fill out the label on a devfs_dirent being created for
the passed device. This call will be made when the device
file system is mounted, regenerated, or a new device is made
available.
&mac.mpo;_create_devfs_directory
void
&mac.mpo;_create_devfs_directory
char *dirname
int dirnamelen
struct devfs_dirent
*devfs_dirent
struct label
*label
&mac.thead;
dirname
Name of directory being created
namelen
Length of string
dirname
devfs_dirent
Devfs directory entry for directory being
created.
Fill out the label on a devfs_dirent being created for
the passed directory. This call will be made when the device
file system is mounted, regenerated, or a new device
requiring a specific directory hierarchy is made
available.
&mac.mpo;_create_devfs_vnode
void
&mac.mpo;_create_devfs_vnode
struct devfs_dirent
*devfs_dirent
struct label
*direntlabel
struct vnode
*vp
struct label
*vnodelabel
&mac.thead;
devfs_dirent
Object; devfs directory entry
direntlabel
Policy label for
devfs_dirent
vp
Object; file system object being labeled
vnodelabel
Policy label to be filled in for
vp
Fill out the label on the vnode being created for the
passed devfs_dirent. This call will be made when a vnode is
required to represent the specified devfs_dirent in a
mounted devfs instance.
&mac.mpo;_vnode_create_from_vnode
void
&mac.mpo;_vnode_create_from_vnode
struct ucred
*cred
struct vnode
*parent
struct label
*parentlabel
struct vnode
*child
struct label
*childlabel
&mac.thead;
cred
Subject credential
parent
Parent vnode; the directory in which
child is being
created
parentlabel
Policy label for
parent
child
New vnode
childlabel
Label to be filled in for
child
Fill out the label on the vnode being created in the
passed vnode parent by the passed subject credential. This
call will be made when a vnode is allocated during a vnode
creation operation. For example, this call is made by
multi-label file systems during the creation of a new file
or directory.
&mac.mpo;_create_mount
void
&mac.mpo;_create_mount
struct ucred
*cred
struct mount
*mp
struct label
*mnt
struct label
*fslabel
&mac.thead;
cred
Subject credential
mp
Object; file system being mounted
mntlabel
Policy label to be filled in for
mp
fslabel
Policy label for the file system
mp mounts.
Fill out the labels on the mount point being created by
the passed subject credential. This call will be made when
a new file system is mounted.
&mac.mpo;_create_root_mount
void
&mac.mpo;_create_root_mount
struct ucred
*cred
struct mount
*mp
struct label
*mntlabel
struct label
*fslabel
&mac.thead;
See .
Fill out the labels on the mount point being created by
the passed subject credential. This call will be made when
the root file system is mounted, after
&mac.mpo;_create_mount;.
&mac.mpo;_vnode_relabel
void
&mac.mpo;_vnode_relabel
struct ucred
*cred
struct vnode
*vp
struct label
*vnodelabel
struct label
*newlabel
&mac.thead;
cred
Subject credential
vp
vnode to relabel
vnodelabel
Existing policy label for
vp
newlabel
New, possibly partial label to replace
vnodelabel
Update the label on the passed vnode given the passed
update vnode label and the passed subject credential.
&mac.mpo;_stdcreatevnode_ea
int
&mac.mpo;_stdcreatevnode_ea
struct vnode
*vp
struct label
*vnodelabel
&mac.thead;
vp
vnode to commit
Locked on entry, locked on exit
vnodelabel
Label associated with
vp
This entry point is called when a vnode is to be
committed to disk via the extended attribute service (see
&man.extattr.9;). If committing to the disk is successful,
a value of 0 should be returned;
otherwise, an appropriate error code should be
returned.
The current implementation as of July 24, 2002
commits the data to disk from within the architecture.
The implementation will be updated to be closer to the
above documentation as development progresses.
&mac.mpo;_update_devfsdirent
void
&mac.mpo;_update_devfsdirent
struct devfs_dirent
*devfs_dirent
struct label
*direntlabel
struct vnode
*vp
struct label
*vnodelabel
&mac.thead;
devfs_dirent
Object; devfs directory entry
direntlabel
Policy label for
devfs_dirent to be
updated.
vp
Parent vnode
Locked
vnodelabel
Policy label for
vp
Update the devfs_dirent label
from the passed devfs vnode label. This call will be made
when a devfs vnode has been successfully relabeled to commit
the label change such that it lasts even if the vnode is
recycled. It will also be made when when a symlink is
created in devfs, following a call to
mac_vnode_create_from_vnode to
initialize the vnode label.
&mac.mpo;_update_procfsvnode
void
&mac.mpo;_update_procfsvnode
struct vnode
*vp
struct label
*vnodelabel
struct ucred
*cred
&mac.thead;
vp
Object; procfs vnode
Locked
vnodelabel
Policy label to be filled in for
vp
cred
Subject; credential for the process
entry
Immutable
Update the procfs vnode label from the passed subject
credential. This call will be made when an operation on a
procfs vnode requires a fresh label on a process-derived
vnode.
&mac.mpo;_update_vnode_from_extattr
int
&mac.mpo;_update_vnode_from_extattr
struct vnode
*vp
struct label
*vnodelabel
struct mount
*mp
struct label
*fslabel
&mac.thead;
vp
Object; vnode whose label is being updated
Locked
vnodelabel
Policy label to refresh
mp
Mount point for
vp
fslabel
Policy label for vp's
file system.
Update the vnode label by refreshing the label data from
the extended attribute service for the vnode. The mount
point fslabel is also made available
so that the fslabel may be used as a
labeling source if fallback is appropriate for the policy.
This call is permitted to fail; if the call fails, the
associated label refresh will also fail, causing the failure
of the operation requiring the MAC check and vnode label
refresh, permitting a fail closed
policy if
labeling data is not available.
&mac.mpo;_update_from_externalized
int
&mac.mpo;_update_from_externalized
struct vnode
*vp
struct label
*vnodelabel
struct mac
*extmac
&mac.thead;
vp
Object; vnode
Locked
vnodelabel
Policy label for
vp
extmac
Externalized MAC policy label
Update the vnode label from the passed externalized
label loaded from disk by the MAC framework. This call is
permitted to fail; if the call fails, the associated label
refresh will also fail, causing the failure of the operation
requiring the MAC check and vnode label refresh, permitting
a fail closed
policy if labeling data is not
available. This call will be obsoleted by the new extended
attribute labeling interface.
&mac.mpo;_update_vnode_from_mount
void
&mac.mpo;_update_vnode_from_mount
struct vnode
*vp
struct label
*vnodelabel
struct mount
*mp
struct label
*mountlabel
&mac.thead;
vp
Object; vnode
Locked
vnodelabel
Policy label for
vp
mp
Mount point where vp
resides
fslabel
Policy label for the file system where
vp resides.
Update the vnode label from the passed mount point
label. This call is made when a single label file system
vnode requires a label, or if the obsoleted MAC framework
externalized extended attribute read fails.
IPC Object Labeling Event Operations
&mac.mpo;_create_mbuf_from_socket
void
&mac.mpo;_create_mbuf_from_socket
struct socket
*so
struct label
*socketlabel
struct mbuf *m
struct label
*mbuflabel
&mac.thead;
socket
Socket
Socket locking WIP
socketlabel
Policy label for
socket
m
Object; mbuf
mbuflabel
Policy label to fill in for
m
Set the label on a newly created mbuf header from the
passed socket label. This call is made when a new datagram
or messsage is generated by the socket and stored in the
passed mbuf.
&mac.mpo;_create_socket
void
&mac.mpo;_create_socket
struct ucred
*cred
struct socket
*so
struct label
*socketlabel
&mac.thead;
cred
Subject credential
Immutable
so
Object; socket to label
socketlabel
Label to fill in for
so
Set the label on a newly created socket from the passed
subject credential. This call is made when a socket is
created.
&mac.mpo;_create_socket_from_socket
void
&mac.mpo;_create_socket_from_socket
struct socket
*oldsocket
struct label
*oldsocketlabel
struct socket
*newsocket
struct label
*newsocketlabel
&mac.thead;
oldsocket
Object; parent socket; created from
&man.listen.2;
oldsocketlabel
Label for
oldsocket
newsocket
Object; child socket; incoming connection
newsocketlabel
Label to be filled in for
newsocket
Set the label on a newly created stream socket from the
passed listen socket. This call may occur during &man.accept.2;,
or prior to &man.accept.2;, depending on the protocol.
&mac.mpo;_socket_relabel
void
&mac.mpo;_socket_relabel
struct ucred
*cred
struct socket
*so
struct label
*oldlabel
struct label
*newlabel
&mac.thead;
cred
Subject credential
Immutable
so
Object; socket
oldlabel
Current label for
so
newlabel
Label update for
so
Update the label on a socket from the passed socket
label update.
&mac.mpo;_set_socket_peer_from_mbuf
void
&mac.mpo;_set_socket_peer_from_mbuf
struct mbuf
*mbuf
struct label
*mbuflabel
struct label
*oldlabel
struct label
*newlabel
&mac.thead;
mbuf
First datagram received over socket
mbuflabel
Label for mbuf
oldlabel
Current label for the socket
newlabel
Policy label to be filled out for the
socket
Set the peer label on a stream socket from the passed
mbuf label. This call will be made when the first datagram
is received by the stream socket, with the exception of Unix
domain sockets.
&mac.mpo;_set_socket_peer_from_socket
void
&mac.mpo;_set_socket_peer_from_socket
struct socket
*oldsocket
struct label
*oldsocketlabel
struct socket
*newsocket
struct label
*newsocketpeerlabel
&mac.thead;
oldsocket
Local socket
oldsocketlabel
Policy label for
oldsocket
newsocket
Peer socket
newsocketpeerlabel
Policy label to fill in for
newsocket
Set the peer label on a stream UNIX domain socket from
the passed remote socket endpoint. This call will be made
when the socket pair is connected, and will be made for both
endpoints.
Network Object Labeling Event Operations
&mac.mpo;_create_bpfdesc
void
&mac.mpo;_create_bpfdesc
struct ucred
*cred
struct bpf_d
*bpf_d
struct label
*bpflabel
&mac.thead;
cred
Subject credential
Immutable
bpf_d
Object; bpf descriptor
bpf
Policy label to be filled in for
bpf_d
Set the label on a newly created BPF descriptor from the
passed subject credential. This call will be made when a
BPF device node is opened by a process with the passed
subject credential.
&mac.mpo;_create_ifnet
void
&mac.mpo;_create_ifnet
struct ifnet
*ifnet
struct label
*ifnetlabel
&mac.thead;
ifnet
Network interface
ifnetlabel
Policy label to fill in for
ifnet
Set the label on a newly created interface. This call
may be made when a new physical interface becomes available
to the system, or when a pseudo-interface is instantiated
during the boot or as a result of a user action.
&mac.mpo;_create_ipq
void
&mac.mpo;_create_ipq
struct mbuf
*fragment
struct label
*fragmentlabel
struct ipq
*ipq
struct label
*ipqlabel
&mac.thead;
fragment
First received IP fragment
fragmentlabel
Policy label for
fragment
ipq
IP reassembly queue to be labeled
ipqlabel
Policy label to be filled in for
ipq
Set the label on a newly created IP fragment reassembly
queue from the mbuf header of the first received
fragment.
&mac.mpo;_create_datagram_from_ipq
void
&mac.mpo;_create_create_datagram_from_ipq
struct ipq
*ipq
struct label
*ipqlabel
struct mbuf
*datagram
struct label
*datagramlabel
&mac.thead;
ipq
IP reassembly queue
ipqlabel
Policy label for
ipq
datagram
Datagram to be labeled
datagramlabel
Policy label to be filled in for
datagramlabel
Set the label on a newly reassembled IP datagram from
the IP fragment reassembly queue from which it was
generated.
&mac.mpo;_create_fragment
void
&mac.mpo;_create_fragment
struct mbuf
*datagram
struct label
*datagramlabel
struct mbuf
*fragment
struct label
*fragmentlabel
&mac.thead;
datagram
Datagram
datagramlabel
Policy label for
datagram
fragment
Fragment to be labeled
fragmentlabel
Policy label to be filled in for
datagram
Set the label on the mbuf header of a newly created IP
fragment from the label on the mbuf header of the datagram
it was generate from.
&mac.mpo;_create_mbuf_from_mbuf
void
&mac.mpo;_create_mbuf_from_mbuf
struct mbuf
*oldmbuf
struct label
*oldmbuflabel
struct mbuf
*newmbuf
struct label
*newmbuflabel
&mac.thead;
oldmbuf
Existing (source) mbuf
oldmbuflabel
Policy label for
oldmbuf
newmbuf
New mbuf to be labeled
newmbuflabel
Policy label to be filled in for
newmbuf
Set the label on the mbuf header of a newly created
datagram from the mbuf header of an existing datagram. This
call may be made in a number of situations, including when
an mbuf is re-allocated for alignment purposes.
&mac.mpo;_create_mbuf_linklayer
void
&mac.mpo;_create_mbuf_linklayer
struct ifnet
*ifnet
struct label
*ifnetlabel
struct mbuf
*mbuf
struct label
*mbuflabel
&mac.thead;
ifnet
Network interface
ifnetlabel
Policy label for
ifnet
mbuf
mbuf header for new datagram
mbuflabel
Policy label to be filled in for
mbuf
Set the label on the mbuf header of a newly created
datagram generated for the purposes of a link layer response
for the passed interface. This call may be made in a number
of situations, including for ARP or ND6 responses in the
IPv4 and IPv6 stacks.
&mac.mpo;_create_mbuf_from_bpfdesc
void
&mac.mpo;_create_mbuf_from_bpfdesc
struct bpf_d
*bpf_d
struct label
*bpflabel
struct mbuf
*mbuf
struct label
*mbuflabel
&mac.thead;
bpf_d
BPF descriptor
bpflabel
Policy label for
bpflabel
mbuf
New mbuf to be labeled
mbuflabel
Policy label to fill in for
mbuf
Set the label on the mbuf header of a newly created
datagram generated using the passed BPF descriptor. This
call is made when a write is performed to the BPF device
associated with the passed BPF descriptor.
&mac.mpo;_create_mbuf_from_ifnet
void
&mac.mpo;_create_mbuf_from_ifnet
struct ifnet
*ifnet
struct label
*ifnetlabel
struct mbuf
*mbuf
struct label
*mbuflabel
&mac.thead;
ifnet
Network interface
ifnetlabel
Policy label for
ifnetlabel
mbuf
mbuf header for new datagram
mbuflabel
Policy label to be filled in for
mbuf
Set the label on the mbuf header of a newly created
datagram generated from the passed network interface.
&mac.mpo;_create_mbuf_multicast_encap
void
&mac.mpo;_create_mbuf_multicast_encap
struct mbuf
*oldmbuf
struct label
*oldmbuflabel
struct ifnet
*ifnet
struct label
*ifnetlabel
struct mbuf
*newmbuf
struct label
*newmbuflabel
&mac.thead;
oldmbuf
mbuf header for existing datagram
oldmbuflabel
Policy label for
oldmbuf
ifnet
Network interface
ifnetlabel
Policy label for
ifnet
newmbuf
mbuf header to be labeled for new
datagram
newmbuflabel
Policy label to be filled in for
newmbuf
Set the label on the mbuf header of a newly created
datagram generated from the existing passed datagram when it
is processed by the passed multicast encapsulation
interface. This call is made when an mbuf is to be
delivered using the virtual interface.
&mac.mpo;_create_mbuf_netlayer
void
&mac.mpo;_create_mbuf_netlayer
struct mbuf
*oldmbuf
struct label
*oldmbuflabel
struct mbuf
*newmbuf
struct label
*newmbuflabel
&mac.thead;
oldmbuf
Received datagram
oldmbuflabel
Policy label for
oldmbuf
newmbuf
Newly created datagram
newmbuflabel
Policy label for
newmbuf
Set the label on the mbuf header of a newly created
datagram generated by the IP stack in response to an
existing received datagram (oldmbuf).
This call may be made in a number of situations, including
when responding to ICMP request datagrams.
&mac.mpo;_fragment_match
int
&mac.mpo;_fragment_match
struct mbuf
*fragment
struct label
*fragmentlabel
struct ipq
*ipq
struct label
*ipqlabel
&mac.thead;
fragment
IP datagram fragment
fragmentlabel
Policy label for
fragment
ipq
IP fragment reassembly queue
ipqlabel
Policy label for
ipq
Determine whether an mbuf header containing an IP
datagram (fragment) fragment matches
the label of the passed IP fragment reassembly queue
(ipq). Return
(1) for a successful match, or
(0) for no match. This call is
made when the IP stack attempts to find an existing fragment
reassembly queue for a newly received fragment; if this
fails, a new fragment reassembly queue may be instantiated
for the fragment. Policies may use this entry point to
prevent the reassembly of otherwise matching IP fragments if
policy does not permit them to be reassembled based on the
label or other information.
&mac.mpo;_ifnet_relabel
void
&mac.mpo;_ifnet_relabel
struct ucred
*cred
struct ifnet
*ifnet
struct label
*ifnetlabel
struct label
*newlabel
&mac.thead;
cred
Subject credential
ifnet
Object; Network interface
ifnetlabel
Policy label for
ifnet
newlabel
Label update to apply to
ifnet
Update the label of network interface,
ifnet, based on the passed update
label, newlabel, and the passed
subject credential, cred.
&mac.mpo;_update_ipq
void
&mac.mpo;_update_ipq
struct mbuf
*fragment
struct label
*fragmentlabel
struct ipq
*ipq
struct label
*ipqlabel
&mac.thead;
mbuf
IP fragment
mbuflabel
Policy label for
mbuf
ipq
IP fragment reassembly queue
ipqlabel
Policy label to be updated for
ipq
Update the label on an IP fragment reassembly queue
(ipq) based on the acceptance of the
passed IP fragment mbuf header
(mbuf).
Process Labeling Event Operations
&mac.mpo;_create_cred
void
&mac.mpo;_create_cred
struct ucred
*parent_cred
struct ucred
*child_cred
&mac.thead;
parent_cred
Parent subject credential
child_cred
Child subject credential
Set the label of a newly created subject credential from
the passed subject credential. This call will be made when
crcopy(9) is invoked on a newly created struct
ucred. This call should not be confused with a
process forking or creation event.
&mac.mpo;_execve_transition
void
&mac.mpo;_execve_transition
struct ucred
*old
struct ucred
*new
struct vnode
*vp
struct label
*vnodelabel
&mac.thead;
old
Existing subject credential
Immutable
new
New subject credential to be labeled
vp
File to execute
Locked
vnodelabel
Policy label for
vp
Update the label of a newly created subject credential
(new) from the passed existing
subject credential (old) based on a
label transition caused by executing the passed vnode
(vp). This call occurs when a
process executes the passed vnode and one of the policies
returns a success from the
mpo_execve_will_transition entry point.
Policies may choose to implement this call simply by
invoking mpo_create_cred and passing
the two subject credentials so as not to implement a
transitioning event. Policies should not leave this entry
point unimplemented if they implement
mpo_create_cred, even if they do not
implement
mpo_execve_will_transition.
&mac.mpo;_execve_will_transition
int
&mac.mpo;_execve_will_transition
struct ucred
*old
struct vnode
*vp
struct label
*vnodelabel
&mac.thead;
old
Subject credential prior to
&man.execve.2;
Immutable
vp
File to execute
vnodelabel
Policy label for
vp
Determine whether the policy will want to perform a
transition event as a result of the execution of the passed
vnode by the passed subject credential. Return
1 if a transition is required,
0 if not. Even if a policy
returns 0, it should behave
correctly in the presence of an unexpected invocation of
mpo_execve_transition, as that call may
happen as a result of another policy requesting a
transition.
&mac.mpo;_create_proc0
void
&mac.mpo;_create_proc0
struct ucred
*cred
&mac.thead;
cred
Subject credential to be filled in
Create the subject credential of process 0, the parent
of all kernel processes.
&mac.mpo;_create_proc1
void
&mac.mpo;_create_proc1
struct ucred
*cred
&mac.thead;
cred
Subject credential to be filled in
Create the subject credential of process 1, the parent
of all kernel processes.
&mac.mpo;_cred_relabel
void
&mac.mpo;_cred_relabel
struct ucred
*cred
struct label
*newlabel
&mac.thead;
cred
Subject credential
newlabel
Label update to apply to
cred
Update the label on a subject credential from the passed
update label.
Access Control Checks
Access control entry points permit policy modules to
influence access control decisions made by the kernel.
Generally, although not always, arguments to an access control
entry point will include one or more authorizing credentials,
information (possibly including a label) for any other objects
involved in the operation. An access control entry point may
return 0 to permit the operation, and an &man.errno.2; error
value. The results of invoking the entry point across various
registered policy modules will be composed as follows: if all
modules permit the operation to succeed, success will be
returned. If one or modules returns a failure, a failure will
be returned. If more than one module returns a failure, the
errno value to return to the user will be selected using the
following precedence, implemented by the
error_select() function in
kern_mac.c:
Most precedence
EDEADLK
EINVAL
ESRCH
EACCES
Least precedence
EPERM
If none of the error values returned by all modules are
listed in the precedence chart then an arbitrarily selected
value from the set will be returned. In general, the rules
provide precedence to errors in the following order: kernel
failures, invalid arguments, object not present, access not
permitted, other.
&mac.mpo;_check_bpfdesc_receive
int
&mac.mpo;_check_bpfdesc_receive
struct bpf_d
*bpf_d
struct label
*bpflabel
struct ifnet
*ifnet
struct label
*ifnetlabel
&mac.thead;
bpf_d
Subject; BPF descriptor
bpflabel
Policy label for
bpf_d
ifnet
Object; network interface
ifnetlabel
Policy label for
ifnet
Determine whether the MAC framework should permit
datagrams from the passed interface to be delivered to the
buffers of the passed BPF descriptor. Return
(0) for success, or an
errno value for failure Suggested
failure: EACCES for label mismatches,
EPERM for lack of privilege.
&mac.mpo;_check_socket_bind
int
&mac.mpo;_check_socket_bind
struct ucred
*cred
struct socket
*socket
struct label
*socketlabel
struct sockaddr
*sockaddr
&mac.thead;
cred
Subject credential
socket
Socket to be bound
socketlabel
Policy label for
socket
sockaddr
Address of
socket
&mac.mpo;_check_socket_connect
int
&mac.mpo;_check_socket_connect
struct ucred
*cred
struct socket
*socket
struct label
*socketlabel
struct sockaddr
*sockaddr
&mac.thead;
cred
Subject credential
socket
Socket to be connected
socketlabel
Policy label for
socket
sockaddr
Address of
socket
Determine whether the subject credential
(cred) can connect the passed socket
(socket) to the passed socket address
(sockaddr). Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatches,
EPERM for lack of privilege.
&mac.mpo;_check_cred_visible
int
&mac.mpo;_check_cred_visible
struct ucred
*u1
struct ucred
*u2
&mac.thead;
u1
Subject credential
u2
Object credential
Determine whether the subject credential
u1 can see
other
subjects with the passed subject credential
u2. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatches,
EPERM for lack of privilege, or
ESRCH to hide visibility. This call
may be made in a number of situations, including
inter-process status sysctls used by ps,
and in procfs lookups.
&mac.mpo;_check_socket_visible
int
&mac.mpo;_check_socket_visible
struct ucred
*cred
struct socket
*socket
struct label
*socketlabel
&mac.thead;
cred
Subject credential
socket
Object; socket
socketlabel
Policy label for
socket
&mac.mpo;_check_ifnet_relabel
int
&mac.mpo;_check_ifnet_relabel
struct ucred
*cred
struct ifnet
*ifnet
struct label
*ifnetlabel
struct label
*newlabel
&mac.thead;
cred
Subject credential
ifnet
Object; network interface
ifnetlabel
Existing policy label for
ifnet
newlabel
Policy label update to later be applied to
ifnet
Determine whether the subject credential can relabel the
passed network interface to the passed label update.
&mac.mpo;_check_socket_relabel
int
&mac.mpo;_check_socket_relabel
struct ucred
*cred
struct socket
*socket
struct label
*socketlabel
struct label
*newlabel
&mac.thead;
cred
Subject credential
socket
Object; socket
socketlabel
Existing policy label for
socket
newlabel
Label update to later be applied to
socketlabel
Determine whether the subject credential can relabel the
passed socket to the passed label update.
&mac.mpo;_check_cred_relabel
int
&mac.mpo;_check_cred_relabel
struct ucred
*cred
struct label
*newlabel
&mac.thead;
cred
Subject credential
newlabel
Label update to later be applied to
cred
Determine whether the subject credential can relabel
itself to the passed label update.
&mac.mpo;_check_vnode_relabel
int
&mac.mpo;_check_vnode_relabel
struct ucred
*cred
struct vnode
*vp
struct label
*vnodelabel
struct label
*newlabel
&mac.thead;
cred
Subject credential
Immutable
vp
Object; vnode
Locked
vnodelabel
Existing policy label for
vp
newlabel
Policy label update to later be applied to
vp
Determine whether the subject credential can relabel the
passed vnode to the passed label update.
&mac.mpo;_check_mount_stat
int &mac.mpo;_check_mount_stat
struct ucred
*cred
struct mount
*mp
struct label
*mountlabel
&mac.thead;
cred
Subject credential
mp
Object; file system mount
mountlabel
Policy label for
mp
Determine whether the subject credential can see the
results of a statfs performed on the file system. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatches
or EPERM for lack of privilege. This
call may be made in a number of situations, including during
invocations of &man.statfs.2; and related calls, as well as to
determine what file systems to exclude from listings of file
systems, such as when &man.getfsstat.2; is invoked.
&mac.mpo;_check_proc_debug
int
&mac.mpo;_check_proc_debug
struct ucred
*cred
struct proc
*proc
&mac.thead;
cred
Subject credential
Immutable
proc
Object; process
Determine whether the subject credential can debug the
passed process. Return 0 for
success, or an errno value for failure.
Suggested failure: EACCES for label
mismatch, EPERM for lack of
privilege, or ESRCH to hide
visibility of the target. This call may be made in a number
of situations, including use of the &man.ptrace.2; and
&man.ktrace.2; APIs, as well as for some types of procfs
operations.
&mac.mpo;_check_vnode_access
int
&mac.mpo;_check_vnode_access
struct ucred
*cred
struct vnode
*vp
struct label
*label
int flags
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for
vp
flags
&man.access.2; flags
Determine how invocations of &man.access.2; and related
calls by the subject credential should return when performed
on the passed vnode using the passed access flags. This
should generally be implemented using the same semantics
used in &mac.mpo;_check_vnode_open.
Return 0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatches
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_chdir
int
&mac.mpo;_check_vnode_chdir
struct ucred
*cred
struct vnode
*dvp
struct label
*dlabel
&mac.thead;
cred
Subject credential
dvp
Object; vnode to &man.chdir.2; into
dlabel
Policy label for
dvp
Determine whether the subject credential can change the
process working directory to the passed vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_create
int
&mac.mpo;_check_vnode_create
struct ucred
*cred
struct vnode
*dvp
struct label
*dlabel
struct componentname
*cnp
struct vattr
*vap
&mac.thead;
cred
Subject credential
dvp
Object; vnode
dlabel
Policy label for
dvp
cnp
Component name for
dvp
vap
vnode attributes for vap
Determine whether the subject credential can create a
vnode with the passed parent directory, passed name
information, and passed attribute information. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES. for label mismatch,
or EPERM for lack of privilege.
This call may be made in a number of situations, including
as a result of calls to &man.open.2; with
O_CREAT, &man.mknod.2;, &man.mkfifo.2;, and
others.
&mac.mpo;_check_vnode_delete
int
&mac.mpo;_check_vnode_delete
struct ucred
*cred
struct vnode
*dvp
struct label
*dlabel
struct vnode
*vp
void *label
struct componentname
*cnp
&mac.thead;
cred
Subject credential
dvp
Parent directory vnode
dlabel
Policy label for
dvp
vp
Object; vnode to delete
label
Policy label for
vp
cnp
Component name for
vp
Determine whether the subject credential can delete a
vnode from the passed parent directory and passed name
information. Return 0 for
success, or an errno value for failure.
Suggested failure: EACCES for label
mismatch, or EPERM for lack of
privilege. This call may be made in a number of situations,
including as a result of calls to &man.unlink.2; and
&man.rmdir.2;. Policies implementing this entry point
should also implement
mpo_check_rename_to to authorize
deletion of objects as a result of being the target of a
rename.
&mac.mpo;_check_vnode_deleteacl
int
&mac.mpo;_check_vnode_deleteacl
struct ucred *cred
struct vnode *vp
struct label *label
acl_type_t type
&mac.thead;
cred
Subject credential
Immutable
vp
Object; vnode
Locked
label
Policy label for
vp
type
ACL type
Determine whether the subject credential can delete the
ACL of passed type from the passed vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_exec
int
&mac.mpo;_check_vnode_exec
struct ucred
*cred
struct vnode
*vp
struct label
*label
&mac.thead;
cred
Subject credential
vp
Object; vnode to execute
label
Policy label for
vp
Determine whether the subject credential can execute the
passed vnode. Determination of execute privilege is made
seperately from decisions about any transitioning event.
Return 0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_getacl
int
&mac.mpo;_check_vnode_getacl
struct ucred
*cred
struct vnode
*vp
struct label
*label
acl_type_t
type
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for
vp
type
ACL type
Determine whether the subject credentical can retrieve
the ACL of passed type from the passed vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_getextattr
int
&mac.mpo;_check_vnode_getextattr
struct ucred
*cred
struct vnode
*vp
struct label
*label
int
attrnamespace
const char
*name
struct uio
*uio
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for
vp
attrnamespace
Extended attribute namespace
name
Extended attribute name
uio
I/O structure pointer; see &man.uio.9;
Determine whether the subject credential can retrieve
the extended attribute with the passed namespace and name
from the passed vnode. Policies implementing labeling using
extended attributes may be interested in special handling of
operations on those extended attributes. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_socket_listen
int
&mac.mpo;_check_socket_listen
struct ucred
*cred
struct socket
*socket
struct label
*socketlabel
&mac.thead;
cred
Subject credential
socket
Object; socket
socketlabel
Policy label for
socket
Determine whether the subject credential can listen on
the passed socket. Return 0 for
success, or an errno value for failure.
Suggested failure: EACCES for label
mismatch, or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_lookup
int
&mac.mpo;_check_vnode_lookup
struct ucred
*cred
struct vnode
*dvp
struct label
*dlabel
struct componentname
*cnp
&mac.thead;
cred
Subject credential
dvp
Object; vnode
dlabel
Policy label for
dvp
cnp
Component name being looked up
Determine whether the subject credential can perform a
lookup in the passed directory vnode for the passed name.
Return 0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_open
int
&mac.mpo;_check_vnode_open
struct ucred
*cred
struct vnode
*vp
struct label
*label
mode_t
acc_mode
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for
vp
acc_mode
&man.open.2; access mode
Determine whether the subject credential can perform an
open operation on the passed vnode with the passed access
mode. Return 0 for success, or
an errno value for failure. Suggested failure:
EACCES for label mismatch, or
EPERM for lack of privilege.
&mac.mpo;_check_vnode_readdir
int
&mac.mpo;_check_vnode_readdir
struct ucred
*cred
struct vnode
*dvp
struct label
*dlabel
&mac.thead;
cred
Subject credential
dvp
Object; directory vnode
dlabel
Policy label for
dvp
Determine whether the subject credential can perform a
readdir operation on the passed
directory vnode. Return 0 for
success, or an errno value for failure.
Suggested failure: EACCES for label
mismatch, or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_readlink
int
&mac.mpo;_check_vnode_readlink
struct ucred
*cred
struct vnode
*vp
struct label
*label
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for
vp
Determine whether the subject credential can perform a
readlink operation on the passed
symlink vnode. Return 0 for
success, or an errno value for failure.
Suggested failure: EACCES for label
mismatch, or EPERM for lack of
privilege. This call may be made in a number of situations,
including an explicit readlink call by
the user process, or as a result of an implicit
readlink during a name lookup by the
process.
&mac.mpo;_check_rename_from_vnode
int
&mac.mpo;_check_rename_from_vnode
struct ucred
*cred
struct vnode
*dvp
struct label
*dlabel
struct vnode
*vp
struct label
*label
struct componentname
*cnp
&mac.thead;
cred
Subject credential
dvp
Directory vnode
dlabel
Policy label for
dvp
vp
Object; vnode
label
Policy label for
vp
cnp
Pathname
Determine whether the subject credential can rename the
passed vnode (vp) in the passed
directory (dvp) using the passed name
(cnp). This call will be made in
combination with a follow-up call to
mpo_check_rename_to_vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_rename_to_vnode
int
&mac.mpo;_check_rename_to_vnode
struct ucred
*cred
struct vnode
*dvp
struct label
*dlabel
struct vnode
*vp
struct label
*label
int samedir
struct componentname
*cnp
&mac.thead;
cred
Subject credential
dvp
Directory vnode
dlabel
Policy label for dvp
vp
Object; vnode
label
Policy label for
vp
cnp
Pathname
Determine whether the subject credential can rename to
the passed vnode (vp) and the passed
directory (dvp) with the passed name
(cnp). This call will be made in
combination with an earlier call to
mpo_check_rename_from_vnode.
Return 0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_revoke
int
&mac.mpo;_check_vnode_revoke
struct ucred
*cred
struct vnode
*vp
struct label
*label
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for
vp
Determine whether the subject credential can revoke
access to the passed vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_setacl
int
&mac.mpo;_check_vnode_setacl
struct ucred
*cred
struct vnode
*vp
struct label
*label
acl_type_t
type
struct acl
*acl
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for
vp
type
ACL type
acl
ACL
Determine whether the subject credential can set the
passed ACL of passed type on the passed vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_setextattr
int
&mac.mpo;_check_vnode_setextattr
struct ucred
*cred
struct vnode
*vp
struct label
*label
int
attrnamespace
const char
*name
struct uio
*uio
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for vp
attrnamespace
Extended attribute namespace
name
Extended attribute name
uio
I/O structure pointer; see &man.uio.9;
Determine whether the subject credentical can set the
extended attribute of passed name and passed namespace on
the passed vnode. Policies implementing security labels
backed into extended attributes may want to provide
additional protections for those attributes. Additionally,
policies should avoid making decisions based on the data
referenced from uio, as there is a
potential race condition between this check and the actual
operation. The uio may also be
NULL if a delete operation is being
performed. Return 0 for success,
or an errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_setflags
int
&mac.mpo;_check_vnode_setflags
struct ucred
*cred
struct vnode
*vp
struct label
*label
u_long flags
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for
vp
flags
File flags; see &man.chflags.2;
Determine whether the subject credential can set the
passed flags on the passed vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_setmode
int
&mac.mpo;_check_vnode_setmode
struct ucred
*cred
struct vnode
*vp
struct label
*label
mode_t mode
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for vp
mode
File mode; see &man.chmod.2;
Determine whether the subject credential can set the
pased mode on the passed vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_setowner
int
&mac.mpo;_check_vnode_setowner
struct ucred
*cred
struct vnode
*vp
struct label
*label
uid_t uid
gid_t gid
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for vp
uid
User ID
gid
Group ID
Determine whether the subject credential can set the
passed uid and passed gid as file uid and file gid on the
passed vnode. The IDs may be set to (-1)
to request no update. Return 0
for success, or an errno value for
failure. Suggested failure: EACCES
for label mismatch, or EPERM for lack
of privilege.
&mac.mpo;_check_vnode_setutimes
int
&mac.mpo;_check_vnode_setutimes
struct ucred
*cred
struct vnode
*vp
struct label
*label
struct timespec
atime
struct timespec
mtime
&mac.thead;
cred
Subject credential
vp
Object; vp
label
Policy label for
vp
atime
Access time; see &man.utimes.2;
mtime
Modification time; see &man.utimes.2;
Determine whether the subject credential can set the
passed access timestamps on the passed vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_proc_sched
int
&mac.mpo;_check_proc_sched
struct ucred
*ucred
struct proc
*proc
&mac.thead;
cred
Subject credential
proc
Object; process
Determine whether the subject credential can change the
scheduling parameters of the passed process. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
EPERM for lack of privilege, or
ESRCH to limit visibility.
See &man.setpriority.2; for more information.
&mac.mpo;_check_proc_signal
int
&mac.mpo;_check_proc_signal
struct ucred
*cred
struct proc
*proc
int signal
&mac.thead;
cred
Subject credential
proc
Object; process
signal
Signal; see &man.kill.2;
Determine whether the subject credential can deliver the
passed signal to the passed process. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
EPERM for lack of privilege, or
ESRCH to limit visibility.
&mac.mpo;_check_vnode_stat
int
&mac.mpo;_check_vnode_stat
struct ucred
*cred
struct vnode
*vp
struct label
*label
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for
vp
Determine whether the subject credential can
stat the passed vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
See &man.stat.2; for more information.
&mac.mpo;_check_ifnet_transmit
int
&mac.mpo;_check_ifnet_transmit
struct ucred
*cred
struct ifnet
*ifnet
struct label
*ifnetlabel
struct mbuf
*mbuf
struct label
*mbuflabel
&mac.thead;
cred
Subject credential
ifnet
Network interface
ifnetlabel
Policy label for
ifnet
mbuf
Object; mbuf to be sent
mbuflabel
Policy label for
mbuf
Determine whether the network interface can transmit the
passed mbuf. Return 0 for
success, or an errno value for failure.
Suggested failure: EACCES for label
mismatch, or EPERM for lack of
privilege.
&mac.mpo;_check_socket_receive
int
&mac.mpo;_check_socket_receive
struct ucred
*cred
struct ifnet
*ifnet
struct label
*ifnetlabel
struct mbuf
*mbuf
struct label
*mbuflabel
&mac.thead;
cred
Subject credential
ifnet
Network interface
ifnetlabel
Policy label for
ifnet
mbuf
Object; mbuf to be received
mbuflabel
Policy label for
mbuf
Determine whether the socket may receive the datagram
stored in the passed mbuf header. Return
0 for success, or an
errno value for failure. Suggested
failures: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_socket_visible
int
&mac.mpo;_check_socket_visible
struct ucred
*cred
struct socket
*so
struct label
*socketlabel
&mac.thead;
cred
Subject credential
Immutable
so
Object; socket
socketlabel
Policy label for
so
Determine whether the subject credential cred can "see"
the passed socket (socket) using
system monitoring functions, such as those employed by
&man.netstat.8; and &man.sockstat.1;. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatches,
EPERM for lack of privilege, or
ESRCH to hide visibility.
Label Management Calls
Relabel events occur when a user process has requested
that the label on an object be modified. A two-phase update
occurs: first, an access control check will be performed to
determine if the update is both valid and permitted, and then
the update itself is performed via a seperate entry point.
Relabel entry points typically accept the object, object label
reference, and an update label submitted by the process.
Memory allocation during relabel is discouraged, as relabel
calls are not permitted to fail (failure should be reported
earlier in the relabel check).
&mac.mpo;_init_bpfdesc
void
&mac.mpo;_init_bpfdesc
struct bpf_d
*bpf_d
struct label
*label
&mac.thead;
bpf_d
Object; bpf descriptor
label
New label to apply
Initialize the label on a newly instantiated bpfdesc (BPF
descriptor)
&mac.mpo;_init_devfsdirent
void
&mac.mpo;_init_devfsdirent
struct devfs_dirent
*devfs_dirent
struct label
*label
&mac.thead;
devfs_dirent
Object; devfs directory entry
label
New label to apply
Initialize the label on a newly instantiated devfs
entry.
&mac.mpo;_init_ifnet
void
&mac.mpo;_init_ifnet
struct ifnet
*ifnet
struct label
*label
&mac.thead;
ifnet
Object; network interface
label
New label to apply
Initialize the label on a newly instantiated network
interface.
&mac.mpo;_init_ipq
void
&mac.mpo;_init_ipq
struct ipq
*ipq
struct label
*label
&mac.thead;
ipq
Object; IP reassembly queue
label
New label to apply
Initialize the label on a newly instantiated IP fragment
reassembly queue.
&mac.mpo;_init_mbuf
void
&mac.mpo;_init_mbuf
struct mbuf
*mbuf
int how
struct label
*label
&mac.thead;
mbuf
Object; mbuf
how
Blocking/non-blocking &man.malloc.9; see
below
label
Policy label to initialize
Initialize the label on a newly instantiated mbuf packet
header (mbuf). The
how field may be one of
M_WAITOK and M_NOWAIT, and
should be employed to avoid performing a blocking
&man.malloc.9; during this initialization call. Mbuf
allocation frequently occurs in performance sensitive
environments, and the implementation should be careful to
avoid blocking or long-lived operations. This entry point
is permitted to fail resulting in the failure to allocate
the mbuf header.
&mac.mpo;_init_mount
void
&mac.mpo;_init_mount
struct mount
*mount
struct label
*mntlabel
struct label
*fslabel
&mac.thead;
mount
Object; file system mount point
mntlabel
Policy label to be initialized for the mount
itself
fslabel
Policy label to be initialized for the file
system
Initialize the labels on a newly instantiated mount
point.
&mac.mpo;_init_socket
void
&mac.mpo;_init_socket
struct socket
*socket
struct label
*label
struct label
*peerlabel
&mac.thead;
socket
Object; socket
label
New label to apply to the socket
peerlabel
New label to apply to the socket's peer
Initialize the labels on a newly instantiated
socket.
&mac.mpo;_init_cred
void
&mac.mpo;_init_cred
struct ucred
*cred
struct label
*label
&mac.thead;
cred
Subject; user credetial
label
New label
Initialize the labels on a newly instantiated subject.
&mac.mpo;_init_temp
void
&mac.mpo;_init_temp
struct label
*label
&mac.thead;
label
Temporary label
Initialize a newly instantiated temporary label;
temporary labels are frequently used to hold label update
requests.
&mac.mpo;_init_vnode
void
&mac.mpo;_init_vnode
struct vnode
*vp
struct label
*label
&mac.thead;
vp
Object; file system object
label
New label to initialize
Initialize the label on a newly instantiated vnode.
&mac.mpo;_destroy_bpfdesc
void
&mac.mpo;_destroy_bpfdesc
struct bpf_d
*bpf_d
struct label
*label
&mac.thead;
bpf_d
Object; bpf descriptor
label
Label being destroyed
Destroy the label on a BPF descriptor. In this entry
point, a policy module should free any internal storage
associated with label so that it may
be destroyed.
&mac.mpo;_destroy_devfsdirent
void
&mac.mpo;_destroy_devfsdirent
struct devfs_dirent
*devfs_dirent
struct label
*label
&mac.thead;
devfs_dirent
Object; devfs directory entry
label
Label being destroyed
Destroy the label on a devfs entry. In this entry
point, a policy module should free any internal storage
asociated with label so that it may
be destroyed.
&mac.mpo;_destroy_ifnet
void
&mac.mpo;_destroy_ifnet
struct ifnet
*ifnet
struct label
*label
&mac.thead;
ifnet
Object; network interface
label
Label being destroyed
Destroy the label on a removed interface. In this entry
point, a policy module should free any internal storage
associated with label so that it may
be destroyed.
&mac.mpo;_destroy_ipq
void
&mac.mpo;_destroy_ipq
struct ipq
*ipq
struct label
*label
&mac.thead;
ipq
Object; IP reassembly queue
label
Label being destroyed
Destroy the label on an IP fragment queue. In this
entry point, a policy module should free any internal
storage associated with label so that
it may be destroyed.
&mac.mpo;_destroy_mbuf
void
&mac.mpo;_destroy_mbuf
struct mbuf
*mbuf
struct label
*label
&mac.thead;
mbuf
Object; mbuf
label
Label being destroyed
Destroy the label on an mbuf header. In this entry
point, a policy module should free any internal storage
associated with label so that it may
be destroyed.
&mac.mpo;_destroy_mount
void
&mac.mpo;_destroy_mount
struct mount
*mp
struct label
*mntlabel
struct label
*fslabel
&mac.thead;
mp
Object; file system mount point
mntlabel
Mount point label being destroyed
fslabel
File system label being destroyed>
Destroy the labels on a mount point. In this entry
point, a policy module should free the internal storage
associated with mntlabel and
fslabel so that they may be
destroyed.
&mac.mpo;_destroy_socket
void
&mac.mpo;_destroy_socket
struct socket
*socket
struct label
*label
struct label
*peerlabel
&mac.thead;
socket
Object; socket
label
Socket label being destroyed
peerlabel
Socket peer label being destroyed
Destroy the labels on a socket. In this entry point, a
policy module should free any internal storage associated
with label and
peerlabel so that they may be
destroyed.
&mac.mpo;_destroy_cred
void
&mac.mpo;_destroy_cred
struct ucred
*cred
struct label
*label
&mac.thead;
cred
Subject; user credential
label
Label being destroyed
Destroy the label on a credential. In this entry point,
a policy module should free any internal storage associated
with label so that it may be
destroyed.
&mac.mpo;_destroy_temp
void
&mac.mpo;_destroy_temp
struct label
*label
&mac.thead;
label
Temporary label being destroyed
Destroy a temporary label. In this entry point, a
policy module should free any internal storage associated
with the temporary label label so
that it may be destroyed.
&mac.mpo;_destroy_vnode
void
&mac.mpo;_destroy_vnode
struct vnode
*vp
struct label
*label
&mac.thead;
vp
Object; file system object
label
Label being destroyed
Destroy the label on a vnode. In this entry point, a
policy module should free any internal storage associated
with label so that it may be
destroyed.
&mac.mpo;_externalize
void
&mac.mpo;_externalize
struct label
*label
struct mac
*extmac
&mac.thead;
label
Label to be externalized
extmac
MAC structure to be filled in
Given an internalized subject or object label, fill out
an externalized label. This call is permitted to fail.
This call will be obsoleted by the new userland and extended
attribute interfaces for the MAC framework.
&mac.mpo;_internalize
void
&mac.mpo;_internalize
struct label
*label
struct mac
*extmac
&mac.thead;
label
Label to be filled in
extmac
MAC structure to internalize
Given an externalized subject or object label, likely
from userland, internalize the label. The entry point
implementation should handle incorrect or corrupted labels.
This call is permitted to fail. This call will be obsoleted
by the new userland and extended attribute interfaces for
the MAC framework.
Additional Framework API Calls
The MAC_SYSCALL entry point provides a
policy-multiplexed system call so that policies may provide
additional services to user processes without registering
specific system calls. The policy name provided during
registration is used to demux calls from userland, and the
arguments will be forwarded to this entry point. When
implementing new services, security modules should be sure to
invoke appropriate access control checks from the MAC
framework as needed. For example, if a policy implements an
augmented signal functionality, it should call the necessary
signal access control checks to invoke the MAC framework and
other registered policies.
Userland APIs
The userland API is still under development.
Sample Policy Modules
The mac_none policy provides sample
prototypes and registration of all available policy entry
points.
The mac_seeotheruids policy provides
a simple access control policy without the use of labeling,
relying only on information already present in the kernel
objects.
The mac_biba policy provides a sample
information flow based labeled access control policy,
assigning labels to all kernel objects.
System Integration
...
Conclusion
The TrustedBSD MAC framework permits kernel modules to
augment the system security policy in a highly integrated
manner. They may do this based on existing object properties,
or based on label data that is maintained with the assistance of
the MAC framework. The framework is sufficiently flexible to
implement a variety of policy types, including information flow
security policies such as MLS and Biba, as well as policies
based on existing BSD credentials or file protections. Policy
authors may wish to consult this documentation as well as
existing security modules when implementing a new security
service.
diff --git a/en_US.ISO8859-1/books/developers-handbook/mac/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/mac/chapter.sgml
index dae0ee52be..b6f82c56df 100644
--- a/en_US.ISO8859-1/books/developers-handbook/mac/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/mac/chapter.sgml
@@ -1,5681 +1,5681 @@
Chris
Costello
TrustedBSD Project
chris@FreeBSD.org
Robert
Watson
TrustedBSD Project
rwatson@FreeBSD.org
Writing MAC Policies
Synopsis
MAC, or Mandatory Access Control, is a feature introduced by
the TrustedBSD Project to supplement the existing standard DAC
- (Discreationary Access Control) policies of BSD Unix systems.
+ (Discretionary Access Control) policies of BSD Unix systems.
This chapter introduces the MAC policy framework and
provides documentation for a sample MAC policy module.
Introduction
The TrustedBSD MAC framework provides a mechanism to allow
the compile-time or run-time extension of the kernel access
control model. New system policies may be implemented as
kernel modules and linked to the kernel; if multiple policy
modules are present, their results will be composed. While the
framework is intended to support a variety of access control
models, its design was derived from the requirements of a set
of specific access control models required for the TrustedBSD
and CBOSS Projects. This includes support for fixed and
floating label Biba integrity policies, the MLS
confidentiality policy, the Type Enforcement rule-based access
control policy, and the ability to support layering of the NSA
FLASK framework above the TrustedBSD MAC framework. This
document describes the rough architecture of the framework,
with the understanding that this is a work-in-progress and may
change subtantially as requirements evolve.
Kernel Architecture
The TrustedBSD MAC framework provides the opportunity for
policy modules to be augment system access control decisions.
Policies are permitted the opportunity to restrict the set of
rights available for processes at a variety of relevant points
in the kernel. In addition, they are provided the opportunity
to tag processes and various kernel objects with labels storing
access control information. Policy modules may register
interest in a subset of the total available events or objects,
and are not required to implement events or objects that are not
relevant to the policy. Multiple modules may be loaded at once,
and the results of the modules are composed as necessary to
build an over-all system policy. Policy modules may be
implemented such that they can be loaded on-demand at run-time,
or such that they may only be loaded early in the boot process.
This permits policies requiring pervasive labeling of all
objects to prevent improper use.
Userland Architecture
...
Entry Point Framework
Four classes of entry points are offered to policies
registered with the framework: entry points associated with
the registration and management of policies, entry points
denoting initialization, creation, destruction, and other life
cycle events for kernel objects, events assocated with access
control decisions that the policy module may influence, and
calls associated with the management of labels on objects. In
addition, a mac_syscall() entry point is
provided so that policies may extend the kernel interface
without registering new system calls.
Policy module writers should be aware of the kernel
locking strategy, as well as what object locks are available
during which entry points. Writers should attempt to avoid
deadlock scenarios by avoiding grabbing non-leaf locks inside
of entry points, and also follow the locking protocol for
object access and modification. In particular, writers should
be aware that while necessary locks to access objects and
their labels are generally held, sufficient locks to modify an
object or its label may not be present for all entry points.
Locking information for arguments is documented in the MAC
framework entry point document.
Policy entry points will pass a reference to the object
label along with the object itself. This permits labeled
policies to be unaware of the internals of the object yet
still make decisions based on the label. The exception to this
is the process credential, which is assumed to be understood
by policies as a first class security object in the kernel.
Policies that do not implement labels on kernel objects will
be passed NULL pointers for label arguments to entry
points.
Policy Module Registration
Modules may be declared using the
MAC_POLICY_SET() macro, which names the
policy, provides a reference to the MAC entry point vector,
provides load-time flags determining how the policy framework
should handle the policy, and optionally requests the
allocation of label state by the framework:
static struct mac_policy_op_entry mac_none_ops[] =
{
{ MAC_DESTROY,
(macop_t)mac_none_destroy },
{ MAC_INIT,
(macop_t)mac_none_init },
{ MAC_INIT_BPFDESC,
(macop_t)mac_none_init_bpfdesc },
/* ... */
{ MAC_CHECK_VNODE_STAT,
(macop_t)mac_none_check_vnode_stat },
{ MAC_CHECK_VNODE_WRITE,
(macop_t)mac_none_check_vnode_write },
{ MAC_OP_LAST, NULL }
};
The MAC policy entry point vector,
mac_none_ops in this example, associates
functions defined in the module with specific entry points. A
complete listing of available entry points and their
prototypes may be found in the MAC entry point reference
section. Of specific interest during module registration are
the MAC_DESTROY and MAC_INIT
entry points. MAC_INIT will be invoked once a
policy is successfully registered with the module framework
but prior to any other entry points becoming active. This
permits the policy to perform any policy-specific allocation
and initialization, such as initialization of any data or
locks. MAC_DESTROY will be invoked when a
policy module is unloaded to permit releasing of any allocated
memory and destruction of locks. Currently, these two entry
points are invoked with the MAC policy list mutex held to
prevent any other entry points from being invoked: this will
be changed, but in the mean time, policies should be careful
about what kernel primitives they invoke so as to avoid lock
ordering or sleeping problems.
The policy declaration's module name field exists so that
the module may be uniquely identified for the purposes of
module dependencies. An appropriate string should be selected.
The full string name of the policy is displayed to the user
via the kernel log during load and unload events, and also
exported when providing status information to userland
processes.
The policy flags field permits the module to provide the
framework with information about its loader-related
capabilities. Currently, two flags are defined:
MPC_LOADTIME_FLAG_UNLOADOK
This flag indicates that the policy module may be
unloaded. If this flag is not provided, then the policy
framework will reject requests to unload the module.
This flag might be used by modules that allocate label
state and are unable to free that state at
runtime.
MPC_LOADTIME_FLAG_NOTLATE
This flag indicates that the policy module
must be loaded and initialized early in the boot
process. If the flag is specified, attempts to register
the module following boot will be rejected. The flag
may be used by policies that require pervasive labeling
of all system objects, and cannot handle objects that
have not been properly initialized by the policy.
&mac.mpo;_init
void
&mac.mpo;_init
struct mac_policy_conf
*conf
&mac.thead;
conf
MAC policy definition
Policy load event. The policy list mutex is held, so
caution should be applied.
&mac.mpo;_destroy
void
&mac.mpo;_destroy
struct mac_policy_conf
*conf
&mac.thead;
conf
MAC policy definition
Policy load event. The policy list mutex is held, so
caution should be applied.
Label Events
This class of entry points is used by the MAC framework to
permit policies to maintain label information on kernel
objects. For each labeled kernel object of interest to a MAC
policy, entry points may be registered for relevant life cycle
events. All objects implement initialization, creation, and
destruction hooks. Some objects will also implement
relabeling, allowing user processes to change the labels on
objects. Some objects will also implement object-specific
events, such as label events associated with IP reassembly. A
typical labeled object will have the following life cycle of
entry points:
Label initialization o
(object-specific wait) \
Label creation o
\
Relabel events, o--<--.
Various object-specific, | |
Access control events ~-->--o
\
Label destruction o
Label initialization permits policies to allocate memory
and set initial values for labels without context for the use
of the object. The label slot allocated to a policy will be
zero'd by default, so some policies may not need to perform
initialization.
Label creation occurs when the kernel structure is
associated with an actual kernel object. For example, mbufs
may be allocated and remain unused in a pool until they are
required. mbuf allocation causes label initialization on the
mbuf to take place, but mbuf creation occurs when the mbuf is
associated with a datagram. Typically, context will be
provided for a creation event, including the circumstances of
the creation, and labels of other relevant objects in the
creation process. For example, when an mbuf is created from a
socket, the socket and its label will be presented to
registered policies in addition to the new mbuf and its label.
Memory allocation in creation events is discouraged, as it may
occur in performance sensitive ports of the kernel; in
addition, creation calls are not permitted to fail so a
failure to allocate memory cannot be reported.
Object specific events do not generally fall into the
other broad classes of label events, but will generally
provide an opportunity to modify or update the label on an
object based on additional context. For example, the label on
an IP fragment reassembly queue may be updated during the
MAC_UPDATE_IPQ entry point as a result of the
acceptance of an additional mbuf to that queue.
Access control events are discussed in detail in the
following section.
Label destruction permits policies to release storage or
state associated with a label during its association with an
object so that the kernel data structures supporting the
object may be reused or released.
In addition to labels associated with specific kernel
objects, an additional class of labels exists: temporary
labels. These labels are used to store update information
submitted by user processes. These labels are initialized and
destroyed as with other label types, but the creation event is
MAC_INTERNALIZE, which accepts a user label
to be converted to an in-kernel representation.
File System Object Labeling Event Operations
&mac.mpo;_create_devfs_device
void
&mac.mpo;_create_devfs_device
dev_t dev
struct devfs_dirent
*devfs_dirent
struct label
*label
&mac.thead;
dev
Device corresponding with
devfs_dirent
devfs_dirent
Devfs directory entry to be labeled.
label
Label for devfs_dirent
to be filled in.
Fill out the label on a devfs_dirent being created for
the passed device. This call will be made when the device
file system is mounted, regenerated, or a new device is made
available.
&mac.mpo;_create_devfs_directory
void
&mac.mpo;_create_devfs_directory
char *dirname
int dirnamelen
struct devfs_dirent
*devfs_dirent
struct label
*label
&mac.thead;
dirname
Name of directory being created
namelen
Length of string
dirname
devfs_dirent
Devfs directory entry for directory being
created.
Fill out the label on a devfs_dirent being created for
the passed directory. This call will be made when the device
file system is mounted, regenerated, or a new device
requiring a specific directory hierarchy is made
available.
&mac.mpo;_create_devfs_vnode
void
&mac.mpo;_create_devfs_vnode
struct devfs_dirent
*devfs_dirent
struct label
*direntlabel
struct vnode
*vp
struct label
*vnodelabel
&mac.thead;
devfs_dirent
Object; devfs directory entry
direntlabel
Policy label for
devfs_dirent
vp
Object; file system object being labeled
vnodelabel
Policy label to be filled in for
vp
Fill out the label on the vnode being created for the
passed devfs_dirent. This call will be made when a vnode is
required to represent the specified devfs_dirent in a
mounted devfs instance.
&mac.mpo;_vnode_create_from_vnode
void
&mac.mpo;_vnode_create_from_vnode
struct ucred
*cred
struct vnode
*parent
struct label
*parentlabel
struct vnode
*child
struct label
*childlabel
&mac.thead;
cred
Subject credential
parent
Parent vnode; the directory in which
child is being
created
parentlabel
Policy label for
parent
child
New vnode
childlabel
Label to be filled in for
child
Fill out the label on the vnode being created in the
passed vnode parent by the passed subject credential. This
call will be made when a vnode is allocated during a vnode
creation operation. For example, this call is made by
multi-label file systems during the creation of a new file
or directory.
&mac.mpo;_create_mount
void
&mac.mpo;_create_mount
struct ucred
*cred
struct mount
*mp
struct label
*mnt
struct label
*fslabel
&mac.thead;
cred
Subject credential
mp
Object; file system being mounted
mntlabel
Policy label to be filled in for
mp
fslabel
Policy label for the file system
mp mounts.
Fill out the labels on the mount point being created by
the passed subject credential. This call will be made when
a new file system is mounted.
&mac.mpo;_create_root_mount
void
&mac.mpo;_create_root_mount
struct ucred
*cred
struct mount
*mp
struct label
*mntlabel
struct label
*fslabel
&mac.thead;
See .
Fill out the labels on the mount point being created by
the passed subject credential. This call will be made when
the root file system is mounted, after
&mac.mpo;_create_mount;.
&mac.mpo;_vnode_relabel
void
&mac.mpo;_vnode_relabel
struct ucred
*cred
struct vnode
*vp
struct label
*vnodelabel
struct label
*newlabel
&mac.thead;
cred
Subject credential
vp
vnode to relabel
vnodelabel
Existing policy label for
vp
newlabel
New, possibly partial label to replace
vnodelabel
Update the label on the passed vnode given the passed
update vnode label and the passed subject credential.
&mac.mpo;_stdcreatevnode_ea
int
&mac.mpo;_stdcreatevnode_ea
struct vnode
*vp
struct label
*vnodelabel
&mac.thead;
vp
vnode to commit
Locked on entry, locked on exit
vnodelabel
Label associated with
vp
This entry point is called when a vnode is to be
committed to disk via the extended attribute service (see
&man.extattr.9;). If committing to the disk is successful,
a value of 0 should be returned;
otherwise, an appropriate error code should be
returned.
The current implementation as of July 24, 2002
commits the data to disk from within the architecture.
The implementation will be updated to be closer to the
above documentation as development progresses.
&mac.mpo;_update_devfsdirent
void
&mac.mpo;_update_devfsdirent
struct devfs_dirent
*devfs_dirent
struct label
*direntlabel
struct vnode
*vp
struct label
*vnodelabel
&mac.thead;
devfs_dirent
Object; devfs directory entry
direntlabel
Policy label for
devfs_dirent to be
updated.
vp
Parent vnode
Locked
vnodelabel
Policy label for
vp
Update the devfs_dirent label
from the passed devfs vnode label. This call will be made
when a devfs vnode has been successfully relabeled to commit
the label change such that it lasts even if the vnode is
recycled. It will also be made when when a symlink is
created in devfs, following a call to
mac_vnode_create_from_vnode to
initialize the vnode label.
&mac.mpo;_update_procfsvnode
void
&mac.mpo;_update_procfsvnode
struct vnode
*vp
struct label
*vnodelabel
struct ucred
*cred
&mac.thead;
vp
Object; procfs vnode
Locked
vnodelabel
Policy label to be filled in for
vp
cred
Subject; credential for the process
entry
Immutable
Update the procfs vnode label from the passed subject
credential. This call will be made when an operation on a
procfs vnode requires a fresh label on a process-derived
vnode.
&mac.mpo;_update_vnode_from_extattr
int
&mac.mpo;_update_vnode_from_extattr
struct vnode
*vp
struct label
*vnodelabel
struct mount
*mp
struct label
*fslabel
&mac.thead;
vp
Object; vnode whose label is being updated
Locked
vnodelabel
Policy label to refresh
mp
Mount point for
vp
fslabel
Policy label for vp's
file system.
Update the vnode label by refreshing the label data from
the extended attribute service for the vnode. The mount
point fslabel is also made available
so that the fslabel may be used as a
labeling source if fallback is appropriate for the policy.
This call is permitted to fail; if the call fails, the
associated label refresh will also fail, causing the failure
of the operation requiring the MAC check and vnode label
refresh, permitting a fail closed
policy if
labeling data is not available.
&mac.mpo;_update_from_externalized
int
&mac.mpo;_update_from_externalized
struct vnode
*vp
struct label
*vnodelabel
struct mac
*extmac
&mac.thead;
vp
Object; vnode
Locked
vnodelabel
Policy label for
vp
extmac
Externalized MAC policy label
Update the vnode label from the passed externalized
label loaded from disk by the MAC framework. This call is
permitted to fail; if the call fails, the associated label
refresh will also fail, causing the failure of the operation
requiring the MAC check and vnode label refresh, permitting
a fail closed
policy if labeling data is not
available. This call will be obsoleted by the new extended
attribute labeling interface.
&mac.mpo;_update_vnode_from_mount
void
&mac.mpo;_update_vnode_from_mount
struct vnode
*vp
struct label
*vnodelabel
struct mount
*mp
struct label
*mountlabel
&mac.thead;
vp
Object; vnode
Locked
vnodelabel
Policy label for
vp
mp
Mount point where vp
resides
fslabel
Policy label for the file system where
vp resides.
Update the vnode label from the passed mount point
label. This call is made when a single label file system
vnode requires a label, or if the obsoleted MAC framework
externalized extended attribute read fails.
IPC Object Labeling Event Operations
&mac.mpo;_create_mbuf_from_socket
void
&mac.mpo;_create_mbuf_from_socket
struct socket
*so
struct label
*socketlabel
struct mbuf *m
struct label
*mbuflabel
&mac.thead;
socket
Socket
Socket locking WIP
socketlabel
Policy label for
socket
m
Object; mbuf
mbuflabel
Policy label to fill in for
m
Set the label on a newly created mbuf header from the
passed socket label. This call is made when a new datagram
or messsage is generated by the socket and stored in the
passed mbuf.
&mac.mpo;_create_socket
void
&mac.mpo;_create_socket
struct ucred
*cred
struct socket
*so
struct label
*socketlabel
&mac.thead;
cred
Subject credential
Immutable
so
Object; socket to label
socketlabel
Label to fill in for
so
Set the label on a newly created socket from the passed
subject credential. This call is made when a socket is
created.
&mac.mpo;_create_socket_from_socket
void
&mac.mpo;_create_socket_from_socket
struct socket
*oldsocket
struct label
*oldsocketlabel
struct socket
*newsocket
struct label
*newsocketlabel
&mac.thead;
oldsocket
Object; parent socket; created from
&man.listen.2;
oldsocketlabel
Label for
oldsocket
newsocket
Object; child socket; incoming connection
newsocketlabel
Label to be filled in for
newsocket
Set the label on a newly created stream socket from the
passed listen socket. This call may occur during &man.accept.2;,
or prior to &man.accept.2;, depending on the protocol.
&mac.mpo;_socket_relabel
void
&mac.mpo;_socket_relabel
struct ucred
*cred
struct socket
*so
struct label
*oldlabel
struct label
*newlabel
&mac.thead;
cred
Subject credential
Immutable
so
Object; socket
oldlabel
Current label for
so
newlabel
Label update for
so
Update the label on a socket from the passed socket
label update.
&mac.mpo;_set_socket_peer_from_mbuf
void
&mac.mpo;_set_socket_peer_from_mbuf
struct mbuf
*mbuf
struct label
*mbuflabel
struct label
*oldlabel
struct label
*newlabel
&mac.thead;
mbuf
First datagram received over socket
mbuflabel
Label for mbuf
oldlabel
Current label for the socket
newlabel
Policy label to be filled out for the
socket
Set the peer label on a stream socket from the passed
mbuf label. This call will be made when the first datagram
is received by the stream socket, with the exception of Unix
domain sockets.
&mac.mpo;_set_socket_peer_from_socket
void
&mac.mpo;_set_socket_peer_from_socket
struct socket
*oldsocket
struct label
*oldsocketlabel
struct socket
*newsocket
struct label
*newsocketpeerlabel
&mac.thead;
oldsocket
Local socket
oldsocketlabel
Policy label for
oldsocket
newsocket
Peer socket
newsocketpeerlabel
Policy label to fill in for
newsocket
Set the peer label on a stream UNIX domain socket from
the passed remote socket endpoint. This call will be made
when the socket pair is connected, and will be made for both
endpoints.
Network Object Labeling Event Operations
&mac.mpo;_create_bpfdesc
void
&mac.mpo;_create_bpfdesc
struct ucred
*cred
struct bpf_d
*bpf_d
struct label
*bpflabel
&mac.thead;
cred
Subject credential
Immutable
bpf_d
Object; bpf descriptor
bpf
Policy label to be filled in for
bpf_d
Set the label on a newly created BPF descriptor from the
passed subject credential. This call will be made when a
BPF device node is opened by a process with the passed
subject credential.
&mac.mpo;_create_ifnet
void
&mac.mpo;_create_ifnet
struct ifnet
*ifnet
struct label
*ifnetlabel
&mac.thead;
ifnet
Network interface
ifnetlabel
Policy label to fill in for
ifnet
Set the label on a newly created interface. This call
may be made when a new physical interface becomes available
to the system, or when a pseudo-interface is instantiated
during the boot or as a result of a user action.
&mac.mpo;_create_ipq
void
&mac.mpo;_create_ipq
struct mbuf
*fragment
struct label
*fragmentlabel
struct ipq
*ipq
struct label
*ipqlabel
&mac.thead;
fragment
First received IP fragment
fragmentlabel
Policy label for
fragment
ipq
IP reassembly queue to be labeled
ipqlabel
Policy label to be filled in for
ipq
Set the label on a newly created IP fragment reassembly
queue from the mbuf header of the first received
fragment.
&mac.mpo;_create_datagram_from_ipq
void
&mac.mpo;_create_create_datagram_from_ipq
struct ipq
*ipq
struct label
*ipqlabel
struct mbuf
*datagram
struct label
*datagramlabel
&mac.thead;
ipq
IP reassembly queue
ipqlabel
Policy label for
ipq
datagram
Datagram to be labeled
datagramlabel
Policy label to be filled in for
datagramlabel
Set the label on a newly reassembled IP datagram from
the IP fragment reassembly queue from which it was
generated.
&mac.mpo;_create_fragment
void
&mac.mpo;_create_fragment
struct mbuf
*datagram
struct label
*datagramlabel
struct mbuf
*fragment
struct label
*fragmentlabel
&mac.thead;
datagram
Datagram
datagramlabel
Policy label for
datagram
fragment
Fragment to be labeled
fragmentlabel
Policy label to be filled in for
datagram
Set the label on the mbuf header of a newly created IP
fragment from the label on the mbuf header of the datagram
it was generate from.
&mac.mpo;_create_mbuf_from_mbuf
void
&mac.mpo;_create_mbuf_from_mbuf
struct mbuf
*oldmbuf
struct label
*oldmbuflabel
struct mbuf
*newmbuf
struct label
*newmbuflabel
&mac.thead;
oldmbuf
Existing (source) mbuf
oldmbuflabel
Policy label for
oldmbuf
newmbuf
New mbuf to be labeled
newmbuflabel
Policy label to be filled in for
newmbuf
Set the label on the mbuf header of a newly created
datagram from the mbuf header of an existing datagram. This
call may be made in a number of situations, including when
an mbuf is re-allocated for alignment purposes.
&mac.mpo;_create_mbuf_linklayer
void
&mac.mpo;_create_mbuf_linklayer
struct ifnet
*ifnet
struct label
*ifnetlabel
struct mbuf
*mbuf
struct label
*mbuflabel
&mac.thead;
ifnet
Network interface
ifnetlabel
Policy label for
ifnet
mbuf
mbuf header for new datagram
mbuflabel
Policy label to be filled in for
mbuf
Set the label on the mbuf header of a newly created
datagram generated for the purposes of a link layer response
for the passed interface. This call may be made in a number
of situations, including for ARP or ND6 responses in the
IPv4 and IPv6 stacks.
&mac.mpo;_create_mbuf_from_bpfdesc
void
&mac.mpo;_create_mbuf_from_bpfdesc
struct bpf_d
*bpf_d
struct label
*bpflabel
struct mbuf
*mbuf
struct label
*mbuflabel
&mac.thead;
bpf_d
BPF descriptor
bpflabel
Policy label for
bpflabel
mbuf
New mbuf to be labeled
mbuflabel
Policy label to fill in for
mbuf
Set the label on the mbuf header of a newly created
datagram generated using the passed BPF descriptor. This
call is made when a write is performed to the BPF device
associated with the passed BPF descriptor.
&mac.mpo;_create_mbuf_from_ifnet
void
&mac.mpo;_create_mbuf_from_ifnet
struct ifnet
*ifnet
struct label
*ifnetlabel
struct mbuf
*mbuf
struct label
*mbuflabel
&mac.thead;
ifnet
Network interface
ifnetlabel
Policy label for
ifnetlabel
mbuf
mbuf header for new datagram
mbuflabel
Policy label to be filled in for
mbuf
Set the label on the mbuf header of a newly created
datagram generated from the passed network interface.
&mac.mpo;_create_mbuf_multicast_encap
void
&mac.mpo;_create_mbuf_multicast_encap
struct mbuf
*oldmbuf
struct label
*oldmbuflabel
struct ifnet
*ifnet
struct label
*ifnetlabel
struct mbuf
*newmbuf
struct label
*newmbuflabel
&mac.thead;
oldmbuf
mbuf header for existing datagram
oldmbuflabel
Policy label for
oldmbuf
ifnet
Network interface
ifnetlabel
Policy label for
ifnet
newmbuf
mbuf header to be labeled for new
datagram
newmbuflabel
Policy label to be filled in for
newmbuf
Set the label on the mbuf header of a newly created
datagram generated from the existing passed datagram when it
is processed by the passed multicast encapsulation
interface. This call is made when an mbuf is to be
delivered using the virtual interface.
&mac.mpo;_create_mbuf_netlayer
void
&mac.mpo;_create_mbuf_netlayer
struct mbuf
*oldmbuf
struct label
*oldmbuflabel
struct mbuf
*newmbuf
struct label
*newmbuflabel
&mac.thead;
oldmbuf
Received datagram
oldmbuflabel
Policy label for
oldmbuf
newmbuf
Newly created datagram
newmbuflabel
Policy label for
newmbuf
Set the label on the mbuf header of a newly created
datagram generated by the IP stack in response to an
existing received datagram (oldmbuf).
This call may be made in a number of situations, including
when responding to ICMP request datagrams.
&mac.mpo;_fragment_match
int
&mac.mpo;_fragment_match
struct mbuf
*fragment
struct label
*fragmentlabel
struct ipq
*ipq
struct label
*ipqlabel
&mac.thead;
fragment
IP datagram fragment
fragmentlabel
Policy label for
fragment
ipq
IP fragment reassembly queue
ipqlabel
Policy label for
ipq
Determine whether an mbuf header containing an IP
datagram (fragment) fragment matches
the label of the passed IP fragment reassembly queue
(ipq). Return
(1) for a successful match, or
(0) for no match. This call is
made when the IP stack attempts to find an existing fragment
reassembly queue for a newly received fragment; if this
fails, a new fragment reassembly queue may be instantiated
for the fragment. Policies may use this entry point to
prevent the reassembly of otherwise matching IP fragments if
policy does not permit them to be reassembled based on the
label or other information.
&mac.mpo;_ifnet_relabel
void
&mac.mpo;_ifnet_relabel
struct ucred
*cred
struct ifnet
*ifnet
struct label
*ifnetlabel
struct label
*newlabel
&mac.thead;
cred
Subject credential
ifnet
Object; Network interface
ifnetlabel
Policy label for
ifnet
newlabel
Label update to apply to
ifnet
Update the label of network interface,
ifnet, based on the passed update
label, newlabel, and the passed
subject credential, cred.
&mac.mpo;_update_ipq
void
&mac.mpo;_update_ipq
struct mbuf
*fragment
struct label
*fragmentlabel
struct ipq
*ipq
struct label
*ipqlabel
&mac.thead;
mbuf
IP fragment
mbuflabel
Policy label for
mbuf
ipq
IP fragment reassembly queue
ipqlabel
Policy label to be updated for
ipq
Update the label on an IP fragment reassembly queue
(ipq) based on the acceptance of the
passed IP fragment mbuf header
(mbuf).
Process Labeling Event Operations
&mac.mpo;_create_cred
void
&mac.mpo;_create_cred
struct ucred
*parent_cred
struct ucred
*child_cred
&mac.thead;
parent_cred
Parent subject credential
child_cred
Child subject credential
Set the label of a newly created subject credential from
the passed subject credential. This call will be made when
crcopy(9) is invoked on a newly created struct
ucred. This call should not be confused with a
process forking or creation event.
&mac.mpo;_execve_transition
void
&mac.mpo;_execve_transition
struct ucred
*old
struct ucred
*new
struct vnode
*vp
struct label
*vnodelabel
&mac.thead;
old
Existing subject credential
Immutable
new
New subject credential to be labeled
vp
File to execute
Locked
vnodelabel
Policy label for
vp
Update the label of a newly created subject credential
(new) from the passed existing
subject credential (old) based on a
label transition caused by executing the passed vnode
(vp). This call occurs when a
process executes the passed vnode and one of the policies
returns a success from the
mpo_execve_will_transition entry point.
Policies may choose to implement this call simply by
invoking mpo_create_cred and passing
the two subject credentials so as not to implement a
transitioning event. Policies should not leave this entry
point unimplemented if they implement
mpo_create_cred, even if they do not
implement
mpo_execve_will_transition.
&mac.mpo;_execve_will_transition
int
&mac.mpo;_execve_will_transition
struct ucred
*old
struct vnode
*vp
struct label
*vnodelabel
&mac.thead;
old
Subject credential prior to
&man.execve.2;
Immutable
vp
File to execute
vnodelabel
Policy label for
vp
Determine whether the policy will want to perform a
transition event as a result of the execution of the passed
vnode by the passed subject credential. Return
1 if a transition is required,
0 if not. Even if a policy
returns 0, it should behave
correctly in the presence of an unexpected invocation of
mpo_execve_transition, as that call may
happen as a result of another policy requesting a
transition.
&mac.mpo;_create_proc0
void
&mac.mpo;_create_proc0
struct ucred
*cred
&mac.thead;
cred
Subject credential to be filled in
Create the subject credential of process 0, the parent
of all kernel processes.
&mac.mpo;_create_proc1
void
&mac.mpo;_create_proc1
struct ucred
*cred
&mac.thead;
cred
Subject credential to be filled in
Create the subject credential of process 1, the parent
of all kernel processes.
&mac.mpo;_cred_relabel
void
&mac.mpo;_cred_relabel
struct ucred
*cred
struct label
*newlabel
&mac.thead;
cred
Subject credential
newlabel
Label update to apply to
cred
Update the label on a subject credential from the passed
update label.
Access Control Checks
Access control entry points permit policy modules to
influence access control decisions made by the kernel.
Generally, although not always, arguments to an access control
entry point will include one or more authorizing credentials,
information (possibly including a label) for any other objects
involved in the operation. An access control entry point may
return 0 to permit the operation, and an &man.errno.2; error
value. The results of invoking the entry point across various
registered policy modules will be composed as follows: if all
modules permit the operation to succeed, success will be
returned. If one or modules returns a failure, a failure will
be returned. If more than one module returns a failure, the
errno value to return to the user will be selected using the
following precedence, implemented by the
error_select() function in
kern_mac.c:
Most precedence
EDEADLK
EINVAL
ESRCH
EACCES
Least precedence
EPERM
If none of the error values returned by all modules are
listed in the precedence chart then an arbitrarily selected
value from the set will be returned. In general, the rules
provide precedence to errors in the following order: kernel
failures, invalid arguments, object not present, access not
permitted, other.
&mac.mpo;_check_bpfdesc_receive
int
&mac.mpo;_check_bpfdesc_receive
struct bpf_d
*bpf_d
struct label
*bpflabel
struct ifnet
*ifnet
struct label
*ifnetlabel
&mac.thead;
bpf_d
Subject; BPF descriptor
bpflabel
Policy label for
bpf_d
ifnet
Object; network interface
ifnetlabel
Policy label for
ifnet
Determine whether the MAC framework should permit
datagrams from the passed interface to be delivered to the
buffers of the passed BPF descriptor. Return
(0) for success, or an
errno value for failure Suggested
failure: EACCES for label mismatches,
EPERM for lack of privilege.
&mac.mpo;_check_socket_bind
int
&mac.mpo;_check_socket_bind
struct ucred
*cred
struct socket
*socket
struct label
*socketlabel
struct sockaddr
*sockaddr
&mac.thead;
cred
Subject credential
socket
Socket to be bound
socketlabel
Policy label for
socket
sockaddr
Address of
socket
&mac.mpo;_check_socket_connect
int
&mac.mpo;_check_socket_connect
struct ucred
*cred
struct socket
*socket
struct label
*socketlabel
struct sockaddr
*sockaddr
&mac.thead;
cred
Subject credential
socket
Socket to be connected
socketlabel
Policy label for
socket
sockaddr
Address of
socket
Determine whether the subject credential
(cred) can connect the passed socket
(socket) to the passed socket address
(sockaddr). Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatches,
EPERM for lack of privilege.
&mac.mpo;_check_cred_visible
int
&mac.mpo;_check_cred_visible
struct ucred
*u1
struct ucred
*u2
&mac.thead;
u1
Subject credential
u2
Object credential
Determine whether the subject credential
u1 can see
other
subjects with the passed subject credential
u2. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatches,
EPERM for lack of privilege, or
ESRCH to hide visibility. This call
may be made in a number of situations, including
inter-process status sysctls used by ps,
and in procfs lookups.
&mac.mpo;_check_socket_visible
int
&mac.mpo;_check_socket_visible
struct ucred
*cred
struct socket
*socket
struct label
*socketlabel
&mac.thead;
cred
Subject credential
socket
Object; socket
socketlabel
Policy label for
socket
&mac.mpo;_check_ifnet_relabel
int
&mac.mpo;_check_ifnet_relabel
struct ucred
*cred
struct ifnet
*ifnet
struct label
*ifnetlabel
struct label
*newlabel
&mac.thead;
cred
Subject credential
ifnet
Object; network interface
ifnetlabel
Existing policy label for
ifnet
newlabel
Policy label update to later be applied to
ifnet
Determine whether the subject credential can relabel the
passed network interface to the passed label update.
&mac.mpo;_check_socket_relabel
int
&mac.mpo;_check_socket_relabel
struct ucred
*cred
struct socket
*socket
struct label
*socketlabel
struct label
*newlabel
&mac.thead;
cred
Subject credential
socket
Object; socket
socketlabel
Existing policy label for
socket
newlabel
Label update to later be applied to
socketlabel
Determine whether the subject credential can relabel the
passed socket to the passed label update.
&mac.mpo;_check_cred_relabel
int
&mac.mpo;_check_cred_relabel
struct ucred
*cred
struct label
*newlabel
&mac.thead;
cred
Subject credential
newlabel
Label update to later be applied to
cred
Determine whether the subject credential can relabel
itself to the passed label update.
&mac.mpo;_check_vnode_relabel
int
&mac.mpo;_check_vnode_relabel
struct ucred
*cred
struct vnode
*vp
struct label
*vnodelabel
struct label
*newlabel
&mac.thead;
cred
Subject credential
Immutable
vp
Object; vnode
Locked
vnodelabel
Existing policy label for
vp
newlabel
Policy label update to later be applied to
vp
Determine whether the subject credential can relabel the
passed vnode to the passed label update.
&mac.mpo;_check_mount_stat
int &mac.mpo;_check_mount_stat
struct ucred
*cred
struct mount
*mp
struct label
*mountlabel
&mac.thead;
cred
Subject credential
mp
Object; file system mount
mountlabel
Policy label for
mp
Determine whether the subject credential can see the
results of a statfs performed on the file system. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatches
or EPERM for lack of privilege. This
call may be made in a number of situations, including during
invocations of &man.statfs.2; and related calls, as well as to
determine what file systems to exclude from listings of file
systems, such as when &man.getfsstat.2; is invoked.
&mac.mpo;_check_proc_debug
int
&mac.mpo;_check_proc_debug
struct ucred
*cred
struct proc
*proc
&mac.thead;
cred
Subject credential
Immutable
proc
Object; process
Determine whether the subject credential can debug the
passed process. Return 0 for
success, or an errno value for failure.
Suggested failure: EACCES for label
mismatch, EPERM for lack of
privilege, or ESRCH to hide
visibility of the target. This call may be made in a number
of situations, including use of the &man.ptrace.2; and
&man.ktrace.2; APIs, as well as for some types of procfs
operations.
&mac.mpo;_check_vnode_access
int
&mac.mpo;_check_vnode_access
struct ucred
*cred
struct vnode
*vp
struct label
*label
int flags
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for
vp
flags
&man.access.2; flags
Determine how invocations of &man.access.2; and related
calls by the subject credential should return when performed
on the passed vnode using the passed access flags. This
should generally be implemented using the same semantics
used in &mac.mpo;_check_vnode_open.
Return 0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatches
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_chdir
int
&mac.mpo;_check_vnode_chdir
struct ucred
*cred
struct vnode
*dvp
struct label
*dlabel
&mac.thead;
cred
Subject credential
dvp
Object; vnode to &man.chdir.2; into
dlabel
Policy label for
dvp
Determine whether the subject credential can change the
process working directory to the passed vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_create
int
&mac.mpo;_check_vnode_create
struct ucred
*cred
struct vnode
*dvp
struct label
*dlabel
struct componentname
*cnp
struct vattr
*vap
&mac.thead;
cred
Subject credential
dvp
Object; vnode
dlabel
Policy label for
dvp
cnp
Component name for
dvp
vap
vnode attributes for vap
Determine whether the subject credential can create a
vnode with the passed parent directory, passed name
information, and passed attribute information. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES. for label mismatch,
or EPERM for lack of privilege.
This call may be made in a number of situations, including
as a result of calls to &man.open.2; with
O_CREAT, &man.mknod.2;, &man.mkfifo.2;, and
others.
&mac.mpo;_check_vnode_delete
int
&mac.mpo;_check_vnode_delete
struct ucred
*cred
struct vnode
*dvp
struct label
*dlabel
struct vnode
*vp
void *label
struct componentname
*cnp
&mac.thead;
cred
Subject credential
dvp
Parent directory vnode
dlabel
Policy label for
dvp
vp
Object; vnode to delete
label
Policy label for
vp
cnp
Component name for
vp
Determine whether the subject credential can delete a
vnode from the passed parent directory and passed name
information. Return 0 for
success, or an errno value for failure.
Suggested failure: EACCES for label
mismatch, or EPERM for lack of
privilege. This call may be made in a number of situations,
including as a result of calls to &man.unlink.2; and
&man.rmdir.2;. Policies implementing this entry point
should also implement
mpo_check_rename_to to authorize
deletion of objects as a result of being the target of a
rename.
&mac.mpo;_check_vnode_deleteacl
int
&mac.mpo;_check_vnode_deleteacl
struct ucred *cred
struct vnode *vp
struct label *label
acl_type_t type
&mac.thead;
cred
Subject credential
Immutable
vp
Object; vnode
Locked
label
Policy label for
vp
type
ACL type
Determine whether the subject credential can delete the
ACL of passed type from the passed vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_exec
int
&mac.mpo;_check_vnode_exec
struct ucred
*cred
struct vnode
*vp
struct label
*label
&mac.thead;
cred
Subject credential
vp
Object; vnode to execute
label
Policy label for
vp
Determine whether the subject credential can execute the
passed vnode. Determination of execute privilege is made
seperately from decisions about any transitioning event.
Return 0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_getacl
int
&mac.mpo;_check_vnode_getacl
struct ucred
*cred
struct vnode
*vp
struct label
*label
acl_type_t
type
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for
vp
type
ACL type
Determine whether the subject credentical can retrieve
the ACL of passed type from the passed vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_getextattr
int
&mac.mpo;_check_vnode_getextattr
struct ucred
*cred
struct vnode
*vp
struct label
*label
int
attrnamespace
const char
*name
struct uio
*uio
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for
vp
attrnamespace
Extended attribute namespace
name
Extended attribute name
uio
I/O structure pointer; see &man.uio.9;
Determine whether the subject credential can retrieve
the extended attribute with the passed namespace and name
from the passed vnode. Policies implementing labeling using
extended attributes may be interested in special handling of
operations on those extended attributes. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_socket_listen
int
&mac.mpo;_check_socket_listen
struct ucred
*cred
struct socket
*socket
struct label
*socketlabel
&mac.thead;
cred
Subject credential
socket
Object; socket
socketlabel
Policy label for
socket
Determine whether the subject credential can listen on
the passed socket. Return 0 for
success, or an errno value for failure.
Suggested failure: EACCES for label
mismatch, or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_lookup
int
&mac.mpo;_check_vnode_lookup
struct ucred
*cred
struct vnode
*dvp
struct label
*dlabel
struct componentname
*cnp
&mac.thead;
cred
Subject credential
dvp
Object; vnode
dlabel
Policy label for
dvp
cnp
Component name being looked up
Determine whether the subject credential can perform a
lookup in the passed directory vnode for the passed name.
Return 0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_open
int
&mac.mpo;_check_vnode_open
struct ucred
*cred
struct vnode
*vp
struct label
*label
mode_t
acc_mode
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for
vp
acc_mode
&man.open.2; access mode
Determine whether the subject credential can perform an
open operation on the passed vnode with the passed access
mode. Return 0 for success, or
an errno value for failure. Suggested failure:
EACCES for label mismatch, or
EPERM for lack of privilege.
&mac.mpo;_check_vnode_readdir
int
&mac.mpo;_check_vnode_readdir
struct ucred
*cred
struct vnode
*dvp
struct label
*dlabel
&mac.thead;
cred
Subject credential
dvp
Object; directory vnode
dlabel
Policy label for
dvp
Determine whether the subject credential can perform a
readdir operation on the passed
directory vnode. Return 0 for
success, or an errno value for failure.
Suggested failure: EACCES for label
mismatch, or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_readlink
int
&mac.mpo;_check_vnode_readlink
struct ucred
*cred
struct vnode
*vp
struct label
*label
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for
vp
Determine whether the subject credential can perform a
readlink operation on the passed
symlink vnode. Return 0 for
success, or an errno value for failure.
Suggested failure: EACCES for label
mismatch, or EPERM for lack of
privilege. This call may be made in a number of situations,
including an explicit readlink call by
the user process, or as a result of an implicit
readlink during a name lookup by the
process.
&mac.mpo;_check_rename_from_vnode
int
&mac.mpo;_check_rename_from_vnode
struct ucred
*cred
struct vnode
*dvp
struct label
*dlabel
struct vnode
*vp
struct label
*label
struct componentname
*cnp
&mac.thead;
cred
Subject credential
dvp
Directory vnode
dlabel
Policy label for
dvp
vp
Object; vnode
label
Policy label for
vp
cnp
Pathname
Determine whether the subject credential can rename the
passed vnode (vp) in the passed
directory (dvp) using the passed name
(cnp). This call will be made in
combination with a follow-up call to
mpo_check_rename_to_vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_rename_to_vnode
int
&mac.mpo;_check_rename_to_vnode
struct ucred
*cred
struct vnode
*dvp
struct label
*dlabel
struct vnode
*vp
struct label
*label
int samedir
struct componentname
*cnp
&mac.thead;
cred
Subject credential
dvp
Directory vnode
dlabel
Policy label for dvp
vp
Object; vnode
label
Policy label for
vp
cnp
Pathname
Determine whether the subject credential can rename to
the passed vnode (vp) and the passed
directory (dvp) with the passed name
(cnp). This call will be made in
combination with an earlier call to
mpo_check_rename_from_vnode.
Return 0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_revoke
int
&mac.mpo;_check_vnode_revoke
struct ucred
*cred
struct vnode
*vp
struct label
*label
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for
vp
Determine whether the subject credential can revoke
access to the passed vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_setacl
int
&mac.mpo;_check_vnode_setacl
struct ucred
*cred
struct vnode
*vp
struct label
*label
acl_type_t
type
struct acl
*acl
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for
vp
type
ACL type
acl
ACL
Determine whether the subject credential can set the
passed ACL of passed type on the passed vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_setextattr
int
&mac.mpo;_check_vnode_setextattr
struct ucred
*cred
struct vnode
*vp
struct label
*label
int
attrnamespace
const char
*name
struct uio
*uio
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for vp
attrnamespace
Extended attribute namespace
name
Extended attribute name
uio
I/O structure pointer; see &man.uio.9;
Determine whether the subject credentical can set the
extended attribute of passed name and passed namespace on
the passed vnode. Policies implementing security labels
backed into extended attributes may want to provide
additional protections for those attributes. Additionally,
policies should avoid making decisions based on the data
referenced from uio, as there is a
potential race condition between this check and the actual
operation. The uio may also be
NULL if a delete operation is being
performed. Return 0 for success,
or an errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_setflags
int
&mac.mpo;_check_vnode_setflags
struct ucred
*cred
struct vnode
*vp
struct label
*label
u_long flags
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for
vp
flags
File flags; see &man.chflags.2;
Determine whether the subject credential can set the
passed flags on the passed vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_setmode
int
&mac.mpo;_check_vnode_setmode
struct ucred
*cred
struct vnode
*vp
struct label
*label
mode_t mode
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for vp
mode
File mode; see &man.chmod.2;
Determine whether the subject credential can set the
pased mode on the passed vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_vnode_setowner
int
&mac.mpo;_check_vnode_setowner
struct ucred
*cred
struct vnode
*vp
struct label
*label
uid_t uid
gid_t gid
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for vp
uid
User ID
gid
Group ID
Determine whether the subject credential can set the
passed uid and passed gid as file uid and file gid on the
passed vnode. The IDs may be set to (-1)
to request no update. Return 0
for success, or an errno value for
failure. Suggested failure: EACCES
for label mismatch, or EPERM for lack
of privilege.
&mac.mpo;_check_vnode_setutimes
int
&mac.mpo;_check_vnode_setutimes
struct ucred
*cred
struct vnode
*vp
struct label
*label
struct timespec
atime
struct timespec
mtime
&mac.thead;
cred
Subject credential
vp
Object; vp
label
Policy label for
vp
atime
Access time; see &man.utimes.2;
mtime
Modification time; see &man.utimes.2;
Determine whether the subject credential can set the
passed access timestamps on the passed vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_proc_sched
int
&mac.mpo;_check_proc_sched
struct ucred
*ucred
struct proc
*proc
&mac.thead;
cred
Subject credential
proc
Object; process
Determine whether the subject credential can change the
scheduling parameters of the passed process. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
EPERM for lack of privilege, or
ESRCH to limit visibility.
See &man.setpriority.2; for more information.
&mac.mpo;_check_proc_signal
int
&mac.mpo;_check_proc_signal
struct ucred
*cred
struct proc
*proc
int signal
&mac.thead;
cred
Subject credential
proc
Object; process
signal
Signal; see &man.kill.2;
Determine whether the subject credential can deliver the
passed signal to the passed process. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
EPERM for lack of privilege, or
ESRCH to limit visibility.
&mac.mpo;_check_vnode_stat
int
&mac.mpo;_check_vnode_stat
struct ucred
*cred
struct vnode
*vp
struct label
*label
&mac.thead;
cred
Subject credential
vp
Object; vnode
label
Policy label for
vp
Determine whether the subject credential can
stat the passed vnode. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatch,
or EPERM for lack of
privilege.
See &man.stat.2; for more information.
&mac.mpo;_check_ifnet_transmit
int
&mac.mpo;_check_ifnet_transmit
struct ucred
*cred
struct ifnet
*ifnet
struct label
*ifnetlabel
struct mbuf
*mbuf
struct label
*mbuflabel
&mac.thead;
cred
Subject credential
ifnet
Network interface
ifnetlabel
Policy label for
ifnet
mbuf
Object; mbuf to be sent
mbuflabel
Policy label for
mbuf
Determine whether the network interface can transmit the
passed mbuf. Return 0 for
success, or an errno value for failure.
Suggested failure: EACCES for label
mismatch, or EPERM for lack of
privilege.
&mac.mpo;_check_socket_receive
int
&mac.mpo;_check_socket_receive
struct ucred
*cred
struct ifnet
*ifnet
struct label
*ifnetlabel
struct mbuf
*mbuf
struct label
*mbuflabel
&mac.thead;
cred
Subject credential
ifnet
Network interface
ifnetlabel
Policy label for
ifnet
mbuf
Object; mbuf to be received
mbuflabel
Policy label for
mbuf
Determine whether the socket may receive the datagram
stored in the passed mbuf header. Return
0 for success, or an
errno value for failure. Suggested
failures: EACCES for label mismatch,
or EPERM for lack of
privilege.
&mac.mpo;_check_socket_visible
int
&mac.mpo;_check_socket_visible
struct ucred
*cred
struct socket
*so
struct label
*socketlabel
&mac.thead;
cred
Subject credential
Immutable
so
Object; socket
socketlabel
Policy label for
so
Determine whether the subject credential cred can "see"
the passed socket (socket) using
system monitoring functions, such as those employed by
&man.netstat.8; and &man.sockstat.1;. Return
0 for success, or an
errno value for failure. Suggested
failure: EACCES for label mismatches,
EPERM for lack of privilege, or
ESRCH to hide visibility.
Label Management Calls
Relabel events occur when a user process has requested
that the label on an object be modified. A two-phase update
occurs: first, an access control check will be performed to
determine if the update is both valid and permitted, and then
the update itself is performed via a seperate entry point.
Relabel entry points typically accept the object, object label
reference, and an update label submitted by the process.
Memory allocation during relabel is discouraged, as relabel
calls are not permitted to fail (failure should be reported
earlier in the relabel check).
&mac.mpo;_init_bpfdesc
void
&mac.mpo;_init_bpfdesc
struct bpf_d
*bpf_d
struct label
*label
&mac.thead;
bpf_d
Object; bpf descriptor
label
New label to apply
Initialize the label on a newly instantiated bpfdesc (BPF
descriptor)
&mac.mpo;_init_devfsdirent
void
&mac.mpo;_init_devfsdirent
struct devfs_dirent
*devfs_dirent
struct label
*label
&mac.thead;
devfs_dirent
Object; devfs directory entry
label
New label to apply
Initialize the label on a newly instantiated devfs
entry.
&mac.mpo;_init_ifnet
void
&mac.mpo;_init_ifnet
struct ifnet
*ifnet
struct label
*label
&mac.thead;
ifnet
Object; network interface
label
New label to apply
Initialize the label on a newly instantiated network
interface.
&mac.mpo;_init_ipq
void
&mac.mpo;_init_ipq
struct ipq
*ipq
struct label
*label
&mac.thead;
ipq
Object; IP reassembly queue
label
New label to apply
Initialize the label on a newly instantiated IP fragment
reassembly queue.
&mac.mpo;_init_mbuf
void
&mac.mpo;_init_mbuf
struct mbuf
*mbuf
int how
struct label
*label
&mac.thead;
mbuf
Object; mbuf
how
Blocking/non-blocking &man.malloc.9; see
below
label
Policy label to initialize
Initialize the label on a newly instantiated mbuf packet
header (mbuf). The
how field may be one of
M_WAITOK and M_NOWAIT, and
should be employed to avoid performing a blocking
&man.malloc.9; during this initialization call. Mbuf
allocation frequently occurs in performance sensitive
environments, and the implementation should be careful to
avoid blocking or long-lived operations. This entry point
is permitted to fail resulting in the failure to allocate
the mbuf header.
&mac.mpo;_init_mount
void
&mac.mpo;_init_mount
struct mount
*mount
struct label
*mntlabel
struct label
*fslabel
&mac.thead;
mount
Object; file system mount point
mntlabel
Policy label to be initialized for the mount
itself
fslabel
Policy label to be initialized for the file
system
Initialize the labels on a newly instantiated mount
point.
&mac.mpo;_init_socket
void
&mac.mpo;_init_socket
struct socket
*socket
struct label
*label
struct label
*peerlabel
&mac.thead;
socket
Object; socket
label
New label to apply to the socket
peerlabel
New label to apply to the socket's peer
Initialize the labels on a newly instantiated
socket.
&mac.mpo;_init_cred
void
&mac.mpo;_init_cred
struct ucred
*cred
struct label
*label
&mac.thead;
cred
Subject; user credetial
label
New label
Initialize the labels on a newly instantiated subject.
&mac.mpo;_init_temp
void
&mac.mpo;_init_temp
struct label
*label
&mac.thead;
label
Temporary label
Initialize a newly instantiated temporary label;
temporary labels are frequently used to hold label update
requests.
&mac.mpo;_init_vnode
void
&mac.mpo;_init_vnode
struct vnode
*vp
struct label
*label
&mac.thead;
vp
Object; file system object
label
New label to initialize
Initialize the label on a newly instantiated vnode.
&mac.mpo;_destroy_bpfdesc
void
&mac.mpo;_destroy_bpfdesc
struct bpf_d
*bpf_d
struct label
*label
&mac.thead;
bpf_d
Object; bpf descriptor
label
Label being destroyed
Destroy the label on a BPF descriptor. In this entry
point, a policy module should free any internal storage
associated with label so that it may
be destroyed.
&mac.mpo;_destroy_devfsdirent
void
&mac.mpo;_destroy_devfsdirent
struct devfs_dirent
*devfs_dirent
struct label
*label
&mac.thead;
devfs_dirent
Object; devfs directory entry
label
Label being destroyed
Destroy the label on a devfs entry. In this entry
point, a policy module should free any internal storage
asociated with label so that it may
be destroyed.
&mac.mpo;_destroy_ifnet
void
&mac.mpo;_destroy_ifnet
struct ifnet
*ifnet
struct label
*label
&mac.thead;
ifnet
Object; network interface
label
Label being destroyed
Destroy the label on a removed interface. In this entry
point, a policy module should free any internal storage
associated with label so that it may
be destroyed.
&mac.mpo;_destroy_ipq
void
&mac.mpo;_destroy_ipq
struct ipq
*ipq
struct label
*label
&mac.thead;
ipq
Object; IP reassembly queue
label
Label being destroyed
Destroy the label on an IP fragment queue. In this
entry point, a policy module should free any internal
storage associated with label so that
it may be destroyed.
&mac.mpo;_destroy_mbuf
void
&mac.mpo;_destroy_mbuf
struct mbuf
*mbuf
struct label
*label
&mac.thead;
mbuf
Object; mbuf
label
Label being destroyed
Destroy the label on an mbuf header. In this entry
point, a policy module should free any internal storage
associated with label so that it may
be destroyed.
&mac.mpo;_destroy_mount
void
&mac.mpo;_destroy_mount
struct mount
*mp
struct label
*mntlabel
struct label
*fslabel
&mac.thead;
mp
Object; file system mount point
mntlabel
Mount point label being destroyed
fslabel
File system label being destroyed>
Destroy the labels on a mount point. In this entry
point, a policy module should free the internal storage
associated with mntlabel and
fslabel so that they may be
destroyed.
&mac.mpo;_destroy_socket
void
&mac.mpo;_destroy_socket
struct socket
*socket
struct label
*label
struct label
*peerlabel
&mac.thead;
socket
Object; socket
label
Socket label being destroyed
peerlabel
Socket peer label being destroyed
Destroy the labels on a socket. In this entry point, a
policy module should free any internal storage associated
with label and
peerlabel so that they may be
destroyed.
&mac.mpo;_destroy_cred
void
&mac.mpo;_destroy_cred
struct ucred
*cred
struct label
*label
&mac.thead;
cred
Subject; user credential
label
Label being destroyed
Destroy the label on a credential. In this entry point,
a policy module should free any internal storage associated
with label so that it may be
destroyed.
&mac.mpo;_destroy_temp
void
&mac.mpo;_destroy_temp
struct label
*label
&mac.thead;
label
Temporary label being destroyed
Destroy a temporary label. In this entry point, a
policy module should free any internal storage associated
with the temporary label label so
that it may be destroyed.
&mac.mpo;_destroy_vnode
void
&mac.mpo;_destroy_vnode
struct vnode
*vp
struct label
*label
&mac.thead;
vp
Object; file system object
label
Label being destroyed
Destroy the label on a vnode. In this entry point, a
policy module should free any internal storage associated
with label so that it may be
destroyed.
&mac.mpo;_externalize
void
&mac.mpo;_externalize
struct label
*label
struct mac
*extmac
&mac.thead;
label
Label to be externalized
extmac
MAC structure to be filled in
Given an internalized subject or object label, fill out
an externalized label. This call is permitted to fail.
This call will be obsoleted by the new userland and extended
attribute interfaces for the MAC framework.
&mac.mpo;_internalize
void
&mac.mpo;_internalize
struct label
*label
struct mac
*extmac
&mac.thead;
label
Label to be filled in
extmac
MAC structure to internalize
Given an externalized subject or object label, likely
from userland, internalize the label. The entry point
implementation should handle incorrect or corrupted labels.
This call is permitted to fail. This call will be obsoleted
by the new userland and extended attribute interfaces for
the MAC framework.
Additional Framework API Calls
The MAC_SYSCALL entry point provides a
policy-multiplexed system call so that policies may provide
additional services to user processes without registering
specific system calls. The policy name provided during
registration is used to demux calls from userland, and the
arguments will be forwarded to this entry point. When
implementing new services, security modules should be sure to
invoke appropriate access control checks from the MAC
framework as needed. For example, if a policy implements an
augmented signal functionality, it should call the necessary
signal access control checks to invoke the MAC framework and
other registered policies.
Userland APIs
The userland API is still under development.
Sample Policy Modules
The mac_none policy provides sample
prototypes and registration of all available policy entry
points.
The mac_seeotheruids policy provides
a simple access control policy without the use of labeling,
relying only on information already present in the kernel
objects.
The mac_biba policy provides a sample
information flow based labeled access control policy,
assigning labels to all kernel objects.
System Integration
...
Conclusion
The TrustedBSD MAC framework permits kernel modules to
augment the system security policy in a highly integrated
manner. They may do this based on existing object properties,
or based on label data that is maintained with the assistance of
the MAC framework. The framework is sufficiently flexible to
implement a variety of policy types, including information flow
security policies such as MLS and Biba, as well as policies
based on existing BSD credentials or file protections. Policy
authors may wish to consult this documentation as well as
existing security modules when implementing a new security
service.