From owner-p4-projects Sun Aug 18 13:25:37 2002 Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id 35C6337B401; Sun, 18 Aug 2002 13:24:34 -0700 (PDT) Delivered-To: perforce@freebsd.org Received: from mx1.FreeBSD.org (mx1.FreeBSD.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 9C83D37B400 for ; Sun, 18 Aug 2002 13:24:33 -0700 (PDT) Received: from freefall.freebsd.org (freefall.FreeBSD.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id 8F48B43E3B for ; Sun, 18 Aug 2002 13:24:32 -0700 (PDT) (envelope-from chris@freebsd.org) Received: from freefall.freebsd.org (perforce@localhost [127.0.0.1]) by freefall.freebsd.org (8.12.4/8.12.4) with ESMTP id g7IKOWJU057185 for ; Sun, 18 Aug 2002 13:24:32 -0700 (PDT) (envelope-from chris@freebsd.org) Received: (from perforce@localhost) by freefall.freebsd.org (8.12.4/8.12.4/Submit) id g7IKOWJ7057182 for perforce@freebsd.org; Sun, 18 Aug 2002 13:24:32 -0700 (PDT) Date: Sun, 18 Aug 2002 13:24:32 -0700 (PDT) Message-Id: <200208182024.g7IKOWJ7057182@freefall.freebsd.org> X-Authentication-Warning: freefall.freebsd.org: perforce set sender to chris@freebsd.org using -f From: Chris Costello Subject: PERFORCE change 16219 for review To: Perforce Change Reviews Sender: owner-p4-projects@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.ORG http://people.freebsd.org/~peter/p4db/chv.cgi?CH=16219 Change 16219 by chris@chris_holly on 2002/08/18 13:24:00 Apply introductory text written by Robert Watson, and a few more sections written by same. Affected files ... .. //depot/projects/trustedbsd/doc/en_US.ISO8859-1/books/developers-handbook/mac/chapter.sgml#13 edit Differences ... ==== //depot/projects/trustedbsd/doc/en_US.ISO8859-1/books/developers-handbook/mac/chapter.sgml#13 (text+ko) ==== @@ -70,59 +70,180 @@ (Discreationary Access Control) policies of BSD Unix systems. This chapter introduces the MAC policy framework and - provides documentation for an sample MAC policy module. + provides documentation for a sample MAC policy module. - - Architecture - XFIG: .. MAC architecture, the path of process -> syscall -> - MAC_PERFORM -> policy + + 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. - - - Locking - - - Module writers must be aware of the locking semantics of - entry points that they implement: MAC API entry points will have - specific locking or reference counting semantics for each - argument, and modules must follow the locking and reference - counting protocol or risk a variety of failure modes, including - race conditions, imappropriate pointer dereferences, etc. - - MAC module writers must also be aware that MAC API entry - points will frequently be invoked from deep in a kernel stack, - and as such must be careful to avoid violating more global - locking requirements, such as global lock order requirements. - For example, it may be inappropriate to lock additional objects - not specifically maintained and ordered by the policy module, or - the policy module might violate a global ordering requirement - relating to those additional objects. - - Finally, MAC API module implementors must be careful to - avoid inappropriately calling back into the MAC framework: the - framework makes use of locking to prevent inconsistencies during - policy module attachment and detachment. MAC API modules should - avoid producing scenarios in which deadlocks or inconsistencies - might occur. + + + Userland Architecture + + ... - - Policy Operations + + Entry Point Framework + + Four classes of entry points are offered to policies + registered with the framework: entry points associated with + the registration and management of policies, entry points + denoting initialization, creation, destruction, and other life + cycle events for kernel objects, events assocated with access + control decisions that the policy module may influence, and + calls associated with the management of labels on objects. In + addition, a mac_syscall() entry point is + provided so that policies may extend the kernel interface + without registering new system calls. + + Policy module writers should be aware of the kernel + locking strategy, as well as what object locks are available + during which entry points. Writers should attempt to avoid + deadlock scenarios by avoiding grabbing non-leaf locks inside + of entry points, and also follow the locking protocol for + object access and modification. In particular, writers should + be aware that while necessary locks to access objects and + their labels are generally held, sufficient locks to modify an + object or its label may not be present for all entry points. + Locking information for arguments is documented in the MAC + framework entry point document. + + Policy entry points will pass a reference to the object + label along with the object itself. This permits labeled + policies to be unaware of the internals of the object yet + still make decisions based on the label. The exception to this + is the process credential, which is assumed to be understood + by policies as a first class security object in the kernel. + Policies that do not implement labels on kernel objects will + be passed NULL pointers for label arguments to entry + points. + + + Policy Module Registration + + Modules may be declared using the + MAC_POLICY_SET() macro, which names the + policy, provides a reference to the MAC entry point vector, + provides load-time flags determining how the policy framework + should handle the policy, and optionally requests the + allocation of label state by the framework: + + static struct mac_policy_op_entry mac_none_ops[] = +{ + { MAC_DESTROY, + (macop_t)mac_none_destroy }, + { MAC_INIT, + (macop_t)mac_none_init }, + { MAC_INIT_BPFDESC, + (macop_t)mac_none_init_bpfdesc }, +/* ... */ + { MAC_CHECK_VNODE_STAT, + (macop_t)mac_none_check_vnode_stat }, + { MAC_CHECK_VNODE_WRITE, + (macop_t)mac_none_check_vnode_write }, + { MAC_OP_LAST, NULL } +}; - The MAC policy framework implements policy operation entry - points which supply policy modules with relevant data on a - subject and the operation it is attempting to perform on an - object. - - - Policy Module Operations - - The MAC policy framework includes the ability for policies - to be compiled as separate loadable kernel modules. The - following entry points are defined for module-related - events. + The MAC policy entry point vector, + mac_none_ops in this example, associates + functions defined in the module with specific entry points. A + complete listing of available entry points and their + prototypes may be found in the MAC entry point reference + section. Of specific interest during module registration are + the MAC_DESTROY and MAC_INIT + entry points. MAC_INIT will be invoked once a + policy is successfully registered with the module framework + but prior to any other entry points becoming active. This + permits the policy to perform any policy-specific allocation + and initialization, such as initialization of any data or + locks. MAC_DESTROY will be invoked when a + policy module is unloaded to permit releasing of any allocated + memory and destruction of locks. Currently, these two entry + points are invoked with the MAC policy list mutex held to + prevent any other entry points from being invoked: this will + be changed, but in the mean time, policies should be careful + about what kernel primitives they invoke so as to avoid lock + ordering or sleeping problems. + + The policy declaration's module name field exists so that + the module may be uniquely identified for the purposes of + module dependencies. An appropriate string should be selected. + The full string name of the policy is displayed to the user + via the kernel log during load and unload events, and also + exported when providing status information to userland + processes. + + The policy flags field permits the module to provide the + framework with information about its loader-related + capabilities. Currently, two flags are defined: + + + + MPC_LOADTIME_FLAG_UNLOADOK + + + This flag indicates that the policy module may be + unloaded. If this flag is not provided, then the policy + framework will reject requests to unload the module. + This flag might be used by modules that allocate label + state and are unable to free that state at + runtime. + + + + + MPC_LOADTIME_FLAG_NOTLATE + + This flag indicates that the policy module + must be loaded and initialized early in the boot + process. If the flag is specified, attempts to register + the module following boot will be rejected. The flag + may be used by policies that require pervasive labeling + of all system objects, and cannot handle objects that + have not been properly initialized by the policy. + + + <function>&mac.mpo;_init</function @@ -184,891 +305,82 @@ 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 Operations + 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;_init_bpfdesc</function> - - - - void - &mac.mpo;_init_bpfdesc - - struct bpf_d - *bpf_d - struct label - *label - - - - - - &mac.thead; - - - - bpf_d - Object; bpf descriptor - - - - label - New label to apply - - - - - - Initialize the label on a newly instantiated bpfdesc (BPF - descriptor) - - - - <function>&mac.mpo;_init_devfsdirent</function> - - - - void - &mac.mpo;_init_devfsdirent - - struct devfs_dirent - *devfs_dirent - struct label - *label - - - - - - &mac.thead; - - - - devfs_dirent - Object; devfs directory entry - - - - label - New label to apply - - - - - - Initialize the label on a newly instantiated devfs - entry. - - - - <function>&mac.mpo;_init_ifnet</function> - - - - void - &mac.mpo;_init_ifnet - - struct ifnet - *ifnet - struct label - *label - - - - - - &mac.thead; - - - - ifnet - Object; network interface - - - - label - New label to apply - - - - - - Initialize the label on a newly instantiated network - interface. - - - - <function>&mac.mpo;_init_ipq</function> - - - - void - &mac.mpo;_init_ipq - - struct ipq - *ipq - struct label - *label - - - - - - &mac.thead; - - - - ipq - Object; IP reassembly queue - - - - label - New label to apply - - - - - - Initialize the label on a newly instantiated IP fragment - reassembly queue. - - - - <function>&mac.mpo;_init_mbuf</function> - - - - void - &mac.mpo;_init_mbuf - - struct mbuf - *mbuf - int how - struct label - *label - - - - - - &mac.thead; - - - - mbuf - Object; mbuf - - - - how - Blocking/non-blocking &man.malloc.9; see - below - - - - label - Policy label to initialize - - - - - Initialize the label on a newly instantiated mbuf packet - header (mbuf). The - how field may be one of - M_WAITOK and M_NOWAIT, and - should be employed to avoid performing a blocking - &man.malloc.9; during this initialization call. Mbuf - allocation frequently occurs in performance sensitive - environments, and the implementation should be careful to - avoid blocking or long-lived operations. This entry point - is permitted to fail resulting in the failure to allocate - the mbuf header. - - - - <function>&mac.mpo;_init_mount</function> - - - - void - &mac.mpo;_init_mount - - struct mount - *mount - struct label - *mntlabel - struct label - *fslabel - - - - - - - &mac.thead; - - - - mount - Object; file system mount point - - - - mntlabel - Policy label to be initialized for the mount - itself - - - - fslabel - Policy label to be initialized for the file - system - - - - - - Initialize the labels on a newly instantiated mount - point. - - - - <function>&mac.mpo;_init_socket</function> - - - - void - &mac.mpo;_init_socket - - struct socket - *socket - struct label - *label - struct label - *peerlabel - - - - - - &mac.thead; - - - - socket - Object; socket - - - - label - New label to apply to the socket - - - - peerlabel - New label to apply to the socket's peer - - - - - - Initialize the labels on a newly instantiated - socket. - - - - <function>&mac.mpo;_init_cred</function> - - - - void - &mac.mpo;_init_cred - - struct ucred - *cred - struct label - *label - - - - - - &mac.thead; - - - - cred - Subject; user credetial - - - - label - New label - - - - - - Initialize the labels on a newly instantiated subject. - - - - <function>&mac.mpo;_init_temp</function> - - - - void - &mac.mpo;_init_temp - - struct label - *label - - - - - - &mac.thead; - - - - label - Temporary label - - - - - - Initialize a newly instantiated temporary label; - temporary labels are frequently used to hold label update - requests. - - - - <function>&mac.mpo;_init_vnode</function> - - - - void - &mac.mpo;_init_vnode - - struct vnode - *vp - struct label - *label - - - - - - &mac.thead; - - - - vp - Object; file system object - - - - label - New label to initialize - - - - - - Initialize the label on a newly instantiated vnode. - - - - <function>&mac.mpo;_destroy_bpfdesc</function> - - - - void - &mac.mpo;_destroy_bpfdesc - - struct bpf_d - *bpf_d - struct label - *label - - - - - - &mac.thead; - - - - bpf_d - Object; bpf descriptor - - - - label - Label being destroyed - - - - - - Destroy the label on a BPF descriptor. In this entry - point, a policy module should free any internal storage - associated with label so that it may - be destroyed. - - - - <function>&mac.mpo;_destroy_devfsdirent</function> - - - - void - &mac.mpo;_destroy_devfsdirent - - struct devfs_dirent - *devfs_dirent - struct label - *label - - - - - - &mac.thead; - - - - devfs_dirent - Object; devfs directory entry - - - - label - Label being destroyed - - - - - - Destroy the label on a devfs entry. In this entry - point, a policy module should free any internal storage - asociated with label so that it may - be destroyed. - - - - <function>&mac.mpo;_destroy_ifnet</function> - - - - void - &mac.mpo;_destroy_ifnet - - struct ifnet - *ifnet - struct label - *label - - - - - - &mac.thead; - - - - ifnet - Object; network interface - - - - label - Label being destroyed - - - - - - Destroy the label on a removed interface. In this entry - point, a policy module should free any internal storage - associated with label so that it may - be destroyed. - - - - <function>&mac.mpo;_destroy_ipq</function> - - - - void - &mac.mpo;_destroy_ipq - - struct ipq - *ipq - struct label - *label - - - - - - &mac.thead; - - - - ipq - Object; IP reassembly queue - - - - label - Label being destroyed - - - - - - Destroy the label on an IP fragment queue. In this - entry point, a policy module should free any internal - storage associated with label so that - it may be destroyed. - - - - <function>&mac.mpo;_destroy_mbuf</function> - - - - void - &mac.mpo;_destroy_mbuf - - struct mbuf - *mbuf - struct label - *label - - - - - - &mac.thead; - - - - mbuf - Object; mbuf - - - - label - Label being destroyed - - - - - - Destroy the label on an mbuf header. In this entry - point, a policy module should free any internal storage - associated with label so that it may - be destroyed. - - - - <function>&mac.mpo;_destroy_mount</function> - - - - void - &mac.mpo;_destroy_mount - - struct mount - *mp - struct label - *mntlabel - struct label - *fslabel - - - - - - &mac.thead; - - - - mp - Object; file system mount point - - - - mntlabel - Mount point label being destroyed - - - - fslabel - File system label being destroyed> - - - - - - Destroy the labels on a mount point. In this entry - point, a policy module should free the internal storage - associated with mntlabel and - fslabel so that they may be - destroyed. - - - - <function>&mac.mpo;_destroy_socket</function> - - - - void - &mac.mpo;_destroy_socket - - struct socket - *socket - struct label - *label - struct label - *peerlabel - - - - - - &mac.thead; - - - - socket - Object; socket - - - - label - Socket label being destroyed - - - - peerlabel - Socket peer label being destroyed - - - - - - Destroy the labels on a socket. In this entry point, a - policy module should free any internal storage associated - with label and - peerlabel so that they may be >>> TRUNCATED FOR MAIL (1000 lines) <<< To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe p4-projects" in the body of the message