1. 14 Feb, 2010 3 commits
  2. 11 Feb, 2010 1 commit
  3. 08 Feb, 2010 1 commit
  4. 26 Jan, 2010 1 commit
  5. 10 Jan, 2010 2 commits
  6. 15 Dec, 2009 1 commit
  7. 08 Dec, 2009 1 commit
  8. 25 Nov, 2009 1 commit
  9. 19 Jun, 2009 1 commit
  10. 08 Jun, 2009 2 commits
  11. 02 Jun, 2009 2 commits
  12. 09 May, 2009 1 commit
  13. 13 Apr, 2009 1 commit
  14. 07 Apr, 2009 1 commit
  15. 06 Apr, 2009 1 commit
  16. 15 Feb, 2009 1 commit
  17. 12 Feb, 2009 1 commit
    • Kentaro Takeda's avatar
      Common functions for TOMOYO Linux. · 9590837b
      Kentaro Takeda authored
      This file contains common functions (e.g. policy I/O, pattern matching).
      -------------------- About pattern matching --------------------
      Since TOMOYO Linux is a name based access control, TOMOYO Linux seriously
      considers "safe" string representation.
      TOMOYO Linux's string manipulation functions make reviewers feel crazy,
      but there are reasons why TOMOYO Linux needs its own string manipulation
      ----- Part 1 : preconditions -----
      People definitely want to use wild card.
        To support pattern matching, we have to support wild card characters.
        In a typical Linux system, filenames are likely consists of only alphabets,
        numbers, and some characters (e.g. + - ~ . / ).
        But theoretically, the Linux kernel accepts all characters but NUL character
        (which is used as a terminator of a string).
          Some Linux systems can have filenames which contain * ? ** etc.
      Therefore, we have to somehow modify string so that we can distinguish
      wild card characters and normal characters.
        It might be possible for some application's configuration files to restrict
        acceptable characters.
        It is impossible for kernel to restrict acceptable characters.
          We can't accept approaches which will cause troubles for applications.
      ----- Part 2 : commonly used approaches -----
      Text formatted strings separated by space character (0x20) and new line
      character (0x0A) is more preferable for users over array of NUL-terminated
        Thus, people use text formatted configuration files separated by space
        character and new line.
      We sometimes need to handle non-printable characters.
        Thus, people use \ character (0x5C) as escape character and represent
        non-printable characters using octal or hexadecimal format.
      At this point, we remind (at least) 3 approaches.
        (1) Shell glob style expression
        (2) POSIX regular expression (UNIX style regular expression)
        (3) Maverick wild card expression
      On the surface, (1) and (2) sound good choices. But they have a big pitfall.
      All meta-characters in (1) and (2) are legal characters for representing
      a pathname, and users easily write incorrect expression. What is worse, users
      unlikely notice incorrect expressions because characters used for regular
      pathnames unlikely contain meta-characters. This incorrect use of
      meta-characters in pathname representation reveals vulnerability
      (e.g. unexpected results) only when irregular pathname is specified.
      The authors of TOMOYO Linux think that approaches which adds some character
      for interpreting meta-characters as normal characters (i.e. (1) and (2)) are
      not suitable for security use.
      Therefore, the authors of TOMOYO Linux propose (3).
      ----- Part 3: consideration points -----
      We need to solve encoding problem.
        A single character can be represented in several ways using encodings.
          For Japanese language, there are "ShiftJIS", "ISO-2022-JP", "EUC-JP",
          "UTF-8" and more.
        Some languages (e.g. Japanese language) supports multi-byte characters
        (where a single character is represented using several bytes).
          Some multi-byte characters may match the escape character.
          For Japanese language, some characters in "ShiftJIS" encoding match
          \ character, and bothering Web's CGI developers.
        It is important that the kernel string is not bothered by encoding problem.
          Linus said, "I really would expect that kernel strings don't have
          an encoding. They're just C strings: a NUL-terminated stream of bytes."
          Yes. The kernel strings are just C strings.
          We are talking about how to store and carry "kernel strings" safely.
        If we store "kernel string" into policy file as-is, the "kernel string" will
        be interpreted differently depending on application's encoding settings.
        One application may interpret "kernel string" as "UTF-8",
        another application may interpret "kernel string" as "ShiftJIS".
          Therefore, we propose to represent strings using ASCII encoding.
          In this way, we are no longer bothered by encoding problems.
      We need to avoid information loss caused by display.
        It is difficult to input and display non-printable characters, but we have to
        be able to handle such characters because the kernel string is a C string.
        If we use only ASCII printable characters (from 0x21 to 0x7E) and space
        character (0x20) and new line character (0x0A), it is easy to input from
        keyboard and display on all terminals which is running Linux.
        Therefore, we propose to represent strings using only characters which value
        is one of "from 0x21 to 0x7E", "0x20", "0x0A".
      We need to consider ease of splitting strings from a line.
        If we use an approach which uses "\ " for representing a space character
        within a string, we have to count the string from the beginning to check
        whether this space character is accompanied with \ character or not.
        As a result, we cannot monotonically split a line using space character.
        If we use an approach which uses "\040" for representing a space character
        within a string, we can monotonically split a line using space character.
        If we use an approach which uses NUL character as a delimiter, we cannot
        use string manipulation functions for splitting strings from a line.
        Therefore, we propose that we represent space character as "\040".
      We need to avoid wrong designations (incorrect use of special characters).
        Not all users can understand and utilize POSIX's regular expressions
        correctly and perfectly.
        If a character acts as a wild card by default, the user will get unexpected
        result if that user didn't know the meaning of that character.
          Therefore, we propose that all characters but \ character act as
          a normal character and let the user add \ character to make a character
          act as a wild card.
          In this way, users needn't to know all wild card characters beforehand.
          They can learn when they encountered an unseen wild card character
          for their first time.
      ----- Part 4: supported wild card expressions -----
      At this point, we have wild card expressions listed below.
        | Wild card | Meaning and example                                          |
        |   \*      | More than or equals to 0 character other than '/'.           |
        |           |           /var/log/samba/\*                                  |
        |   \@      | More than or equals to 0 character other than '/' or '.'.    |
        |           |           /var/www/html/\@.html                              |
        |   \?      | 1 byte character other than '/'.                             |
        |           |           /tmp/mail.\?\?\?\?\?\?                             |
        |   \$      | More than or equals to 1 decimal digit.                      |
        |           |           /proc/\$/cmdline                                   |
        |   \+      | 1 decimal digit.                                             |
        |           |           /var/tmp/my_work.\+                                |
        |   \X      | More than or equals to 1 hexadecimal digit.                  |
        |           |           /var/tmp/my-work.\X                                |
        |   \x      | 1 hexadecimal digit.                                         |
        |           |           /tmp/my-work.\x                                    |
        |   \A      | More than or equals to 1 alphabet character.                 |
        |           |           /var/log/my-work/\$-\A-\$.log                      |
        |   \a      | 1 alphabet character.                                        |
        |           |           /home/users/\a/\*/public_html/\*.html              |
        |   \-      | Pathname subtraction operator.                               |
        |           | +---------------------+------------------------------------+ |
        |           | | Example             | Meaning                            | |
        |           | +---------------------+------------------------------------+ |
        |           | | /etc/\*             | All files in /etc/ directory.      | |
        |           | +---------------------+------------------------------------+ |
        |           | | /etc/\*\-\*shadow\* | /etc/\* other than /etc/\*shadow\* | |
        |           | +---------------------+------------------------------------+ |
        |           | | /\*\-proc\-sys/     | /\*/ other than /proc/ /sys/       | |
        |           | +---------------------+------------------------------------+ |
        | Representation | Meaning and example                                     |
        |   \\           | backslash character itself.                             |
        |   \ooo         | 1 byte character.                                       |
        |                | ooo is 001 <= ooo <= 040 || 177 <= ooo <= 377.          |
        |                |                                                         |
        |                |           \040 for space character.                     |
        |                |           \177 for del character.                       |
        |                |                                                         |
      ----- Part 5: Advantages -----
      We can obtain extensibility.
        Since our proposed approach adds \ to a character to interpret as a wild
        card, we can introduce new wild card in future while maintaining backward
      We can process monotonically.
        Since our proposed approach separates strings using a space character,
        we can split strings using existing string manipulation functions.
      We can reliably analyze access logs.
        It is guaranteed that a string doesn't contain space character (0x20) and
        new line character (0x0A).
        It is guaranteed that a string won't be converted by FTP and won't be damaged
        by a terminal's settings.
        It is guaranteed that a string won't be affected by encoding converters
        (except encodings which insert NUL character (e.g. UTF-16)).
      ----- Part 6: conclusion -----
      TOMOYO Linux is using its own encoding with reasons described above.
      There is a disadvantage that we need to introduce a series of new string
      manipulation functions. But TOMOYO Linux's encoding is useful for all users
      (including audit and AppArmor) who want to perform pattern matching and
      safely exchange string information between the kernel and the userspace.
      -------------------- About policy interface --------------------
      TOMOYO Linux creates the following files on securityfs (normally
      mounted on /sys/kernel/security) as interfaces between kernel and
      userspace. These files are for TOMOYO Linux management tools *only*,
      not for general programs.
        * profile
        * exception_policy
        * domain_policy
        * manager
        * meminfo
        * self_domain
        * version
        * .domain_status
        * .process_status
      ** /sys/kernel/security/tomoyo/profile **
      This file is used to read or write profiles.
      "profile" means a running mode of process. A profile lists up
      functions and their modes in "$number-$variable=$value" format. The
      $number is profile number between 0 and 255. Each domain is assigned
      one profile. To assign profile to domains, use "ccs-setprofile" or
      "ccs-editpolicy" or "ccs-loadpolicy" commands.
      [root@tomoyo]# cat /sys/kernel/security/tomoyo/profile
      0-COMMENT=-----Disabled Mode-----
      1-COMMENT=-----Learning Mode-----
      2-COMMENT=-----Permissive Mode-----
      3-COMMENT=-----Enforcing Mode-----
      - MAC_FOR_FILE:
      Specifies access control level regarding file access requests.
      Limits the max number of ACL entries that are automatically appended
      during learning mode. Default is 2048.
      Specifies whether to print domain policy violation messages or not.
      ** /sys/kernel/security/tomoyo/manager **
      This file is used to read or append the list of programs or domains
      that can write to /sys/kernel/security/tomoyo interface. By default,
      only processes with both UID = 0 and EUID = 0 can modify policy via
      /sys/kernel/security/tomoyo interface. You can use keyword
      "manage_by_non_root" to allow policy modification by non root user.
      [root@tomoyo]# cat /sys/kernel/security/tomoyo/manager
      ** /sys/kernel/security/tomoyo/exception_policy **
      This file is used to read and write system global settings. Each line
      has a directive and operand pair. Directives are listed below.
      - initialize_domain:
      To initialize domain transition when specific program is executed,
      use initialize_domain directive.
        * initialize_domain "program" from "domain"
        * initialize_domain "program" from "the last program part of domain"
        * initialize_domain "program"
      If the part "from" and after is not given, the entry is applied to
      all domain. If the "domain" doesn't start with "<kernel>", the entry
      is applied to all domain whose domainname ends with "the last program
      part of domain".
      This directive is intended to aggregate domain transitions for daemon
      program and program that are invoked by the kernel on demand, by
      transiting to different domain.
      - keep_domain
      To prevent domain transition when program is executed from specific
      domain, use keep_domain directive.
        * keep_domain "program" from "domain"
        * keep_domain "program" from "the last program part of domain"
        * keep_domain "domain"
        * keep_domain "the last program part of domain"
      If the part "from" and before is not given, this entry is applied to
      all program. If the "domain" doesn't start with "<kernel>", the entry
      is applied to all domain whose domainname ends with "the last program
      part of domain".
      This directive is intended to reduce total number of domains and
      memory usage by suppressing unneeded domain transitions.
      To declare domain keepers, use keep_domain directive followed by
      domain definition.
      Any process that belongs to any domain declared with this directive,
      the process stays at the same domain unless any program registered
      with initialize_domain directive is executed.
      In order to control domain transition in detail, you can use
      no_keep_domain/no_initialize_domain keywrods.
      - alias:
      To allow executing programs using the name of symbolic links, use
      alias keyword followed by dereferenced pathname and reference
      pathname. For example, /sbin/pidof is a symbolic link to
      /sbin/killall5 . In normal case, if /sbin/pidof is executed, the
      domain is defined as if /sbin/killall5 is executed. By specifying
      "alias /sbin/killall5 /sbin/pidof", you can run /sbin/pidof in the
      domain for /sbin/pidof .
      alias /sbin/killall5 /sbin/pidof
      - allow_read:
      To grant unconditionally readable permissions, use allow_read keyword
      followed by canonicalized file. This keyword is intended to reduce
      size of domain policy by granting read access to library files such
      as GLIBC and locale files. Exception is, if ignore_global_allow_read
      keyword is given to a domain, entries specified by this keyword are
      allow_read /lib/libc-2.5.so
      - file_pattern:
      To declare pathname pattern, use file_pattern keyword followed by
      pathname pattern. The pathname pattern must be a canonicalized
      Pathname. This keyword is not applicable to neither granting execute
      permissions nor domain definitions.
      For example, canonicalized pathname that contains a process ID
      (i.e. /proc/PID/ files) needs to be grouped in order to make access
      control work well.
      file_pattern /proc/\$/cmdline
      - path_group
      To declare pathname group, use path_group keyword followed by name of
      the group and pathname pattern. For example, if you want to group all
      files under home directory, you can define
         path_group HOME-DIR-FILE /home/\*/\*
         path_group HOME-DIR-FILE /home/\*/\*/\*
         path_group HOME-DIR-FILE /home/\*/\*/\*/\*
      in the exception policy and use like
         allow_read @HOME-DIR-FILE
      to grant file access permission.
      - deny_rewrite:
      To deny overwriting already written contents of file (such as log
      files) by default, use deny_rewrite keyword followed by pathname
      pattern. Files whose pathname match the patterns are not permitted to
      open for writing without append mode or truncate unless the pathnames
      are explicitly granted using allow_rewrite keyword in domain policy.
      deny_rewrite /var/log/\*
      - aggregator
      To deal multiple programs as a single program, use aggregator keyword
      followed by name of original program and aggregated program. This
      keyword is intended to aggregate similar programs.
      For example, /usr/bin/tac and /bin/cat are similar. By specifying
      "aggregator /usr/bin/tac /bin/cat", you can run /usr/bin/tac in the
      domain for /bin/cat .
      For example, /usr/sbin/logrotate for Fedora Core 3 generates programs
      like /tmp/logrotate.\?\?\?\?\?\? and run them, but TOMOYO Linux
      doesn't allow using patterns for granting execute permission and
      defining domains. By specifying
      "aggregator /tmp/logrotate.\?\?\?\?\?\? /tmp/logrotate.tmp", you can
      run /tmp/logrotate.\?\?\?\?\?\? as if /tmp/logrotate.tmp is running.
      ** /sys/kernel/security/tomoyo/domain_policy **
      This file contains definition of all domains and permissions that are
      granted to each domain.
      Lines from the next line to a domain definition ( any lines starting
      with "<kernel>") to the previous line to the next domain definitions
      are interpreted as access permissions for that domain.
      ** /sys/kernel/security/tomoyo/meminfo **
      This file is to show the total RAM used to keep policy in the kernel
      by TOMOYO Linux in bytes.
      [root@tomoyo]# cat /sys/kernel/security/tomoyo/meminfo
      Shared:       61440
      Private:      69632
      Dynamic:        768
      Total:       131840
      You can set memory quota by writing to this file.
      [root@tomoyo]# echo Shared: 2097152 > /sys/kernel/security/tomoyo/meminfo
      [root@tomoyo]# echo Private: 2097152 > /sys/kernel/security/tomoyo/meminfo
      ** /sys/kernel/security/tomoyo/self_domain **
      This file is to show the name of domain the caller process belongs to.
      [root@etch]# cat /sys/kernel/security/tomoyo/self_domain
      <kernel> /usr/sbin/sshd /bin/zsh /bin/cat
      ** /sys/kernel/security/tomoyo/version **
      This file is used for getting TOMOYO Linux's version.
      [root@etch]# cat /sys/kernel/security/tomoyo/version
      ** /sys/kernel/security/tomoyo/.domain_status **
      This is a view (of a DBMS) that contains only profile number and
      domainnames of domain so that "ccs-setprofile" command can do
      line-oriented processing easily.
      ** /sys/kernel/security/tomoyo/.process_status **
      This file is used by "ccs-ccstree" command to show "list of processes
      currently running" and "domains which each process belongs to" and
      "profile number which the domain is currently assigned" like "pstree"
      command. This file is writable by programs that aren't registered as
      policy manager.
      Signed-off-by: default avatarKentaro Takeda <takedakn@nttdata.co.jp>
      Signed-off-by: default avatarTetsuo Handa <penguin-kernel@I-love.SAKURA.ne.jp>
      Signed-off-by: default avatarToshiharu Harada <haradats@nttdata.co.jp>
      Signed-off-by: default avatarJames Morris <jmorris@namei.org>