docs-rst: convert lsm from DocBook to ReST

+2

Documentation/00-INDEX

··· 264 264 - full colour GIF image of Linux logo (penguin - Tux). 265 265 logo.txt 266 266 - info on creator of above logo & site to get additional images from. 267 + lsm.txt 268 + - Linux Security Modules: General Security Hooks for Linux 267 269 lzo.txt 268 270 - kernel LZO decompressor input formats 269 271 m68k/

-275

Documentation/DocBook/Makefile

··· 1 - ### 2 - # This makefile is used to generate the kernel documentation, 3 - # primarily based on in-line comments in various source files. 4 - # See Documentation/kernel-doc-nano-HOWTO.txt for instruction in how 5 - # to document the SRC - and how to read it. 6 - # To add a new book the only step required is to add the book to the 7 - # list of DOCBOOKS. 8 1 9 - DOCBOOKS := lsm.xml 10 - 11 - ifeq ($(DOCBOOKS),) 12 - 13 - # Skip DocBook build if the user explicitly requested no DOCBOOKS. 14 - .DEFAULT: 15 - @echo " SKIP DocBook $@ target (DOCBOOKS=\"\" specified)." 16 - else 17 - ifneq ($(SPHINXDIRS),) 18 - 19 - # Skip DocBook build if the user explicitly requested a sphinx dir 20 - .DEFAULT: 21 - @echo " SKIP DocBook $@ target (SPHINXDIRS specified)." 22 - else 23 - 24 - 25 - ### 26 - # The build process is as follows (targets): 27 - # (xmldocs) [by docproc] 28 - # file.tmpl --> file.xml +--> file.ps (psdocs) [by db2ps or xmlto] 29 - # +--> file.pdf (pdfdocs) [by db2pdf or xmlto] 30 - # +--> DIR=file (htmldocs) [by xmlto] 31 - # +--> man/ (mandocs) [by xmlto] 32 - 33 - 34 - # for PDF and PS output you can choose between xmlto and docbook-utils tools 35 - PDF_METHOD = $(prefer-db2x) 36 - PS_METHOD = $(prefer-db2x) 37 - 38 - 39 - targets += $(DOCBOOKS) 40 - BOOKS := $(addprefix $(obj)/,$(DOCBOOKS)) 41 - xmldocs: $(BOOKS) 42 - sgmldocs: xmldocs 43 - 44 - PS := $(patsubst %.xml, %.ps, $(BOOKS)) 45 - psdocs: $(PS) 46 - 47 - PDF := $(patsubst %.xml, %.pdf, $(BOOKS)) 48 - pdfdocs: $(PDF) 49 - 50 - HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS))) 51 - htmldocs: $(HTML) 52 - $(call cmd,build_main_index) 53 - 54 - MAN := $(patsubst %.xml, %.9, $(BOOKS)) 55 - mandocs: $(MAN) 56 - find $(obj)/man -name '*.9' | xargs gzip -nf 57 - 58 - # Default location for installed man pages 59 - export INSTALL_MAN_PATH = $(objtree)/usr 60 - 61 - installmandocs: mandocs 62 - mkdir -p $(INSTALL_MAN_PATH)/man/man9/ 63 - find $(obj)/man -name '*.9.gz' -printf '%h %f\n' | \ 64 - sort -k 2 -k 1 | uniq -f 1 | sed -e 's: :/:' | \ 65 - xargs install -m 644 -t $(INSTALL_MAN_PATH)/man/man9/ 66 - 67 - # no-op for the DocBook toolchain 68 - epubdocs: 69 - latexdocs: 70 - linkcheckdocs: 71 - 72 - ### 73 - #External programs used 74 - KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref 75 - KERNELDOC = $(srctree)/scripts/kernel-doc 76 - DOCPROC = $(objtree)/scripts/docproc 77 - CHECK_LC_CTYPE = $(objtree)/scripts/check-lc_ctype 78 - 79 - # Use a fixed encoding - UTF-8 if the C library has support built-in 80 - # or ASCII if not 81 - LC_CTYPE := $(call try-run, LC_CTYPE=C.UTF-8 $(CHECK_LC_CTYPE),C.UTF-8,C) 82 - export LC_CTYPE 83 - 84 - XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl 85 - XMLTOFLAGS += --skip-validation 86 - 87 - ### 88 - # DOCPROC is used for two purposes: 89 - # 1) To generate a dependency list for a .tmpl file 90 - # 2) To preprocess a .tmpl file and call kernel-doc with 91 - # appropriate parameters. 92 - # The following rules are used to generate the .xml documentation 93 - # required to generate the final targets. (ps, pdf, html). 94 - quiet_cmd_docproc = DOCPROC $@ 95 - cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@ 96 - define rule_docproc 97 - set -e; \ 98 - $(if $($(quiet)cmd_$(1)),echo ' $($(quiet)cmd_$(1))';) \ 99 - $(cmd_$(1)); \ 100 - ( \ 101 - echo 'cmd_$@ := $(cmd_$(1))'; \ 102 - echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`; \ 103 - ) > $(dir $@).$(notdir $@).cmd 104 - endef 105 - 106 - %.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE 107 - $(call if_changed_rule,docproc) 108 - 109 - # Tell kbuild to always build the programs 110 - always := $(hostprogs-y) 111 - 112 - notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \ 113 - exit 1 114 - db2xtemplate = db2TYPE -o $(dir $@) $< 115 - xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $< 116 - 117 - # determine which methods are available 118 - ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found) 119 - use-db2x = db2x 120 - prefer-db2x = db2x 121 - else 122 - use-db2x = notfound 123 - prefer-db2x = $(use-xmlto) 124 - endif 125 - ifeq ($(shell which xmlto >/dev/null 2>&1 && echo found),found) 126 - use-xmlto = xmlto 127 - prefer-xmlto = xmlto 128 - else 129 - use-xmlto = notfound 130 - prefer-xmlto = $(use-db2x) 131 - endif 132 - 133 - # the commands, generated from the chosen template 134 - quiet_cmd_db2ps = PS $@ 135 - cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template)) 136 - %.ps : %.xml 137 - $(call cmd,db2ps) 138 - 139 - quiet_cmd_db2pdf = PDF $@ 140 - cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template)) 141 - %.pdf : %.xml 142 - $(call cmd,db2pdf) 143 - 144 - 145 - index = index.html 146 - main_idx = $(obj)/$(index) 147 - quiet_cmd_build_main_index = HTML $(main_idx) 148 - cmd_build_main_index = rm -rf $(main_idx); \ 149 - echo '<h1>Linux Kernel HTML Documentation</h1>' >> $(main_idx) && \ 150 - echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \ 151 - cat $(HTML) >> $(main_idx) 152 - 153 - quiet_cmd_db2html = HTML $@ 154 - cmd_db2html = xmlto html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \ 155 - echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \ 156 - $(patsubst %.html,%,$(notdir $@))</a><p>' > $@ 157 - 158 - ### 159 - # Rules to create an aux XML and .db, and use them to re-process the DocBook XML 160 - # to fill internal hyperlinks 161 - gen_aux_xml = : 162 - quiet_gen_aux_xml = echo ' XMLREF $@' 163 - silent_gen_aux_xml = : 164 - %.aux.xml: %.xml 165 - @$($(quiet)gen_aux_xml) 166 - @rm -rf $@ 167 - @(cat $< | egrep "^<refentry id" | egrep -o "\".*\"" | cut -f 2 -d \" > $<.db) 168 - @$(KERNELDOCXMLREF) -db $<.db $< > $@ 169 - .PRECIOUS: %.aux.xml 170 - 171 - %.html: %.aux.xml 172 - @(which xmlto > /dev/null 2>&1) || \ 173 - (echo "*** You need to install xmlto ***"; \ 174 - exit 1) 175 - @rm -rf $@ $(patsubst %.html,%,$@) 176 - $(call cmd,db2html) 177 - @if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \ 178 - cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi 179 - 180 - quiet_cmd_db2man = MAN $@ 181 - cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man/$(*F) $< ; fi 182 - %.9 : %.xml 183 - @(which xmlto > /dev/null 2>&1) || \ 184 - (echo "*** You need to install xmlto ***"; \ 185 - exit 1) 186 - $(Q)mkdir -p $(obj)/man/$(*F) 187 - $(call cmd,db2man) 188 - @touch $@ 189 - 190 - ### 191 - # Rules to generate postscripts and PNG images from .fig format files 192 - quiet_cmd_fig2eps = FIG2EPS $@ 193 - cmd_fig2eps = fig2dev -Leps $< $@ 194 - 195 - %.eps: %.fig 196 - @(which fig2dev > /dev/null 2>&1) || \ 197 - (echo "*** You need to install transfig ***"; \ 198 - exit 1) 199 - $(call cmd,fig2eps) 200 - 201 - quiet_cmd_fig2png = FIG2PNG $@ 202 - cmd_fig2png = fig2dev -Lpng $< $@ 203 - 204 - %.png: %.fig 205 - @(which fig2dev > /dev/null 2>&1) || \ 206 - (echo "*** You need to install transfig ***"; \ 207 - exit 1) 208 - $(call cmd,fig2png) 209 - 210 - ### 211 - # Rule to convert a .c file to inline XML documentation 212 - gen_xml = : 213 - quiet_gen_xml = echo ' GEN $@' 214 - silent_gen_xml = : 215 - %.xml: %.c 216 - @$($(quiet)gen_xml) 217 - @( \ 218 - echo "<programlisting>"; \ 219 - expand --tabs=8 < $< | \ 220 - sed -e "s/&/\\&/g" \ 221 - -e "s/</\\</g" \ 222 - -e "s/>/\\>/g"; \ 223 - echo "</programlisting>") > $@ 224 - 225 - endif # DOCBOOKS="" 226 - endif # SPHINDIR=... 227 - 228 - ### 229 - # Help targets as used by the top-level makefile 230 - dochelp: 231 - @echo ' Linux kernel internal documentation in different formats (DocBook):' 232 - @echo ' htmldocs - HTML' 233 - @echo ' pdfdocs - PDF' 234 - @echo ' psdocs - Postscript' 235 - @echo ' xmldocs - XML DocBook' 236 - @echo ' mandocs - man pages' 237 - @echo ' installmandocs - install man pages generated by mandocs to INSTALL_MAN_PATH'; \ 238 - echo ' (default: $(INSTALL_MAN_PATH))'; \ 239 - echo '' 240 - @echo ' cleandocs - clean all generated DocBook files' 241 - @echo 242 - @echo ' make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml' 243 - @echo ' valid values for DOCBOOKS are: $(DOCBOOKS)' 244 - @echo 245 - @echo " make DOCBOOKS=\"\" [target] Don't generate docs from Docbook" 246 - @echo ' This is useful to generate only the ReST docs (Sphinx)' 247 - 248 - 249 - ### 250 - # Temporary files left by various tools 251 - clean-files := $(DOCBOOKS) \ 252 - $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \ 253 - $(patsubst %.xml, %.aux, $(DOCBOOKS)) \ 254 - $(patsubst %.xml, %.tex, $(DOCBOOKS)) \ 255 - $(patsubst %.xml, %.log, $(DOCBOOKS)) \ 256 - $(patsubst %.xml, %.out, $(DOCBOOKS)) \ 257 - $(patsubst %.xml, %.ps, $(DOCBOOKS)) \ 258 - $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \ 259 - $(patsubst %.xml, %.html, $(DOCBOOKS)) \ 260 - $(patsubst %.xml, %.9, $(DOCBOOKS)) \ 261 - $(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \ 262 - $(patsubst %.xml, %.xml.db, $(DOCBOOKS)) \ 263 - $(patsubst %.xml, %.xml, $(DOCBOOKS)) \ 264 - $(patsubst %.xml, .%.xml.cmd, $(DOCBOOKS)) \ 265 - $(index) 266 - 267 - clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man 268 - 269 - cleandocs: 270 - $(Q)rm -f $(call objectify, $(clean-files)) 271 - $(Q)rm -rf $(call objectify, $(clean-dirs)) 272 - 273 - # Declare the contents of the .PHONY variable as phony. We keep that 274 - # information in a variable so we can use it in if_changed and friends. 275 - 276 - .PHONY: $(PHONY)

-265

Documentation/DocBook/lsm.tmpl

··· 1 - <?xml version="1.0" encoding="UTF-8"?> 2 - <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 3 - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> 4 - 5 - <article class="whitepaper" id="LinuxSecurityModule" lang="en"> 6 - <articleinfo> 7 - <title>Linux Security Modules: General Security Hooks for Linux</title> 8 - <authorgroup> 9 - <author> 10 - <firstname>Stephen</firstname> 11 - <surname>Smalley</surname> 12 - <affiliation> 13 - <orgname>NAI Labs</orgname> 14 - <address><email>ssmalley@nai.com</email></address> 15 - </affiliation> 16 - </author> 17 - <author> 18 - <firstname>Timothy</firstname> 19 - <surname>Fraser</surname> 20 - <affiliation> 21 - <orgname>NAI Labs</orgname> 22 - <address><email>tfraser@nai.com</email></address> 23 - </affiliation> 24 - </author> 25 - <author> 26 - <firstname>Chris</firstname> 27 - <surname>Vance</surname> 28 - <affiliation> 29 - <orgname>NAI Labs</orgname> 30 - <address><email>cvance@nai.com</email></address> 31 - </affiliation> 32 - </author> 33 - </authorgroup> 34 - </articleinfo> 35 - 36 - <sect1 id="Introduction"><title>Introduction</title> 37 - 38 - <para> 39 - In March 2001, the National Security Agency (NSA) gave a presentation 40 - about Security-Enhanced Linux (SELinux) at the 2.5 Linux Kernel 41 - Summit. SELinux is an implementation of flexible and fine-grained 42 - nondiscretionary access controls in the Linux kernel, originally 43 - implemented as its own particular kernel patch. Several other 44 - security projects (e.g. RSBAC, Medusa) have also developed flexible 45 - access control architectures for the Linux kernel, and various 46 - projects have developed particular access control models for Linux 47 - (e.g. LIDS, DTE, SubDomain). Each project has developed and 48 - maintained its own kernel patch to support its security needs. 49 - </para> 50 - 51 - <para> 52 - In response to the NSA presentation, Linus Torvalds made a set of 53 - remarks that described a security framework he would be willing to 54 - consider for inclusion in the mainstream Linux kernel. He described a 55 - general framework that would provide a set of security hooks to 56 - control operations on kernel objects and a set of opaque security 57 - fields in kernel data structures for maintaining security attributes. 58 - This framework could then be used by loadable kernel modules to 59 - implement any desired model of security. Linus also suggested the 60 - possibility of migrating the Linux capabilities code into such a 61 - module. 62 - </para> 63 - 64 - <para> 65 - The Linux Security Modules (LSM) project was started by WireX to 66 - develop such a framework. LSM is a joint development effort by 67 - several security projects, including Immunix, SELinux, SGI and Janus, 68 - and several individuals, including Greg Kroah-Hartman and James 69 - Morris, to develop a Linux kernel patch that implements this 70 - framework. The patch is currently tracking the 2.4 series and is 71 - targeted for integration into the 2.5 development series. This 72 - technical report provides an overview of the framework and the example 73 - capabilities security module provided by the LSM kernel patch. 74 - </para> 75 - 76 - </sect1> 77 - 78 - <sect1 id="framework"><title>LSM Framework</title> 79 - 80 - <para> 81 - The LSM kernel patch provides a general kernel framework to support 82 - security modules. In particular, the LSM framework is primarily 83 - focused on supporting access control modules, although future 84 - development is likely to address other security needs such as 85 - auditing. By itself, the framework does not provide any additional 86 - security; it merely provides the infrastructure to support security 87 - modules. The LSM kernel patch also moves most of the capabilities 88 - logic into an optional security module, with the system defaulting 89 - to the traditional superuser logic. This capabilities module 90 - is discussed further in <xref linkend="cap"/>. 91 - </para> 92 - 93 - <para> 94 - The LSM kernel patch adds security fields to kernel data structures 95 - and inserts calls to hook functions at critical points in the kernel 96 - code to manage the security fields and to perform access control. It 97 - also adds functions for registering and unregistering security 98 - modules, and adds a general <function>security</function> system call 99 - to support new system calls for security-aware applications. 100 - </para> 101 - 102 - <para> 103 - The LSM security fields are simply <type>void*</type> pointers. For 104 - process and program execution security information, security fields 105 - were added to <structname>struct task_struct</structname> and 106 - <structname>struct linux_binprm</structname>. For filesystem security 107 - information, a security field was added to 108 - <structname>struct super_block</structname>. For pipe, file, and socket 109 - security information, security fields were added to 110 - <structname>struct inode</structname> and 111 - <structname>struct file</structname>. For packet and network device security 112 - information, security fields were added to 113 - <structname>struct sk_buff</structname> and 114 - <structname>struct net_device</structname>. For System V IPC security 115 - information, security fields were added to 116 - <structname>struct kern_ipc_perm</structname> and 117 - <structname>struct msg_msg</structname>; additionally, the definitions 118 - for <structname>struct msg_msg</structname>, <structname>struct 119 - msg_queue</structname>, and <structname>struct 120 - shmid_kernel</structname> were moved to header files 121 - (<filename>include/linux/msg.h</filename> and 122 - <filename>include/linux/shm.h</filename> as appropriate) to allow 123 - the security modules to use these definitions. 124 - </para> 125 - 126 - <para> 127 - Each LSM hook is a function pointer in a global table, 128 - security_ops. This table is a 129 - <structname>security_operations</structname> structure as defined by 130 - <filename>include/linux/security.h</filename>. Detailed documentation 131 - for each hook is included in this header file. At present, this 132 - structure consists of a collection of substructures that group related 133 - hooks based on the kernel object (e.g. task, inode, file, sk_buff, 134 - etc) as well as some top-level hook function pointers for system 135 - operations. This structure is likely to be flattened in the future 136 - for performance. The placement of the hook calls in the kernel code 137 - is described by the "called:" lines in the per-hook documentation in 138 - the header file. The hook calls can also be easily found in the 139 - kernel code by looking for the string "security_ops->". 140 - 141 - </para> 142 - 143 - <para> 144 - Linus mentioned per-process security hooks in his original remarks as a 145 - possible alternative to global security hooks. However, if LSM were 146 - to start from the perspective of per-process hooks, then the base 147 - framework would have to deal with how to handle operations that 148 - involve multiple processes (e.g. kill), since each process might have 149 - its own hook for controlling the operation. This would require a 150 - general mechanism for composing hooks in the base framework. 151 - Additionally, LSM would still need global hooks for operations that 152 - have no process context (e.g. network input operations). 153 - Consequently, LSM provides global security hooks, but a security 154 - module is free to implement per-process hooks (where that makes sense) 155 - by storing a security_ops table in each process' security field and 156 - then invoking these per-process hooks from the global hooks. 157 - The problem of composition is thus deferred to the module. 158 - </para> 159 - 160 - <para> 161 - The global security_ops table is initialized to a set of hook 162 - functions provided by a dummy security module that provides 163 - traditional superuser logic. A <function>register_security</function> 164 - function (in <filename>security/security.c</filename>) is provided to 165 - allow a security module to set security_ops to refer to its own hook 166 - functions, and an <function>unregister_security</function> function is 167 - provided to revert security_ops to the dummy module hooks. This 168 - mechanism is used to set the primary security module, which is 169 - responsible for making the final decision for each hook. 170 - </para> 171 - 172 - <para> 173 - LSM also provides a simple mechanism for stacking additional security 174 - modules with the primary security module. It defines 175 - <function>register_security</function> and 176 - <function>unregister_security</function> hooks in the 177 - <structname>security_operations</structname> structure and provides 178 - <function>mod_reg_security</function> and 179 - <function>mod_unreg_security</function> functions that invoke these 180 - hooks after performing some sanity checking. A security module can 181 - call these functions in order to stack with other modules. However, 182 - the actual details of how this stacking is handled are deferred to the 183 - module, which can implement these hooks in any way it wishes 184 - (including always returning an error if it does not wish to support 185 - stacking). In this manner, LSM again defers the problem of 186 - composition to the module. 187 - </para> 188 - 189 - <para> 190 - Although the LSM hooks are organized into substructures based on 191 - kernel object, all of the hooks can be viewed as falling into two 192 - major categories: hooks that are used to manage the security fields 193 - and hooks that are used to perform access control. Examples of the 194 - first category of hooks include the 195 - <function>alloc_security</function> and 196 - <function>free_security</function> hooks defined for each kernel data 197 - structure that has a security field. These hooks are used to allocate 198 - and free security structures for kernel objects. The first category 199 - of hooks also includes hooks that set information in the security 200 - field after allocation, such as the <function>post_lookup</function> 201 - hook in <structname>struct inode_security_ops</structname>. This hook 202 - is used to set security information for inodes after successful lookup 203 - operations. An example of the second category of hooks is the 204 - <function>permission</function> hook in 205 - <structname>struct inode_security_ops</structname>. This hook checks 206 - permission when accessing an inode. 207 - </para> 208 - 209 - </sect1> 210 - 211 - <sect1 id="cap"><title>LSM Capabilities Module</title> 212 - 213 - <para> 214 - The LSM kernel patch moves most of the existing POSIX.1e capabilities 215 - logic into an optional security module stored in the file 216 - <filename>security/capability.c</filename>. This change allows 217 - users who do not want to use capabilities to omit this code entirely 218 - from their kernel, instead using the dummy module for traditional 219 - superuser logic or any other module that they desire. This change 220 - also allows the developers of the capabilities logic to maintain and 221 - enhance their code more freely, without needing to integrate patches 222 - back into the base kernel. 223 - </para> 224 - 225 - <para> 226 - In addition to moving the capabilities logic, the LSM kernel patch 227 - could move the capability-related fields from the kernel data 228 - structures into the new security fields managed by the security 229 - modules. However, at present, the LSM kernel patch leaves the 230 - capability fields in the kernel data structures. In his original 231 - remarks, Linus suggested that this might be preferable so that other 232 - security modules can be easily stacked with the capabilities module 233 - without needing to chain multiple security structures on the security field. 234 - It also avoids imposing extra overhead on the capabilities module 235 - to manage the security fields. However, the LSM framework could 236 - certainly support such a move if it is determined to be desirable, 237 - with only a few additional changes described below. 238 - </para> 239 - 240 - <para> 241 - At present, the capabilities logic for computing process capabilities 242 - on <function>execve</function> and <function>set*uid</function>, 243 - checking capabilities for a particular process, saving and checking 244 - capabilities for netlink messages, and handling the 245 - <function>capget</function> and <function>capset</function> system 246 - calls have been moved into the capabilities module. There are still a 247 - few locations in the base kernel where capability-related fields are 248 - directly examined or modified, but the current version of the LSM 249 - patch does allow a security module to completely replace the 250 - assignment and testing of capabilities. These few locations would 251 - need to be changed if the capability-related fields were moved into 252 - the security field. The following is a list of known locations that 253 - still perform such direct examination or modification of 254 - capability-related fields: 255 - <itemizedlist> 256 - <listitem><para><filename>fs/open.c</filename>:<function>sys_access</function></para></listitem> 257 - <listitem><para><filename>fs/lockd/host.c</filename>:<function>nlm_bind_host</function></para></listitem> 258 - <listitem><para><filename>fs/nfsd/auth.c</filename>:<function>nfsd_setuser</function></para></listitem> 259 - <listitem><para><filename>fs/proc/array.c</filename>:<function>task_cap</function></para></listitem> 260 - </itemizedlist> 261 - </para> 262 - 263 - </sect1> 264 - 265 - </article>

+201

Documentation/lsm.txt

··· 1 + ======================================================== 2 + Linux Security Modules: General Security Hooks for Linux 3 + ======================================================== 4 + 5 + :Author: Stephen Smalley 6 + :Author: Timothy Fraser 7 + :Author: Chris Vance 8 + 9 + .. note:: 10 + 11 + The APIs described in this book are outdated. 12 + 13 + Introduction 14 + ============ 15 + 16 + In March 2001, the National Security Agency (NSA) gave a presentation 17 + about Security-Enhanced Linux (SELinux) at the 2.5 Linux Kernel Summit. 18 + SELinux is an implementation of flexible and fine-grained 19 + nondiscretionary access controls in the Linux kernel, originally 20 + implemented as its own particular kernel patch. Several other security 21 + projects (e.g. RSBAC, Medusa) have also developed flexible access 22 + control architectures for the Linux kernel, and various projects have 23 + developed particular access control models for Linux (e.g. LIDS, DTE, 24 + SubDomain). Each project has developed and maintained its own kernel 25 + patch to support its security needs. 26 + 27 + In response to the NSA presentation, Linus Torvalds made a set of 28 + remarks that described a security framework he would be willing to 29 + consider for inclusion in the mainstream Linux kernel. He described a 30 + general framework that would provide a set of security hooks to control 31 + operations on kernel objects and a set of opaque security fields in 32 + kernel data structures for maintaining security attributes. This 33 + framework could then be used by loadable kernel modules to implement any 34 + desired model of security. Linus also suggested the possibility of 35 + migrating the Linux capabilities code into such a module. 36 + 37 + The Linux Security Modules (LSM) project was started by WireX to develop 38 + such a framework. LSM is a joint development effort by several security 39 + projects, including Immunix, SELinux, SGI and Janus, and several 40 + individuals, including Greg Kroah-Hartman and James Morris, to develop a 41 + Linux kernel patch that implements this framework. The patch is 42 + currently tracking the 2.4 series and is targeted for integration into 43 + the 2.5 development series. This technical report provides an overview 44 + of the framework and the example capabilities security module provided 45 + by the LSM kernel patch. 46 + 47 + LSM Framework 48 + ============= 49 + 50 + The LSM kernel patch provides a general kernel framework to support 51 + security modules. In particular, the LSM framework is primarily focused 52 + on supporting access control modules, although future development is 53 + likely to address other security needs such as auditing. By itself, the 54 + framework does not provide any additional security; it merely provides 55 + the infrastructure to support security modules. The LSM kernel patch 56 + also moves most of the capabilities logic into an optional security 57 + module, with the system defaulting to the traditional superuser logic. 58 + This capabilities module is discussed further in 59 + `LSM Capabilities Module <#cap>`__. 60 + 61 + The LSM kernel patch adds security fields to kernel data structures and 62 + inserts calls to hook functions at critical points in the kernel code to 63 + manage the security fields and to perform access control. It also adds 64 + functions for registering and unregistering security modules, and adds a 65 + general :c:func:`security()` system call to support new system calls 66 + for security-aware applications. 67 + 68 + The LSM security fields are simply ``void*`` pointers. For process and 69 + program execution security information, security fields were added to 70 + :c:type:`struct task_struct <task_struct>` and 71 + :c:type:`struct linux_binprm <linux_binprm>`. For filesystem 72 + security information, a security field was added to :c:type:`struct 73 + super_block <super_block>`. For pipe, file, and socket security 74 + information, security fields were added to :c:type:`struct inode 75 + <inode>` and :c:type:`struct file <file>`. For packet and 76 + network device security information, security fields were added to 77 + :c:type:`struct sk_buff <sk_buff>` and :c:type:`struct 78 + net_device <net_device>`. For System V IPC security information, 79 + security fields were added to :c:type:`struct kern_ipc_perm 80 + <kern_ipc_perm>` and :c:type:`struct msg_msg 81 + <msg_msg>`; additionally, the definitions for :c:type:`struct 82 + msg_msg <msg_msg>`, struct msg_queue, and struct shmid_kernel 83 + were moved to header files (``include/linux/msg.h`` and 84 + ``include/linux/shm.h`` as appropriate) to allow the security modules to 85 + use these definitions. 86 + 87 + Each LSM hook is a function pointer in a global table, security_ops. 88 + This table is a :c:type:`struct security_operations 89 + <security_operations>` structure as defined by 90 + ``include/linux/security.h``. Detailed documentation for each hook is 91 + included in this header file. At present, this structure consists of a 92 + collection of substructures that group related hooks based on the kernel 93 + object (e.g. task, inode, file, sk_buff, etc) as well as some top-level 94 + hook function pointers for system operations. This structure is likely 95 + to be flattened in the future for performance. The placement of the hook 96 + calls in the kernel code is described by the "called:" lines in the 97 + per-hook documentation in the header file. The hook calls can also be 98 + easily found in the kernel code by looking for the string 99 + "security_ops->". 100 + 101 + Linus mentioned per-process security hooks in his original remarks as a 102 + possible alternative to global security hooks. However, if LSM were to 103 + start from the perspective of per-process hooks, then the base framework 104 + would have to deal with how to handle operations that involve multiple 105 + processes (e.g. kill), since each process might have its own hook for 106 + controlling the operation. This would require a general mechanism for 107 + composing hooks in the base framework. Additionally, LSM would still 108 + need global hooks for operations that have no process context (e.g. 109 + network input operations). Consequently, LSM provides global security 110 + hooks, but a security module is free to implement per-process hooks 111 + (where that makes sense) by storing a security_ops table in each 112 + process' security field and then invoking these per-process hooks from 113 + the global hooks. The problem of composition is thus deferred to the 114 + module. 115 + 116 + The global security_ops table is initialized to a set of hook functions 117 + provided by a dummy security module that provides traditional superuser 118 + logic. A :c:func:`register_security()` function (in 119 + ``security/security.c``) is provided to allow a security module to set 120 + security_ops to refer to its own hook functions, and an 121 + :c:func:`unregister_security()` function is provided to revert 122 + security_ops to the dummy module hooks. This mechanism is used to set 123 + the primary security module, which is responsible for making the final 124 + decision for each hook. 125 + 126 + LSM also provides a simple mechanism for stacking additional security 127 + modules with the primary security module. It defines 128 + :c:func:`register_security()` and 129 + :c:func:`unregister_security()` hooks in the :c:type:`struct 130 + security_operations <security_operations>` structure and 131 + provides :c:func:`mod_reg_security()` and 132 + :c:func:`mod_unreg_security()` functions that invoke these hooks 133 + after performing some sanity checking. A security module can call these 134 + functions in order to stack with other modules. However, the actual 135 + details of how this stacking is handled are deferred to the module, 136 + which can implement these hooks in any way it wishes (including always 137 + returning an error if it does not wish to support stacking). In this 138 + manner, LSM again defers the problem of composition to the module. 139 + 140 + Although the LSM hooks are organized into substructures based on kernel 141 + object, all of the hooks can be viewed as falling into two major 142 + categories: hooks that are used to manage the security fields and hooks 143 + that are used to perform access control. Examples of the first category 144 + of hooks include the :c:func:`alloc_security()` and 145 + :c:func:`free_security()` hooks defined for each kernel data 146 + structure that has a security field. These hooks are used to allocate 147 + and free security structures for kernel objects. The first category of 148 + hooks also includes hooks that set information in the security field 149 + after allocation, such as the :c:func:`post_lookup()` hook in 150 + :c:type:`struct inode_security_ops <inode_security_ops>`. 151 + This hook is used to set security information for inodes after 152 + successful lookup operations. An example of the second category of hooks 153 + is the :c:func:`permission()` hook in :c:type:`struct 154 + inode_security_ops <inode_security_ops>`. This hook checks 155 + permission when accessing an inode. 156 + 157 + LSM Capabilities Module 158 + ======================= 159 + 160 + The LSM kernel patch moves most of the existing POSIX.1e capabilities 161 + logic into an optional security module stored in the file 162 + ``security/capability.c``. This change allows users who do not want to 163 + use capabilities to omit this code entirely from their kernel, instead 164 + using the dummy module for traditional superuser logic or any other 165 + module that they desire. This change also allows the developers of the 166 + capabilities logic to maintain and enhance their code more freely, 167 + without needing to integrate patches back into the base kernel. 168 + 169 + In addition to moving the capabilities logic, the LSM kernel patch could 170 + move the capability-related fields from the kernel data structures into 171 + the new security fields managed by the security modules. However, at 172 + present, the LSM kernel patch leaves the capability fields in the kernel 173 + data structures. In his original remarks, Linus suggested that this 174 + might be preferable so that other security modules can be easily stacked 175 + with the capabilities module without needing to chain multiple security 176 + structures on the security field. It also avoids imposing extra overhead 177 + on the capabilities module to manage the security fields. However, the 178 + LSM framework could certainly support such a move if it is determined to 179 + be desirable, with only a few additional changes described below. 180 + 181 + At present, the capabilities logic for computing process capabilities on 182 + :c:func:`execve()` and :c:func:`set\*uid()`, checking 183 + capabilities for a particular process, saving and checking capabilities 184 + for netlink messages, and handling the :c:func:`capget()` and 185 + :c:func:`capset()` system calls have been moved into the 186 + capabilities module. There are still a few locations in the base kernel 187 + where capability-related fields are directly examined or modified, but 188 + the current version of the LSM patch does allow a security module to 189 + completely replace the assignment and testing of capabilities. These few 190 + locations would need to be changed if the capability-related fields were 191 + moved into the security field. The following is a list of known 192 + locations that still perform such direct examination or modification of 193 + capability-related fields: 194 + 195 + - ``fs/open.c``::c:func:`sys_access()` 196 + 197 + - ``fs/lockd/host.c``::c:func:`nlm_bind_host()` 198 + 199 + - ``fs/nfsd/auth.c``::c:func:`nfsd_setuser()` 200 + 201 + - ``fs/proc/array.c``::c:func:`task_cap()`