FreeBSD Developers' Handbook
Prev	Chapter 14 Writing MAC Policies	Next

14.5 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.

14.5.1 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.

14.5.1.1 `mpo_init`

void mpo_init(struct mac_policy_conf *conf);

Parameter	Description	Locking
`conf`	MAC policy definition

Policy load event. The policy list mutex is held, so caution should be applied.

14.5.1.2 `mpo_destroy`

void mpo_destroy(struct mac_policy_conf *conf);

Parameter	Description	Locking
`conf`	MAC policy definition

Policy load event. The policy list mutex is held, so caution should be applied.

14.5.2 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.

14.5.2.1 File System Object Labeling Event Operations

14.5.2.1.1 `mpo_create_devfs_device`

void mpo_create_devfs_device(dev_t dev, struct devfs_dirent *devfs_dirent, struct label *label);

Parameter	Description	Locking
`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.

14.5.2.1.2 `mpo_create_devfs_directory`

void mpo_create_devfs_directory(char *dirname, int dirnamelen, struct devfs_dirent *devfs_dirent, struct label *label);

Parameter	Description	Locking
`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.

14.5.2.1.3 `mpo_create_devfs_vnode`

void mpo_create_devfs_vnode(struct devfs_dirent *devfs_dirent, struct label *direntlabel, struct vnode *vp, struct label *vnodelabel);

Parameter	Description	Locking
`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.

14.5.2.1.4 `mpo_vnode_create_from_vnode`

void mpo_vnode_create_from_vnode(struct ucred *cred, struct vnode *parent, struct label *parentlabel, struct vnode *child, struct label *childlabel);

Parameter	Description	Locking
`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.

14.5.2.1.5 `mpo_create_mount`

void mpo_create_mount(struct ucred *cred, struct mount *mp, struct label *mnt, struct label *fslabel);

Parameter	Description	Locking
`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.

14.5.2.1.6 `mpo_create_root_mount`

void mpo_create_root_mount(struct ucred *cred, struct mount *mp, struct label *mntlabel, struct label *fslabel);

Parameter	Description	Locking
See Section 14.5.2.1.5.

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 mpo_create_mount;.

14.5.2.1.7 `mpo_vnode_relabel`

void mpo_vnode_relabel(struct ucred *cred, struct vnode *vp, struct label *vnodelabel, struct label *newlabel);

Parameter	Description	Locking
`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.

14.5.2.1.8 `mpo_stdcreatevnode_ea`

int mpo_stdcreatevnode_ea(struct vnode *vp, struct label *vnodelabel);

Parameter	Description	Locking
`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 extattr(9)). If committing to the disk is successful, a value of 0 should be returned; otherwise, an appropriate error code should be returned.

Note: 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.

14.5.2.1.9 `mpo_update_devfsdirent`

void mpo_update_devfsdirent(struct devfs_dirent *devfs_dirent, struct label *direntlabel, struct vnode *vp, struct label *vnodelabel);

Parameter	Description	Locking
`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.

14.5.2.1.10 `mpo_update_procfsvnode`

void mpo_update_procfsvnode(struct vnode *vp, struct label *vnodelabel, struct ucred *cred);

Parameter	Description	Locking
`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.

14.5.2.1.11 `mpo_update_vnode_from_extattr`

int mpo_update_vnode_from_extattr(struct vnode *vp, struct label *vnodelabel, struct mount *mp, struct label *fslabel);

Parameter	Description	Locking
`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.

14.5.2.1.12 `mpo_update_from_externalized`

int mpo_update_from_externalized(struct vnode *vp, struct label *vnodelabel, struct mac *extmac);

Parameter	Description	Locking
`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.

14.5.2.1.13 `mpo_update_vnode_from_mount`

void mpo_update_vnode_from_mount(struct vnode *vp, struct label *vnodelabel, struct mount *mp, struct label *mountlabel);

Parameter	Description	Locking
`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.

14.5.2.2 IPC Object Labeling Event Operations

14.5.2.2.1 `mpo_create_mbuf_from_socket`

void mpo_create_mbuf_from_socket(struct socket *so, struct label *socketlabel, struct mbuf *m, struct label *mbuflabel);

Parameter	Description	Locking
`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.

14.5.2.2.2 `mpo_create_socket`

void mpo_create_socket(struct ucred *cred, struct socket *so, struct label *socketlabel);

Parameter	Description	Locking
`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.

14.5.2.2.3 `mpo_create_socket_from_socket`

void mpo_create_socket_from_socket(struct socket *oldsocket, struct label *oldsocketlabel, struct socket *newsocket, struct label *newsocketlabel);

Parameter	Description	Locking
`oldsocket`	Object; parent socket; created from 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 accept(2), or prior to accept(2), depending on the protocol.

14.5.2.2.4 `mpo_socket_relabel`

void mpo_socket_relabel(struct ucred *cred, struct socket *so, struct label *oldlabel, struct label *newlabel);

Parameter	Description	Locking
`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.

14.5.2.2.5 `mpo_set_socket_peer_from_mbuf`

void mpo_set_socket_peer_from_mbuf(struct mbuf *mbuf, struct label *mbuflabel, struct label *oldlabel, struct label *newlabel);

Parameter	Description	Locking
`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.

14.5.2.2.6 `mpo_set_socket_peer_from_socket`

void mpo_set_socket_peer_from_socket(struct socket *oldsocket, struct label *oldsocketlabel, struct socket *newsocket, struct label *newsocketpeerlabel);

Parameter	Description	Locking
`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.

14.5.2.3 Network Object Labeling Event Operations

14.5.2.3.1 `mpo_create_bpfdesc`

void mpo_create_bpfdesc(struct ucred *cred, struct bpf_d *bpf_d, struct label *bpflabel);

Parameter	Description	Locking
`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.

14.5.2.3.2 `mpo_create_ifnet`

void mpo_create_ifnet(struct ifnet *ifnet, struct label *ifnetlabel);

Parameter	Description	Locking
`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.

14.5.2.3.3 `mpo_create_ipq`

void mpo_create_ipq(struct mbuf *fragment, struct label *fragmentlabel, struct ipq *ipq, struct label *ipqlabel);

Parameter	Description	Locking
`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.

14.5.2.3.4 `mpo_create_datagram_from_ipq`

void mpo_create_create_datagram_from_ipq(struct ipq *ipq, struct label *ipqlabel, struct mbuf *datagram, struct label *datagramlabel);

Parameter	Description	Locking
`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.

14.5.2.3.5 `mpo_create_fragment`

void mpo_create_fragment(struct mbuf *datagram, struct label *datagramlabel, struct mbuf *fragment, struct label *fragmentlabel);

Parameter	Description	Locking
`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.

14.5.2.3.6 `mpo_create_mbuf_from_mbuf`

void mpo_create_mbuf_from_mbuf(struct mbuf *oldmbuf, struct label *oldmbuflabel, struct mbuf *newmbuf, struct label *newmbuflabel);

Parameter	Description	Locking
`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.

14.5.2.3.7 `mpo_create_mbuf_linklayer`

void mpo_create_mbuf_linklayer(struct ifnet *ifnet, struct label *ifnetlabel, struct mbuf *mbuf, struct label *mbuflabel);

Parameter	Description	Locking
`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.

14.5.2.3.8 `mpo_create_mbuf_from_bpfdesc`

void mpo_create_mbuf_from_bpfdesc(struct bpf_d *bpf_d, struct label *bpflabel, struct mbuf *mbuf, struct label *mbuflabel);

Parameter	Description	Locking
`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.

14.5.2.3.9 `mpo_create_mbuf_from_ifnet`

void mpo_create_mbuf_from_ifnet(struct ifnet *ifnet, struct label *ifnetlabel, struct mbuf *mbuf, struct label *mbuflabel);

Parameter	Description	Locking
`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.

14.5.2.3.10 `mpo_create_mbuf_multicast_encap`

void mpo_create_mbuf_multicast_encap(struct mbuf *oldmbuf, struct label *oldmbuflabel, struct ifnet *ifnet, struct label *ifnetlabel, struct mbuf *newmbuf, struct label *newmbuflabel);

Parameter	Description	Locking
`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.

14.5.2.3.11 `mpo_create_mbuf_netlayer`

void mpo_create_mbuf_netlayer(struct mbuf *oldmbuf, struct label *oldmbuflabel, struct mbuf *newmbuf, struct label *newmbuflabel);

Parameter	Description	Locking
`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.

14.5.2.3.12 `mpo_fragment_match`

int mpo_fragment_match(struct mbuf *fragment, struct label *fragmentlabel, struct ipq *ipq, struct label *ipqlabel);

Parameter	Description	Locking
`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.

14.5.2.3.13 `mpo_ifnet_relabel`

void mpo_ifnet_relabel(struct ucred *cred, struct ifnet *ifnet, struct label *ifnetlabel, struct label *newlabel);

Parameter	Description	Locking
`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.

14.5.2.3.14 `mpo_update_ipq`

void mpo_update_ipq(struct mbuf *fragment, struct label *fragmentlabel, struct ipq *ipq, struct label *ipqlabel);

Parameter	Description	Locking
`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).

14.5.2.4 Process Labeling Event Operations

14.5.2.4.1 `mpo_create_cred`

void mpo_create_cred(struct ucred *parent_cred, struct ucred *child_cred);

Parameter	Description	Locking
`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.

14.5.2.4.2 `mpo_execve_transition`

void mpo_execve_transition(struct ucred *old, struct ucred *new, struct vnode *vp, struct label *vnodelabel);

Parameter	Description	Locking
`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.

14.5.2.4.3 `mpo_execve_will_transition`

int mpo_execve_will_transition(struct ucred *old, struct vnode *vp, struct label *vnodelabel);

Parameter	Description	Locking
`old`	Subject credential prior to 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.

14.5.2.4.4 `mpo_create_proc0`

void mpo_create_proc0(struct ucred *cred);

Parameter	Description	Locking
`cred`	Subject credential to be filled in

Create the subject credential of process 0, the parent of all kernel processes.

14.5.2.4.5 `mpo_create_proc1`

void mpo_create_proc1(struct ucred *cred);

Parameter	Description	Locking
`cred`	Subject credential to be filled in

Create the subject credential of process 1, the parent of all kernel processes.

14.5.2.4.6 `mpo_cred_relabel`

void mpo_cred_relabel(struct ucred *cred, struct label *newlabel);

Parameter	Description	Locking
`cred`	Subject credential
`newlabel`	Label update to apply to `cred`

Update the label on a subject credential from the passed update label.

14.5.3 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 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
	ENOENT
	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.

14.5.3.1 `mpo_check_bpfdesc_receive`

int mpo_check_bpfdesc_receive(struct bpf_d *bpf_d, struct label *bpflabel, struct ifnet *ifnet, struct label *ifnetlabel);

Parameter	Description	Locking
`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.

14.5.3.2 `mpo_check_socket_bind`

int mpo_check_socket_bind(struct ucred *cred, struct socket *socket, struct label *socketlabel, struct sockaddr *sockaddr);

Parameter	Description	Locking
`cred`	Subject credential
`socket`	Socket to be bound
`socketlabel`	Policy label for `socket`
`sockaddr`	Address of `socket`

14.5.3.3 `mpo_check_socket_connect`

int mpo_check_socket_connect(struct ucred *cred, struct socket *socket, struct label *socketlabel, struct sockaddr *sockaddr);

Parameter	Description	Locking
`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.

14.5.3.4 `mpo_check_cred_visible`

int mpo_check_cred_visible(struct ucred *u1, struct ucred *u2);

Parameter	Description	Locking
`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.

14.5.3.5 `mpo_check_socket_visible`

int mpo_check_socket_visible(struct ucred *cred, struct socket *socket, struct label *socketlabel);

Parameter	Description	Locking
`cred`	Subject credential
`socket`	Object; socket
`socketlabel`	Policy label for `socket`

14.5.3.6 `mpo_check_ifnet_relabel`

int mpo_check_ifnet_relabel(struct ucred *cred, struct ifnet *ifnet, struct label *ifnetlabel, struct label *newlabel);

Parameter	Description	Locking
`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.

14.5.3.7 `mpo_check_socket_relabel`

int mpo_check_socket_relabel(struct ucred *cred, struct socket *socket, struct label *socketlabel, struct label *newlabel);

Parameter	Description	Locking
`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.

14.5.3.8 `mpo_check_cred_relabel`

int mpo_check_cred_relabel(struct ucred *cred, struct label *newlabel);

Parameter	Description	Locking
`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.

14.5.3.9 `mpo_check_vnode_relabel`

int mpo_check_vnode_relabel(struct ucred *cred, struct vnode *vp, struct label *vnodelabel, struct label *newlabel);

Parameter	Description	Locking
`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.

14.5.3.10 `mpo_check_mount_stat`

int mpo_check_mount_stat(struct ucred *cred, struct mount *mp, struct label *mountlabel);

Parameter	Description	Locking
`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 statfs(2) and related calls, as well as to determine what file systems to exclude from listings of file systems, such as when getfsstat(2) is invoked.

14.5.3.11 `mpo_check_proc_debug`

int mpo_check_proc_debug(struct ucred *cred, struct proc *proc);

Parameter	Description	Locking
`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 ptrace(2) and ktrace(2) APIs, as well as for some types of procfs operations.

14.5.3.12 `mpo_check_vnode_access`

int mpo_check_vnode_access(struct ucred *cred, struct vnode *vp, struct label *label, int flags);

Parameter	Description	Locking
`cred`	Subject credential
`vp`	Object; vnode
`label`	Policy label for `vp`
`flags`	access(2) flags

Determine how invocations of 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 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.

14.5.3.13 `mpo_check_vnode_chdir`

int mpo_check_vnode_chdir(struct ucred *cred, struct vnode *dvp, struct label *dlabel);

Parameter	Description	Locking
`cred`	Subject credential
`dvp`	Object; vnode to 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.

14.5.3.14 `mpo_check_vnode_create`

int mpo_check_vnode_create(struct ucred *cred, struct vnode *dvp, struct label *dlabel, struct componentname *cnp, struct vattr *vap);

Parameter	Description	Locking
`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 open(2) with O_CREAT, mknod(2), mkfifo(2), and others.

14.5.3.15 `mpo_check_vnode_delete`

int mpo_check_vnode_delete(struct ucred *cred, struct vnode *dvp, struct label *dlabel, struct vnode *vp, void *label, struct componentname *cnp);

Parameter	Description	Locking
`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 unlink(2) and 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.

14.5.3.16 `mpo_check_vnode_deleteacl`

int mpo_check_vnode_deleteacl(struct ucred *cred, struct vnode *vp, struct label *label, acl_type_t type);

Parameter	Description	Locking
`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.

14.5.3.17 `mpo_check_vnode_exec`

int mpo_check_vnode_exec(struct ucred *cred, struct vnode *vp, struct label *label);

Parameter	Description	Locking
`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.

14.5.3.18 `mpo_check_vnode_getacl`

int mpo_check_vnode_getacl(struct ucred *cred, struct vnode *vp, struct label *label, acl_type_t type);

Parameter	Description	Locking
`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.

14.5.3.19 `mpo_check_vnode_getextattr`

int mpo_check_vnode_getextattr(struct ucred *cred, struct vnode *vp, struct label *label, int attrnamespace, const char *name, struct uio *uio);

Parameter	Description	Locking
`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 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.

14.5.3.20 `mpo_check_socket_listen`

int mpo_check_socket_listen(struct ucred *cred, struct socket *socket, struct label *socketlabel);

Parameter	Description	Locking
`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.

14.5.3.21 `mpo_check_vnode_lookup`

int mpo_check_vnode_lookup(struct ucred *cred, struct vnode *dvp, struct label *dlabel, struct componentname *cnp);

Parameter	Description	Locking
`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.

14.5.3.22 `mpo_check_vnode_open`

int mpo_check_vnode_open(struct ucred *cred, struct vnode *vp, struct label *label, mode_t acc_mode);

Parameter	Description	Locking
`cred`	Subject credential
`vp`	Object; vnode
`label`	Policy label for `vp`
`acc_mode`	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.

14.5.3.23 `mpo_check_vnode_readdir`

int mpo_check_vnode_readdir(struct ucred *cred, struct vnode *dvp, struct label *dlabel);

Parameter	Description	Locking
`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.

14.5.3.24 `mpo_check_vnode_readlink`

int mpo_check_vnode_readlink(struct ucred *cred, struct vnode *vp, struct label *label);

Parameter	Description	Locking
`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.

14.5.3.25 `mpo_check_rename_from_vnode`

int mpo_check_rename_from_vnode(struct ucred *cred, struct vnode *dvp, struct label *dlabel, struct vnode *vp, struct label *label, struct componentname *cnp);

Parameter	Description	Locking
`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.

14.5.3.26 `mpo_check_rename_to_vnode`

int 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);

Parameter	Description	Locking
`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.

14.5.3.27 `mpo_check_vnode_revoke`

int mpo_check_vnode_revoke(struct ucred *cred, struct vnode *vp, struct label *label);

Parameter	Description	Locking
`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.

14.5.3.28 `mpo_check_vnode_setacl`

int mpo_check_vnode_setacl(struct ucred *cred, struct vnode *vp, struct label *label, acl_type_t type, struct acl *acl);

Parameter	Description	Locking
`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.

14.5.3.29 `mpo_check_vnode_setextattr`

int mpo_check_vnode_setextattr(struct ucred *cred, struct vnode *vp, struct label *label, int attrnamespace, const char *name, struct uio *uio);

Parameter	Description	Locking
`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 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.

14.5.3.30 `mpo_check_vnode_setflags`

int mpo_check_vnode_setflags(struct ucred *cred, struct vnode *vp, struct label *label, u_long flags);

Parameter	Description	Locking
`cred`	Subject credential
`vp`	Object; vnode
`label`	Policy label for `vp`
`flags`	File flags; see 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.

14.5.3.31 `mpo_check_vnode_setmode`

int mpo_check_vnode_setmode(struct ucred *cred, struct vnode *vp, struct label *label, mode_t mode);

Parameter	Description	Locking
`cred`	Subject credential
`vp`	Object; vnode
`label`	Policy label for `vp`
`mode`	File mode; see 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.

14.5.3.32 `mpo_check_vnode_setowner`

int mpo_check_vnode_setowner(struct ucred *cred, struct vnode *vp, struct label *label, uid_t uid, gid_t gid);

Parameter	Description	Locking
`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.

14.5.3.33 `mpo_check_vnode_setutimes`

int mpo_check_vnode_setutimes(struct ucred *cred, struct vnode *vp, struct label *label, struct timespec atime, struct timespec mtime);

Parameter	Description	Locking
`cred`	Subject credential
`vp`	Object; vp
`label`	Policy label for `vp`
`atime`	Access time; see utimes(2)
`mtime`	Modification time; see 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.

14.5.3.34 `mpo_check_proc_sched`

int mpo_check_proc_sched(struct ucred *ucred, struct proc *proc);

Parameter	Description	Locking
`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 setpriority(2) for more information.

14.5.3.35 `mpo_check_proc_signal`

int mpo_check_proc_signal(struct ucred *cred, struct proc *proc, int signal);

Parameter	Description	Locking
`cred`	Subject credential
`proc`	Object; process
`signal`	Signal; see 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.

14.5.3.36 `mpo_check_vnode_stat`

int mpo_check_vnode_stat(struct ucred *cred, struct vnode *vp, struct label *label);

Parameter	Description	Locking
`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 stat(2) for more information.

14.5.3.37 `mpo_check_ifnet_transmit`

int mpo_check_ifnet_transmit(struct ucred *cred, struct ifnet *ifnet, struct label *ifnetlabel, struct mbuf *mbuf, struct label *mbuflabel);

Parameter	Description	Locking
`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.

14.5.3.38 `mpo_check_socket_receive`

int mpo_check_socket_receive(struct ucred *cred, struct ifnet *ifnet, struct label *ifnetlabel, struct mbuf *mbuf, struct label *mbuflabel);

Parameter	Description	Locking
`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.

14.5.3.39 `mpo_check_socket_visible`

int mpo_check_socket_visible(struct ucred *cred, struct socket *so, struct label *socketlabel);

Parameter	Description	Locking
`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 netstat(8) and 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.

14.5.4 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).

14.5.4.1 `mpo_init_bpfdesc`

void mpo_init_bpfdesc(struct bpf_d *bpf_d, struct label *label);

Parameter	Description	Locking
`bpf_d`	Object; bpf descriptor
`label`	New label to apply

Initialize the label on a newly instantiated bpfdesc (BPF descriptor)

14.5.4.2 `mpo_init_devfsdirent`

void mpo_init_devfsdirent(struct devfs_dirent *devfs_dirent, struct label *label);

Parameter	Description	Locking
`devfs_dirent`	Object; devfs directory entry
`label`	New label to apply

Initialize the label on a newly instantiated devfs entry.

14.5.4.3 `mpo_init_ifnet`

void mpo_init_ifnet(struct ifnet *ifnet, struct label *label);

Parameter	Description	Locking
`ifnet`	Object; network interface
`label`	New label to apply

Initialize the label on a newly instantiated network interface.

14.5.4.4 `mpo_init_ipq`

void mpo_init_ipq(struct ipq *ipq, struct label *label);

Parameter	Description	Locking
`ipq`	Object; IP reassembly queue
`label`	New label to apply

Initialize the label on a newly instantiated IP fragment reassembly queue.

14.5.4.5 `mpo_init_mbuf`

void mpo_init_mbuf(struct mbuf *mbuf, int how, struct label *label);

Parameter	Description	Locking
`mbuf`	Object; mbuf
`how`	Blocking/non-blocking 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 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.

14.5.4.6 `mpo_init_mount`

void mpo_init_mount(struct mount *mount, struct label *mntlabel, struct label *fslabel);

Parameter	Description	Locking
`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.

14.5.4.7 `mpo_init_socket`

void mpo_init_socket(struct socket *socket, struct label *label, struct label *peerlabel);

Parameter	Description	Locking
`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.

14.5.4.8 `mpo_init_cred`

void mpo_init_cred(struct ucred *cred, struct label *label);

Parameter	Description	Locking
`cred`	Subject; user credetial
`label`	New label

Initialize the labels on a newly instantiated subject.

14.5.4.9 `mpo_init_temp`

void mpo_init_temp(struct label *label);

Parameter	Description	Locking
`label`	Temporary label

Initialize a newly instantiated temporary label; temporary labels are frequently used to hold label update requests.

14.5.4.10 `mpo_init_vnode`

void mpo_init_vnode(struct vnode *vp, struct label *label);

Parameter	Description	Locking
`vp`	Object; file system object
`label`	New label to initialize

Initialize the label on a newly instantiated vnode.

14.5.4.11 `mpo_destroy_bpfdesc`

void mpo_destroy_bpfdesc(struct bpf_d *bpf_d, struct label *label);

Parameter	Description	Locking
`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.

14.5.4.12 `mpo_destroy_devfsdirent`

void mpo_destroy_devfsdirent(struct devfs_dirent *devfs_dirent, struct label *label);

Parameter	Description	Locking
`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.

14.5.4.13 `mpo_destroy_ifnet`

void mpo_destroy_ifnet(struct ifnet *ifnet, struct label *label);

Parameter	Description	Locking
`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.

14.5.4.14 `mpo_destroy_ipq`

void mpo_destroy_ipq(struct ipq *ipq, struct label *label);

Parameter	Description	Locking
`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.

14.5.4.15 `mpo_destroy_mbuf`

void mpo_destroy_mbuf(struct mbuf *mbuf, struct label *label);

Parameter	Description	Locking
`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.

14.5.4.16 `mpo_destroy_mount`

void mpo_destroy_mount(struct mount *mp, struct label *mntlabel, struct label *fslabel);

Parameter	Description	Locking
`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.

14.5.4.17 `mpo_destroy_socket`

void mpo_destroy_socket(struct socket *socket, struct label *label, struct label *peerlabel);

Parameter	Description	Locking
`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.

14.5.4.18 `mpo_destroy_cred`

void mpo_destroy_cred(struct ucred *cred, struct label *label);

Parameter	Description	Locking
`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.

14.5.4.19 `mpo_destroy_temp`

void mpo_destroy_temp(struct label *label);

Parameter	Description	Locking
`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.

14.5.4.20 `mpo_destroy_vnode`

void mpo_destroy_vnode(struct vnode *vp, struct label *label);

Parameter	Description	Locking
`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.

14.5.4.21 `mpo_externalize`

void mpo_externalize(struct label *label, struct mac *extmac);

Parameter	Description	Locking
`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.

14.5.4.22 `mpo_internalize`

void mpo_internalize(struct label *label, struct mac *extmac);

Parameter	Description	Locking
`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.

14.5.5 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.