From owner-p4-projects Sun Aug 18 13:50:30 2002 Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id C69BE37B401; Sun, 18 Aug 2002 13:49:05 -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 78C2537B400 for ; Sun, 18 Aug 2002 13:49:05 -0700 (PDT) Received: from freefall.freebsd.org (freefall.FreeBSD.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id 6BAFD43E3B for ; Sun, 18 Aug 2002 13:49:04 -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 g7IKn4JU061159 for ; Sun, 18 Aug 2002 13:49:04 -0700 (PDT) (envelope-from chris@freebsd.org) Received: (from perforce@localhost) by freefall.freebsd.org (8.12.4/8.12.4/Submit) id g7IKn2cG061156 for perforce@freebsd.org; Sun, 18 Aug 2002 13:49:02 -0700 (PDT) Date: Sun, 18 Aug 2002 13:49:02 -0700 (PDT) Message-Id: <200208182049.g7IKn2cG061156@freefall.freebsd.org> X-Authentication-Warning: freefall.freebsd.org: perforce set sender to chris@freebsd.org using -f From: Chris Costello Subject: PERFORCE change 16221 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=16221 Change 16221 by chris@chris_holly on 2002/08/18 13:48:09 Run through sgml-indent-buffer Affected files ... .. //depot/projects/trustedbsd/doc/en_US.ISO8859-1/books/developers-handbook/mac/chapter.sgml#14 edit Differences ... ==== //depot/projects/trustedbsd/doc/en_US.ISO8859-1/books/developers-handbook/mac/chapter.sgml#14 (text+ko) ==== @@ -41,17 +41,17 @@ Chris Costello - + TrustedBSD Project
chris@FreeBSD.org
 - + Robert Watson - + TrustedBSD Project
rwatson@FreeBSD.org
@@ -59,41 +59,41 @@ - + Writing MAC Policies - + Synopsis - + MAC, or Mandatory Access Control, is a feature introduced by the TrustedBSD Project to supplement the existing standard DAC (Discreationary Access Control) policies of BSD Unix systems. - + 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. - + + + + 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 @@ -121,42 +121,42 @@ ... - - - 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. + + + 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 @@ -183,7 +183,7 @@ (macop_t)mac_none_check_vnode_write }, { MAC_OP_LAST, NULL } }; - + The MAC policy entry point vector, mac_none_ops in this example, associates functions defined in the module with specific entry points. A @@ -244,24 +244,24 @@ - + <function>&mac.mpo;_init</function - + void &mac.mpo;_init - + struct mac_policy_conf *conf - + &mac.thead; - + conf @@ -270,28 +270,28 @@ - + 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 @@ -300,7 +300,7 @@ - + Policy load event. The policy list mutex is held, so caution should be applied. @@ -320,7 +320,7 @@ 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 @@ -376,2073 +376,2073 @@ 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;_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_vnode</function> - - - - void - &mac.mpo;_create_devfs_vnode - - struct devfs_dirent - *devfs_dirent - struct label - *direntlabel - struct vnode - *vp - struct label - *vnodelabel - - - - - - &mac.thead; - - - - devfs_dirent - Object; devfs directory entry - - - - direntlabel - Policy label for - devfs_dirent - - - - vp - Object; file system object being labeled - - - - vnodelabel - Policy label to be filled in for - vp - - - - - - Fill out the label on the vnode being created for the - passed devfs_dirent. This call will be made when a vnode is - required to represent the specified devfs_dirent in a - mounted devfs instance. - - - - <function>&mac.mpo;_vnode_create_from_vnode</function> - - - - void - &mac.mpo;_vnode_create_from_vnode - - struct ucred - *cred - struct vnode - *parent - struct label - *parentlabel - struct vnode - *child - struct label - *childlabel - - - - - - &mac.thead; - - - - cred - Subject credential - - - - parent - Parent vnode; the directory in which - child is being - created - - - - parentlabel - Policy label for - parent - - - - child - New vnode - - - - childlabel - Label to be filled in for - child - - - - - - Fill out the label on the vnode being created in the - passed vnode parent by the passed subject credential. This - call will be made when a vnode is allocated during a vnode - creation operation. For example, this call is made by - multi-label file systems during the creation of a new file - or directory. - - - - <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> - - - - void - &mac.mpo;_vnode_relabel - - struct ucred - *cred - struct vnode - *vp - struct label - *vnodelabel - struct label - *newlabel - - - - - - &mac.thead; - - - - cred - Subject credential - - - - vp - vnode to relabel - - - - vnodelabel - Existing policy label for - vp - - - - newlabel - New, possibly partial label to replace - vnodelabel - - - - - - Update the label on the passed vnode given the passed - update vnode label and the passed subject credential. - - - - <function>&mac.mpo;_stdcreatevnode_ea</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 - 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 - struct label - *vnodelabel - struct mac - *extmac - - - - - - &mac.thead; - - - - vp - Object; vnode - Locked - - - - vnodelabel - Policy label for - vp - - - - extmac - Externalized MAC policy label - - - - - - Update the vnode label from the passed externalized - label loaded from disk by the MAC framework. This call is - permitted to fail; if the call fails, the associated label - refresh will also fail, causing the failure of the operation - requiring the MAC check and vnode label refresh, permitting - a fail closed policy if labeling data is not - available. This call will be obsoleted by the new extended - attribute labeling interface. - - - - <function>&mac.mpo;_update_vnode_from_mount</function> - - - - void - &mac.mpo;_update_vnode_from_mount - - struct vnode - *vp - struct label - *vnodelabel - struct mount - *mp - struct label - *mountlabel - - - - - - &mac.thead; - - - - vp - Object; vnode - Locked - - - - vnodelabel - Policy label for - vp - - - - mp - Mount point where vp - resides - - - - fslabel - Policy label for the file system where - vp resides. - - - - - - Update the vnode label from the passed mount point - label. This call is made when a single label file system - vnode requires a label, or if the obsoleted MAC framework - externalized extended attribute read fails. - - - - - IPC Object Labeling Event Operations - - - <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; - - - >>> TRUNCATED FOR MAIL (1000 lines) <<< To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe p4-projects" in the body of the message