Info: Version 1.3 is available.

# Tools Documentation

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

## <<Tools for system administrators>>

Most administrators need tools only in this chapter and the next chapter.

### <Policy Editor "editpolicy">

Edits the current policy in /proc/ccs/policy/ directory.

You may give one of 's' 'e' 'd' to the commandline to choose the initial screen. If not given, screen for domain listing is shown.

Keys applicable to all screens

q/Q | Quit
r/R | Refresh
Up-arrow | Scroll 1 line up.
Down-arrow | Scroll 1 line down.
PageUp | Scroll 1 page up.
PageDown | Scroll 1 page down.

Keys applicable to screen for system policy

a/A | Add an entry.
d/D | Delete the selected entry.
Tab | Switch to screen for exception policy.

Keys applicable to screen for exception policy.

a/A | Add an entry.
d/D | Delete the selected entry.
Tab | Switch to screen for domain listing.

Keys applicable to screen for domain listing.

a/A | Create a domain.
d/D | Delete the selected domain and its descendants.
Tab | Switch to screen for system policy.
Enter | Switch to screen for editing ACLs for the selected domain.
@ | New search
Left-arrow | Search previous
Right-arrow | Search next

Keys applicable to screen for editing ACLs for the selected domain

Enter | Return to screen for domain listing.
a/A | Add an access permission.
d/D | Delete existing permission.

This program keeps pathnames on dynamically allocated memory on the first appearance of the pathname and never frees that memory until termination. This is to reduce memory for keeping filenames.

The same mechanism is used by the TOMOYO Linux kernel. The memory allocated by the kernel for keeping pathnames and access permissions is never freed. Therefore, you can't run in "accept mode" forever, otherwise the system falls into out of memory. But actual amount of extra memory consumed by TOMOYO Linux kernel, though it depends on the number of domains and number of access permissions for domains, is less than 1 MB in most systems.

The memory for keeping access logs is allocated dynamically, and is freed as soon as the userland program reads the log. Also, there is a limitation for the maximum number of logs that the kernel can keep, therefore the system won't become out of memory even if the userland program doesn't read the logs.

### <Policy Loader "loadpolicy">

Reloads the on-disk policy onto memory.

There are the following commandline parameters.

- s --- Reload system policy.
- e --- Reload exception policy.
- d --- Reload domain policy.
- a --- Reload the above three policies.
- f --- Erase on-memory policy before loading.

### <Access control level changer "setlevel">

Changes the current control level (i.e. writing to /proc/ccs/status ) and displays the new control level.

You can give the new control level from commandline parameter.

Only programs that are listed in /root/security/manager.txt can write to /proc/ccs/ directory. You may use shells and /bin/cat for accept mode, but you should list only loadpolicy editpolicy setlevel for production state.

### <Policy Saver "savepolicy">

Saves the on-memory policy onto disk.

There are the following commandline parameters.

- s --- Save system policy.
- e --- Save exception policy.
- d --- Save domain policy.
- a --- Save the above three policies.
- f --- Save even if on-memory policy and on-disk policy are same.

### <Template generator for SYAORAN filesystem "makesyaoranconf">

Generates syaoran.conf, the configuration file for SYAORAN (the Tamper-Proof /dev filesystem). You can use SYAORAN filesystem if you want to run the system with read-only root fs or you want to prevent device files from tampering.

You can't create files that are not listed in the configuration file. If the system creates device files dynamically, attach all necessary devices before executing this program to ensure all device files are listed in the configuration file.

### <Access log reader daemon "ccs-auditd">

Reads from /proc/ccs/info/grant_log and /proc/ccs/info/reject_log and writes to the location given in the commandline parameters.

The first commandline parameter is the location of access granted log. The second one is the location of access rejected log. You may give /dev/null as the location. If you needn't to save access logs, you needn't to run this program.

This program runs as a daemon. You can start from /etc/rc.d/rc.local if you are using RedHat Linux. The number of logs that the kernel will keep is given using "MAX_GRANT_LOG=integer" and "MAX_REJECT_LOG=integer" lines in the profile.

### <Temporal pathnames detector "findtemp">

Reads domain policy from standard input and checks the existence of pathnames that contains write permission, and dumps the nonexistent pathnames.

The nonexistent pathnames with write permission are likely used as temporary pathnames. So find the naming rules from similar nonexistent pathnames and append the pattern to /root/security/exception_policy.txt and /proc/ccs/policy/exception_policy .

If "--all" is given as a commandline parameter, this program will report all nonexistent pathnames.

You can pass the content of /root/security/domain_policy.txt or /proc/ccs/policy/domain_policy using redirection or pipes to the standard input of this program.

### <Library pathnames updater "ld-watch">

Appends shared libraries to exception policy automatically using "allow_read" directive when the location of shared libraries in /etc/ld.so.cache has changed.

By running this program while updating packages, you can avoid errors "unable to start applications because shared libraries are unreadable" when the pathnames of shared libraries accessed by general programs has changed.

### <Delayed enforcing mode handler "ccs-queryd">

Detects policy violation and displays the access request. You can tell the system whether the access request should be granted (or granted and policy should be appended to grant the access request) or rejected after you validate the access request.

By running this program while updating packages, you can avoid errors due to insufficient permissions.

Never grant access requests unconditionally. The cause of policy violation is not always updating packages, but may by malicious requests by attackers. If you grant access requests caused by malicious requests by attackers, the system gets intruded.

To use this program, you need to set "MAX_ENFORCE_GRACE=integer" in /proc/ccs/status where integer is the grace time in seconds.

## <<Tools for reinforcing login authentications>>

The programs described in this chapter are used only when you want to reinforce login authentications.

### <Restricted login shell for authentication "falsh">

A tiny shell that have no built-in command such as kill. You can use this program for login shell ( the shell specified in the /etc/passwd file). You won't need this program if you don't want to reinforce login authentications.

You should make your own programs for additional authentications. You shouldn't use the following example programs without modifications.

### <An example program for password authentication with timings "honey">

This program fails unless the correct password is typed with the correct time interval. Conventional authentication programs don't check the time interval of typing, but this program does to prevent password brute force attack.

### <An example program for password authentication with time limit "candy"

This program fails unless the correct password is typed and this program was invoked within 10 seconds after the parent process was invoked. Conventional authentication programs don't check the time interval between the invocation time of parent process and the invocation time of child process, but this program does to prevent password brute force attack.

### <An example program for lockfile authentication "groovy">

This program fails while the file /tmp/.lockme exists. This program prompts for password, but doesn't check for password. This program checks for the existence of the file /tmp/.lockme . This program prevents password brute force attack by keeping locked just before you run this program. This is a program for demonstration, and using a filename that are apparent to crackers. You must customize if you want to use.

### <An example program for token authentication "gettoken / checktoken">

This program generates tokens by according to the system time. The authentication will succeed if the output of gettoken is passwd to the input of checktoken. These are programs for demonstration, and the algorithm is too poor. You must customize if you want to use.

### <An example program for challenge-handshake authentication "chaplet">

This program displays strings as a challenge data. The authentication will succeed if you input only numerical letters from the challenge data as a response data. This is a program for demonstration, and the algorithm is too poor. You must customize if you want to use.

## <<Tools for working with read-only root filesystem.>>

The programs described in this chapter are used only when you want to run your system with read-only root filesystem.

### <Conditional remounter "remount_rootfs">

Remounts root fs in read-write mode and enables swap partitions. Unmounts forcefully initrd-loop.img mounted on /initrd/ .

If the kernel commandline includes "readonly", root fs is not remounted. If the kernel commandline includes "noswap", swap partitions are not enabled.

### <Initial RAM disk for loopback mount image "initrd-loop.img">

This is an initial RAM disk that includes linuxrc for a loopback mountable root filesystem image. You can use this initial RAM disk if you are using a loopback mount image for root fs. It is possible to do loopback mount with standard nash program, but nash script can't handle errors and continue running until kernel panic. This program can stop on error.

If the original linuxrc (which is a nash script) exists as linuxrc.org , this linuxrc reads linuxrc.org , and processes lines that starts with insmod or sleep. linuxrc uses external insmod command to handle insmod request, you need to include insmod in the initrd-loop.img if you want to use insmod. But if insmod requires dynamic link library files, the initrd-loop.img will become larger, so you should built-in modules into the kernel that needs to be loaded by linuxrc .

If the file /.linuxrc exists in the loopback mounted root fs, it is executed before linuxrc terminates.

The location of the loopback mountable root fs is given from the kernel commandline using ROOTIMG= parameter. The default is /rootimg .

The device name that contains the loopback mountable root fs is given using root= parameter. But you need to give it by device file name. root=LABEL=/ can't be interpreted, for linuxrc is not a nash script.

The filesystem type of the loopback mountable root fs is given using IMAGE= parameter. The filesystem type of device which contains the loopback mountable root fs is given using CONTAINER= parameter. You can omit these parameters if filesystem type is one of ext2, ext3, iso9660, vfat, reiserfs, xfs, jfs.

## <<Tools for building customized root filesystem>>

The programs described in this chapter are used only when you want to create custom root filesystem with minimum files.

### <Hard link generator "makelink">

Reads the list of hard links from standard input and generates according to the list. This program is used to create hard links in the destination environment if the source environment is hard linked. The reason why the program to dump hard links and the program to generate hard links is that the destination directory may be included in the source directory or the destination and the source are different machines.

### <Hard link dumper "dumplink">

Dumps the list of hard links. Save the output of this program to file, and pass to makelink .

### <Symbolic link generator "makesymlink">

Reads the list of symbolic links from standard input and generates according to the list. The hard links and symbolic links might depend on each other. So repeatedly run makelink and makesymlink .

### <Symbolic link dumper "dumpsymlink">

Dumps the list of symbolic links. Save the output of this program to file, and pass to makesymlink .

Return to index