Info: Version 1.3 is available.

# Policy Specifications of TOMOYO Linux

Last modified: $Date: 2011-07-01 13:55:23 +0900 (Fri, 01 Jul 2011) $

# Index

## 1. Introduction

1.1 Word definition

1.2 DOMAIN definitions and DOMAIN transitions rule

## 2. Types and syntaxes of policy files

2.1 Policy Manager Definition (manager.txt)

2.2 Initial Control Status Definition

2.3 System policy (system_policy.txt)

2.4 DOMAIN policy (domain_policy.txt)

2.5 Exception policy (exception_policy.txt)

2.6 Mapping Definition (mapping.txt)

## 3. /proc/ccs/ interface

3.1 status

3.2 policy/system_policy

3.3 policy/domain_policy

3.4 policy/exception_policy

3.5 policy/query

3.6 info/trusted_pids

3.7 info/deleted_pids

3.8 info/meminfo

3.9 info/grant_log

3.10 info/reject_log

3.11 info/self_domain

3.12 info/mapping

# 1. Introduction

## 1.1 Word definition

Canonicalized Pathname | A pathname that begins with "/" and contain neither symbolic links, "/./", "//" nor "/../" . (There is one exception. Process information directory for current process that is accessible via "/proc/self/" directory is represented as is.) Even if a process is running under chroot'ed environment, Canonicalized Pathname is calculated from outside the chroot'ed environment. Canonicalized Pathname contains only ASCII printable range (from 0x21 to 0x7E) characters. Thus, "\" character (0x5C) itself is represented as "\\", and all other non-printable characters (from 0x01 to 0x20, from 0x7F to 0xFF) are represented using octal expressions("\ooo") (for example, the space character (0x20) is represented as "\040").
Canonicalized Directory | A Canonicalized Pathname that ends with "/".
Canonicalized File | A Canonicalized Pathname that doesn't end with "/". Canonicalized File includes all file types other than directory (i.e. regular file, character device, block device, FIFO, symbolic link, socket).
PROGRAM | A Canonicalized File that is executable.
DOMAIN | An attribute that is used for MAC (Mandatory Access Control).
Source DOMAIN | A DOMAIN that the process belongs to.
Destination DOMAIN | A DOMAIN that the process will belong to if the process successfully executes a PROGRAM.
Target DOMAIN | A DOMAIN that the target process belongs to.

## 1.2 DOMAIN definitions and DOMAIN transitions rule

In TOMOYO Linux, every process belongs to a single DOMAIN, and all PROGRAM 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".

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, if /sbin/pidof is executed, the DOMAIN is defined as if /sbin/killall5 is executed.

When a process tries to execute a PROGRAM, the following steps are performed.

Step | Procedure
Getting program's name | Get the name of PROGRAM that the process is going to execute and keep it as "Candidate 1". This procedure dereferences if the program is a symbolic link.
Handling symbolic links | Check whether "Candidate 1" matches to the pathnames declared with "alias" directives in exception policy. If they don't match, proceed to the next step. Get the name of PROGRAM that the process is going to execute and keep it as "Candidate 2". This procedure does NOT dereference if the program is a symbolic link. Compare "Candidate 1" and "Candidate 2". If they are equal, proceed to the next step. Check whether the combination of "Candidate 1" and "Candidate 2" matches to the combinations of pathnames declared with "alias" directives in exception policy. If they match, replace "Candidate 1" with "Candidate 2".
Aggregating similar programs | Check whether the "Candidate 1" matches to the pathname patterns declared with "aggregator" directives in exception policy. If they match, replace "Candidate 1" with the pathname declared with "aggregator" directives.
Checking argv[0] | Check whether the combination of "Candidate 2" and argv[0] is allowed by "allow_argv0" directive if the basename of "Candidate 2" and the basename of argv[0] differ.
Checking permission | Check whether Source DOMAIN is allowed to execute "Candidate 1".
Deciding Destination DOMAIN | Check whether "Candidate 1" matches to the pathnames declared with "initializer" directives in exception policy. If they match, concatenate the name of the DOMAIN that the kernel belongs to (i.e. <kernel>) and "Candidate 1" and keep the result as Destination DOMAIN, and check whether the Destination DOMAIN is defined. If they don't match, check whether the name of the DOMAIN the current process belongs to starts with name of DOMAINs declared with "trust_domain" directives in exception policy. If so, keep the name of the DOMAIN the current process belongs to as Destination DOMAIN. If not, concatenate the name of the DOMAIN the current process belongs to and "Candidate 1" and keep the result as Destination DOMAIN, and check whether the Destination DOMAIN is defined.
DOMAIN transition | Regular steps for executing PROGRAM are performed. If the regular steps for executing PROGRAM successfully completed, the process transits to Destination DOMAIN

# 2. Types and syntaxes of policy files

All policy files are kept in /root/security/ directory. Files in this directory are automatically loaded when /sbin/init starts.

## 2.1 Policy Manager Definitions (manager.txt)

Since it is not secure that all processes can modify policies, this file defines PROGRAM that can do write access to /proc/ccs/ interface.

PROGRAM that are not declared in this file cannot do write access to /proc/ccs/ interface. If you don't allow policy updates at production state, delete this file.

(Example)
/root/ccstools/loadpolicy
/root/ccstools/editpolicy
/root/ccstools/setlevel
/root/ccstools/ld-watch
/root/ccstools/ccs-queryd

## 2.2 Initial Control Status Definition

TOMOYO Linux can perform several MACs besides MAC for files, but to reduce the load of policy managements, you can disable MACs you think unnecessary. You can switch the MACs and their initial control status by creating several profiles and specifying the profile index number at kernel command line.

Variable | Meaning | Accept mode support
MAC_FOR_FILE | Enable Mandatory Access Control(MAC) for files. | Yes
MAC_FOR_ARGV0 | Enable MAC for argv[0] checks. | Yes
MAC_FOR_CAPABILITY::*** | Enable MAC for capabilities. The *** matches to values that can be given using allow_capability directive described in DOMAIN policy. | Yes
MAC_FOR_NETWORK | Enable MAC for network addresses and ports. | Yes
MAC_FOR_BINDPORT | Enable MAC for local ports. This is a subset of MAC_FOR_NETWORK. | Yes
MAC_FOR_CONNECTPORT | Enable MAC for remote ports. This is a subset of MAC_FOR_NETWORK. | Yes
MAC_FOR_SIGNAL | Enable MAC for signal. | Yes
DENY_CONCEAL_MOUNT | Forbid mount requests that hides an existing mount. | No
RESTRICT_CHROOT | Enable restrictions for chroot directories. | Yes
RESTRICT_MOUNT | Enable restrictions for mount parameters. | Yes
RESTRICT_UNMOUNT | Forbid unmount requests for specified directories. | No
DENY_PIVOT_ROOT | Forbid pivot_root requests. | No
RESTRICT_AUTOBIND | Forbid selecting specific local port number when automatic local port binding happens. | No
TRACE_READONLY | Dump Canonicalized Pathname that write requests failed due to read only filesystem. | -
MAX_ACCEPT_FILES | Limits the max number of file ACL entries that are automatically appended during accept mode. | -
MAX_GRANT_LOG | Limits the max number of grant logs that the kernel can hold. | -
MAX_REJECT_LOG | Limits the max number of reject logs that the kernel can hold. | -
TOMOYO_VERBOSE | Dump domain policy violation messages to syslog. | -
MAX_ENFORCE_GRACE | Allowed grace time in seconds before rejecting access request when the request violates policy in enforce mode. | -

You can give the following values for TRACE_READONLY and RESTRICT_AUTOBIND

Value | Meaning
0 | Off. Works as if regular kernel.
1 | On.

You can give the following values for MAX_ACCEPT_FILES

Value | Meaning
any integer | The max number of file ACL entries that are automatically appended during accept mode. The default is given at the kernel compilation time.

You can give the following values for MAX_GRANT_LOG and MAX_REJECT_LOG

Value | Meaning
any integer | The max number of logs that the kernel can hold. The default is given at the kernel compilation time.

You can give the following values for TOMOYO_VERBOSE

Value | Meaning
0 | Don't dump domain policy violation messages.
1 | Dump domain policy violation messages.

You can give the following values for MAX_ENFORCE_GRACE

Value | Meaning
any integer | The max grace time in seconds. If the administrator tells the kernel not to reject the request that violated policy in enforce mode, the request will be granted.

You can give the following values for all but listed above.

Value | Meaning
0 | Disabled. Works as if regular kernel.
1 | Accept mode. Not rejected if the request violates policy. Automatically appended to policy.
2 | Permissive mode. Not rejected if the request violates policy. Not appended to policy automatically.
3 | Enforce mode. Rejected if the request violates policy.

Create /root/security/profile$INDEX.txt (where $INDEX is an integer) and list "Variable=Value" pairs in it.

(Example) Kernel command line options:

CCS=0 | Use /root/security/profile0.txt . This is the default.
CCS=1 | Use /root/security/profile1.txt .
CCS=2 | Use /root/security/profile2.txt .

## 2.3 System policy (system_policy.txt)

This file contains permissions that apply to the entire system. The following 4 types of permissions are declared.

- Mount permission
- Directories that don't allow to be unmounted
- Directories that are allowed to chroot to
- Local ports that don't allow to be bound automatically

### Mount permission

To grant mount permission, use allow_mount directive followed by "$devicefile $mountpoint $filesystem $options".
The $devicefile need to be a Canonicalized File if the $filesystem requires device file.
The $mountpoint must be a Canonicalized Directory.
The $options are the choice of dev,nodev,exec,noexec,suid,nosuid,rw,ro,atime,noatime,diratime,nodiratime,recurse,norecurse. The $options overrides the user's requests. For example, if rw is given for $options, the kernel will mount for read-write even if the user requested to mount for read-only. The $options can be omitted.

To grant "mount -o remount $mountpoint" permission, use allow_mount directive followed by "any $mountpoint --remount $options".

To grant "mount --bind $source_dir $dest_dir" and "mount --move $source_dir $dest_dir" permission, use allow_mount directive followed by "$source_dir $dest_dir --bind" and "$source_dir $dest_dir --move" respectively. The $source_dir and $dest_dir must be Canonicalized Directory.

Kernel 2.6.15 and later supports "Shared Subtree" functionality.
To grant "mount --make-unbindable $mountpoint" permission, use allow_mount directive followed by "any $mountpoint --make-unbindable $options".
To grant "mount --make-private $mountpoint" permission, use allow_mount directive followed by "any $mountpoint --make-private $options".
To grant "mount --make-slave $mountpoint" permission, use allow_mount directive followed by "any $mountpoint --make-slave $options".
To grant "mount --make-shared $mountpoint" permission, use allow_mount directive followed by "any $mountpoint --make-shared $options".
The $options are either recurse or norecurse. The $options overrides the user's requests. For example, if recurse is given for $options, the kernel will mount for recurse even if the user requested to mount for norecurse. The $options can be omitted.

### Directories that don't allow to be unmounted

To reject unmount request, use deny_unmount directive followed by a Canonicalized Directory.

Usually, specify /dev/ directory (that contains /dev/tty? used by /sbin/mingetty) and /dev/pts/ directory (that are used to create pty device files for remote login).

If /dev/ becomes read-only or /dev/pts/ is unmounted, you can't login to the system.
Therefore /dev/ and /dev/pts/ must not be unmounted for systems where / is read-only.

### Directories that are allowed to chroot to

To grant chroot permission, use allow_chroot directive followed by a Canonicalized Directory.

Usually, grant /var/empty/sshd/ that sshd uses.
In addition, if you have applications that runs in the chroot'ed environment or applications that uses chroot (for example, /usr/share/empty/ is used by vsftpd), grant such directories too.

### Local ports that don't allow to be bound automatically

To prevent specific local port from being selected automatically, use deny_autobind directive followed by local port number.

This directive is intended to prevent specific local port from being bound for temporary use.
For example, some proxy server uses local port 8080, so port 8080 should not be bound by other PROGRAMs for temporary use.

### (Example)

allow_mount | none | /dev/pts/ | devpts
allow_mount | /proc | /proc/ | proc
allow_mount | usbdevfs | /proc/bus/usb/ | usbdevfs
allow_mount | none | /data/ | tmpfs nosuid,nodev,noexec
allow_mount | none | /dev/shm/ | tmpfs nosuid,nodev,noexec
allow_mount | /dev/hdc | /var/www/ | ext2 ro,nosuid,nodev,noexec
allow_mount | any | / | --remount
deny_unmount | /dev/
deny_unmount | /dev/pts/
deny_unmount | /proc/
allow_chroot | /var/empty/sshd/
allow_chroot | /usr/share/empty/
allow_chroot | /var/www/html/
allow_chroot | /
deny_autobind | 1-1023
deny_autobind | 8080

## 2.4 DOMAIN policy (domain_policy.txt)

This file contains permissions that apply to DOMAIN. The following 7 types of permissions are declared.

- MAC for files
- MAC for argv[0]
- MAC for capabilities
- MAC for network addresses and ports
- MAC for local ports
- MAC for remote ports
- MAC for signals

You may specify additional condition for each permissions as needed. The syntax for additional condition is described later.

This file contains all DOMAIN definitions. Lines from the next line to a DOMAIN definition to the previous line to the next DOMAIN definitions are interpreted as access permissions for that DOMAIN.

### MAC for files

To grant file permission, use the following directives.

Directive | Granted Operation | Example
1 | Execute | 1 /bin/ls
2 | Write | 2 /dev/null
3 | Write and Execute |
4 | Read | 4 /proc/meminfo
5 | Read and Execute |
6 | Read and Write | 6 /dev/null
7 | Read and Write and Execute |
allow_create | Create regular file | allow_create /var/lock/subsys/crond
allow_unlink | Delete non-directory | allow_unlink /var/lock/subsys/crond
allow_mkdir | Create directory | allow_mkdir /tmp/logwatch.\*/
allow_rmdir | Remove directory | allow_rmdir /tmp/logwatch.\*/
allow_mkfifo | Create FIFO | allow_mkfifo /dev/initctl
allow_mksock | Create UNIX doimain socket | allow_mksock /dev/log
allow_mkblock | Create block device file | allow_mkblock /dev/\*
allow_mkchar | Create character device file | allow_mkchar /dev/\*
allow_truncate | Truncate or expand | allow_truncate /etc/mtab
allow_symlink | Create symbolic link | allow_symlink /dev/cdrom
allow_link | Create hard link | allow_link /etc/mtab~\$ /etc/mtab~
allow_rename | Rename | allow_rename /etc/mtab.tmp /etc/mtab

You may use wildcards for directives other than 1 3 5 and 7. You should avoid using directives 3 5 and 7 as hard as possible.

You may use one of directives 2 3 6 or 7 in place with directives that starts with "allow_" via Mapping Definition.

### MAC for argv[0]

To restrict the contents of argv[0], use allow_argv0 directive followed by "the pathname of program without dereferencing symbolic links" and "the basename part of argv[0]".

The execve() system call, which is used to execute a program, accepts filename and argv[] and envp[], sometimes, there are programs that behave differently depending on the basename of argv[0]. The busybox is an example. The domain transition of TOMOYO Linux is done based on the contents of filename. In most cases, the basename of filename and the basename of argv[0] are identical and are no problem, but there are programs such as binary wrapper that intentionally pass different filename and argv[0]. For example, passing /bin/ls which is a symbolic link to /sbin/busybox as the filename parameter and passing /bin/cat which is a symbolic link to /sbin/busybox as the argv[0] parameter will cause TOMOYO Linux behave as /bin/cat in the domain of /bin/ls, which is a incongruous situation. This means that if an attacker succeeds passing different filename and argv[0] intentionally, this will become a security hole. The purpose of this directive is to restrict the combinations of filename and argv[0] so that such incongruous situation won't occur.

### MAC for capabilities

To grant capability permission, use allow_capability directive followed by a capability.
The following capabilities are applicable.

Value | Meaning
inet_tcp_create | Grant socket(PF_INET or PF_INET6, SOCK_STREAM, *)
inet_tcp_listen | Grant listen() for PF_INET or PF_INET6, SOCK_STREAM
inet_tcp_connect | Grant connect() for PF_INET or PF_INET6, SOCK_STREAM
use_inet_udp | Grant socket(PF_INET, SOCK_DGRAM, *)
use_inet_ip | Grant socket(PF_INET, SOCK_RAW, *)
use_route | Grant socket(PF_ROUTE, *, *)
use_packet | Grant socket(PF_PACKET, *, *)
use_kernel_module | Grant create_module(2) init_module(2) delete_module(2)
create_fifo | Grant mknod(2) for FIFO.
create_block_dev | Grant mknod(2) for block device.
create_char_dev | Grant mknod(2) for character device.
create_unix_socket | Grant mknod(2) for unix domain sockets.
SYS_MOUNT | Grant mount(2)
SYS_UMOUNT | Grant umount(2)
SYS_REBOOT | Grant reboot(2)
SYS_CHROOT | Grant chroot(2)
SYS_KILL | Grant kill(2) tkill(2) tgkill(2) with non-0 signal.
SYS_VHANGUP | Grant vhangup(2)
SYS_TIME | Grant stime(2) settimeofday(2) adjtimex(2)
SYS_NICE | Grant nice(2) setpriority(2)
SYS_SETHOSTNAME | Grant sethostname(2) setdomainname(2)
SYS_LINK | Grant link(2)
SYS_SYMLINK | Grant symlink(2)
SYS_RENAME | Grant rename(2)
SYS_UNLINK | Grant unlink(2)
SYS_CHMOD | Grant chmod(2) fchmod(2)
SYS_CHOWN | Grant chown(2) fchown(2) lchown(2)
SYS_IOCTL | Grant ioctl(2) compat_sys_ioctl(2)
SYS_KEXEC_LOAD | Grant kexec_load(2)

The purpose of allow_capability directive is to restrict system calls that a PROGRAM can call.
You can restrict more strictly with other directives and policy files for some system calls.

- You can restrict creation of block device files with allow_mkblock directive.
- You can restrict creation of character device files with allow_mkchar directive.
- You can restrict creation of FIFOs with allow_mkfifo directive.
- You can restrict creation of UNIX domain sockets with allow_mksock directive.
- You can restrict creation of symbolic links with allow_symlink directive.
- You can restrict deletion of non-directories with allow_unlink directive.
- You can restrict combination of pathnames that can be hard linked with allow_link directive.
- You can restrict combination of pathnames that can be renamed with allow_rename directive.
- You can restrict IP addresses and ports with allow_network directive.
- You can restrict local TCP or UDP ports with allow_bind directive.
- You can restrict remote TCP or UDP ports with allow_connect directive.
- You can restrict signal numbers and Target DOMAIN with allow_signal directive.
- You can restrict devices and directories with allow_mount directive.
- You can restrict directories that you don't allow unmount with deny_unmount directive.
- You can restrict directories that can chroot to with allow_chroot directive.

### MAC for networking addresses and ports

To grant permission for ports, use allow_network directive followed by protocol(TCP or UDP or RAW) and IP address and port number (for TCP or UDP) / protocol number (for RAW). This permission is applicable to IPv4 and IPv6.

Directive | Granted Operation | Example
allow_network TCP bind | Bind to local TCP address/port. | allow_network TCP bind 0.0.0.0 80
allow_network TCP listen | Listen to local TCP address/port. | allow_network TCP listen 0.0.0.0 80
allow_network TCP accept | Accept from and communicate with remote TCP address/port. | allow_network TCP accept 10.0.0.0-10.255.255.255 1024-65535
allow_network TCP connect | Connect to and communicate with remote TCP address/port. | allow_network TCP connect 127.0.0.1 1024-65535
allow_network UDP bind | Bind to local UDP address/port. | allow_network UDP bind 0.0.0.0 53
allow_network UDP connect | Communicate with remote UDP address/port. | allow_network UDP connect 127.0.0.1 53
allow_network RAW bind | Bind to local IP address/protocol. | allow_network RAW bind 127.0.0.1 255
allow_network RAW connect | Communicate with remote IP address/protocol. | allow_network RAW connect 10.0.0.1 1

Use of "::" for IPv6 address representation is not supported. You need to use "0:0:0:0:0:0:0:1" for "::1".

Permission check is not applied for recvmsg() with msg_name == NULL or read().

### MAC for local ports

To grant permission for local ports, use allow_bind directive followed by protocol(TCP or UDP) and port number. This permission is applicable to IPv4 and IPv6.

To grant automatic local port selection (i.e. calling bind() with port number = 0), use allow_bind TCP/0 or allow_bind UDP/0 . But this permission is not checked if the process calls connect() without calling bind().

To grant all local ports (1-65535), use allow_bind TCP/1-65535 (for TCP sockets) or allow_bind UDP/1-65535 (for UDP sockets).

### MAC for remote ports

To grant permission for remote ports, use allow_connect directive followed by protocol(TCP or UDP) and port number. This permission is applicable to IPv4 and IPv6.

To grant all remote ports (1-65535), use allow_connect TCP/1-65535 (for TCP sockets) or allow_connect UDP/1-65535 (for UDP sockets).

### MAC for signals

To grant permissions for signals, use allow_signal directive followed by signal number and Target DOMAIN.

There are two exceptions. If signal number is 0, it is always granted. If the Target DOMAIN and the Source DOMAIN are the same, it is always granted.

In other cases, signals are granted only when the signal number matches and the Target DOMAIN starts with the Target DOMAIN declared with this directive.

If only <kernel> is declared as a Target DOMAIN, the Source DOMAIN can send signals to any DOMAIN with that signal number.

### Conditional permission

TOMOYO Linux 1.2 supports conditional permission. The condition clause are appended to the tail of each permission using "if" directive.

Example | Meaning
4 /etc/passwd | Allow reading /etc/passwd .
4 /etc/passwd if task.uid=0 | Allow reading /etc/passwd if the process's UID is 0.
4 /etc/passwd if task.uid!=0 | Allow reading /etc/passwd if the process's UID is not 0.
allow_network TCP connect 10.0.0.1 80 | Connect to 10.0.0.1 port 80 using TCP.
allow_network TCP connect 10.0.0.1 80 if task.uid=100 | Connect to 10.0.0.1 port 80 using TCP if the process's UID is 100.
allow_capability SYS_KILL | Allow calling kill(2).
allow_capability SYS_KILL if task.ppid=1 task.uid=0 task.euid=0 | Allow calling kill(2) if the process is the child of /sbin/init and the process's UID is 0 and the process's EUID is 0.

The following variables are available.

Variable | Meaning
task.uid | UID of current process
task.euid | EUID of current process
task.suid | SUID of current process
task.fsuid | FSUID of current process
task.gid | GID of current process
task.egid | EGID of current process
task.sgid | SGID of current process
task.fsgid | FSGID of current process
task.pid | PID of current process
task.ppid | PID of parent process
path1.uid | UID of object.
path1.gid | GID of object.
path1.ino | i-node number of object.
path1.parent.uid | UID of object's parent directory.
path1.parent.gid | GID of object's parent directory.
path1.parent.ino | i-node number of object's parent directory.
path2.parent.uid | UID of object's parent directory.
path2.parent.gid | GID of object's parent directory.
path2.parent.ino | i-node number of object's parent directory.

"path1" corresponds to the first pathname of operations that requires pathnames, and "path2" corresponds to the second pathname of operations that requires pathnames. For example, the case of "allow_rename file1 file2", path1 corresponds to file1 and path2 corresponds to file2.

"path1.uid" and "path1.gid" are not available for pathnames that don't exist. Thus, you can't use when creating pathnames (such as allow_create directive).

"path1.parent.uid" and "path1.parent.gid" are always available.

"path2.parent.uid" and "path2.parent.gid" are available only for operations that require 2 pathnames (in other words, allow_link and allow_rename directives).

"path2.uid" and "path2.gid" are not supported. ( If "path2" already exist for "rename" operation, "unlink" or "rmdir" operation is performed implicitly.)

Neither "path1" nor "path2" are supported when accessing via "sysctl" ( i.e. accessing files under /proc/sys/ directories using "sysctl" instead for "open")

## 2.5 Exception policy (exception_policy.txt)

This file contains exceptions for DOMAIN access controls. The following 6 types of permissions are declared.

- Pathname pattern
- Unconditionally readable files
- DOMAIN transition initializers
- Programs invocable via symbolic links
- Program aggregations
- Trusted DOMAIN

### Pathname pattern

To declare pathname pattern, use file_pattern directive followed by pathname pattern. The pathname pattern must be a Canonicalized Pathname. This directive 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.

The following wildcards are available.

Value | Meaning
\\ | \ itself.
\* | Zero or more repetitions of characters other than '/'.
\@ | Zero or more repetitions of characters other than '/' or '.'.
\? | 1 byte character other than '/'.
\$ | One or more repetitions of decimal digits.
\+ | 1 decimal digit.
\X | One or more repetitions of hexadecimal digits.
\x | 1 hexadecimal digit.
\A | One or more repetitions of alphabet characters.
\a | 1 alphabet character.

### Unconditionally readable files

To grant unconditionally readable permissions, use allow_read directive followed by Canonicalized File. This directive is intended to reduce size of DOMAIN policy by granting read access to library files such as GLIBC and locale files. You should not grant password files such as /etc/passwd, for all process can read if DAC is granted.

### DOMAIN transition initializers

To declare DOMAIN transition initializers, use initializer directive followed by PROGRAM. 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.

When a process tries to execute a PROGRAM declared with this directive, the following steps are performed. Step 3 differs from regular rules.

### Programs invocable via symbolic links

To allow executing programs using the name of symbolic links, use alias directive followed by dereferenced pathname and reference pathname. This directive 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 .

### Program aggregations

To deal multiple programs as a single program, use aggregator directive followed by name of original program and aggregated program. This directive 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.

### Trusted DOMAIN

To declare trusted DOMAIN, use trust_domain directive followed by DOMAIN definition. This directive is intended to provide workspace for nonroutine tasks such as software update, by creating DOMAIN that are free from MACs for DOMAINs.

If the name of a DOMAIN starts with names declared with this directive, the DOMAIN is marked as "trusted". For processes that belong to DOMAIN that is marked as "trusted", the MACs for DOMAIN are not applied.

For example, if this file contains a line "trust_domain <kernel> /usr/sbin/sshd /bin/tcsh", "<kernel> /usr/sbin/sshd /bin/tcsh" DOMAIN and its descendents (such as "<kernel> /usr/sbin/sshd /bin/tcsh /bin/cat") are marked as "trusted".

Note that if this file contains a line "trust_domain <kernel>", all DOMAINs are marked as "trusted".

## 2.6 Mapping Definition (mapping.txt)

This file defines mappings of write access permission checks for files and directories. This file allows you switching the granularity of write access permission checks based on how fine-grained do you want to control write access permissions for files and directories.

The format of this file is a list of "item=method". An example is shown below.

create=generic-write unlink=generic-write mkdir=mkdir rmdir=rmdir mkfifo=mkfifo mksock=mksock mkblock=mkblock mkchar=mkchar truncate=generic-write symlink=symlink link=link rename=rename

If "generic-write" is specified as the method, the item is checked using permissions for directive 2 3 6 or 7. If "no-check" is specified as the method, the item is not checked. If a method same as the item's name, the item is checked using permissions for directive of the item.

This file is read only once at boot. You can't switch after boot.

# 3. /proc/ccs/ interface

This is the interface to read/append/delete policies after boot. Only PROGRAMs that are declared in Policy Manager Definition can append/delete policies.

## 3.1 status

This file is to get or set the value of current control status.

(Example)
cat /proc/ccs/status
echo 'MAC_FOR_FILE=1' > /proc/ccs/status

## 3.2 policy/system_policy

This file is to read, append or delete current System policy.

(Example)
echo 'allow_mount /proc /proc/ proc' > /proc/ccs/policy/system_policy
echo 'delete allow_mount /proc /proc/ proc' > /proc/ccs/policy/system_policy
cat /proc/ccs/policy/system_policy

## 3.3 policy/domain_policy

This file is to read, append or delete current DOMAIN policy.

(Example) Selecting specific DOMAIN and appending ACLs. The DOMAIN will be created if nonexistent.
printf "<kernel> /sbin/init\n4 /etc/passwd\n" > /proc/ccs/policy/domain_policy

(Example) Selecting specific DOMAIN and appending ACLs. The DOMAIN won't be created if nonexistent.
printf "select <kernel> /sbin/init\n4 /etc/passwd\n" > /proc/ccs/policy/domain_policy

(Example) Selecting specific DOMAIN and removing ACLs.
printf "select <kernel> /sbin/init\ndelete 4 /etc/passwd\ndelete 4 /etc/shadow\n" > /proc/ccs/policy/domain_policy

(Example) Deleting specific DOMAIN.
printf "delete <kernel> /sbin/init\n" > /proc/ccs/policy/domain_policy

(Example) Reading current DOMAIN policy.
cat /proc/ccs/policy/domain_policy

## 3.4 policy/exception_policy

This file is to read, append or delete current Exception policy.

(Example)
echo 'file_pattern /proc/\$/status' > /proc/ccs/policy/exception_policy
echo 'delete file_pattern /proc/\$/status' > /proc/ccs/policy/exception_policy
cat /proc/ccs/policy/exception_policy

## 3.5 policy/query

This file is used to manually grant or reject individual access requests when the policy violation occurs in enforce mode. If you didn't respond within MAX_ENFORCE_GRACE seconds from the occurence of policy violation, the access request is rejected automatically. This file is not used for stable state, but used only while doing operations such as updating packages that would cause unexpected access requests.

## 3.6 info/trusted_pids

This file is to show a list of PIDs that belong to "trusted" DOMAINs. This file is used to confirm that processes (especially, daemons) aren't running in "trusted" DOMAINs after your nonroutine tasks finished. Some PIDs may not be shown if there are too many to list up all PIDs.

(Example)
cat /proc/ccs/info/trusted_pids

## 3.7 info/deleted_pids

This file is to show a list of PIDs that belong to "deleted" DOMAINs.

(Example)
cat /proc/ccs/info/deleted_pids

## 3.8 info/meminfo

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

(Example)
cat /proc/ccs/info/meminfo

## 3.9 info/grant_log

This file holds the granted log. The reader process returns immediately if no granted logs exists. To wait until a granted log is generated, use select(2) for readability. The max number of logs that the kernel can hold is limited to MAX_GRANT_LOG, so read out timely.

(Example)
cat /proc/ccs/info/grant_log

## 3.10 info/reject_log

This file holds the rejected log. The reader process returns immediately if no violation logs exists. To wait until a violation log is generated, use select(2) for readability. The max number of logs that the kernel can hold is limited to MAX_REJECT_LOG, so read out timely.

(Example)
cat /proc/ccs/info/reject_log

## 3.11 info/self_domain

This file is to show the name of domain the caller process belongs to.

(Example)
cat /proc/ccs/info/self_domain

## 3.12 info/mapping

This file is to show the mapping of write access permission checks.

(Example)
cat /proc/ccs/info/mapping

Return to index