Chapter 15 Label Builder

The Trusted Solaris environment provides a set of Motif-based programming interfaces for creating an interactive user interface that builds valid sensitivity labels, CMW labels, or clearances from user input. This set of interfaces is called Label builder, and will be most often called from within administrative applications.

Label builder graphical user interfaces are used in the Trusted Solaris environment. The Trusted Solaris User's Guide describes these interfaces from the end user's point of view. This discussion describes the functionality provided by the Label builder library routines.

• "Header Files and Libraries"

• "Programming Interfaces"

• "Creating an Interactive User Interface"

• "Online Help"

Header Files and Libraries

To use the programming interfaces described in this section, you need the following header file.

#include <Dt/ModLabel.h>

The examples in this chapter compile with the following libraries:

-lDtTsol -ltsol

Programming Interfaces

The following programming interfaces are available for building label GUIs. The data types and parameter lists are covered in "Creating an Interactive User Interface".

ModLabelData *tsol_lbuild_create(Widget widget,
	void (*event_handler)() ok_callback,
		lbuild_attributes extended_operation
		...,
	 	NULL);

	void tsol_lbuild_destroy(ModLabelData *lbdata);

	void *tsol_lbuild_get(ModLabelData *lbdata,
		lbuild_attributes extended_operation);

	void tsol_lbuild_set(ModLabelData *lbdata,
		lbuild_attributes extended_operation,
		...,
		NULL);

Creating an Interactive User Interface

The following figure shows the graphical user interface (GUI) created from the code after the figure. The main program creates a parent form (form) with one pushbutton (display). The pushbutton callback displays the Label builder dialog box created in the call to tsol_lbuild_create(3TSOL).

Figure 15-1 CMW Label Building Interface

The Label builder dialog box on the right appears when the Show pushbutton on the left is selected. The callouts point out where the parameters passed to tsol_lbuild_create(3TSOL) appear on the Label builder dialog box.

#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <Xm/Xm.h>
#include <Xm/PushB.h>
#include <Xm/Form.h>
#include <Dt/ModLabel.h>

ModLabelData *data;

/* Callback passed to tsol_lbuild_create() */
void callback_function()
{ 
	char *title, *userval;
	char *string = (char *)0;
	char *string1 = (char *)0;
	int mode, view;
	Boolean show;
	bslabel_t sl_label, work_sl_label;
	Position x, y;

/* Your application-specific implementation goes here */
	printf("OK pushbutton called\n"); 

/* Query settings */
	mode = (int)tsol_lbuild_get(data, LBUILD_MODE);
	title = (String)tsol_lbuild_get(data, LBUILD_TITLE);
	sl_label = *(bslabel_t*) tsol_lbuild_get(data, LBUILD_VALUE_SL);
	work_sl_label = *(bslabel_t*) tsol_lbuild_get(data, LBUILD_WORK_SL);
	view = (int )tsol_lbuild_get(data, LBUILD_VIEW);
	x = (Position ) tsol_lbuild_get(data, LBUILD_X);
	y = (Position ) tsol_lbuild_get(data, LBUILD_Y);
	userval = (char *)tsol_lbuild_get(data, LBUILD_USERFIELD);
	show = (Boolean )tsol_lbuild_get(data, LBUILD_SHOW);

	bsltos(&sl_label, &string, 0, LONG_WORDS);
	bsltos(&work_sl_label, &string1, 0, LONG_WORDS);
	printf("Mode = %d, Title = %s, SL = %s, WorkSL = %s, View = %d, ",
		mode, title, string, string1, view);
	printf("X = %d, Y = %d, Userval = %s, Show = %d\n",
		x, y, userval, show);

}

/* Callback to display dialog box upon pushbutton press */
void Show(Widget display, caddr_t client_data, caddr_t call_data)
{
	tsol_lbuild_set(data, LBUILD_SHOW, TRUE, NULL);
}

main(int argc, char **argv)
{
	Widget 	form, topLevel, display;
	Arg args[9];
	int i = 0, error, retval;
	char *sl_string = "[C]";
	bslabel_t sl_label;

	topLevel = XtInitialize(argv[0], "XMcmds1", NULL, 0, &argc, argv);
	form = XtCreateManagedWidget("form",
		xmFormWidgetClass, topLevel, NULL, 0);

	retval = stobsl(sl_string, &sl_label, NEW_LABEL, &error);
	printf("Retval = %d\n", retval);

	data = tsol_lbuild_create( form, callback_function,
		LBUILD_MODE, LBUILD_MODE_SL,
		LBUILD_TITLE, "Building Sensitivity Label",
		LBUILD_VALUE_SL, sl_label,
		LBUILD_VIEW, LBUILD_VIEW_EXTERNAL,
		LBUILD_X, 200,
		LBUILD_Y, 200,
		LBUILD_USERFIELD, "/export/home/zelda",
		LBUILD_SHOW, FALSE,
		NULL);

	i = 0;
	XtSetArg(args[i], XmNtopAttachment, XmATTACH_FORM); i++;
	XtSetArg(args[i], XmNleftAttachment, XmATTACH_FORM); i++;
	XtSetArg(args[i], XmNrightAttachment, XmATTACH_FORM); i++;
	XtSetArg(args[i], XmNbottomAttachment, XmATTACH_FORM); i++;
	display = XtCreateManagedWidget("Show",
		xmPushButtonWidgetClass, form, args, i);
	XtAddCallback(display, XmNactivateCallback, Show,0);
	XtRealizeWidget(topLevel);

	XtMainLoop();

	tsol_lbuild_destroy(data);

}

The printf(1) statements print the following:

OK pushbutton called  
Mode = 12, Title = Building Sensitivity label, 
Label = [C], WorkSL = [S], 
View = 1, X = 200, Y = 200, 
Userval = /export/home/zelda, 
Show = 1

Label Builder Behavior

The Label builder dialog box prompts the end user for information and generates a valid CMW label from the input. The input can be entered from the keyboard or by choosing options. Either way, Label builder ensures that a valid label or clearance as defined in the label_encodings(4) file for the system is built.

Label builder provides default behavior for the OK, Reset, Cancel, and Update pushbuttons. The callback passed to tsol_lbuild_create(3TSOL) is mapped to the OK pushbutton to provide application-specific behavior.

Keyboard Entry

The Update pushbutton takes the text the end user types into the Update With field and checks that the string is a valid label or clearance as defined in the label_encodings(4) file.

• If the input is not valid, Label builder raises an error to the end user.

• If the input is valid, Label builder updates the text in the Label field above and stores the value in the appropriate working label field of the ModLabelData variable returned by tsol_lbuild_create(3TSOL). See "ModLabelData Structure".

When the end user selects the OK pushbutton, the user-built value is handled according to the OK pushbutton callback implementation.

Selecting Options

The Label Settings radio button options let you build a sensitivity label or clearance from classifications and compartments, or an information label from classifications, compartments, and markings. Depending on the mode, one of these buttons might be grayed out. This approach is independent of the keyboard entry and Update pushbutton method described above.

The classifications, compartments, and markings information are from the label_encodings(4) file for the system. The combinations and constraints specified in the label_encodings file are enforced by graying out invalid combinations. The Label field updates the Label field above and stores the value in the appropriate working label field of the ModLabelData variable returned by tsol_lbuild_create(3TSOL) (see "ModLabelData Structure") when the end user chooses options. The end user can build a sensitivity label, clearance, or sensitivity label portion of a CMW label from the classifications (CLASS) and compartments (COMPS) radio buttons listed.

When the end user selects the OK pushbutton, the user-built value is handled according to the OK pushbutton callback implementation.

Reset Pushbutton

The Rest pushbutton sets the text in the Label field to what its value was when the application started.

Cancel Pushbutton

The Cancel pushbutton exits the application.

Application-Specific Functionality

It is up to you to add application-specific callbacks, error handling, and other functionality to go with the valid label or clearance generated by the Label builder user interface.

Privileged Operations

Label builder shows the user only those classifications (and related compartments and markings) dominated by the workspace sensitivity label unless the executable has the sys_trans_label privilege in its effective set.

Your application-specific implementation for the OK pushbutton callback might require privileges.

If the end user does not have the authorization to upgrade or downgrade labels, or if the user-built label is out of the user's accreditation range, the OK and Reset buttons are grayed to prevent the end user from completing the task. There are no privileges to override these restrictions.

Create Routine

The tsol_lbuild_create(3TSOL) routine accepts any widget, Boolean value, callback, and a NULL terminated series of operation and value pairs. A variable of type ModLabelData is returned.

• Widget - Label builder can build the dialog box from any widget.

• Callback function - The callback function activates when the OK pushbutton is pressed. This callback provides application-specific behavior.

• Operation and value pairs - The operation (left) side of the pair specifies an extended operation (see "Extended Operations") and the value (right) side specifies the value. In some cases, the value is an enumerated constant, and in other cases, you provide a value. The pairs can be specified in any order, but every operation you specify requires a valid value.

• The return value is a data structure that contains information on the dialog box just created. The information comes from the tsol_lbuild_create(3TSOL) input parameters and user activities during execution. Label builder provides default values for some fields where no values have been specified.

  Use the tsol_lbuild_get(3TSOL) and tsol_lbuild_set(3TSOL) routines to programmatically access and change the information in this variable. The data structure is described in "ModLabelData Structure".

	data= tsol_lbuild_create( form, callback_function,
		LBUILD_MODE, LBUILD_MODE_CMW,
		LBUILD_TITLE, "Building CMW Label",
		LBUILD_VALUE_CMW, cmwlabel,
		LBUILD_VIEW, LBUILD_VIEW_EXTERNAL
		LBUILD_X, 200,
		LBUILD_Y, 200,
		LBUILD_USERFIELD "/export/home/zelda"
		LBUILD_SHOW, FALSE,
		NULL);

Extended Operations

This section describes the extended operations and valid values you can pass to tsol_lbuild_create(3TSOL), tsol_lbuild_get(3TSOL), and tsol_lbuild_set(3TSOL). The values passed to tsol_lbuild_create() are stored in its return value of type ModLabelData where they can be accessed by calls to tsol_lbuild_get() and tsol_lbuild_set(). The ModLabelData structure is described in "ModLabelData Structure".

All extended operations are valid to pass to tsol_lbuild_get(3TSOL). However the *WORK* operations are not valid to pass to tsol_lbuild_set(3TSOL) or tsol_lbuild_create(3TSOL) because these values are set by Label builder according to end user input. These exceptions are noted in the descriptions.

LBUILD_MODE - You can tell tsol_lbuild_create() to create a user interface to build information labels, sensitivity labels, CMW labels, or clearances. Value is LBUILD_MODE_CMW by default.

• LBUILD_MODE_SL - Build a sensitivity label.

• LBUILD_MODE_CMW - Build a CMW label.

• LBUILD_MODE_CLR - Build a clearance.

Knowing how labels are configured for the system on which your application will run can help you know which mode to use. For example, you would not have a user build an information label on a system that does not use information labels. "Query System Security Configuration" in Chapter 2, Getting Startedexplains how to check the system security configuration.

LBUILD_VALUE_SL - The starting sensitivity label displayed in the Label field above the Update With field when the mode is LBUILD_MODE_SL. This value is ADMIN_LOW by default.

LBUILD_VALUE_CMW - The starting CMW label displayed in the Label field above the Update With field when the mode is LBUILD_MODE_CMW. This value is ADMIN_LOW[ADMIN_LOW] by default.

LBUILD_VALUE_CLR - The starting clearance displayed in the Label field above the Update With field when the mode is LBUILD_MODE_CL. This value is ADMIN_LOW by default.

LBUILD_USERFIELD - A character string prompt that displays at the top of the Label builder dialog box. Value is NULL by default.

LBUILD_SHOW - Show or hide the Label builder dialog box. Value is FALSE by default.

• TRUE - Show the Label builder dialog box.

• FALSE - Hide the Label builder dialog box.

LBUILD_TITLE - A character string title that appears at the top of the Label builder dialog box. Value is NULL by default.

LBUILD_WORK_SL - The sensitivity label the end user is building. Value is updated to the end user's input when the end user selects the Update pushbutton or interactively chooses an option. Value is ADMIN_LOW by default. Not a valid extended operation for tsol_lbuild_set(3TSOL) or tsol_lbuild_create(3TSOL).

LBUILD_WORK_CMW - The CMW label the end user is building. Value is updated to the end user's input value when the end user selects the Update pushbutton or interactively chooses an option. Value is ADMIN_LOW[ADMIN_LOW] by default. Not a valid extended operation for tsol_lbuild_set(3TSOL)or tsol_lbuild_create(3TSOL)

LBUILD_WORK_CLR - The clearance the end user is building. Value is updated to the end user's input value when the end user selects the Update pushbutton or interactively chooses an option. Value is ADMIN_LOW by default. Not a valid extended operation for tsol_lbuild_set(3TSOL) or tsol_lbuild_create(3TSOL)

LBUILD_X - The X offset in pixels from the top-left corner of the Label builder dialog box in relation to the top-left corner of the screen. By default the Label builder dialog box is positioned in the middle of the screen.

LBUILD_Y - The Y offset in pixels from the top-left corner of the Label builder dialog box in relation to the top-left corner of the screen. By default the Label builder dialog box is positioned in the middle of the screen.

LBUILD_UPPER_BOUND - The highest classification (and related compartments and markings) available to the user as radio buttons for interactively building a label or clearance. A value you supply should be within the user's accreditation range. If no value is supplied, this value is the user's workspace sensitivity label, or if the executable has the sys_trans_label privilege, this value is the user's clearance.

LBUILD_LOWER_BOUND - The lowest classification (and related compartments and markings) available to the user as radio buttons for interactively building a label or clearance. This value is the user's minimum label.

LBUILD_CHECK_AR - Check that the user-built label is within the user's accreditation range. A value of 1 means check and a value of 0 means do not check. If the label is out of range, an error message is raised to the end user. The default is check.

LBUILD_VIEW - Use the internal or external label representation. Value is LBUILD_VIEW_EXTERNAL by default.

• LBUILD_VIEW_INTERNAL - Use the internal names for the highest and lowest labels in the system: ADMIN_HIGH and ADMIN_LOW.

• LBUILD_VIEW_EXTERNAL - Promote an ADMIN_LOW label to the next lowest label and demote an ADMIN_HIGH label to the next highest label.

ModLabelData Structure

The ModLabelData structure contains information on the state of the Label builder interface created in the call to tsol_lbuild_create(3TSOL). The following table describes the ModLabelData fields. All fields except the widgets and callback are accessible by specifying the listed extended operation and a valid value in a call to tsol_lbuild_set(3TSOL) and/or tsol_lbuild_get(3TSOL). See "Extended Operations" for descriptions of the extended operations.

Online Help

The Help pushbutton and other widgets used in the user interface can be accessed directly from your application code through the lbl_shell field in the ModLabelData structure. To add online help to your application, follow the procedures and guidelines in the document listed below.

Common Desktop Environment: Help System Author's and Programmer's Guide, Part No. 802-1578-10, from Sun Microsystems, Inc.