test

Trusted Solaris Developer's Guide

Chapter 1 Introduction to the API and Security Policy

The Trusted Solaris environment provides an application programming interface (API) for accessing and handling security-related information from within third-party applications. This chapter summarizes the API functionality and introduces you to the Trusted Solaris security policy.

Operating Environment Features

The Trusted Solaris environment is based on the Solaris operating environment, and provides enhanced security while maintaining the following Solaris operating environment features:

Data Objects

Applications use Solaris and Trusted Solaris APIs to work on data in the types of objects described here. The Trusted Solaris environment implements security policy by imposing constraints on security-related operations applications perform on these objects. "Security Policy" describes Trusted Solaris security policy as it applies to applications.

File System Objects

File system objects reside in a file system where they can be read, written to, searched, and executed according to file system security policy. File system objects are the following:

X11 Windows Objects

X Window System objects handle data input and output through a special file system interface. Although the data in these special files is not accessed the way the data in file system objects is accessed, these files are protected by file system security policy, while the X Window Server and the X Window System objects are protected by X Window System security policy.

Process Objects

A process can access data in another process or in lightweight processes (independently scheduled threads of execution). All process to process communications is protected by either process, network, or interprocess communications (IPC) security policy. If the communication involves a special file, the file is protected by file system security policy.

IPC Objects

Interprocess communication (IPC) objects are the following.

Network Communication Endpoints

Network communication endpoints are sockets and transport layer interface (TLI) endpoints.

STREAMS Objects

STREAMS objects form the basis for networking software and are protected by network security policy. Security attribute information carried on STREAMS is accessed through the IPC and networking APIs described in detail in this guide. "Trusted Streams" lists interfaces that let you access the security attribute information on a Stream directly; however, no conceptual information or code examples is currently provided for these interfaces.

Application Programming Interfaces

The Trusted Solaris API provides access to the following security features. These features are listed here, briefly introduced in this chapter, and covered in detail in the remaining chapters of this guide.

Privileges

Privileges let a process perform tasks that are normally prohibited by the system security policy. In the Solaris operating environment, processes with the effective User ID of 0 (superuser) can bypass the system security policy, and processes at any other user ID have limited powers. In the Trusted Solaris environment, there is no superuser. A process with any user ID can be assigned specific privileges to give it a defined set of security-related powers. See priv_desc(4) for a list of privileges and the tasks they allow a process to perform.

Most applications do not use privileges because they do not need security-related powers to run. An application using privileges is called a Trusted Computing Base (TCB) application and should be carefully coded to not make information available in inappropriate ways. "Security Policy" provides guidelines to help you know when privileges might be needed, and Chapter 3, Privileges provides information and guidelines for coding privileged programs.

User Authorizations

The Trusted Solaris environment provides authorizations to control login, files and file management, devices, labels, and system administration activities. Applications can check a user's authorizations before performing certain tasks on behalf of that user if the tasks require user authorization. The tasks might be privileged administrative tasks or privileged non-administrative tasks. A good coding practice is to identify the authorization to be checked, identify the user or role performing the task, and check whether that user or role has the authorization to perform the task before turning privileges on in the application. If the task requires privilege (it usually does), authorizations should be checked before the process asserts the privilege.

Authorizations are administratively assigned and control user access to specific tasks. Authorizations are stored in /etc/security/auth_attr database. For a description of the file, see auth_attr(4). See getauthattr(3SECDB) for information on the family of routines for accessing and manipulating authorizations.

CMW Labels

CMW Labels control access to and maintain the classification of data. All processes and objects have a CMW label with two portions: the sensitivity label portion for mandatory access control (MAC) decisions, and the information label portion to identify the true sensitivity of the data.

Chapter 4, Labels describes programming interfaces that do the following.

Process Clearance

When a user starts an application from a workspace, the user's session clearance is set on the process and called the process clearance. The process clearance sets the upper bound to which the process can change an object's CMW label and to which the process can write data. Chapter 6, Process Clearance describes programming interfaces that do the following:

Multilevel Directories

Multilevel directories (MLDs) enable a program that runs at different sensitivity labels to use a common directory and access files at the sensitivity label at which the process is currently running. An MLD contains only single-level directories (SLDs), and each SLD stores files at the sensitivity label of the SLD. Within one MLD, several files with the same name can be stored in different SLDs. Each instance of the same file contains data appropriate to the sensitivity label of the SLD where it is stored. This is called polyinstantiation of directories and files. Chapter 7, Multilevel Directories describes programming interfaces that do the following:

Application Auditing

Third-party applications can generate audit records to monitor user actions to detect suspicious or abnormal patterns of system usage. Chapter 8, Application Auditing describes third-party application auditing.

User and Rights Profile Database Access

The user and profile databases contain information on users, roles, and profiles that can be accessed by an application. Chapter 9, Accessing User and Rights Profile Data describes programming interfaces that access this data.

Interprocess Communications

The Trusted Solaris environment supports labeled interprocess communications (IPC) with access and ownership checks. It supports the transfer of security attribute information for network endpoint objects.

Labeled endpoint communications can be single-level, multilevel, or polyinstantiated:

See the following chapters for information: Chapter 10, Interprocess Communications, Chapter 11, System V Interprocess Communication, Chapter 12, Trusted Security Information Exchange Library, and Chapter 13, Remote Procedure Calls.

Trusted X Window System

The Trusted X Window System, Version 11, server starts at login and handles the workstation windowing system using a trusted interprocess communication (IPC) path. Windows, properties, selections, and TooltalkTM sessions are created at multiple sensitivity labels (polyinstantiated) as separate and distinct objects. Applications created with Motif widgets, Xt Intrinsics, Xlib, and CDE interfaces run within the security policy constraints enforced by extensions to the X11 protocols.

Appendix B, Trusted Solaris Interfaces Reference describes the extensions for developers who need to create a X11 trusted IPC path. Chapter 14, Trusted X Window System describes programming interfaces to access security attribute information and translate binary labels and clearances to text by a specified width and font list for display in the X Window System.

Application User Interface

The Common Desktop Environment (CDE) 1.1.1 window system is the user interface for all interaction with the Trusted Solaris distributed operating system. User interfaces for new applications should use CDE APIs, Motif widgets 1.2, Xt Intrinsics, or XLib. The Trusted Solaris environment supports OpenWindowsTM applications (based on the XViewTM and Open Look Interface Toolkit (OLIT)) so trusted and untrusted applications that use OLIT for their user interface will run on the Trusted Solaris environment.

Label Builder

The Trusted Solaris environment provides Motif-based programming interfaces for adding a general label building user interface to an application. The label building interface lets a user interactively build valid CMW labels, sensitivity labels, or clearances. See Chapter 15, Label Builder for information on the programming interfaces.

System Security Configuration Settings

The system administrator sets system variables in the /etc/security file to configure the system to handle certain security attributes at a site. Chapter 2, Getting Started describes the programming interface for accessing Trusted Solaris system security variables that do the following:

Security Attributes

Security attributes define security information for file systems, processes, data packets, communication endpoints, and X Window System objects.

File System Security Attributes and Flags

File systems store the Solaris and Trusted Solaris security attributes listed below as a security attribute set accessible by the programming interfaces described in Chapter 2, Getting Started. Chapter 3, Privileges describes how to access file privileges.

Solaris Attributes 

Trusted Solaris Attributes 

Access Control Lists (ACLs) 

CMW label 

DAC permission bits 

File system label range 

file user ID 

Forced and allowed privilege sets 

file group ID  

Audit preselection attributes 

 

Attribute flags 

 

Multilevel directory prefix 

Process Security Attributes and Flags

User processes receive the Solaris and Trusted Solaris security attributes listed below from the user or role that started them and the workspace where they were started.

Process ID 

Process clearance 

Real and effective user ID 

CMW label 

Real and effective group ID 

Process attribute flags 

Supplementary group list 

Process privilege sets 

User audit ID 

 

Audit session ID 

 

umask (defines permission bits for files created by the process) 

Endpoint Communications Security Attributes

The Trusted Security Information eXchange (TSIX) library provides access to the Trusted Solaris security attributes on data packets and communication endpoints. TSIX is based on Berkeley sockets and supports transport layer interface (TLI). Chapter 12, Trusted Security Information Exchange Library describes how to access security attributes on data packets and communication endpoints.

Effective user ID 

Sensitivity label 

Effective group ID 

Audit information 

Process ID 

Process clearance 

Network session ID 

Effective privilege set 

Supplementary group ID 

Process attribute flags 

Audit ID 

 

Trusted X Window System Security Attributes

The Trusted X Window System stores the security attributes listed below. Chapter 14, Trusted X Window System describes how to access X Window System security attributes.

Window Server owner ID 

Sensitivity label 

User ID 

Internet address 

Group ID 

X Window Server clearance 

Process ID 

X Window Server minimum label 

Session ID 

Trusted Path window 

Audit ID 

 

The Trusted Path flag means the window is a trusted path window. The trusted path window is always the top-most window (such as the screen stripe or log in window), and protects the system against access by untrusted programs.

Security Policy

The laws, rules, and practical guidelines by which the Trusted Solaris environment regulates how sensitive information is protected, managed, and distributed is called security policy. Trusted Solaris applications differ from Solaris applications in that they are subject to mandatory access control (MAC) and cannot run with all the powers of superuser. Solaris applications by contrast are subject to discretionary access control (DAC) only and can run with all the powers of superuser.

The Trusted Solaris environment provides privileges so processes can override mandatory read, write, and search restrictions; discretionary read, write, execute, and search restrictions; and perform special security-related tasks that would normally be reserved for superuser.

Discretionary Access Policy

The Trusted Solaris environment supports discretionary read, write, execute, and search permission using user, group, and other permission bits; and access control lists (ACLs). Controlling access with DAC and ACLs is part of the Solaris operating environment and not described in great detail in this guide, although retrieving ACLs as a file system security attribute is described in Chapter 2, Getting Started and DAC policy is summarized in "Discretionary Access"

Mandatory Access Policy

The Trusted Solaris environment supports mandatory search, read, and write operations. MAC is enforced by comparing the sensitivity label and clearance of a process with the sensitivity label of the object to which the process is seeking access and determining whether the access is allowed or denied according to the MAC policy enforced on the object and the outcome of the comparison.

The outcome states the relationship between the process sensitivity label and object sensitivity label and is described as one dominating the other or equaling the other. The relationships of dominance and equality are covered in Chapter 4, Labels, and summarized here:

The outcome also states the relationship between the process clearance and the object sensitivity label as one of dominance or equality. If the access operation attempts to change the CMW label of the object, the clearance sets the highest level to which the sensitivity label portion can be changed. If the access operation is a write-up (see "Write Access" below), the clearance sets the highest level to which the process may write.

The Trusted Solaris environment supports the following mandatory read and write operations on interactions between unprivileged processes and the objects they access. See "Policy Enforcement" for information on how these operations apply to objects.

Read Access

The Trusted Solaris definition of mandatory read access includes read-equal and read-down:

Write Access

The Trusted Solaris definition of mandatory write access includes write-equal and write-up:

When to Use Privileges

To know if your application can run without privilege, you need to know what tasks use which privileges and when those privileges are needed. The following guidelines are to help you determine what privileges (if any) an application might need.

See Appendix A, Programmer's Reference for information on how to access man pages to obtain information on privileges and privilege descriptions.

Administrative and User Applications

Administrative applications run at the administrative sensitivity labels of ADMIN_HIGH or ADMIN_LOW. At ADMIN_HIGH, the application can read down to any object to which it has discretionary access, and at ADMIN_LOW, the application can write up to any object to which it has discretionary access. An administrator will generally launch an application at ADMIN_HIGH to perform read-down operations, and launch the same application at ADMIN_LOW to perform write-up operations. In these cases, no privileges are needed as long as the application has discretionary access.

See "Initialize Binary Labels and Check Types" in Chapter 5, Label Code Examples for definitions of and information on initializing labels to ADMIN_HIGH and ADMIN_LOW.

Users generally launch an application at a given sensitivity label and access objects at that same sensitivity label. If the user keeps data at another sensitivity label, he or she will usually change the workspace sensitivity label and launch the application at the new sensitivity label. In this case, no privileges are needed as long as the application also has discretionary access.

If a user application is designed to access objects at sensitivity labels different from the sensitivity label at which the application is running, the application might need privilege to complete its tasks if mandatory access is denied.

See "Label Guidelines" in Chapter 4, Labels for guidance on the use of privileges to bypass mandatory access controls or to change a process or object sensitivity label.

Policy Enforcement

In UNIX all input and output is performed through a file interface, which means that file system security policy applies throughout the Trusted Solaris environment. For this reason, file system security policy is described in detail here.

File system security policy is stated in terms of the following:

Security policy for interprocess communications (IPC) is stated in terms of mandatory read and write access checks between the accessing process and the process being accessed. Some IPC mechanisms and X Window System objects use files, and file system security policy as described in this section applies to those operations. Some IPC mechanisms have the read-down and write-up security policy, while other IPC mechanisms have the more restrictive read-equal and write-equal policy. The X Window system has the write-equal and read-down policy. See the following chapters for specific security policy information on these topics:

File System Security Policy

This section describes mandatory and discretionary access checks for the following file system objects:

Discretionary Access

The owner of the process must have discretionary search (execute) access to all directories in the path preceding the final object. Once the final object is reached, access operations can be performed as follows.

Mandatory Access

In addition to passing the DAC checks, mandatory search access is required to all directories in the path preceding the final file. Mandatory search access to a directory is allowed when the process sensitivity label dominates the sensitivity label of all directories in the path. Once the final file is reached, access operations can be performed as follows.

File System Access Privileges

When a discretionary or mandatory access check fails on a file system object, the process can assert privilege to bypass security policy, or raise an error if the task should not be allowed at the current label or for that user.

Discretionary access is enabled as follows:

Mandatory access is enabled as follows:

When Access Checks are Performed

Mandatory and discretionary access checks are performed on the path name at the time a file system object is opened. No further access checks are performed when the file descriptor is used in other system calls, except as follows:

File System Policy Examples

The examples in this section illustrate the kinds of things you need to think about when a process accesses a file system object for read, write, search, and execute operations.

The process accesses /export/home/heartyann/somefile for reading and writing, and /export/home/heartyann/filetoexec for execution. These files are both protected at Confidential. The process sensitivity label is Secret and the process clearance is Top Secret. Confidential is lower than Secret and Secret is lower than Top Secret.

Sensitivity Labels

As shown in the following figure, the path /export/home has a sensitivity label of ADMIN_LOW and the heartyann directory and somefile have a sensitivity label of Confidential.

Figure 1-1 Accessing a File System Object

Graphic

If the process fails a mandatory or discretionary access check, the program needs to assert an error or the proper privilege if the program is intended to run with privilege.

See Chapter 4, Labels in "Label Guidelines" for information on handling sensitivity labels when privileges are used to bypass access controls.

Open the File

The Secret process opens somefile for reading, performs a read operation, and closes the file. The fully adorned pathname is used so somefile in the Confidential /export/home/heartyann single-level directory is accessed.

A fully adorned pathname uses the multilevel directory adornment and specifies precisely which single-level directory is wanted. If a regular pathname was used instead, the Secret single-level directory would be accessed because the process is running at Secret.

See "Adorned Names" for a discussion on fully adorned pathnames. Chapter 7, Multilevel Directories presents interfaces for handling multilevel and single-level directories so fully adorned pathnames are not hardcoded the way they have been for clarity in these examples.

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <unistd.h>

main()
{
	int filedes, retval;
	ssize_t size;
	char readbuf[1024];
	char *buffer = "Write to File.";
	char *file = "/export/home/.MLD.heartyann/.SLD.1/filetoexec";
	char *argv[10] = {"filetoexec"};

	filedes = open("/export/home/.MLD.heartyann/.SLD.1/somefile", O_RDONLY);
	size = read(filedes, readbuf, 29);
	retval = close(filedes);

Write to the File

The Secret process opens somefile for writing in the Confidential /export/home/heartyann single-level directory, performs a write operation, and closes the file. 

filedes = open("/export/home/.MLD.heartyann/.SLD.1/somefile", O_WRONLY);
size = write(filedes, buffer, 14);
retval = close(filedes);

Execute a File

The Secret process executes an executable file in the Confidential /export/home/heartyann single-level directory. 

retval = execv(file, argv);