This page is for TOMOYO 2.2 (for Linux 2.6.30 - 2.6.35 kernels). Please jump to this page for TOMOYO 2.3 (for Linux 2.6.36 and later kernels).

Japanese Page

Last modified: $Date: 2024-03-30 20:25:00 +0900 (Sat, 30 Mar 2024) $

Policy Specifications of TOMOYO Linux

Index

1. Keywords Index

2. Introduction

2.1 Word Expression Rules

2.2 Wildcard Expression Rules

2.3 Word Length Rules

2.4 Line Length Rules

2.5 Memory Allocation Rules

3. Policy Files

3.1 Policy File's Location

3.2 Policy File's Modification

4. Domain Rules

4.1 Domain Definition

4.2 Domain Transition

5. Syntax Details

6. Advanced Features

6.1 Allowing policy modification by non root user.

6.2 Enabling quota for memory used for holding policy.

1. Keywords Index

Used by /sys/kernel/security/tomoyo/profile and /etc/tomoyo/profile.conf

• MAC_FOR_FILE
• MAX_ACCEPT_ENTRY
• TOMOYO_VERBOSE

Used by /sys/kernel/security/tomoyo/exception_policy and /etc/tomoyo/exception_policy.conf

• initialize_domain
• no_initialize_domain
• keep_domain
• no_keep_domain
• file_pattern
• path_group
• allow_read
• deny_rewrite
• alias

Used by /sys/kernel/security/tomoyo/domain_policy and /etc/tomoyo/domain_policy.conf

• allow_execute
• allow_read
• allow_write
• allow_read/write
• allow_create
• allow_unlink
• allow_mkdir
• allow_rmdir
• allow_mkfifo
• allow_mksock
• allow_mkblock
• allow_mkchar
• allow_truncate
• allow_symlink
• allow_link
• allow_rename
• allow_rewrite
• allow_chmod
• allow_chown
• allow_chgrp
• allow_ioctl
• allow_mount
• allow_unmount
• allow_chroot
• allow_pivot_root
• use_profile
• ignore_global_allow_read
• quota_exceeded
• transition_failed

Used by /sys/kernel/security/tomoyo/manager and /etc/tomoyo/manager.conf

• manage_by_non_root

2. Introduction

2.1 Word Expression Rules

TOMOYO Linux performs pathname based access control. A pathname may contain not only alphabet and number but also space and carriage return and multibyte (e.g. kanji) characters. Thus, to be able to handle any characters correctly, TOMOYO Linux follows the rules shown below to represent a word. A word means all tokens that are treated as string data, such as pathnames, comments.

• NUL character (0x00) is used for indicating end of string. Thus you cannot include \000 in a word.
• \ character (0x5C) is used for indicating octal expression. Thus, you need to use \\ to represent a \.
• Characters 0x01 - 0x20 and 0x7F - 0xFF are represented using octal expression \ooo .
• The rest characters (i.e. 0x21 - 0x5B and 0x5D - 0x7E) are represented as is.

• Space character (0x20) is used as a delimiter that separates words. Line feed character (0x0A) is used as a delimiter that separates lines.
• Only words that follow the rule above and the delimiters (i.e. space character and line feed characters) are valid. All other characters are regarded as space character. Multiple spaces are automatically compressed into one space. Leading and trailing spaces are automatically deleted.

Some examples are shown below.

Pathname must start with / character. Pathnames that end with / character are interpreted as directories, and that don't end with / character are interpreted as non-directories.

Exceptions are pipes and sockets. Pipes begin with "pipe:" and sockets begin with "socket:" when these pathnames are accessed via /proc/PID/fd/ directory.

2.2 Wildcard Expression Rules

Like temporary files, pathnames may contain randomly selected characters. Thus, you often need to define pathnames using wildcards. TOMOYO Linux supports wildcards shown below.

2.3 Word Length Rules

There is no limitation regarding the length of pathnames in Linux. But to perform pathname based access control, it is impossible to support pathnames with infinite length. Thus, in TOMOYO Linux, the length of a word is limited to 4000 bytes including trailing NUL character.

2.4 Line Length Rules

In TOMOYO Linux, the length of a line is limited to 8192 bytes including trailing NUL character.

2.5 Memory Allocation Rules

Regarding TOMOYO Linux for Kernel 2.6.33 and earlier, memory allocated for holding access permissions and words are never freed. There is no way except rebooting the system that can free unneeded memory.

But don't worry. The policy seldom changes after you start production mode. By tuning policy before starting production mode, you can reduce memory usage to (usually) less than 1 MB.

The memory used by TOMOYO Linux can be obtained via /sys/kernel/security/tomoyo/meminfo . The unit is byte. "Shared:" indicates memory used for holding words. "Private:" indicates memory used for holding access permissions. These memories never decrease. "Dynamic:" indicates memory used for temporary purpose such as access permission checks. This memory decreases when it became unneeded.

# cat /sys/kernel/security/tomoyo/meminfo

Shared:          65536
Private:         49152
Dynamic:          5106
Total:          119794

Regarding TOMOYO Linux for Kernel 2.6.34 and later, memory allocated for holding access permissions and words are automatically freed. There is no need to reboot the system to free unneeded memory.

The memory used by TOMOYO Linux can be obtained via /sys/kernel/security/tomoyo/meminfo . The unit is byte. "Policy:" indicates memory used for holding policy.

# cat /sys/kernel/security/tomoyo/meminfo
Policy:         119794
Total:          119794

3. Policy Files

3.1 Policy File's Location

Policy files are files that contain access permissions. These files are automatically loaded into the kernel upon boot.

When a system boots, /sbin/init is executed. When the execution of /sbin/init is requested and if /sbin/tomoyo-init exists, /sbin/tomoyo-init is executed, and /sbin/init is executed after /sbin/tomoyo-init terminates.

/sbin/tomoyo-init loads policy files in /etc/tomoyo/ directory via the kernel's /sys/kernel/security/tomoyo/ interface.

There are more interfaces for obtaining information. These interfaces don't have corresponding policy files.

3.2 Policy File's Modification

Register the name of programs or domains that can modify policy via the kernel's /sys/kernel/security/tomoyo/ interface. Only

• Processes with programs listed in /sys/kernel/security/tomoyo/manager
• Processes with domainnames listed in /sys/kernel/security/tomoyo/manager

can modify policy via the kernel's /sys/kernel/security/tomoyo/ interface. Some examples are show below.

By default, only processes with UID = 0 and EUID = 0 can modify policy via this interface. But by doing configurations described in Allowing policy modification by non root user., non root user can modify policy via this interface.

Exception is, processes that belong to domains with profiles for learning mode can append access permissions to /sys/kernel/security/tomoyo/domain_policy by simply requesting the access.

4. Domain Rules

4.1 Domain Definition

TOMOYO Linux gives access permissions as per a domain. The file which contains access permissions is called domain policy and is managed via /sys/kernel/security/tomoyo/domain_policy.

In TOMOYO Linux, every process belongs to a single domain, and all programs belong to different domain. Even the two processes are executing the same program, if their previous domains differ, they belong to different domain.

All domains are defined originating from "<kernel>" domain, which the kernel process belongs to. Since /sbin/init is invoked by the "<kernel>" domain, the domain for /sbin/init is defined as "<kernel> /sbin/init". Since /etc/rc.d/rc is invoked by /sbin/init invoked by the kernel, the domain for /etc/rc.d/rc is defined as "<kernel> /sbin/init /etc/rc.d/rc".

4.2 Domain Transition

There are some programs that behave differently depending on the invocation name. For example, /sbin/pidof is a symbolic link to /sbin/killall5 . Since TOMOYO Linux uses canonicalized pathname, by default, if /sbin/pidof is executed, the domain is defined as if /sbin/killall5 is executed.

When a process tries to execute a program, the steps shown below are performed.

5. Syntax Details

/sys/kernel/security/tomoyo/profile

List up functions and their modes in "$number-$variable=$value" format. The $number is profile number between 0 and 255. To modify profile, use "tomoyo-setlevel" or "tomoyo-loadpolicy" commands.

Each domain is assigned one profile. To assign profile to domains, use "tomoyo-setprofile" or "tomoyo-editpolicy" or "tomoyo-loadpolicy" commands.

You can see profiles currently assigned to domains using "tomoyo-editpolicy" command.
You can see profiles currently assigned to processes using "tomoyo-pstree" command.
If you saved current policy using "tomoyo-savepolicy" command, the currently assigned profile number is saved as use_profile line of domain policy.

To read or modify current profiles, operate like below.

(Example)
cat /sys/kernel/security/tomoyo/profile
tomoyo-savepolicy -p
tomoyo-setlevel 1-MAC_FOR_FILE=learning
echo 1-MAC_FOR_FILE=learning | tomoyo-loadpolicy -p

See also: Policy File's Modification

MAC_FOR_FILE

Specifies access control level regarding file access requests.

MAX_ACCEPT_ENTRY

Limits the max number of ACL entries that are automatically appended during learning mode. Default is 2048.

TOMOYO_VERBOSE

Specifies whether to print domain policy violation messages or not.

/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.

To read or modify current domain policy, operate like below.

(Example) Selecting specific domain and appending ACLs. The domain will be created if nonexistent.
printf "<kernel> /sbin/init\nallow_read /etc/passwd\n" | tomoyo-loadpolicy -d

(Example) Selecting specific domain and appending ACLs. The domain won't be created if nonexistent.
printf "select <kernel> /sbin/init\nallow_read /etc/passwd\n" | tomoyo-loadpolicy -d

(Example) Selecting specific domain and removing ACLs.
printf "select <kernel> /sbin/init\ndelete allow_read /etc/passwd\ndelete allow_read /etc/shadow\n" | tomoyo-loadpolicy -d

(Example) Deleting specific domain.
printf "delete <kernel> /sbin/init\n" | tomoyo-loadpolicy -d

(Example) Reading current domain policy.
cat /sys/kernel/security/tomoyo/domain_policy

See also: Policy File's Modification

allow_execute

This keyword grants execution of the specified pathname. No wildcards are permitted for the pathname.

(Example) allow_execute /bin/ls

See also: Domain Transition

allow_write

This keyword grants the specified pathname to be opened for writing.

(Example) allow_write /dev/null

allow_read

This keyword grants the specified pathname to be opened for reading.

(Example) allow_read /proc/meminfo

allow_read/write

This keyword grants the specified pathname to be opened for reading and writing.

(Example) allow_read/write /dev/null

allow_create

This keyword grants the specified pathname to be created.

(Example) allow_create /var/lock/subsys/crond

allow_unlink

This keyword grants the specified pathname to be deleted.

(Example) allow_unlink /var/lock/subsys/crond

allow_mkdir

This keyword grants the specified pathname to be created. The pathname must be a directory.

(Example) allow_mkdir /tmp/logwatch.\*/

allow_rmdir

This keyword grants the specified pathname to be deleted. The pathname must be a directory.

(Example) allow_rmdir /tmp/logwatch.\*/

allow_mkfifo

This keyword grants creation of FIFO by the specified pathname.

(Example) allow_mkfifo /dev/initctl

allow_mksock

This keyword grants creation of UNIX domain socket by the specified pathname.

(Example) allow_mksock /dev/log

allow_mkblock

This keyword grants creation of block device file by the specified pathname.

(Example) allow_mkblock /dev/\*

allow_mkchar

This keyword grants creation of character device file by the specified pathname.

(Example) allow_mkchar /dev/\*

allow_truncate

This keyword grants the specified pathname to be truncated or extended.

(Example) allow_truncate /etc/mtab

allow_symlink

This keyword grants creation of symbolic link by the specified pathname.

(Example) allow_symlink /dev/cdrom

allow_link

This keyword grants creation of hard link by the specified pathnames.

(Example) allow_link /etc/mtab~\$ /etc/mtab~

allow_rename

This keyword grants renaming of the specified pathnames.

(Example) allow_rename /etc/mtab.tmp /etc/mtab

allow_rewrite

This keyword grants the specified pathname to be rewritten when the pathname is specified by deny_rewrite keyword.

(Example) allow_rewrite /var/log/messages

See also: deny_rewrite

allow_chmod

This keyword grants changing DAC's permissions. (Valid only in Kernel 2.6.34 and later)

(Example) allow_chmod /dev/mem

allow_chown

This keyword grants changing DAC's owner. (Valid only in Kernel 2.6.34 and later)

(Example) allow_chown /dev/sda

allow_chmod

This keyword grants changing DAC's group. (Valid only in Kernel 2.6.34 and later)

(Example) allow_chgrp /dev/audio

allow_ioctl

This keyword grants doing IOCTL request with the specified pathnames. (Valid only in Kernel 2.6.34 and later)

(Example) allow_ioctl socket:[\$]

allow_mount

This keyword grants mounting on the specified location. (Valid only in Kernel 2.6.34 and later)

(Example) allow_mount /proc/

allow_unmount

This keyword grants unmounting from the specified location. (Valid only in Kernel 2.6.34 and later)

(Example) allow_unmount /mnt/cdrom/

allow_chroot

This keyword grants changing root directory to the specified location. (Valid only in Kernel 2.6.34 and later)

(Example) allow_chroot /var/empty/sshd/

allow_pivot_root

This keyword grants exchanging root directory with the specified location. (Valid only in Kernel 2.6.34 and later)
Usually, you don't need this keyword.

use_profile

This keyword indicates the profile number currently assigned to this domain. The profile number is an integer between 0 and 255.

ignore_global_allow_read

This keyword ignores pathnames specified by allow_read keyword in exception policy. You can use this keyword for domains you want to ignore globally readable files.

See also: allow_read

quota_exceeded

This keyword indicates that this domain has failed to append entry in learning mode since the number of entries reached to the limit specified by MAX_ACCEPT_ENTRY keyword. You need to reduce the number of entries for this domain by tuning policy.

See also: MAX_ACCEPT_ENTRY

transition_failed

This keyword indicates that this domain has failed to create a new domain since "the name of the domain to be created was too long" or "the kernel was unable to allocate memory" but processed the execute request without domain transition to avoid rejecting the execute request. You need to consider "suppressing domain transitions" or "increasing memory quota" if you are planning to assign a profile with MAC_FOR_FILE=enforcing to this domain.

See also: keep_domain Enabling quota for memory used for holding policy.

/sys/kernel/security/tomoyo/exception_policy

To read or modify current exception policy, operate like below.

(Example)
echo 'file_pattern /proc/\$/status' | tomoyo-loadpolicy -e
echo 'delete file_pattern /proc/\$/status' | tomoyo-loadpolicy -e
cat /sys/kernel/security/tomoyo/exception_policy

See also: Policy File's Modification

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.

When file access requests arise in learning mode ( profile's MAC_FOR_FILE is set to "learning" ) , the requested pathname is automatically patterned according to patterns specified using this keyword. This keyword does not affect modes other than learning mode. This keyword is used for only reducing the burden of policy tuning which is needed after the learning mode by making already known pathname patterns as templates.

path_group

To declare pathname group, use path_group keyword followed by name of the group and pathname pattern. (Valid only in Kernel 2.6.35 and later)
For example, if you want to group all files under home directory, you can define

in the exception policy and use like

to grant file access permission.

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 ignored.

See also: allow_read ignore_global_allow_read

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.

See also: allow_rewrite

alias

To allow executing programs using the name of symbolic links, use alias keyword followed by dereferenced pathname and reference pathname. This keyword is intended to allow programs that behave differently depending on the name of invocation and that referenced using symbolic links instead of hard links transit domain using the symbolic link's name.

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 .

See also: allow_execute

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.

See also: Domain Transition no_initialize_domain

no_initialize_domain

To deny the effect of "initialize_domain" directive, use "no_initialize_domain" directive.

• no_initialize_domain "program" from "domain"
• no_initialize_domain "program" from "the last program part of domain"
• no_initialize_domain "program"

Use this directive when you don't want to initialize domain transition.

See also: Domain Transition initialize_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.

See also: Domain Transition no_keep_domain

no_keep_domain

To deny the effect of "keep_domain" directive, use "no_keep_domain" directive.

• no_keep_domain "program" from "domain"
• no_keep_domain "program" from "the last program part of domain"
• no_keep_domain "domain"
• no_keep_domain "the last program part of domain"

Use this directive when you want to escape from a domain that is kept by "keep_domain" directive.

See also: Domain Transition keep_domain

/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.

manage_by_non_root

By default, only processes with both UID = 0 and EUID = 0 can modify policy via /sys/kernel/security/tomoyo/ interface. You can use this keyword to allow policy modification by non root user.

/sys/kernel/security/tomoyo/.domain_status

This is a view (of a DBMS) that contains only profile number and domainnames of domain so that "tomoyo-setprofile" command can do line-oriented processing easily.

/sys/kernel/security/tomoyo/meminfo

This file is to show the total RAM used to keep policy in the kernel by TOMOYO Linux.

(Example)
cat /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.

(Example)
cat /sys/kernel/security/tomoyo/self_domain

/sys/kernel/security/tomoyo/.process_status

This file is used by "tomoyo-pstree" 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.

/sys/kernel/security/tomoyo/version

This file is used for getting TOMOYO Linux's version.

(Example)
cat /sys/kernel/security/tomoyo/version

6. Advanced Features

6.1 Allowing policy modification by non root user.

By default, only processes with both UID = 0 and EUID = 0 can modify policy via /sys/kernel/security/tomoyo/ interface. But if you want to permit policy modification via /sys/kernel/security/tomoyo/ interface by non root user, you can write this keyword like

to disable UID and EUID checks. Also, you can write this keyword like

to enable UID and EUID checks again. Use chown/chmod as needed since the owner of /sys/kernel/security/tomoyo/ interface is root.
To be able to do this steps, /sbin/tomoyo-init also executes /etc/tomoyo/tomoyo-post-init if /etc/tomoyo/tomoyo-post-init is executable. Therefore, to allow access to /sys/kernel/security/tomoyo/ interface by user demo, create /etc/tomoyo/tomoyo-post-init with

and initialize like

Then, user demo will be able to access policy directories and policy editors.

6.2 Enabling quota for memory used for holding policy.

You can use memory quota for limiting maximum memory allocated for holding TOMOYO Linux's policy.

You can set memory quota by writing to /sys/kernel/security/tomoyo/meminfo like below from /etc/tomoyo/tomoyo-post-init .

(For Kernel 2.6.33 and earlier)

(For Kernel 2.6.34 and later)

Return to index page.