From owner-p4-projects Fri Jul 19 17:45:44 2002 Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id B1F3737B401; Fri, 19 Jul 2002 17:44:08 -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 B897E37B400 for ; Fri, 19 Jul 2002 17:44:07 -0700 (PDT) Received: from freefall.freebsd.org (freefall.FreeBSD.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id E3C3943E5E for ; Fri, 19 Jul 2002 17:44:06 -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 g6K0i6JU080821 for ; Fri, 19 Jul 2002 17:44:06 -0700 (PDT) (envelope-from chris@freebsd.org) Received: (from perforce@localhost) by freefall.freebsd.org (8.12.4/8.12.4/Submit) id g6K0i6Na080818 for perforce@freebsd.org; Fri, 19 Jul 2002 17:44:06 -0700 (PDT) Date: Fri, 19 Jul 2002 17:44:06 -0700 (PDT) Message-Id: <200207200044.g6K0i6Na080818@freefall.freebsd.org> X-Authentication-Warning: freefall.freebsd.org: perforce set sender to chris@freebsd.org using -f From: Chris Costello Subject: PERFORCE change 14488 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=14488 Change 14488 by chris@chris_holly on 2002/07/19 17:43:06 o Add a section on locking from the man page. o s/hook/entry point/ (and rewrap) o Remove not-supposed-to-be-documented struct mac_policy_conf o `mac_policy' is replaced by an entity for easily changing it once we decide what to change it to. o Some small SGML formatting nits o ... section that keeps getting repeated was replaced with an entity containing that bit, for cleanliness purposes. o Documented mpo_destroy and fix an instant where I misspelled it as mpo_ops. o Mark up and partially document the MAC label operations. o Add a new `mac.ent' to contain the new entities mentioned above. Affected files ... .. //depot/projects/trustedbsd/doc/en_US.ISO8859-1/books/developers-handbook/book.sgml#3 edit .. //depot/projects/trustedbsd/doc/en_US.ISO8859-1/books/developers-handbook/mac.ent#1 add .. //depot/projects/trustedbsd/doc/en_US.ISO8859-1/books/developers-handbook/mac/chapter.sgml#6 edit Differences ... ==== //depot/projects/trustedbsd/doc/en_US.ISO8859-1/books/developers-handbook/book.sgml#3 (text+ko) ==== @@ -10,6 +10,7 @@ %man; %chapters; + %mac-entities; %authors %mailing-lists; ==== //depot/projects/trustedbsd/doc/en_US.ISO8859-1/books/developers-handbook/mac/chapter.sgml#6 (text+ko) ==== @@ -69,40 +69,57 @@ MAC_PERFORM -> policy + + 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. + + Policy Operations - The MAC policy framework implements policy operation hooks - which supply policy modules with relevant data on a subject and - the operation it is attempting to perform on an object. + 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 structure is passed to the module operation - hooks: + following entry points are defined for module-related + events. - struct mac_policy_conf { - char *mpc_name; /* policy name */ - char *mpc_fullname; /* policy full name */ - struct mac_policy_ops mpc_ops; /* policy operations */ - struct mac_policy_op_entry *mpc_entries; /* ops to fill in */ - int mpc_loadtime_flags; /* flags */ - int *mpc_field_off; /* security field */ - int mpc_runtime_flags; /* flags */ - LIST_ENTRY(mac_policy_conf) mpc_list; /* global list */ -}; - - <function>mac_<replaceable>policy</replaceable>_init</function + <function>&mac.mpo;_init</function static void - mac_policy_init - + &mac.mpo;_init struct mac_policy_conf *conf @@ -111,12 +128,7 @@ - - - Parameter - Description - - + &mac.thead; @@ -127,11 +139,10 @@ - This is the initialization hook called after the policy - has been added to the list, but before the list is unlocked. - At the point a module would typically initialize its own - internal structures, print any copyright messages, - etc. + This is the entry point called after the policy has been + added to the list, but before the list is unlocked. At the + point a module would typically initialize its own internal + structures, print any copyright messages, etc. A module loaded message is already printed when a policy is loaded so any further messages of @@ -139,13 +150,12 @@ - <function>mac_<replaceable>policy</replaceable>_destroy</function> + <function>&mac.mpo;_destroy</function> static void - mac_policy_ops - + &mac.mpo;_destroy struct mac_policy_conf *conf @@ -154,40 +164,885 @@ - + &mac.thead; + + + + conf + MAC policy definition + + + + + + This entry point is called when the module is being + unloaded. At this point the policy would typically be + freeing internal storage, etc. + + + + + Label Operations + + ... + + + <function>&mac.mpo;_init_bpfdesc</function> + + + + static 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 + + + + + + ... + + + + <function>&mac.mpo;_init_devfsdirent</function> + + + + static 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 + + + + + + ... + + + + <function>&mac.mpo;_init_ifnet</function> + + + + static void + &mac.mpo;_init_ifnet + + struct ifnet + *ifnet + struct label + *label + + + + + + &mac.thead; + + + + ifnet + Object; network interface + + + + label + New label to apply + + + + + + ... + + + + <function>&mac.mpo;_init_ipq</function> + + + + static void + &mac.mpo;_init_ipq + + struct ipq + *ipq + struct label + *label + + + + + + &mac.thead; + + + + ipq + Object; IP reassembly queue + + + + label + New label to apply + + + + + + + + <function>&mac.mpo;_init_mbuf</function> + + + + static void + &mac.mpo;_init_mbuf + + struct mbuf + *mbuf + struct label + *label + + + + + + &mac.thead; + + + + mbuf + Object; mbuf + + + + label + New label to apply + + + + + ... + + + + <function>&mac.mpo;_init_mount</function> + + + + static void + &mac.mpo;_init_mount + + struct mount + *mount + struct label + *mntlabel + struct label + *fslabel + + + + + + + &mac.thead; + + + + mount + Object; file system mount point + + + + mntlabel + New file system mount point label + + + + fslabel + New file system label + + + + + + ... + + + + <function>&mac.mpo;_init_socket</function> + + + + static 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 + + + + + + ... + + + + <function>&mac.mpo;_init_subject</function> + + + + static void + &mac.mpo;_init_subject + + struct ucred + *cred + struct label + *label + + + + + + &mac.thead; + + + + cred + Subject; user credetial + + + + label + New label + + + + + + In this entry point, a policy module should allocate and + initialize any internal storage for a new label for a + subject (user) credential. No label information should be + filled out. + + + + <function>&mac.mpo;_init_temp</function> + + + + static void + &mac.mpo;_init_temp + + struct label + *label + + + + + + &mac.thead; + + + + label + Temporary label + + + + + + In this entry point, a policy module should allocate + storage for a label meant for temporary use. No label + information should be filled out. + + + + <function>&mac.mpo;_init_vnode</function> + + + + static void + &mac.mpo;_init_vnode + + struct vnode + *vp + struct label + *label + + + + + + &mac.thead; + + + + vp + Object; file system object + + + + label + New label to initialize + + + + + + In this entry point, a policy module should allocate and + initialize any internal storage necessary for a new file + system object label. + + + + <function>&mac.mpo;_destroy_bpfdesc</function> + + + + static void + &mac.mpo;_destroy_bpfdesc + + struct bpf_d + *bpf_d + struct label + *label + + + + + + &mac.thead; + + + + bpf_d + Object; bpf descriptor + + + + label + Label being destroyed + + + + + + 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> + + + + static 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 + + + + + + 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> + + + + static void + &mac.mpo;_destroy_ifnet + + struct ifnet + *ifnet + struct label + *label + + + + + + &mac.thead; + + + + ifnet + Object; network interface + + + + label + Label being destroyed + + + + + + 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> + + + + static void + &mac.mpo;_destroy_ipq + + struct ipq + *ipq + struct label + *label + + + + + + &mac.thead; + + + + ipq + Object; IP reassembly queue + + + + label + Label being destroyed + + + + + + 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> + + + + static void + &mac.mpo;_destroy_mbuf + + struct mbuf + *mbuf + struct label + *label + + + + + + &mac.thead; + + + + mbuf + Object; mbuf + + + + label + Label being destroyed + + + + + + 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> + + + + static 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> + + + + + + 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> + + + + static 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 + + + + + + In this entry point, a policy module should free any + internal storage associated with + label and + peerlabel so that they may be + destroyed. + + + + <function>&mac.mpo;_destroy_subject</function> + + + + static void + &mac.mpo;_destroy_subject + + struct ucred + *cred + struct label + *label + + + + + + &mac.thead; + + + + cred + Subject; user credential + + + + label + Label being destroyed + + + + + + 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_temp</function> + + + + static void + &mac.mpo;_destroy_temp + + struct label + *label + + + + + + &mac.thead; + + + + label + Temporary label being destroyed + + + + + + In this entry point, a policy module should free any + internal storage associated with the temporary label + label so that it may be + destroyed. + + + + <function>&mac.mpo;_destroy_vnode</function> + + + + static void + &mac.mpo;_destroy_vnode + + struct vnode + *vp + struct label + *label + + + + + + &mac.thead; + + + + vp + Object; file system object + + + + label + Label being destroyed + + + + + + In this entry point, a policy module should free any + internal storage associated with + label so that it may be + destroyed. + + + + <function>&mac.mpo;_externalize</function> + + + + static void + &mac.mpo;_externalize + + struct label + *label + struct mac + *extmac + + + + + + &mac.thead; + + + + label + Label to be externalized + + - Parameter - Description + extmac + MAC structure to be filled in - + + + + + ... + + + + <function>&mac.mpo;_internalize</function> >>> TRUNCATED FOR MAIL (1000 lines) <<< To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe p4-projects" in the body of the message