Trusted Solaris Developer's Guide

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.

Security mechanisms:
- Privileges
- User authorizations
- CMW labels
- Process clearances
- Multilevel directories
- Application auditing

User and Rights Profile database security information
System security configuration settings
Security attribute information:
- File system security attributes and flags
- Process security attribute flags
- Network security attributes
- X11 Windows security attributes

Process to object communications:
- Secure interprocess communications with CMW labels
- Secure file system communications with CMW labels and file system security attributes
- Secure network communications with CMW labels, multilevel ports, multilevel mappings (RPC only), and network security attributes
- Secure transfer of data between X11 Windows with CMW labels and windows security attributes

Label builder - APIs that let you create a graphical user interface for your application that takes end user input and builds a valid label for the system

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.

Get and set the file and process privilege sets.
Set the effective, permitted, and inheritable process privilege sets.
Convert privilege IDs between numeric and text.
Get privilege text for a privilege ID.

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.

Get and set file and process labels.
Get file system label ranges.
Initialize labels.
Find the greatest lower bound or least upper bound between two levels.
Compare levels for dominance and equality.
Check and set binary label types.
Convert labels between binary and text or hexadecimal.
Check that a sensitivity label is valid and within the system or user accreditation range.
Get information from the label_encodings(4) file. This file is set up and maintained by the system administrator and contains the label definitions for the system.

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:

Get and set the process clearance.
Initialize a binary clearance.
Find the greatest lower bound or least upper bound between two levels.
Compare levels for dominance and equality.
Check and set binary label types.
Convert clearances between binary and text or hexadecimal.
Check that a clearance is valid.

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:

Get single-level or multilevel directory names.
Get attribute information for a single-level or multilevel directory.
Using single-level or multilevel directory names in system calls.

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:

Single-level port connection - Two unprivileged processes communicate at the same sensitivity label.
Multilevel port connections - A privileged server communicates with any number of unprivileged clients running at different sensitivity labels.
Polyinstantiated port connection (UNIX address family only) - A single-level connection using files of the same name residing in different single-level directories (SLDs) within a multilevel directory (MLD). Polyinstantiated port connections create multiple independent parallel binds.

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 Tooltalk^TM 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 OpenWindows^TM applications (based on the XView^TM 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:

Enable privilege debugging for testing a privileged application. When privilege debugging is on, an application succeeds even when it does not have all the privileges it needs and the missing privileges are printed to the command line and to a file for your information. See Trusted Solaris Administrator's Procedures or "Privilege Debugging" for information on enabling and using privilege debugging.
Hide file names of files that have had their sensitivity labels upgraded by a privileged processes.

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.

Chapter 2, Getting Started describes how to access process attribute flags.
Chapter 3, Privileges describes how to access process privilege sets.
Chapter 4, Labels describes how to access labels on processes.
Chapter 6, Process Clearance describes how to access the process clearance.

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.