diff --git a/en_US.ISO8859-1/books/arch-handbook/mac.ent b/en_US.ISO8859-1/books/arch-handbook/mac.ent index 381b994b23..6ead9b19ca 100644 --- a/en_US.ISO8859-1/books/arch-handbook/mac.ent +++ b/en_US.ISO8859-1/books/arch-handbook/mac.ent @@ -1,18 +1,122 @@ - + Parameter Description Locking '> + +struct label *label + char *element_name + char *element_data + size_t size + size_t *len + int *claimed +'> + + + + label + Label to be externalized + + + + element_name + Name of the policy whose label should be externalized + + + + element_data + Buffer; to be filled in with text representation of label + + + + size + Size of element_data + + + + len + To be filled in with the length of the string representing the + label data. + + + + claimed + Should be incremented when element_data + can be filled in. + + +'> + +Produce an externalized label based on the label structure passed. + An externalized label consists of a text representation of the label + contents that can be used with userland applications and read by the + user. Currently, all policies' externalize entry + points will be called, so the implementation should check the contents + of element_name before attempting to fill in + element_data. If + element_name does not match the name of your + policy, simply return 0. Only return nonzero + if an error occurs while externalizing the label data. Once the policy + fills in element_data, *claimed + should be incremented. +"> + +struct label *label + char *element_name + char *element_data + int *claimed +'> + + + + label + Label to be filled in + + + + element_name + Name of the policy whose label should be internalized + + + + element_data + Text data to be internalized + + + + claimed + Should be incremented when data can be successfully + internalized. + + +'> + +Produce an internal label structure based on externalized label data + in text format. Currently, all policies' internalize + entry points are called when internalization is requested, so the + implementation should compare the contents of + element_name to its own name in order to be sure + it should be internalizing the data in element_data. + Just as in the externalize entry points, the entry + point should return 0 if + element_name does not match its own name, or when + data can successfully be internalized, in which case + *claimed should be incremented. +"> 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 d6117ad667..caee9e28a4 100644 --- a/en_US.ISO8859-1/books/arch-handbook/mac/chapter.sgml +++ b/en_US.ISO8859-1/books/arch-handbook/mac/chapter.sgml @@ -1,5730 +1,7483 @@ Chris Costello TrustedBSD Project
chris@FreeBSD.org
 Robert Watson TrustedBSD Project
rwatson@FreeBSD.org
 The TrustedBSD MAC Framework + + + MAC Documentation Copyright + + This documentation was developed for the FreeBSD Project by + Chris Costello at Safeport Network Services and Network + Associates Laboratories, the Security Research Division of + Network Associates, Inc. under DARPA/SPAWAR contract + N66001-01-C-8035 (CBOSS), as part of the DARPA + CHATS research program. + + Redistribution and use in source (SGML DocBook) and + 'compiled' forms (SGML, HTML, PDF, PostScript, RTF and so forth) + with or without modification, are permitted provided that the + following conditions are met: + + + + Redistributions of source code (SGML DocBook) must + retain the above copyright notice, this list of conditions + and the following disclaimer as the first lines of this file + unmodified. + + + + Redistributions in compiled form (transformed to other + DTDs, converted to PDF, PostScript, RTF and other formats) + must reproduce the above copyright notice, this list of + conditions and the following disclaimer in the documentation + and/or other materials provided with the + distribution. + + + + + THIS DOCUMENTATION IS PROVIDED BY THE NETWORKS ASSOCIATES + TECHNOLOGY, INC "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NETWORKS ASSOCIATES TECHNOLOGY, + INC BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS + OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER + CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN + IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + Synopsis - Mandatory Access Control (MAC) is a security feature frequently - found in commercial trusted operating systems. MAC supplements - existing Discretionary Access Control (DAC) protections (such as - file system permissions and access control lists) by allowing the - security administrator to define mandatory protections for - system objects. Mandatory protections may be distinguished from - discretionary protections in that DAC is applied at the discretion - of the object owner, whereas MAC protections are defined by the - administrator and applied to all users and objects in the system - and may not be bypassed even by object owners. A variety of - MAC policies have been explored in security research literature - as well as the commercial trusted operating system space. These - include policies such as the Multi-Level Security (MLS) - confidentiality policy, used to prevent inappropriate sharing of - information on multi-user systems, and the Biba integrity policy, - typically used to protect the integrity of system and user - services. - - The implementation of MAC found in FreeBSD was developed by - the TrustedBSD Project, and includes support for both a number of - specific MAC policies, and for a flexible and extensible security - framework to support the easy creation of new kernel security - policies. This framework isolates the internals of specific MAC - policies from the implementation of kernel services, and - encapsulates the policies in policy modules. Policy modules may - be added to the system without changes to the base kernel, and can - augment the kernel security policy in a variety of ways. In - addition, policies may provide a shared object implementation - of common MAC interfaces for userland applications, permitting - applications to be easily extended to manage labels for new - policies. Support is provided for setting labels on user - processes at login, as well as in a number of other locations where - user context management occurs. - - This chapter introduces the MAC policy userland and kernel - policy frameworks and provides documentation for a sample MAC - policy module. + MAC, or Mandatory Access Control, is a feature introduced by + the TrustedBSD Project to supplement the existing standard DAC + (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 + + General-Purpose Module Entry Points 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 }, + allocation of label state by the framework. + + static struct mac_policy_ops mac_policy_ops = +{ + .mpo_destroy = mac_policy_destroy, + .mpo_init = mac_policy_init, + .mpo_init_bpfdesc_label = mac_policy_init_bpfdesc_label, + .mpo_init_cred_label = mac_policy_init_label, /* ... */ - { 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 } + .mpo_check_vnode_setutimes = mac_policy_check_vnode_setutimes, + .mpo_check_vnode_stat = mac_policy_check_vnode_stat, + .mpo_check_vnode_write = mac_policy_check_vnode_write, }; The MAC policy entry point vector, - mac_none_ops in this example, associates + mac_policy_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 + the .mpo_destroy and .mpo_init + entry points. .mpo_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 + locks. .mpo_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. <function>&mac.mpo;_init</function 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. <function>&mac.mpo;_destroy</function> 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. + + + <function>&mac.mpo;_syscall</function> + + + + int + &mac.mpo;_syscall + + struct thread + *td + int call + void *arg + + + + + + &mac.thead; + + + + td + Calling thread + + + + call + Syscall number + + + + arg + Pointer to syscall arguments + + + + + + This 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. + + Modules must currently perform the + copyin() of the syscall data on their + own. + - - File System Object Labeling Event Operations + + <function>&mac.mpo;_thread_userret</function> + + + + void + &mac.mpo;_thread_userret + + struct thread + *td + + + + + + &mac.thead; + + + + td + Returning thread + + + + + + + This entry point permits policy modules to perform + MAC-related events when a thread returns to user space. + This is required for policies that have floating process + labels, as it's not always possible to acquire the process + lock at arbitrary points in the stack during system call + processing; process labels might represent traditional + authentication data, process history information, or other + data. + + + + + Label Operations + + + <function>&mac.mpo;_init_bpfdesc_label</function> - - <function>&mac.mpo;_create_devfs_device</function> - - - - 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. - + + + void + &mac.mpo;_init_bpfdesc_label + + struct bpf_d + *bpf_d + struct label + *label + + - - <function>&mac.mpo;_create_devfs_directory</function> - - - - void - &mac.mpo;_create_devfs_directory - - char *dirname - int dirnamelen - struct devfs_dirent - *devfs_dirent - struct label - *label - - - - - - &mac.thead; + + + &mac.thead; + + + + bpf_d + Object; bpf descriptor + - - - 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. - + + label + New label to apply + + + + - - <function>&mac.mpo;_create_devfs_vnode</function> - + Initialize the label on a newly instantiated bpfdesc (BPF + descriptor) + + + + <function>&mac.mpo;_init_cred_label</function> + + + + void + &mac.mpo;_init_cred_label + + struct label + *label + + + + + + &mac.thead; + + + + label + New label to initialize + + + + + + Initialize the label for a newly instantiated + user credential. + + + + <function>&mac.mpo;_init_devfsdirent_label</function> + + + + void + &mac.mpo;_init_devfsdirent_label + + 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. + + + + <function>&mac.mpo;_init_ifnet_label</function> + + + + void + &mac.mpo;_init_ifnet_label + + 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. + + + + <function>&mac.mpo;_init_ipq_label</function> + + + + void + &mac.mpo;_init_ipq_label + + 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. + + + + <function>&mac.mpo;_init_mbuf_label</function> + + + + void + &mac.mpo;_init_mbuf_label + + 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. + + + + <function>&mac.mpo;_init_mount_label</function> + + + + void + &mac.mpo;_init_mount_label + + 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. + + + + <function>&mac.mpo;_init_mount_fs_label</function> + + + + void + &mac.mpo;_init_mount_fs_label + + struct label + *label + + + + + + &mac.thead; + + + + label + Label to be initialized + + + + + + Initialize the label on a newly mounted file + system. + + + + <function>&mac.mpo;_init_pipe_label</function> + + + + void + &mac.mpo;_init_pipe_label + + struct + label*label + + + + + + &mac.thead; + + + + label + Label to be filled in + + + + + Initialize a label for a newly instantiated pipe. + + + + <function>&mac.mpo;_init_socket_label</function> + + + + void + &mac.mpo;_init_socket_label + + struct label + *label + int flag + + + + + + &mac.thead; + + + + label + New label to initialize + + + + flag + &man.malloc.9; flags + + + + + + Initialize a label for a newly instantiated + socket. + + + + <function>&mac.mpo;_init_socket_peer_label</function> + + + + void + &mac.mpo;_init_socket_peer_label + + struct label + *label + int flag + + + + + + &mac.thead; + + + + label + New label to initialize + + + + flag + &man.malloc.9; flags + + + + + + Initialize the peer label for a newly instantiated + socket. + + + + <function>&mac.mpo;_init_proc_label</function> + + + + void + &mac.mpo;_init_proc_label + + struct label + *label + + + + + + &mac.thead; + + + + label + New label to initialize + + + + + + Initialize the label for a newly instantiated + process. + + + + + <function>&mac.mpo;_init_vnode_label</function> + + + + void + &mac.mpo;_init_vnode_label + + 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. + + + <function>&mac.mpo;_destroy_bpfdesc_label</function> + + + + void + &mac.mpo;_destroy_bpfdesc_label + + struct label + *label + + + + + + &mac.thead; + + + + label + bpfdesc label + + + + + + Destroy the label on a bpf descriptor. In this entry + point a policy should free any internal storage associated + with label so that it may be + destroyed. + + + + <function>&mac.mpo;_destroy_cred_label</function> + + + + void + &mac.mpo;_destroy_cred_label + + 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. + + + + + <function>&mac.mpo;_destroy_devfsdirent_label</function> + + + + void + &mac.mpo;_destroy_devfsdirent_label + + 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. + + + + <function>&mac.mpo;_destroy_ifnet_label</function> + + + + void + &mac.mpo;_destroy_ifnet_label + + struct label + *label + + + + + + &mac.thead; + + + + 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. + + + + <function>&mac.mpo;_destroy_ipq_label</function> + + + + void + &mac.mpo;_destroy_ipq_label + + struct label + *label + + + + + + &mac.thead; + + + + 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. + + + + <function>&mac.mpo;_destroy_mbuf_label</function> + + + + void + &mac.mpo;_destroy_mbuf_label + + struct label + *label + + + + + + &mac.thead; + + + + 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. + + + + <function>&mac.mpo;_destroy_mount_label</function> + + + + void + &mac.mpo;_destroy_mount_label + + struct label + *label + + + + + + &mac.thead; + + + + label + Mount point 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 so that they + may be destroyed. + + + + <function>&mac.mpo;_destroy_mount_label</function> + + + + void + &mac.mpo;_destroy_mount_label + + 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. + + + + <function>&mac.mpo;_destroy_socket_label</function> + + + + void + &mac.mpo;_destroy_socket_label + + struct label + *label + + + + + + + &mac.thead; + + + + label + Socket label being destroyed + + + + + + + Destroy the label on a socket. In this entry point, a + policy module should free any internal storage associated + with label so that it may be + destroyed. + + + + <function>&mac.mpo;_destroy_socket_peer_label</function> + + + + void + &mac.mpo;_destroy_socket_peer_label + + struct label + *peerlabel + + + + + + &mac.thead; + + + + peerlabel + Socket peer label being destroyed + + + + + + Destroy the peer label on a socket. In this entry + point, a policy module should free any internal storage + associated with label so that it may + be destroyed. + + + + <function>&mac.mpo;_destroy_pipe_label</function> + + + + void + &mac.mpo;_destroy_pipe_label + + struct label + *label + + + + + + &mac.thead; + + + + label + Pipe label + + + + + + Destroy the label on a pipe. In this entry point, a + policy module should free any internal storage associated + with label so that it may be + destroyed. + + + + <function>&mac.mpo;_destroy_proc_label</function> + + + + void + &mac.mpo;_destroy_proc_label + struct label + *label + + + + + + &mac.thead; + + + + label + Process label + + + + + + Destroy the label on a process. In this entry point, a + policy module should free any internal storage associated + with label so that it may be + destroyed. + + + + <function>&mac.mpo;_copy_pipe_label</function> + + + + void + &mac.mpo;_copy_pipe_label + + struct label + *src + struct label + *dest + + + + + + &mac.thead; + + + + src + Source label + + + + dest + Destination label + + + + + + Copy the label information in + src into + dest. + + + + <function>&mac.mpo;_copy_vnode_label</function> + + + + void + &mac.mpo;_copy_vnode_label + + struct label + *src + struct label + *dest + + + + + + &mac.thead; + + + + src + Source label + + + + dest + Destination label + + + + + + Copy the label information in + src into + dest. + + + + <function>&mac.mpo;_externalize_cred_label</function> + + + + int + &mac.mpo;_externalize_cred_label + + &mac.externalize.paramdefs; + + + + + + &mac.thead; + + &mac.externalize.tbody; + + + + &mac.externalize.para; + + + + <function>&mac.mpo;_externalize_ifnet_label</function> + + + + int + &mac.mpo;_externalize_ifnet_label + + &mac.externalize.paramdefs; + + + + + + &mac.thead; + + &mac.externalize.tbody; + + + + &mac.externalize.para; + + + + <function>&mac.mpo;_externalize_pipe_label</function> + + + + int + &mac.mpo;_externalize_pipe_label + + &mac.externalize.paramdefs; + + + + + + &mac.thead; + + &mac.externalize.tbody; + + + + &mac.externalize.para; + + + + <function>&mac.mpo;_externalize_socket_label</function> + + + + int + &mac.mpo;_externalize_socket_label + + &mac.externalize.paramdefs; + + + + + + &mac.thead; + + &mac.externalize.tbody; + + + + &mac.externalize.para; + + + + <function>&mac.mpo;_externalize_socket_peer_label</function> + + + + int + &mac.mpo;_externalize_socket_peer_label + + &mac.externalize.paramdefs; + + + + + + &mac.thead; + + &mac.externalize.tbody; + + + + &mac.externalize.para; + + + + <function>&mac.mpo;_externalize_vnode_label</function> + + + + int + &mac.mpo;_externalize_vnode_label + + &mac.externalize.paramdefs; + + + + + + &mac.thead; + + &mac.externalize.tbody; + + + + &mac.externalize.para; + + + + <function>&mac.mpo;_internalize_cred_label</function> + + + + int + &mac.mpo;_internalize_cred_label + + &mac.internalize.paramdefs; + + + + + + &mac.thead; + + &mac.internalize.tbody; + + + + &mac.internalize.para; + + + + <function>&mac.mpo;_internalize_ifnet_label</function> + + + + int + &mac.mpo;_internalize_ifnet_label + + &mac.internalize.paramdefs; + + + + + + &mac.thead; + + &mac.internalize.tbody; + + + + &mac.internalize.para; + + + + <function>&mac.mpo;_internalize_pipe_label</function> + + + + int + &mac.mpo;_internalize_pipe_label + + &mac.internalize.paramdefs; + + + + + + &mac.thead; + + &mac.internalize.tbody; + + + + &mac.internalize.para; + + + + <function>&mac.mpo;_internalize_socket_label</function> + + + + int + &mac.mpo;_internalize_socket_label + + &mac.internalize.paramdefs; + + + + + + &mac.thead; + + &mac.internalize.tbody; + + + + &mac.internalize.para; + + + + <function>&mac.mpo;_internalize_vnode_label</function> + + + + int + &mac.mpo;_internalize_vnode_label + + &mac.internalize.paramdefs; + + + + + + &mac.thead; + + &mac.internalize.tbody; + + + + &mac.internalize.para; + + + + + 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 + + + <function>&mac.mpo;_associate_vnode_devfs</function> + void - &mac.mpo;_create_devfs_vnode - + &mac.mpo;_associate_vnode_devfs + + struct mount + *mp + struct label + *fslabel struct devfs_dirent - *devfs_dirent + *de struct label - *direntlabel + *delabel struct vnode *vp struct label - *vnodelabel + *vlabel + + + + + + &mac.thead; + + + + mp + Devfs mount point + + + + fslabel + Devfs file system label + (mp->mnt_fslabel) + + + + de + Devfs directory entry + + + + delabel + Policy label associated with + de + + + + vp + vnode associated with + de + + + + vlabel + Policy label associated with + vp + + + + + + Fill in the label (vlabel) for + a newly created devfs vnode based on the devfs directory + entry passed in de and its + label. + + + + <function>&mac.mpo;_associate_vnode_extattr</function> + + + + int + &mac.mpo;_associate_vnode_extattr + + struct mount + *mp + struct label + *fslabel + struct vnode + *vp + struct label + *vlabel + + + + + + &mac.thead; + + + + mp + File system mount point + + + + fslabel + File system label + + + + vp + Vnode to label + + + + vlabel + Policy label associated with + vp + + + + + + Attempt to retrieve the label for + vp from the file system extended + attributes. Upon success, the value 0 + is returned. Should extended attribute retrieval not be + supported, an accepted fallback is to copy + fslabel into + vlabel. In the event of an error, + an appropriate value for errno should + be returned. + + + + <function>&mac.mpo;_associate_vnode_singlelabel</function> + + + + void + &mac.mpo;_associate_vnode_singlelabel + + struct mount + *mp + struct label + *fslabel + struct vnode + *vp + struct label + *vlabel + + + + + + &mac.thead; + + + + mp + File system mount point + + + + fslabel + File system label + + + + vp + Vnode to label + + + + vlabel + Policy label associated with + vp + + + + + + On non-multilabel file systems, this entry point is + called to set the policy label for + vp based on the file system label, + fslabel. + + + + + <function>&mac.mpo;_create_devfs_device</function> + + + + 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. + + + + <function>&mac.mpo;_create_devfs_directory</function> + + + + 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. + + + + <function>&mac.mpo;_create_devfs_symlink</function> + + + + void + &mac.mpo;_create_devfs_symlink + + struct ucred + *cred + struct mount + *mp + struct devfs_dirent + *dd + struct label + *ddlabel + struct devfs_dirent + *de + struct label + *delabel - + &mac.thead; - + - devfs_dirent - Object; devfs directory entry + cred + Subject credential - + - direntlabel - Policy label for - devfs_dirent + mp + Devfs mount point - + - vp - Object; file system object being labeled + dd + Link destination - + - vnodelabel - Policy label to be filled in for - vp + ddlabel + Label associated with + dd + + + + de + Symlink entry + + + + delabel + Label associated with + de - - 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. + + Fill in the label (delabel) for + a newly created &man.devfs.5; symbolic link entry. - - <function>&mac.mpo;_vnode_create_from_vnode</function> - + + <function>&mac.mpo;_create_vnode_extattr</function> + - void - &mac.mpo;_vnode_create_from_vnode - + int + &mac.mpo;_create_vnode_extattr + struct ucred *cred + struct mount + *mp + struct label + *fslabel struct vnode - *parent + *dvp struct label - *parentlabel + *dlabel struct vnode - *child + *vp struct label - *childlabel + *vlabel + struct componentname + *cnp - + &mac.thead; - + cred Subject credential - + - parent - Parent vnode; the directory in which - child is being - created + mount + File system mount point - + - parentlabel - Policy label for - parent + label + File system label - + - child - New vnode + dvp + Parent directory vnode - + + + dlabel + Label associated with + dvp + + + + vp + Newly created vnode + + + + vlabel + Policy label associated with + vp + + - childlabel - Label to be filled in for - child + cnp + Component name for + vp - - 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. + + Write out the label for vp to + the appropriate extended attribute. If the write + succeeds, fill in vlabel with the + label, and return 0. Otherwise, + return an appropriate error. - + <function>&mac.mpo;_create_mount</function> 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. <function>&mac.mpo;_create_root_mount</function> 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;. - - - <function>&mac.mpo;_vnode_relabel</function> + + + <function>&mac.mpo;_relabel_vnode</function> void - &mac.mpo;_vnode_relabel + &mac.mpo;_relabel_vnode 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. - - - <function>&mac.mpo;_stdcreatevnode_ea</function> - + + + <function>&mac.mpo;_setlabel_vnode_extattr</function> + 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. - - - - <function>&mac.mpo;_update_devfsdirent</function> - - - 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. - - - - <function>&mac.mpo;_update_procfsvnode</function> - - - - void - &mac.mpo;_update_procfsvnode - - struct vnode - *vp - struct label - *vnodelabel + &mac.mpo;_setlabel_vnode_extattr + 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. - - - - <function>&mac.mpo;_update_vnode_from_extattr</function> - - - - 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. - - - - <function>&mac.mpo;_update_from_externalized</function> - - - - int - &mac.mpo;_update_from_externalized - - struct vnode - *vp + *vlabel struct label - *vnodelabel - struct mac - *extmac + *intlabel - + &mac.thead; - + + + cred + Subject credential + + vp - Object; vnode - Locked + Vnode for which the label is being + written - + - vnodelabel - Policy label for + vlabel + Policy label associated with vp - + - extmac - Externalized MAC policy label + intlabel + Label to write out - - 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. + + Write out the policy from + intlabel to an extended + attribute. This is called from + vop_stdcreatevnode_ea. - - - <function>&mac.mpo;_update_vnode_from_mount</function> - + + + <function>&mac.mpo;_update_devfsdirent</function> void - &mac.mpo;_update_vnode_from_mount + &mac.mpo;_update_devfsdirent + struct devfs_dirent + *devfs_dirent + struct label + *direntlabel struct vnode *vp struct label *vnodelabel - struct mount - *mp - struct label - *mountlabel &mac.thead; - vp - Object; vnode - Locked + devfs_dirent + Object; devfs directory entry - vnodelabel + direntlabel Policy label for - vp + devfs_dirent to be + updated. - mp - Mount point where vp - resides + vp + Parent vnode + Locked - fslabel - Policy label for the file system where - vp resides. + vnodelabel + Policy label for + vp - 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. + 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. IPC Object Labeling Event Operations + <function>&mac.mpo;_create_mbuf_from_socket</function> 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 + or message is generated by the socket and stored in the passed mbuf. + + + <function>&mac.mpo;_create_pipe</function> + + + + void + &mac.mpo;_create_pipe + + struct ucred + *cred + struct pipe + *pipe + struct label + *pipelabel + + + + + + &mac.thead; + + + + cred + Subject credential + + + + pipe + Pipe + + + + pipelabel + Policy label associated with + pipe + + + + + + Set the label on a newly created pipe from the passed + subject credential. This call is made when a new pipe is + created. + <function>&mac.mpo;_create_socket</function> 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. - - + + <function>&mac.mpo;_create_socket_from_socket</function> - + 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; + Listening socket - + oldsocketlabel - Label for + Policy label associated with oldsocket - + newsocket - Object; child socket; incoming connection + New socket - + newsocketlabel - Label to be filled in for - newsocket + Policy label associated with + newsocketlabel - - 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. + + Label a socket, newsocket, + newly &man.accept.2;ed, based on the &man.listen.2; + socket, oldsocket. - - - <function>&mac.mpo;_socket_relabel</function> + + + <function>&mac.mpo;_relabel_pipe</function> + + + + void + &mac.mpo;_relabel_pipe + + struct ucred + *cred + struct pipe + *pipe + struct label + *oldlabel + struct label + *newlabel + + + + + + &mac.thead; + + + + cred + Subject credential + + + + pipe + Pipe + + + + oldlabel + Current policy label associated with + pipe + + + + newlabel + Policy label update to apply to + pipe + + + + + + Apply a new label, newlabel, to + pipe. + + + + <function>&mac.mpo;_relabel_socket</function> void - &mac.mpo;_socket_relabel + &mac.mpo;_relabel_socket 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. <function>&mac.mpo;_set_socket_peer_from_mbuf</function> 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. <function>&mac.mpo;_set_socket_peer_from_socket</function> 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 <function>&mac.mpo;_create_bpfdesc</function> 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. <function>&mac.mpo;_create_ifnet</function> 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. <function>&mac.mpo;_create_ipq</function> 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. <function>&mac.mpo;_create_datagram_from_ipq</function> 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. <function>&mac.mpo;_create_fragment</function> 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. <function>&mac.mpo;_create_mbuf_from_mbuf</function> 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. <function>&mac.mpo;_create_mbuf_linklayer</function> 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. <function>&mac.mpo;_create_mbuf_from_bpfdesc</function> 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. <function>&mac.mpo;_create_mbuf_from_ifnet</function> 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. <function>&mac.mpo;_create_mbuf_multicast_encap</function> 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. <function>&mac.mpo;_create_mbuf_netlayer</function> 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. <function>&mac.mpo;_fragment_match</function> 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. - <function>&mac.mpo;_ifnet_relabel</function> + <function>&mac.mpo;_relabel_ifnet</function> void - &mac.mpo;_ifnet_relabel + &mac.mpo;_relabel_ifnet 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. <function>&mac.mpo;_update_ipq</function> 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 <function>&mac.mpo;_create_cred</function> 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 + &man.crcopy.9; is invoked on a newly created struct ucred. This call should not be confused with a process forking or creation event. <function>&mac.mpo;_execve_transition</function> 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. <function>&mac.mpo;_execve_will_transition</function> 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. <function>&mac.mpo;_create_proc0</function> 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. <function>&mac.mpo;_create_proc1</function> 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. + of all user processes. - - <function>&mac.mpo;_cred_relabel</function> + + <function>&mac.mpo;_relabel_cred</function> void - &mac.mpo;_cred_relabel + &mac.mpo;_relabel_cred 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 + return 0 to permit the operation, or 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 - - - 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. <function>&mac.mpo;_check_bpfdesc_receive</function> int - &mac.mpo;_check_bpfdesc_receive - - struct bpf_d - *bpf_d - struct label - *bpflabel - struct ifnet - *ifnet - struct label - *ifnetlabel + &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. + + + + <function>&mac.mpo;_check_kenv_dump</function> + + + + int + &mac.mpo;_check_kenv_dump + + struct ucred + *cred + + + + + + &mac.thead; + + + + cred + Subject credential + + + + + + Determine whether the subject should be allowed to + retrieve the kernel environment (see &man.kenv.2;). + + + + <function>&mac.mpo;_check_kenv_get</function> + + + + int + &mac.mpo;_check_kenv_get + + struct ucred + *cred + char *name + + + + + + &mac.thead; + + + + cred + Subject credential + + + + name + Kernel environment variable name + + + + + + Determine whether the subject should be allowed to + retrieve the value of the specified kernel environment + variable. + + + + <function>&mac.mpo;_check_kenv_set</function> + + + + int + &mac.mpo;_check_kenv_set + + struct ucred + *cred + char *name - + &mac.thead; - + - bpf_d - Subject; BPF descriptor + cred + Subject credential - + - bpflabel - Policy label for - bpf_d + name + Kernel environment variable name - + + + + + Determine whether the subject should be allowed to set + the specified kernel environment variable. + + + + <function>&mac.mpo;_check_kenv_unset</function> + + + + int + &mac.mpo;_check_kenv_unset + + struct ucred + *cred + char *name + + + + + + &mac.thead; + + - ifnet - Object; network interface + cred + Subject credential - ifnetlabel - Policy label for - ifnet + name + Kernel environment variable name - - 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. + + Determine whether the subject should be allowed to unset + the specified kernel environment variable. - - - <function>&mac.mpo;_check_socket_bind</function> - + + + <function>&mac.mpo;_check_kld_load</function> + int - &mac.mpo;_check_socket_bind - + &mac.mpo;_check_kld_load + struct ucred *cred - struct socket - *socket + struct vnode + *vp struct label - *socketlabel - struct sockaddr - *sockaddr + *vlabel - + &mac.thead; - + cred Subject credential - + - socket - Socket to be bound + vp + Kernel module vnode - + - socketlabel - Policy label for - socket + vlabel + Label associated with + vp - + + + + + Determine whether the subject should be allowed to load + the specified module file. + + + + <function>&mac.mpo;_check_kld_stat</function> + + + + int + &mac.mpo;_check_kld_stat + + struct ucred + *cred + + + + + + &mac.thead; + + - sockaddr - Address of - socket + cred + Subject credential - + + Determine whether the subject should be allowed to + retrieve a list of loaded kernel module files and associated + statistics. - - - - <function>&mac.mpo;_check_socket_connect</function> - + + + <function>&mac.mpo;_check_kld_unload</function> + + + + int + &mac.mpo;_check_kld_unload + + struct ucred + *cred + + + + + + &mac.thead; + + + + cred + Subject credential + + + + + + Determine whether the subject should be allowed to + unload a kernel module. + + + + <function>&mac.mpo;_check_pipe_ioctl</function> + int - &mac.mpo;_check_socket_connect - + &mac.mpo;_check_pipe_ioctl + struct ucred *cred - struct socket - *socket + struct pipe + *pipe struct label - *socketlabel - struct sockaddr - *sockaddr + *pipelabel + unsigned long + cmd + void *data - + &mac.thead; - + cred Subject credential - + - socket - Socket to be connected + pipe + Pipe - + - socketlabel - Policy label for - socket + pipelabel + Policy label associated with + pipe - + - sockaddr - Address of - socket + cmd + &man.ioctl.2; command - + + + data + &man.ioctl.2; data + + - - 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. + + Determine whether the subject should be allowed to make + the specified &man.ioctl.2; call. - - - <function>&mac.mpo;_check_cred_visible</function> - + + + <function>&mac.mpo;_check_pipe_poll</function> + int - &mac.mpo;_check_cred_visible - - struct ucred - *u1 + &mac.mpo;_check_pipe_poll + struct ucred - *u2 + *cred + struct pipe + *pipe + struct label + *pipelabel - + &mac.thead; - + - u1 + cred Subject credential - + - u2 - Object credential + pipe + Pipe + + + + pipelabel + Policy label associated with + pipe - - 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. - - - - <function>&mac.mpo;_check_socket_visible</function> - + + Determine whether the subject should be allowed to poll + pipe. + + + + <function>&mac.mpo;_check_pipe_read</function> + int - &mac.mpo;_check_socket_visible - + &mac.mpo;_check_pipe_read + struct ucred *cred - struct socket - *socket + struct pipe + *pipe struct label - *socketlabel + *pipelabel - + &mac.thead; - + cred Subject credential - + - socket - Object; socket + pipe + Pipe - + - socketlabel - Policy label for - socket + pipelabel + Policy label associated with + pipe - + + Determine whether the subject should be allowed read + access to pipe. - - - <function>&mac.mpo;_check_ifnet_relabel</function> - + + + <function>&mac.mpo;_check_pipe_relabel</function> + int - &mac.mpo;_check_ifnet_relabel - + &mac.mpo;_check_pipe_relabel + struct ucred *cred - struct ifnet - *ifnet + struct pipe + *pipe struct label - *ifnetlabel + *pipelabel struct label *newlabel - + &mac.thead; - + cred Subject credential - + - ifnet - Object; network interface + pipe + Pipe - + - ifnetlabel - Existing policy label for - ifnet + pipelabel + Current policy label associated with + pipe - + newlabel - Policy label update to later be applied to - ifnet + Label update to + pipelabel - - Determine whether the subject credential can relabel the - passed network interface to the passed label update. + + Determine whether the subject should be allowed to + relabel pipe. - - - <function>&mac.mpo;_check_socket_relabel</function> - + + + <function>&mac.mpo;_check_pipe_stat</function> + int - &mac.mpo;_check_socket_relabel - + &mac.mpo;_check_pipe_stat + struct ucred *cred - struct socket - *socket - struct label - *socketlabel + struct pipe + *pipe struct label - *newlabel + *pipelabel - + &mac.thead; - + cred Subject credential - - - socket - Object; socket - - + - socketlabel - Existing policy label for - socket + pipe + Pipe - + - newlabel - Label update to later be applied to - socketlabel + pipelabel + Policy label associated with + pipe - - Determine whether the subject credential can relabel the - passed socket to the passed label update. + + Determine whether the subject should be allowed to + retrieve statistics related to + pipe. - - - <function>&mac.mpo;_check_cred_relabel</function> - + + + <function>&mac.mpo;_check_pipe_write</function> + int - &mac.mpo;_check_cred_relabel - + &mac.mpo;_check_pipe_write + struct ucred *cred + struct pipe + *pipe struct label - *newlabel + *pipelabel - + &mac.thead; - + cred Subject credential - + - newlabel - Label update to later be applied to - cred + pipe + Pipe + + + + pipelabel + Policy label associated with + pipe - - Determine whether the subject credential can relabel - itself to the passed label update. + + Determine whether the subject should be allowed to write + to pipe. - - - <function>&mac.mpo;_check_vnode_relabel</function> + + + <function>&mac.mpo;_check_socket_bind</function> int - &mac.mpo;_check_vnode_relabel + &mac.mpo;_check_socket_bind struct ucred *cred - struct vnode - *vp - struct label - *vnodelabel + struct socket + *socket struct label - *newlabel + *socketlabel + struct sockaddr + *sockaddr &mac.thead; cred Subject credential - Immutable - vp - Object; vnode - Locked + socket + Socket to be bound - vnodelabel - Existing policy label for - vp + socketlabel + Policy label for + socket - newlabel - Policy label update to later be applied to - vp + sockaddr + Address of + socket - Determine whether the subject credential can relabel the - passed vnode to the passed label update. - - <function>&mac.mpo;_check_mount_stat</function> + + + <function>&mac.mpo;_check_socket_connect</function> - int &mac.mpo;_check_mount_stat + int + &mac.mpo;_check_socket_connect struct ucred *cred - struct mount - *mp + struct socket + *socket struct label - *mountlabel + *socketlabel + struct sockaddr + *sockaddr &mac.thead; cred Subject credential - mp - Object; file system mount + socket + Socket to be connected - mountlabel + socketlabel Policy label for - mp + socket - + + + sockaddr + Address of + socket + + - - Determine whether the subject credential can see the - results of a statfs performed on the file system. Return + 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 - 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. + failure: EACCES for label mismatches, + EPERM for lack of privilege. - - - <function>&mac.mpo;_check_proc_debug</function> - + + + <function>&mac.mpo;_check_socket_receive</function> + int - &mac.mpo;_check_proc_debug - + &mac.mpo;_check_socket_receive + struct ucred *cred - struct proc - *proc + struct socket + *so + struct label + *socketlabel - + &mac.thead; - + cred Subject credential - Immutable - + - proc - Object; process + so + Socket + + + + socketlabel + Policy label associated with + so - - 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. + + Determine whether the subject should be allowed to + receive information from the socket + so. - - - <function>&mac.mpo;_check_vnode_access</function> - + + + <function>&mac.mpo;_check_socket_send</function> + int - &mac.mpo;_check_vnode_access - + &mac.mpo;_check_socket_send + struct ucred *cred - struct vnode - *vp + struct socket + *so struct label - *label - int flags + *socketlabel - + &mac.thead; - + cred Subject credential - - - vp - Object; vnode - - + - label - Policy label for - vp + so + Socket - + - flags - &man.access.2; flags + socketlabel + Policy label associated with + so - - 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. + + Determine whether the subject should be allowed to send + information across the socket + so. - - <function>&mac.mpo;_check_vnode_chdir</function> + + <function>&mac.mpo;_check_cred_visible</function> int - &mac.mpo;_check_vnode_chdir + &mac.mpo;_check_cred_visible struct ucred - *cred - struct vnode - *dvp - struct label - *dlabel + *u1 + struct ucred + *u2 &mac.thead; - cred + u1 Subject credential - dvp - Object; vnode to &man.chdir.2; into - - - - dlabel - Policy label for - dvp + u2 + Object credential - Determine whether the subject credential can change the - process working directory to the passed vnode. Return + 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 mismatch, - or EPERM for lack of - privilege. + 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. - - <function>&mac.mpo;_check_vnode_create</function> + + <function>&mac.mpo;_check_socket_visible</function> int - &mac.mpo;_check_vnode_create + &mac.mpo;_check_socket_visible struct ucred *cred - struct vnode - *dvp + struct socket + *socket struct label - *dlabel - struct componentname - *cnp - struct vattr - *vap + *socketlabel &mac.thead; cred Subject credential - dvp - Object; vnode + socket + Object; socket - dlabel + socketlabel Policy label for - dvp - - - - cnp - Component name for - dvp - - - - vap - vnode attributes for vap + socket - 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. - - <function>&mac.mpo;_check_vnode_delete</function> + + <function>&mac.mpo;_check_ifnet_relabel</function> int - &mac.mpo;_check_vnode_delete + &mac.mpo;_check_ifnet_relabel struct ucred *cred - struct vnode - *dvp + struct ifnet + *ifnet struct label - *dlabel - struct vnode - *vp - void *label - struct componentname - *cnp + *ifnetlabel + struct label + *newlabel &mac.thead; cred Subject credential - dvp - Parent directory vnode - - - - dlabel - Policy label for - dvp - - - - vp - Object; vnode to delete + ifnet + Object; network interface - label - Policy label for - vp + ifnetlabel + Existing policy label for + ifnet - cnp - Component name for - vp + newlabel + Policy label update to later be applied to + ifnet - 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. + Determine whether the subject credential can relabel the + passed network interface to the passed label update. - - <function>&mac.mpo;_check_vnode_deleteacl</function> + + <function>&mac.mpo;_check_socket_relabel</function> int - &mac.mpo;_check_vnode_deleteacl + &mac.mpo;_check_socket_relabel - struct ucred *cred - struct vnode *vp - struct label *label - acl_type_t type + struct ucred + *cred + struct socket + *socket + struct label + *socketlabel + struct label + *newlabel &mac.thead; cred Subject credential - Immutable - vp - Object; vnode - Locked + socket + Object; socket - label - Policy label for - vp + socketlabel + Existing policy label for + socket - type - ACL type + newlabel + Label update to later be applied to + socketlabel - 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. + Determine whether the subject credential can relabel the + passed socket to the passed label update. - - <function>&mac.mpo;_check_vnode_exec</function> + + <function>&mac.mpo;_check_cred_relabel</function> int - &mac.mpo;_check_vnode_exec + &mac.mpo;_check_cred_relabel struct ucred *cred - struct vnode - *vp struct label - *label + *newlabel &mac.thead; cred Subject credential - vp - Object; vnode to execute - - - - label - Policy label for - vp + newlabel + Label update to later be applied to + cred - Determine whether the subject credential can execute the - passed vnode. Determination of execute privilege is made - separately 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. + Determine whether the subject credential can relabel + itself to the passed label update. - - - <function>&mac.mpo;_check_vnode_getacl</function> + + + + <function>&mac.mpo;_check_vnode_relabel</function> int - &mac.mpo;_check_vnode_getacl + &mac.mpo;_check_vnode_relabel struct ucred *cred struct vnode *vp struct label - *label - acl_type_t - type + *vnodelabel + struct label + *newlabel &mac.thead; cred Subject credential + Immutable vp Object; vnode + Locked - label - Policy label for + vnodelabel + Existing policy label for vp - type - ACL type + newlabel + Policy label update to later be applied to + vp - 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. + Determine whether the subject credential can relabel the + passed vnode to the passed label update. - - <function>&mac.mpo;_check_vnode_getextattr</function> + + <function>&mac.mpo;_check_mount_stat</function> - int - &mac.mpo;_check_vnode_getextattr + int &mac.mpo;_check_mount_stat struct ucred *cred - struct vnode - *vp + struct mount + *mp struct label - *label - int - attrnamespace - const char - *name - struct uio - *uio + *mountlabel &mac.thead; cred Subject credential - vp - Object; vnode + mp + Object; file system mount - label + mountlabel Policy label for - vp - - - - attrnamespace - Extended attribute namespace - - - - name - Extended attribute name - - - - uio - I/O structure pointer; see &man.uio.9; + mp - 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 + + 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 mismatch, - or EPERM for lack of - privilege. + 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. - - <function>&mac.mpo;_check_socket_listen</function> + + <function>&mac.mpo;_check_proc_debug</function> int - &mac.mpo;_check_socket_listen + &mac.mpo;_check_proc_debug struct ucred *cred - struct socket - *socket - struct label - *socketlabel + struct proc + *proc &mac.thead; cred Subject credential + Immutable - socket - Object; socket - - - - socketlabel - Policy label for - socket + proc + Object; process - Determine whether the subject credential can listen on - the passed socket. Return 0 for + 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, or EPERM for lack of - privilege. + 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. - - <function>&mac.mpo;_check_vnode_lookup</function> + + <function>&mac.mpo;_check_vnode_access</function> int - &mac.mpo;_check_vnode_lookup + &mac.mpo;_check_vnode_access struct ucred - *cred + *cred struct vnode - *dvp + *vp struct label - *dlabel - struct componentname - *cnp + *label + int flags &mac.thead; cred Subject credential - dvp + vp Object; vnode - dlabel + label Policy label for - dvp + vp - cnp - Component name being looked up + flags + &man.access.2; flags - Determine whether the subject credential can perform a - lookup in the passed directory vnode for the passed name. + 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 mismatch, + failure: EACCES for label mismatches or EPERM for lack of privilege. - - <function>&mac.mpo;_check_vnode_open</function> + + <function>&mac.mpo;_check_vnode_chdir</function> int - &mac.mpo;_check_vnode_open + &mac.mpo;_check_vnode_chdir struct ucred *cred struct vnode - *vp + *dvp struct label - *label - mode_t - acc_mode + *dlabel &mac.thead; cred Subject credential - vp - Object; vnode + dvp + Object; vnode to &man.chdir.2; into - label + dlabel Policy label for - vp - - - - acc_mode - &man.open.2; access mode + dvp - 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. + 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. - - - <function>&mac.mpo;_check_vnode_readdir</function> - + + + <function>&mac.mpo;_check_vnode_chroot</function> + int - &mac.mpo;_check_vnode_readdir - + &mac.mpo;_check_vnode_chroot + struct ucred - *cred + *cred struct vnode - *dvp + *dvp struct label - *dlabel + *dlabel - + &mac.thead; - + cred Subject credential - + dvp - Object; directory vnode + Directory vnode - + dlabel - Policy label for + Policy label associated with 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. + + Determine whether the subject should be allowed to + &man.chroot.2; into the specified directory + (dvp). - - <function>&mac.mpo;_check_vnode_readlink</function> + + <function>&mac.mpo;_check_vnode_create</function> int - &mac.mpo;_check_vnode_readlink + &mac.mpo;_check_vnode_create struct ucred *cred struct vnode - *vp + *dvp struct label - *label + *dlabel + struct componentname + *cnp + struct vattr + *vap &mac.thead; cred Subject credential - vp + dvp Object; vnode - label + dlabel Policy label for - vp + dvp + + + + cnp + Component name for + dvp + + + + vap + vnode attributes for vap - 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. + 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. - - <function>&mac.mpo;_check_rename_from_vnode</function> + + <function>&mac.mpo;_check_vnode_delete</function> int - &mac.mpo;_check_rename_from_vnode + &mac.mpo;_check_vnode_delete struct ucred *cred struct vnode *dvp struct label *dlabel struct vnode *vp - struct label - *label + void *label struct componentname *cnp &mac.thead; cred Subject credential dvp - Directory vnode + Parent directory vnode dlabel Policy label for dvp vp - Object; vnode + Object; vnode to delete label Policy label for vp - cnp - Pathname + Component name for + vp - 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. + 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. - - <function>&mac.mpo;_check_rename_to_vnode</function> + + <function>&mac.mpo;_check_vnode_deleteacl</function> int - &mac.mpo;_check_rename_to_vnode + &mac.mpo;_check_vnode_deleteacl - struct ucred - *cred - struct vnode - *dvp - struct label - *dlabel - struct vnode - *vp - struct label - *label - int samedir - struct componentname - *cnp + struct ucred *cred + struct vnode *vp + struct label *label + acl_type_t type &mac.thead; cred Subject credential - - - - dvp - Directory vnode - - - - dlabel - Policy label for dvp + Immutable vp Object; vnode + Locked label Policy label for vp - cnp - Pathname + type + ACL type - 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 + 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. - - <function>&mac.mpo;_check_vnode_revoke</function> + + <function>&mac.mpo;_check_vnode_exec</function> int - &mac.mpo;_check_vnode_revoke + &mac.mpo;_check_vnode_exec struct ucred *cred struct vnode *vp struct label *label &mac.thead; cred Subject credential vp - Object; vnode + Object; vnode to execute 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 + 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. - - <function>&mac.mpo;_check_vnode_setacl</function> + + <function>&mac.mpo;_check_vnode_getacl</function> int - &mac.mpo;_check_vnode_setacl + &mac.mpo;_check_vnode_getacl 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 + 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. - - <function>&mac.mpo;_check_vnode_setextattr</function> + + <function>&mac.mpo;_check_vnode_getextattr</function> int - &mac.mpo;_check_vnode_setextattr + &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 + 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 + 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. - - - <function>&mac.mpo;_check_vnode_setflags</function> - + + + <function>&mac.mpo;_check_vnode_link</function> + int - &mac.mpo;_check_vnode_setflags - + &mac.mpo;_check_vnode_link + struct ucred *cred + struct vnode + *dvp + struct label + *dlabel struct vnode *vp struct label *label - u_long flags + struct componentname + *cnp - + &mac.thead; - + cred Subject credential - + + + dvp + Directory vnode + + + + dlabel + Policy label associated with + dvp + + vp - Object; vnode + Link destination vnode - + label - Policy label for + Policy label associated with vp - + - flags - File flags; see &man.chflags.2; + cnp + Component name for the link being created - - 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. + + Determine whether the subject should be allowed to + create a link to the vnode vp with + the name specified by cnp. - - - <function>&mac.mpo;_check_vnode_setmode</function> - + + + <function>&mac.mpo;_check_vnode_mmap</function> + int - &mac.mpo;_check_vnode_setmode - + &mac.mpo;_check_vnode_mmap + struct ucred *cred struct vnode *vp struct label *label - mode_t mode + int prot - + &mac.thead; - + cred Subject credential - + vp - Object; vnode + Vnode to map - + label - Policy label for vp + Policy label associated with + vp - + - mode - File mode; see &man.chmod.2; + prot + Mmap protections (see &man.mmap.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. + + + + Determine whether the subject should be allowed to map + the vnode vp with the protections + specified in prot. - - - <function>&mac.mpo;_check_vnode_setowner</function> - + + + <function>&mac.mpo;_check_vnode_mmap_downgrade</function> + - int - &mac.mpo;_check_vnode_setowner - + void + &mac.mpo;_check_vnode_mmap_downgrade + struct ucred *cred struct vnode *vp struct label *label - uid_t uid - gid_t gid + int *prot - + &mac.thead; - + cred - Subject credential + See + . - + vp - Object; vnode - + label - Policy label for vp - - - - uid - User ID - + - gid - Group ID + prot + Mmap protections to be downgraded - - 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. + + Downgrade the mmap protections based on the subject and + object labels. - - - <function>&mac.mpo;_check_vnode_setutimes</function> - + + + <function>&mac.mpo;_check_vnode_mprotect</function> + int - &mac.mpo;_check_vnode_setutimes - + &mac.mpo;_check_vnode_mprotect + struct ucred - *cred + *cred struct vnode - *vp + *vp struct label - *label - struct timespec - atime - struct timespec - mtime + *label + int prot - + &mac.thead; - + cred Subject credential - + vp - Object; vp - - - - label - Policy label for - vp - - - - atime - Access time; see &man.utimes.2; + Mapped vnode - + - mtime - Modification time; see &man.utimes.2; + prot + Memory protections - - 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. + + Determine whether the subject should be allowed to + set the specified memory protections on memory mapped from + the vnode vp. - - - <function>&mac.mpo;_check_proc_sched</function> - + + + <function>&mac.mpo;_check_vnode_poll</function> + int - &mac.mpo;_check_proc_sched - + &mac.mpo;_check_vnode_poll + struct ucred - *ucred - struct proc - *proc + *active_cred + struct ucred + *file_cred + struct vnode + *vp + struct label + *label - + &mac.thead; - + - cred + active_cred Subject credential - + - proc - Object; process + file_cred + Credential associated with the struct + file + + + + vp + Polled vnode + + + + label + Policy label associated with + vp - - 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. + + Determine whether the subject should be allowed to poll + the vnode vp. - - - <function>&mac.mpo;_check_proc_signal</function> - + + + <function>&mac.mpo;_check_vnode_rename_from</function> + int - &mac.mpo;_check_proc_signal - + &mac.mpo;_vnode_rename_from + struct ucred *cred - struct proc - *proc - int signal + struct vnode + *dvp + struct label + *dlabel + struct vnode + *vp + struct label + *label + struct componentname + *cnp - + &mac.thead; - + cred Subject credential - + - proc - Object; process + dvp + Directory vnode - + - signal - Signal; see &man.kill.2; + dlabel + Policy label associated with + dvp + + + + vp + Vnode to be renamed + + + + label + Policy label asociated with + vp + + + + cnp + Component name for + vp - - 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. + + Determine whether the subject should be allowed to + rename the vnode vp to something + else. - - - <function>&mac.mpo;_check_vnode_stat</function> - + + + <function>&mac.mpo;_check_vnode_rename_to</function> + int - &mac.mpo;_check_vnode_stat - + &mac.mpo;_check_vnode_rename_to + 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 associated with + dvp + + vp - Object; vnode + Overwritten vnode - + label - Policy label for + Policy label associated with vp + + + samedir + Boolean; 1 if the source and + destination directories are the same + + + + cnp + Destination component name + - - 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. + + Determine whether the subject should be allowed to + rename to the vnode vp, into the + directory dvp, or to the name + represented by cnp. If there is no + existing file to overwrite, vp and + label will be NULL. - - <function>&mac.mpo;_check_ifnet_transmit</function> + + <function>&mac.mpo;_check_socket_listen</function> int - &mac.mpo;_check_ifnet_transmit + &mac.mpo;_check_socket_listen struct ucred *cred - struct ifnet - *ifnet - struct label - *ifnetlabel - struct mbuf - *mbuf + struct socket + *socket struct label - *mbuflabel + *socketlabel &mac.thead; cred Subject credential - ifnet - Network interface - - - - ifnetlabel - Policy label for - ifnet - - - - mbuf - Object; mbuf to be sent + socket + Object; socket - mbuflabel + socketlabel Policy label for - mbuf + socket - Determine whether the network interface can transmit the - passed mbuf. Return 0 for + 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. - - <function>&mac.mpo;_check_socket_receive</function> + + <function>&mac.mpo;_check_vnode_lookup</function> int - &mac.mpo;_check_socket_receive + &mac.mpo;_check_vnode_lookup struct ucred - *cred - struct ifnet - *ifnet - struct label - *ifnetlabel - struct mbuf - *mbuf + *cred + struct vnode + *dvp struct label - *mbuflabel + *dlabel + struct componentname + *cnp &mac.thead; cred Subject credential - ifnet - Network interface + dvp + Object; vnode - ifnetlabel + dlabel Policy label for - ifnet - - - - mbuf - Object; mbuf to be received + dvp - mbuflabel - Policy label for - mbuf + cnp + Component name being looked up - Determine whether the socket may receive the datagram - stored in the passed mbuf header. Return - 0 for success, or an + 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 - failures: EACCES for label mismatch, + failure: EACCES for label mismatch, or EPERM for lack of privilege. - - <function>&mac.mpo;_check_socket_visible</function> + + <function>&mac.mpo;_check_vnode_open</function> int - &mac.mpo;_check_socket_visible + &mac.mpo;_check_vnode_open struct ucred *cred - struct socket - *so + struct vnode + *vp struct label - *socketlabel + *label + int + acc_mode &mac.thead; cred Subject credential - Immutable - so - Object; socket + vp + Object; vnode - socketlabel + label 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 separate 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). - - - <function>&mac.mpo;_init_bpfdesc</function> - - - - void - &mac.mpo;_init_bpfdesc - - struct bpf_d - *bpf_d - struct label - *label - - - - - - &mac.thead; - - - - bpf_d - Object; bpf descriptor + vp - label - New label to apply + acc_mode + &man.open.2; access mode - Initialize the label on a newly instantiated bpfdesc (BPF - descriptor) + 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. - - <function>&mac.mpo;_init_devfsdirent</function> + + <function>&mac.mpo;_check_vnode_readdir</function> - void - &mac.mpo;_init_devfsdirent + int + &mac.mpo;_check_vnode_readdir - struct devfs_dirent - *devfs_dirent + struct ucred + *cred + struct vnode + *dvp struct label - *label + *dlabel &mac.thead; - devfs_dirent - Object; devfs directory entry + cred + Subject credential - label - New label to apply + dvp + Object; directory vnode + + + + dlabel + Policy label for + dvp - Initialize the label on a newly instantiated devfs - entry. + 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. - - <function>&mac.mpo;_init_ifnet</function> + + <function>&mac.mpo;_check_vnode_readlink</function> - void - &mac.mpo;_init_ifnet + int + &mac.mpo;_check_vnode_readlink - struct ifnet - *ifnet + struct ucred + *cred + struct vnode + *vp struct label *label &mac.thead; - ifnet - Object; network interface + cred + Subject credential + + + + vp + Object; vnode label - New label to apply + Policy label for + vp - Initialize the label on a newly instantiated network - interface. + 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. - - <function>&mac.mpo;_init_ipq</function> + + <function>&mac.mpo;_check_vnode_revoke</function> - void - &mac.mpo;_init_ipq + int + &mac.mpo;_check_vnode_revoke - struct ipq - *ipq + struct ucred + *cred + struct vnode + *vp struct label *label &mac.thead; - ipq - Object; IP reassembly queue + cred + Subject credential + + + + vp + Object; vnode label - New label to apply + Policy label for + vp - Initialize the label on a newly instantiated IP fragment - reassembly queue. + 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. - - <function>&mac.mpo;_init_mbuf</function> + + <function>&mac.mpo;_check_vnode_setacl</function> - void - &mac.mpo;_init_mbuf + int + &mac.mpo;_check_vnode_setacl - struct mbuf - *mbuf - int how + struct ucred + *cred + struct vnode + *vp struct label *label + acl_type_t + type + struct acl + *acl &mac.thead; - mbuf - Object; mbuf + cred + Subject credential - how - Blocking/non-blocking &man.malloc.9; see - below + vp + Object; vnode label - Policy label to initialize + Policy label for + vp + + + + type + ACL type + + + + acl + ACL + - 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. + 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. - - <function>&mac.mpo;_init_mount</function> + + <function>&mac.mpo;_check_vnode_setextattr</function> - void - &mac.mpo;_init_mount + int + &mac.mpo;_check_vnode_setextattr - struct mount - *mount - struct label - *mntlabel + struct ucred + *cred + struct vnode + *vp struct label - *fslabel + *label + int + attrnamespace + const char + *name + struct uio + *uio - &mac.thead; - mount - Object; file system mount point + cred + Subject credential - mntlabel - Policy label to be initialized for the mount - itself + vp + Object; vnode - fslabel - Policy label to be initialized for the file - system + label + Policy label for vp + + + + attrnamespace + Extended attribute namespace + + + + name + Extended attribute name + + + + uio + I/O structure pointer; see &man.uio.9; - Initialize the labels on a newly instantiated mount - point. + 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. - - <function>&mac.mpo;_init_socket</function> + + <function>&mac.mpo;_check_vnode_setflags</function> - void - &mac.mpo;_init_socket + int + &mac.mpo;_check_vnode_setflags - struct socket - *socket + struct ucred + *cred + struct vnode + *vp struct label *label - struct label - *peerlabel + u_long flags &mac.thead; - socket - Object; socket + cred + Subject credential + + + + vp + Object; vnode label - New label to apply to the socket + Policy label for + vp - peerlabel - New label to apply to the socket's peer + flags + File flags; see &man.chflags.2; - Initialize the labels on a newly instantiated - socket. + 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. - - <function>&mac.mpo;_init_cred</function> + + <function>&mac.mpo;_check_vnode_setmode</function> - void - &mac.mpo;_init_cred + int + &mac.mpo;_check_vnode_setmode struct ucred *cred + struct vnode + *vp struct label *label + mode_t mode &mac.thead; cred - Subject; user credetial + Subject credential + + + + vp + Object; vnode label - New label + Policy label for vp + + + + mode + File mode; see &man.chmod.2; - Initialize the labels on a newly instantiated subject. + 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. - - <function>&mac.mpo;_init_temp</function> + + <function>&mac.mpo;_check_vnode_setowner</function> - void - &mac.mpo;_init_temp + 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 - Temporary label + Policy label for vp + + + + uid + User ID + + + + gid + Group ID - Initialize a newly instantiated temporary label; - temporary labels are frequently used to hold label update - requests. + 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. - - <function>&mac.mpo;_init_vnode</function> + + <function>&mac.mpo;_check_vnode_setutimes</function> - void - &mac.mpo;_init_vnode + int + &mac.mpo;_check_vnode_setutimes + struct ucred + *cred struct vnode - *vp + *vp struct label - *label + *label + struct timespec + atime + struct timespec + mtime &mac.thead; + + cred + Subject credential + + vp - Object; file system object + Object; vp label - New label to initialize + Policy label for + vp + + + + atime + Access time; see &man.utimes.2; + + + + mtime + Modification time; see &man.utimes.2; - Initialize the label on a newly instantiated vnode. + 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. - - <function>&mac.mpo;_destroy_bpfdesc</function> + + <function>&mac.mpo;_check_proc_sched</function> - void - &mac.mpo;_destroy_bpfdesc + int + &mac.mpo;_check_proc_sched - struct bpf_d - *bpf_d - struct label - *label + struct ucred + *ucred + struct proc + *proc &mac.thead; - bpf_d - Object; bpf descriptor + cred + Subject credential - label - Label being destroyed + proc + Object; process - 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. + 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. - - <function>&mac.mpo;_destroy_devfsdirent</function> + + <function>&mac.mpo;_check_proc_signal</function> - void - &mac.mpo;_destroy_devfsdirent + int + &mac.mpo;_check_proc_signal - struct devfs_dirent - *devfs_dirent - struct label - *label + struct ucred + *cred + struct proc + *proc + int signal &mac.thead; - devfs_dirent - Object; devfs directory entry + cred + Subject credential - label - Label being destroyed + proc + Object; process + + + + signal + Signal; see &man.kill.2; - 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. + 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. - - <function>&mac.mpo;_destroy_ifnet</function> + + <function>&mac.mpo;_check_vnode_stat</function> - void - &mac.mpo;_destroy_ifnet + int + &mac.mpo;_check_vnode_stat - struct ifnet - *ifnet + struct ucred + *cred + struct vnode + *vp struct label *label &mac.thead; - ifnet - Object; network interface + cred + Subject credential + + + + vp + Object; vnode label - Label being destroyed + Policy label for + vp - 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. + 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. - - <function>&mac.mpo;_destroy_ipq</function> + + <function>&mac.mpo;_check_ifnet_transmit</function> - void - &mac.mpo;_destroy_ipq + int + &mac.mpo;_check_ifnet_transmit - struct ipq - *ipq + struct ucred + *cred + struct ifnet + *ifnet struct label - *label + *ifnetlabel + struct mbuf + *mbuf + struct label + *mbuflabel &mac.thead; - ipq - Object; IP reassembly queue + cred + Subject credential - label - Label being destroyed + ifnet + Network interface + + + + ifnetlabel + Policy label for + ifnet + + + + mbuf + Object; mbuf to be sent + + + + mbuflabel + Policy label for + mbuf - 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. + 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. - - <function>&mac.mpo;_destroy_mbuf</function> + + <function>&mac.mpo;_check_socket_deliver</function> - void - &mac.mpo;_destroy_mbuf + int + &mac.mpo;_check_socket_deliver + struct ucred + *cred + struct ifnet + *ifnet + struct label + *ifnetlabel struct mbuf *mbuf struct label - *label + *mbuflabel &mac.thead; + + cred + Subject credential + + + + ifnet + Network interface + + + + ifnetlabel + Policy label for + ifnet + + mbuf - Object; mbuf + Object; mbuf to be delivered - label - Label being destroyed + mbuflabel + Policy label for + mbuf - 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. + 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. - - <function>&mac.mpo;_destroy_mount</function> + + <function>&mac.mpo;_check_socket_visible</function> - void - &mac.mpo;_destroy_mount + int + &mac.mpo;_check_socket_visible - struct mount - *mp - struct label - *mntlabel + struct ucred + *cred + struct socket + *so struct label - *fslabel + *socketlabel &mac.thead; - mp - Object; file system mount point + cred + Subject credential + Immutable - mntlabel - Mount point label being destroyed + so + Object; socket - fslabel - File system label being destroyed> + socketlabel + Policy label for + so - 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. + 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. - - - <function>&mac.mpo;_destroy_socket</function> - + + + <function>&mac.mpo;_check_system_acct</function> + - void - &mac.mpo;_destroy_socket - - struct socket - *socket - struct label - *label + int + &mac.mpo;_check_system_acct + + struct ucred + *ucred + struct vnode + *vp struct label - *peerlabel + *vlabel - + &mac.thead; - + - socket - Object; socket + ucred + Subject credential - + - label - Socket label being destroyed + vp + Accounting file; &man.acct.5; - + - peerlabel - Socket peer label being destroyed + vlabel + Label associated with + vp - - 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. + + Determine whether the subject should be allowed to + enable accounting, based on its label and the label of the + accounting log file. - - - <function>&mac.mpo;_destroy_cred</function> - + + + <function>&mac.mpo;_check_system_nfsd</function> + - void - &mac.mpo;_destroy_cred - + int + &mac.mpo;_check_system_nfsd + struct ucred *cred - struct label - *label - + &mac.thead; - + cred - Subject; user credential + Subject credential - + + + + + Determine whether the subject should be allowed to call + &man.nfssvc.2;. + + + + <function>&mac.mpo;_check_system_reboot</function> + + + + int + &mac.mpo;_check_system_reboot + + struct ucred + *cred + int howto + + + + + + &mac.thead; + + - label - Label being destroyed + cred + Subject credential + + + + howto + howto parameter from + &man.reboot.2; - - 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. + + Determine whether the subject should be allowed to + reboot the system in the specified manner. - - - <function>&mac.mpo;_destroy_temp</function> - + + + <function>&mac.mpo;_check_system_settime</function> + - void - &mac.mpo;_destroy_temp - - struct label - *label + int + &mac.mpo;_check_system_settime + + struct ucred + *cred - + &mac.thead; - + - label - Temporary label being destroyed + cred + Subject credential - - 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. + + Determine whether the user should be allowed to set the + system clock. - - - <function>&mac.mpo;_destroy_vnode</function> - + + + <function>&mac.mpo;_check_system_swapon</function> + - void - &mac.mpo;_destroy_vnode - + int + &mac.mpo;_check_system_swapon + + struct ucred + *cred struct vnode *vp struct label - *label + *vlabel - + &mac.thead; - + + + cred + Subject credential + + vp - Object; file system object + Swap device - + - label - Label being destroyed + vlabel + Label associated with + vp - - 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. + + Determine whether the subject should be allowed to add + vp as a swap device. - - - <function>&mac.mpo;_externalize</function> - + + + <function>&mac.mpo;_check_system_sysctl</function> + - void - &mac.mpo;_externalize - - struct label - *label - struct mac - *extmac + int + &mac.mpo;_check_system_sysctl + + struct ucred + *cred + int *name + u_int *namelen + void *old + size_t + *oldlenp + int inkernel + void *new + size_t newlen - + &mac.thead; - + - label - Label to be externalized + cred + Subject credential - + + + name + See &man.sysctl.3; + + + + namelen + + + + old + + - extmac - MAC structure to be filled in + oldlenp + + + + inkernel + Boolean; 1 if called from + kernel + + + + new + See &man.sysctl.3; + + + + newlen + - - 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. + + Determine whether the subject should be allowed to make + the specified &man.sysctl.3; transaction. + + + + Label Management Calls - - <function>&mac.mpo;_internalize</function> + 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). + + + + + <function>&mac.mpo;_destroy_vnode_label</function> void - &mac.mpo;_internalize + &mac.mpo;_destroy_vnode_label + struct vnode + *vp struct label *label - struct mac - *extmac &mac.thead; - label - Label to be filled in + vp + Object; file system object - extmac - MAC structure to internalize + label + Label being destroyed - 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. + 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. - - - 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 TrustedBSD MAC Framework provides a number of - Application Programming Interfaces (APIs) to that permit - user applications to interact with security labels and - policies. Several categories of interfaces are available - to applications: library calls to convert label data to - and from user-chewable text strings based on a central - configuration, and system calls and ioctls to retrieve - and manipulate labels on kernel-maintained objects. In - addition, interfaces are provided to permit atomic - changing of the process label when a new file is executed, - as well as a multiplexor system call permitting policies - to export functionality without reserving system call - numbers. Finally, modules may be loaded and unloaded - using the existing module management interfaces. - - A list of calls with cross-references will go here - soon. - + 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.ent b/en_US.ISO8859-1/books/developers-handbook/mac.ent index 381b994b23..6ead9b19ca 100644 --- a/en_US.ISO8859-1/books/developers-handbook/mac.ent +++ b/en_US.ISO8859-1/books/developers-handbook/mac.ent @@ -1,18 +1,122 @@ - + Parameter Description Locking '> + +struct label *label + char *element_name + char *element_data + size_t size + size_t *len + int *claimed +'> + + + + label + Label to be externalized + + + + element_name + Name of the policy whose label should be externalized + + + + element_data + Buffer; to be filled in with text representation of label + + + + size + Size of element_data + + + + len + To be filled in with the length of the string representing the + label data. + + + + claimed + Should be incremented when element_data + can be filled in. + + +'> + +Produce an externalized label based on the label structure passed. + An externalized label consists of a text representation of the label + contents that can be used with userland applications and read by the + user. Currently, all policies' externalize entry + points will be called, so the implementation should check the contents + of element_name before attempting to fill in + element_data. If + element_name does not match the name of your + policy, simply return 0. Only return nonzero + if an error occurs while externalizing the label data. Once the policy + fills in element_data, *claimed + should be incremented. +"> + +struct label *label + char *element_name + char *element_data + int *claimed +'> + + + + label + Label to be filled in + + + + element_name + Name of the policy whose label should be internalized + + + + element_data + Text data to be internalized + + + + claimed + Should be incremented when data can be successfully + internalized. + + +'> + +Produce an internal label structure based on externalized label data + in text format. Currently, all policies' internalize + entry points are called when internalization is requested, so the + implementation should compare the contents of + element_name to its own name in order to be sure + it should be internalizing the data in element_data. + Just as in the externalize entry points, the entry + point should return 0 if + element_name does not match its own name, or when + data can successfully be internalized, in which case + *claimed should be incremented. +"> 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 d6117ad667..caee9e28a4 100644 --- a/en_US.ISO8859-1/books/developers-handbook/mac/chapter.sgml +++ b/en_US.ISO8859-1/books/developers-handbook/mac/chapter.sgml @@ -1,5730 +1,7483 @@ Chris Costello TrustedBSD Project
chris@FreeBSD.org
 Robert Watson TrustedBSD Project
rwatson@FreeBSD.org
 The TrustedBSD MAC Framework + + + MAC Documentation Copyright + + This documentation was developed for the FreeBSD Project by + Chris Costello at Safeport Network Services and Network + Associates Laboratories, the Security Research Division of + Network Associates, Inc. under DARPA/SPAWAR contract + N66001-01-C-8035 (CBOSS), as part of the DARPA + CHATS research program. + + Redistribution and use in source (SGML DocBook) and + 'compiled' forms (SGML, HTML, PDF, PostScript, RTF and so forth) + with or without modification, are permitted provided that the + following conditions are met: + + + + Redistributions of source code (SGML DocBook) must + retain the above copyright notice, this list of conditions + and the following disclaimer as the first lines of this file + unmodified. + + + + Redistributions in compiled form (transformed to other + DTDs, converted to PDF, PostScript, RTF and other formats) + must reproduce the above copyright notice, this list of + conditions and the following disclaimer in the documentation + and/or other materials provided with the + distribution. + + + + + THIS DOCUMENTATION IS PROVIDED BY THE NETWORKS ASSOCIATES + TECHNOLOGY, INC "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NETWORKS ASSOCIATES TECHNOLOGY, + INC BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS + OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER + CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN + IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + Synopsis - Mandatory Access Control (MAC) is a security feature frequently - found in commercial trusted operating systems. MAC supplements - existing Discretionary Access Control (DAC) protections (such as - file system permissions and access control lists) by allowing the - security administrator to define mandatory protections for - system objects. Mandatory protections may be distinguished from - discretionary protections in that DAC is applied at the discretion - of the object owner, whereas MAC protections are defined by the - administrator and applied to all users and objects in the system - and may not be bypassed even by object owners. A variety of - MAC policies have been explored in security research literature - as well as the commercial trusted operating system space. These - include policies such as the Multi-Level Security (MLS) - confidentiality policy, used to prevent inappropriate sharing of - information on multi-user systems, and the Biba integrity policy, - typically used to protect the integrity of system and user - services. - - The implementation of MAC found in FreeBSD was developed by - the TrustedBSD Project, and includes support for both a number of - specific MAC policies, and for a flexible and extensible security - framework to support the easy creation of new kernel security - policies. This framework isolates the internals of specific MAC - policies from the implementation of kernel services, and - encapsulates the policies in policy modules. Policy modules may - be added to the system without changes to the base kernel, and can - augment the kernel security policy in a variety of ways. In - addition, policies may provide a shared object implementation - of common MAC interfaces for userland applications, permitting - applications to be easily extended to manage labels for new - policies. Support is provided for setting labels on user - processes at login, as well as in a number of other locations where - user context management occurs. - - This chapter introduces the MAC policy userland and kernel - policy frameworks and provides documentation for a sample MAC - policy module. + MAC, or Mandatory Access Control, is a feature introduced by + the TrustedBSD Project to supplement the existing standard DAC + (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 + + General-Purpose Module Entry Points 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 }, + allocation of label state by the framework. + + static struct mac_policy_ops mac_policy_ops = +{ + .mpo_destroy = mac_policy_destroy, + .mpo_init = mac_policy_init, + .mpo_init_bpfdesc_label = mac_policy_init_bpfdesc_label, + .mpo_init_cred_label = mac_policy_init_label, /* ... */ - { 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 } + .mpo_check_vnode_setutimes = mac_policy_check_vnode_setutimes, + .mpo_check_vnode_stat = mac_policy_check_vnode_stat, + .mpo_check_vnode_write = mac_policy_check_vnode_write, }; The MAC policy entry point vector, - mac_none_ops in this example, associates + mac_policy_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 + the .mpo_destroy and .mpo_init + entry points. .mpo_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 + locks. .mpo_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. <function>&mac.mpo;_init</function 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. <function>&mac.mpo;_destroy</function> 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. + + + <function>&mac.mpo;_syscall</function> + + + + int + &mac.mpo;_syscall + + struct thread + *td + int call + void *arg + + + + + + &mac.thead; + + + + td + Calling thread + + + + call + Syscall number + + + + arg + Pointer to syscall arguments + + + + + + This 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. + + Modules must currently perform the + copyin() of the syscall data on their + own. + - - File System Object Labeling Event Operations + + <function>&mac.mpo;_thread_userret</function> + + + + void + &mac.mpo;_thread_userret + + struct thread + *td + + + + + + &mac.thead; + + + + td + Returning thread + + + + + + + This entry point permits policy modules to perform + MAC-related events when a thread returns to user space. + This is required for policies that have floating process + labels, as it's not always possible to acquire the process + lock at arbitrary points in the stack during system call + processing; process labels might represent traditional + authentication data, process history information, or other + data. + + + + + Label Operations + + + <function>&mac.mpo;_init_bpfdesc_label</function> - - <function>&mac.mpo;_create_devfs_device</function> - - - - 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. - + + + void + &mac.mpo;_init_bpfdesc_label + + struct bpf_d + *bpf_d + struct label + *label + + - - <function>&mac.mpo;_create_devfs_directory</function> - - - - void - &mac.mpo;_create_devfs_directory - - char *dirname - int dirnamelen - struct devfs_dirent - *devfs_dirent - struct label - *label - - - - - - &mac.thead; + + + &mac.thead; + + + + bpf_d + Object; bpf descriptor + - - - 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. - + + label + New label to apply + + + + - - <function>&mac.mpo;_create_devfs_vnode</function> - + Initialize the label on a newly instantiated bpfdesc (BPF + descriptor) + + + + <function>&mac.mpo;_init_cred_label</function> + + + + void + &mac.mpo;_init_cred_label + + struct label + *label + + + + + + &mac.thead; + + + + label + New label to initialize + + + + + + Initialize the label for a newly instantiated + user credential. + + + + <function>&mac.mpo;_init_devfsdirent_label</function> + + + + void + &mac.mpo;_init_devfsdirent_label + + 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. + + + + <function>&mac.mpo;_init_ifnet_label</function> + + + + void + &mac.mpo;_init_ifnet_label + + 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. + + + + <function>&mac.mpo;_init_ipq_label</function> + + + + void + &mac.mpo;_init_ipq_label + + 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. + + + + <function>&mac.mpo;_init_mbuf_label</function> + + + + void + &mac.mpo;_init_mbuf_label + + 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. + + + + <function>&mac.mpo;_init_mount_label</function> + + + + void + &mac.mpo;_init_mount_label + + 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. + + + + <function>&mac.mpo;_init_mount_fs_label</function> + + + + void + &mac.mpo;_init_mount_fs_label + + struct label + *label + + + + + + &mac.thead; + + + + label + Label to be initialized + + + + + + Initialize the label on a newly mounted file + system. + + + + <function>&mac.mpo;_init_pipe_label</function> + + + + void + &mac.mpo;_init_pipe_label + + struct + label*label + + + + + + &mac.thead; + + + + label + Label to be filled in + + + + + Initialize a label for a newly instantiated pipe. + + + + <function>&mac.mpo;_init_socket_label</function> + + + + void + &mac.mpo;_init_socket_label + + struct label + *label + int flag + + + + + + &mac.thead; + + + + label + New label to initialize + + + + flag + &man.malloc.9; flags + + + + + + Initialize a label for a newly instantiated + socket. + + + + <function>&mac.mpo;_init_socket_peer_label</function> + + + + void + &mac.mpo;_init_socket_peer_label + + struct label + *label + int flag + + + + + + &mac.thead; + + + + label + New label to initialize + + + + flag + &man.malloc.9; flags + + + + + + Initialize the peer label for a newly instantiated + socket. + + + + <function>&mac.mpo;_init_proc_label</function> + + + + void + &mac.mpo;_init_proc_label + + struct label + *label + + + + + + &mac.thead; + + + + label + New label to initialize + + + + + + Initialize the label for a newly instantiated + process. + + + + + <function>&mac.mpo;_init_vnode_label</function> + + + + void + &mac.mpo;_init_vnode_label + + 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. + + + <function>&mac.mpo;_destroy_bpfdesc_label</function> + + + + void + &mac.mpo;_destroy_bpfdesc_label + + struct label + *label + + + + + + &mac.thead; + + + + label + bpfdesc label + + + + + + Destroy the label on a bpf descriptor. In this entry + point a policy should free any internal storage associated + with label so that it may be + destroyed. + + + + <function>&mac.mpo;_destroy_cred_label</function> + + + + void + &mac.mpo;_destroy_cred_label + + 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. + + + + + <function>&mac.mpo;_destroy_devfsdirent_label</function> + + + + void + &mac.mpo;_destroy_devfsdirent_label + + 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. + + + + <function>&mac.mpo;_destroy_ifnet_label</function> + + + + void + &mac.mpo;_destroy_ifnet_label + + struct label + *label + + + + + + &mac.thead; + + + + 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. + + + + <function>&mac.mpo;_destroy_ipq_label</function> + + + + void + &mac.mpo;_destroy_ipq_label + + struct label + *label + + + + + + &mac.thead; + + + + 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. + + + + <function>&mac.mpo;_destroy_mbuf_label</function> + + + + void + &mac.mpo;_destroy_mbuf_label + + struct label + *label + + + + + + &mac.thead; + + + + 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. + + + + <function>&mac.mpo;_destroy_mount_label</function> + + + + void + &mac.mpo;_destroy_mount_label + + struct label + *label + + + + + + &mac.thead; + + + + label + Mount point 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 so that they + may be destroyed. + + + + <function>&mac.mpo;_destroy_mount_label</function> + + + + void + &mac.mpo;_destroy_mount_label + + 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. + + + + <function>&mac.mpo;_destroy_socket_label</function> + + + + void + &mac.mpo;_destroy_socket_label + + struct label + *label + + + + + + + &mac.thead; + + + + label + Socket label being destroyed + + + + + + + Destroy the label on a socket. In this entry point, a + policy module should free any internal storage associated + with label so that it may be + destroyed. + + + + <function>&mac.mpo;_destroy_socket_peer_label</function> + + + + void + &mac.mpo;_destroy_socket_peer_label + + struct label + *peerlabel + + + + + + &mac.thead; + + + + peerlabel + Socket peer label being destroyed + + + + + + Destroy the peer label on a socket. In this entry + point, a policy module should free any internal storage + associated with label so that it may + be destroyed. + + + + <function>&mac.mpo;_destroy_pipe_label</function> + + + + void + &mac.mpo;_destroy_pipe_label + + struct label + *label + + + + + + &mac.thead; + + + + label + Pipe label + + + + + + Destroy the label on a pipe. In this entry point, a + policy module should free any internal storage associated + with label so that it may be + destroyed. + + + + <function>&mac.mpo;_destroy_proc_label</function> + + + + void + &mac.mpo;_destroy_proc_label + struct label + *label + + + + + + &mac.thead; + + + + label + Process label + + + + + + Destroy the label on a process. In this entry point, a + policy module should free any internal storage associated + with label so that it may be + destroyed. + + + + <function>&mac.mpo;_copy_pipe_label</function> + + + + void + &mac.mpo;_copy_pipe_label + + struct label + *src + struct label + *dest + + + + + + &mac.thead; + + + + src + Source label + + + + dest + Destination label + + + + + + Copy the label information in + src into + dest. + + + + <function>&mac.mpo;_copy_vnode_label</function> + + + + void + &mac.mpo;_copy_vnode_label + + struct label + *src + struct label + *dest + + + + + + &mac.thead; + + + + src + Source label + + + + dest + Destination label + + + + + + Copy the label information in + src into + dest. + + + + <function>&mac.mpo;_externalize_cred_label</function> + + + + int + &mac.mpo;_externalize_cred_label + + &mac.externalize.paramdefs; + + + + + + &mac.thead; + + &mac.externalize.tbody; + + + + &mac.externalize.para; + + + + <function>&mac.mpo;_externalize_ifnet_label</function> + + + + int + &mac.mpo;_externalize_ifnet_label + + &mac.externalize.paramdefs; + + + + + + &mac.thead; + + &mac.externalize.tbody; + + + + &mac.externalize.para; + + + + <function>&mac.mpo;_externalize_pipe_label</function> + + + + int + &mac.mpo;_externalize_pipe_label + + &mac.externalize.paramdefs; + + + + + + &mac.thead; + + &mac.externalize.tbody; + + + + &mac.externalize.para; + + + + <function>&mac.mpo;_externalize_socket_label</function> + + + + int + &mac.mpo;_externalize_socket_label + + &mac.externalize.paramdefs; + + + + + + &mac.thead; + + &mac.externalize.tbody; + + + + &mac.externalize.para; + + + + <function>&mac.mpo;_externalize_socket_peer_label</function> + + + + int + &mac.mpo;_externalize_socket_peer_label + + &mac.externalize.paramdefs; + + + + + + &mac.thead; + + &mac.externalize.tbody; + + + + &mac.externalize.para; + + + + <function>&mac.mpo;_externalize_vnode_label</function> + + + + int + &mac.mpo;_externalize_vnode_label + + &mac.externalize.paramdefs; + + + + + + &mac.thead; + + &mac.externalize.tbody; + + + + &mac.externalize.para; + + + + <function>&mac.mpo;_internalize_cred_label</function> + + + + int + &mac.mpo;_internalize_cred_label + + &mac.internalize.paramdefs; + + + + + + &mac.thead; + + &mac.internalize.tbody; + + + + &mac.internalize.para; + + + + <function>&mac.mpo;_internalize_ifnet_label</function> + + + + int + &mac.mpo;_internalize_ifnet_label + + &mac.internalize.paramdefs; + + + + + + &mac.thead; + + &mac.internalize.tbody; + + + + &mac.internalize.para; + + + + <function>&mac.mpo;_internalize_pipe_label</function> + + + + int + &mac.mpo;_internalize_pipe_label + + &mac.internalize.paramdefs; + + + + + + &mac.thead; + + &mac.internalize.tbody; + + + + &mac.internalize.para; + + + + <function>&mac.mpo;_internalize_socket_label</function> + + + + int + &mac.mpo;_internalize_socket_label + + &mac.internalize.paramdefs; + + + + + + &mac.thead; + + &mac.internalize.tbody; + + + + &mac.internalize.para; + + + + <function>&mac.mpo;_internalize_vnode_label</function> + + + + int + &mac.mpo;_internalize_vnode_label + + &mac.internalize.paramdefs; + + + + + + &mac.thead; + + &mac.internalize.tbody; + + + + &mac.internalize.para; + + + + + 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 + + + <function>&mac.mpo;_associate_vnode_devfs</function> + void - &mac.mpo;_create_devfs_vnode - + &mac.mpo;_associate_vnode_devfs + + struct mount + *mp + struct label + *fslabel struct devfs_dirent - *devfs_dirent + *de struct label - *direntlabel + *delabel struct vnode *vp struct label - *vnodelabel + *vlabel + + + + + + &mac.thead; + + + + mp + Devfs mount point + + + + fslabel + Devfs file system label + (mp->mnt_fslabel) + + + + de + Devfs directory entry + + + + delabel + Policy label associated with + de + + + + vp + vnode associated with + de + + + + vlabel + Policy label associated with + vp + + + + + + Fill in the label (vlabel) for + a newly created devfs vnode based on the devfs directory + entry passed in de and its + label. + + + + <function>&mac.mpo;_associate_vnode_extattr</function> + + + + int + &mac.mpo;_associate_vnode_extattr + + struct mount + *mp + struct label + *fslabel + struct vnode + *vp + struct label + *vlabel + + + + + + &mac.thead; + + + + mp + File system mount point + + + + fslabel + File system label + + + + vp + Vnode to label + + + + vlabel + Policy label associated with + vp + + + + + + Attempt to retrieve the label for + vp from the file system extended + attributes. Upon success, the value 0 + is returned. Should extended attribute retrieval not be + supported, an accepted fallback is to copy + fslabel into + vlabel. In the event of an error, + an appropriate value for errno should + be returned. + + + + <function>&mac.mpo;_associate_vnode_singlelabel</function> + + + + void + &mac.mpo;_associate_vnode_singlelabel + + struct mount + *mp + struct label + *fslabel + struct vnode + *vp + struct label + *vlabel + + + + + + &mac.thead; + + + + mp + File system mount point + + + + fslabel + File system label + + + + vp + Vnode to label + + + + vlabel + Policy label associated with + vp + + + + + + On non-multilabel file systems, this entry point is + called to set the policy label for + vp based on the file system label, + fslabel. + + + + + <function>&mac.mpo;_create_devfs_device</function> + + + + 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. + + + + <function>&mac.mpo;_create_devfs_directory</function> + + + + 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. + + + + <function>&mac.mpo;_create_devfs_symlink</function> + + + + void + &mac.mpo;_create_devfs_symlink + + struct ucred + *cred + struct mount + *mp + struct devfs_dirent + *dd + struct label + *ddlabel + struct devfs_dirent + *de + struct label + *delabel - + &mac.thead; - + - devfs_dirent - Object; devfs directory entry + cred + Subject credential - + - direntlabel - Policy label for - devfs_dirent + mp + Devfs mount point - + - vp - Object; file system object being labeled + dd + Link destination - + - vnodelabel - Policy label to be filled in for - vp + ddlabel + Label associated with + dd + + + + de + Symlink entry + + + + delabel + Label associated with + de - - 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. + + Fill in the label (delabel) for + a newly created &man.devfs.5; symbolic link entry. - - <function>&mac.mpo;_vnode_create_from_vnode</function> - + + <function>&mac.mpo;_create_vnode_extattr</function> + - void - &mac.mpo;_vnode_create_from_vnode - + int + &mac.mpo;_create_vnode_extattr + struct ucred *cred + struct mount + *mp + struct label + *fslabel struct vnode - *parent + *dvp struct label - *parentlabel + *dlabel struct vnode - *child + *vp struct label - *childlabel + *vlabel + struct componentname + *cnp - + &mac.thead; - + cred Subject credential - + - parent - Parent vnode; the directory in which - child is being - created + mount + File system mount point - + - parentlabel - Policy label for - parent + label + File system label - + - child - New vnode + dvp + Parent directory vnode - + + + dlabel + Label associated with + dvp + + + + vp + Newly created vnode + + + + vlabel + Policy label associated with + vp + + - childlabel - Label to be filled in for - child + cnp + Component name for + vp - - 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. + + Write out the label for vp to + the appropriate extended attribute. If the write + succeeds, fill in vlabel with the + label, and return 0. Otherwise, + return an appropriate error. - + <function>&mac.mpo;_create_mount</function> 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. <function>&mac.mpo;_create_root_mount</function> 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;. - - - <function>&mac.mpo;_vnode_relabel</function> + + + <function>&mac.mpo;_relabel_vnode</function> void - &mac.mpo;_vnode_relabel + &mac.mpo;_relabel_vnode 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. - - - <function>&mac.mpo;_stdcreatevnode_ea</function> - + + + <function>&mac.mpo;_setlabel_vnode_extattr</function> + 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. - - - - <function>&mac.mpo;_update_devfsdirent</function> - - - 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. - - - - <function>&mac.mpo;_update_procfsvnode</function> - - - - void - &mac.mpo;_update_procfsvnode - - struct vnode - *vp - struct label - *vnodelabel + &mac.mpo;_setlabel_vnode_extattr + 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. - - - - <function>&mac.mpo;_update_vnode_from_extattr</function> - - - - 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. - - - - <function>&mac.mpo;_update_from_externalized</function> - - - - int - &mac.mpo;_update_from_externalized - - struct vnode - *vp + *vlabel struct label - *vnodelabel - struct mac - *extmac + *intlabel - + &mac.thead; - + + + cred + Subject credential + + vp - Object; vnode - Locked + Vnode for which the label is being + written - + - vnodelabel - Policy label for + vlabel + Policy label associated with vp - + - extmac - Externalized MAC policy label + intlabel + Label to write out - - 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. + + Write out the policy from + intlabel to an extended + attribute. This is called from + vop_stdcreatevnode_ea. - - - <function>&mac.mpo;_update_vnode_from_mount</function> - + + + <function>&mac.mpo;_update_devfsdirent</function> void - &mac.mpo;_update_vnode_from_mount + &mac.mpo;_update_devfsdirent + struct devfs_dirent + *devfs_dirent + struct label + *direntlabel struct vnode *vp struct label *vnodelabel - struct mount - *mp - struct label - *mountlabel &mac.thead; - vp - Object; vnode - Locked + devfs_dirent + Object; devfs directory entry - vnodelabel + direntlabel Policy label for - vp + devfs_dirent to be + updated. - mp - Mount point where vp - resides + vp + Parent vnode + Locked - fslabel - Policy label for the file system where - vp resides. + vnodelabel + Policy label for + vp - 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. + 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. IPC Object Labeling Event Operations + <function>&mac.mpo;_create_mbuf_from_socket</function> 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 + or message is generated by the socket and stored in the passed mbuf. + + + <function>&mac.mpo;_create_pipe</function> + + + + void + &mac.mpo;_create_pipe + + struct ucred + *cred + struct pipe + *pipe + struct label + *pipelabel + + + + + + &mac.thead; + + + + cred + Subject credential + + + + pipe + Pipe + + + + pipelabel + Policy label associated with + pipe + + + + + + Set the label on a newly created pipe from the passed + subject credential. This call is made when a new pipe is + created. + <function>&mac.mpo;_create_socket</function> 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. - - + + <function>&mac.mpo;_create_socket_from_socket</function> - + 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; + Listening socket - + oldsocketlabel - Label for + Policy label associated with oldsocket - + newsocket - Object; child socket; incoming connection + New socket - + newsocketlabel - Label to be filled in for - newsocket + Policy label associated with + newsocketlabel - - 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. + + Label a socket, newsocket, + newly &man.accept.2;ed, based on the &man.listen.2; + socket, oldsocket. - - - <function>&mac.mpo;_socket_relabel</function> + + + <function>&mac.mpo;_relabel_pipe</function> + + + + void + &mac.mpo;_relabel_pipe + + struct ucred + *cred + struct pipe + *pipe + struct label + *oldlabel + struct label + *newlabel + + + + + + &mac.thead; + + + + cred + Subject credential + + + + pipe + Pipe + + + + oldlabel + Current policy label associated with + pipe + + + + newlabel + Policy label update to apply to + pipe + + + + + + Apply a new label, newlabel, to + pipe. + + + + <function>&mac.mpo;_relabel_socket</function> void - &mac.mpo;_socket_relabel + &mac.mpo;_relabel_socket 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. <function>&mac.mpo;_set_socket_peer_from_mbuf</function> 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. <function>&mac.mpo;_set_socket_peer_from_socket</function> 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 <function>&mac.mpo;_create_bpfdesc</function> 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. <function>&mac.mpo;_create_ifnet</function> 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. <function>&mac.mpo;_create_ipq</function> 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. <function>&mac.mpo;_create_datagram_from_ipq</function> 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. <function>&mac.mpo;_create_fragment</function> 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. <function>&mac.mpo;_create_mbuf_from_mbuf</function> 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. <function>&mac.mpo;_create_mbuf_linklayer</function> 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. <function>&mac.mpo;_create_mbuf_from_bpfdesc</function> 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. <function>&mac.mpo;_create_mbuf_from_ifnet</function> 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. <function>&mac.mpo;_create_mbuf_multicast_encap</function> 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. <function>&mac.mpo;_create_mbuf_netlayer</function> 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. <function>&mac.mpo;_fragment_match</function> 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. - <function>&mac.mpo;_ifnet_relabel</function> + <function>&mac.mpo;_relabel_ifnet</function> void - &mac.mpo;_ifnet_relabel + &mac.mpo;_relabel_ifnet 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. <function>&mac.mpo;_update_ipq</function> 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 <function>&mac.mpo;_create_cred</function> 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 + &man.crcopy.9; is invoked on a newly created struct ucred. This call should not be confused with a process forking or creation event. <function>&mac.mpo;_execve_transition</function> 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. <function>&mac.mpo;_execve_will_transition</function> 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. <function>&mac.mpo;_create_proc0</function> 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. <function>&mac.mpo;_create_proc1</function> 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. + of all user processes. - - <function>&mac.mpo;_cred_relabel</function> + + <function>&mac.mpo;_relabel_cred</function> void - &mac.mpo;_cred_relabel + &mac.mpo;_relabel_cred 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 + return 0 to permit the operation, or 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 - - - 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. <function>&mac.mpo;_check_bpfdesc_receive</function> int - &mac.mpo;_check_bpfdesc_receive - - struct bpf_d - *bpf_d - struct label - *bpflabel - struct ifnet - *ifnet - struct label - *ifnetlabel + &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. + + + + <function>&mac.mpo;_check_kenv_dump</function> + + + + int + &mac.mpo;_check_kenv_dump + + struct ucred + *cred + + + + + + &mac.thead; + + + + cred + Subject credential + + + + + + Determine whether the subject should be allowed to + retrieve the kernel environment (see &man.kenv.2;). + + + + <function>&mac.mpo;_check_kenv_get</function> + + + + int + &mac.mpo;_check_kenv_get + + struct ucred + *cred + char *name + + + + + + &mac.thead; + + + + cred + Subject credential + + + + name + Kernel environment variable name + + + + + + Determine whether the subject should be allowed to + retrieve the value of the specified kernel environment + variable. + + + + <function>&mac.mpo;_check_kenv_set</function> + + + + int + &mac.mpo;_check_kenv_set + + struct ucred + *cred + char *name - + &mac.thead; - + - bpf_d - Subject; BPF descriptor + cred + Subject credential - + - bpflabel - Policy label for - bpf_d + name + Kernel environment variable name - + + + + + Determine whether the subject should be allowed to set + the specified kernel environment variable. + + + + <function>&mac.mpo;_check_kenv_unset</function> + + + + int + &mac.mpo;_check_kenv_unset + + struct ucred + *cred + char *name + + + + + + &mac.thead; + + - ifnet - Object; network interface + cred + Subject credential - ifnetlabel - Policy label for - ifnet + name + Kernel environment variable name - - 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. + + Determine whether the subject should be allowed to unset + the specified kernel environment variable. - - - <function>&mac.mpo;_check_socket_bind</function> - + + + <function>&mac.mpo;_check_kld_load</function> + int - &mac.mpo;_check_socket_bind - + &mac.mpo;_check_kld_load + struct ucred *cred - struct socket - *socket + struct vnode + *vp struct label - *socketlabel - struct sockaddr - *sockaddr + *vlabel - + &mac.thead; - + cred Subject credential - + - socket - Socket to be bound + vp + Kernel module vnode - + - socketlabel - Policy label for - socket + vlabel + Label associated with + vp - + + + + + Determine whether the subject should be allowed to load + the specified module file. + + + + <function>&mac.mpo;_check_kld_stat</function> + + + + int + &mac.mpo;_check_kld_stat + + struct ucred + *cred + + + + + + &mac.thead; + + - sockaddr - Address of - socket + cred + Subject credential - + + Determine whether the subject should be allowed to + retrieve a list of loaded kernel module files and associated + statistics. - - - - <function>&mac.mpo;_check_socket_connect</function> - + + + <function>&mac.mpo;_check_kld_unload</function> + + + + int + &mac.mpo;_check_kld_unload + + struct ucred + *cred + + + + + + &mac.thead; + + + + cred + Subject credential + + + + + + Determine whether the subject should be allowed to + unload a kernel module. + + + + <function>&mac.mpo;_check_pipe_ioctl</function> + int - &mac.mpo;_check_socket_connect - + &mac.mpo;_check_pipe_ioctl + struct ucred *cred - struct socket - *socket + struct pipe + *pipe struct label - *socketlabel - struct sockaddr - *sockaddr + *pipelabel + unsigned long + cmd + void *data - + &mac.thead; - + cred Subject credential - + - socket - Socket to be connected + pipe + Pipe - + - socketlabel - Policy label for - socket + pipelabel + Policy label associated with + pipe - + - sockaddr - Address of - socket + cmd + &man.ioctl.2; command - + + + data + &man.ioctl.2; data + + - - 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. + + Determine whether the subject should be allowed to make + the specified &man.ioctl.2; call. - - - <function>&mac.mpo;_check_cred_visible</function> - + + + <function>&mac.mpo;_check_pipe_poll</function> + int - &mac.mpo;_check_cred_visible - - struct ucred - *u1 + &mac.mpo;_check_pipe_poll + struct ucred - *u2 + *cred + struct pipe + *pipe + struct label + *pipelabel - + &mac.thead; - + - u1 + cred Subject credential - + - u2 - Object credential + pipe + Pipe + + + + pipelabel + Policy label associated with + pipe - - 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. - - - - <function>&mac.mpo;_check_socket_visible</function> - + + Determine whether the subject should be allowed to poll + pipe. + + + + <function>&mac.mpo;_check_pipe_read</function> + int - &mac.mpo;_check_socket_visible - + &mac.mpo;_check_pipe_read + struct ucred *cred - struct socket - *socket + struct pipe + *pipe struct label - *socketlabel + *pipelabel - + &mac.thead; - + cred Subject credential - + - socket - Object; socket + pipe + Pipe - + - socketlabel - Policy label for - socket + pipelabel + Policy label associated with + pipe - + + Determine whether the subject should be allowed read + access to pipe. - - - <function>&mac.mpo;_check_ifnet_relabel</function> - + + + <function>&mac.mpo;_check_pipe_relabel</function> + int - &mac.mpo;_check_ifnet_relabel - + &mac.mpo;_check_pipe_relabel + struct ucred *cred - struct ifnet - *ifnet + struct pipe + *pipe struct label - *ifnetlabel + *pipelabel struct label *newlabel - + &mac.thead; - + cred Subject credential - + - ifnet - Object; network interface + pipe + Pipe - + - ifnetlabel - Existing policy label for - ifnet + pipelabel + Current policy label associated with + pipe - + newlabel - Policy label update to later be applied to - ifnet + Label update to + pipelabel - - Determine whether the subject credential can relabel the - passed network interface to the passed label update. + + Determine whether the subject should be allowed to + relabel pipe. - - - <function>&mac.mpo;_check_socket_relabel</function> - + + + <function>&mac.mpo;_check_pipe_stat</function> + int - &mac.mpo;_check_socket_relabel - + &mac.mpo;_check_pipe_stat + struct ucred *cred - struct socket - *socket - struct label - *socketlabel + struct pipe + *pipe struct label - *newlabel + *pipelabel - + &mac.thead; - + cred Subject credential - - - socket - Object; socket - - + - socketlabel - Existing policy label for - socket + pipe + Pipe - + - newlabel - Label update to later be applied to - socketlabel + pipelabel + Policy label associated with + pipe - - Determine whether the subject credential can relabel the - passed socket to the passed label update. + + Determine whether the subject should be allowed to + retrieve statistics related to + pipe. - - - <function>&mac.mpo;_check_cred_relabel</function> - + + + <function>&mac.mpo;_check_pipe_write</function> + int - &mac.mpo;_check_cred_relabel - + &mac.mpo;_check_pipe_write + struct ucred *cred + struct pipe + *pipe struct label - *newlabel + *pipelabel - + &mac.thead; - + cred Subject credential - + - newlabel - Label update to later be applied to - cred + pipe + Pipe + + + + pipelabel + Policy label associated with + pipe - - Determine whether the subject credential can relabel - itself to the passed label update. + + Determine whether the subject should be allowed to write + to pipe. - - - <function>&mac.mpo;_check_vnode_relabel</function> + + + <function>&mac.mpo;_check_socket_bind</function> int - &mac.mpo;_check_vnode_relabel + &mac.mpo;_check_socket_bind struct ucred *cred - struct vnode - *vp - struct label - *vnodelabel + struct socket + *socket struct label - *newlabel + *socketlabel + struct sockaddr + *sockaddr &mac.thead; cred Subject credential - Immutable - vp - Object; vnode - Locked + socket + Socket to be bound - vnodelabel - Existing policy label for - vp + socketlabel + Policy label for + socket - newlabel - Policy label update to later be applied to - vp + sockaddr + Address of + socket - Determine whether the subject credential can relabel the - passed vnode to the passed label update. - - <function>&mac.mpo;_check_mount_stat</function> + + + <function>&mac.mpo;_check_socket_connect</function> - int &mac.mpo;_check_mount_stat + int + &mac.mpo;_check_socket_connect struct ucred *cred - struct mount - *mp + struct socket + *socket struct label - *mountlabel + *socketlabel + struct sockaddr + *sockaddr &mac.thead; cred Subject credential - mp - Object; file system mount + socket + Socket to be connected - mountlabel + socketlabel Policy label for - mp + socket - + + + sockaddr + Address of + socket + + - - Determine whether the subject credential can see the - results of a statfs performed on the file system. Return + 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 - 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. + failure: EACCES for label mismatches, + EPERM for lack of privilege. - - - <function>&mac.mpo;_check_proc_debug</function> - + + + <function>&mac.mpo;_check_socket_receive</function> + int - &mac.mpo;_check_proc_debug - + &mac.mpo;_check_socket_receive + struct ucred *cred - struct proc - *proc + struct socket + *so + struct label + *socketlabel - + &mac.thead; - + cred Subject credential - Immutable - + - proc - Object; process + so + Socket + + + + socketlabel + Policy label associated with + so - - 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. + + Determine whether the subject should be allowed to + receive information from the socket + so. - - - <function>&mac.mpo;_check_vnode_access</function> - + + + <function>&mac.mpo;_check_socket_send</function> + int - &mac.mpo;_check_vnode_access - + &mac.mpo;_check_socket_send + struct ucred *cred - struct vnode - *vp + struct socket + *so struct label - *label - int flags + *socketlabel - + &mac.thead; - + cred Subject credential - - - vp - Object; vnode - - + - label - Policy label for - vp + so + Socket - + - flags - &man.access.2; flags + socketlabel + Policy label associated with + so - - 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. + + Determine whether the subject should be allowed to send + information across the socket + so. - - <function>&mac.mpo;_check_vnode_chdir</function> + + <function>&mac.mpo;_check_cred_visible</function> int - &mac.mpo;_check_vnode_chdir + &mac.mpo;_check_cred_visible struct ucred - *cred - struct vnode - *dvp - struct label - *dlabel + *u1 + struct ucred + *u2 &mac.thead; - cred + u1 Subject credential - dvp - Object; vnode to &man.chdir.2; into - - - - dlabel - Policy label for - dvp + u2 + Object credential - Determine whether the subject credential can change the - process working directory to the passed vnode. Return + 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 mismatch, - or EPERM for lack of - privilege. + 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. - - <function>&mac.mpo;_check_vnode_create</function> + + <function>&mac.mpo;_check_socket_visible</function> int - &mac.mpo;_check_vnode_create + &mac.mpo;_check_socket_visible struct ucred *cred - struct vnode - *dvp + struct socket + *socket struct label - *dlabel - struct componentname - *cnp - struct vattr - *vap + *socketlabel &mac.thead; cred Subject credential - dvp - Object; vnode + socket + Object; socket - dlabel + socketlabel Policy label for - dvp - - - - cnp - Component name for - dvp - - - - vap - vnode attributes for vap + socket - 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. - - <function>&mac.mpo;_check_vnode_delete</function> + + <function>&mac.mpo;_check_ifnet_relabel</function> int - &mac.mpo;_check_vnode_delete + &mac.mpo;_check_ifnet_relabel struct ucred *cred - struct vnode - *dvp + struct ifnet + *ifnet struct label - *dlabel - struct vnode - *vp - void *label - struct componentname - *cnp + *ifnetlabel + struct label + *newlabel &mac.thead; cred Subject credential - dvp - Parent directory vnode - - - - dlabel - Policy label for - dvp - - - - vp - Object; vnode to delete + ifnet + Object; network interface - label - Policy label for - vp + ifnetlabel + Existing policy label for + ifnet - cnp - Component name for - vp + newlabel + Policy label update to later be applied to + ifnet - 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. + Determine whether the subject credential can relabel the + passed network interface to the passed label update. - - <function>&mac.mpo;_check_vnode_deleteacl</function> + + <function>&mac.mpo;_check_socket_relabel</function> int - &mac.mpo;_check_vnode_deleteacl + &mac.mpo;_check_socket_relabel - struct ucred *cred - struct vnode *vp - struct label *label - acl_type_t type + struct ucred + *cred + struct socket + *socket + struct label + *socketlabel + struct label + *newlabel &mac.thead; cred Subject credential - Immutable - vp - Object; vnode - Locked + socket + Object; socket - label - Policy label for - vp + socketlabel + Existing policy label for + socket - type - ACL type + newlabel + Label update to later be applied to + socketlabel - 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. + Determine whether the subject credential can relabel the + passed socket to the passed label update. - - <function>&mac.mpo;_check_vnode_exec</function> + + <function>&mac.mpo;_check_cred_relabel</function> int - &mac.mpo;_check_vnode_exec + &mac.mpo;_check_cred_relabel struct ucred *cred - struct vnode - *vp struct label - *label + *newlabel &mac.thead; cred Subject credential - vp - Object; vnode to execute - - - - label - Policy label for - vp + newlabel + Label update to later be applied to + cred - Determine whether the subject credential can execute the - passed vnode. Determination of execute privilege is made - separately 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. + Determine whether the subject credential can relabel + itself to the passed label update. - - - <function>&mac.mpo;_check_vnode_getacl</function> + + + + <function>&mac.mpo;_check_vnode_relabel</function> int - &mac.mpo;_check_vnode_getacl + &mac.mpo;_check_vnode_relabel struct ucred *cred struct vnode *vp struct label - *label - acl_type_t - type + *vnodelabel + struct label + *newlabel &mac.thead; cred Subject credential + Immutable vp Object; vnode + Locked - label - Policy label for + vnodelabel + Existing policy label for vp - type - ACL type + newlabel + Policy label update to later be applied to + vp - 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. + Determine whether the subject credential can relabel the + passed vnode to the passed label update. - - <function>&mac.mpo;_check_vnode_getextattr</function> + + <function>&mac.mpo;_check_mount_stat</function> - int - &mac.mpo;_check_vnode_getextattr + int &mac.mpo;_check_mount_stat struct ucred *cred - struct vnode - *vp + struct mount + *mp struct label - *label - int - attrnamespace - const char - *name - struct uio - *uio + *mountlabel &mac.thead; cred Subject credential - vp - Object; vnode + mp + Object; file system mount - label + mountlabel Policy label for - vp - - - - attrnamespace - Extended attribute namespace - - - - name - Extended attribute name - - - - uio - I/O structure pointer; see &man.uio.9; + mp - 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 + + 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 mismatch, - or EPERM for lack of - privilege. + 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. - - <function>&mac.mpo;_check_socket_listen</function> + + <function>&mac.mpo;_check_proc_debug</function> int - &mac.mpo;_check_socket_listen + &mac.mpo;_check_proc_debug struct ucred *cred - struct socket - *socket - struct label - *socketlabel + struct proc + *proc &mac.thead; cred Subject credential + Immutable - socket - Object; socket - - - - socketlabel - Policy label for - socket + proc + Object; process - Determine whether the subject credential can listen on - the passed socket. Return 0 for + 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, or EPERM for lack of - privilege. + 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. - - <function>&mac.mpo;_check_vnode_lookup</function> + + <function>&mac.mpo;_check_vnode_access</function> int - &mac.mpo;_check_vnode_lookup + &mac.mpo;_check_vnode_access struct ucred - *cred + *cred struct vnode - *dvp + *vp struct label - *dlabel - struct componentname - *cnp + *label + int flags &mac.thead; cred Subject credential - dvp + vp Object; vnode - dlabel + label Policy label for - dvp + vp - cnp - Component name being looked up + flags + &man.access.2; flags - Determine whether the subject credential can perform a - lookup in the passed directory vnode for the passed name. + 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 mismatch, + failure: EACCES for label mismatches or EPERM for lack of privilege. - - <function>&mac.mpo;_check_vnode_open</function> + + <function>&mac.mpo;_check_vnode_chdir</function> int - &mac.mpo;_check_vnode_open + &mac.mpo;_check_vnode_chdir struct ucred *cred struct vnode - *vp + *dvp struct label - *label - mode_t - acc_mode + *dlabel &mac.thead; cred Subject credential - vp - Object; vnode + dvp + Object; vnode to &man.chdir.2; into - label + dlabel Policy label for - vp - - - - acc_mode - &man.open.2; access mode + dvp - 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. + 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. - - - <function>&mac.mpo;_check_vnode_readdir</function> - + + + <function>&mac.mpo;_check_vnode_chroot</function> + int - &mac.mpo;_check_vnode_readdir - + &mac.mpo;_check_vnode_chroot + struct ucred - *cred + *cred struct vnode - *dvp + *dvp struct label - *dlabel + *dlabel - + &mac.thead; - + cred Subject credential - + dvp - Object; directory vnode + Directory vnode - + dlabel - Policy label for + Policy label associated with 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. + + Determine whether the subject should be allowed to + &man.chroot.2; into the specified directory + (dvp). - - <function>&mac.mpo;_check_vnode_readlink</function> + + <function>&mac.mpo;_check_vnode_create</function> int - &mac.mpo;_check_vnode_readlink + &mac.mpo;_check_vnode_create struct ucred *cred struct vnode - *vp + *dvp struct label - *label + *dlabel + struct componentname + *cnp + struct vattr + *vap &mac.thead; cred Subject credential - vp + dvp Object; vnode - label + dlabel Policy label for - vp + dvp + + + + cnp + Component name for + dvp + + + + vap + vnode attributes for vap - 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. + 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. - - <function>&mac.mpo;_check_rename_from_vnode</function> + + <function>&mac.mpo;_check_vnode_delete</function> int - &mac.mpo;_check_rename_from_vnode + &mac.mpo;_check_vnode_delete struct ucred *cred struct vnode *dvp struct label *dlabel struct vnode *vp - struct label - *label + void *label struct componentname *cnp &mac.thead; cred Subject credential dvp - Directory vnode + Parent directory vnode dlabel Policy label for dvp vp - Object; vnode + Object; vnode to delete label Policy label for vp - cnp - Pathname + Component name for + vp - 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. + 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. - - <function>&mac.mpo;_check_rename_to_vnode</function> + + <function>&mac.mpo;_check_vnode_deleteacl</function> int - &mac.mpo;_check_rename_to_vnode + &mac.mpo;_check_vnode_deleteacl - struct ucred - *cred - struct vnode - *dvp - struct label - *dlabel - struct vnode - *vp - struct label - *label - int samedir - struct componentname - *cnp + struct ucred *cred + struct vnode *vp + struct label *label + acl_type_t type &mac.thead; cred Subject credential - - - - dvp - Directory vnode - - - - dlabel - Policy label for dvp + Immutable vp Object; vnode + Locked label Policy label for vp - cnp - Pathname + type + ACL type - 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 + 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. - - <function>&mac.mpo;_check_vnode_revoke</function> + + <function>&mac.mpo;_check_vnode_exec</function> int - &mac.mpo;_check_vnode_revoke + &mac.mpo;_check_vnode_exec struct ucred *cred struct vnode *vp struct label *label &mac.thead; cred Subject credential vp - Object; vnode + Object; vnode to execute 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 + 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. - - <function>&mac.mpo;_check_vnode_setacl</function> + + <function>&mac.mpo;_check_vnode_getacl</function> int - &mac.mpo;_check_vnode_setacl + &mac.mpo;_check_vnode_getacl 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 + 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. - - <function>&mac.mpo;_check_vnode_setextattr</function> + + <function>&mac.mpo;_check_vnode_getextattr</function> int - &mac.mpo;_check_vnode_setextattr + &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 + 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 + 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. - - - <function>&mac.mpo;_check_vnode_setflags</function> - + + + <function>&mac.mpo;_check_vnode_link</function> + int - &mac.mpo;_check_vnode_setflags - + &mac.mpo;_check_vnode_link + struct ucred *cred + struct vnode + *dvp + struct label + *dlabel struct vnode *vp struct label *label - u_long flags + struct componentname + *cnp - + &mac.thead; - + cred Subject credential - + + + dvp + Directory vnode + + + + dlabel + Policy label associated with + dvp + + vp - Object; vnode + Link destination vnode - + label - Policy label for + Policy label associated with vp - + - flags - File flags; see &man.chflags.2; + cnp + Component name for the link being created - - 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. + + Determine whether the subject should be allowed to + create a link to the vnode vp with + the name specified by cnp. - - - <function>&mac.mpo;_check_vnode_setmode</function> - + + + <function>&mac.mpo;_check_vnode_mmap</function> + int - &mac.mpo;_check_vnode_setmode - + &mac.mpo;_check_vnode_mmap + struct ucred *cred struct vnode *vp struct label *label - mode_t mode + int prot - + &mac.thead; - + cred Subject credential - + vp - Object; vnode + Vnode to map - + label - Policy label for vp + Policy label associated with + vp - + - mode - File mode; see &man.chmod.2; + prot + Mmap protections (see &man.mmap.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. + + + + Determine whether the subject should be allowed to map + the vnode vp with the protections + specified in prot. - - - <function>&mac.mpo;_check_vnode_setowner</function> - + + + <function>&mac.mpo;_check_vnode_mmap_downgrade</function> + - int - &mac.mpo;_check_vnode_setowner - + void + &mac.mpo;_check_vnode_mmap_downgrade + struct ucred *cred struct vnode *vp struct label *label - uid_t uid - gid_t gid + int *prot - + &mac.thead; - + cred - Subject credential + See + . - + vp - Object; vnode - + label - Policy label for vp - - - - uid - User ID - + - gid - Group ID + prot + Mmap protections to be downgraded - - 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. + + Downgrade the mmap protections based on the subject and + object labels. - - - <function>&mac.mpo;_check_vnode_setutimes</function> - + + + <function>&mac.mpo;_check_vnode_mprotect</function> + int - &mac.mpo;_check_vnode_setutimes - + &mac.mpo;_check_vnode_mprotect + struct ucred - *cred + *cred struct vnode - *vp + *vp struct label - *label - struct timespec - atime - struct timespec - mtime + *label + int prot - + &mac.thead; - + cred Subject credential - + vp - Object; vp - - - - label - Policy label for - vp - - - - atime - Access time; see &man.utimes.2; + Mapped vnode - + - mtime - Modification time; see &man.utimes.2; + prot + Memory protections - - 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. + + Determine whether the subject should be allowed to + set the specified memory protections on memory mapped from + the vnode vp. - - - <function>&mac.mpo;_check_proc_sched</function> - + + + <function>&mac.mpo;_check_vnode_poll</function> + int - &mac.mpo;_check_proc_sched - + &mac.mpo;_check_vnode_poll + struct ucred - *ucred - struct proc - *proc + *active_cred + struct ucred + *file_cred + struct vnode + *vp + struct label + *label - + &mac.thead; - + - cred + active_cred Subject credential - + - proc - Object; process + file_cred + Credential associated with the struct + file + + + + vp + Polled vnode + + + + label + Policy label associated with + vp - - 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. + + Determine whether the subject should be allowed to poll + the vnode vp. - - - <function>&mac.mpo;_check_proc_signal</function> - + + + <function>&mac.mpo;_check_vnode_rename_from</function> + int - &mac.mpo;_check_proc_signal - + &mac.mpo;_vnode_rename_from + struct ucred *cred - struct proc - *proc - int signal + struct vnode + *dvp + struct label + *dlabel + struct vnode + *vp + struct label + *label + struct componentname + *cnp - + &mac.thead; - + cred Subject credential - + - proc - Object; process + dvp + Directory vnode - + - signal - Signal; see &man.kill.2; + dlabel + Policy label associated with + dvp + + + + vp + Vnode to be renamed + + + + label + Policy label asociated with + vp + + + + cnp + Component name for + vp - - 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. + + Determine whether the subject should be allowed to + rename the vnode vp to something + else. - - - <function>&mac.mpo;_check_vnode_stat</function> - + + + <function>&mac.mpo;_check_vnode_rename_to</function> + int - &mac.mpo;_check_vnode_stat - + &mac.mpo;_check_vnode_rename_to + 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 associated with + dvp + + vp - Object; vnode + Overwritten vnode - + label - Policy label for + Policy label associated with vp + + + samedir + Boolean; 1 if the source and + destination directories are the same + + + + cnp + Destination component name + - - 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. + + Determine whether the subject should be allowed to + rename to the vnode vp, into the + directory dvp, or to the name + represented by cnp. If there is no + existing file to overwrite, vp and + label will be NULL. - - <function>&mac.mpo;_check_ifnet_transmit</function> + + <function>&mac.mpo;_check_socket_listen</function> int - &mac.mpo;_check_ifnet_transmit + &mac.mpo;_check_socket_listen struct ucred *cred - struct ifnet - *ifnet - struct label - *ifnetlabel - struct mbuf - *mbuf + struct socket + *socket struct label - *mbuflabel + *socketlabel &mac.thead; cred Subject credential - ifnet - Network interface - - - - ifnetlabel - Policy label for - ifnet - - - - mbuf - Object; mbuf to be sent + socket + Object; socket - mbuflabel + socketlabel Policy label for - mbuf + socket - Determine whether the network interface can transmit the - passed mbuf. Return 0 for + 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. - - <function>&mac.mpo;_check_socket_receive</function> + + <function>&mac.mpo;_check_vnode_lookup</function> int - &mac.mpo;_check_socket_receive + &mac.mpo;_check_vnode_lookup struct ucred - *cred - struct ifnet - *ifnet - struct label - *ifnetlabel - struct mbuf - *mbuf + *cred + struct vnode + *dvp struct label - *mbuflabel + *dlabel + struct componentname + *cnp &mac.thead; cred Subject credential - ifnet - Network interface + dvp + Object; vnode - ifnetlabel + dlabel Policy label for - ifnet - - - - mbuf - Object; mbuf to be received + dvp - mbuflabel - Policy label for - mbuf + cnp + Component name being looked up - Determine whether the socket may receive the datagram - stored in the passed mbuf header. Return - 0 for success, or an + 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 - failures: EACCES for label mismatch, + failure: EACCES for label mismatch, or EPERM for lack of privilege. - - <function>&mac.mpo;_check_socket_visible</function> + + <function>&mac.mpo;_check_vnode_open</function> int - &mac.mpo;_check_socket_visible + &mac.mpo;_check_vnode_open struct ucred *cred - struct socket - *so + struct vnode + *vp struct label - *socketlabel + *label + int + acc_mode &mac.thead; cred Subject credential - Immutable - so - Object; socket + vp + Object; vnode - socketlabel + label 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 separate 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). - - - <function>&mac.mpo;_init_bpfdesc</function> - - - - void - &mac.mpo;_init_bpfdesc - - struct bpf_d - *bpf_d - struct label - *label - - - - - - &mac.thead; - - - - bpf_d - Object; bpf descriptor + vp - label - New label to apply + acc_mode + &man.open.2; access mode - Initialize the label on a newly instantiated bpfdesc (BPF - descriptor) + 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. - - <function>&mac.mpo;_init_devfsdirent</function> + + <function>&mac.mpo;_check_vnode_readdir</function> - void - &mac.mpo;_init_devfsdirent + int + &mac.mpo;_check_vnode_readdir - struct devfs_dirent - *devfs_dirent + struct ucred + *cred + struct vnode + *dvp struct label - *label + *dlabel &mac.thead; - devfs_dirent - Object; devfs directory entry + cred + Subject credential - label - New label to apply + dvp + Object; directory vnode + + + + dlabel + Policy label for + dvp - Initialize the label on a newly instantiated devfs - entry. + 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. - - <function>&mac.mpo;_init_ifnet</function> + + <function>&mac.mpo;_check_vnode_readlink</function> - void - &mac.mpo;_init_ifnet + int + &mac.mpo;_check_vnode_readlink - struct ifnet - *ifnet + struct ucred + *cred + struct vnode + *vp struct label *label &mac.thead; - ifnet - Object; network interface + cred + Subject credential + + + + vp + Object; vnode label - New label to apply + Policy label for + vp - Initialize the label on a newly instantiated network - interface. + 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. - - <function>&mac.mpo;_init_ipq</function> + + <function>&mac.mpo;_check_vnode_revoke</function> - void - &mac.mpo;_init_ipq + int + &mac.mpo;_check_vnode_revoke - struct ipq - *ipq + struct ucred + *cred + struct vnode + *vp struct label *label &mac.thead; - ipq - Object; IP reassembly queue + cred + Subject credential + + + + vp + Object; vnode label - New label to apply + Policy label for + vp - Initialize the label on a newly instantiated IP fragment - reassembly queue. + 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. - - <function>&mac.mpo;_init_mbuf</function> + + <function>&mac.mpo;_check_vnode_setacl</function> - void - &mac.mpo;_init_mbuf + int + &mac.mpo;_check_vnode_setacl - struct mbuf - *mbuf - int how + struct ucred + *cred + struct vnode + *vp struct label *label + acl_type_t + type + struct acl + *acl &mac.thead; - mbuf - Object; mbuf + cred + Subject credential - how - Blocking/non-blocking &man.malloc.9; see - below + vp + Object; vnode label - Policy label to initialize + Policy label for + vp + + + + type + ACL type + + + + acl + ACL + - 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. + 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. - - <function>&mac.mpo;_init_mount</function> + + <function>&mac.mpo;_check_vnode_setextattr</function> - void - &mac.mpo;_init_mount + int + &mac.mpo;_check_vnode_setextattr - struct mount - *mount - struct label - *mntlabel + struct ucred + *cred + struct vnode + *vp struct label - *fslabel + *label + int + attrnamespace + const char + *name + struct uio + *uio - &mac.thead; - mount - Object; file system mount point + cred + Subject credential - mntlabel - Policy label to be initialized for the mount - itself + vp + Object; vnode - fslabel - Policy label to be initialized for the file - system + label + Policy label for vp + + + + attrnamespace + Extended attribute namespace + + + + name + Extended attribute name + + + + uio + I/O structure pointer; see &man.uio.9; - Initialize the labels on a newly instantiated mount - point. + 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. - - <function>&mac.mpo;_init_socket</function> + + <function>&mac.mpo;_check_vnode_setflags</function> - void - &mac.mpo;_init_socket + int + &mac.mpo;_check_vnode_setflags - struct socket - *socket + struct ucred + *cred + struct vnode + *vp struct label *label - struct label - *peerlabel + u_long flags &mac.thead; - socket - Object; socket + cred + Subject credential + + + + vp + Object; vnode label - New label to apply to the socket + Policy label for + vp - peerlabel - New label to apply to the socket's peer + flags + File flags; see &man.chflags.2; - Initialize the labels on a newly instantiated - socket. + 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. - - <function>&mac.mpo;_init_cred</function> + + <function>&mac.mpo;_check_vnode_setmode</function> - void - &mac.mpo;_init_cred + int + &mac.mpo;_check_vnode_setmode struct ucred *cred + struct vnode + *vp struct label *label + mode_t mode &mac.thead; cred - Subject; user credetial + Subject credential + + + + vp + Object; vnode label - New label + Policy label for vp + + + + mode + File mode; see &man.chmod.2; - Initialize the labels on a newly instantiated subject. + 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. - - <function>&mac.mpo;_init_temp</function> + + <function>&mac.mpo;_check_vnode_setowner</function> - void - &mac.mpo;_init_temp + 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 - Temporary label + Policy label for vp + + + + uid + User ID + + + + gid + Group ID - Initialize a newly instantiated temporary label; - temporary labels are frequently used to hold label update - requests. + 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. - - <function>&mac.mpo;_init_vnode</function> + + <function>&mac.mpo;_check_vnode_setutimes</function> - void - &mac.mpo;_init_vnode + int + &mac.mpo;_check_vnode_setutimes + struct ucred + *cred struct vnode - *vp + *vp struct label - *label + *label + struct timespec + atime + struct timespec + mtime &mac.thead; + + cred + Subject credential + + vp - Object; file system object + Object; vp label - New label to initialize + Policy label for + vp + + + + atime + Access time; see &man.utimes.2; + + + + mtime + Modification time; see &man.utimes.2; - Initialize the label on a newly instantiated vnode. + 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. - - <function>&mac.mpo;_destroy_bpfdesc</function> + + <function>&mac.mpo;_check_proc_sched</function> - void - &mac.mpo;_destroy_bpfdesc + int + &mac.mpo;_check_proc_sched - struct bpf_d - *bpf_d - struct label - *label + struct ucred + *ucred + struct proc + *proc &mac.thead; - bpf_d - Object; bpf descriptor + cred + Subject credential - label - Label being destroyed + proc + Object; process - 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. + 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. - - <function>&mac.mpo;_destroy_devfsdirent</function> + + <function>&mac.mpo;_check_proc_signal</function> - void - &mac.mpo;_destroy_devfsdirent + int + &mac.mpo;_check_proc_signal - struct devfs_dirent - *devfs_dirent - struct label - *label + struct ucred + *cred + struct proc + *proc + int signal &mac.thead; - devfs_dirent - Object; devfs directory entry + cred + Subject credential - label - Label being destroyed + proc + Object; process + + + + signal + Signal; see &man.kill.2; - 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. + 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. - - <function>&mac.mpo;_destroy_ifnet</function> + + <function>&mac.mpo;_check_vnode_stat</function> - void - &mac.mpo;_destroy_ifnet + int + &mac.mpo;_check_vnode_stat - struct ifnet - *ifnet + struct ucred + *cred + struct vnode + *vp struct label *label &mac.thead; - ifnet - Object; network interface + cred + Subject credential + + + + vp + Object; vnode label - Label being destroyed + Policy label for + vp - 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. + 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. - - <function>&mac.mpo;_destroy_ipq</function> + + <function>&mac.mpo;_check_ifnet_transmit</function> - void - &mac.mpo;_destroy_ipq + int + &mac.mpo;_check_ifnet_transmit - struct ipq - *ipq + struct ucred + *cred + struct ifnet + *ifnet struct label - *label + *ifnetlabel + struct mbuf + *mbuf + struct label + *mbuflabel &mac.thead; - ipq - Object; IP reassembly queue + cred + Subject credential - label - Label being destroyed + ifnet + Network interface + + + + ifnetlabel + Policy label for + ifnet + + + + mbuf + Object; mbuf to be sent + + + + mbuflabel + Policy label for + mbuf - 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. + 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. - - <function>&mac.mpo;_destroy_mbuf</function> + + <function>&mac.mpo;_check_socket_deliver</function> - void - &mac.mpo;_destroy_mbuf + int + &mac.mpo;_check_socket_deliver + struct ucred + *cred + struct ifnet + *ifnet + struct label + *ifnetlabel struct mbuf *mbuf struct label - *label + *mbuflabel &mac.thead; + + cred + Subject credential + + + + ifnet + Network interface + + + + ifnetlabel + Policy label for + ifnet + + mbuf - Object; mbuf + Object; mbuf to be delivered - label - Label being destroyed + mbuflabel + Policy label for + mbuf - 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. + 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. - - <function>&mac.mpo;_destroy_mount</function> + + <function>&mac.mpo;_check_socket_visible</function> - void - &mac.mpo;_destroy_mount + int + &mac.mpo;_check_socket_visible - struct mount - *mp - struct label - *mntlabel + struct ucred + *cred + struct socket + *so struct label - *fslabel + *socketlabel &mac.thead; - mp - Object; file system mount point + cred + Subject credential + Immutable - mntlabel - Mount point label being destroyed + so + Object; socket - fslabel - File system label being destroyed> + socketlabel + Policy label for + so - 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. + 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. - - - <function>&mac.mpo;_destroy_socket</function> - + + + <function>&mac.mpo;_check_system_acct</function> + - void - &mac.mpo;_destroy_socket - - struct socket - *socket - struct label - *label + int + &mac.mpo;_check_system_acct + + struct ucred + *ucred + struct vnode + *vp struct label - *peerlabel + *vlabel - + &mac.thead; - + - socket - Object; socket + ucred + Subject credential - + - label - Socket label being destroyed + vp + Accounting file; &man.acct.5; - + - peerlabel - Socket peer label being destroyed + vlabel + Label associated with + vp - - 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. + + Determine whether the subject should be allowed to + enable accounting, based on its label and the label of the + accounting log file. - - - <function>&mac.mpo;_destroy_cred</function> - + + + <function>&mac.mpo;_check_system_nfsd</function> + - void - &mac.mpo;_destroy_cred - + int + &mac.mpo;_check_system_nfsd + struct ucred *cred - struct label - *label - + &mac.thead; - + cred - Subject; user credential + Subject credential - + + + + + Determine whether the subject should be allowed to call + &man.nfssvc.2;. + + + + <function>&mac.mpo;_check_system_reboot</function> + + + + int + &mac.mpo;_check_system_reboot + + struct ucred + *cred + int howto + + + + + + &mac.thead; + + - label - Label being destroyed + cred + Subject credential + + + + howto + howto parameter from + &man.reboot.2; - - 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. + + Determine whether the subject should be allowed to + reboot the system in the specified manner. - - - <function>&mac.mpo;_destroy_temp</function> - + + + <function>&mac.mpo;_check_system_settime</function> + - void - &mac.mpo;_destroy_temp - - struct label - *label + int + &mac.mpo;_check_system_settime + + struct ucred + *cred - + &mac.thead; - + - label - Temporary label being destroyed + cred + Subject credential - - 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. + + Determine whether the user should be allowed to set the + system clock. - - - <function>&mac.mpo;_destroy_vnode</function> - + + + <function>&mac.mpo;_check_system_swapon</function> + - void - &mac.mpo;_destroy_vnode - + int + &mac.mpo;_check_system_swapon + + struct ucred + *cred struct vnode *vp struct label - *label + *vlabel - + &mac.thead; - + + + cred + Subject credential + + vp - Object; file system object + Swap device - + - label - Label being destroyed + vlabel + Label associated with + vp - - 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. + + Determine whether the subject should be allowed to add + vp as a swap device. - - - <function>&mac.mpo;_externalize</function> - + + + <function>&mac.mpo;_check_system_sysctl</function> + - void - &mac.mpo;_externalize - - struct label - *label - struct mac - *extmac + int + &mac.mpo;_check_system_sysctl + + struct ucred + *cred + int *name + u_int *namelen + void *old + size_t + *oldlenp + int inkernel + void *new + size_t newlen - + &mac.thead; - + - label - Label to be externalized + cred + Subject credential - + + + name + See &man.sysctl.3; + + + + namelen + + + + old + + - extmac - MAC structure to be filled in + oldlenp + + + + inkernel + Boolean; 1 if called from + kernel + + + + new + See &man.sysctl.3; + + + + newlen + - - 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. + + Determine whether the subject should be allowed to make + the specified &man.sysctl.3; transaction. + + + + Label Management Calls - - <function>&mac.mpo;_internalize</function> + 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). + + + + + <function>&mac.mpo;_destroy_vnode_label</function> void - &mac.mpo;_internalize + &mac.mpo;_destroy_vnode_label + struct vnode + *vp struct label *label - struct mac - *extmac &mac.thead; - label - Label to be filled in + vp + Object; file system object - extmac - MAC structure to internalize + label + Label being destroyed - 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. + 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. - - - 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 TrustedBSD MAC Framework provides a number of - Application Programming Interfaces (APIs) to that permit - user applications to interact with security labels and - policies. Several categories of interfaces are available - to applications: library calls to convert label data to - and from user-chewable text strings based on a central - configuration, and system calls and ioctls to retrieve - and manipulate labels on kernel-maintained objects. In - addition, interfaces are provided to permit atomic - changing of the process label when a new file is executed, - as well as a multiplexor system call permitting policies - to export functionality without reserving system call - numbers. Finally, modules may be loaded and unloaded - using the existing module management interfaces. - - A list of calls with cross-references will go here - soon. - + 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.