[TOMOYO #6 retry 01/21] TOMOYO Linux documentation.

[Kentaro Takeda]

Signed-off-by: Kentaro Takeda <takedakn@xxxxxxxxxxxxx>
Signed-off-by: Tetsuo Handa <penguin-kernel@xxxxxxxxxxxxxxxxxxx>
Signed-off-by: Toshiharu Harada <haradats@xxxxxxxxxxxxx>
---
 Documentation/TOMOYO.txt |  266 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 266 insertions(+)

--- /dev/null
+++ linux-2.6-mm/Documentation/TOMOYO.txt
@@ -0,0 +1,266 @@
+Subject: TOMOYO Linux Security Goal
+
+This document is intended to specify the security goal that TOMOYO Linux is
+trying to achieve, so that users can evaluate whether TOMOYO Linux will meet
+their needs, and kernel developers can evaluate whether TOMOYO Linux deserved
+to be in-tree.
+
+1. About TOMOYO Linux
+
+Project Homepage: http://tomoyo.sourceforge.jp/index.html.en
+Project Wiki: http://elinux.org/TomoyoLinux
+
+TOMOYO Linux is a DIY tool for understanding and protecting your system.
+TOMOYO Linux policy definitions are absolutely readable to Linux users, and
+TOMOYO Linux supports unique policy learning mechanism which automatically
+gathers information and arranges the results as policy definitions.
+These things made it possible for users to write policy from scratch.
+Troubleshooting can be done by users.
+
+We put some TOMOYO Linux policy examples on our web site.
+http://tomoyo.sourceforge.jp/cgi-bin/lxr/source/etch/domain_policy.conf?v=policy-sample
+
+Here's our version of Linux security comparison table.
+http://tomoyo.sourceforge.jp/wiki-e/?WhatIs#comparison
+
+2. TOMOYO Linux Security Goal
+
+The TOMOYO Linux's security goal is to provide "MAC that covers practical
+requirements for most users and keeps usable for most administrators".
+TOMOYO Linux is not a tool for security professional but for average users
+and administrators. We keep TOMOYO Linux understandable and customizable
+so that end users (i.e. administrators) can configure policy for their systems.
+
+TOMOYO Linux can authorize part of kernel resources which SELinux can
+and part of other resources which SELinux can't.
+
+Currently, TOMOYO Linux can authorize
+
+  * execve() of programs.
+  * open() of files for reading/writing.
+  * creat()/link()/rename()/unlink()/symlink()/mkfifo()/mksock()/mkblock()/
+    mkchar()/truncate()/mkdir()/rmdir() of files and directries
+    that are visible to userland process's namespace.
+  * namespace manipulation. (i.e. mount()/umount()/pivot_root())
+  * TCP/IP networking operations based on IPv4/v6 addresses and port numbers.
+    (Need to add LSM hooks for incoming connections/packets.)
+  * booleans for some operations. (Part of POSIX capability and TOMOYO Linux's
+    original capability.)
+  * signal transmissions. (Needs to add LSM hooks.)
+  * argv[0] passed to execve().
+  * environment variables' names passed to execve().
+
+TOMOYO Linux is purely restrictive. No requests which are denied by existent
+access control mechanisms (e.g. DAC) will be reversed by TOMOYO Linux.
+
+TOMOYO Linux is not intended to provide information flow control.
+Analyzing and restricting how information propagates are not the region of
+interest for TOMOYO Linux.
+
+3. Our Approach
+
+To meet the above goal, TOMOYO Linux attempts to make the system where
+everything is prearranged in an easy-to-understand way.
+
+  * Make the all subject's all access requests that will occur at least once
+    during the lifetime of the kernel known in advance.
+
+  * Let the administrator understand what access requests will each subject
+    raise in his/her system and write policy which only allows expected and
+    desirable access requests for his/her needs.
+
+Unlike AppArmor, TOMOYO Linux is intended to protect the whole system from
+attackers exploiting vulnerabilities in applications that the system hosts.
+The threat is that an attacker can cause a vulnerable application to do
+something unexpected and undesirable. TOMOYO Linux addresses this threat by
+recording all applications' behaviors in the test environment and forcing
+all applications behave within recorded behaviors in the production environment.
+
+TOMOYO Linux has a unique concept of "process invocation history"
+(in short, PIH). The PIH is a developmental lineage of a process.
+When a process executes a program, the process creates a copy with fork() and
+replace the copy with execve().
+TOMOYO Linux appends the pathname of the executed program to the PIH of
+the replaced process, and associates process's PIH (stored in task_struct)
+with a domain.
+As a result, the context switching (a.k.a. domain transition) is unidirectional.
+This rule allows administrator distinguish and manage fine-grained context.
+Domain transition forms tree structure like a directory tree of filesystems.
+Each domain has different set of permissions that are essential for that domain.
+
+TOMOYO Linux's region of interest is how to minimize means granted to each PIH,
+although not all permissions TOMOYO Linux can authorize.
+
+The "learning mode" is primary source of policy. TOMOYO Linux depends on change
+of behavior to detect intruders. All unprecedented behaviors should be detected
+and rejected. TOMOYO Linux's power comes from
+"know all and understand what requests can happen within your system".
+
+4. Things you can do with TOMOYO Linux.
+
+Create policy from scratch.
+
+  You want to use ready-made policy files supplied by somebody else
+  because testing all paths needed for your usage sounds boring?
+
+  OK, then you can choose other implementations that provide
+  ready-made policy files, but you should check whether these files
+  contain enough permissions for your usage or not. It is inevitable thing
+  to test all paths needed for your usage if you want to use white listing
+  access control.
+
+  Also, ready-made policy files tend to contain redundant permissions
+  for your usage which often leads to serious problem.
+
+  TOMOYO Linux is a DIY tool for understanding and protecting your Linux box.
+  TOMOYO Linux's "learning mode" will automatically generate
+  policy files with necessary and sufficient permissions for you.
+
+Understand all possible requests.
+
+  TOMOYO Linux reports what is happening within your Linux box.
+  You can have the security of knowing that no unexpected requests arise,
+  if you have tested all paths needed for your usage.
+
+  Please remember, we are not saying that
+  "You can have the security of knowing that no unexpected results happen".
+  Although TOMOYO Linux attempts to filter the request as hard as possible,
+  TOMOYO Linux can't guarantee the result.
+
+Analyze system's behavior.
+
+  TOMOYO Linux resembles to /usr/bin/strace .
+  TOMOYO Linux reports what programs are executed from each program and
+  what files/networks are accessed by each program.
+
+  You can use TOMOYO Linux for analyzing application's behavior
+  if you want to know "which configuration file does this daemon read?",
+  "what port numbers does this daemon require?" and so on.
+
+  This helps debugging program's behaviors and writing manuals.
+  TOMOYO Linux is also applicable for educational use.
+
+Provide per application firewall.
+
+  It is userland applications' businesses to perform pathname based access
+  control, but they sometimes make mistakes which are known as OS command
+  injection vulnerability or buffer overflow vulnerability.
+  TOMOYO Linux assists this access control in kernel space to reduce
+  the damage by restricting pathnames which each application can request.
+
+  TOMOYO Linux can perform TCP_Wrapper-like simple stateless
+  TCP/IP packet filtering based on IPv4/v6 address and ports.
+
+  TOMOYO Linux can restrict the list of environment variable's name
+  passed to execve() so that some dangerous environment variable
+  (e.g. LD_PRELOAD) won't be passed freely.
+
+  TOMOYO Linux also supports conditional permissions.
+  You can use uid/gid etc. of a process to restrict the combination of
+  user and accessible resources.
+
+Provide support for multi-call binary applications without patches.
+
+  A multi-call binary (e.g. /sbin/busybox) changes behaviors according to
+  the invocation name (in other words, argv[0] passed to execve()).
+  Users specify the invocation name using symbolic links or hard links.
+
+  TOMOYO Linux allows administrators to give execute permission and define PIH
+  using the pathname of a symbolic link, if the combination of
+  the pathname of a symbolic link and the pathname of the entity pointed
+  by the symbolic link is registered in the policy file.
+  You can use symbolic links as if they are hard links.
+
+  TOMOYO Linux supports restricting the combination of
+  path-to-executable-or-symbolic-link and basename-of-argv[0]
+  so that users can't pass different argv[0]
+  from path-to-executable-or-symbolic-link freely.
+
+  Please be aware that some multi-call binary programs change their behaviors
+  according to the command line parameters (i.e. argv[1] to argv[argc - 1]).
+  Regarding such programs, TOMOYO Linux can't restrict behaviors by restricting
+  the argv[0]. But TOMOYO Linux doesn't attempt to restrict all argv[] elements
+  passed to execve(), because doing so will make the system too inconvenient
+  and frustrating to use.
+
+Give different set of permissions to the same application.
+
+  There are some non-executable applications (e.g. Java's class files).
+  Such applications use the same program for executing (e.g. Java Runtime
+  Environment). Since TOMOYO Linux has PIH, you can give different set of
+  permissions for each application by separating PIH for each application.
+
+  Although TOMOYO Linux can switch context for every execve() requests,
+  it is preferable to be able to switch context without invoking execve().
+  So far, we are not providing APIs to switch context like AppArmor's
+  change_hat()/change_profile(). We'd like to introduce APIs to switch context
+  when distributors get ready to support TOMOYO Linux (in other words, after
+  TOMOYO Linux is merged into mainline).
+
+Provide DMZ for remote logins.
+
+  Recently, password brute-force attacks against SSH service are increasing.
+  But TOMOYO Linux's PIH can provide a room for deploying DMZ.
+
+  Why password or public-key authentication is possible for only once?
+  Why not give normal users a chance to beat back attackers who logged in
+  through brute-force attacks?
+
+  You can deploy extra login authentications that the only normal user knows
+  how to pass.
+
+Provide simple RBAC-like administrative task division.
+
+  TOMOYO Linux's PIH forms a tree structure.
+  This means that you can split one tree into several subtrees
+  and associate each subtree with each administrative task.
+  You can give each subtree necessary and sufficient permissions
+  for each administrative task.
+
+  You can deploy custom authentication at the entry point of each subtree
+  so that one administrator cannot proceed to other administrator's subtrees.
+
+And more...
+
+  Your imagination invents new usage.
+
+
+Authors:
+  Tetsuo Handa <penguin-kernel@xxxxxxxxxxxxxxxxxxx>
+  Toshiharu Harada <haradats@xxxxxxxxxxxxx>
+  Kentaro Takeda <takedakn@xxxxxxxxxxxxx>
+
+
+Appendix 1 - Usability features of TOMOYO Linux
+
+TOMOYO Linux switches the context of a process whenever a process executes
+a program, but there are two exceptions.
+Administrator may relocate domain of a process if PIH is not meaningful for
+that process (e.g. daemon programs). This exception allows administrator
+restart daemon programs.
+Administrator may suppress domain transition if domain transition is not
+meaningful for that process (e.g. /bin/touch called from /etc/init.d/ scripts).
+This exception reduces memory usage for policy.
+
+TOMOYO Linux can apply access control over all userspace applications,
+but administrator can also apply access control over only specific userspace
+applications if he/she wishes so.
+
+TOMOYO Linux supports "delayed enforcing mode" that allows administrator
+interactively judge whether a request which is not defined in the policy
+should be permitted or rejected.
+This mode helps administrator adjust the policy after software updates.
+
+
+Appendix 2 - Presentation slides
+
+- PacSec2007: TOMOYO Linux: "A Practical Method to Understand and Protect
+                             Your Own Linux Box"
+  http://sourceforge.jp/projects/tomoyo/document/PacSec2007-en-demo.pdf
+
+- OLS2007: "TOMOYO Linux BoF"
+  http://sourceforge.jp/projects/tomoyo/document/ols2007-tomoyo-20070629.pdf
+
+- ELC2007: "TOMOYO Linux - A Lightweight and Manageable Security System
+            for PC and Embedded Linux"
+  http://sourceforge.jp/projects/tomoyo/document/elc2007-presentation-20070418-for_linux.pdf

-- 
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/