1labelbuilder(3TSOL) Trusted Extensions Library Functions labelbuilder(3TSOL)
2
6 labelbuilder, tsol_lbuild_create, tsol_lbuild_get, tsol_lbuild_set,
7 tsol_lbuild_destroy - create a Motif-based user interface for interac‐
8 tively building a valid label or clearance
9
11 cc [flag...] file... -ltsol -lDtTsol [library...]
12 #include <Dt/ModLabel.h>
15 ModLabelData *tsol_lbuild_create(Widget widget,
17 void (*event_handler)() ok_callback,
18 lbuild_attributes extended_operation, ..., NULL);
19 void *tsol_lbuild_get(ModLabelData *data,
22 lbuild_attributes extended_operation);
23 void tsol_lbuild_set(ModLabelData *data,
26 lbuild_attributes extended_operation, ..., NULL);
27 void tsol_lbuild_destroy(ModLabelData *data);
30
33 The label builder user interface prompts the end user for information
34 and generates a valid sensitivity label or clearance from the user
35 input based on specifications in the label_encodings(4) file on the
36 system where the application runs. The end user can build the label or
37 clearance by typing a text value or by interactively choosing options.
38 Application-specific functionality is implemented in the callback for
41 the OK pushbutton. This callback is passed to the tsol_lbuild_create()
42 call where it is mapped to the OK pushbutton widget.
43 When choosing options, the label builder shows the user only those
46 classifications (and related compartments and markings) dominated by
47 the workspace sensitivity label unless the executable has the
48 PRIV_SYS_TRANS_LABEL privilege in its effective set.
49 If the end user does not have the authorization to upgrade or downgrade
52 labels, or if the user-built label is out of the user's accreditation
53 range, the OK and Reset pushbuttons are grayed. There are no privileges
54 to override these restrictions.
55 tsol_lbuild_create() creates the graphical user interface and returns a
58 pointer variable of type ModLabeldata* that contains information on the
59 user interface. This information is a combination of values passed in
60 the tsol_lbuild_create() input parameter list, default values for
61 information not provided, and information on the widgets used by the
62 label builder to create the user interface. All information except the
63 widget information should be accessed with the tsol_lbuild_get() and
64 tsol_lbuild_set() routines.
65 The widget information is accessed directly by referencing the follow‐
68 ing fields of the ModLabelData structure.
69 lbuild_dialog The label builder dialog box.
71 ok The OK pushbutton.
74 cancel The Cancel pushbutton.
77 reset The Reset pushbutton.
80 help The Help pushbutton.
83 The tsol_lbuild_create() parameter list takes the following values:
87 widget The widget from which the dialog box is created. Any
89 Motif widget can be passed.
90 ok_callback A callback function that implements the behavior of the
93 OK pushbutton on the dialog box.
94 ..., NULL A NULL terminated list of extended operations and value
97 pairs that define the characteristics and behavior of
98 the label builder dialog box.
99 tsol_lbuild_destroy() destroys the ModLabelData structure returned by
103 tsol_lbuild_create().
104 tsol_lbuild_get() and tsol_lbuild_set() access the information stored
107 in the ModLabelData structure returned by tsol_lbuild_create().
108 The following extended operations can be passed to tsol_lbuild_create()
111 to build the user interface, to tsol_lbuild_get() to retrieve informa‐
112 tion on the user interface, and to tsol_lbuild_set() to change the user
113 interface information. All extended operations are valid for
114 tsol_lbuild_get(), but the *WORK* operations are not valid for
115 tsol_lbuild_set() or tsol_lbuild_create() because these values are set
116 from input supplied by the end user. These exceptions are noted in the
117 descriptions.
118 LBUILD_MODE Create a user interface to build a sensitivity
120 label or a clearance. Value is LBUILD_MODE_SL by
121 default.
122 LBUILD_MODE_SL Build a sensitivity label.
124 LBUILD_MODE_CLR Build a clearance.
127 LBUILD_VALUE_SL The starting sensitivity label. This value is
131 ADMIN_LOW by default and is used when the mode is
132 LBUILD_MODE_SL.
133 LBUILD_VALUE_CLR The starting clearance. This value is ADMIN_LOW
136 by default and is used when the mode is
137 LBUILD_MODE_CLR.
138 LBUILD_USERFIELD A character string prompt that displays at the
141 top of the label builder dialog box. Value is
142 NULL by default.
143 LBUILD_SHOW Show or hide the label builder dialog box. Value
146 is FALSE by default.
147 TRUE Show the label builder dialog box.
149 FALSE Hide the label builder dialog box.
152 LBUILD_TITLE A character string title that appears at the top
156 of the label builder dialog box. Value is NULL by
157 default.
158 LBUILD_WORK_SL Not valid for tsol_lbuild_set() or
161 tsol_lbuild_create(). The sensitivity label the
162 end user is building. Value is updated to the end
163 user's input when the end user selects the Update
164 pushbutton or interactively chooses an option.
165 LBUILD_WORK_CLR Not valid for tsol_lbuild_set() or
168 tsol_lbuild_create(). The clearance the end user
169 is building. Value is updated to the end user's
170 input when the end user selects the Update push‐
171 button or interactively chooses an option.
172 LBUILD_X The X position in pixels of the top-left corner
175 of the label builder dialog box in relation to
176 the top-left corner of the screen. By default the
177 label builder dialog box is positioned in the
178 middle of the screen.
179 LBUILD_Y The Y position in pixels of the top-left corner
182 of the label builder dialog box in relation to
183 the top-left corner of the screen. By default the
184 label builder dialog box is positioned in the
185 middle of the screen.
186 LBUILD_LOWER_BOUND The lowest classification (and related compart‐
189 ments and markings) available to the user as
190 radio buttons for interactively building a label
191 or clearance. This value is the user's minimum
192 label.
193 LBUILD_UPPER_BOUND The highest classification (and related compart‐
196 ments and markings) available to the user as
197 radio buttons for interactively building a label
198 or clearance. A supplied value should be within
199 the user's accreditation range. If no value is
200 specified, the value is the user's workspace sen‐
201 sitivity label, or if the executable has the
202 PRIV_SYS_TRANS_LABEL privilege, the value is the
203 user's clearance.
204 LBUILD_CHECK_AR Check that the user-built label entered in the
207 Update With field is within the user's accredita‐
208 tion range. A value of 1 means check, and a value
209 of 0 means do not check. If checking is on and
210 the label is out of range, an error message is
211 raised to the end user.
212 LBUILD_VIEW Use the internal or external label representa‐
215 tion. Value is LBUILD_VIEW_EXTERNAL by default.
216 LBUILD_VIEW_INTERNAL
218 Use the internal names for the highest and
220 lowest labels in the system: ADMIN_HIGH and
221 ADMIN_LOW.
222 LBUILD_VIEW_EXTERNAL
225 Promote an ADMIN_LOW label to the next high‐
227 est label, and demote an ADMIN_HIGH label to
228 the next lowest label.
229
233 The tsol_lbuild_get() function returns −1 if it is unable to get the
234 value.
235 The tsol_lbuild_create() function returns a variable of type ModLabel‐
238 Data that contains the information provided in the tsol_lbuild_create()
239 input parameter list, default values for information not provided, and
240 information on the widgets used by the label builder to create the user
241 interface.
242
244 Example 1 Create a Label Builder.
245 (ModLabelData *)lbldata = tsol_lbuild_create(widget0, callback_function,
247 LBUILD_MODE, LBUILD_MODE_SL,
248 LBUILD_TITLE, "Setting Sensitivity Label",
249 LBUILD_VIEW, LBUILD_VIEW_INTERNAL,
250 LBUILD_X, 200,
251 LBUILD_Y, 200,
252 LBUILD_USERFIELD, "Pathname:",
253 LBUILD_SHOW, FALSE,
254 NULL);
255 Example 2 Query the Mode and Display the Label Builder.
259 These examples call the tsol_lbuild_get() function to query the mode
262 being used, and call the tsol_lbuild_set() function so the label
263 builder dialog box displays.
264 mode = (int)tsol_lbuild_get(lbldata, LBUILD_MODE );
267 tsol_lbuild_set(lbldata, LBUILD_SHOW, TRUE, NULL);
269 Example 3 Destroy the ModLabelData Variable.
273 This example destroys the ModLabelData variable returned in the call to
276 tsol_lbuild_create().
277 tsol_lbuild_destroy(lbldata);
280
284 /usr/dt/include/Dt/ModLabel.h
285 Header file for label builder functions
287 /etc/security/tsol/label_encodings
290 The label encodings file contains the classification names, words,
292 constraints, and values for the defined labels of this system.
293
296 See attributes(5) for descriptions of the following attributes:
297 ┌─────────────────────────────┬─────────────────────────────┐
302 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
303 ├─────────────────────────────┼─────────────────────────────┤
304 │Interface Stability │Committed │
305 ├─────────────────────────────┼─────────────────────────────┤
306 │MT-Level │MT-Safe │
307 └─────────────────────────────┴─────────────────────────────┘
308
310 libtsol(3LIB), label_encodings(4), attributes(5)
311 Label Builder APIs in Solaris Trusted Extensions Developer's Guide
314
316 The functionality described on this manual page is available only if
317 the system is configured with Trusted Extensions.
318SunOS 5.11 20 Jul 2007 labelbuilder(3TSOL)