From: serue@us.ibm.com
To: lkml <linux-kernel@vger.kernel.org>
Cc: Chris Wright <chrisw@osdl.org>,
Stephen Smalley <sds@epoch.ncsc.mil>,
James Morris <jmorris@redhat.com>, Andrew Morton <akpm@osdl.org>,
Michael Halcrow <mhalcrow@us.ibm.com>,
David Safford <safford@watson.ibm.com>,
Reiner Sailer <sailer@us.ibm.com>,
Gerrit Huizenga <gerrit@us.ibm.com>,
emily@serge.austin.ibm.com
Subject: [patch 4/12] lsm stacking v0.2: stacker documentation
Date: Thu, 30 Jun 2005 14:49:52 -0500 [thread overview]
Message-ID: <20050630194952.GD23538@serge.austin.ibm.com> (raw)
In-Reply-To: <20050630194458.GA23439@serge.austin.ibm.com>
Add documentation about stacker and its usage.
Signed-off-by: Serge Hallyn <serue@us.ibm.com>
---
LSM-stacking.txt | 157 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 157 insertions(+)
Index: linux-2.6.13-rc1/Documentation/LSM-stacking.txt
===================================================================
--- /dev/null 1970-01-01 00:00:00.000000000 +0000
+++ linux-2.6.13-rc1/Documentation/LSM-stacking.txt 2005-06-30 14:11:39.000000000 -0500
@@ -0,0 +1,157 @@
+------------
+LSM stacking
+------------
+
+This document consists of two parts. The first describes the stacker LSM.
+The second describes what is needed from an LSM in order to permit it to
+stack with other LSMs.
+
+--------------------------------------------------------
+stacker LSM - enable stacking multiple security modules.
+--------------------------------------------------------
+
+Stacker is compiled into the kernel. Find the "Stacker" option under
+the Security submenu, and say 'Y'. Now, any security modules which are
+loaded or compiled into the kernel will be managed by stacker.
+
+You may interact with stacker through its sysfs interface, located
+under /sys/stacker/. This consists of the following files:
+
+/sys/stacker/lockdown:
+Once you write to this file, you will no longer be able to load
+LSMs.
+
+/sys/stacker/list_modules:
+Reading this file will show which LSMs are being stacked.
+
+/sys/stacker/stop_responding:
+Unregisters the /sys/stacker directory, so that you can no longer
+interact with stacker.
+
+/sys/stacker/unload:
+Disables the specified module. The module will actually still be
+loaded, but will no longer be asked to mediate accesses or update
+security information. It will still be consulted on kernel object
+deletions. Please see further down why.
+
+---------------------------------------------
+Readying an LSM for stacking with other LSMs.
+---------------------------------------------
+
+LSM stacking is not a simple matter. You must consider the behavior of
+all stacked LSMs very carefully, as well as certain subtle effects of
+the LSM implementation. Please do not try to stack arbitrary modules!
+For instance, while SELinux and cap-stack should always be used
+together, SELinux cannot be combined with the original capability
+module. The reason for this is that capability enforces that
+a process must have CAP_SYS_ADMIN when writing "security.*" extended
+attributes. However selinux requires that non-CAP_SYS_ADMIN processes
+be able to write security.selinux attributes, instead enforcing its
+own permission check. More subtle interactions are certainly
+imaginable, such as a first security module updating state on a kernel
+object such that a second security module denies or allows the action
+when it otherwise would not have.
+
+If you have any questions about the proper or actual behavior of
+modules, whether existing or ones to be written by yourself, a good
+place to engage in discussion is the lsm mailing list,
+linux-security-module@wirex.com. Information about the mailing list can
+be found at lsm.immunix.org.
+
+For performance reasons, stacker currently does not permit unloading
+of stacked modules. They may be disabled while loaded by using the
+/sys/stacker/unload file. Stacker attempts to prevent the unloads by
+incrementing the usage count on the module's struct security_operations.
+
+If your module will be annotating security information to kernel
+objects, then you should use the provided API. The functions intended
+for use by modules are defined in include/linux/security.h. A
+good example of a user of these functions is the SELinux module. The
+following describes the API usage.
+
+Assume you wish to annotate an instance of the following struct to the
+inode_struct:
+
+struct my_security_info {
+ int a;
+ struct list_head some_list;
+ spinlock_t lock;
+};
+
+At the top of the struct, you must add a struct security_list lsm_list,
+as follows:
+
+struct my_security_info {
++ struct security_list lsm_list;
+ int count;
+ struct list_head some_list;
+ spinlock_t lock;
+};
+
+This will add the information which the API will need to tell your
+information apart from that of other modules. You also need to define a
+unique ID to distinguish information owned by your module. Usually you
+can just "echo <module_name> | sha1sum" and use the first 8 digits.
+For instance, if
+#echo seclvl | sha1sum | awk --field-separator="" '{ print \
+$1$2$3$4$5$6$7$8 '}
+40e81e47
+
+then in your my_lsm.h, add
+#define MY_LSM_ID 0x40e81e47
+
+Do make sure that no other module happens to have the same ID.
+
+Now when the kernel object is created, you may use
+security_set_value_type to append the struct to the object's list of
+security information. Note that you may ONLY use this while the kernel
+object is being created, ie during the security_<KERNEL_OBJECT>_alloc
+function. Since you are appending my_security_info to the inode, you
+will do so during the security_inode_alloc() hook. For instance,
+
+static inline int my_inode_alloc(struct inode *inode)
+{
+ struct my_security_info *my_data;
+
+ my_data = kmalloc(sizeof(struct my_security_info), GFP_KERNEL);
+ if (!my_data)
+ return -ENOMEM;
+ init_inode_data(my_data);
+
+ security_set_value_type(&inode->i_security, MY_LSM_ID, my_data);
+}
+
+If you need to append your information after the kernel object has been
+created, you may do so using security_add_value_type() hook. However,
+for both performance and security reasons, it is preferable to compile
+your module into the kernel and always append your info while the object
+is created.
+
+To get your information back, you may use security_get_value_type.
+For instance,
+
+static inline int my_inode_create(struct inode *dir,
+ struct dentry *dentry,
+ int mode)
+{
+ struct my_security_info *my_data;
+
+ my_data = security_get_value_type(&dir->i_security,
+ MY_LSM_ID, struct my_security_info);
+ if (!my_data || my_data->count)
+ return -EPERM;
+ return 0;
+}
+
+Finally, data appended to kernel objects must (for now) be removed
+during the security_<KERNEL_OBJECT>_free() function only. This is a
+limitation for performance reasons. Allowing data to be freed anytime
+would only be needed if security modules could be unloaded, which would
+then require two additions to the locking scheme: We would have to
+protect the object->security readers from data deletions, and likewise
+protect the actual security_operations structures from being unloaded
+while one of its member functions is executed. It is possible that the
+latter is sufficiently taken care of by the module unloading logic. The
+former would require waiting for a full rcu cycle between removing an
+element from the list, and actually deleting the element. Additional
+locking (ie a refcount) would be up to the module itself.
next prev parent reply other threads:[~2005-06-30 19:48 UTC|newest]
Thread overview: 57+ messages / expand[flat|nested] mbox.gz Atom feed top
2005-06-30 19:44 [patch 0/12] lsm stacking v0.2: intro serue
2005-06-30 19:48 ` [patch 1/12] lsm stacking v0.2: don't default to dummy_##hook serue
2005-06-30 19:48 ` [patch 2/12] lsm stacking v0.2: replace void* security with hlist serue
2005-06-30 19:49 ` [patch 3/12] lsm stacking v0.2: introduce security_*_value API serue
2005-06-30 19:49 ` serue [this message]
2005-06-30 19:50 ` [patch 5/12] lsm stacking v0.2: actual stacker module serue
2005-07-01 2:32 ` James Morris
2005-07-01 19:24 ` serge
2005-07-01 20:35 ` Greg KH
2005-07-03 0:24 ` serge
2005-07-03 18:25 ` Tony Jones
2005-07-03 18:53 ` James Morris
2005-07-03 19:09 ` Tony Jones
2005-07-03 20:44 ` [PATCH] securityfs Greg KH
2005-07-04 12:39 ` serge
2005-07-04 15:53 ` serge
2005-07-05 6:07 ` Greg KH
2005-07-06 12:25 ` serge
2005-07-06 6:52 ` James Morris
2005-07-06 7:04 ` Greg KH
2005-07-06 12:29 ` Stephen Smalley
2005-07-06 15:35 ` James Morris
2005-07-06 16:06 ` Stephen Smalley
2005-07-06 16:16 ` Greg KH
2005-07-06 18:01 ` Chris Wright
2005-07-06 22:08 ` serue
2005-07-06 22:22 ` Greg KH
2005-07-06 23:32 ` serge
2005-07-07 17:30 ` serge
2005-07-07 17:48 ` Greg KH
2005-07-07 18:27 ` serue
2005-07-07 22:46 ` serge
2005-07-07 23:06 ` Greg KH
2005-07-07 23:12 ` serue
2005-07-08 20:44 ` serue
2005-07-08 20:49 ` Greg KH
2005-07-08 21:03 ` Chris Wright
2005-07-04 3:18 ` [patch 5/12] lsm stacking v0.2: actual stacker module Tony Jones
2005-07-04 11:51 ` serge
2005-07-04 19:37 ` Tony Jones
2005-07-04 20:06 ` serge
2005-07-04 20:41 ` Tony Jones
2005-07-05 18:17 ` serge
2005-07-08 21:43 ` serue
2005-07-08 22:12 ` serue
2005-07-11 14:40 ` Stephen Smalley
2005-07-11 17:51 ` serue
2005-07-11 19:03 ` Stephen Smalley
2005-07-13 16:39 ` serue
2005-07-13 18:27 ` serue
2005-06-30 19:51 ` [patch 6/12] lsm stacking v0.2: stackable capability lsm serue
2005-06-30 19:52 ` [patch 7/12] lsm stacking v0.2: selinux: update security structs serue
2005-06-30 19:53 ` [patch 8/12] lsm stacking v0.2: selinux: use security_*_value API serue
2005-06-30 19:53 ` [patch 9/12] lsm stacking v0.2: selinux: remove secondary support serue
2005-06-30 19:54 ` [patch 10/12] lsm stacking v0.2: hook completeness verification serue
2005-06-30 19:55 ` [patch 11/12] lsm stacking v0.2: /proc/$$/attr/ sharing serue
2005-06-30 19:55 ` [patch 12/12] lsm stacking v0.2: update seclvl for stacking serue
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20050630194952.GD23538@serge.austin.ibm.com \
--to=serue@us.ibm.com \
--cc=akpm@osdl.org \
--cc=chrisw@osdl.org \
--cc=emily@serge.austin.ibm.com \
--cc=gerrit@us.ibm.com \
--cc=jmorris@redhat.com \
--cc=linux-kernel@vger.kernel.org \
--cc=mhalcrow@us.ibm.com \
--cc=safford@watson.ibm.com \
--cc=sailer@us.ibm.com \
--cc=sds@epoch.ncsc.mil \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).