Appendix A Programmer's Reference

This appendix provides reference materials for the following topics.

• "Man Pages"

• "Making Shared Libraries Trusted"

• "Header File Locations"

• "Abbreviations in Names"

• "Developing, Testing, and Debugging"

• "Releasing an Application"

Man Pages

The Trusted Solaris release installs Solaris man pages and man pages specific to the Trusted Solaris environment. Where appropriate, the Solaris man pages are modified to contain security-related information relevant to the Trusted Solaris environment.

Reading Man Pages

The intro man pages provide global security policy information for Trusted Solaris man pages in a section. Security information specific to the interfaces on a particular man page is in the Description section, in the Errors section under EPERM, EACCES, or ESRCH, and in the Summary of Trusted Solaris Changes section at the end.

If a man page for a library routine has no security information on it and the routine has an underlying system call, check the man page for the underlying system call. The underlying system call enforces security policy for all library routines built on top of it.

• When the library routine and system call have similar names such as fopen(3UCB) and open(2), the policy information is on the system call man page only.

• Whether the names are similar or not, the library routine man pages for routines based on system calls have a cross-reference in their See Also section to the system call man page with the policy information.

If no Trusted Solaris man page exists for a Solaris interface, the interface has not been modified for the Trusted Solaris environment, or has been modified, but there is no security-related behavior to be aware of when using the interface in the Trusted Solaris environment.

Making Shared Libraries Trusted

To be used by any application that requires privilege(s), shared libraries must be trusted. In the Trusted Solaris environment, the dynamic linking of privileged applications to shared libraries is restricted--to ensure that privileged applications can never use untrusted libraries. A privileged application that tries to link to an untrusted library fails with an error such as: "error: cannot load **** libraries."

For information on how an administrator makes a library trusted, see "Testing New Software for Security" in Trusted Solaris Administrator's Procedures, and see also examples in the crle(1) man page.

Header File Locations

Most Trusted Solaris header files are located in /usr/include/tsol and include headers in /usr/include/sys/tsol. However, a few header files are modified from the Solaris operating environment, and are therefore located in other directories as follows:

Abbreviations in Names

Many of the Trusted Solaris interfaces and data structure names use the short abbreviations shown below in their names. Knowing the abbreviations will help you recognize the purpose of an interface or structure from its name.

Developing, Testing, and Debugging

Development, testing, and debugging should take place on an isolated development system to prevent software bugs and incomplete code from compromising security policy on the main system.

• Remove extra debugging code especially code that provides undocumented features and back doors that bypass security checks.

• Make application data manipulation easy to follow so it can be inspected for security problems by the system administrator before installation.

• Test return codes for all programming interfaces. An unsuccessful call can have unpredictable results. When an unexpected error condition occurs, the application should always terminate.

• Test all functionality by running the application at all sensitivity labels and from all roles at which you expect it to run.

  • If the program is run by a normal user (not by a role), launch it from the command line as a normal user at the labels in the user accreditation range at which it is intended to run.

  • If the program is run by a role, launch it from the command line from the administrative role at one the administrative label at which it is intended to run (ADMIN_HIGH or ADMIN_LOW), or from the user role at the labels in the user accreditation range at which it is intended to run.

• Test all functionality under privilege debugging mode so you know if the application has all the privileges it needs, or if it is attempting to perform privileged tasks that it should not be attempting.

• Know and follow privilege bracketing.

• Know the security implications of using privileges, and make sure the application does not compromise system security by its use of privilege.

• If you are applying the SUNWSpro debugger/dbx/dbxtool to test a privileged application, you must start the debugger first and then attach it to a running process. You cannot start the debugger with the command name as an argument.

Privilege Debugging

Privilege debugging mode is described in Trusted Solaris Administrator's Procedures. This is a summary of the steps for enabling privilege debugging and using runpd(1M) under privilege debugging mode to test an application.

1. Privilege debugging mode allows an application to succeed when it does not have the privileges it needs and tells you which privileges are missing.

2. In the /etc/system file, set the tsol_privs_debug variable to 1. This file is ADMIN_LOW and the owner is root.

3. In the /etc/syslog.conf file, uncomment the kern.debug; local0.debug line. This file is ADMIN_LOW and the owner is sys.

4. Touch the /var/log/privdebug.log file. This file is ADMIN_HIGH and the owner is root.

5. Reboot your system.

6. Assume an administrative role with runpd(1M) in the profile.

7. Use the runpd() command to invoke the executable and find out which privileges, if any, are missing. The following command line invokes the executable file in Zelda's confidential home directory. Information on missing privileges displays at the command line and is logged to the /var/log/privdebug.log file.

phoenix# runpd /export/home/.MLD.Zelda/.SLD.2/executable

runpd terminated with a status of 1

process runpd pid 822 lacking privilege file_mac_search to 
perform special method upon resource VNODE (Jan 29 12:45)

process runpd pid 822 lacking privilege file_mac_read to 
perform read method upon resource VNODE (Jan 29 12:45)

1. Interpret privilege numbers in the /var/log/privdebug.log file. The privilege number appears after the word privilege. Process 822 lacks privilege numbers 11 and 10 which correspond to file_mac_search and file_mac_read.

Jan 29 12:45:39 phoenix unix DEBUG: runpd pid 822 lacking 
privilege 11 to 5 79

Jan 29 12:45:39 phoenix unix DEBUG: runpd pid 822 lacking 
privilege 10 to 2 79

Assigning File Privileges using a Script

How to write privileged scripts to be deployed and used by others in your organization is described in Trusted Solaris Administrator's Procedures. This section briefly explains how to create a script that uses setfpriv(1) to assign forced and allowed privileges to an executable file for testing and debugging an application during application development.

First of all, the user or role you are working in needs a profile with the setfpriv(1) command and file_setpriv privilege assigned to it. The Object Privilege Management profile in the default system has these. To run the script from any shell and have the commands invoked by the script run under the profile shell and inherit your profile privileges, invoke pfsh(1M) at the top of the script as shown in the example below.

The example assigns forced and allowed privileges to executable. The -s -f options set forced privileges on executable, and the -a option sets allowed privileges on executable. This script will quit with the error: executable: not owner unless the file_setpriv privilege is inherited by the commands.

#/bin/pfsh
setfpriv -s -f 
ipc_mac_write,proc_setsl,sys_trans_label -a 
ipc_mac_write,proc_setsl,sys_trans_label executable

When you use a script to put forced and allowed privileges on an executable file, keep the following points in mind:

• If you remove a privilege from the allowed set specified in the script, you must also remove it from the forced set. If you remove it from the allowed set only, you will see the error: executable: Invalid argument when you run the script.

• If your program inherits privileges, launch it from the command line in the profile shell with the privileges to be inherited.

  • The allowed set of the executable file must have the privileges to be inherited.

  • If your program is going to only inherit privileges, the forced set of the executable file should be empty.

  • If your program takes a different action when a privilege is forced from when it is inherited, launch the program with the privilege in the forced and allowed set, and launch the program again with the privilege in the allowed set from a profile shell that has the privilege to be inherited.

Always test the program at all labels at which it is intended to run.

Releasing an Application

You submit a fully tested and debugged application to the system administrator for application integration. The application can be submitted as a CDE action or software package. If the application uses privilege, the system administrator evaluates (or has someone else evaluate) the application source code and security information you supply with the CDE action or software package to verify the use of privilege does not compromise system security.

Notify the system administrator of new auditing events, audit classes, or X Window System properties your application uses because he or she will need to put them into the correct files. See Chapter 8, Application Auditing and Chapter 14, Trusted X Window System for more information.

Creating a CDE Action

A CDE action is launched from the work space by a user or role and inherits the privileges assigned to it in that user's or role's profile. A CDE action is a set of instructions that work like application macros or programming interfaces to automate desktop tasks such as running applications and opening data files. In the Trusted Solaris environment, applications are started from the work space as CDE actions. How to create a CDE action is fully described in the Common Desktop Environment: Advanced User's and System Administrator's Guide, Part Number: 802-1575-10. SunSoft, a Sun Microsystems, Inc. business, produces the guide.

When you create a CDE action, always create an f.action rather than an f.exec. An f.exec executes the program as root with all privileges.

The system administrator puts the CDE action into the appropriate profiles and assigns inheritable privileges (if any) to the CDE action. The executable files associated with the CDE action need allowed privileges if the program inherits privileges and might or might not need forced privileges. You should list the inheritable, forced, and allowed, privileges the program uses (if any), indicate the labels at which the application is intended to run, and supply any effective user or group IDs required. The system administrator assigns forced and allowed privileges to the executable file, and assigns inheritable privileges, label ranges, and effective user and group IDs to the CDE action in the profile.

Creating a Software Package

The System V Release 4 application binary interface (ABI) specifies a software distribution model called software packaging that you use to package software for integration by the system administrator. All software distributed using the ABI model is guaranteed to install on all ABI-compliant systems.

When you create the software package, you supply security attribute information in the optional tsolinfo(4) file (described below), which is used in the package installation procedure. This file is optional because default security attributes are assigned during package installation in the event no security attribute information is provided with the package.

Package Files

A package consists of package objects (the files to be installed) and control files (files that control how, when, where, and if the package is installed). Information about packages already installed on the system is stored in the software installation database in /var/sadm/install/contents.

The Solaris operating environment provides the following commands for creating and installing ABI-compliant software packages.

To create a package, you set up the following files:

• Required information files.

  • pkginfo(4)

  • prototype(4)

• Optional information files as needed

• Optional mandatory access control (MAC) security attributes file, tsolinfo(4).

• Optional packaging scripts as needed.

pkgmk(1) uses pkginfo(4) and prototype(4) to construct a software package. The optional scripts customize the installation and remove packages.

MAC Security Attributes

The tsolinfo(4) file contains entries associated with package objects that require special security attributes. If a package object does not have any tsolinfo entries associated with it, it is assigned a default set of security attributes derived from the file system where the package is finally installed. This file can contain one or more entries per package object in the following format, where all fields in the format are required for each entry.

attribute_name object_name attribute_value

Here is a list of possible attribute names, what they mean, and how to specify them.

The following example tsolinfo(4) file entries specify security attributes for the sendmail(1M) package objects.

Description

• The var/spool/mail, var/mail, and var/tmp package objects are multilevel directories. The MLD attribute has no attribute values.

• The /usr/lib/sendmail object has All system privileges in its allowed privilege set.

• The /usr/lib/sendmail object has a comma-separated list of privileges in its forced set.

• The etc/security/tsol file has a CMW label in brackets, ADMIN_HIGH.

Edit Existing Package

To find and edit an existing package, search the software installation database with the grep(1) command. The information returned includes the package name.

% cat /var/sadm/install/contents | grep /usr/lib/object

Once you have the package name, you can find the package definition for that package and edit the tsolinfo(4) file. If no tsolinfo file exists, create one. If you create a tsolinfo file, add it to the prototype file so the pkgmk(1) command can find the tsolinfo file.

Add New Package

To add a new package, refer to the Application Packaging Developer's Guide for the Solaris operating environment for detailed information on creating packages. This section summarizes the concepts and steps.

The following Solaris commands are for creating new software packages.

The following figure shows the files that you are responsible for creating, the role of the pkgmk(1) command, and the resulting directory structure or package.

Figure A-1 Add New Package

Create Required files

1. Create a pkginfo(4) file using the man page.

2. Create a prototype(4) file using the man page.

   Use the pkgproto(1) command to generate a prototype(4) file template.

Create Optional Files and Scripts

1. Create the tsolinfo(4) file using the man page.

   Make sure tsolinfo is listed in the prototype file so that the pkgmk(1) command can find the tsolinfo file.

2. Create optional package information files as needed.

3. Create optional packaging scripts as needed.

Create the Package

1. Run the pkgmk(1) command.

2. Save the package to storage media

3. Give the storage media to the system administrator for installation.

Prototype File

You can create a prototype file with any editor. There must be one entry for every package component. The following is a sample prototype file that contains an entry for the tsolinfo file. The tsolinfo file is preceded by the letter i to indicate an information file. The letter f indicates a standard executable or data file. Refer to the prototype(4) man page for more information.

# Package "prototype" file for the bbp device driver.
# Bidirectional Parallel Port Driver for SBus Printer Card.
#
i pkginfo
i request
i copyright
i postinstall
i tsolinfo
f none bbp.kmod 0444 root sys
f none bbp_make_node 0555 root sys
f none bbp_remove_node 0555 root sys