1labelbuilder(3TSOL)  Trusted Extensions Library Functions  labelbuilder(3TSOL)
2
3
4

NAME

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

SYNOPSIS

11       cc [flag...] file... -ltsol -lDtTsol [library...]
12
13
14       #include <Dt/ModLabel.h>
15
16       ModLabelData *tsol_lbuild_create(Widget widget,
17            void (*event_handler)() ok_callback,
18            lbuild_attributes extended_operation, ..., NULL);
19
20
21       void *tsol_lbuild_get(ModLabelData *data,
22            lbuild_attributes extended_operation);
23
24
25       void tsol_lbuild_set(ModLabelData *data,
26            lbuild_attributes extended_operation, ..., NULL);
27
28
29       void tsol_lbuild_destroy(ModLabelData *data);
30
31

DESCRIPTION

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
39
40       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
44
45       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
50
51       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
56
57       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
66
67       The widget information is accessed directly by referencing the  follow‐
68       ing fields of the ModLabelData structure.
69
70       lbuild_dialog    The label builder dialog box.
71
72
73       ok               The OK pushbutton.
74
75
76       cancel           The Cancel pushbutton.
77
78
79       reset            The Reset pushbutton.
80
81
82       help             The Help pushbutton.
83
84
85
86       The tsol_lbuild_create() parameter list takes the following values:
87
88       widget         The  widget  from  which  the dialog box is created. Any
89                      Motif widget can be passed.
90
91
92       ok_callback    A callback function that implements the behavior of  the
93                      OK pushbutton on the dialog box.
94
95
96       ..., 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
100
101
102       tsol_lbuild_destroy()  destroys  the ModLabelData structure returned by
103       tsol_lbuild_create().
104
105
106       tsol_lbuild_get() and tsol_lbuild_set() access the  information  stored
107       in the ModLabelData structure returned by tsol_lbuild_create().
108
109
110       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
119       LBUILD_MODE           Create a user interface to  build  a  sensitivity
120                             label  or a clearance. Value is LBUILD_MODE_SL by
121                             default.
122
123                             LBUILD_MODE_SL     Build a sensitivity label.
124
125
126                             LBUILD_MODE_CLR    Build a clearance.
127
128
129
130       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
134
135       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
139
140       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
144
145       LBUILD_SHOW           Show or hide the label builder dialog box.  Value
146                             is FALSE by default.
147
148                             TRUE     Show the label builder dialog box.
149
150
151                             FALSE    Hide the label builder dialog box.
152
153
154
155       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
159
160       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
166
167       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
173
174       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
180
181       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
187
188       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
194
195       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
205
206       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
213
214       LBUILD_VIEW           Use the internal or  external  label  representa‐
215                             tion. Value is LBUILD_VIEW_EXTERNAL by default.
216
217                             LBUILD_VIEW_INTERNAL
218
219                                 Use  the  internal  names for the highest and
220                                 lowest labels in the system:  ADMIN_HIGH  and
221                                 ADMIN_LOW.
222
223
224                             LBUILD_VIEW_EXTERNAL
225
226                                 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
230
231

RETURN VALUES

233       The  tsol_lbuild_get()  function  returns −1 if it is unable to get the
234       value.
235
236
237       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

EXAMPLES

244       Example 1 Create a Label Builder.
245
246         (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
256
257
258       Example 2 Query the Mode and Display the Label Builder.
259
260
261       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
265
266         mode = (int)tsol_lbuild_get(lbldata, LBUILD_MODE );
267
268         tsol_lbuild_set(lbldata, LBUILD_SHOW, TRUE, NULL);
269
270
271
272       Example 3 Destroy the ModLabelData Variable.
273
274
275       This example destroys the ModLabelData variable returned in the call to
276       tsol_lbuild_create().
277
278
279         tsol_lbuild_destroy(lbldata);
280
281
282

FILES

284       /usr/dt/include/Dt/ModLabel.h
285
286           Header file for label builder functions
287
288
289       /etc/security/tsol/label_encodings
290
291           The  label encodings file contains the classification names, words,
292           constraints, and values for the defined labels of this system.
293
294

ATTRIBUTES

296       See attributes(5) for descriptions of the following attributes:
297
298
299
300
301       ┌─────────────────────────────┬─────────────────────────────┐
302       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
303       ├─────────────────────────────┼─────────────────────────────┤
304       │Interface Stability          │Committed                    │
305       ├─────────────────────────────┼─────────────────────────────┤
306       │MT-Level                     │MT-Safe                      │
307       └─────────────────────────────┴─────────────────────────────┘
308

SEE ALSO

310       libtsol(3LIB), label_encodings(4), attributes(5)
311
312
313       Label Builder APIs in Solaris Trusted Extensions Developer's Guide
314

NOTES

316       The functionality described on this manual page is  available  only  if
317       the system is configured with Trusted Extensions.
318
319
320
321SunOS 5.11                        20 Jul 2007              labelbuilder(3TSOL)
Impressum