<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;"># This is a BitKeeper generated patch for the following project:
# Project Name: Linux kernel tree
# This patch format is intended for GNU patch command version 2.5 or higher.
# This patch includes the following deltas:
#	           ChangeSet	1.705   -&gt; 1.706  
#	Documentation/DocBook/kernel-api.tmpl	1.19    -&gt; 1.20   
#	Documentation/DocBook/Makefile	1.32    -&gt; 1.33   
#	               (new)	        -&gt; 1.1     Documentation/DocBook/lsm.tmpl
#
# The following is the BitKeeper ChangeSet Log
# --------------------------------------------
# 02/10/08	greg@kroah.com	1.706
# LSM: added lsm documentation to the tree.
# --------------------------------------------
#
diff -Nru a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
--- a/Documentation/DocBook/Makefile	Tue Oct  8 15:51:08 2002
+++ b/Documentation/DocBook/Makefile	Tue Oct  8 15:51:08 2002
@@ -11,7 +11,7 @@
 	    kernel-locking.sgml via-audio.sgml mousedrivers.sgml \
 	    deviceiobook.sgml procfs-guide.sgml tulip-user.sgml \
 	    writing_usb_driver.sgml scsidrivers.sgml sis900.sgml \
-	    kernel-api.sgml journal-api.sgml
+	    kernel-api.sgml journal-api.sgml lsm.sgml
 
 JBDSOURCES :=  $(TOPDIR)/include/linux/jbd.h \
 	$(TOPDIR)/fs/jbd/journal.c \
diff -Nru a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl
--- a/Documentation/DocBook/kernel-api.tmpl	Tue Oct  8 15:51:08 2002
+++ b/Documentation/DocBook/kernel-api.tmpl	Tue Oct  8 15:51:08 2002
@@ -185,6 +185,11 @@
 !Efs/devfs/base.c
   &lt;/chapter&gt;
 
+  &lt;chapter id="security"&gt;
+     &lt;title&gt;Security Framework&lt;/title&gt;
+!Esecurity/security.c
+  &lt;/chapter&gt;
+
   &lt;chapter id="pmfuncs"&gt;
      &lt;title&gt;Power Management&lt;/title&gt;
 !Ekernel/pm.c
diff -Nru a/Documentation/DocBook/lsm.tmpl b/Documentation/DocBook/lsm.tmpl
--- /dev/null	Wed Dec 31 16:00:00 1969
+++ b/Documentation/DocBook/lsm.tmpl	Tue Oct  8 15:51:09 2002
@@ -0,0 +1,285 @@
+&lt;!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[]&gt;
+&lt;article class="whitepaper" id="LinuxSecurityModule" lang="en"&gt;
+ &lt;artheader&gt;
+ &lt;title&gt;Linux Security Modules:  General Security Hooks for Linux&lt;/title&gt;
+ &lt;authorgroup&gt;
+ &lt;author&gt;
+ &lt;firstname&gt;Stephen&lt;/firstname&gt; 
+ &lt;surname&gt;Smalley&lt;/surname&gt;
+ &lt;affiliation&gt;
+ &lt;orgname&gt;NAI Labs&lt;/orgname&gt;
+ &lt;address&gt;&lt;email&gt;ssmalley@nai.com&lt;/email&gt;&lt;/address&gt;
+ &lt;/affiliation&gt;
+ &lt;/author&gt;
+ &lt;author&gt;
+ &lt;firstname&gt;Timothy&lt;/firstname&gt; 
+ &lt;surname&gt;Fraser&lt;/surname&gt;
+ &lt;affiliation&gt;
+ &lt;orgname&gt;NAI Labs&lt;/orgname&gt;
+ &lt;address&gt;&lt;email&gt;tfraser@nai.com&lt;/email&gt;&lt;/address&gt;
+ &lt;/affiliation&gt;
+ &lt;/author&gt;
+ &lt;author&gt;
+ &lt;firstname&gt;Chris&lt;/firstname&gt; 
+ &lt;surname&gt;Vance&lt;/surname&gt;
+ &lt;affiliation&gt;
+ &lt;orgname&gt;NAI Labs&lt;/orgname&gt;
+ &lt;address&gt;&lt;email&gt;cvance@nai.com&lt;/email&gt;&lt;/address&gt;
+ &lt;/affiliation&gt;
+ &lt;/author&gt;
+ &lt;/authorgroup
+ &lt;/artheader&gt;
+
+&lt;sect1&gt;&lt;title&gt;Introduction&lt;/title&gt;
+
+&lt;para&gt;
+In March 2001, the National Security Agency (NSA) gave a presentation
+about Security-Enhanced Linux (SELinux) at the 2.5 Linux Kernel
+Summit.  SELinux is an implementation of flexible and fine-grained
+nondiscretionary access controls in the Linux kernel, originally
+implemented as its own particular kernel patch.  Several other
+security projects (e.g. RSBAC, Medusa) have also developed flexible
+access control architectures for the Linux kernel, and various
+projects have developed particular access control models for Linux
+(e.g. LIDS, DTE, SubDomain).  Each project has developed and
+maintained its own kernel patch to support its security needs.
+&lt;/para&gt;
+
+&lt;para&gt;
+In response to the NSA presentation, Linus Torvalds made a set of
+remarks that described a security framework he would be willing to
+consider for inclusion in the mainstream Linux kernel.  He described a
+general framework that would provide a set of security hooks to
+control operations on kernel objects and a set of opaque security
+fields in kernel data structures for maintaining security attributes.
+This framework could then be used by loadable kernel modules to
+implement any desired model of security.  Linus also suggested the
+possibility of migrating the Linux capabilities code into such a
+module.
+&lt;/para&gt;
+
+&lt;para&gt;
+The Linux Security Modules (LSM) project was started by WireX to
+develop such a framework.  LSM is a joint development effort by
+several security projects, including Immunix, SELinux, SGI and Janus,
+and several individuals, including Greg Kroah-Hartman and James
+Morris, to develop a Linux kernel patch that implements this
+framework.  The patch is currently tracking the 2.4 series and is
+targeted for integration into the 2.5 development series.  This
+technical report provides an overview of the framework and the example
+capabilities security module provided by the LSM kernel patch.
+&lt;/para&gt;
+
+&lt;/sect1&gt;
+
+&lt;sect1 id="framework"&gt;&lt;title&gt;LSM Framework&lt;/title&gt;
+
+&lt;para&gt;
+The LSM kernel patch provides a general kernel framework to support
+security modules.  In particular, the LSM framework is primarily
+focused on supporting access control modules, although future
+development is likely to address other security needs such as
+auditing.  By itself, the framework does not provide any additional
+security; it merely provides the infrastructure to support security
+modules.  The LSM kernel patch also moves most of the capabilities
+logic into an optional security module, with the system defaulting
+to the traditional superuser logic.  This capabilities module
+is discussed further in &lt;XRef LinkEnd="cap"&gt;.
+&lt;/para&gt;
+
+&lt;para&gt;
+The LSM kernel patch adds security fields to kernel data structures
+and inserts calls to hook functions at critical points in the kernel
+code to manage the security fields and to perform access control.  It
+also adds functions for registering and unregistering security
+modules, and adds a general &lt;function&gt;security&lt;/function&gt; system call
+to support new system calls for security-aware applications.
+&lt;/para&gt;
+
+&lt;para&gt;
+The LSM security fields are simply &lt;type&gt;void*&lt;/type&gt; pointers.  For
+process and program execution security information, security fields
+were added to &lt;structname&gt;struct task_struct&lt;/structname&gt; and 
+&lt;structname&gt;struct linux_binprm&lt;/structname&gt;.  For filesystem security
+information, a security field was added to 
+&lt;structname&gt;struct super_block&lt;/structname&gt;.  For pipe, file, and socket
+security information, security fields were added to 
+&lt;structname&gt;struct inode&lt;/structname&gt; and 
+&lt;structname&gt;struct file&lt;/structname&gt;.  For packet and network device security
+information, security fields were added to
+&lt;structname&gt;struct sk_buff&lt;/structname&gt; and
+&lt;structname&gt;struct net_device&lt;/structname&gt;.  For System V IPC security
+information, security fields were added to
+&lt;structname&gt;struct kern_ipc_perm&lt;/structname&gt; and
+&lt;structname&gt;struct msg_msg&lt;/structname&gt;; additionally, the definitions
+for &lt;structname&gt;struct msg_msg&lt;/structname&gt;, &lt;structname&gt;struct 
+msg_queue&lt;/structname&gt;, and &lt;structname&gt;struct 
+shmid_kernel&lt;/structname&gt; were moved to header files
+(&lt;filename&gt;include/linux/msg.h&lt;/filename&gt; and
+&lt;filename&gt;include/linux/shm.h&lt;/filename&gt; as appropriate) to allow
+the security modules to use these definitions.
+&lt;/para&gt;
+
+&lt;para&gt;
+Each LSM hook is a function pointer in a global table,
+security_ops. This table is a
+&lt;structname&gt;security_operations&lt;/structname&gt; structure as defined by
+&lt;filename&gt;include/linux/security.h&lt;/filename&gt;.  Detailed documentation
+for each hook is included in this header file.  At present, this
+structure consists of a collection of substructures that group related
+hooks based on the kernel object (e.g. task, inode, file, sk_buff,
+etc) as well as some top-level hook function pointers for system
+operations.  This structure is likely to be flattened in the future
+for performance.  The placement of the hook calls in the kernel code
+is described by the "called:" lines in the per-hook documentation in
+the header file.  The hook calls can also be easily found in the
+kernel code by looking for the string "security_ops-&gt;".
+
+&lt;/para&gt;
+
+&lt;para&gt;
+Linus mentioned per-process security hooks in his original remarks as a
+possible alternative to global security hooks.  However, if LSM were
+to start from the perspective of per-process hooks, then the base
+framework would have to deal with how to handle operations that
+involve multiple processes (e.g. kill), since each process might have
+its own hook for controlling the operation.  This would require a
+general mechanism for composing hooks in the base framework.
+Additionally, LSM would still need global hooks for operations that
+have no process context (e.g. network input operations).
+Consequently, LSM provides global security hooks, but a security
+module is free to implement per-process hooks (where that makes sense)
+by storing a security_ops table in each process' security field and
+then invoking these per-process hooks from the global hooks.
+The problem of composition is thus deferred to the module.
+&lt;/para&gt;
+
+&lt;para&gt;
+The global security_ops table is initialized to a set of hook
+functions provided by a dummy security module that provides
+traditional superuser logic.  A &lt;function&gt;register_security&lt;/function&gt;
+function (in &lt;filename&gt;security/security.c&lt;/filename&gt;) is provided to
+allow a security module to set security_ops to refer to its own hook
+functions, and an &lt;function&gt;unregister_security&lt;/function&gt; function is
+provided to revert security_ops to the dummy module hooks.  This
+mechanism is used to set the primary security module, which is
+responsible for making the final decision for each hook.
+&lt;/para&gt;
+
+&lt;para&gt;
+LSM also provides a simple mechanism for stacking additional security
+modules with the primary security module.  It defines
+&lt;function&gt;register_security&lt;/function&gt; and
+&lt;function&gt;unregister_security&lt;/function&gt; hooks in the
+&lt;structname&gt;security_operations&lt;/structname&gt; structure and provides
+&lt;function&gt;mod_reg_security&lt;/function&gt; and
+&lt;function&gt;mod_unreg_security&lt;/function&gt; functions that invoke these
+hooks after performing some sanity checking.  A security module can
+call these functions in order to stack with other modules.  However,
+the actual details of how this stacking is handled are deferred to the
+module, which can implement these hooks in any way it wishes
+(including always returning an error if it does not wish to support
+stacking).  In this manner, LSM again defers the problem of
+composition to the module.
+&lt;/para&gt;
+
+&lt;para&gt;
+Although the LSM hooks are organized into substructures based on
+kernel object, all of the hooks can be viewed as falling into two
+major categories: hooks that are used to manage the security fields
+and hooks that are used to perform access control.  Examples of the
+first category of hooks include the
+&lt;function&gt;alloc_security&lt;/function&gt; and
+&lt;function&gt;free_security&lt;/function&gt; hooks defined for each kernel data
+structure that has a security field.  These hooks are used to allocate
+and free security structures for kernel objects.  The first category
+of hooks also includes hooks that set information in the security
+field after allocation, such as the &lt;function&gt;post_lookup&lt;/function&gt;
+hook in &lt;structname&gt;struct inode_security_ops&lt;/structname&gt;.  This hook
+is used to set security information for inodes after successful lookup
+operations.  An example of the second category of hooks is the
+&lt;function&gt;permission&lt;/function&gt; hook in 
+&lt;structname&gt;struct inode_security_ops&lt;/structname&gt;.  This hook checks
+permission when accessing an inode.
+&lt;/para&gt;
+
+&lt;para&gt;
+LSM adds a general &lt;function&gt;security&lt;/function&gt; system call that
+simply invokes the &lt;function&gt;sys_security&lt;/function&gt; hook.  This
+system call and hook permits security modules to implement new system
+calls for security-aware applications.  The interface is similar to
+socketcall, but also has an &lt;parameter&gt;id&lt;/parameter&gt; to help identify
+the security module whose call is being invoked.  
+To eliminate the need for a central registry of ids,
+the recommended convention for creating the hexadecimal id value is:
+&lt;programlisting&gt;
+&lt;![CDATA[
+ echo "Name_of_module" | md5sum | cut -c -8
+]]&gt;
+&lt;/programlisting&gt;
+C code will need to prefix this result with ``0x''.
+For example, the id for ``SGI Trusted Linux'' could be used in C as:
+&lt;programlisting&gt;
+&lt;![CDATA[
+ #define SYS_SECURITY_MODID 0xc4c7be22
+]]&gt;
+&lt;/programlisting&gt;
+&lt;/para&gt;
+
+&lt;/sect1&gt;
+
+&lt;sect1 id="cap"&gt;&lt;title&gt;LSM Capabilities Module&lt;/title&gt;
+
+&lt;para&gt;
+The LSM kernel patch moves most of the existing POSIX.1e capabilities
+logic into an optional security module stored in the file
+&lt;filename&gt;security/capability.c&lt;/filename&gt;.  This change allows
+users who do not want to use capabilities to omit this code entirely
+from their kernel, instead using the dummy module for traditional
+superuser logic or any other module that they desire.  This change
+also allows the developers of the capabilities logic to maintain and
+enhance their code more freely, without needing to integrate patches
+back into the base kernel.
+&lt;/para&gt;
+
+&lt;para&gt;
+In addition to moving the capabilities logic, the LSM kernel patch
+could move the capability-related fields from the kernel data
+structures into the new security fields managed by the security
+modules.  However, at present, the LSM kernel patch leaves the
+capability fields in the kernel data structures.  In his original
+remarks, Linus suggested that this might be preferable so that other
+security modules can be easily stacked with the capabilities module
+without needing to chain multiple security structures on the security field.
+It also avoids imposing extra overhead on the capabilities module
+to manage the security fields.  However, the LSM framework could
+certainly support such a move if it is determined to be desirable,
+with only a few additional changes described below.
+&lt;/para&gt;
+
+&lt;para&gt;
+At present, the capabilities logic for computing process capabilities
+on &lt;function&gt;execve&lt;/function&gt; and &lt;function&gt;set*uid&lt;/function&gt;,
+checking capabilities for a particular process, saving and checking
+capabilities for netlink messages, and handling the
+&lt;function&gt;capget&lt;/function&gt; and &lt;function&gt;capset&lt;/function&gt; system
+calls have been moved into the capabilities module.  There are still a
+few locations in the base kernel where capability-related fields are
+directly examined or modified, but the current version of the LSM
+patch does allow a security module to completely replace the
+assignment and testing of capabilities.  These few locations would
+need to be changed if the capability-related fields were moved into
+the security field.  The following is a list of known locations that
+still perform such direct examination or modification of
+capability-related fields:
+&lt;itemizedlist&gt;
+&lt;listitem&gt;&lt;para&gt;&lt;filename&gt;fs/open.c&lt;/filename&gt;:&lt;function&gt;sys_access&lt;/function&gt;&lt;/para&gt;&lt;/listitem&gt;
+&lt;listitem&gt;&lt;para&gt;&lt;filename&gt;fs/lockd/host.c&lt;/filename&gt;:&lt;function&gt;nlm_bind_host&lt;/function&gt;&lt;/para&gt;&lt;/listitem&gt;
+&lt;listitem&gt;&lt;para&gt;&lt;filename&gt;fs/nfsd/auth.c&lt;/filename&gt;:&lt;function&gt;nfsd_setuser&lt;/function&gt;&lt;/para&gt;&lt;/listitem&gt;
+&lt;listitem&gt;&lt;para&gt;&lt;filename&gt;fs/proc/array.c&lt;/filename&gt;:&lt;function&gt;task_cap&lt;/function&gt;&lt;/para&gt;&lt;/listitem&gt;
+&lt;/itemizedlist&gt;
+&lt;/para&gt;
+
+&lt;/sect1&gt;
+
+&lt;/article&gt;
</pre></body></html>