labelbuilder(3TSOL)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | FILES | ATTRIBUTES | SEE ALSO

NAME

labelbuilder, tsol_lbuild_create, tsol_lbuild_get, tsol_lbuild_set, tsol_lbuild_destroy- create a Motif-based user interface for interactively building a valid label or clearance

SYNOPSIS

cc [flag...] file... -ltsol -lDtTsol [library...]


#include <Dt/ModLabel.h>

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

DESCRIPTION

The label builder user interface prompts the end user for information and generates a valid CMW label, information label, sensitivity label, or clearance from the user input based on specifications in the label_encodings(4) file on the system where the application runs. The end user can build the label or clearance by typing a text value or by interactively choosing options.

Application-specific functionality is implemented in the callback for the OK pushbutton. This callback is passed to the tsol_lbuild_create() call where it is mapped to the OK pushbutton widget.

When choosing options, the label builder shows the user only those classifications (and related compartments and markings) dominated by the workspace sensitivity label unless the executable has the PRIV_SYS_TRANS_LABEL privilege in its effective set.

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 pushbuttons are grayed. There are no privileges to override these restrictions.

tsol_lbuild_create() creates the graphical user interface and returns a pointer variable of type ModLabeldata* that contains information on the user interface. This information is a combination of values passed in the tsol_lbuild_create() input parameter list, default values for information not provided, and information on the widgets used by the label builder to create the user interface. All information except the widget information should be accessed with the tsol_lbuild_get() and tsol_lbuild_set() routines.

The widget information is accessed directly by referencing the following fields of the ModLabelData structure.

lbuild_dialog

The label builder dialog box.

ok

The OK pushbutton.

cancel

The Cancel pushbutton.

reset

The Reset pushbutton.

help

The Help pushbutton.

The tsol_lbuild_create() parameter list takes the following values:

widget

The widget from which the dialog box is created. Any Motif widget can be passed.

ok_callback

A callback function that implements the behavior of the OK pushbutton on the dialog box.

..., NULL

A NULL terminated list of extended operations and value pairs that define the characteristics and behavior of the label builder dialog box.

tsol_lbuild_destroy() destroys the ModLabelData structure returned by tsol_lbuild_create().

tsol_lbuild_get() and tsol_lbuild_set() access the information stored in the ModLabelData structure returned by tsol_lbuild_create().

The following extended operations can be passed to tsol_lbuild_create() to build the user interface, to tsol_lbuild_get() to retrieve information on the user interface, and to tsol_lbuild_set() to change the user interface information. All extended operations are valid for tsol_lbuild_get(), but the *WORK* operations are not valid for tsol_lbuild_set() or tsol_lbuild_create() because these values are set from input supplied by the end user. These exceptions are noted in the descriptions.

LBUILD_MODE

Create a user interface to build an information label, sensitivity label, CMW label, or clearance. Value is LBUILD_MODE_CMW by default.

LBUILD_MODE_IL

Build an information label.

An information label is fixed at ADMIN_LOW.

LBUILD_MODE_SL

Build a sensitivity label.

LBUILD_MODE_CMW

Build a CMW label.

LBUILD_MODE_CLR

Build a clearance.

LBUILD_VALUE_SL

The starting sensitivity label. This value is ADMIN_LOW by default and is used when the mode is LBUILD_MODE_SL.

LBUILD_VALUE_IL

The starting information label. This value is ADMIN_LOW by default and is used when the mode is LBUILD_MODE_IL.

LBUILD_VALUE_CMW

The starting CMW label. This value is ADMIN_LOW[ADMIN_LOW] by default and is used when the mode is LBUILD_MODE_CMW.

LBUILD_VALUE_CLR

The starting clearance. This value is ADMIN_LOW by default and is used when the mode is LBUILD_MODE_CLR.

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

Not valid for tsol_lbuild_set() or tsol_lbuild_create(). 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.

LBUILD_WORK_IL

Not valid for tsol_lbuild_set() or tsol_lbuild_create(). The information 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.

LBUILD_WORK_CMW

Not valid for tsol_lbuild_set() or tsol_lbuild_create(). The CMW 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.

LBUILD_WORK_CLR

Not valid for tsol_lbuild_set() or tsol_lbuild_create(). The clearance 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.

LBUILD_X

The X position in pixels of the top-left corner of the label buider 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 position in pixels of 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_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_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 supplied value should be within the user's accreditation range. If no value is specified, the value is the user's workspace sensitivity label, or if the executable has the PRIV_SYS_TRANS_LABEL privilege, the value is the user's clearance.

LBUILD_CHECK_AR

Check that the user-built label entered in the Update With field is within the user's accreditation range. A value of 1 means check, and a value of 0 means do not check. If checking is on and the label is out of range, an error message is raised to the end user.

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 highest label, and demote an ADMIN_HIGH label to the next lowest label.

RETURN VALUES

The tsol_lbuild_get() returns -1 if it is unable to get the value.

The tsol_lbuild_create() routine returns a variable of type ModLabelData that contains the information provided in the tsol_lbuild_create() input parameter list, default values for information not provided, and information on the widgets used by the label builder to create the user interface.

EXAMPLES

---

Example 1 To create a Label Builder




(ModLabelData *)lbldata = tsol_lbuild_create(widget0, callback_function,
     LBUILD_MODE, LBUILD_MODE_CMW,
     LBUILD_TITLE, "Setting CMW Label", 
     LBUILD_VIEW, LBUILD_VIEW_INTERNAL,
     LBUILD_X, 200,
     LBUILD_Y, 200,
     LBUILD_USERFIELD, "Pathname:",
     LBUILD_SHOW, FALSE,
  NULL);

---

---

Example 2 To query the mode and display the Label Builder




These examples call the tsol_lbuild_get() routine to query the mode being used, and call the tsol_lbuild_set() routine so the label builder dialog box displays.

mode = (int)tsol_lbuild_get(lbldata, LBUILD_MODE );

tsol_lbuild_set(lbldata, LBUILD_SHOW, TRUE,
NULL);

---

---

Example 3 To destroy the ModLabelData variable




This example destroys the ModLabelData variable returned in the call to tsol_lbuild_create().

tsol_lbuild_destroy(lbldata);

---

FILES

/usr/dt/include/Dt/ModLabel.h

Header file for label builder functions

/etc/security/tsol/label_encodings

The label encodings file contains the classification names, words, constraints, and values for the defined labels of this system.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWtsu
MT-Level	MT-Safe

SEE ALSO

Trusted Solaris 8 4/01 Reference Manual

label_encodings(4)

Trusted Solaris Developer's Guide

SunOS 5.8 Reference Manual

attributes(5)

Trusted Solaris 8  Last Revised 24 May 2001

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | FILES | ATTRIBUTES | SEE ALSO