Trusted Solaris Developer's Guide

Chapter 14 Trusted X Window System

This chapter uses a short Motif application to describe Trusted X Window System security policy and the Trusted Solaris interfaces.

X Windows Environment

The Trusted Solaris environment uses the Trusted Common Desktop Environment (CDE) which is an enhanced version of CDE 1.0.2. Trusted CDE uses the X Window System, Version 11, with the Trusted Solaris X Window System server. The Trusted X Window System server has protocol extensions to support mandatory access controls, discretionary access controls, and the use of privileges. Clients connect to the Trusted X Window System server over UNIX domain and TCP/IP domain network connections.

Data transfer sessions are instantiated at different sensitivity labels and user IDs (polyinstantiated). This is so data in an unprivileged client at one sensitivity label or user ID is not transferred to another client at another sensitivity label or user ID in violation of the Trusted X Window System discretionary access controls and mandatory access policies of write-equal and read-down.

Trusted Solaris X Window System programming interfaces let you get and set security-related attribute information and translate binary labels to text using a font list and width to apply a style such as Helvetica 14 point bold to the text string output. These interfaces are usually called by administrative applications written with Motif widgets, Xt Intrinsics, Xlib, and CDE interfaces.

Security Attributes

The Trusted X Window System interfaces manage security-related attribute information for various X Window objects. If your application GUI is created with Motif only, you need to use XToolkit routines within the Motif application to retrieve the Xlib object IDs underlying the Motif widgets to handle security attribute information for an Xlib object.

The X Window objects for which security attribute information can be retrieved by the Trusted X Window System interfaces are window, property, X Window Server, and the connection between the client and the X Window Server. Xlib provides calls to retrieve window, property, display, and client connection IDs.

The security attributes for windows, properties, and client connections consist of ownership IDs and CMW label information. See "Data Types, Header Files, and Libraries" for information on the structures for capturing some of these attributes, and "Programming Interface Declarations" for information on the interfaces that get and set security attribute information.

Security Policy

Window, property, and pixmap objects have a user ID, client ID, and a CMW label. Graphic contexts, fonts, and cursors have a client ID only. The connection between the client and the X Window Server has a user ID, X Window Server ID, and a CMW label.

The user ID is the ID of the client that created the object. The client ID is related to the connection number to which the client that creates the object is connected.

The discretionary access policy requires a client to own an object to perform any operations on the object. A client owns an object when the client's user ID equals the object's ID. For a connection request, the user ID of the client must be in the Access Control List (ACL) of the owner of the X Window Server workstation or the client must assert the Trusted Path attribute as described in "Get and Set Process Security Attribute Flags".

The mandatory access policy is write-equal, read-equal for naming windows, and read-down for properties. The sensitivity label portion of the CMW label is set to the sensitivity label of the creating client. The information label portion of the CMW label is always ADMIN_LOW.

Windows can have properties that contain information to be shared among clients. Window properties are created at the sensitivity label at which the application is running so access to the property data is segregated by its sensitivity label. clients can create properties, store data in a property on a window, and retrieve the data from a property subject to mandatory and discretionary access restrictions. See /usr/openwin/server/tsol/property.atoms to specify properties that are not polyinstantiated.

Root Window

The root window is at the top of the window hierarchy. The root window is a public object that does not belong to any client, but has data that must be protected. The root window attributes are protected at ADMIN_LOW.

Client Windows

A client usually has at least one top-level client window that descends from the root window, and additional windows nested within the top-level window. All windows that descend from the client's top-level window have the same sensitivity label.

Override-Redirect Windows

Override-redirect windows such as menus and certain dialog boxes cannot take the input focus away from another client to prevent the input focus from accepting input into a file at the wrong sensitivity label. Override-redirect windows are owned by the creating client and cannot be used by other clients to access data at another sensitivity label.

Keyboard, Pointer, and Server Control

A client needs mandatory and discretionary access to gain keyboard, pointer, or server control. To reset the focus, a client must own the focus or have the win_devices privilege.

To warp a pointer, the client needs pointer control and mandatory and discretionary access to the destination window. X and Y coordinate information can be obtained for events that involve explicit user action.

Selection Manager

The Selection Manager arbitrates user-level inter-window data moves such as cut-and-paste or drag-and-drop where information is transferred between untrusted windows. When a transfer is attempted, Selection Manager captures the transfer, verifies the controlling user's authorization, and requests confirmation and labeling information from the user. The Selection Manager displays whenever the end user attempts a data move without your writing application code.

The administrator can set autoconfirm for some transfer types in which case the Selection Manager does not appear. If the transfer meets mandatory and discretionary access policies, the data transfer completes. The File Manager and Window Manager also act as selection agents for their private drop sites. See /usr/openwin/server/tsol/selection.atoms to specify selection targets that are polyinstantiated. See /usr/dt/config/sel_config to determine which selection targets are automatically confirmed.

Default Resources

Resources not created by clients are default resources labeled ADMIN_LOW. Only clients running at ADMIN_LOW or with the appropriate privileges can modify default resources.

Moving Data Between Windows

A client needs the win_selection privilege to move data between one window and another without going through the "Selection Manager".

Getting and setting process attribute flags is covered in Chapter 2, Getting Started.

Privileged Operations

Library routines that access a window, property or atom name without user involvement require mandatory and discretionary access. Library routines that access framebuffer graphic contexts, fonts, and cursors require discretionary access and may also require additional privilege for special tasks as described below.

The client may need one or more of the following privileges in its effective set if access to the object is denied: win_dac_read, win_dac_write, win_mac_read, or win_mac_write. See /usr/openwin/server/tsol/config.privs to enable or disable these policies..

Configuring and Destroying Resources

A client needs the win_config privilege in its effective set to configure or destroy windows or properties permanently retained by the X Window Server. The screen saver timeout is an example of such a resource.

Input Devices

A client needs the win_devices privilege in its effective set to get and set keyboard and pointer controls or modify pointer button and key mappings.

Direct Graphics Access

A client needs the win_dga privilege in its effective set to use the direct graphics access (DGA) X protocol extension.

Downgrading labels

A client needs the win_downgrade_sl privilege in its effective set to change the sensitivity label on a window, pixmap, or property to a new label that does not dominate the existing label.

Upgrading Labels

A client process needs the win_upgrade_sl privilege in its effective set to change the sensitivity label on a window, pixmap, or property to a new label that dominates the existing label.

Setting a Font Path

A client needs the win_fontpath privilege in its effective set to modify the font path.

Data Types, Header Files, and Libraries

To use the Trusted X11 programming interfaces described in this chapter, you need the following header files:


#include <tsol/Xtsol.h>

The Trusted X11 examples compile with the following library:


-lXtsol -ltsol

To use the X11 Windows label clipping programming interfaces described in this chapter, you need the following header file:


#include <tsol/label_clipping.h>

The label clipping examples compile with the following library:


-lDtTsol -ltsol 

Object Type

The ResourceType type definition indicates the type of resource to be handled. The value can IsWindow.

Object Attributes

The XTsolResAttributes structure contains the resource attributes.

CARD32

ouid

User ID of workstation server owner 

CARD32

uid

User ID of window 

bslabel_t

sl

Sensitivity label 

Property Attributes

The XTsolPropAttributes structure contains the property attributes.

CARD32

uid

User ID of property 

bslabel_t

sl

Sensitivity label 

Client Attributes

The XTsolClientAttributes structure contains the client attributes.

uid_t

uid

ID of user that started the client. 

gid_t

gid

Group ID 

pid_t

pid

Process ID 

u_long

sessionid

Session ID 

au_id_t 

auditid 

Audit ID 

u_long

iaddr

Internet address of workstation where the client is running. 

Setting Flag

The setting_flag type definition defines CMW label flag values as follows:

SETCL_SL - Set the sensitivity label portion of the CMW label. SETCL_ALL - Set the entire CMW label.

CMW Label

A data structure to represent a binary CMW label. Interfaces accept and return a binary CMW label in a structure of type bclabel_t.

Clearance

A type definition to represent a clearance. Interfaces accept as parameters and return binary clearances in a structure of type bclear_t.

Programming Interface Declarations

This section provides declarations for the Trusted X11 interfaces and the X11 Windows label clipping interfaces.

Window Attributes

This routine returns the resource attributes for a window ID in *resattrp. Refer to the XTSOLgetResAttributes(3) man page.

Status XTSOLgetResAttributes(Display *display,
	XID object,
	ResourceType resourceFlag,
	XTsolResAttributes *resattrp);

Property Attributes

This routine returns the property attributes for a property hanging on a window ID in *propattrp. Refer to the XTSOLgetPropAttributes(3) man page.

Status XTSOLgetPropAttributes(Display *display,
	Window win,
	Atom property,
	XTsolPropAttributes *propattrp);

Client Connection Attributes

This routine returns the client attributes in *clientattrp. Refer to the XTSOLgetClientAttributes(3) man page.

Status XTSOLgetClientAttributes(Display *display,
	XID win,
	XTsolClientAttributes *clientattrp);

Window CMW Label

These routines get and set the CMW label of a window. Refer to the XTSOLgetResLabel(3) and XTSOLsetResLabel(3) man pages.

Status XTSOLgetResLabel(Display *display,
	XID object,
	ResourceType resourceFlag,
	bclabel_t *cmwlabel);

void XTSOLsetResLabel(Display *display,
	XID object,
	ResourceType resourceFlag,
	bclabel_t *cmwLabel,
	enum setting_flag labelFlag);

Window User ID

These interfaces get and set the user ID of a window. Refer to the XTSOLgetResUID(3) and XTSOLsetResUID(3) man pages.

Status XTSOLgetResUID(Display *display,
	XID object,
	ResourceType resourceFlag,
	uid_t *uidp);

void XTSOLsetResUID(Display *display,
	XID object,
	ResourceType resourceFlag,
	uid_t *uidp);

Property CMW Label

These routines get and set the CMW label of a property hanging on a window. Refer to the XTSOLgetPropLabel(3) and XTSOLsetPropLabel(3) man page.

Status XTSOLgetPropLabel(Display *display,
	Window win,
	Atom property,
	bclabel_t *cmwlabel);

void XTSOLsetPropLabel(Display *display,
	Window win,
	Atom property,
	bclabel_t *cmwLabel,
	enum setting_flag labelFlag);

Property User ID

These interfaces get and set the user ID of a property hanging on a window. Refer to the XTSOLgetPropUID(3) and XTSOLsetPropUID(3) man pages.

Status XTSOLgetPropUID(Display *display,
	Window winID,
	Atom property,
	uid_t *uidp);

void XTSOLsetPropUID(Display *display,
	Window win,
	Atom property,
	uid_t *uidp);

Workstation Owner ID

These routines get and set the user ID for the owner of the workstation server. Refer to the XTSOLgetWorkstationOwner(3) and XTSOLsetWorkstationOwner(3) man pages.


Note -

XTSOLsetWorkstationOwner(3) is reserved for the Window Manager.


Status XTSOLgetWorkstationOwner(Display *display, uid_t *uidp);
void XTSOLsetWorkstationOwner(Display *display, uid_t *uidp);

X Window Server Clearance and Minimum Label

These routines set the session high clearance and the session low minimum label for the X Window Server. Refer to the XTSOLsetSessionHI(3) and XTSOLsetSessionLO(3) man pages.


Note -

These interfaces are reserved for the Window Manager.


void XTSOLsetSessionHI(Display *display, bclear_t *clearance);
void XTSOLsetSessionLO(Display *display, bslabel_t *sl);

Trusted Path Window

These routines makes the specified window the trusted path window and test whether the specified window is the trusted path window. Refer to the XTSOLMakeTPWindow(3) man page.

void XTSOLMakeTPWindow(Display *dpy, Window win);
Bool XTSOLIsWindowTrusted(Display *display, Window win);

Screen Stripe Height

These interfaces get and set the screen stripe height - an additive and subtractive operation. Be careful you do not end up with no screen stripe or a very large screen stripe. Refer to the XTSOLsetSSHeight(3) and XTSOLgetSSHeight(3) man pages.


Note -

These interfaces are reserved for the Window Manager.


Status XTSOLgetSSHeight(Display *display,
	int screen_num,
	int *newHeight);

void XTSOLsetSSHeight(Display *display,
	int screen_num,
	int newHeight);

Polyinstantiation Information

This routine lets a client get property information from a property at a different sensitivity label from the client. In the first call, specify the desired sensitivity label and user ID, and set enabled to True. Then call XTSOLgetPropAttributes(3), XTSOLgetPropLabel(3), or XTSOLgetPropUID(3), and finish up by calling this routine again with enabled set to False. Refer to the XTSOLsetPolyInstInfo(3) man page.

void XTSOLsetPolyInstInfo(Display *dpy,
	bslabel_t *senslabel,
	uid_t *userID, int enabled);

X11 Windows Label Clipping Interfaces

These routines translate a binary CMW label, sensitivity label, or clearance to a compound string using a font list. The returned string is clipped to the specified pixel width, or if width equals the display width (display), the label is word wrapped using a width of half the display width. See "Binary and Text Label Translation" for a description of the flags parameter. Refer to the labelclipping(3TSOL) man page.

/* CMW label */
	XmString Xbcltos(Display *display,
		const bclabel_t *cmwlabel,
		const Dimension width,
		const XmFontList fontlist,
		const int flags);

/* Sensitivity label */
	XmString Xbsltos(Display *display,
		const bslabel_t *senslabel,
		const Dimension width,
		const XmFontList fontlist,
		const int flags);

/* Clearance */
	XmString Xbcleartos(Display *display,
		const bclear_t *clearance,
		const Dimension width,
		const XmFontList fontlist,
		const int flags);

Example Motif Application

The example Motif application in the following figure launches xclock or xterm applications. It is simple because its purpose is to show how Trusted Solaris X Windows programming interfaces are called from within a Motif application. The application's process sensitivity label is Confidential and the information label is ADMIN_LOW.

Figure 14-1 Simple Motif Application

Graphic

The next headings provide example code segments that use the Trusted Solaris interface calls to handle security attributes and translate a binary label to text with a font list. The code segments focus on handling window security attributes because those are the most common operations in application programs. Often a client will retrieve security attributes (using the appropriate privileges) for an object created by another application and check the attributes to determine if an operation on the object is permitted by the system's discretionary ownership policies and the mandatory write-equal and read-down policies. If access is denied, the application raises an error or uses privilege as appropriate. See "Privileged Operations" for information on when privileges are needed.

The source code for the simple Motif application including the code segments below is provided in "Code". Xlib calls to retrieve object IDs to pass to the Trusted Solaris programming interfaces should be made after the appropriate object has been created so there is an ID to retrieve. In this source code, the Xlib calls are after XtRealizeWidget() is called.

Getting Window Attributes

The XTSOLgetPropAttributes(3) routine returns security-related attributes for a window. You supply the display and window IDs, a flag to indicate the object you want security attributes on is a window, and an XtsolResAttributes structure to receive the returned attributes. The client is getting the security attributes for a window it created so no privileges are required.

/* Retrieve underlying window and display IDs with Xlib calls */
	window = XtWindow(topLevel);
	display = XtDisplay(topLevel);

/* Retrieve window security attributes */
	retval = XTSOLgetResAttributes(display, window, IsWindow, &winattrs);

/* Translate labels to strings */
	retval = bsltos(&winattrs.sl, &string1, 0, LONG_WORDS);
	
/* Print security attribute information */
	printf("Workstation owner ID = %d, User ID = %d, Label = %s\n",
   winattrs.ouid, winattrs.uid,string1, string2,	string3);

The printf(1) statement prints the following:


Workstation owner ID = 29378
User ID = 29378
Label = CONFIDENTIAL

Translate Label with Font List

This example gets the process sensitivity label and translates it to text using a font list and pixel width. A label widget is created with the string for its label. The process sensitivity label equals the window sensitivity label so no privileges are required.

When the final string is longer than the width, it is clipped and the clipped indicator is used. The clipped indicator for a clipped sensitivity label is described in "Sensitivity and Information Labels" and on the sbsltos(3TSOL) man page. Note that the X Window System label translation interfaces clip to the number of pixels specified, and the label clipping interfaces clip to the number of characters.

If your site uses a label_encodings file in a language other than English, the translation might not work on accent characters in the ISO standard above 128, and will not work on the Asian character set.

	retval = getcmwplabel(&cmwlabel);
	getcsl(&senslabel, &cmwlabel);

/* Create the font list and translate the label using it */
	italic = XLoadQueryFont(XtDisplay(topLevel),
		"-adobe-times-medium-i-*-*-14-*-*-*-*-*-iso8859-1");
	fontlist = XmFontListCreate(italic, "italic");
	xmstr = Xbsltos(XtDisplay(topLevel), &senslabel, width, fontlist, 
		LONG_WORDS);

/* Create a label widget using the font list and label text*/
	i=0;
	XtSetArg(args[i], XmNfontList, fontlist); i++;
	XtSetArg(args[i], XmNlabelString, xmstr); i++;
	label = XtCreateManagedWidget("label", xmLabelWidgetClass, 
		form, args, i);

The source code for the italicized sensitivity label string and the non-italicized "Launch and application" label is in "Code". Launch the application with any command line argument to see the italicized sensitivity label string in the label widget as shown in the following figure.

Figure 14-2 Italicized Label Text

Graphic

Getting a Window CMW Label

This example gets the CMW label on a window. The process sensitivity label equals the window sensitivity label so no privileges are required.

/* Retrieve window CMW label */
	retval = XTSOLgetResLabel(display, window, IsWindow, &cmwlabel);

/* Translate labels to string and print */
	retval = bcltos(&cmwlabel, &string, 0, LONG_WORDS);
	printf("CWM label = %s\n", string);

The printf(1)statement prints the following:


CMW label = ADMIN_LOW[C]

Setting a Window CMW Label

This example sets the CMW label on a window. The new sensitivity label dominates the window's and process's sensitivity label. The client needs the sys_trans_label privilege in its effective set to translate a label it does not dominate, and the win_upgrade_sl privilege to change the window sensitivity label.

/* Translate text string to binary sensitivity label and */
/* Turn sys_trans_label on in the effective set */
	retval = stobsl(&string4, &senslabel, NEW_LABEL, &error);
/* Turn sys_trans_label off */

/* Set the sensitivity label in the cmwlabel structure */
	setcsl(&cmwlabel, &senslabel);

/* Set sensitivity label portion of CMW label with new value */
/* and turn win_upgrade_sl on in the effective set */
	retval = XTSOLsetResLabel(display, window, IsWindow, &cmwlabel,
		SETCL_SL);
/* Turn the win_upgrade_sl privilege off */

Getting the Window User ID

This example gets the window user ID. The process owns the window resource and is running at the same sensitivity label so no privileges are required.

/* Get the user ID of the window */
	retval = XTSOLgetResUID(display, window, IsWindow, &uid);

Getting the X Window Server Workstation Owner ID

This example gets the ID of the user logged in to X Window Server. The process sensitivity label equals the window sensitivity label so no privileges are required.

/* Get the user ID of the window */
	retval = XTSOLgetWorkstationOwner(display, &uid);

Source Code

This is the source code for the simple Motif applications shown in Figure 14-1 and Figure 14-2. Launch it with any command line argument to see the text label string in italic font in the label widget.

Resource File

Here is the Resource file for the simple Motif application. One way to use it is to create the file and set the XENVIRONMENT variable with the pathname.


phoenix% setenv XENVIRONMENT /export/home/zelda/resfile
Example.*geometry: 400X100
Example.*orientation: XmHORIZONTAL
Example.*label.labelString: Launch an application
Example.*xclock.labelString: Run xclock
Example.*xterm.labelString: Run xterm
Example.*xmag.labelString: Run xmag
Example.*goodbye.labelString: Quit
Example.*XmPushButton*background: blue
Example.*XmLabel*foreground: white
Example.*XmLabel*foreground: white

Compile Command


phoenix% cc -I/usr/openwin/include -I/usr/dt/include ex.c -o Example \
-L/usr/openwin/lib -L/usr/dt/lib -lXm -lXt -lX11 -lXtsol -ltsol -lDtTsol

Code

#include <stdio.h>
#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <Xm/Xm.h>
#include <Xm/Label.h>
#include <Xm/PushB.h>
#include <Xm/Form.h>
#include <tsol/Xtsol.h>
#include <Dt/label_clipping.h>

XTsolResAttributes winattrs;
int retval, error;
uid_t uid;
Window window;
Display *display;
char *string = (char *)0, *string1 = (char *)0, *string2 = (char *)0,
	*string3 = (char *)0, *string4 = "SECRET";
XmFontList fontlist;
XmString xmstr;
XFontStruct *italic;
Arg args[9];
Dimension width = 144;
Widget stringLabel;
bslabel_t senslabel;
bclabel_t cmwlabel;

/* Callbacks */

void Xclock(Widget w, caddr_t client_data, caddr_t call_data)
{ system("xclock &"); }

void Xterm(Widget w, caddr_t client_data, caddr_t call_data)
{ system("xterm &"); }

void Quit(Widget w, caddr_t client_data, caddr_t call_data)
{
	fprintf(stderr, "exiting  . . .\n");
	exit(0);
}
main(int argc, char **argv)
{
	Widget rowcolumn, label, xclock, xterm, quit, form, topLevel;
	int i = 0;
	Arg args[9];

/* Create Widgets */
	topLevel = XtInitialize(argv[0], "XMCmds1", NULL, 0, &argc, argv);
	form = XtCreateManagedWidget("form", xmFormWidgetClass, 
	       topLevel, NULL, 0);

/* Launch application with any command argument to use the */
/* Text label string and font list for the label widget */

	if (argc == 2) {
/* Create the font list and translate the label using it */
		retval = getcmwplabel(&cmwlabel);
		getcsl(&senslabel, &cmwlabel);
		italic = XLoadQueryFont(XtDisplay(topLevel),
			"-adobe-times-medium-i-*-*-14-*-*-*-*-*-iso8859-1");
		fontlist = XmFontListCreate(italic, "italic");
		xmstr = (XmString)Xbsltos(XtDisplay(topLevel), &senslabel,
			width, fontlist, LONG_WORDS);

/* Create a label widget using the font list and label text*/
		i=0;
		XtSetArg(args[i], XmNfontList, fontlist); i++;
		XtSetArg(args[i], XmNlabelString, xmstr); i++;
		label = XtCreateManagedWidget("label", xmLabelWidgetClass, 
			form, args, i);
	}

/* Launch application with no command arguments to use the text */
/* in the resource file for the label widget */

	else {
		label = XtCreateManagedWidget("label", xmLabelWidgetClass, 
		        form, NULL, 0); }

/* Continue widget creation */
	i=0;
	XtSetArg(args[i], XmNtopAttachment, XmATTACH_WIDGET); i++;
	XtSetArg(args[i], XmNtopWidget, label); i++;
	XtSetArg(args[i], XmNleftAttachment, XmATTACH_FORM); i++;
	XtSetArg(args[i], XmNrightAttachment, XmATTACH_POSITION); i++;
	XtSetArg(args[i], XmNrightPosition, 33); i++;
	XtSetArg(args[i], XmNbottomAttachment, XmATTACH_FORM); i++;
	xclock = XtCreateManagedWidget("xclock", xmPushButtonWidgetClass, 
	   form, args, i);

	i=0;
	XtSetArg(args[i], XmNtopAttachment, XmATTACH_WIDGET); i++;
	XtSetArg(args[i], XmNtopWidget, label); i++;
	XtSetArg(args[i], XmNleftAttachment, XmATTACH_POSITION); i++;
	XtSetArg(args[i], XmNleftPosition, 33); i++;
	XtSetArg(args[i], XmNrightAttachment, XmATTACH_POSITION);i++;Ha>

Changing Window Configuration

Window behavior in the Trusted Solaris operating environment can be modified by changing the settings in these files: