labelbuilder(3TSOL) Trusted Extensions Library Functions labelbuilder(3TSOL)NAME
labelbuilder, tsol_lbuild_create, tsol_lbuild_get, tsol_lbuild_set,
tsol_lbuild_destroy - create a Motif-based user interface for interac‐
tively 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 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 follow‐
ing 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 informa‐
tion 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 a sensitivity
label or a clearance. Value is LBUILD_MODE_SL by
default.
LBUILD_MODE_SL Build a sensitivity 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_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_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 push‐
button or interactively chooses an option.
LBUILD_X The X 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_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 compart‐
ments 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 compart‐
ments 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 sen‐
sitivity 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 accredita‐
tion 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 representa‐
tion. 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 high‐
est label, and demote an ADMIN_HIGH label to
the next lowest label.
RETURN VALUES
The tsol_lbuild_get() function returns −1 if it is unable to get the
value.
The tsol_lbuild_create() function returns a variable of type ModLabel‐
Data 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 Create a Label Builder.
(ModLabelData *)lbldata = tsol_lbuild_create(widget0, callback_function,
LBUILD_MODE, LBUILD_MODE_SL,
LBUILD_TITLE, "Setting Sensitivity Label",
LBUILD_VIEW, LBUILD_VIEW_INTERNAL,
LBUILD_X, 200,
LBUILD_Y, 200,
LBUILD_USERFIELD, "Pathname:",
LBUILD_SHOW, FALSE,
NULL);
Example 2 Query the Mode and Display the Label Builder.
These examples call the tsol_lbuild_get() function to query the mode
being used, and call the tsol_lbuild_set() function 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 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 │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Committed │
├─────────────────────────────┼─────────────────────────────┤
│MT-Level │MT-Safe │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOlibtsol(3LIB), label_encodings(4), attributes(5)
Label Builder APIs in Solaris Trusted Extensions Developer's Guide
NOTES
The functionality described on this manual page is available only if
the system is configured with Trusted Extensions.
SunOS 5.10 20 Jul 2007 labelbuilder(3TSOL)
