te
Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
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

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

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 following fields of the ModLabelData structure.

lbuild_dialog

ok

cancel

reset

help

The tsol_lbuild_create() parameter list takes the following values:

widget

ok_callback

..., NULL

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

LBUILD_VALUE_SL

LBUILD_VALUE_CLR

LBUILD_USERFIELD

LBUILD_SHOW

LBUILD_TITLE

LBUILD_WORK_SL

LBUILD_WORK_CLR

LBUILD_X

LBUILD_Y

LBUILD_LOWER_BOUND

LBUILD_UPPER_BOUND

LBUILD_CHECK_AR

LBUILD_VIEW

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 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.

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

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

/etc/security/tsol/label_encodings

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Committed
MT-Level	MT-Safe

libtsol(3LIB), label_encodings(4), attributes(5)

Label Builder APIs in Solaris Trusted Extensions Developer's Guide

The functionality described on this manual page is available only if the system is configured with Trusted Extensions.