Appendix A Programmer's Reference

This appendix explains where to find information about developing, testing, and releasing label-aware applications to an environment that uses the Trusted Extensions software.

This appendix covers the following topics:

• Header File Locations

• Abbreviations Used in Interface Names and Data Structure Names

• Developing, Testing, and Debugging an Application

• Releasing an Application

Header File Locations

Most Trusted Extensions header files are located in the /usr/include/tsol directory and in the /usr/include/sys/tsol directory. The locations of other header files are shown in the following table.

Header File and Its Location	Category of Interface
/usr/dt/include/Dt/label_clipping.h	X11 label translation and label clipping with font list
/usr/dt/include/Dt/ModLabel.h	Label Builder
/usr/openwin/include/X11/extensions/Xtsol.h	X Window System
/usr/include/libtsnet.h	Trusted network library
/usr/include/bsm/libbsm.h	Audit library

Abbreviations Used in Interface Names and Data Structure Names

Many of the Trusted Extensions interface names and data structure names use the following short abbreviations. Knowing the abbreviations of these names will help you recognize the purpose of an interface or structure.

Table A–1 Name Abbreviations Used by Trusted Extensions APIs

Abbreviation	Name
attr	Attribute
b	Binary
clear	Clearance
ent	Entry
f	File
fs	File system
h	Hexadecimal
l	Level, label, or symbolic link
lbuild	Label Builder
prop	Properties
r	Re-entrant
res	Resource
s	String
sec	Security
sl	Sensitivity label
tp	Trusted Path
tsol	Trusted Extensions
xtsol	Trusted X11 Server

Developing, Testing, and Debugging an Application

You must develop, test, and debug an application on an isolated development system to prevent software bugs and incomplete code from compromising the security policy on the main system.

Follow these guidelines:

• Remove extra debugging code, especially code that provides undocumented features and code that bypasses security checks.

• Make application data manipulation easy to follow so that the manipulation can be inspected for security problems by an 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 must always terminate.

• Test all functionality by running the application at all sensitivity labels and from all roles that you expect will run the application.

  • If the program is run by an ordinary user and not by a role, start the program from the command line at the labels where the program is intended to run.

  • If the program is run by a role, start the program from the command line in the global zone or from the user role at the labels where the program is intended to run.

• Test all functionality under privilege debugging mode so that you know whether the application has all the privileges it needs. This type of testing also determines whether the application is attempting to perform privileged tasks that it should not be performing.

• Know the security implications of using privileges. Ensure that the application does not compromise system security by its use of privileges.

• Know and follow good privilege bracketing practices.

  See Oracle Solaris Security for Developers Guide.

• If you use the SUNWspro debugger or the dbx command to test a privileged application, start the debugger before you attach it to a running process. You cannot start the debugger with the command name as an argument.

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 as a software package. If the application uses privileges, the system administrator must evaluate the application source code and the security information that you supply. This evaluation verifies that your use of privileges does not compromise system security.

---

Caution –

Notify the system administrator of new auditing events, audit classes, or X Window System properties that your application uses. The system administrator must place these items into the correct files. For more information, see Chapter 6, Trusted X Window System.

---

Creating a CDE Action

A CDE action is started from the workspace by a user or a role. The action inherits the privileges assigned to the profile of that user or role. A CDE action is a set of instructions that work like application macros or APIs to automate desktop tasks such as running applications and opening data files. On a system configured with Trusted Extensions, applications are started from the workspace as CDE actions. Instructions on how to create a CDE action are provided in the Solaris Common Desktop Environment: Advanced User’s and System Administrator’s Guide.

---

Note –

When you create a CDE action, create an f.action, not an f.exec. An f.exec executes the program as superuser with all privileges.

---

The system administrator puts the CDE action into the appropriate profiles and assigns any necessary privileges to the CDE action. You must list the privileges that the program uses, indicate the labels at which the application is intended to run, and supply any required effective user or group IDs. The system administrator assigns privileges as well as effective user and group IDs to the CDE action in the profile.

Creating a Software Package

To create a software package, see the Application Packaging Developer’s Guide. To debug package installation issues, see Chapter 14, Troubleshooting Software Problems (Overview), in System Administration Guide: Advanced Administration.