Solaris Trusted Extensions Developer's Guide

Chapter 6 Trusted X Window System

This chapter describes the Trusted Extensions X Window System APIs. This chapter also includes a short Motif application that is used to describe the Trusted X Window System security policy and the Solaris Trusted Extensions interfaces.

For examples of how the Trusted Extensions APIs are used in the Solaris OS, see the Solaris source code. Go to the OpenSolaris web site and click Source Browser in the left navigation bar. Use the Source Browser to search through the Solaris source code.

This chapter covers the following topics:

Trusted X Window System Environment

A system that is configured with Solaris Trusted Extensions uses the Trusted Extensions X Window System. The Trusted Extensions X Window System includes protocol extensions to support mandatory access control (MAC), discretionary access control (DAC), and the use of privileges.

Data transfer sessions are polyinstantiated, meaning that they are instantiated at different sensitivity labels and user IDs. Polyinstantiation ensures that 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. Such a transfer might violate the Trusted X Window System DAC policies and the MAC policies of write-equal and read-down.

The Trusted Extensions X Window System APIs enable you to obtain and set security-related attribute information. These APIs also enable you to translate labels to strings by using a font list and width to apply a style to the text string output. For example, the font might be 14-point, bold Helvetica. These interfaces are usually called by administrative applications.

Obtaining security-related information – These interfaces operate at the Xlib level where X protocol requests are made. Use Xlib interfaces to obtain data for the input parameter values.
Translating labels to strings – These interfaces operate at the Motif level. The input parameters are the label, a font list that specifies the appearance of the text string output, and the desired width. A compound string of the specified style and width is returned.

For declarations of these routines, see Trusted Extensions X Window System APIs.

Trusted X Window System Security Attributes

The Trusted X Window System interfaces manage security-related attribute information for various X Window System objects. You can choose to create a GUI application with Motif only. The Motif application should use XToolkit routines to retrieve the Xlib object IDs underlying the Motif widgets to handle security attribute information for an Xlib object.

The X Window System 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 the window, property, display, and client connection IDs.

A window displays output to the user and accepts input from clients.

A property is an arbitrary collection of data that is accessed by the property name. Property names and property types can be referenced by an atom, which is a unique, 32-bit identifier and a character name string.

The security attributes for windows, properties, and client connections consist of ownership IDs and sensitivity label information. For information about the structures for capturing some of these attributes, see Data Types for X11. For information about the interfaces that obtain and set security attribute information, see Trusted Extensions X Window System APIs.

Trusted X Window System Security Policy

Window, property, and pixmap objects have a user ID, a client ID, and a sensitivity 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, an X Window Server ID, and a sensitivity 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 DAC policy requires a client to own an object to perform any operations on that 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.

The MAC policy is write-equal for windows and pixmaps, and read-equal for naming windows. The MAC policy is read-down for properties. The sensitivity label is set to the sensitivity label of the creating client. The following shows the MAC policy for these actions:

Modify, create, or delete – The sensitivity label of the client must equal the object's sensitivity label.
Name, read, or retrieve – The client's sensitivity label must dominate the object's sensitivity label.
Connection request – The sensitivity label of the client must be dominated by the session clearance of the owner of the X Window Server workstation, or the client must assert the Trusted Path attribute.

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 MAC and DAC restrictions. To specify properties that are not polyinstantiated, update the TrustedExtensionsPolicy file.

The TrustedExtensionsPolicy file is supported for the Xsun server and the Xorg server:

SPARC: For Xsun, the file is in /usr/openwin/server/etc.
x86: For Xorg, the file is in /usr/X11/lib/X11/xserver.

These sections describe the security policy for the following:

Root window
Client windows
Override-redirect windows
Keyboard, pointer, and server control
Selection Manager
Default window resources
Moving data between windows

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 it 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. This prevents 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 MAC and DAC to gain control of the keyboard, pointer, and server. To reset the focus, a client must own the focus or have the win_devices privilege in its effective set.

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

Selection Manager

The Selection Manager application arbitrates user-level interwindow data moves, such as cut and paste or drag and drop, where information is transferred between untrusted windows. When a transfer is attempted, the Selection Manager captures the transfer, verifies the controlling user's authorization, and requests confirmation and labeling information from the user. Any time the user attempts a data move, the Selection Manager automatically appears. You do not need to update your application code to get the Selection Manager to appear.

The administrator can set automatic confirmation for some transfer types, in which case the Selection Manager does not appear. If the transfer meets the MAC and DAC policies, the data transfer completes. The File Browser and the window manager also act as selection agents for their private drop sites. See the /usr/X11/lib/X11/xserver/TrustedExtensionsPolicy file to specify selection targets that are polyinstantiated. See the /usr/share/gnome/sel_config file to determine which selection targets are automatically confirmed.

Default Window Resources

Resources that are not created by clients are default resources that are protected at ADMIN_LOW. Only clients that run at ADMIN_LOW or with the appropriate privileges can modify default resources.

The following are window resources:

Root window attributes – All clients have read and create access, but only privileged clients have write or modify access. See Privileged Operations and the Trusted X Window System.
Default cursor – Clients are free to reference the default cursor in protocol requests.
Predefined atoms – The TrustedExtensionsPolicy file contains a read-only list of predefined atoms.

Moving Data Between Windows

A client needs the win_selection privilege in its effective set to move data between one window and another window without going through the Selection Manager. See Selection Manager.

Privileged Operations and the Trusted X Window System

Library routines that access a window, property, or atom name without user involvement require MAC and DAC. Library routines that access frame buffer graphic contexts, fonts, and cursors require discretionary access and might also require additional privileges for special tasks.

The client might 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 the TrustedExtensionsPolicy file to enable or disable these privileges.

This list shows the privileges needed to perform the following tasks:

Configuring and destroying window resources – A client process needs the win_config privilege in its effective set to configure or destroy windows or properties that are permanently retained by the X Window Server. The screen saver timeout is an example of such a resource.
Using window input devices – A client process needs the win_devices privilege in its effective set to obtain and set keyboard and pointer controls, or to modify pointer button mappings and key mappings.
Using direct graphics access – A client process needs the win_dga privilege in its effective set to use the direct graphics access (DGA) X protocol extension.
Downgrading window labels – A client process needs the win_downgrade_sl privilege in its effective set to change the sensitivity label of a window, pixmap, or property to a new label that does not dominate the existing label.
Upgrading window labels – A client process needs the win_upgrade_sl privilege in its effective set to change the sensitivity label of a window, pixmap, or property to a new label that dominates the existing label.
Setting a font path on a window – A client process needs the win_fontpath privilege in its effective set to modify the font path.

Trusted Extensions X Window System APIs

To use the Trusted X11 APIs, you need the following header file:

#include <X11/extensions/Xtsol.h>

The Trusted X11 examples compile with the -lXtsol and -ltsol library options.

To use the X11 label-clipping APIs, you need the following header file:

#include <Dt/label_clipping.h>

The label-clipping examples compile with the -lDtTsol and -ltsol library options.

The following sections provide data types and declarations for the Trusted X11 interfaces and the X11 label-clipping interfaces:

Data types for X11
Accessing attributes
Accessing and setting a window label
Accessing and setting a window user ID
Accessing and setting a window property label
Accessing and setting a window property user ID
Accessing and setting a workstation owner ID
Setting the X Window Server clearance and minimum label
Working with the Trusted Path window
Accessing and setting the screen stripe height
Setting window polyinstantiation information
Working with the X11 label-clipping interface

Data Types for X11

The following data types are defined in X11/extensions/Xtsol.h and are used for the Trusted Extensions X Window System APIs:

Object type for X11 – The ResourceType definition indicates the type of resource to be handled. The value can be IsWindow, IsPixmap, or IsColormap.

ResourceType is a type definition to represent a clearance. Interfaces accept a structure of type m_label_t as parameters and return clearances in a structure of the same type.

Object attributes for X11 –The XTsolResAttributes structure contains these resource attributes:

typedef struct _XTsolResAttributes {
    CARD32     ouid;    /* owner uid */
    CARD32     uid;     /* uid of the window */
    m_label_t  *sl;     /* sensitivity label */
} XTsolResAttributes;

Property attributes for X11 – The XTsolPropAttributes structure contains these property attributes:

typedef struct _XTsolPropAttributes {
    CARD32     uid;     /* uid of the property */
    m_label_t  *sl;     /* sensitivity label */
} XTsolPropAttributes;

Client attributes for X11 – The XTsolClientAttributes structure contains these client attributes:

typedef struct _XTsolClientAttributes {
    int      trustflag; /* true if client masked as trusted */
    uid_t    uid;       /* owner uid who 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 addr of host where client is running */
} XTsolClientAttributes;

Accessing Attributes

The following routines are used to access resource, property, and client attributes:

Status XTSOLgetResAttributes(Display *display, XID object, ResourceType type, XTSOLResAttributes *winattrp);: This routine returns the resource attributes for a window ID in winattrp. See the XTSOLgetResAttributes(3XTSOL) man page.
Status XTSOLgetPropAttributes(Display *display, Window window, Atom property, XTSOLPropAttributes *propattrp);: This routine returns the property attributes for a property hanging on a window ID in propattrp. See the XTSOLgetPropAttributes(3XTSOL) man page.
Status XTSOLgetClientAttributes(Display *display, XID windowid, XTsolClientAttributes *clientattrp);: This routine returns the client attributes in clientattrp. See the XTSOLgetClientAttributes(3XTSOL) man page.

Accessing and Setting a Window Label

The XTSOLgetResLabel() and XTSOLsetResLabel() routines are used to obtain and set the sensitivity label of a window.

Status XTSOLgetResLabel(Display *display, XID object, ResourceType type, m_label_t *sl);: This routine obtains the sensitivity label of a window. See the XTSOLgetResLabel(3XTSOL) man page.
Status XTSOLsetResLabel(Display *display, XID object, ResourceType type, m_label_t *sl);: This routine sets the sensitivity label of a window. See the XTSOLsetResLabel(3XTSOL) man page.

Accessing and Setting a Window User ID

The XTSOLgetResUID() and XTSOLsetResUID() routines are used to obtain and set the user ID of a window.

Status XTSOLgetResUID(Display *display, XID object, ResourceType type, uid_t *uidp);: This routine obtains the user ID of a window. See the XTSOLgetResUID(3XTSOL) man page.
Status XTSOLsetResUID(Display *display, XID object, ResourceType type, uid_t *uidp);: This routine sets the user ID of a window. See the XTSOLsetResUID(3XTSOL) man page.

Accessing and Setting a Window Property Label

The XTSOLgetPropLabel() and XTSOLsetPropLabel() routines are used to obtain and set the sensitivity label of a property hanging on a window ID.

Status XTSOLgetPropLabel(Display *display, Window window, Atom property, m_label_t *sl);: This routine obtains the sensitivity label of a property hanging on a window ID. See the XTSOLgetPropLabel(3XTSOL) man page.
Status XTSOLsetPropLabel(Display *display, Window window, Atom property, m_label_t *sl);: This routine sets the sensitivity label of a property hanging on a window ID. See the XTSOLsetPropLabel(3XTSOL) man page.

Accessing and Setting a Window Property User ID

The XTSOLgetPropUID() and XTSOLsetPropUID() routines are used to obtain and set the user ID of a property hanging on a window ID.

Status XTSOLgetPropUID(Display *display, Window window, Atom property, uid_t *uidp);: This routine obtains the user ID of a property hanging on a window ID. See the XTSOLgetPropUID(3XTSOL) man page.
Status XTSOLsetPropUID(Display *display, Window window, Atom property, uid_t *uidp);: This routine sets the user ID of a property hanging on a window ID. See the XTSOLsetPropUID(3XTSOL) man page.

Accessing and Setting a Workstation Owner ID

The XTSOLgetWorkstationOwner() and XTSOLsetWorkstationOwner() routines are used to obtain and set the user ID of the owner of the workstation server.

Note –

The XTSOLsetWorkstationOwner() routine should only be used by the window manager.

Status XTSOLgetWorkstationOwner(Display *display, uid_t *uidp);: This routine obtains the user ID of the owner of the workstation server. See the XTSOLgetWorkstationOwner(3XTSOL) man page
Status XTSOLsetWorkstationOwner(Display *display, uid_t *uidp);: This routine sets the user ID of the owner of the workstation server. See the XTSOLsetWorkstationOwner(3XTSOL) man page.

Setting the X Window Server Clearance and Minimum Label

The XTSOLsetSessionHI() and XTSOLsetSessionLO() routines are used to set the session high clearance and the session low minimum label for the X Window Server. Session high must be within the user's range. Session low is the same as the user's minimum label for the multilevel session.

Note –

These interfaces should only be used by the window manager.

Status XTSOLsetSessionHI(Display *display, m_label_t *sl);: The session high clearance is set from the workstation owner's clearance at login. The session high clearance must be dominated by the owner's clearance and by the upper bound of the machine monitor's label range. Once changed, connection requests from clients that run at a sensitivity label higher than the window server clearance are rejected unless they have privileges. See the XTSOLsetSessionHI(3XTSOL) man page.
Status XTSOLsetSessionLO(Display *display, m_label_t *sl);: The session low minimum label is set from the workstation owner's minimum label at login. The session low minimum label must be greater than the user's administratively set minimum label and the lower bound of the machine monitor's label range. When this setting is changed, connection requests from clients that run at a sensitivity label lower than the window server sensitivity label are rejected unless they have privileges. See the XTSOLsetSessionLO(3XTSOL) man page.

Working With the Trusted Path Window

The XTSOLMakeTPWindow() and XTSOLIsWindowTrusted() routines are used to make the specified window the Trusted Path window and to test whether the specified window is the Trusted Path window.

Status XTSOLMakeTPWindow(Display *display, Window *w);: This routine makes the specified window the Trusted Path window. See the XTSOLMakeTPWindow(3XTSOL) man page.
Bool XTSOLIsWindowTrusted(Display *display, Window *window);: This routine tests whether the specified window is the Trusted Path window. See the XTSOLIsWindowTrusted(3XTSOL) man page.

Accessing and Setting the Screen Stripe Height

The XTSOLgetSSHeight() and XTSOLsetSSHeight() routines are used to obtain and set the screen stripe height.

Note –

These interfaces should only be used by the window manager.

Status XTSOLgetSSHeight(Display *display, int screen_num, int *newHeight);: This routine obtains the screen stripe height. See the XTSOLgetSSHeight(3XTSOL) man page.
Status XTSOLsetSSHeight(Display *display, int screen_num, int newHeight);: This routine sets the screen stripe height. Be careful that you do not end up without a screen stripe or with a very large screen stripe. See the XTSOLsetSSHeight(3XTSOL) man page.

Setting Window Polyinstantiation Information

Status XTSOLsetPolyInstInfo(Display *display, m_label_t sl, uid_t *uidp, int enabled);: The XTSOLsetPolyInstInfo() routine enables a client to obtain property information from a property at a different sensitivity label than the client. In the first call, you specify the desired sensitivity label and the user ID, and set the enabled property to True. Then, you call XTSOLgetPropAttributes(), XTSOLgetPropLabel(), or XTSOLgetPropUID(). To finish, you call the XTSOLsetPolyInstInfo() routine again with the enabled property set to False. See the XTSOLsetPolyInstInfo(3XTSOL) man page.

Working With the X11 Label-Clipping Interface

int label_to_str(const m_label_t *label, char **string, const m_label_str_t conversion_type, uint_t flags);: The label_to_str() routine translates a sensitivity label or clearance to a string. See the label_to_str(3TSOL) man page.

Using Trusted X Window System Interfaces

The following sections provide example code excerpts that use Trusted Extensions interface calls. These calls handle security attributes and translate a label to a string. The excerpts focus on handling window security attributes, the most commonly managed attributes in application programs. Often, a client retrieves security attributes by using the appropriate privileges for an object that was created by another application. The client then checks the attributes to determine whether an operation on the object is permitted by the system's security policy. The security policy covers DAC policies and the MAC write-equal and read-down policies. If access is denied, the application generates an error or uses privileges, as appropriate. See Privileged Operations and the Trusted X Window System for a discussion about when privileges are needed.

You must create an object before you can retrieve its ID to pass to the Trusted Extensions APIs.

Obtaining Window Attributes

The XTSOLgetResAttributes() routine returns security-related attributes for a window. You supply the following:

Display ID
Window ID
Flag to indicate that the object for which you want security attributes is a window
XtsolResAttributes structure to receive the returned attributes

Because the client is obtaining the security attributes for a window that the client created, no privileges are required.

Note that the example programs in this book focus on the APIs being shown and do not perform error checking. Your applications should perform the appropriate error checking.

/* 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 = label_to_str(&winattrs.sl, &plabel, M_LABEL, LONG_NAMES);

/* Print security attribute information */
   printf(“Workstation Owner ID = %d\nUser ID = %d\nLabel = %s\n”,
   winattrs.ouid, winattrs.uid, string1);

The printf statement prints the following:

Workstation Owner ID = 29378
User ID = 29378
Label = CONFIDENTIAL

Translating the Window Label With the Font List

This example shows how to obtain the process sensitivity label and translate it to a string by using a font list and the pixel width. A label widget is created with the string for its label. The process sensitivity label equals the window sensitivity label. Therefore, no privileges are required.

When the final string is longer than the width, the string is clipped and the clipped indicator is used. Note that the X Window System label-translation interfaces clip to the specified number of pixels, while the label-clipping interfaces clip to the number of characters.

Note –

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. The following example does not work for the Asian character set.

	retval = getplabel(&senslabel);

/* 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);

Obtaining a Window Label

This example shows how to obtain the sensitivity label for a window. The process sensitivity label equals the window sensitivity label. Therefore, no privileges are required.

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

/* Translate labels to string and print */
	retval = label_to_str(label, &string, M_LABEL, LONG_NAMES);
	printf(“Label = %s\n”, string);

The printf statement, for example, prints the following:

Label = PUBLIC

Setting a Window Label

This example shows how to set the sensitivity label on a window. The new sensitivity label dominates the sensitivity label of the window and the process. The client needs the sys_trans_label privilege in its effective set to translate a label that the client does not dominate. The client also needs the win_upgrade_sl privilege to change the window's sensitivity label.

For more information about using privileges, see Solaris Security for Developers Guide.

/* Translate text string to sensitivity label */
   retval = label_to_str(string4, &label, M_LABEL, L_NO_CORRECTION, &error);

/* Set sensitivity label with new value */
   retval = XTSOLsetResLabel(display, window, IsWindow, label);

Obtaining the Window User ID

This example shows how to obtain the window user ID. The process owns the window resource and is running at the same sensitivity label. Therefore, no privileges are required.

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

Obtaining the X Window Server Workstation Owner ID

This example shows how to obtain the ID of the user who is logged in to the X Window Server. The process sensitivity label equals the window sensitivity label. Therefore, no privileges are required.

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