1 02/05/82  convert_authorization_
  2 
  3 The convert_authorization_ subroutine is provided to convert an
  4 authorization in the Multics access isolation mechanism (AIM) back and
  5 forth between its binary and character-string representations.
  6 Additional entries provide the ability to encode an authorization as a
  7 short character string for use in entrynames.
  8 
  9 
 10 Entry points in convert_authorization_:
 11    (List is generated by the help command)
 12 
 13 
 14 :Entry: decode:  01/27/82  convert_authorization_$decode
 15 
 16 
 17 Function:  This entry point takes the character string produced by the
 18 convert_authorization_$encode entry point and returns the original
 19 authorization or access class.  The null string is converted to the
 20 system_low authorization.
 21 
 22 
 23 Syntax:
 24 declare convert_authorization_$decode entry (bit(72) aligned, char(*));
 25 call convert_authorization_$decode (authorization, decoded_string);
 26 
 27 
 28 Arguments:
 29 authorization
 30    is the the decoded authorization.  (Output)
 31 decoded_string
 32    is a short string (maximum of 15 characters) that uniquely
 33    represents the input authorization/access class.  (Input)
 34 
 35 
 36 :Entry: encode:  01/27/82  convert_authorization_$encode
 37 
 38 
 39 Function:  This entry point encodes an authorization or access class
 40 into a short character string, suitable for inclusion in entrynames.
 41 If the input authorization represents system_low, the returned string
 42 is blank.
 43 
 44 
 45 Syntax:
 46 declare convert_authorization_$encode entry (bit(72) aligned, char(*));
 47 call convert_authorization_$encode (authorization, encoded_string);
 48 
 49 
 50 Arguments:
 51 authorization
 52    is the input authorization.  (Input)
 53 encoded_string
 54    is a short string (maximum of 15 characters) that uniquely
 55    represents the input authorization/access class.  (Output)
 56 
 57 
 58 :Entry: from_string:  01/27/82  convert_authorization_$from_string
 59 
 60 
 61 Function:  This entry point converts a character string to an encoded
 62 binary form suitable for storage in system tables and as input to the
 63 various modules that accept the binary form.
 64 
 65 
 66 Syntax:
 67 declare convert_authorization_$from_string entry (bit(72) aligned,
 68      char(*), fixed bin(35));
 69 call convert_authorization_$from_string (authorization, string, code);
 70 
 71 
 72 Arguments:
 73 authorization
 74    is the binary representation of string.  (Output)
 75 string
 76    is the character string to be converted (see "Notes" below).
 77    (Input)
 78 code
 79    is a standard status code.  (Output) It may be one of the following:
 80    error_table_$ai_invalid_string
 81         one or more namei is misspelled (see "Notes" below).
 82    error_table_$ai_above_allowed_max
 83         no error in conversion; but the resulting authorization class
 84         is greater than the system_high authorization.
 85 
 86 
 87 Notes:  The string argument must be of the form--
 88           name1,name2,...,nameN
 89 where nameI represents the mnemonic for a sensitivity level or access
 90 category.  The print_auth_names command (described in the MPM Commands)
 91 may be used to obtain a list of acceptable mnenomics.  If the string
 92 argument is null or system_low, the resulting authorization is level 0
 93 and no categories.  If the string is system_high, the system
 94 access_ceiling is returned (the maximum authorization or access class
 95 allowed).
 96 
 97 
 98 :Entry:  from_string_range:  01/27/82  convert_authorization_$from_string_range
 99 
100 
101 Function:  This entry point converts a character string to the form of
102 a binary authorization range.
103 
104 
105 Syntax:
106 declare convert_authorization_$from_string_range entry (bit (72)
107      aligned dimension (2), char (*), fixed bin (35));
108 call convert_authorization_$from_string (authorization_range, string,
109      code);
110 
111 
112 Arguments:
113 authorization_range
114    is the binary representation of string.  (Output)
115 string
116    is the character string to be converted (see "Notes" below).
117    (Input)
118 code
119    is a standard status code.  (Output) It may be one of the following:
120    error_table_$ai_invalid_string
121         one or more nameI are misspelled (see "Notes" below).
122    error_table_$ai_above_allowed_max
123         no error in conversion; but the resulting authorization is
124         greater than the system_high authorization.
125    error_table_$ai_invalid_range
126         no error in conversion; but authorization_range (2) does not
127         represent an authorization greater than or equal to
128         authorization_range (1).
129 
130 
131 Notes:  The string must be one of the two forms--
132           name1,name2,...,nameN
133           name1a,name2a,...,nameNa:name1b,name2b,...nameNb
134 where nameI represents the mnemonic for a sensitivity level or access
135 category.  If the string is in the first form, both elements of
136 authorization_range will be set to equal values (similar to the
137 operation of convert_authorization_$from_string).  If string is in the
138 second form, authorization_range (1) will be returned as the binary
139 representation of the part of string left of the colon, and
140 authorization_range (2) will be returned as the binary representation
141 of the part of the string right of the colon.
142 
143 
144 :Entry: minimum:  01/27/82  convert_authorization_$minimum
145 
146 
147 Function:  This entry point accepts an array of authorizations or
148 access classes and a binary number indicating how many elements to
149 process from the array.  It returns an authorization/access class whose
150 category set is the intersection of all input category sets and whose
151 sensitivity level is the minimum of all input sensitivity levels.  The
152 returned value need not equal any of the input values.
153 
154 
155 Syntax:
156 declare convert_authorization_$minimum entry (dim(*) bit(72) aligned,
157      fixed bin, bit(72) aligned);
158 call convert_authorization_$minimum (auth_array, n_elements,
159      minimum_auth);
160 
161 
162 Arguments:
163 auth_array
164    are the input authorizations.  (Input)
165 n_elements
166    is the number of elements to be processed in the auth_array
167    argument.  (Input)
168 minimum_auth
169    is the result.  (Output)
170 
171 
172 :Entry: to_string:  01/27/82  convert_authorization_$to_string
173 
174 
175 Function:  This entry point accepts a binary form of an authorization
176 and returns it as a printable string.  This output string is suitable
177 for input to the convert_authorization_$from_string entry point.  Each
178 level/category name has a maximum length of 32 characters.
179 
180 
181 Syntax:
182 declare convert_authorization_$to_string entry (bit(72) aligned,
183      char(*), fixed bin(35));
184 call convert_authorization_$to_string (authorization, string, code);
185 
186 
187 Arguments:
188 authorization
189    is the binary representation of string.  (Input)
190 string
191    is the character string to be converted.  (Output)
192 code
193    is a standard status code.  (Output) It may be one of the following:
194    error_table_$smallarg
195         string is too short to hold the converted result (see "Notes"
196         below).
197    error table_$ai_invalid binary
198         either the level number or category set is invalid; the
199         resulting output is also invalid.
200 
201 
202 Notes:  When the error_table_$smallarg code is returned, as much of the
203 resulting conversion as fits in the output string is returned.
204 However, since the results are not complete, they should not be used as
205 input to the convert_authorization_$from_string entry point.
206 
207 
208 :Entry:  to_string_range:  01/27/82  convert_authorization_$to_string_range
209 
210 
211 Function:  This entry point accepts a binary authorization range pair
212 and returns it as a printable string.  This output string is suitable
213 for input to the convert_authorization_$from_string_range entry point.
214 Each level/category name has a maximum length of 32 characters.
215 
216 
217 Syntax:
218 declare convert_authorization_$to_string_range entry (bit (72) aligned
219      dimension (2), char (*), fixed bin (35));
220 call convert_authorization_$to_string_range (authorization_range,
221      string, code);
222 
223 
224 Arguments:
225 authorization_range
226    is the binary representation of an authorization range to be
227    converted.  (Input)
228 string
229    is the resultant character string.  (Output)
230 code
231    is a standard status code.  (Output) It may be one of the following:
232    error_table_$smallarg
233         string is too short to hold the converted result.
234    error_table_$ai_invalid_binary
235         either the level number or category set is invalid; the
236         resulting output is also invalid.
237    error_table_$ai_invalid_range
238         no error in conversion; but authorization_range (2) does not
239         represent an authorization greater than or equal to
240         authorization_range (1).
241 
242 
243 Notes:  When the error_table_$smallarg code is returned, as much of the
244 resulting conversion as fits in the output string is returned.
245 However, since the results are not complete, they should not be used as
246 input to the convert_authorization_$from_string entry point.
247 
248 
249 :Entry:  to_string_range_short:  01/27/82  convert_authorization_$to_string_range_short
250 
251 
252 Function:  This entry point is identical to the
253 convert_authorization_$to_string_range entry point except that the
254 short level/category names are returned.  Each short name has a maximum
255 length of eight characters.  This output is also suitable for input to
256 the convert_authorization_$from_string_range entry point.
257 
258 
259 Syntax:
260 declare convert_authorization_$to_string_range_short entry bit (72)
261      aligned dimension (2), char(*), fixed bin(35);
262 call convert_authorization_$to_string_range_short (authorization_range,
263      string, code)
264 
265 
266 Arguments:
267 authorization_range
268    is the binary representation of an authorization range to be
269    converted.
270     (Input)
271 string
272    is the resultant character string.  (Output)
273 code
274    is a standard status code.  (Output) It may be one of the following:
275    error_table_$smallarg
276         string is too short to hold the converted result.
277    error_table_$ai_invalid_binary
278         either the level number or category set is invalid; the
279         resulting output is also invalid.
280    error_table_$ai_invalid_range
281         no error in conversion; but authorization_range (2) does not
282         represent an authorization greater than or equal to
283         authorization_range (1).
284 
285 
286 :Entry:  to_string_short:  01/27/82  convert_authorization_$to_string_short
287 
288 
289 Function:  This entry point is identical to the
290 convert_authorization_$to_string entry point, except that the short
291 level/category names are returned.  Each short name has a maximum
292 length of eight characters.  This output is also suitable for input to
293 the convert_authorization_$from_string entry point.
294 
295 
296 Syntax:
297 declare convert_authorization_$to_string_short entry (bit(72) aligned,
298      char(*), fixed bin(35));
299 call convert_authorization_$to_string_short (authorization, string,
300      code);
301 
302 
303 Arguments:
304 authorization
305    is the binary representation of string.  (Input)
306 string
307    is the character string to be converted.  (Output)
308 code
309    is a standard status code.  (Output) It may be one of the following:
310    error_table_$smallarg
311         string is too short to hold the converted result.
312    error_table_$ai_invalid_binary
313         either the level number or category set is invalid; the
314         resulting output is also invalid.
315    error_table_$ai_invalid_range
316         no error in conversion; but authorization_range (2) does not
317         represent an authorization greater than or equal to
318         authorization_range (1).